Fixes #97, #83, #98

README.md

@@ -91,3 +91,41 @@ 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. These must be "hinted" by appending a `>` character to the end of the argument name. 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.
+
+Note the `configure>` parameter name with the trailing hint character:
+
+```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.
+

sample/Sample/appsettings.json

@@ -11,7 +11,7 @@
     "WriteTo:Sublogger": {
       "Name": "Logger",
       "Args": {
-        "configureLogger": {
+        "configureLogger>": {
           "WriteTo": [
             {
               "Name": "Console",
@@ -28,7 +28,7 @@
     "WriteTo:Async": {
       "Name": "Async",
       "Args": {
-        "configure": [
+        "configure>": [
           {
             "Name": "File",
             "Args": {

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

@@ -17,6 +17,10 @@
     <PackageProjectUrl>https://github.com/serilog/serilog-settings-configuration</PackageProjectUrl>
     <PackageLicenseUrl>https://www.apache.org/licenses/LICENSE-2.0</PackageLicenseUrl>
     <RootNamespace>Serilog</RootNamespace>
+    <GeneratePackageOnBuild>false</GeneratePackageOnBuild>
+    <Version>3.0.0</Version>
+    <AssemblyVersion>3.0.0</AssemblyVersion>
+    <FileVersion>3.0.0</FileVersion>
   </PropertyGroup>
 
   <ItemGroup>
@@ -26,10 +30,12 @@
 
   <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>