# EasyElasticLogger.NETFramework

**Repository Path**: lovelydouble/easy-elastic-logger-.netframework

## Basic Information

- **Project Name**: EasyElasticLogger.NETFramework
- **Description**: 一个轻量级、灵活、强大的 Elasticsearch 日志记录组件，专为 .NET Framework 应用程序设计，支持多环境、多配置方式和集群部署。
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-11
- **Last Updated**: 2026-01-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EasyElasticLogger.NETFramework

> 🚀🚀🚀 一个简单易用的Elasticsearch日志记录器，专为.NET Framework应用程序设计

<div align="center">

**简单易用 | 功能丰富 | 生产就绪**

</div>

## ✨✨ 功能特性

| 特性类别 | 功能描述 |
|----------|----------|
| ✅ **配置灵活** | 支持多种配置方式：直接传参、JSON文件、.config文件 |
| ✅ **索引策略** | 多种索引策略：固定索引、按日期滚动索引，符合ELK最佳实践|
| ✅ **集群支持** | 支持单节点和集群模式，完善的连接管理 |
| ✅ **日志级别** | 丰富的日志级别：Debug, Info, Warn, Error, Fatal |
| ✅ **容错机制** | 完善的容错机制和错误处理，确保日志不丢失 |
| ✅ **性能优化** | 灵活的API设计，支持同步和异步日志记录 |
| ✅ **多环境支持** | 支持多环境配置（开发、测试、生产环境） |
| ✅ **兼容性强** | 兼容AutoCAD二次开发，支持自定义配置文件路径 |
| ✅ **使用简单** | 采用静态类设计，使用简单直观 |

---

## 🎯🎯 适用场景

> **📢📢 重要说明：本插件仅适用于 .NET Framework 4.7.2 和 4.8 版本的应用程序，Elasticsearch 版本兼容 Elasticsearch 7.x**

### 📊📊 需要将日志集中到 ELK 进行统一分析的系统
- 需要实时日志监控和告警的系统
- 希望利用 Kibana 进行日志可视化和分析的场景

### 🖥️🖥️ 基于 .NET Framework 4.7.2/4.8 的应用程序
- **WinForm** 桌面应用程序（.NET Framework 4.7.2/4.8）
- **WPF** 桌面应用程序（.NET Framework 4.7.2/4.8）
- **WebForm** 传统 Web 应用程序（.NET Framework 4.7.2/4.8）
- **Windows服务** 和后台任务程序（.NET Framework 4.7.2/4.8）
- **控制台应用程序** 的日志记录需求（.NET Framework 4.7.2/4.8）

### 🔧🔧 特殊开发环境中的诊断与运维日志需求
- **AutoCAD** 二次开发插件的日志记录（基于.NET Framework）
- **Revit** 等BIM软件的插件开发（基于.NET Framework）
- 工业软件插件的诊断和运维监控
- 需要自定义配置文件路径的特殊环境部署

### ❌❌ 不支持的场景
- .NET Core / .NET 5/6/7/8 应用程序
- .NET Standard 类库项目
- .NET Framework 4.7.2 以下版本
- 跨平台应用程序（Linux/macOS）

---

## 📦📦 安装

通过NuGet包管理器安装：

```powershell
Install-Package EasyElasticLogger.NETFramework
```xml

或者通过.NET CLI安装：

```bash
dotnet add package EasyElasticLogger.NETFramework
```xml

---

## 🚀🚀🚀 快速开始

### 1. 基本使用

```csharp
using EasyElasticLogger.NETFramework.ES.Logging;

// 在应用程序启动时初始化（如Program.cs或Startup.cs中）
ElasticLogger.Initialize("Production");

// 在任何需要记录日志的地方直接使用静态方法
// 同步记录日志
ElasticLogger.Info("这是一条信息日志");
ElasticLogger.Warn("这是一条警告日志");
ElasticLogger.Error("这是一条错误日志", new Exception("测试异常"));

// 异步记录日志
await ElasticLogger.InfoAsync("这是一条异步信息日志");
await ElasticLogger.ErrorAsync("这是一条异步错误日志", new Exception("测试异常"));
```xml

### 2. 环境配置

#### 使用环境变量

```csharp
// 设置环境变量
Environment.SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Development");

// 或者设置 ENVIRONMENT 环境变量
Environment.SetEnvironmentVariable("ENVIRONMENT", "Test");

// 使用环境特定的配置初始化
ElasticLogger.Initialize();
```xml

#### 使用初始化方法指定环境

```csharp
// 直接指定环境
ElasticLogger.Initialize("Production");
```xml

---

## ⚙⚙⚙️ 配置方式

配置加载优先级：**直接传参 > JSON配置 > .config配置**

### 1. 📝📝 直接传参配置

```csharp
var config = new LoggerConfiguration
{
    Enabled = true,
    IndexPrefix = "myapp-log",
    IndexStrategy = IndexStrategy.DailyRolling,
    ApplicationName = "MyApplication",
    BatchSize = 100,
    TimeoutMs = 10000,
    Cluster = new ClusterConfigurationElement
    {
        Nodes = new List<string> { "http://localhost:9200" },
        Username = "elastic",
        Password = "password",
        UseSsl = false,
        SkipSslVerification = false,
        ConnectionTimeoutMs = 5000,
        MaxRetries = 2
    }
};

ElasticLogger.Initialize(config);
```xml

### 2. 📄📄 JSON配置文件（支持环境特定配置）

```csharp
// 会自动查找 logger-config.Production.json 或 logger-config.json
ElasticLogger.InitializeFromJson("logger-config.json", "Production");
```xml

#### JSON配置文件示例

**默认配置 (logger-config.json)**
```json
{
  "Enabled": true,
  "IndexPrefix": "myapp-log",
  "IndexStrategy": "DailyRolling",
  "ApplicationName": "MyApplication",
  "BatchSize": 100,
  "TimeoutMs": 10000,
  "Cluster": {
    "Nodes": ["http://localhost:9200"],
    "Username": "elastic",
    "Password": "password",
    "UseSsl": false,
    "SkipSslVerification": false,
    "ConnectionTimeoutMs": 5000,
    "MaxRetries": 2
  }
}
```xml

**生产环境配置 (logger-config.Production.json)**
```json
{
  "Enabled": true,
  "IndexPrefix": "myapp-log-prod",
  "IndexStrategy": "DailyRolling",
  "ApplicationName": "MyProductionApp",
  "BatchSize": 100,
  "TimeoutMs": 10000,
  "Cluster": {
    "Nodes": ["http://prod-es1:9200", "http://prod-es2:9200", "http://prod-es3:9200"],
    "Username": "elastic",
    "Password": "prod_password",
    "UseSsl": true,
    "SkipSslVerification": false,
    "ConnectionTimeoutMs": 10000,
    "MaxRetries": 3
  }
}
```xml

**使用示例**
```csharp
// 使用默认JSON配置文件
ElasticLogger.InitializeFromJson("logger-config.json");

// 使用指定环境的JSON配置文件
ElasticLogger.InitializeFromJson("logger-config.json", "Production");
```xml

### 3. ⚙⚙⚙️ .config配置文件（支持环境特定配置）

```xml
<configuration>
  <appSettings>
    <add key="Environment" value="Development" />
  </appSettings>
  
  <configSections>
    <!-- 默认配置 -->
    <section name="elasticLogger" type="EasyElasticLogger.NETFramework.ES.Configuration.LoggerConfiguration, EasyElasticLogger.NETFramework" />
    
    <!-- 环境特定配置 -->
    <section name="elasticLogger.Development" type="EasyElasticLogger.NETFramework.ES.Configuration.LoggerConfiguration, EasyElasticLogger.NETFramework" />
    <section name="elasticLogger.Test" type="EasyElasticLogger.NETFramework.ES.Configuration.LoggerConfiguration, EasyElasticLogger.NETFramework" />
    <section name="elasticLogger.Production" type="EasyElasticLogger.NETFramework.ES.Configuration.LoggerConfiguration, EasyElasticLogger.NETFramework" />
  </configSections>

  <!-- 默认配置 -->
  <elasticLogger enabled="true" indexPrefix="app-log" applicationName="MyApplication" batchSize="100" timeoutMs="10000" indexStrategy="DailyRolling">
    <cluster nodes="http://localhost:9200" username="" password="" useSsl="false" skipSslVerification="false" connectionTimeoutMs="5000" maxRetries="2" />
  </elasticLogger>

  <!-- 开发环境配置 -->
  <elasticLogger.Development enabled="true" indexPrefix="dev-app-log" applicationName="MyApplication-Dev" batchSize="50" timeoutMs="15000" indexStrategy="DailyRolling">
    <cluster nodes="http://localhost:9200" username="elastic" password="changeme" useSsl="false" skipSslVerification="true" connectionTimeoutMs="10000" maxRetries="3" />
  </elasticLogger.Development>

  <!-- 生产环境配置 -->
  <elasticLogger.Production enabled="true" indexPrefix="prod-app-log" applicationName="MyApplication-Prod" batchSize="200" timeoutMs="30000" indexStrategy="DailyRolling" fixedIndexName="my-fixed-index">
    <cluster nodes="https://es1.prod.com,https://es2.prod.com,https://es3.prod.com" username="prod-user" password="prod-password" useSsl="true" skipSslVerification="false" connectionTimeoutMs="15000" maxRetries="5" />
  </elasticLogger.Production>
</configuration>
```xml

### 4. 🖥🖥🖥️ 自定义配置文件路径（兼容AutoCAD二次开发）

```csharp
// 使用自定义配置文件路径和环境初始化
ElasticLogger.Initialize(@"C:\\MyApp\\config\\myapp.config", "Production");
```

---

## 📋📋 日志记录示例

### 同步日志记录

``csharp
// Debug级别日志
ElasticLogger.Debug("调试信息", "MyClass.Method");

// Info级别日志
ElasticLogger.Info("一般信息", "MyClass.Method");

// Warn级别日志
ElasticLogger.Warn("警告信息", "MyClass.Method");

// Error级别日志
ElasticLogger.Error("错误信息", new Exception("异常详情"), "MyClass.Method");

// Fatal级别日志
ElasticLogger.Fatal("严重错误", new Exception("异常详情"), "MyClass.Method");

// 带附加数据的日志
var userData = new { UserId = 123, UserName = "张三" };
ElasticLogger.Info("用户登录", "UserService.Login", userData);
```

### 异步日志记录

``csharp
// 异步记录不同级别的日志
await ElasticLogger.DebugAsync("调试信息", "MyClass.Method");
await ElasticLogger.InfoAsync("一般信息", "MyClass.Method");
await ElasticLogger.WarnAsync("警告信息", "MyClass.Method");
await ElasticLogger.ErrorAsync("错误信息", new Exception("异常详情"), "MyClass.Method");
await ElasticLogger.FatalAsync("严重错误", new Exception("异常详情"), "MyClass.Method");
```

---

## 🔧🔧 配置参数详解

### Logger配置项

| 属性 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `Enabled` | `bool` | `true` | 是否启用日志记录功能 |
| `IndexPrefix` | `string` | `"app-log"` | 索引前缀 |
| `IndexStrategy` | `IndexStrategy` | `DailyRolling` | 索引策略（Fixed/DailyRolling） |
| `FixedIndexName` | `string` | `null` | 固定索引名称（仅在IndexStrategy为Fixed时使用） |
| `ApplicationName` | `string` | `"DefaultApp"` | 应用程序名称 |
| `BatchSize` | `int` | `100` | 批量发送日志的大小 |
| `TimeoutMs` | `int` | `10000` | 发送超时时间（毫秒） |

### Cluster配置项

| 属性 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `Nodes` | `List<string>` | `empty` | Elasticsearch节点地址列表 |
| `Username` | `string` | `null` | 用户名（用于Basic认证） |
| `Password` | `string` | `null` | 密码（用于Basic认证） |
| `UseSsl` | `bool` | `false` | 是否启用SSL |
| `SkipSslVerification` | `bool` | `false` | 是否跳过SSL证书验证 |
| `ConnectionTimeoutMs` | `int` | `5000` | 连接超时时间（毫秒） |
| `MaxRetries` | `int` | `2` | 最大重试次数 |

### 📊📊 IndexStrategy索引策略

| 策略 | 描述 |
|------|------|
| **Fixed** | 固定索引，所有日志都写入同一个索引 |
| **DailyRolling** | 按日期滚动索引，每天生成一个新的索引（默认） |

---

## 🔄🔄 环境配置支持

### 支持的环境

- 🛠🛠🛠️ **Development** - 开发环境
- 🧪🧪🧪 **Test** - 测试环境  
- 🏭🏭🏭 **Production** - 生产环境

### 环境识别优先级

1. 🥇🥇🥇 环境变量 `ASPNETCORE_ENVIRONMENT`
2. 🥈🥈🥈 环境变量 `ENVIRONMENT`
3. 🥉🥉🥉 AppSettings中的 `Environment` 配置项

---

## 📄📄 许可证

本项目采用 **MIT许可证** - 查看 LICENSE 文件了解详情。

---

<div align="center">

**让日志记录变得简单而强大** ✨✨

</div>