Merge branch 'bugfix/null-value' into main

Author: 0xced

CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.0][1.4.0] - 2025-09-19
+
+- Properties whose values are `null` are now always serialized with a `value` attribute. Thanks to @southernprogrammer for reporting this issue. See the [Null text](https://github.com/serilog-contrib/serilog-formatting-log4net#null-text) documentation in the README for more information.
+
+Before (1.3.1)
+
+```xml
+<log4net:properties>
+  <log4net:data name="key" />
+</log4net:properties>
+```
+
+After (1.4.0)
+
+```xml
+<log4net:properties>
+  <log4net:data name="key" value="(null)" />
+</log4net:properties>
+```
+
 ## [1.3.1][1.3.1] - 2025-04-30
 
 - Log events coming from `Microsoft.Extensions.Logging` are now identified if they have **either** an `EventId.Id` or an `EventId.Name` property. Previously, log events coming from `Microsoft.Extensions.Logging` were identified if they had **both** an `Id` and a `Name` property.
@@ -139,7 +159,8 @@ Still trying to figure out how to make everything fit together with [MinVer](htt
 
 - Implement log4j compatibility mode.
 
-[Unreleased]: https://github.com/serilog-contrib/serilog-formatting-log4net/compare/1.3.1...HEAD
+[Unreleased]: https://github.com/serilog-contrib/serilog-formatting-log4net/compare/1.4.0...HEAD
+[1.4.0]: https://github.com/serilog-contrib/serilog-formatting-log4net/compare/1.3.1...1.4.0
 [1.3.1]: https://github.com/serilog-contrib/serilog-formatting-log4net/compare/1.3.0...1.3.1
 [1.3.0]: https://github.com/serilog-contrib/serilog-formatting-log4net/compare/1.2.0...1.3.0
 [1.2.0]: https://github.com/serilog-contrib/serilog-formatting-log4net/compare/1.1.0...1.2.0

README.md

@@ -106,6 +106,28 @@ By default, Log4NetTextFormatter writes all messages and exceptions with a [CDAT
 new Log4NetTextFormatter(c => c.UseCDataMode(CDataMode.Never))
 ```
 
+### Null text
+
+Available since version 1.4.0
+
+By default, when a property value is `null`, the text used for its representation is `(null)`. This can be changed with the `UseNullText()` configuration method.
+
+Here's how to configure the formatter to use `🔷null🔷` when a property value is `null`.
+
+```c#
+new Log4NetTextFormatter(c => c.UseNullText("🔷null🔷"));
+```
+
+This will produce the following output.
+
+```xml
+<log4net:properties>
+  <log4net:data name="key" value="🔷null🔷" />
+</log4net:properties>
+```
+
+To restore compatibility with version 1.3.1 and earlier (which produced a non-compatible XML), `UseNullText(null)` can be called.
+
 ### XML Namespace
 
 You can remove the `log4net` XML namespace by calling `UseNoXmlNamespace()` on the options builder. This is useful if you want to spare some bytes and your log reader supports log4net XML events without namespace, like [Log4View](https://www.log4view.com) does.

src/Log4NetTextFormatter.cs

@@ -406,11 +406,14 @@ private void WritePropertyElement(XmlWriter writer, string name, LogEventPropert
     {
         WriteStartElement(writer, "data");
         writer.WriteAttributeString("name", name);
-        var isNullValue = value is ScalarValue { Value: null };
-        if (!isNullValue)
+        if (value is not ScalarValue { Value: null })
         {
             writer.WriteAttributeString("value", RenderValue(value));
         }
+        else if (_options.NullText != null)
+        {
+            writer.WriteAttributeString("value", _options.NullText);
+        }
         writer.WriteEndElement();
     }
 

src/Log4NetTextFormatterOptions.cs

@@ -8,10 +8,11 @@ namespace Serilog.Formatting.Log4Net;
 /// </summary>
 internal sealed class Log4NetTextFormatterOptions
 {
-    internal Log4NetTextFormatterOptions(IFormatProvider? formatProvider, CDataMode cDataMode, XmlQualifiedName? xmlNamespace, XmlWriterSettings xmlWriterSettings, PropertyFilter filterProperty, MessageFormatter formatMessage, ExceptionFormatter formatException)
+    internal Log4NetTextFormatterOptions(IFormatProvider? formatProvider, CDataMode cDataMode, string? nullText, XmlQualifiedName? xmlNamespace, XmlWriterSettings xmlWriterSettings, PropertyFilter filterProperty, MessageFormatter formatMessage, ExceptionFormatter formatException)
     {
         FormatProvider = formatProvider;
         CDataMode = cDataMode;
+        NullText = nullText;
         XmlNamespace = xmlNamespace;
         XmlWriterSettings = xmlWriterSettings;
         FilterProperty = filterProperty;
@@ -25,6 +26,9 @@ internal Log4NetTextFormatterOptions(IFormatProvider? formatProvider, CDataMode
     /// <summary>See <see cref="Log4NetTextFormatterOptionsBuilder.UseCDataMode"/></summary>
     internal CDataMode CDataMode { get; }
 
+    /// <summary>See <see cref="Log4NetTextFormatterOptionsBuilder.UseNullText"/></summary>
+    internal string? NullText { get; }
+
     /// <summary>See <see cref="Log4NetTextFormatterOptionsBuilder.UseNoXmlNamespace"/></summary>
     internal XmlQualifiedName? XmlNamespace { get; }
 

src/Log4NetTextFormatterOptionsBuilder.cs

@@ -31,9 +31,12 @@ internal Log4NetTextFormatterOptionsBuilder()
     /// <summary>See <see cref="UseFormatProvider"/></summary>
     private IFormatProvider? _formatProvider;
 
-    /// <summary> See <see cref="UseCDataMode"/></summary>
+    /// <summary>See <see cref="UseCDataMode"/></summary>
     private CDataMode _cDataMode = CDataMode.Always;
 
+    /// <summary>See <see cref="UseNullText"/></summary>
+    private string? _nullText = "(null)";
+
     /// <summary>See <see cref="UseNoXmlNamespace"/></summary>
     private XmlQualifiedName? _xmlNamespace = Log4NetXmlNamespace;
 
@@ -78,6 +81,23 @@ public Log4NetTextFormatterOptionsBuilder UseCDataMode(CDataMode cDataMode)
         return this;
     }
 
+    /// <summary>
+    /// Sets how <see langword="null"/> properties are rendered as textual representation inside XML attributes.
+    /// <para/>
+    /// The default value is <c>(null)</c>.
+    /// </summary>
+    /// <param name="nullText">The text to use to represent <see langword="null"/> properties.</param>
+    /// <returns>The builder in order to fluently chain all options.</returns>
+    /// <remarks>
+    /// Pass <see langword="null"/> for <paramref name="nullText"/> to omit the <c>value</c> attribute, i.e. <code>&lt;log4net:data name="MiddleName" /&gt;</code>
+    /// Note that this is not strictly compatible with log4net/log4j XML formats and should be used to keep compatibility with Serilog.Formatting.Log4Net 1.3.1 and earlier if needed.
+    /// </remarks>
+    public Log4NetTextFormatterOptionsBuilder UseNullText(string? nullText)
+    {
+        _nullText = nullText;
+        return this;
+    }
+
     /// <summary>
     /// Do not use any XML namespace for log4net events.
     /// <para/>
@@ -197,7 +217,7 @@ public void UseLog4JCompatibility()
     }
 
     internal Log4NetTextFormatterOptions Build()
-        => new(_formatProvider, _cDataMode, _xmlNamespace, CreateXmlWriterSettings(_lineEnding, _indentationSettings), _filterProperty, _formatMessage, _formatException);
+        => new(_formatProvider, _cDataMode, _nullText, _xmlNamespace, CreateXmlWriterSettings(_lineEnding, _indentationSettings), _filterProperty, _formatMessage, _formatException);
 
     private static XmlWriterSettings CreateXmlWriterSettings(LineEnding lineEnding, IndentationSettings? indentationSettings)
     {

tests/Log4NetTextFormatterTest.DefaultMessageFormatter_eventId=1_eventIdName=EventName.verified.xml

@@ -3,7 +3,7 @@
     <log4net:data name="Name" value="World" />
     <log4net:data name="EventId.Id" value="1" />
     <log4net:data name="EventId.Name" value="EventName" />
-    <log4net:data name="EventId.More" />
+    <log4net:data name="EventId.More" value="(null)" />
   </log4net:properties>
   <log4net:message><![CDATA[Hello World!]]></log4net:message>
 </log4net:event>

tests/Log4NetTextFormatterTest.NullProperty_nullText=-null-.verified.xml

@@ -0,0 +1,6 @@
+<log4net:event timestamp="2003-01-04T15:09:26.535+01:00" level="INFO" xmlns:log4net="http://logging.apache.org/log4net/schemas/log4net-events-1.2/">
+  <log4net:properties>
+    <log4net:data name="n/a" value="&lt;null&gt;" />
+  </log4net:properties>
+  <log4net:message><![CDATA[Hello from Serilog]]></log4net:message>
+</log4net:event>

tests/Log4NetTextFormatterTest.NullProperty_nullText=.verified.xml

@@ -0,0 +1,6 @@
+<log4net:event timestamp="2003-01-04T15:09:26.535+01:00" level="INFO" xmlns:log4net="http://logging.apache.org/log4net/schemas/log4net-events-1.2/">
+  <log4net:properties>
+    <log4net:data name="n/a" value="" />
+  </log4net:properties>
+  <log4net:message><![CDATA[Hello from Serilog]]></log4net:message>
+</log4net:event>

tests/Log4NetTextFormatterTest.NullProperty_nullText=_DEFAULT_.verified.xml

@@ -0,0 +1,6 @@
+<log4net:event timestamp="2003-01-04T15:09:26.535+01:00" level="INFO" xmlns:log4net="http://logging.apache.org/log4net/schemas/log4net-events-1.2/">
+  <log4net:properties>
+    <log4net:data name="n/a" value="(null)" />
+  </log4net:properties>
+  <log4net:message><![CDATA[Hello from Serilog]]></log4net:message>
+</log4net:event>

tests/Log4NetTextFormatterTest.NullProperty.verified.xml renamed to tests/Log4NetTextFormatterTest.NullProperty_nullText=null.verified.xml

@@ -1,4 +1,4 @@
-<log4net:event timestamp="2003-01-04T15:09:26.535+01:00" level="INFO" xmlns:log4net="http://logging.apache.org/log4net/schemas/log4net-events-1.2/">
+<log4net:event timestamp="2003-01-04T15:09:26.535+01:00" level="INFO" xmlns:log4net="http://logging.apache.org/log4net/schemas/log4net-events-1.2/">
   <log4net:properties>
     <log4net:data name="n/a" />
   </log4net:properties>