Always write the value XML attributes in properties, even when the value is null

0xced · 0xced · commit 8f59f06c70b8 · 2025-06-16T11:06:37.000+02:00
Also make the null text configurable through a new `UseNullText()` method on the options builder. The default null text value is `(null)` in order to match the log4net behavior. Fixes #287
diff --git a/src/Log4NetTextFormatter.cs b/src/Log4NetTextFormatter.cs
@@ -407,10 +407,7 @@ private void WritePropertyElement(XmlWriter writer, string name, LogEventPropert
         WriteStartElement(writer, "data");
         writer.WriteAttributeString("name", name);
         var isNullValue = value is ScalarValue { Value: null };
-        if (!isNullValue)
-        {
-            writer.WriteAttributeString("value", RenderValue(value));
-        }
+        writer.WriteAttributeString("value", isNullValue ? _options.NullText : RenderValue(value));
         writer.WriteEndElement();
     }
 
diff --git a/src/Log4NetTextFormatterOptions.cs b/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; }
 
diff --git a/src/Log4NetTextFormatterOptionsBuilder.cs b/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,19 @@ 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>
+    public Log4NetTextFormatterOptionsBuilder UseNullText(string nullText)
+    {
+        _nullText = nullText ?? throw new ArgumentNullException(nameof(nullText), "The null text can not be null.");
+        return this;
+    }
+
     /// <summary>
     /// Do not use any XML namespace for log4net events.
     /// <para/>
@@ -197,7 +213,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)
     {
diff --git a/tests/Log4NetTextFormatterTest.DefaultMessageFormatter_eventId=1_eventIdName=EventName.verified.xml b/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>
diff --git a/tests/Log4NetTextFormatterTest.NullProperty.verified.xml b/tests/Log4NetTextFormatterTest.NullProperty.verified.xml
diff --git a/tests/Log4NetTextFormatterTest.NullProperty_nullText=-null-.verified.xml b/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>
diff --git a/tests/Log4NetTextFormatterTest.NullProperty_nullText=.verified.xml b/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>
diff --git a/tests/Log4NetTextFormatterTest.NullProperty_nullText=null.verified.xml b/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="(null)" />
+  </log4net:properties>
+  <log4net:message><![CDATA[Hello from Serilog]]></log4net:message>
+</log4net:event>
diff --git a/tests/Log4NetTextFormatterTest.NullProperty_nullText=🌀.verified.xml b/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>
diff --git a/tests/Log4NetTextFormatterTest.TwoPropertiesOneNull.verified.xml b/tests/Log4NetTextFormatterTest.TwoPropertiesOneNull.verified.xml
@@ -1,6 +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" />
+    <log4net:data name="n/a" value="(null)" />
     <log4net:data name="one" value="1" />
   </log4net:properties>
   <log4net:message><![CDATA[Hello from Serilog]]></log4net:message>
diff --git a/tests/Log4NetTextFormatterTest.cs b/tests/Log4NetTextFormatterTest.cs
@@ -82,6 +82,18 @@ public void NullOutputThrowsArgumentNullException()
             .Which.StackTrace!.TrimStart().Should().StartWith("at Serilog.Formatting.Log4Net.Log4NetTextFormatter.Format");
     }
 
+    [Fact]
+    public void SettingNullTextToNullThrowsArgumentNullException()
+    {
+        // Act
+        Action action = () => _ = new Log4NetTextFormatter(c => c.UseNullText(null!));
+
+        // Assert
+        action.Should().ThrowExactly<ArgumentNullException>()
+            .WithMessage("The null text can not be null.*")
+            .And.ParamName.Should().Be("nullText");
+    }
+
     [Fact]
     public void SettingPropertyFilterToNullThrowsArgumentNullException()
     {
@@ -243,19 +255,23 @@ public Task NoNamespace()
         return Verify(output);
     }
 
-    [Fact]
-    public Task NullProperty()
+    [Theory]
+    [InlineData(null)]
+    [InlineData("")]
+    [InlineData("<null>")]
+    [InlineData("🌀")]
+    public Task NullProperty(string? nullText)
     {
         // Arrange
         using var output = new StringWriter();
         var logEvent = CreateLogEvent(properties: new LogEventProperty("n/a", new ScalarValue(null)));
-        var formatter = new Log4NetTextFormatter();
+        var formatter = new Log4NetTextFormatter(options => { if (nullText != null) { options.UseNullText(nullText); } });
 
         // Act
         formatter.Format(logEvent, output);
 
         // Assert
-        return Verify(output);
+        return Verify(output).UseParameters(nullText);
     }
 
     [Fact]
diff --git a/tests/PublicApi.net6.0.verified.cs b/tests/PublicApi.net6.0.verified.cs
@@ -45,6 +45,7 @@ public void UseLog4JCompatibility() { }
         public Serilog.Formatting.Log4Net.Log4NetTextFormatterOptionsBuilder UseMessageFormatter(Serilog.Formatting.Log4Net.MessageFormatter formatMessage) { }
         public Serilog.Formatting.Log4Net.Log4NetTextFormatterOptionsBuilder UseNoIndentation() { }
         public Serilog.Formatting.Log4Net.Log4NetTextFormatterOptionsBuilder UseNoXmlNamespace() { }
+        public Serilog.Formatting.Log4Net.Log4NetTextFormatterOptionsBuilder UseNullText(string nullText) { }
         public Serilog.Formatting.Log4Net.Log4NetTextFormatterOptionsBuilder UsePropertyFilter(Serilog.Formatting.Log4Net.PropertyFilter filterProperty) { }
     }
     public delegate string MessageFormatter(Serilog.Events.LogEvent logEvent, System.IFormatProvider? formatProvider);
diff --git a/tests/PublicApi.net8.0.verified.cs b/tests/PublicApi.net8.0.verified.cs
@@ -46,6 +46,7 @@ public void UseLog4JCompatibility() { }
         public Serilog.Formatting.Log4Net.Log4NetTextFormatterOptionsBuilder UseMessageFormatter(Serilog.Formatting.Log4Net.MessageFormatter formatMessage) { }
         public Serilog.Formatting.Log4Net.Log4NetTextFormatterOptionsBuilder UseNoIndentation() { }
         public Serilog.Formatting.Log4Net.Log4NetTextFormatterOptionsBuilder UseNoXmlNamespace() { }
+        public Serilog.Formatting.Log4Net.Log4NetTextFormatterOptionsBuilder UseNullText(string nullText) { }
         public Serilog.Formatting.Log4Net.Log4NetTextFormatterOptionsBuilder UsePropertyFilter(Serilog.Formatting.Log4Net.PropertyFilter filterProperty) { }
     }
     public delegate string MessageFormatter(Serilog.Events.LogEvent logEvent, System.IFormatProvider? formatProvider);
diff --git a/tests/PublicApi.netstandard2.0.verified.cs b/tests/PublicApi.netstandard2.0.verified.cs
@@ -45,6 +45,7 @@ public void UseLog4JCompatibility() { }
         public Serilog.Formatting.Log4Net.Log4NetTextFormatterOptionsBuilder UseMessageFormatter(Serilog.Formatting.Log4Net.MessageFormatter formatMessage) { }
         public Serilog.Formatting.Log4Net.Log4NetTextFormatterOptionsBuilder UseNoIndentation() { }
         public Serilog.Formatting.Log4Net.Log4NetTextFormatterOptionsBuilder UseNoXmlNamespace() { }
+        public Serilog.Formatting.Log4Net.Log4NetTextFormatterOptionsBuilder UseNullText(string nullText) { }
         public Serilog.Formatting.Log4Net.Log4NetTextFormatterOptionsBuilder UsePropertyFilter(Serilog.Formatting.Log4Net.PropertyFilter filterProperty) { }
     }
     public delegate string MessageFormatter(Serilog.Events.LogEvent logEvent, System.IFormatProvider? formatProvider);
