Serilog.AspNetCore 8.0.2

Serilog.AspNetCore

针对 ASP.NET Core 的 Serilog 日志记录。本包通过 Serilog 路由 ASP.NET Core 日志消息，因此您可以将有关 ASP.NET 内部操作的信息写入与您的应用程序事件相同的 Serilog 终端。

安装并配置了 Serilog.AspNetCore 之后，您可以直接通过 Serilog 或由 ASP.NET 注入的任何 ILogger 接口写入日志消息。所有记录器都将使用相同的底层实现、级别和目标。

版本控制：本包跟踪其依赖的 Microsoft.Extensions.Hosting 的版本和目标框架支持。大多数用户应选择与其应用程序的目标框架匹配的 Serilog.AspNetCore 版本。例如，如果您针对 .NET 7.x，请选择 7.x 版本的 Serilog.AspNetCore。如果您针对 .NET 8.x，请选择 8.x 版本的 Serilog.AspNetCore，依此类推。

说明

首先，将 Serilog.AspNetCore 的 NuGet 包 安装到您的应用程序中。

dotnet add package Serilog.AspNetCore

接下来，在您的应用程序的 Program.cs 文件中，首先配置 Serilog。一个 try/catch 块将确保任何配置问题都得到适当的记录。

using Serilog;

Log.Logger = new LoggerConfiguration()
    .WriteTo.Console()
    .CreateLogger();

try
{
    Log.Information("Starting web application");

    var builder = WebApplication.CreateBuilder(args);
    builder.Services.AddSerilog(); // <-- Add this line
    
    var app = builder.Build();
    app.MapGet("/", () => "Hello World!");

    app.Run();
}
catch (Exception ex)
{
    Log.Fatal(ex, "Application terminated unexpectedly");
}
finally
{
    Log.CloseAndFlush();
}

builder.Services.AddSerilog() 调用将为所有日志事件重定向到您的 Serilog 管道。

最后，通过清理对默认记录器的剩余配置来完成，包括从 appsettings.*.json 文件中删除 "Logging" 部分（如果需要，可以替换为 Serilog 配置，如 Sample 项目 中所示）。

就是这样！稍微提高日志级别，您将看到类似于以下内容的日志输出

[12:01:43 INF] Starting web application
[12:01:44 INF] Now listening on: http://localhost:5000
[12:01:44 INF] Application started. Press Ctrl+C to shut down.
[12:01:44 INF] Hosting environment: Development
[12:01:44 INF] Content root path: serilog-aspnetcore/samples/Sample
[12:01:47 WRN] Failed to determine the https port for redirect.
[12:01:47 INF] Hello, world!
[12:01:47 INF] HTTP GET / responded 200 in 95.0581 ms

提示：在 IIS 下运行时，要在 Visual Studio 的输出窗口中看到 Serilog 输出，请从 显示输出自 下拉列表中选择 ASP.NET Core Web Server，或者在记录器配置中将 WriteTo.Console() 替换为 WriteTo.Debug()。

一个更完整的示例，包括 appsettings.json 配置，可以在 此处的示例项目 中找到。

请求数据记录

本包包括用于更智能 HTTP 请求记录的中间件。ASP.NET Core 实现的默认请求记录非常嘈杂，每次请求都发出多个事件。所包含的中间件将这些事件压缩成一个事件，该事件包含方法、路径、状态码和计时信息。

作为文本，其格式如下

[16:05:54 INF] HTTP GET / responded 200 in 227.3253 ms

或者作为 JSON

{
  "@t": "2019-06-26T06:05:54.6881162Z",
  "@mt": "HTTP {RequestMethod} {RequestPath} responded {StatusCode} in {Elapsed:0.0000} ms",
  "@r": ["224.5185"],
  "RequestMethod": "GET",
  "RequestPath": "/",
  "StatusCode": 200,
  "Elapsed": 224.5185,
  "RequestId": "0HLNPVG1HI42T:00000001",
  "CorrelationId": null,
  "ConnectionId": "0HLNPVG1HI42T"
}

要启用中间件，请首先修改您的记录器配置或 appsettings.json 文件中将嘈杂的 ASP.NET Core 日志源的最低级别更改为 Warning。

            .MinimumLevel.Override("Microsoft.AspNetCore.Hosting", LogEventLevel.Warning)
            .MinimumLevel.Override("Microsoft.AspNetCore.Mvc", LogEventLevel.Warning)
            .MinimumLevel.Override("Microsoft.AspNetCore.Routing", LogEventLevel.Warning)

提示：将 {SourceContext} 添加到控制台记录器的输出模板中，以查看记录器的名称；这有助于跟踪要抑制的嘈杂日志事件的来源。

然后，在您的应用程序的 Program.cs 中，使用 UseSerilogRequestLogging() 添加中间件

    var app = builder.Build();

    app.UseSerilogRequestLogging(); // <-- Add this line

    // Other app configuration

重要的是确保 UseSerilogRequestLogging() 调用出现在处理程序（如 MVC）之前。中间件不会对管道中出现在其之前的部分进行计时或记录。（可以利用此功能排除记录，例如 UseStaticFiles()，通过将 UseSerilogRequestLogging() 放在其之后。）

在请求处理过程中，可以使用 IDiagnosticContext.Set() 将附加属性附加到完成事件

    public class HomeController : Controller
    {
        readonly IDiagnosticContext _diagnosticContext;

        public HomeController(IDiagnosticContext diagnosticContext)
        {
            _diagnosticContext = diagnosticContext ??
                throw new ArgumentNullException(nameof(diagnosticContext));
        }

        public IActionResult Index()
        {
            // The request completion event will carry this property
            _diagnosticContext.Set("CatalogLoadTime", 1423);

            return View();
        }

这种模式的优势在于，它减少了每个 HTTP 请求需要构建、传输和存储的日志事件的数量。将多个属性添加到同一事件中也可以使请求细节和其他数据的协同更加容易。

默认情况下，将以下请求信息作为属性添加

• 请求方法
• 请求路径
• 状态码
• 持续时间

您可以使用UseSerilogRequestLogging()方法上的options回调来修改用于请求完成事件的模板，添加额外的属性或更改事件级别。

app.UseSerilogRequestLogging(options =>
{
    // Customize the message template
    options.MessageTemplate = "Handled {RequestPath}";
    
    // Emit debug-level events instead of the defaults
    options.GetLevel = (httpContext, elapsed, ex) => LogEventLevel.Debug;
    
    // Attach additional properties to the request completion event
    options.EnrichDiagnosticContext = (diagnosticContext, httpContext) =>
    {
        diagnosticContext.Set("RequestHost", httpContext.Request.Host.Value);
        diagnosticContext.Set("RequestScheme", httpContext.Request.Scheme);
    };
});

两阶段初始化

本页顶部示例展示了如何在应用程序启动时立即配置Serilog的方法。这样做的好处是可以捕获并报告在设置ASP.NET Core主机期间抛出的异常。

首先初始化Serilog的缺点是，此时ASP.NET Core主机的服务尚不可用，包括appsettings.json配置和依赖注入。

为了解决这个问题，Serilog支持两阶段初始化。当程序启动时立即配置一个初始的“引导”日志记录器，并在主机加载后替换为完全配置的日志记录器。

要使用这项技术，首先将初始的CreateLogger()调用替换为CreateBootstrapLogger()

using Serilog;
using Serilog.Events;

Log.Logger = new LoggerConfiguration()
    .MinimumLevel.Override("Microsoft", LogEventLevel.Information)
    .Enrich.FromLogContext()
    .WriteTo.Console()
    .CreateBootstrapLogger(); // <-- Change this line!

然后，将一个回调传递给AddSerilog()来创建最终的日志记录器

builder.Services.AddSerilog((services, lc) => lc
    .ReadFrom.Configuration(builder.Configuration)
    .ReadFrom.Services(services)
    .Enrich.FromLogContext()
    .WriteTo.Console());

需要注意的是，最终的日志记录器将**完全替换**引导日志记录器：如果您希望两者都记录到控制台，例如，您需要像示例中那样在两处都指定WriteTo.Console()。

消费appsettings.json配置

使用**两阶段初始化**，插入示例中所示的ReadFrom.Configuration(builder.Configuration)调用。JSON配置语法在Serilog.Settings.Configuration的README中有文档说明。

将服务注入到增强器和目的地

使用**两阶段初始化**，插入示例中所示的ReadFrom.Services(services)调用。ReadFrom.Services()调用将使用以下服务的任何已注册实现配置日志记录管道：

• IDestructuringPolicy
• ILogEventEnricher
• ILogEventFilter
• ILogEventSink
• LoggingLevelSwitch

JSON输出

Console()、Debug()和File()目的地都原生支持通过包含的Serilog.Formatting.Compact包的JSON格式输出。

要写入换行符分隔的JSON，请将CompactJsonFormatter或RenderedCompactJsonFormatter传递到目的地配置方法。

    .WriteTo.Console(new RenderedCompactJsonFormatter())

写入Azure诊断日志流

Azure诊断日志流从D:\home\LogFiles\文件夹中的任何文件发送事件。要为您的应用程序启用此功能，请在LoggerConfiguration中添加一个文件目的地，并注意设置shared和flushToDiskInterval参数。

Log.Logger = new LoggerConfiguration()
    .MinimumLevel.Debug()
    .MinimumLevel.Override("Microsoft", LogEventLevel.Information)
    .Enrich.FromLogContext()
    .WriteTo.Console()
    // Add this line:
    .WriteTo.File(
       System.IO.Path.Combine(Environment.GetEnvironmentVariable("HOME"), "LogFiles", "Application", "diagnostics.txt"),
       rollingInterval: RollingInterval.Day,
       fileSizeLimitBytes: 10 * 1024 * 1024,
       retainedFileCountLimit: 2,
       rollOnFileSizeLimit: true,
       shared: true,
       flushToDiskInterval: TimeSpan.FromSeconds(1))
    .CreateLogger();

将属性推送到ILogger<T>

如果您想向代码特定部分的全部日志事件添加额外属性，您可以使用以下代码将其添加到Microsoft.Extensions.Logging中的ILogger<T>。要使上述代码生效，请确保您已将.Enrich.FromLogContext()添加到上述示例中指定的.UseSerilog(...)语句。

// Microsoft.Extensions.Logging ILogger<T>
// Yes, it's required to use a dictionary. See https://nblumhardt.com/2016/11/ilogger-beginscope/
using (logger.BeginScope(new Dictionary<string, object>
{
    ["UserId"] = "svrooij",
    ["OperationType"] = "update",
}))
{
   // UserId and OperationType are set for all logging events in these brackets
}

上述代码产生的结果与您在Serilog的LogContext中推送属性的效果相同。更多详细信息可在https://github.com/serilog/serilog/wiki/Enrichment#the-logcontext中找到。

// Serilog LogContext
using (LogContext.PushProperty("UserId", "svrooij"))
using (LogContext.PushProperty("OperationType", "update"))
{
    // UserId and OperationType are set for all logging events in these brackets
}