Serilog.Exceptions.SqlServer 8.4.0

Serilog.Exceptions是Serilog的一个插件，用于记录异常详情和不会被Exception.ToString()输出的高级属性。

它做了什么？

您的JSON日志现在将补充详细异常信息和自定义异常属性。以下是一个示例，展示当您使用EntityFramework从日志中记录DbEntityValidationException时会发生什么（这个异常因其具有深度嵌套的自定义属性而名声鹊起，而这些属性并未包含在.ToString()中）。

try
{
    ...
}
catch (DbEntityValidationException exception)
{
    logger.Error(exception, "Hello World");
}

上述代码记录了以下内容

{
  "Timestamp": "2015-12-07T12:26:24.0557671+00:00",
  "Level": "Error",
  "MessageTemplate": "Hello World",
  "RenderedMessage": "Hello World",
  "Exception": "System.Data.Entity.Validation.DbEntityValidationException: Message",
  "Properties": {
    "ExceptionDetail": {
      "EntityValidationErrors": [
        {
          "Entry": null,
          "ValidationErrors": [
            {
              "PropertyName": "PropertyName",
              "ErrorMessage": "PropertyName is Required.",
              "Type": "System.Data.Entity.Validation.DbValidationError"
            }
          ],
          "IsValid": false,
          "Type": "System.Data.Entity.Validation.DbEntityValidationResult"
        }
      ],
      "Message": "Validation failed for one or more entities. See 'EntityValidationErrors' property for more details.",
      "Data": {},
      "InnerException": null,
      "TargetSite": null,
      "StackTrace": null,
      "HelpLink": null,
      "Source": null,
      "HResult": -2146232032,
      "Type": "System.Data.Entity.Validation.DbEntityValidationException"
    },
    "Source": "418169ff-e65f-456e-8b0d-42a0973c3577"
  }
}

入门教程

请使用NuGet包管理器或将以下命令在包控制台窗口中运行，将Serilog.Exceptions NuGet包添加到您的项目中：

dotnet add package Serilog.Exceptions

在设置您的日志记录器时，添加如下WithExceptionDetails()行

using Serilog;
using Serilog.Exceptions;

ILogger logger = new LoggerConfiguration()
    .Enrich.WithExceptionDetails()
    .WriteTo.RollingFile(
        new JsonFormatter(renderMessage: true), 
        @"C:\logs\log-{Date}.txt")    
    .CreateLogger();

请确保输出格式化的sink输出丰富的属性。Serilog.Sinks.Console等多个sink默认不执行此操作。您可能需要将{Properties:j}添加到您sink的格式模板中。例如，控制台sink的配置可能如下所示：

.WriteTo.Console(outputTemplate: "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] {Message:lj}{NewLine}{Exception} {Properties:j}")

JSON appSettings.json配置

此外，可以将fluent配置设置存储在应用程序配置中，使用Serilog.Settings.Configuration

{
  "Serilog": {
    "Using": [ "Serilog.Exceptions" ],
    "Enrich": [ "WithExceptionDetails" ],
    "WriteTo": [
      { "Name": "Console" }
    ]
  }
}

性能

此库具有自定义代码来处理最常见的异常类型上的额外属性，并且仅在异常不受Serilog.Exceptions内部支持时才回退到使用反射来获取额外信息。反射开销存在，但最小，因为所有昂贵的基于反射的操作都只对每个异常类型执行一次。

更多解构器

Serilog.Exceptions.SqlServer

将Serilog.Exceptions.SqlServer NuGet包添加到您的项目中，以避免在使用System.Data.SqlClient时对SqlException的基于反射的解构器：

Install-Package Serilog.Exceptions.SqlServer

在设置时添加SqlExceptionDestructurer

.Enrich.WithExceptionDetails(new DestructuringOptionsBuilder()
    .WithDefaultDestructurers()
    .WithDestructurers(new[] { new SqlExceptionDestructurer() }))

Serilog.Exceptions.MsSqlServer

将Serilog.Exceptions.MsSqlServer NuGet包添加到您的项目中，以避免在使用Microsoft.Data.SqlClient时对SqlException的基于反射的解构器：

Install-Package Serilog.Exceptions.MsSqlServer

在设置时添加SqlExceptionDestructurer

.Enrich.WithExceptionDetails(new DestructuringOptionsBuilder()
    .WithDefaultDestructurers()
    .WithDestructurers(new[] { new SqlExceptionDestructurer() }))

Serilog.Exceptions.EntityFrameworkCore

警告：在Serilog.Exceptions的版本早于8.0.0的版本中，如果您在使用EntityFrameworkCore和Serilog.Exceptions时，必须在某些情况下添加此内容，否则整个数据库将被记录！这是因为Entity Framework Core中的异常具有与整个数据库模式链接的属性（参见#100，aspnet/EntityFrameworkCore#15214）。Serilog.Exceptions的新版本通过防止属性的实施与分析来避免这个问题，这些属性阻止了它们的执行。

当您在项目中使用EntityFrameworkCore时，将Serilog.Exceptions.EntityFrameworkCore NuGet包添加到您的项目中

Install-Package Serilog.Exceptions.EntityFrameworkCore

在设置时添加DbUpdateExceptionDestructurer

.Enrich.WithExceptionDetails(new DestructuringOptionsBuilder()
    .WithDefaultDestructurers()
    .WithDestructurers(new[] { new DbUpdateExceptionDestructurer() }))

Serilog.Exceptions.Refit

将Serilog.Exceptions.Refit NuGet包添加到您的项目中以提供有关使用Refit的ApiException的详细日志记录

Install-Package Serilog.Exceptions.Refit

在设置时添加ApiExceptionDestructurer

.Enrich.WithExceptionDetails(new DestructuringOptionsBuilder()
    .WithDefaultDestructurers()
    .WithDestructurers(new[] { new ApiExceptionDestructurer() }))

根据您的Serilog设置，常见的System.Exception属性可能已经被记录。要跳过这些属性的记录，请使用如下重载构造函数：

.Enrich.WithExceptionDetails(new DestructuringOptionsBuilder()
    .WithDefaultDestructurers()
    .WithDestructurers(new[] { new ApiExceptionDestructurer(destructureCommonExceptionProperties: false) }))

默认配置会记录ApiException的以下属性：

• Uri
• StatusCode

此外，还可以记录ApiException.Content属性，如下所述：

.Enrich.WithExceptionDetails(new DestructuringOptionsBuilder()
    .WithDefaultDestructurers()
    .WithDestructurers(new[] { new ApiExceptionDestructurer(destructureHttpContent: true) }))

注意使用此选项，因为HTTP正文可能非常大，并且/或可能包含敏感信息。

Serilog.Exceptions.Grpc

将 Serilog.Exceptions.Grpc NuGet 包添加到项目中，以避免在使用 Grpc.Net.Client 时对 RpcException 的反射式解构造

Install-Package Serilog.Exceptions.Grpc

在设置过程中添加 RpcExceptionDestructurer

.Enrich.WithExceptionDetails(new DestructuringOptionsBuilder()
    .WithDefaultDestructurers()
    .WithDestructurers(new[] { new RpcExceptionDestructurer() }))

自定义异常解构造器

您可能希望添加对自定义异常解构造器的支持，而不依赖于反射。为此，创建自己的解构造类实现 ExceptionDestructurer（您可以通过这个 实现 ArgumentException ），然后简单地按照如下方式添加：

.Enrich.WithExceptionDetails(new DestructuringOptionsBuilder()
    .WithDefaultDestructurers()
    .WithDestructurers(new[] { new MyCustomExceptionDestructurer() }))

如果您编写了一个不包括在此项目中的解构造器（即使是第三方库的），请贡献它。

附加配置

您可以在设置时传递自定义解构造选项来配置解构过程的某些附加属性

.Enrich.WithExceptionDetails(new DestructuringOptionsBuilder()
    .WithDefaultDestructurers()
    .WithRootName("Exception"))

当前支持以下选项

• RootName：将解构的异常保存到的属性名称，默认为 ExceptionDetail。
• Filter：实现 IExceptionPropertyFilter 的对象，在将属性放入解构的异常对象之前有机会过滤这些属性。"属性过滤"部分提供了详细信息。
• DestructuringDepth：基于反射的递归解构造过程的最大深度。
• ReflectionBasedDestructurer：默认情况下，基于反射的解构造器被启用，但在需要完全控制解构过程的情况下可以禁用。您必须显式注册所有异常的解构造器。

属性过滤

您可能希望跳过所有或部分异常类的一些属性，而不直接创建或修改自定义解构造器。Serilog.Exceptions 通过筛选器支持此功能。

最常见的用例是需要跳过 StackTrace 和 TargetSite。Serilog 已经报告了它们，因此您可能希望 Serilog.Exceptions 跳过它们以节省空间和处理时间。为此，您只需修改配置中的一行：

.Enrich.WithExceptionDetails(new DestructuringOptionsBuilder().WithFilter(someFilter));

其他场景的过滤也受支持

• 如果需要过滤其他命名属性集，请使用 WithIgnoreStackTraceAndTargetSiteExceptionFilter
• 实现自定义的 IExceptionPropertyFilter 以便使用不同的过滤逻辑
• 使用 CompositeExceptionPropertyFilter 来组合多个筛选器

持续集成

名称	操作系统	状态	历史
Azure Pipelines	Ubuntu
Azure Pipelines	Mac
Azure Pipelines	Windows
Azure Pipelines	总体
GitHub Actions	Ubuntu、Mac 和 Windows
AppVeyor	Ubuntu、Mac 和 Windows

贡献和感谢

请查看贡献指南 以获取更多信息。

• 304NotModified - 添加了 Markdown 语法高亮显示。
• joelweiss - 添加了 Entity Framework Core 解构造器。
• krajek 和 JeroenDragt - 为添加过滤以帮助忽略不想记录的异常属性做出了贡献。
• krajek - 在使用反射解构造器时帮助处理循环依赖。
• mraming - 对于记录抛出异常的属性做出了贡献。
• optical - 对于一个巨大的 VS 2017 升级 PR 做出了贡献。
• Jérémie Bertrand - 对于使 Serilog.Exceptions 与 Mono 兼容做出了贡献。
• krajek - 编写了一些必不可少的单元测试。