3.0 Release

.gitignore

@@ -196,3 +196,6 @@ FakesAssemblies/
 *.opt
 
 project.lock.json
+
+#Test files
+*.txt

.travis.yml

@@ -0,0 +1,11 @@
+language: csharp
+
+matrix:
+ include:
+ - os: linux
+ dist: trusty
+ sudo: required
+ dotnet: 2.1.4
+ group: edge
+script:
+ - ./build.sh

README.md

@@ -7,21 +7,27 @@ Configuration is read from the `Serilog` section.
 ```json
 {
  "Serilog": {
- "Using": ["Serilog.Sinks.Literate"],
+ "Using": ["Serilog.Sinks.Console"],
  "MinimumLevel": "Debug",
  "WriteTo": [
- { "Name": "LiterateConsole" },
+ { "Name": "Console" },
  { "Name": "File", "Args": { "path": "%TEMP%\\Logs\\serilog-configuration-sample.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"
  }
  }
 }
 ```
 
-This example relies on the _Serilog.Sinks.Literate_, _Serilog.Sinks.File_, _Serilog.Enrichers.Environment_, _Serilog.Settings.Configuration_ and _Serilog.Enrichers.Thread_ packages also being installed.
+This example relies on the _Serilog.Sinks.Console_, _Serilog.Sinks.File_, _Serilog.Enrichers.Environment_, _Serilog.Settings.Configuration_ and _Serilog.Enrichers.Thread_ packages also being installed.
 
 After installing this package, use `ReadFrom.Configuration()` and pass an `IConfiguration` object.
 
@@ -46,7 +52,7 @@ public class Program
 The `WriteTo` and `Enrich` sections support the same syntax, for example the following is valid if no arguments are needed by the sinks:
 
 ```json
-"WriteTo": ["LiterateConsole", "DiagnosticTrace"]
+"WriteTo": ["Console", "DiagnosticTrace"]
 ```
 
 Or alternatively, the long-form (`"Name":` ...) syntax from the first example can be used when arguments need to be supplied.
@@ -91,3 +97,39 @@ For example, to set the minimum log level using the _Windows_ command prompt:
 set Serilog:MinimumLevel=Debug
 dotnet run
 ```
+
+### Nested configuration sections
+
+Some Serilog packages require a reference to a logger configuration object. The sample program in this project illustrates this with the following entry configuring the _Serilog.Sinks.Async_ package to wrap the _Serilog.Sinks.File_ package. The `configure` parameter references the File sink configuration:
+
+```json
+"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}"
+ }
+ }
+ ]
+ }
+},
+```
+
+### IConfiguration parameter
+
+If a Serilog package requires additional external configuration information (for example, access to a `ConnectionStrings` section, which would be outside of the `Serilog` section), the sink should include an `IConfiguration` parameter in the configuration extension method. This package will automatically populate that parameter. It should not be declared in the argument list in the configuration source.
+
+### Complex parameter value binding
+
+When the configuration specifies a discrete value for a parameter (such as a string literal), the package will attempt to convert that value to the target method's declared CLR type of the parameter. Additional explicit handling is provided for parsing strings to `Uri` and `TimeSpan` objects and `enum` elements.
+
+If the parameter value is not a discrete value, the package will use the configuration binding system provided by _Microsoft.Extensions.Options.ConfigurationExtensions_ to attempt to populate the parameter. Almost anything that can be bound by `IConfiguration.Get<T>` should work with this package. An example of this is the optional `List<Column>` parameter used to configure the .NET Standard version of the _Serilog.Sinks.MSSqlServer_ package.
+
+### IConfigurationSection parameters
+
+Certain Serilog packages may require configuration information that can't be easily represented by discrete values or direct binding-friendly representations. An example might be lists of values to remove from a collection of default values. In this case the method can accept an entire `IConfigurationSection` as a call parameter and this package will recognize that and populate the parameter. In this way, Serilog packages can support arbitrarily complex configuration scenarios.
+

appveyor.yml

@@ -2,12 +2,6 @@ version: '{build}'
 skip_tags: true
 image: Visual Studio 2017
 configuration: Release
-install:
- - ps: mkdir -Force ".\build\" | Out-Null
- - ps: Invoke-WebRequest "https://raw.githubusercontent.com/dotnet/cli/rel/1.0.0/scripts/obtain/dotnet-install.ps1" -OutFile ".\build\installcli.ps1"
- - ps: $env:DOTNET_INSTALL_DIR = "$pwd\.dotnetcli"
- - ps: '& .\build\installcli.ps1 -InstallDir "$env:DOTNET_INSTALL_DIR" -NoPath -Version 1.0.1'
- - ps: $env:Path = "$env:DOTNET_INSTALL_DIR;$env:Path"
 build_script:
 - ps: ./Build.ps1
 test: off
@@ -16,7 +10,7 @@ artifacts:
 deploy:
 - provider: NuGet
  api_key:
- secure: nvZ/z+pMS91b3kG4DgfES5AcmwwGoBYQxr9kp4XiJHj25SAlgdIxFx++1N0lFH2x
+ secure: bd9z4P73oltOXudAjPehwp9iDKsPtC+HbgshOrSgoyQKr5xVK+bxJQngrDJkHdY8
  skip_symbols: true
  on:
  branch: /^(master|dev)$/
@@ -26,4 +20,4 @@ deploy:
  artifact: /Serilog.*\.nupkg/
  tag: v$(appveyor_build_version)
  on:
- branch: master
+ branch: master

build.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+
+set -e 
+dotnet --info
+dotnet restore
+
+for path in src/**/*.csproj; do
+ dotnet build -f netstandard2.0 -c Release ${path}
+done
+
+for path in test/*.Tests/*.csproj; do
+ dotnet test -f netcoreapp2.0 -c Release ${path}
+done
+
+cd sample/Sample/
+dotnet build -f netcoreapp2.0 -c Release 
+dotnet bin/Release/netcoreapp2.0/Sample.dll --run-once

sample/Sample/Program.cs

@@ -3,9 +3,10 @@
 using Microsoft.Extensions.Configuration;
 using Serilog;
 using System.IO;
-
+using System.Linq;
 using Serilog.Core;
 using Serilog.Events;
+using System.Collections.Generic;
 
 namespace Sample
 {
@@ -22,6 +23,8 @@ public static void Main(string[] args)
  .ReadFrom.Configuration(configuration)
  .CreateLogger();
 
+ logger.Information("Args: {a}", args);
+
  do
  {
  logger.ForContext<Program>().Information("Hello, world!");
@@ -30,17 +33,56 @@ public static void Main(string[] args)
  logger.ForContext(Constants.SourceContextPropertyName, "Microsoft").Error("Hello, world!");
  logger.ForContext(Constants.SourceContextPropertyName, "MyApp.Something.Tricky").Verbose("Hello, world!");
 
- Console.WriteLine();
+ logger.Information("Destructure with max object nesting depth:\n{@NestedObject}",
+ new { FiveDeep = new { Two = new { Three = new { Four = new { Five = "the end" } } } } });
+
+ logger.Information("Destructure with max string length:\n{@LongString}",
+ new { TwentyChars = "0123456789abcdefghij" });
+
+ logger.Information("Destructure with max collection count:\n{@BigData}",
+ new { TenItems = new[] { "one", "two", "three", "four", "five", "six", "seven", "eight", "nine", "ten" } });
+
+ logger.Information("Destructure with policy to strip password:\n{@LoginData}",
+ new LoginData { Username = "BGates", Password = "isityearoflinuxyet" });
+
+ Console.WriteLine("\nPress \"q\" to quit, or any other key to run again.\n");
  }
- while (Console.ReadKey().KeyChar != 'q');
+ while(!args.Contains("--run-once") && (Console.ReadKey().KeyChar != 'q'));
  }
  }
 
+ // The filter syntax in the sample configuration file is
+ // processed by the Serilog.Filters.Expressions package.
  public class CustomFilter : ILogEventFilter
  {
  public bool IsEnabled(LogEvent logEvent)
  {
  return true;
  }
  }
+
+ public class LoginData
+ {
+ public string Username;
+ public string Password;
+ }
+
+ public class CustomPolicy : IDestructuringPolicy
+ {
+ public bool TryDestructure(object value, ILogEventPropertyValueFactory propertyValueFactory, out LogEventPropertyValue result)
+ {
+ result = null;
+
+ if(value is LoginData)
+ {
+ result = new StructureValue(
+ new List<LogEventProperty>
+ {
+ new LogEventProperty("Username", new ScalarValue(((LoginData)value).Username))
+ });
+ }
+
+ return (result != null);
+ }
+ }
 }

sample/Sample/Sample.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
  <PropertyGroup>
- <TargetFrameworks>net46;netcoreapp1.0</TargetFrameworks>
+ <TargetFrameworks>net46;netcoreapp2.0</TargetFrameworks>
  <OutputType>Exe</OutputType>
  </PropertyGroup>
 
@@ -13,8 +13,15 @@
  <ProjectReference Include="..\..\src\Serilog.Settings.Configuration\Serilog.Settings.Configuration.csproj" />
  </ItemGroup>
 
- <ItemGroup>
+ <ItemGroup Condition="'$(TargetFramework)' == 'net46'">
  <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="1.1.1" />
+ </ItemGroup>
+
+ <ItemGroup Condition="'$(TargetFramework)' == 'netcoreapp2.0'">
+ <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="2.0.1" />
+ </ItemGroup>
+
+ <ItemGroup>
  <PackageReference Include="Serilog.Sinks.Async" Version="1.0.1" />
  <PackageReference Include="Serilog.Sinks.Console" Version="3.1.1" />
  <PackageReference Include="Serilog.Sinks.RollingFile" Version="3.0.0" />

sample/Sample/appsettings.json

@@ -43,6 +43,24 @@
  "Properties": {
  "Application": "Sample"
  },
+ "Destructure": [
+ {
+ "Name": "With",
+ "Args": { "policy": "Sample.CustomPolicy, Sample" }
+ },
+ {
+ "Name": "ToMaximumDepth",
+ "Args": { "maximumDestructuringDepth": 3 }
+ },
+ {
+ "Name": "ToMaximumStringLength",
+ "Args": { "maximumStringLength": 10 }
+ },
+ {
+ "Name": "ToMaximumCollectionCount",
+ "Args": { "maximumCollectionCount": 5 }
+ }
+ ],
  "Filter": [
  {
  "Name": "ByIncludingOnly",

src/Serilog.Settings.Configuration/ConfigurationLoggerConfigurationExtensions.cs

@@ -26,13 +26,18 @@ namespace Serilog
  /// </summary>
  public static class ConfigurationLoggerConfigurationExtensions
  {
- const string DefaultSectionName = "Serilog";
+ /// <summary>
+ /// Configuration section name required by this package.
+ /// </summary>
+ public const string DefaultSectionName = "Serilog";
 
  /// <summary>
- /// Reads logger settings from the provided configuration object using the default section name.
+ /// Reads logger settings from the provided configuration object using the default section name. Generally this
+ /// is preferable over the other method that takes a configuration section. Only this version will populate
+ /// IConfiguration parameters on target methods.
  /// </summary>
  /// <param name="settingConfiguration">Logger setting configuration.</param>
- /// <param name="configuration">A configuration object with a Serilog section.</param>
+ /// <param name="configuration">A configuration object which contains a Serilog section.</param>
  /// <param name="dependencyContext">The dependency context from which sink/enricher packages can be located. If not supplied, the platform
  /// default will be used.</param>
  /// <returns>An object allowing configuration to continue.</returns>
@@ -42,28 +47,32 @@ public static LoggerConfiguration Configuration(
  DependencyContext dependencyContext = null)
  {
  if (configuration == null) throw new ArgumentNullException(nameof(configuration));
- return settingConfiguration.ConfigurationSection(configuration.GetSection(DefaultSectionName), dependencyContext);
+ return settingConfiguration.Settings(
+ new ConfigurationReader(
+ configuration,
+ dependencyContext ?? (Assembly.GetEntryAssembly() != null ? DependencyContext.Default : null)));
  }
 
  /// <summary>
- /// Reads logger settings from the provided configuration section.
+ /// Reads logger settings from the provided configuration section. Generally it is preferable to use the other
+ /// extension method that takes the full configuration object.
  /// </summary>
  /// <param name="settingConfiguration">Logger setting configuration.</param>
- /// <param name="configuration">The Serilog configuration section</param>
+ /// <param name="configSection">The Serilog configuration section</param>
  /// <param name="dependencyContext">The dependency context from which sink/enricher packages can be located. If not supplied, the platform
  /// default will be used.</param>
  /// <returns>An object allowing configuration to continue.</returns>
  public static LoggerConfiguration ConfigurationSection(
  this LoggerSettingsConfiguration settingConfiguration,
- IConfigurationSection configuration,
+ IConfigurationSection configSection,
  DependencyContext dependencyContext = null)
  {
  if (settingConfiguration == null) throw new ArgumentNullException(nameof(settingConfiguration));
- if (configuration == null) throw new ArgumentNullException(nameof(configuration));
+ if (configSection == null) throw new ArgumentNullException(nameof(configSection));
 
  return settingConfiguration.Settings(
  new ConfigurationReader(
- configuration,
+ configSection,
  dependencyContext ?? (Assembly.GetEntryAssembly() != null ? DependencyContext.Default : null)));
  }
  }

src/Serilog.Settings.Configuration/Serilog.Settings.Configuration.csproj

@@ -2,9 +2,9 @@
 
  <PropertyGroup>
  <Description>Microsoft.Extensions.Configuration (appsettings.json) support for Serilog.</Description>
- <VersionPrefix>2.6.1</VersionPrefix>
+ <VersionPrefix>3.0.0</VersionPrefix>
  <Authors>Serilog Contributors</Authors>
- <TargetFrameworks>net451;netstandard1.6</TargetFrameworks>
+ <TargetFrameworks>netstandard2.0;net451</TargetFrameworks>
  <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <AssemblyName>Serilog.Settings.Configuration</AssemblyName>
@@ -16,20 +16,22 @@
  <PackageIconUrl>https://serilog.net/images/serilog-configuration-nuget.png</PackageIconUrl>
  <PackageProjectUrl>https://github.com/serilog/serilog-settings-configuration</PackageProjectUrl>
  <PackageLicenseUrl>https://www.apache.org/licenses/LICENSE-2.0</PackageLicenseUrl>
-
- <!-- Don't reference the full NETStandard.Library -->
- <DisableImplicitFrameworkReferences>true</DisableImplicitFrameworkReferences>
  <RootNamespace>Serilog</RootNamespace>
  </PropertyGroup>
 
  <ItemGroup>
- <PackageReference Include="Microsoft.Extensions.Configuration.Abstractions" Version="1.0.0" />
- <PackageReference Include="Microsoft.Extensions.DependencyModel" Version="1.0.0" />
+ <PackageReference Include="Microsoft.Extensions.DependencyModel" Version="2.0.4" />
  <PackageReference Include="Serilog" Version="2.6.0" />
  </ItemGroup>
 
- <PropertyGroup Condition=" '$(TargetFramework)' == 'net451' ">
- <DefineConstants>$(DefineConstants);APPDOMAIN</DefineConstants>
- </PropertyGroup>
+ <ItemGroup Condition="'$(TargetFramework)' == 'net451'">
+ <PackageReference Include="Microsoft.Extensions.Configuration.Abstractions" Version="1.1.2" />
+ <PackageReference Include="Microsoft.Extensions.Options.ConfigurationExtensions" Version="1.1.2" />
+ </ItemGroup>
+
+ <ItemGroup Condition="'$(TargetFramework)' == 'netstandard2.0'">
+ <PackageReference Include="Microsoft.Extensions.Configuration.Abstractions" Version="2.0.1" />
+ <PackageReference Include="Microsoft.Extensions.Options.ConfigurationExtensions" Version="2.0.0" />
+ </ItemGroup>
 
 </Project>