A:初版

src/Sharp/Log/docs/USAGE.md

@@ -0,0 +1,120 @@
+# 使用说明
+
+本指南说明如何在不同类型项目中以“最少代码”集成 Sharp.Log，并按需进行配置与扩展。
+
+## 1. 控制台/Worker 应用
+```csharp
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using Sharp.Log.Extensions;
+
+var host = Host.CreateDefaultBuilder(args)
+    .ConfigureLogging(b => b.AddSharpLog()) // 一行集成，默认 Console + 文件(JSON)
+    .Build();
+
+var logger = host.Services.GetRequiredService<ILogger<Program>>();
+logger.LogInformation("Hello from Sharp.Log");
+
+await host.RunAsync();
+```
+
+## 2. ASP.NET Core 应用
+```csharp
+using Sharp.Log.Extensions;
+using Sharp.Log.Middleware;
+
+var builder = WebApplication.CreateBuilder(args);
+builder.Logging.AddSharpLog(); // 一行集成
+
+var app = builder.Build();
+app.UseSharpRequestLogging(); // 可选：自动请求日志
+app.MapGet("/", () => Results.Ok("ok"));
+app.Run();
+```
+
+## 3. 可选配置（appsettings.json）
+添加 `SharpLog` 配置节（可省略）。
+```json
+{
+  "SharpLog": {
+    "MinLevel": "Information",
+    "Overrides": { "Microsoft": "Warning" },
+    "UseSerilog": true,
+    "UseConsole": true,
+    "ConsoleJson": false,
+    "File": {
+      "Enabled": true,
+      "Path": "logs/app-.log",
+      "Rolling": "Day",
+      "RetainedFileCountLimit": 30,
+      "Json": true
+    },
+    "Enrich": {
+      "Enabled": true,
+      "WithThreadId": true,
+      "WithProcessId": true,
+      "WithMachineName": true,
+      "WithEnvironmentName": true,
+      "WithActivityTrace": true
+    }
+  }
+}
+```
+
+环境变量覆盖示例：
+- `SHARPLOG__MINLEVEL=Warning`
+- `SHARPLOG__FILE__PATH=/var/logs/app-.log`
+- `SHARPLOG__FILE__RETAINEDFILECOUNTLIMIT=7`
+
+## 4. 常见定制
+- 仅文件输出（关闭 Console）：
+  ```csharp
+  builder.Logging.AddSharpLog(o => { o.UseConsole = false; });
+  ```
+- 只文本不 JSON（文件）：
+  ```csharp
+  builder.Logging.AddSharpLog(o => { o.File.Json = false; });
+  ```
+- 提升最小级别到 Warning：
+  ```csharp
+  builder.Logging.AddSharpLog(o => { o.MinLevel = LogLevel.Warning; });
+  ```
+- 指定应用名（默认读取入口程序集名）：
+  ```csharp
+  builder.Logging.AddSharpLog(o => { o.Enrich.Application = "MyApp"; });
+  ```
+
+## 5. 与现有 Provider 协作
+- 默认不清空 Provider；若希望仅用 Sharp.Log，可在应用中先执行 `ClearProviders()` 再调用 `AddSharpLog()`。
+- 如将 `UseSerilog` 设为 `false`，不会注入 Serilog Provider，请保留框架自带 Console Provider（不要 `ClearProviders()`）。
+
+## 6. 请求日志中间件
+启用后会记录：请求开始、结束（状态码与耗时）、异常。
+```csharp
+app.UseSharpRequestLogging();
+```
+
+## 7. 结构化与上下文
+日志条目自动包含：
+- `Application`、`Environment`、`MachineName`、`ProcessId`、`ThreadId`
+- `TraceId`、`SpanId`（来自 `Activity.Current`）
+
+你可使用 `BeginScope` 传入业务上下文：
+```csharp
+using var scope = logger.BeginScope(new Dictionary<string, object>{ ["UserId"] = userId });
+logger.LogInformation("User {UserId} logged in", userId);
+```
+
+## 8. 测试建议
+- 在测试中为文件输出设置临时目录：
+  ```csharp
+  builder.Logging.AddSharpLog(o =>
+  {
+      o.UseConsole = false;
+      o.File.Path = Path.Combine(tempDir, "app-.log");
+      o.File.Json = false;
+  });
+  ```
+
+如需更多示例，请参考本仓库的测试项目 `test/Log.Test`。
+