Merge pull request #51 from nblumhardt/json-safe-string

Introduce `JsonSafeString`

Author: nblumhardt

Build.ps1

@@ -21,9 +21,9 @@ foreach ($src in ls src/*) {
     echo "build: Packaging project in $src"
 
     if ($suffix) {
-        & dotnet pack -c Release -o ..\..\artifacts --version-suffix=$suffix --include-source
+        & dotnet pack -c Release -o ..\..\artifacts --version-suffix=$suffix
     } else {
-        & dotnet pack -c Release -o ..\..\artifacts --include-source
+        & dotnet pack -c Release -o ..\..\artifacts
     }
 
     if($LASTEXITCODE -ne 0) { exit 1 }    

README.md

@@ -105,6 +105,15 @@ In `appsettings.json` add a `"Seq"` property to `"Logging"` to configure the ser
 The logging provider will dynamically adjust the default logging level up or down based on the level associated with an API key in Seq. For further information see 
 the [Seq documentation](http://docs.datalust.co/docs/using-serilog#dynamic-level-control).
 
+### Including literal JSON strings in log events
+
+The logging provider ships with a `JsonSafeString` type that can be used to communicate to the logger that a string contains valid JSON, which can be safely included in a log event as structured data.
+
+```csharp
+var json = "{\"A\": 42}";
+_logger.LogInformation("The answer is {Answer}", new JsonSafeString(json));
+```
+
 ### Troubleshooting
 
 > Nothing showed up, what can I do?

seq-extensions-logging.sln

@@ -1,5 +1,4 @@
-
-Microsoft Visual Studio Solution File, Format Version 12.00
+Microsoft Visual Studio Solution File, Format Version 12.00
 # Visual Studio Version 16
 VisualStudioVersion = 16.0.29326.143
 MinimumVisualStudioVersion = 10.0.40219.1

seq-extensions-logging.sln.DotSettings

@@ -3,4 +3,5 @@
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=appsettings/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=Datalust/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=Enricher/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=Formattable/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=Serilog/@EntryIndexedValue">True</s:Boolean></wpf:ResourceDictionary>

src/Seq.Extensions.Logging/Seq.Extensions.Logging.csproj

@@ -14,9 +14,14 @@
     <PackageIcon>icon.png</PackageIcon>
     <PackageProjectUrl>https://github.com/datalust/seq-extensions-logging</PackageProjectUrl>
     <PackageLicenseExpression>Apache-2.0</PackageLicenseExpression>
+    <LangVersion>latest</LangVersion>
     <RootNamespace />
   </PropertyGroup>
 
+  <ItemGroup>
+    <PackageReference Include="Nullable" Version="1.3.1" PrivateAssets="All" />
+  </ItemGroup>
+    
   <ItemGroup Condition=" '$(TargetFramework)' == 'netstandard2.0' OR '$(TargetFramework)' == 'netstandard2.1' ">
     <PackageReference Include="Microsoft.Extensions.Logging" Version="3.1.22" />
     <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="3.1.22" />

src/Seq.Extensions.Logging/Seq/Extensions/Logging/JsonSafeString.cs

@@ -0,0 +1,30 @@
+#nullable enable
+
+namespace Seq.Extensions.Logging
+{
+    /// <summary>
+    /// A wrapper type that marks a string as containing valid JSON that's safe to include as-is in log events.
+    /// </summary>
+    public readonly struct JsonSafeString
+    {
+        string? Json { get; }
+
+        /// <summary>
+        /// Construct a <see cref="JsonSafeString"/> with well-formed JSON. The JSON is not validated: it must be
+        /// externally validated or proven to be valid JSON before calling this constructor.
+        /// </summary>
+        /// <param name="json">A well-formed JSON string that can be included directly in a log event.</param>
+        public JsonSafeString(string json)
+        {
+            Json = json;
+        }
+
+        /// <inheritdoc />
+        public override string ToString()
+        {
+            // As this type is a struct, it's impossible to enforce that `Json` is non-null. We use "<null>" instead
+            // of a literal JSON null, so that valid null values can be distinguished from invalid values.
+            return Json ?? "\"<null>\"";
+        }
+    }
+}

src/Seq.Extensions.Logging/Seq/Extensions/Logging/SelfLog.cs

@@ -25,25 +25,6 @@ public static class SelfLog
     {
         static Action<string> _output;
 
-        /// <summary>
-        /// The output mechanism for self-log messages.
-        /// </summary>
-        /// <example>
-        /// SelfLog.Out = Console.Error;
-        /// </example>
-        // ReSharper disable once MemberCanBePrivate.Global, UnusedAutoPropertyAccessor.Global
-        [Obsolete("Use SelfLog.Enable(value) and SelfLog.Disable() instead")]
-        public static TextWriter Out
-        {
-            set
-            {
-                if (value != null)
-                    Enable(value);
-                else
-                    Disable();
-            }
-        }
-
         /// <summary>
         /// Set the output mechanism for self-log messages.
         /// </summary>
@@ -68,8 +49,7 @@ public static void Enable(TextWriter output)
         /// // ReSharper disable once MemberCanBePrivate.Global
         public static void Enable(Action<string> output)
         {
-            if (output == null) throw new ArgumentNullException(nameof(output));
-            _output = output;
+            _output = output ?? throw new ArgumentNullException(nameof(output));
         }
 
         /// <summary>

src/Seq.Extensions.Logging/Serilog/Formatting/Compact/CompactJsonFormatter.cs

@@ -22,31 +22,8 @@
 
 namespace Serilog.Formatting.Compact
 {
-    class CompactJsonFormatter
+    static class CompactJsonFormatter
     {
-        readonly JsonValueFormatter _valueFormatter;
-
-        /// <summary>
-        /// Construct a <see cref="CompactJsonFormatter"/>, optionally supplying a formatter for
-        /// <see cref="LogEventPropertyValue"/>s on the event.
-        /// </summary>
-        /// <param name="valueFormatter">A value formatter, or null.</param>
-        public CompactJsonFormatter(JsonValueFormatter valueFormatter = null)
-        {
-            _valueFormatter = valueFormatter ?? new JsonValueFormatter(typeTagName: "$type");
-        }
-
-        /// <summary>
-        /// Format the log event into the output. Subsequent events will be newline-delimited.
-        /// </summary>
-        /// <param name="logEvent">The event to format.</param>
-        /// <param name="output">The output.</param>
-        public void Format(LogEvent logEvent, TextWriter output)
-        {
-            FormatEvent(logEvent, output, _valueFormatter);
-            output.WriteLine();
-        }
-
         /// <summary>
         /// Format the log event into the output.
         /// </summary>

src/Seq.Extensions.Logging/Serilog/Formatting/Json/JsonValueFormatter.cs

@@ -15,8 +15,10 @@
 using System;
 using System.Globalization;
 using System.IO;
+using Seq.Extensions.Logging;
 using Serilog.Data;
 using Serilog.Events;
+// ReSharper disable ForCanBeConvertedToForeach
 
 namespace Serilog.Formatting.Json
 {
@@ -152,7 +154,7 @@ protected override bool VisitDictionaryValue(TextWriter state, DictionaryValue d
         /// </summary>
         /// <param name="value">The value to write.</param>
         /// <param name="output">The output</param>
-        protected virtual void FormatLiteralValue(object value, TextWriter output)
+        static void FormatLiteralValue(object value, TextWriter output)
         {
             if (value == null)
             {
@@ -163,40 +165,38 @@ protected virtual void FormatLiteralValue(object value, TextWriter output)
             // Although the linear switch-on-type has apparently worse algorithmic performance than the O(1)
             // dictionary lookup alternative, in practice, it's much to make a few equality comparisons
             // than the hash/bucket dictionary lookup, and since most data will be string (one comparison),
-            // numeric (a handful) or an object (two comparsions) the real-world performance of the code
+            // numeric (a handful) or an object (two comparisons) the real-world performance of the code
             // as written is as fast or faster.
 
-            var str = value as string;
-            if (str != null)
+            if (value is string str)
             {
                 FormatStringValue(str, output);
                 return;
             }
 
             if (value is ValueType)
             {
-                if (value is int || value is uint || value is long || value is ulong || value is decimal ||
-                    value is byte || value is sbyte || value is short || value is ushort)
+                if (value is int or uint or long or ulong or decimal or byte or sbyte or short or ushort)
                 {
                     FormatExactNumericValue((IFormattable)value, output);
                     return;
                 }
 
-                if (value is double)
+                if (value is double d)
                 {
-                    FormatDoubleValue((double)value, output);
+                    FormatDoubleValue(d, output);
                     return;
                 }
 
-                if (value is float)
+                if (value is float f)
                 {
-                    FormatFloatValue((float)value, output);
+                    FormatFloatValue(f, output);
                     return;
                 }
 
-                if (value is bool)
+                if (value is bool b)
                 {
-                    FormatBooleanValue((bool)value, output);
+                    FormatBooleanValue(b, output);
                     return;
                 }
 
@@ -206,22 +206,33 @@ protected virtual void FormatLiteralValue(object value, TextWriter output)
                     return;
                 }
 
-                if (value is DateTime || value is DateTimeOffset)
+                if (value is DateTime or DateTimeOffset)
                 {
                     FormatDateTimeValue((IFormattable)value, output);
                     return;
                 }
 
-                if (value is TimeSpan)
+                if (value is TimeSpan span)
                 {
-                    FormatTimeSpanValue((TimeSpan)value, output);
+                    FormatTimeSpanValue(span, output);
                     return;
                 }
             }
 
+            if (value is JsonSafeString jss)
+            {
+                FormatJsonSafeString(jss, output);
+                return;
+            }
+
             FormatLiteralObjectValue(value, output);
         }
 
+        static void FormatJsonSafeString(JsonSafeString jss, TextWriter output)
+        {
+            output.Write(jss.ToString());
+        }
+
         static void FormatBooleanValue(bool value, TextWriter output)
         {
             output.Write(value ? "true" : "false");

src/Seq.Extensions.Logging/Serilog/Parameters/PropertyValueConverter.cs

@@ -32,7 +32,7 @@ namespace Serilog.Parameters
     // writing a log event (roughly) in control of the cost of recording that event.
     partial class PropertyValueConverter : ILogEventPropertyFactory, ILogEventPropertyValueFactory
     {
-        static readonly HashSet<Type> BuiltInScalarTypes = new HashSet<Type>
+        readonly HashSet<Type> _builtInScalarTypes = new()
         {
             typeof(bool),
             typeof(char),
@@ -43,6 +43,11 @@ partial class PropertyValueConverter : ILogEventPropertyFactory, ILogEventProper
             typeof(Guid), typeof(Uri)
         };
 
+        static IEnumerable<Type> SeqExtensionsLoggingScalarTypes() => new[]
+        {
+            typeof(JsonSafeString)
+        };
+
         readonly IDestructuringPolicy[] _destructuringPolicies;
         readonly IScalarConversionPolicy[] _scalarConversionPolicies;
         readonly int _maximumDestructuringDepth;
@@ -62,7 +67,7 @@ public PropertyValueConverter(
 
             _scalarConversionPolicies = new IScalarConversionPolicy[]
             {
-                new SimpleScalarConversionPolicy(BuiltInScalarTypes),
+                new SimpleScalarConversionPolicy(_builtInScalarTypes.Concat(SeqExtensionsLoggingScalarTypes())),
                 new NullableScalarConversionPolicy(),
                 new EnumScalarConversionPolicy(),
                 new ByteArrayScalarConversionPolicy(),
@@ -220,7 +225,7 @@ bool IsValueTypeDictionary(Type valueType)
 
         bool IsValidDictionaryKeyType(Type valueType)
         {
-            return BuiltInScalarTypes.Contains(valueType) ||
+            return _builtInScalarTypes.Contains(valueType) ||
                    valueType.GetTypeInfo().IsEnum;
         }
 
@@ -247,14 +252,14 @@ IEnumerable<LogEventProperty> GetProperties(object value, ILogEventPropertyValue
                     if (_propagateExceptions)
                         throw;
 
-                    propValue = "The property accessor threw an exception: " + ex.InnerException.GetType().Name;
+                    propValue = "The property accessor threw an exception: " + ex.InnerException?.GetType().Name;
                 }
                 yield return new LogEventProperty(prop.Name, recursive.CreatePropertyValue(propValue, true));
             }
         }
 
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        internal static bool IsCompilerGeneratedType(Type type)
+        static bool IsCompilerGeneratedType(Type type)
         {
             var typeInfo = type.GetTypeInfo();
             var typeName = type.Name;
@@ -266,4 +271,3 @@ internal static bool IsCompilerGeneratedType(Type type)
         }
     }
 }
-