DMS/软件设计文档/07-日志服务使用说明.md

# DMS日志服务使用说明

## 概述

DMS项目现在支持Microsoft.Extensions.Logging.ILogger接口的日志服务：
1. NLogLogger类直接实现Microsoft.Extensions.Logging.ILogger接口（位于DMS.WPF项目中）
2. 提供ILoggerFactory用于创建命名的Logger实例（位于DMS.WPF项目中）

## 如何注册日志服务

在`Startup.cs`或程序的依赖注入配置中，使用以下扩展方法注册日志服务：

```csharp
using DMS.Application;

// 在ConfigureServices方法中
services.AddDmsServices();
```

这将注册以下服务：
- `Microsoft.Extensions.Logging.ILogger` 接口及其实现 `NLogLogger`（单例，位于DMS.WPF.Logging命名空间）
- `Microsoft.Extensions.Logging.ILoggerFactory` 接口及其实现 `NLogLoggerFactory`（单例，位于DMS.WPF.Logging命名空间）

## 如何使用日志服务

### 1. 使用构造函数注入ILogger（推荐）

```csharp
using Microsoft.Extensions.Logging;

public class MyService
{
    private readonly ILogger<MyService> _logger;

    public MyService(ILogger<MyService> logger)
    {
        _logger = logger;
    }

    public void DoSomething()
    {
        _logger.LogInformation("正在执行操作...");
        
        try
        {
            // 业务逻辑
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "操作失败");
        }
    }
}
```

### 2. 使用ILoggerFactory创建命名的Logger

```csharp
using Microsoft.Extensions.Logging;

public class MyService
{
    private readonly ILogger _logger;

    public MyService(ILoggerFactory loggerFactory)
    {
        _logger = loggerFactory.CreateLogger("MyService");
    }

    public void DoSomething()
    {
        _logger.LogInformation("正在执行操作...");
        
        try
        {
            // 业务逻辑
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "操作失败");
        }
    }
}
```

## NLogLoggerFactory的作用

`NLogLoggerFactory`是`ILoggerFactory`接口的实现，主要作用是：

1. **创建命名的Logger实例**：通过`CreateLogger(string categoryName)`方法，可以为不同的类或模块创建具有特定名称的Logger实例
2. **支持依赖注入**：作为服务注册后，其他类可以通过构造函数注入`ILoggerFactory`来创建Logger实例
3. **符合标准**：实现Microsoft.Extensions.Logging标准，确保与其他.NET日志组件兼容

## 日志级别映射

Microsoft.Extensions.Logging与NLog之间的日志级别映射如下：

| Microsoft.Extensions.Logging | NLog     |
|-----------------------------|----------|
| Trace                       | Trace    |
| Debug                       | Debug    |
| Information                 | Info     |
| Warning                     | Warn     |
| Error                       | Error    |
| Critical                    | Fatal    |

## 节流功能

NLogLogger提供了节流功能，以防止在短时间内产生大量重复的日志（日志风暴）。默认情况下，所有日志都会启用节流，节流时间窗口为30秒。

## 配置

NLog的配置文件位于 `DMS.Core\Configurations\nlog.config`，可以根据需要进行修改。