cleanup

Author: pwelter34

README.md

@@ -206,6 +206,121 @@ The sink includes the following standard column mappings:
 | `Properties`    | `string`         | Additional properties as JSON            | Yes      | MAX  |
 | `SourceContext` | `string`         | Source context (typically class name)    | Yes      | 1000 |
 
+### JSON Structure for Exception and Properties
+
+#### Exception Column
+
+The `Exception` column stores exception details as a JSON object with the following structure:
+
+```json
+{
+  "Message": "The error message",
+  "BaseMessage": "Inner exception message (if present)",
+  "Type": "System.InvalidOperationException",
+  "Text": "Full exception text including stack trace",
+  "HResult": -2146233079,
+  "ErrorCode": -2147467259,
+  "Source": "MyApplication",
+  "MethodName": "MyMethod",
+  "ModuleName": "MyAssembly",
+  "ModuleVersion": "1.0.0.0"
+}
+```
+
+**Key fields:**
+
+- `Message` - The exception's primary error message
+- `BaseMessage` - Message from the innermost exception (if there's an inner exception chain)
+- `Type` - Fully qualified type name of the exception
+- `Text` - Complete exception text including stack trace (from `ToString()`)
+- `HResult` - The HRESULT error code
+- `ErrorCode` - Error code for `ExternalException` types
+- `Source` - The application or object that caused the error
+- `MethodName` - Name of the method that threw the exception
+- `ModuleName` - Name of the assembly containing the throwing method
+- `ModuleVersion` - Version of the assembly
+
+> **Note:** Aggregate exceptions with a single inner exception are automatically flattened to the inner exception.
+
+#### Properties Column
+
+The `Properties` column stores log event properties as a JSON object. Property values are serialized according to their type:
+
+**Scalar values:**
+
+```json
+{
+  "UserId": 123,
+  "UserName": "John Doe",
+  "IsActive": true,
+  "Amount": 99.99,
+  "RequestId": "550e8400-e29b-41d4-a716-446655440000",
+  "Timestamp": "2024-01-15T10:30:45Z"
+}
+```
+
+**Structured values:**
+
+```json
+{
+  "User": {
+    "Id": 123,
+    "Name": "John Doe",
+    "Email": "[email protected]"
+  }
+}
+```
+
+**Arrays/Sequences:**
+
+```json
+{
+  "Roles": ["Admin", "User", "Manager"],
+  "Numbers": [1, 2, 3, 4, 5]
+}
+```
+
+**Dictionaries:**
+
+```json
+{
+  "Headers": {
+    "Content-Type": "application/json",
+    "Authorization": "Bearer token"
+  }
+}
+```
+
+**Complex nested structures:**
+
+```json
+{
+  "Request": {
+    "Method": "POST",
+    "Path": "/api/users",
+    "Headers": {
+      "Content-Type": "application/json",
+      "User-Agent": "MyApp/1.0"
+    },
+    "Body": {
+      "Users": [
+        { "Id": 1, "Name": "Alice" },
+        { "Id": 2, "Name": "Bob" }
+      ]
+    }
+  }
+}
+```
+
+**Supported scalar types:**
+
+- Primitive types: `string`, `bool`, `int`, `long`, `double`, `float`, `decimal`, `byte`, `short`, etc.
+- Date/time types: `DateTime`, `DateTimeOffset`, `TimeSpan`, `DateOnly`, `TimeOnly` (as ISO strings)
+- Other types: `Guid` (as string), `Enum` (as string), `BigInteger` (as string), `char` (as string)
+- `null` values are preserved
+
+> **Note:** By default, properties enriched via `FromLogContext()` or `WithProperty()` are included in this column. You can extract specific properties to dedicated columns using custom mappings (see below).
+
 ### Custom Property Mappings
 
 Add custom property mappings to log additional data:

src/Directory.Build.props

@@ -1,18 +1,18 @@
 <Project>
 
   <PropertyGroup Label="Package">
-    <Description>A high-performance Serilog sink that writes log events to MongoDB</Description>
+    <Description>A high-performance Serilog sink that writes log events to SQL Server</Description>
     <Copyright>Copyright © $([System.DateTime]::Now.ToString(yyyy)) LoreSoft</Copyright>
     <Authors>LoreSoft</Authors>
     <NeutralLanguage>en-US</NeutralLanguage>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
-    <PackageTags>serilog;logging;mongodb</PackageTags>
-    <PackageProjectUrl>https://github.com/loresoft/serilog-sinks-mongo</PackageProjectUrl>
+    <PackageTags>serilog;logging;sqlserver</PackageTags>
+    <PackageProjectUrl>https://github.com/loresoft/serilog-sinks-sqlserver</PackageProjectUrl>
     <PackageLicenseExpression>MIT</PackageLicenseExpression>
     <PackageIcon>logo.png</PackageIcon>
     <PackageReadmeFile>README.md</PackageReadmeFile>
     <RepositoryType>git</RepositoryType>
-    <RepositoryUrl>https://github.com/loresoft/serilog-sinks-mongo</RepositoryUrl>
+    <RepositoryUrl>https://github.com/loresoft/serilog-sinks-sqlserver</RepositoryUrl>
     <PublishRepositoryUrl>true</PublishRepositoryUrl>
   </PropertyGroup>
 

src/Serilog.Sinks.SqlServer/ColumnMapping.cs

@@ -1,5 +1,14 @@
 namespace Serilog.Sinks.SqlServer;
 
+/// <summary>
+/// Represents the mapping configuration for a database column.
+/// </summary>
+/// <typeparam name="T">The type of the source object to map from.</typeparam>
+/// <param name="ColumnName">The name of the database column.</param>
+/// <param name="ColumnType">The data type of the database column.</param>
+/// <param name="GetValue">A function that extracts the value from the source object.</param>
+/// <param name="Nullable">Indicates whether the column allows null values. Default is <c>true</c>.</param>
+/// <param name="Size">The optional size constraint for the column (e.g., varchar length).</param>
 public record ColumnMapping<T>
 (
     string ColumnName,

src/Serilog.Sinks.SqlServer/JsonWriter.cs

@@ -8,8 +8,20 @@
 
 namespace Serilog.Sinks.SqlServer;
 
+/// <summary>
+/// Provides utility methods for writing Serilog log event data to JSON format.
+/// </summary>
 public static class JsonWriter
 {
+    /// <summary>
+    /// Writes an exception to a JSON string representation.
+    /// </summary>
+    /// <param name="exception">The exception to serialize. Can be null.</param>
+    /// <returns>A JSON string containing exception details, or null if the exception is null.</returns>
+    /// <remarks>
+    /// The JSON output includes the exception message, type, full text, error codes, source, and method information.
+    /// Aggregate exceptions with a single inner exception are automatically flattened.
+    /// </remarks>
     public static string? WriteException(Exception? exception)
     {
         if (exception == null)
@@ -77,6 +89,12 @@ public static class JsonWriter
 
     }
 
+    /// <summary>
+    /// Writes a collection of log event properties to a JSON string representation.
+    /// </summary>
+    /// <param name="properties">The dictionary of log event properties to serialize. Can be null or empty.</param>
+    /// <param name="ignored">An optional set of property names to exclude from the output.</param>
+    /// <returns>A JSON string containing the properties, or null if there are no properties to write or all properties are ignored.</returns>
     public static string? WriteProperties(IReadOnlyDictionary<string, LogEventPropertyValue>? properties, HashSet<string>? ignored = null)
     {
         // no properties to write
@@ -117,6 +135,11 @@ public static class JsonWriter
 #endif
     }
 
+    /// <summary>
+    /// Writes a single log event property value to a JSON string representation.
+    /// </summary>
+    /// <param name="value">The log event property value to serialize. Can be null.</param>
+    /// <returns>A JSON string containing the property value, or null if the value is null.</returns>
     public static string? WritePropertyValue(LogEventPropertyValue value)
     {
         if (value == null)
@@ -141,8 +164,15 @@ public static class JsonWriter
 #endif
     }
 
-
-    public static void WritePropertyValue(Utf8JsonWriter writer, LogEventPropertyValue value)
+    /// <summary>
+    /// Writes a log event property value to the specified JSON writer.
+    /// </summary>
+    /// <param name="writer">The UTF-8 JSON writer to write to.</param>
+    /// <param name="value">The log event property value to write.</param>
+    /// <remarks>
+    /// Handles scalar values, sequences, structures, and dictionaries appropriately.
+    /// </remarks>
+    private static void WritePropertyValue(Utf8JsonWriter writer, LogEventPropertyValue value)
     {
         if (value is ScalarValue scalarValue)
             WriteScalarValue(writer, scalarValue);
@@ -156,7 +186,12 @@ public static void WritePropertyValue(Utf8JsonWriter writer, LogEventPropertyVal
             writer.WriteStringValue(value.ToString());
     }
 
-    public static void WriteDictionaryValue(Utf8JsonWriter writer, DictionaryValue dictionaryValue)
+    /// <summary>
+    /// Writes a dictionary value to the specified JSON writer as a JSON object.
+    /// </summary>
+    /// <param name="writer">The UTF-8 JSON writer to write to.</param>
+    /// <param name="dictionaryValue">The dictionary value to write.</param>
+    private static void WriteDictionaryValue(Utf8JsonWriter writer, DictionaryValue dictionaryValue)
     {
         writer.WriteStartObject();
         foreach (var kvp in dictionaryValue.Elements)
@@ -170,7 +205,12 @@ public static void WriteDictionaryValue(Utf8JsonWriter writer, DictionaryValue d
         writer.WriteEndObject();
     }
 
-    public static void WriteStructureValue(Utf8JsonWriter writer, StructureValue structureValue)
+    /// <summary>
+    /// Writes a structure value to the specified JSON writer as a JSON object.
+    /// </summary>
+    /// <param name="writer">The UTF-8 JSON writer to write to.</param>
+    /// <param name="structureValue">The structure value to write.</param>
+    private static void WriteStructureValue(Utf8JsonWriter writer, StructureValue structureValue)
     {
         writer.WriteStartObject();
         foreach (var prop in structureValue.Properties)
@@ -181,7 +221,12 @@ public static void WriteStructureValue(Utf8JsonWriter writer, StructureValue str
         writer.WriteEndObject();
     }
 
-    public static void WriteSequenceValue(Utf8JsonWriter writer, SequenceValue sequenceValue)
+    /// <summary>
+    /// Writes a sequence value to the specified JSON writer as a JSON array.
+    /// </summary>
+    /// <param name="writer">The UTF-8 JSON writer to write to.</param>
+    /// <param name="sequenceValue">The sequence value to write.</param>
+    private static void WriteSequenceValue(Utf8JsonWriter writer, SequenceValue sequenceValue)
     {
         writer.WriteStartArray();
         foreach (var item in sequenceValue.Elements)
@@ -191,7 +236,15 @@ public static void WriteSequenceValue(Utf8JsonWriter writer, SequenceValue seque
         writer.WriteEndArray();
     }
 
-    public static void WriteScalarValue(Utf8JsonWriter writer, ScalarValue scalarValue)
+    /// <summary>
+    /// Writes a scalar value to the specified JSON writer with appropriate JSON typing.
+    /// </summary>
+    /// <param name="writer">The UTF-8 JSON writer to write to.</param>
+    /// <param name="scalarValue">The scalar value to write.</param>
+    /// <remarks>
+    /// Handles all primitive types, date/time types, numeric types, and falls back to JSON serialization for unknown types.
+    /// </remarks>
+    private static void WriteScalarValue(Utf8JsonWriter writer, ScalarValue scalarValue)
     {
         if (scalarValue.Value == null)
         {

src/Serilog.Sinks.SqlServer/ListDataReader.cs

@@ -2,13 +2,27 @@
 
 namespace Serilog.Sinks.SqlServer;
 
+/// <summary>
+/// Provides an <see cref="IDataReader"/> implementation for reading a list of items with configurable column mappings.
+/// </summary>
+/// <typeparam name="T">The type of items to read.</typeparam>
+/// <remarks>
+/// This class enables bulk insert operations by wrapping an enumerable collection and exposing it through the IDataReader interface.
+/// Column mappings are defined through the <see cref="MappingContext{T}"/> which specifies how to extract values from each item.
+/// </remarks>
 public class ListDataReader<T> : IDataReader
 {
     private readonly IEnumerator<T> _iterator;
     private readonly MappingContext<T> _mappingContext;
 
     private bool _disposed;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ListDataReader{T}"/> class.
+    /// </summary>
+    /// <param name="logEvents">The collection of items to read.</param>
+    /// <param name="mappingContext">The mapping context that defines how to map items to columns.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="logEvents"/> or <paramref name="mappingContext"/> is null.</exception>
     public ListDataReader(
         IEnumerable<T> logEvents,
         MappingContext<T> mappingContext)
@@ -54,6 +68,10 @@ public void Dispose()
         GC.SuppressFinalize(this);
     }
 
+    /// <summary>
+    /// Releases the resources used by the <see cref="ListDataReader{T}"/>.
+    /// </summary>
+    /// <param name="disposing"><c>true</c> to release both managed and unmanaged resources; <c>false</c> to release only unmanaged resources.</param>
     protected virtual void Dispose(bool disposing)
     {
         if (_disposed)
@@ -98,7 +116,15 @@ public Type GetFieldType(int i)
         return columnMapping.ColumnType;
     }
 
-    /// <inheritdoc/>
+    /// <summary>
+    /// Gets the value of the specified column in its native format.
+    /// </summary>
+    /// <param name="i">The zero-based column ordinal.</param>
+    /// <returns>The value of the specified column, or <see cref="DBNull.Value"/> if the value is null.</returns>
+    /// <exception cref="IndexOutOfRangeException">Thrown when no column mapping is found for the specified ordinal.</exception>
+    /// <remarks>
+    /// String values that exceed the column's defined size are automatically truncated to fit the maximum length.
+    /// </remarks>
     public object GetValue(int i)
     {
         var columnMapping = _mappingContext.GetMapping(i);

src/Serilog.Sinks.SqlServer/LogEventExtensions.cs

@@ -2,8 +2,25 @@
 
 namespace Serilog.Sinks.SqlServer;
 
+/// <summary>
+/// Provides extension methods for <see cref="LogEvent"/> to simplify property value extraction.
+/// </summary>
 public static class LogEventExtensions
 {
+    /// <summary>
+    /// Gets the value of a specified property from the log event.
+    /// </summary>
+    /// <param name="logEvent">The log event to extract the property from.</param>
+    /// <param name="propertyName">The name of the property to retrieve.</param>
+    /// <returns>
+    /// The underlying value if the property is a <see cref="ScalarValue"/>, 
+    /// a JSON string representation for complex types (sequences, structures, dictionaries),
+    /// or <c>null</c> if the log event is null, the property name is empty, or the property does not exist.
+    /// </returns>
+    /// <remarks>
+    /// Scalar values are returned directly as their underlying type. 
+    /// Complex property types (sequences, structures, dictionaries) are serialized to JSON strings.
+    /// </remarks>
     public static object? GetPropertyValue(this LogEvent logEvent, string propertyName)
     {
         if (logEvent == null || string.IsNullOrEmpty(propertyName))