DuMes.Component.Serilog 6.0.1

DuMes.Component.Serilog

多脉日志组件：接入 Microsoft.Extensions.Logging.ILogger 管道，按环境与级别分流到 Debug 窗口 / 彩色控制台 / 文件。

项目结构

DuMes.Component.Serilog/
├── Constants/              # LogProperties、LogWriteTarget
├── DependencyInjection/    # UseComponentSerilog / AddComponentSerilog
├── Logging/                # WriteInformation / WriteWarning / WriteError
├── Options/                # SerilogComponentOptions
└── Internal/
    ├── Configuration/      # Serilog 管道构建
    ├── Enrichers/          # 文件路由
    ├── Writing/            # 持久化公共逻辑
    └── Utilities/          # 路径清洗

功能概览

输出路由

LogInformation / LogWarning / LogError 不落盘；只有 Write* 且指定了 fileName 才会写文件。

文件路径规则

BaseDirectory 即 AppContext.BaseDirectory（一般为 bin/Debug/net10.0/），与进程当前工作目录无关。

有业务目录时，该目录下按 MaxFilesPerFolder / FileSizeLimitBytes 滚动保留。

输出格式

控制台与文件使用同一模板：

[{Timestamp:yyyy-MM-dd HH:mm:ss.ffff} {Level:u3}] {Message:lj}
{Exception}

示例：[2026-08-06 00:27:35.6166 INF] 正在加载 …

控制台使用 AnsiConsoleTheme.Code：仅 级别 与消息中的 属性值 着色，正文保持默认色；文件为纯文本（无 ANSI）。

引用

项目引用或 NuGet 引用本组件即可。ILogger 由 Serilog.AspNetCore 传递引入，不必再单独安装 Microsoft.Extensions.Logging。

using DuMes.Component.Serilog;           // Write*、UseComponentSerilog、LogWriteTarget
using Microsoft.Extensions.Logging;      // ILogger<T>、LogInformation 等

接入

WebAPI

Program.cs 配置 Host 管道（内部会注册进 DI）；调用返回后即可使用静态 Log，业务类也可注入 ILogger<T>。不要再调 AddComponentSerilog。

using Serilog;

var builder = WebApplication.CreateBuilder(args);
// 须在读取 SerilogComponent 配置之后调用；注册完成后立刻可用 Log.*
builder.Host.UseComponentSerilog(builder.Configuration, builder.Environment);
Log.Information("Serilog 已就绪");

builder.Services.AddControllers();
var app = builder.Build();
app.MapControllers();
try
{
    app.Run();
}
finally
{
    await Log.CloseAndFlushAsync();
}

public class OrderController(ILogger<OrderController> logger) : ControllerBase
{
    [HttpGet]
    public IActionResult Get()
    {
        logger.WriteInformation("api", "处理请求");              // logs/api.log
        logger.WriteInformation("biz", "处理订单", "order");     // logs/order/bizyyyyMMddHH.log
        return Ok();
    }
}

控制台 + Generic Host

using Serilog;

var builder = Host.CreateApplicationBuilder(args);
builder.UseComponentSerilog(); // 注册后即可 Log.*
Log.Information("Serilog 已就绪");
var host = builder.Build();
await host.RunAsync();

控制台仅 DI（无 Host）

configuration 可省略（用代码默认值）。结束前建议 Log.CloseAndFlush()。

using Serilog;

services.AddComponentSerilog();
services.AddComponentSerilog(configuration);
services.AddComponentSerilog(o => o.MaxFilesPerFolder = 50);

// ...
Log.CloseAndFlush();

环境由 ASPNETCORE_ENVIRONMENT / DOTNET_ENVIRONMENT 判断（Development 即开发模式）。

记录日志

// 不落盘（管道默认行为）
logger.LogDebug("仅 Debug 窗口");
logger.LogInformation("仅控制台（Development）");
logger.LogWarning("警告（不落盘）");
logger.LogError(ex, "错误（不落盘）");

// 落盘：Write*（directory / target 可选，默认 File）
logger.WriteInformation("start", "写入 logs/start.log");
logger.WriteInformation("biz", "写入日志", "order");
logger.WriteInformation("biz", "写入文件", "order", LogWriteTarget.File);
// logger.WriteInformation("biz", "写入库", "order", LogWriteTarget.Database); // 尚未实现

logger.WriteWarning("start", "警告");
logger.WriteWarning("biz", "警告", "order");

logger.WriteError("start", "错误");
logger.WriteError(ex, "start", "带异常的错误");
logger.WriteError(ex, "biz", "带异常的错误", "order", LogWriteTarget.File);

清空固定名日志

仅作用于 logs 根目录下固定名称文件，不影响业务目录滚动文件：

LogFile.ClearFixedName("start");  // 清空 logs/start.log
LogFile.ClearFixedName("error");  // 清空 logs/error.log

配置（可选）

均可省略，代码内已有默认值；需要覆盖时在 appsettings.json 增加：

{
  "SerilogComponent": {
    "EnableConsole": true,
    "MaxFilesPerFolder": 100,
    "FileSizeLimitBytes": 10485760
  }
}

也可用代码覆盖：

builder.Host.UseComponentSerilog(builder.Configuration, builder.Environment, o =>
{
    o.EnableConsole = false; // 无黑窗口 / 服务场景
    o.MaxFilesPerFolder = 50;
});

说明

1. WebAPI 为何是 Host.UseComponentSerilog(configuration, environment)： 官方 Serilog 接法是配置 Host 日志管道；本组件在注册时创建并赋值 Log.Logger，再 UseSerilog(logger) 接入 DI，故 Build() 前即可 Log.Information，与注入的 ILogger<T> 同一实例。
2. 为何不叫 LogInformation(fileName, …)： 会与 MEL 实例方法重载冲突，扩展无法被调用，故使用 Write*。
3. LogWriteTarget.Database： 枚举已预留，调用会抛出 NotSupportedException，后续扩展写入库。
4. 静态 Log： 与 ILogger 共用同一 Logger 实例；结束时请 Log.CloseAndFlush() / CloseAndFlushAsync()。

示例工程

# 控制台
cd TestSerilog && dotnet run

# WebAPI（默认 http://localhost:5090）
cd TestSerilogWebApi && dotnet run
curl http://127.0.0.1:5090/test/logs

# 发布后运行（publish 目录不含 launchSettings，需自行指定端口/环境）
dotnet publish TestSerilogWebApi -c Release -o ./publish
cd publish
ASPNETCORE_URLS=http://localhost:5090 dotnet TestSerilogWebApi.dll
curl http://127.0.0.1:5090/test/logs

直接 dotnet xxx.dll 时默认 Production；控制台为 Information+。launchSettings.json 不会打进发布包，需自行指定 --urls / ASPNETCORE_URLS。