Serilog.Exceptions.EntityFrameworkCore 8.4.0

Serilog.Exceptions 是 Serilog（Serilog）的一个扩展，用于记录异常详情和不在 Exception.ToString() 中输出的自定义属性。

它能做什么？

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

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();

确保处理程序的格式化程序输出扩展属性。 Serilog.Sinks.Console 和许多其他处理程序默认不这样做。您可能需要在处理程序的格式模板中添加 {Properties:j}。例如，控制台处理程序的配置可能如下所示

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

JSON appSettings.json 配置

或者，可以使用 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 的新版本通过防止解构实现 IQueryable 的属性来避免此问题，从而阻止其执行。

当在您的项目中使用 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 - 帮助在Reflection解构器使用时处理循环依赖。
• mraming - 为了记录抛出异常的属性。
• optical - 为一个巨大的 VS 2017 升级 PR 做出巨大贡献。
• Jérémie Bertrand - 使 Serilog.Exceptions 与 Mono 兼容。
• krajek - 编写了一些非常需要的单元测试。