sharp-basic/src/Sharp/Log

Sharp.Log

面向“快速集成”的日志整合层：基于 Microsoft.Extensions.Logging 抽象，内置 Serilog 预设，实现一行接入，默认即用（Console + 按日滚动文件，结构化 JSON，丰富上下文）。

• 目标：不重造日志框架，仅做预设与桥接，减少样板代码
• 适用：控制台应用、Worker、ASP.NET Core（含中间件）

特性

• 一行集成：builder.Logging.AddSharpLog()，无配置也可用
• 输出：Console（可彩色）、文件（按日滚动、保留数量、异步写）
• 结构化：文本模板/JSON；支持模板+参数与异常详情
• 上下文丰富：Application/Environment/Machine/Process/Thread/TraceId/SpanId
• 过滤：全局最小级别与按分类覆盖
• ASP.NET：UseSharpRequestLogging() 统一请求日志（开始/结束/异常）
• 配置驱动：支持 appsettings.json:SharpLog 与环境变量绑定

快速开始

1. 引用项目（或 NuGet 包）
2. 在应用入口添加一行：

// 控制台/Worker 通用
var host = Host.CreateDefaultBuilder(args)
    .ConfigureLogging(b => b.AddSharpLog())
    .Build();

// ASP.NET Core
var builder = WebApplication.CreateBuilder(args);
builder.Logging.AddSharpLog(); // 一行集成
var app = builder.Build();
app.UseSharpRequestLogging(); // 可选：请求日志
app.Run();

// WPF/WinForms/任意桌面

using Sharp.Log;
using Microsoft.Extensions.Configuration;

var configuration = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json", optional: true)
    .AddEnvironmentVariables()
    .Build();

using var loggerFactory = SharpLogDefaults.CreateLoggerFactory(configuration);
var logger = loggerFactory.CreateLogger<App>();
logger.LogInformation("桌面程序已启动");

无需任何 appsettings.json，即可获得：

• Console 文本输出
• 文件 JSON 输出：logs/app-.log（按天滚动，保留 30 个文件，异步写）
• 丰富上下文属性

可选配置（appsettings.json）

{
  "SharpLog": {
    "UseSerilog": true,
    "UseConsole": true,
    "ConsoleJson": false,
    "MinLevel": "Information",
    "Overrides": {
      "Microsoft": "Warning",
      "System": "Warning"
    },
    "File": {
      "Enabled": true,
      "Path": "logs/app-.log",
      "Rolling": "Day",
      "RetainedFileCountLimit": 30,
      "FileSizeLimitBytes": null,
      "Buffered": true,
      "Shared": false,
      "Json": true
    },
    "Enrich": {
      "Enabled": true,
      "WithThreadId": true,
      "WithProcessId": true,
      "WithMachineName": true,
      "WithEnvironmentName": true,
      "Application": null,
      "WithActivityTrace": true
    }
  }
}

环境变量示例：

• SHARPLOG__MINLEVEL=Warning
• SHARPLOG__FILE__RETAINEDFILECOUNTLIMIT=7

API 概览

• ILoggingBuilder AddSharpLog(Action<SharpLogOptions>? configure = null)
• IApplicationBuilder UseSharpRequestLogging()
• 选项：SharpLogOptions、FileOptions、EnrichOptions、RollingInterval

常见问题

• 需要清空默认 Provider 吗？
  • 如需仅使用 Sharp.Log，请在调用方执行 builder.Logging.ClearProviders()，然后 AddSharpLog()。
• 一定要 Serilog 吗？
  • 默认启用（文件/JSON/丰富器等依赖）。如不想使用，可在配置中设置 UseSerilog=false，保留框架自带 Console（建议不要 ClearProviders()）。
• 与分布式追踪兼容吗？
  • 兼容。自动注入 Activity.TraceId/SpanId；若使用 OpenTelemetry，日志会带 Trace 关联信息。

目录

• Options/ 选项模型
• Internal/ Serilog 配置与 Enricher
• Extensions/ 集成扩展
• Middleware/ 请求日志中间件

日志要简单可靠：一行接入，默认即用，可配更强。