Merge pull request #1975 from serilog/dev

3.1.0 Release

CONTRIBUTING.md

@@ -7,7 +7,7 @@ The following are a set of guidelines for contributing to [Serilog](https://seri
 
 ## Where to start?
 
-The [Serilog repository][serilog] is the location for enhancements and fixes to the core library.  Generally we try to keep the core library lean and performant while attempting to deliver the features of a first class logging library.  
+The [Serilog repository][serilog] is the location for enhancements and fixes to the core library.  Generally we try to keep the core library lean and performant while attempting to deliver the features of a first class logging library.
 
 If you are interested in contributing to a [sink][sinks] or one of the other [community projects][community_projects] then please create a PR in the respective repository.
 
@@ -52,7 +52,6 @@ Serilog has an active and helpful community who are happy to help point you in t
 
  * [Stack Overflow](http://stackoverflow.com/questions/tagged/serilog) - this is the best place to start if you have a question
  * Our [issue tracker](https://github.com/serilog/serilog/issues) here on GitHub
- * [Gitter chat](https://gitter.im/serilog/serilog)
  * The [#serilog tag on Twitter](https://twitter.com/search?q=%23serilog)
 
 

Directory.Build.props

@@ -7,10 +7,11 @@
     <CheckEolTargetFramework>false</CheckEolTargetFramework>
     <Nullable>enable</Nullable>
     <ImplicitUsings>enable</ImplicitUsings>
+    <Copyright>Copyright © 2013-23 Serilog Contributors</Copyright>
   </PropertyGroup>
   <ItemGroup Condition="'$(TargetFrameworkIdentifier)' == '.NETFramework'">
     <Reference Include="System" />
     <Reference Include="System.Core" />
     <Reference Include="Microsoft.CSharp" />
   </ItemGroup>
-</Project>
+</Project>

README.md

@@ -7,7 +7,7 @@ Serilog is a diagnostic logging library for .NET applications. It is easy to set
 Like many other libraries for .NET, Serilog provides diagnostic logging to [files](https://github.com/serilog/serilog-sinks-file), the [console](https://github.com/serilog/serilog-sinks-console), and [many other outputs](https://github.com/serilog/serilog/wiki/Provided-Sinks).
 
 ```csharp
-var log = new LoggerConfiguration()
+using var log = new LoggerConfiguration()
     .WriteTo.Console()
     .WriteTo.File("log.txt")
     .CreateLogger();
@@ -42,7 +42,7 @@ Supporting structured data doesn't mean giving up text: when Serilog writes even
 09:14:22 [INF] Processed {"Latitude": 25, "Longitude": 134} in 34 ms.
 ```
 
-> **Upgrading from Serilog 1.x?** Check out the [2.0 Upgrade Guide](https://github.com/serilog/serilog/wiki/2.x-Upgrade-Guide) and [Release Notes](https://github.com/serilog/serilog/blob/dev/CHANGES.md).
+> **Upgrading from an earlier Serilog version?** Find [release notes here](https://github.com/serilog/serilog/releases).
 
 ### Features
 
@@ -58,35 +58,40 @@ Supporting structured data doesn't mean giving up text: when Serilog writes even
 
 ### Getting started
 
-Serilog is installed from NuGet. To view log events, one or more sinks need to be installed as well, here we'll use the pretty-printing console sink, and a rolling file set:
+Serilog is installed [from NuGet](https://nuget.org/packages/serilog). To view log events, one or more sinks need to be installed as well, here we'll use the pretty-printing console sink, and a rolling file set:
 
 ```
 dotnet add package Serilog
 dotnet add package Serilog.Sinks.Console
 dotnet add package Serilog.Sinks.File
 ```
 
-The simplest way to set up Serilog is using the static `Log` class. A `LoggerConfiguration` is used to create and assign the default logger.
+The simplest way to set up Serilog is using the static `Log` class. A `LoggerConfiguration` is used to create and assign the default logger, normally in _Program.cs_:
 
 ```csharp
 using Serilog;
 
-public class Program
+Log.Logger = new LoggerConfiguration()
+    .WriteTo.Console()
+    .WriteTo.File("log.txt",
+        rollingInterval: RollingInterval.Day,
+        rollOnFileSizeLimit: true)
+    .CreateLogger();
+
+try
+{
+    // Your program here...
+    const string name = "Serilog";
+    Log.Information("Hello, {Name}!", name);
+    throw new InvalidOperationException("Oops...");
+}
+catch (Exception ex)
+{
+    Log.Error(ex, "Unhandled exception");
+}
+finally
 {
-    public static void Main()
-    {
-        Log.Logger = new LoggerConfiguration()
-            .MinimumLevel.Information()
-            .WriteTo.Console()
-            .WriteTo.File("log.txt",
-                rollingInterval: RollingInterval.Day,
-                rollOnFileSizeLimit: true)
-            .CreateLogger();
-
-        Log.Information("Hello, Serilog!");
-
-        Log.CloseAndFlush();
-    }
+    await Log.CloseAndFlushAsync(); // ensure all logs written before app exits
 }
 ```
 
@@ -98,12 +103,12 @@ To learn more about Serilog, check out the [documentation](https://github.com/se
 
 Serilog has an active and helpful community who are happy to help point you in the right direction or work through any issues you might encounter. You can get in touch via:
 
- * [Stack Overflow](http://stackoverflow.com/questions/tagged/serilog) — this is the best place to start if you have a question
- * [Gitter chat](https://gitter.im/serilog/serilog)
+ * [Stack Overflow](http://stackoverflow.com/questions/tagged/serilog) — this is the best place to start if you have a question. Many track the `serilog` tag there.
  * The [#serilog tag on Twitter](https://twitter.com/search?q=%23serilog)
  * [Serilog-related courses on Pluralsight](https://www.pluralsight.com/search/?q=serilog)
 
-We welcome bug reports and suggestions through our [issue tracker](https://github.com/serilog/serilog/issues) here on GitHub.
+We welcome reproducible bug reports and detailed feature requests through [our GitHub issue tracker](https://github.com/serilog/serilog/issues);
+note the other resource are much better for quick questions or seeking usage help.
 
 ### Contributing
 
@@ -118,4 +123,4 @@ When contributing please keep in mind our [Code of Conduct](CODE_OF_CONDUCT.md).
 | `dev`  | [![Build status](https://ci.appveyor.com/api/projects/status/b9rm3l7kduryjgcj/branch/dev?svg=true)](https://ci.appveyor.com/project/serilog/serilog/branch/dev)       |
 | `main` | [![Build status](https://ci.appveyor.com/api/projects/status/b9rm3l7kduryjgcj/branch/master?svg=true)](https://ci.appveyor.com/project/serilog/serilog/branch/master) |
 
-_Serilog is copyright © 2013-2020 Serilog Contributors - Provided under the [Apache License, Version 2.0](http://apache.org/licenses/LICENSE-2.0.html). Needle and thread logo a derivative of work by [Kenneth Appiah](http://www.kensets.com/)._
+_Serilog is copyright © Serilog Contributors - Provided under the [Apache License, Version 2.0](http://apache.org/licenses/LICENSE-2.0.html). Needle and thread logo a derivative of work by [Kenneth Appiah](http://www.kensets.com/)._

Serilog.sln

@@ -8,7 +8,6 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "assets", "assets", "{E9D1B5
 		appveyor.yml = appveyor.yml
 		Build.ps1 = Build.ps1
 		build.sh = build.sh
-		CHANGES.md = CHANGES.md
 		Directory.Build.props = Directory.Build.props
 		Directory.Build.targets = Directory.Build.targets
 		global.json = global.json

Serilog.sln.DotSettings

@@ -218,6 +218,7 @@
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=destructure/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=Enricher/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=Enrichers/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=formattable/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=Obsoletion/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=stringified/@EntryIndexedValue">True</s:Boolean></wpf:ResourceDictionary>
 

appveyor.yml

@@ -31,7 +31,7 @@ artifacts:
 deploy:
 - provider: NuGet
   api_key:
-    secure: 45/vGyNCdoOvWSorcVX6qYM3oC/mCBj0CDRXNZP4twlIrBiZ9sKtKMdHwufm4ogS
+    secure: JbUCIGD4FHOxmhM49oqvJdLb0TtGQAmBD5vOG9fSROaa85d7sddTLA8suvm407Dk
   on:
     branch: /^(main|dev)$/
 - provider: GitHub

src/Serilog/Capturing/MessageTemplateProcessor.cs

@@ -26,7 +26,11 @@ public MessageTemplateProcessor(PropertyValueConverter propertyValueConverter)
         _propertyBinder = new(_propertyValueConverter);
     }
 
-    public void Process(string messageTemplate, object?[]? messageTemplateParameters, out MessageTemplate parsedTemplate, out EventProperty[] properties)
+#if FEATURE_SPAN
+    public void Process(string messageTemplate, ReadOnlySpan<object?> messageTemplateParameters, out MessageTemplate parsedTemplate, out EventProperty[] properties)
+#else
+    public void Process(string messageTemplate, object?[] messageTemplateParameters, out MessageTemplate parsedTemplate, out EventProperty[] properties)
+#endif
     {
         parsedTemplate = _parser.Parse(messageTemplate);
         properties = _propertyBinder.ConstructProperties(parsedTemplate, messageTemplateParameters);

src/Serilog/Capturing/PropertyBinder.cs

@@ -34,9 +34,13 @@ public PropertyBinder(PropertyValueConverter valueConverter)
     /// represented in the message template.</param>
     /// <returns>A list of properties; if the template is malformed then
     /// this will be empty.</returns>
-    public EventProperty[] ConstructProperties(MessageTemplate messageTemplate, object?[]? messageTemplateParameters)
+#if FEATURE_SPAN
+    public EventProperty[] ConstructProperties(MessageTemplate messageTemplate, ReadOnlySpan<object?> messageTemplateParameters)
+#else
+    public EventProperty[] ConstructProperties(MessageTemplate messageTemplate, object?[] messageTemplateParameters)
+#endif
     {
-        if (messageTemplateParameters == null || messageTemplateParameters.Length == 0)
+        if (messageTemplateParameters.Length == 0)
         {
             if (messageTemplate.NamedProperties != null || messageTemplate.PositionalProperties != null)
                 SelfLog.WriteLine("Required properties not provided for: {0}", messageTemplate);
@@ -47,10 +51,14 @@ public EventProperty[] ConstructProperties(MessageTemplate messageTemplate, obje
         if (messageTemplate.PositionalProperties != null)
             return ConstructPositionalProperties(messageTemplate, messageTemplateParameters, messageTemplate.PositionalProperties);
 
-        return ConstructNamedProperties(messageTemplate, messageTemplateParameters!);
+        return ConstructNamedProperties(messageTemplate, messageTemplateParameters);
     }
 
+#if FEATURE_SPAN
+    EventProperty[] ConstructPositionalProperties(MessageTemplate template, ReadOnlySpan<object?> messageTemplateParameters, PropertyToken[] positionalProperties)
+#else
     EventProperty[] ConstructPositionalProperties(MessageTemplate template, object?[] messageTemplateParameters, PropertyToken[] positionalProperties)
+#endif
     {
         var result = new EventProperty[messageTemplateParameters.Length];
         foreach (var property in positionalProperties)
@@ -83,7 +91,11 @@ EventProperty[] ConstructPositionalProperties(MessageTemplate template, object?[
         return result;
     }
 
-    EventProperty[] ConstructNamedProperties(MessageTemplate template, object[] messageTemplateParameters)
+#if FEATURE_SPAN
+    EventProperty[] ConstructNamedProperties(MessageTemplate template, ReadOnlySpan<object?> messageTemplateParameters)
+#else
+    EventProperty[] ConstructNamedProperties(MessageTemplate template, object?[] messageTemplateParameters)
+#endif
     {
         var namedProperties = template.NamedProperties;
         if (namedProperties == null)

src/Serilog/Capturing/PropertyValueConverter.cs

@@ -22,10 +22,7 @@ partial class PropertyValueConverter : ILogEventPropertyFactory, ILogEventProper
 {
     static readonly HashSet<Type> BuiltInScalarTypes = new()
     {
-        typeof(bool),
-        typeof(char),
-        typeof(byte), typeof(short), typeof(ushort), typeof(int), typeof(uint),
-        typeof(long), typeof(ulong), typeof(float), typeof(double), typeof(decimal),
+        typeof(decimal),
         typeof(string),
         typeof(DateTime), typeof(DateTimeOffset), typeof(TimeSpan),
         typeof(Guid), typeof(Uri),
@@ -63,6 +60,7 @@ partial class PropertyValueConverter : ILogEventPropertyFactory, ILogEventProper
 
         _scalarConversionPolicies = new IScalarConversionPolicy[]
         {
+            new PrimitiveScalarConversionPolicy(),
             new SimpleScalarConversionPolicy(BuiltInScalarTypes.Concat(additionalScalarTypes)),
             new EnumScalarConversionPolicy(),
             new ByteArrayScalarConversionPolicy(),
@@ -272,7 +270,7 @@ bool TryConvertValueTuple(object value, Type type, Destructuring destructuring,
 
 #else
 
-    bool TryConvertValueTuple(object value, Type type, Destructuring destructuring, [NotNullWhen(true)] out LogEventPropertyValue? result)
+    bool TryConvertValueTuple(object value, [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicFields)] Type type, Destructuring destructuring, [NotNullWhen(true)] out LogEventPropertyValue? result)
     {
         if (!(value is IStructuralEquatable && type.IsConstructedGenericType))
         {
@@ -375,7 +373,8 @@ bool TryGetDictionary(object value, Type valueType, [NotNullWhen(true)] out IDic
 
     static bool IsValidDictionaryKeyType(Type valueType)
     {
-        return BuiltInScalarTypes.Contains(valueType) ||
+        return valueType.IsPrimitive ||
+               BuiltInScalarTypes.Contains(valueType) ||
                valueType.IsEnum;
     }