Serilog.Settings.Configuration 8.0.2

Serilog.Settings.Configuration

一个从Microsoft.Extensions.Configuration源头读取设置的Serilog设置提供程序，包括.NET Core的appsettings.json文件。

默认情况下，配置将从配置文件顶部的Serilog部分读取。

{
  "Serilog": {
    "Using":  [ "Serilog.Sinks.Console", "Serilog.Sinks.File" ],
    "MinimumLevel": "Debug",
    "WriteTo": [
      { "Name": "Console" },
      { "Name": "File", "Args": { "path": "Logs/log.txt" } }
    ],
    "Enrich": [ "FromLogContext", "WithMachineName", "WithThreadId" ],
    "Destructure": [
      { "Name": "With", "Args": { "policy": "Sample.CustomPolicy, Sample" } },
      { "Name": "ToMaximumDepth", "Args": { "maximumDestructuringDepth": 4 } },
      { "Name": "ToMaximumStringLength", "Args": { "maximumStringLength": 100 } },
      { "Name": "ToMaximumCollectionCount", "Args": { "maximumCollectionCount": 10 } }
    ],
    "Properties": {
        "Application": "Sample"
    }
  }
}

安装此包后，使用ReadFrom.Configuration()并传递一个IConfiguration对象。

static void Main(string[] args)
{
    var configuration = new ConfigurationBuilder()
        .SetBasePath(Directory.GetCurrentDirectory())
        .AddJsonFile("appsettings.json")
        .AddJsonFile($"appsettings.{Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT") ?? "Production"}.json", true)
        .Build();

    var logger = new LoggerConfiguration()
        .ReadFrom.Configuration(configuration)
        .CreateLogger();

    logger.Information("Hello, world!");
}

此示例依赖于以下包：Microsoft.Extensions.Configuration.Json、Serilog.Sinks.Console、Serilog.Sinks.File、Serilog.Enrichers.Environment和Serilog.Enrichers.Thread，这些包也必须是已安装的。

要查看更复杂的示例，请转到示例文件夹。

语法描述

根部分名

根部分名是可以更改的

{
  "CustomSection": {
    ...
  }
}

var options = new ConfigurationReaderOptions { SectionName = "CustomSection" };
var logger = new LoggerConfiguration()
    .ReadFrom.Configuration(configuration, options)
    .CreateLogger();

使用部分和配置程序集的自动发现

Using部分包含包含配置方法（如WriteTo.File()、Enrich.WithThreadId()）的assemblies列表。

"Serilog": {
    "Using":  [ "Serilog.Sinks.Console", "Serilog.Enrichers.Thread", /* ... */ ],
    // ...
}

对于.NET Core项目，构建工具生成.deps.json文件，本包利用Microsoft.Extensions.DependencyModel的约定来查找依赖中任何带有Serilog的包名称，并从中提取配置方法，因此示例中的Using部分可以省略。

{
  "Serilog": {
    "MinimumLevel": "Debug",
    "WriteTo": [ "Console" ],
    ...
  }
}

为了利用此约定在用.NET Core CLI工具构建的.NET Framework项目中指定PreserveCompilationContext为true在csproj属性中

<PropertyGroup Condition=" '$(TargetFramework)' == 'net46' ">
  <PreserveCompilationContext>true</PreserveCompilationContext>
</PropertyGroup>

在非标准依赖管理的情况下，可以传递一个自定义的DependencyContext对象

var functionDependencyContext = DependencyContext.Load(typeof(Startup).Assembly);

var options = new ConfigurationReaderOptions(functionDependencyContext) { SectionName = "AzureFunctionsJobHost:Serilog" };
var logger = new LoggerConfiguration()
    .ReadFrom.Configuration(hostConfig, options)
    .CreateLogger();

或者，也可以传递配置程序集的数组

var configurationAssemblies = new[]
{
    typeof(ConsoleLoggerConfigurationExtensions).Assembly,
    typeof(FileLoggerConfigurationExtensions).Assembly,
};
var options = new ConfigurationReaderOptions(configurationAssemblies);
var logger = new LoggerConfiguration()
    .ReadFrom.Configuration(configuration, options)
    .CreateLogger();

对于传统的.NET Framework项目，它还会扫描默认的探测路径。

对于所有其他情况，以及在非传统配置程序集名称的情况下，务必使用Using部分。

从.NET 5.0开始的单文件应用程序

目前，在捆绑模式下不支持配置程序集的自动发现。务必使用Using部分或显式传递配置程序集的集合作为解决方案。

MinimumLevel、LevelSwitches、覆盖和动态重新加载

MinimumLevel配置属性可以设置为一个单个值，如上面的示例，或者级别可以按日志源覆盖。

这在ASP.NET Core应用程序中很有用，因为这些应用程序通常会指定最小级别。

"MinimumLevel": {
    "Default": "Information",
    "Override": {
        "Microsoft": "Warning",
        "System": "Warning"
    }
}

MinimumLevel部分还尊重底层提供程序支持的动态重新加载。

var configuration = new ConfigurationBuilder()
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddJsonFile(path: "appsettings.json", reloadOnChange: true)
    .Build();

（注意：仅对现有源尊重动态更新。不支持在Override部分插入新记录。）

您还可以在自定义部分中声明LoggingLevelSwitch并引用它们作为后端参数。

{
    "Serilog": {
        "LevelSwitches": { "controlSwitch": "Verbose" },
        "WriteTo": [
            {
                "Name": "Seq",
                "Args": {
                    "serverUrl": "http://localhost:5341",
                    "apiKey": "yeEZyL3SMcxEKUijBjN",
                    "controlLevelSwitch": "$controlSwitch"
                }
            }
        ]
    }
}

自版本 7.0.0 开始，声明开关（即 Serilog:LevelSwitches 部分）和最低等级覆盖开关（即 Serilog:MinimumLevel:Override 部分）都通过读取器选项上的回调进行暴露，以便保留引用

var allSwitches = new Dictionary<string, LoggingLevelSwitch>();
var options = new ConfigurationReaderOptions
{
    OnLevelSwitchCreated = (switchName, levelSwitch) => allSwitches[switchName] = levelSwitch
};

var logger = new LoggerConfiguration()
    .ReadFrom.Configuration(configuration, options)
    .CreateLogger();

LoggingLevelSwitch controlSwitch = allSwitches["$controlSwitch"];

WriteTo、Enrich、AuditTo、Destructure 部分

这些部分支持简化语法，例如以下内容在没有需要由处理程序传递参数的情况下是有效的

"WriteTo": [ "Console", "DiagnosticTrace" ]

或者，也可以使用上述示例中的长形式（"Name":）语法来传递参数。

按 Microsoft.Extensions.Configuration.Json 惯例，数组语法隐式地为每个元素定义索引，以便为配置键创建唯一的路径。因此，上述示例等同于

"WriteTo": {
    "0": "Console",
    "1": "DiagnosticTrace"
}

并且

"WriteTo:0": "Console",
"WriteTo:1": "DiagnosticTrace"

（键的结果路径将相同，即 Serilog:WriteTo:0 和 Serilog:WriteTo:1）

当使用环境变量覆盖设置时，它会变得更加不方便且脆弱，因此你可以指定自定义名称

"WriteTo": {
    "ConsoleSink": "Console",
    "DiagnosticTraceSink": { "Name": "DiagnosticTrace" }
}

属性部分

本部分定义了一个静态键值对列表，它将丰富日志事件。

过滤器部分

本部分定义了将应用于日志事件的过滤器。这在与 Serilog.Expressions（或旧版 Serilog.Filters.Expressions） 包结合使用时特别有用，这样你可以在文本形式中编写表达式

"Filter": [{
  "Name": "ByIncludingOnly",
  "Args": {
      "expression": "Application = 'Sample'"
  }
}]

使用此包，你还可以在自定义部分声明 LoggingFilterSwitch，并将它们引用为过滤器参数

{
    "Serilog": {
        "FilterSwitches": { "filterSwitch": "Application = 'Sample'" },
        "Filter": [
            {
                "Name": "ControlledBy",
                "Args": {
                    "switch": "$filterSwitch"
                }
            }
        ]
}

自版本 7.0.0 开始，过滤器开关通过读取器选项上的回调进行暴露，以便保留引用

var filterSwitches = new Dictionary<string, ILoggingFilterSwitch>();
var options = new ConfigurationReaderOptions
{
    OnFilterSwitchCreated = (switchName, filterSwitch) => filterSwitches[switchName] = filterSwitch
};

var logger = new LoggerConfiguration()
    .ReadFrom.Configuration(configuration, options)
    .CreateLogger();

ILoggingFilterSwitch filterSwitch = filterSwitches["filterSwitch"];

嵌套配置部分

某些 Serilog 包需要引用日志配置对象。本项目中示例程序的以下条目配置了 Serilog.Sinks.Async 包以包装 Serilog.Sinks.File 包。configure 参数引用了 File 处理器配置

"WriteTo:Async": {
  "Name": "Async",
  "Args": {
    "configure": [
      {
        "Name": "File",
        "Args": {
          "path": "%TEMP%/Logs/serilog-configuration-sample.txt",
          "outputTemplate":
              "{Timestamp:o} [{Level:u3}] ({Application}/{MachineName}/{ThreadId}) {Message}{NewLine}{Exception}"
        }
      }
    ]
  }
},

解构

解构意味着从对象中提取信息并创建具有值的属性；Serilog 提供 @ 结构捕获运算符。如果有必要自定义序列化日志事件的样式（例如，隐藏属性值或将它们替换为其他东西），可以定义几个解构策略，如下所示

"Destructure": [
  {
    "Name": "With",
    "Args": {
      "policy": "MyFirstNamespace.FirstDestructuringPolicy, MyFirstAssembly"
    }
  },
  {
    "Name": "With",
    "Args": {
      "policy": "MySecondNamespace.SecondDestructuringPolicy, MySecondAssembly"
    }
  },
   {
    "Name": "With",
    "Args": {
      "policy": "MyThirdNamespace.ThirdDestructuringPolicy, MyThirdAssembly"
    }
  },
],

这是第一个解构策略的示例。

namespace MyFirstNamespace;

public record MyDto(int Id, int Name);

public class FirstDestructuringPolicy : IDestructuringPolicy
{
    public bool TryDestructure(object value, ILogEventPropertyValueFactory propertyValueFactory, 
        [NotNullWhen(true)] out LogEventPropertyValue? result)
    {
        if (value is not MyDto dto)
        {
            result = null;
            return false;
        }

        result = new StructureValue(new List<LogEventProperty>
        {
            new LogEventProperty("Identifier", new ScalarValue(deleteTodoItemInfo.Id)),
            new LogEventProperty("NormalizedName", new ScalarValue(dto.Name.ToUpperInvariant()))
        });

        return true;
    }
}

假设 Serilog 需要在处理日志事件时对 MyDto 类型的参数进行解构

logger.Information("About to process input: {@MyDto} ...", myDto);

它将应用 FirstDestructuringPolicy，将 MyDto 实例转换为 StructureValue 实例；Serilog 控制台处理程序将写入以下条目

About to process input: {"Identifier": 191, "NormalizedName": "SOME_UPPER_CASE_NAME"} ...

参数绑定

当配置指定了参数的离散值（如字符串字面值）时，包尝试将该值转换为目标方法声明的参数 CLR 类型。对于将字符串解析为 Uri、TimeSpan、枚举、数组和自定义集合，还提供了额外的显式处理。

自版本 7.0.0 开始，只要使用 ReadFrom.Configuration(IConfiguration configuration, ConfigurationReaderOptions options) 方法，转换将使用不变文化（CultureInfo.InvariantCulture）。已弃用的方法使用当前文化以保持后向兼容性。

静态成员支持

静态成员访问可以通过特殊语法传递给配置参数

{
  "Args": {
     "encoding": "System.Text.Encoding::UTF8",
     "theme": "Serilog.Sinks.SystemConsole.Themes.AnsiConsoleTheme::Code, Serilog.Sinks.Console"
  }
}

复杂参数值绑定

如果参数值不是离散值，它会尝试为参数找到一个最佳匹配的公共构造函数

{
  "Name": "Console",
  "Args": {
    "formatter": {
      // `type` (or $type) is optional, must be specified for abstract declared parameter types
      "type": "Serilog.Templates.ExpressionTemplate, Serilog.Expressions",
      "template": "[{@t:HH:mm:ss} {@l:u3} {Coalesce(SourceContext, '<none>')}] {@m}\n{@x}"
      }
  }
}

对于其他情况，该包将使用Microsoft.Extensions.Options.ConfigurationExtensions提供的配置绑定系统来尝试填充参数。几乎所有可以通过IConfiguration.Get<T>进行绑定的内容都应该可以与这个包一起使用。一个例子是用于配置.NET Standard版本的Serilog.Sinks.MSSqlServer包的可选List<Column>参数。

抽象参数类型

如果参数类型是一个接口或抽象类，则需要指定实现该抽象类型的完整类型名。实现类型应该有参数无构造函数。

"Destructure": [
    { "Name": "With", "Args": { "policy": "Sample.CustomPolicy, Sample" } },
    ...
],

IConfiguration参数

如果Serilog包需要额外的外部配置信息（例如，访问ConnectionStrings部分，该部分位于Serilog部分之外），则应在配置扩展方法中使用一个IConfiguration参数。这个包将自动填充这个参数。不应该在配置源中的参数列表中声明。

IConfigurationSection参数

某些Serilog包可能需要配置信息，这些信息难以用离散值或直接绑定友好的表示来表示。一个例子可能是从默认值集合中删除值的值的列表。在这种情况下，方法可以接受整个IConfigurationSection作为调用参数，并且这个包将会识别并填充这个参数。通过这种方式，Serilog包可以支持任意复杂的配置场景。

示例

Azure Functions（v2，v3）

hosts.json

{
  "version": "2.0",
  "logging": {
    "applicationInsights": {
      "samplingExcludedTypes": "Request",
      "samplingSettings": {
        "isEnabled": true
      }
    }
  },
  "Serilog": {
    "MinimumLevel": {
        "Default": "Information",
        "Override": {
            "Microsoft": "Warning",
            "System": "Warning"
        }
    },
    "Enrich": [ "FromLogContext" ],
    "WriteTo": [
      { "Name": "Seq", "Args": { "serverUrl": "http://localhost:5341" } }
    ]
  }
}

Startup.cs部分名称应以前缀AzureFunctionsJobHost开头

public class Startup : FunctionsStartup
{
    public override void Configure(IFunctionsHostBuilder builder)
    {
        builder.Services.AddSingleton<ILoggerProvider>(sp =>
        {
            var functionDependencyContext = DependencyContext.Load(typeof(Startup).Assembly);

            var hostConfig = sp.GetRequiredService<IConfiguration>();
            var options = new ConfigurationReaderOptions(functionDependencyContext) { SectionName = "AzureFunctionsJobHost:Serilog" };
            var logger = new LoggerConfiguration()
                .ReadFrom.Configuration(hostConfig, options)
                .CreateLogger();

            return new SerilogLoggerProvider(logger, dispose: true);
        });
    }
}

为了使配置程序集自动发现工作，修改Function的csproj文件

<Project Sdk="Microsoft.NET.Sdk">

  

  
  <Target Name="FunctionsPostBuildDepsCopy" AfterTargets="PostBuildEvent">
    <Copy SourceFiles="$(OutDir)$(AssemblyName).deps.json" DestinationFiles="$(OutDir)bin\$(AssemblyName).deps.json" />
  </Target>

  <Target Name="FunctionsPublishDepsCopy" AfterTargets="Publish">
    <Copy SourceFiles="$(OutDir)$(AssemblyName).deps.json" DestinationFiles="$(PublishDir)bin\$(AssemblyName).deps.json" />
  </Target>

</Project>

版本控制

这个包跟踪其Microsoft.Extensions.Configuration依赖的版本和目标框架支持。