Refine the API for configuring XML namespaces

Do not allow an arbitrary XML namespace, only allow log4net (default), log4j (through UseLog4JCompatibility) or none (through UseNoXmlNamespace).

Author: 0xced

README.md

@@ -78,10 +78,10 @@ new Log4NetTextFormatter(c => c.UseCDataMode(CDataMode.Never))
 
 ### XML Namespace
 
-You can remove the `log4net` XML namespace by setting the `Log4NetXmlNamespace` option to `null`. 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. You *could* also change the namespace to something else than the default `log4net:http://logging.apache.org/log4net/schemas/log4net-events-1.2/` but that would probably not be a good idea.
+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.
 
 ```c#
-new Log4NetTextFormatter(c => c.UseLog4NetXmlNamespace(null))
+new Log4NetTextFormatter(c => c.UseNoXmlNamespace())
 ```
 
 ### Line ending

src/Log4NetTextFormatter.cs

@@ -88,6 +88,8 @@ public void Format(LogEvent logEvent, TextWriter output)
             output.Write(_options.XmlWriterSettings.NewLineChars);
         }
 
+        private bool UsesLog4JCompatibility => ReferenceEquals(Log4NetTextFormatterOptionsBuilder.Log4JXmlNamespace, _options.XmlNamespace);
+
         /// <summary>
         /// Write the log event into the XML writer.
         /// </summary>
@@ -96,10 +98,9 @@ public void Format(LogEvent logEvent, TextWriter output)
         /// <remarks>https://github.com/apache/logging-log4net/blob/rel/2.0.8/src/Layout/XmlLayout.cs#L218-L310</remarks>
         private void WriteEvent(LogEvent logEvent, XmlWriter writer)
         {
-            var useLog4JCompatibility = _options.Log4NetXmlNamespace?.Name == "log4j";
             WriteStartElement(writer, "event");
             WriteEventAttribute(logEvent, writer, "logger", Constants.SourceContextPropertyName);
-            var timestamp = useLog4JCompatibility ? XmlConvert.ToString(logEvent.Timestamp.ToUnixTimeMilliseconds()) : XmlConvert.ToString(logEvent.Timestamp);
+            var timestamp = UsesLog4JCompatibility ? XmlConvert.ToString(logEvent.Timestamp.ToUnixTimeMilliseconds()) : XmlConvert.ToString(logEvent.Timestamp);
             writer.WriteAttributeString("timestamp", timestamp);
             writer.WriteAttributeString("level", LogLevel(logEvent.Level));
             WriteEventAttribute(logEvent, writer, "thread", ThreadIdPropertyName);
@@ -111,7 +112,7 @@ private void WriteEvent(LogEvent logEvent, XmlWriter writer)
                 WriteProperties(logEvent, writer, properties, machineNameProperty);
             }
             WriteMessage(logEvent, writer);
-            WriteException(logEvent, writer, useLog4JCompatibility ? "throwable" : "exception");
+            WriteException(logEvent, writer, UsesLog4JCompatibility ? "throwable" : "exception");
             writer.WriteEndElement();
         }
 
@@ -374,13 +375,13 @@ private void WriteException(LogEvent logEvent, XmlWriter writer, string elementN
         }
 
         /// <summary>
-        /// Start writing an XML element, taking into account the configured <see cref="Log4NetTextFormatterOptions.Log4NetXmlNamespace"/>.
+        /// Start writing an XML element, taking into account the configured <see cref="Log4NetTextFormatterOptions.XmlNamespace"/>.
         /// </summary>
         /// <param name="writer">The XML writer.</param>
         /// <param name="elementName">The name of the XML element to write.</param>
         private void WriteStartElement(XmlWriter writer, string elementName)
         {
-            var qualifiedName = _options.Log4NetXmlNamespace;
+            var qualifiedName = _options.XmlNamespace;
             if (qualifiedName != null)
             {
                 writer.WriteStartElement(qualifiedName.Name, elementName, qualifiedName.Namespace);

src/Log4NetTextFormatterOptions.cs

@@ -8,11 +8,11 @@ namespace Serilog.Formatting.Log4Net
     /// </summary>
     internal class Log4NetTextFormatterOptions
     {
-        internal Log4NetTextFormatterOptions(IFormatProvider? formatProvider, CDataMode cDataMode, XmlQualifiedName? log4NetXmlNamespace, XmlWriterSettings xmlWriterSettings, PropertyFilter filterProperty, ExceptionFormatter formatException)
+        internal Log4NetTextFormatterOptions(IFormatProvider? formatProvider, CDataMode cDataMode, XmlQualifiedName? xmlNamespace, XmlWriterSettings xmlWriterSettings, PropertyFilter filterProperty, ExceptionFormatter formatException)
         {
             FormatProvider = formatProvider;
             CDataMode = cDataMode;
-            Log4NetXmlNamespace = log4NetXmlNamespace;
+            XmlNamespace = xmlNamespace;
             XmlWriterSettings = xmlWriterSettings;
             FilterProperty = filterProperty;
             FormatException = formatException;
@@ -24,8 +24,8 @@ internal Log4NetTextFormatterOptions(IFormatProvider? formatProvider, CDataMode
         /// <summary>See <see cref="Log4NetTextFormatterOptionsBuilder.UseCDataMode"/></summary>
         internal CDataMode CDataMode { get; }
 
-        /// <summary>See <see cref="Log4NetTextFormatterOptionsBuilder.UseLog4NetXmlNamespace"/></summary>
-        internal XmlQualifiedName? Log4NetXmlNamespace { get; }
+        /// <summary>See <see cref="Log4NetTextFormatterOptionsBuilder.UseNoXmlNamespace"/></summary>
+        internal XmlQualifiedName? XmlNamespace { get; }
 
         /// <summary>See <see cref="Log4NetTextFormatterOptionsBuilder.CreateXmlWriterSettings"/></summary>
         internal XmlWriterSettings XmlWriterSettings { get; }

src/Log4NetTextFormatterOptionsBuilder.cs

@@ -9,6 +9,18 @@ namespace Serilog.Formatting.Log4Net
     /// </summary>
     public class Log4NetTextFormatterOptionsBuilder
     {
+        /// <summary>
+        /// The XML namespace used for log4net events.
+        /// </summary>
+        /// <remarks>https://github.com/apache/logging-log4net/blob/rel/2.0.8/src/Layout/XmlLayout.cs#L49</remarks>
+        private static readonly XmlQualifiedName Log4NetXmlNamespace = new("log4net", "http://logging.apache.org/log4net/schemas/log4net-events-1.2/");
+
+        /// <summary>
+        /// The XML namespace used for Log4j events.
+        /// </summary>
+        /// <remarks>// https://github.com/apache/log4j/blob/v1_2_17/src/main/java/org/apache/log4j/xml/XMLLayout.java#L137</remarks>
+        internal static readonly XmlQualifiedName Log4JXmlNamespace = new("log4j", "http://jakarta.apache.org/log4j/");
+
         /// <summary>
         /// Initialize a new instance of the <see cref="Log4NetTextFormatterOptionsBuilder"/> class.
         /// </summary>
@@ -22,9 +34,8 @@ internal Log4NetTextFormatterOptionsBuilder()
         /// <summary> See <see cref="UseCDataMode"/></summary>
         private CDataMode _cDataMode = CDataMode.Always;
 
-        /// <summary>See <see cref="UseLog4NetXmlNamespace"/></summary>
-        /// <remarks>https://github.com/apache/logging-log4net/blob/rel/2.0.8/src/Layout/XmlLayout.cs#L49</remarks>
-        private XmlQualifiedName? _log4NetXmlNamespace = new("log4net", "http://logging.apache.org/log4net/schemas/log4net-events-1.2/");
+        /// <summary>See <see cref="UseNoXmlNamespace"/></summary>
+        private XmlQualifiedName? _xmlNamespace = Log4NetXmlNamespace;
 
         /// <summary>See <see cref="UseLineEnding"/></summary>
         private LineEnding _lineEnding = LineEnding.LineFeed;
@@ -65,15 +76,14 @@ public Log4NetTextFormatterOptionsBuilder UseCDataMode(CDataMode cDataMode)
         }
 
         /// <summary>
-        /// Sets the XML namespace used for log4net events. Set to <see langword="null"/> in order not to use a namespace.
+        /// Do not use any XML namespace for log4net events.
         /// <para/>
         /// The default value has prefix <c>log4net</c> and namespace <c>http://logging.apache.org/log4net/schemas/log4net-events-1.2/</c>.
         /// </summary>
-        /// <param name="log4NetXmlNamespace">The XML namespace to use.</param>
         /// <returns>The builder in order to fluently chain all options.</returns>
-        public Log4NetTextFormatterOptionsBuilder UseLog4NetXmlNamespace(XmlQualifiedName? log4NetXmlNamespace)
+        public Log4NetTextFormatterOptionsBuilder UseNoXmlNamespace()
         {
-            _log4NetXmlNamespace = log4NetXmlNamespace;
+            _xmlNamespace = null;
             return this;
         }
 
@@ -160,14 +170,14 @@ public void UseLog4JCompatibility()
             _lineEnding = LineEnding.CarriageReturn | LineEnding.LineFeed;
 
             // https://github.com/apache/log4j/blob/v1_2_17/src/main/java/org/apache/log4j/xml/XMLLayout.java#L137
-            _log4NetXmlNamespace = new XmlQualifiedName("log4j", "http://jakarta.apache.org/log4j/");
+            _xmlNamespace = Log4JXmlNamespace;
 
             // https://github.com/apache/log4j/blob/v1_2_17/src/main/java/org/apache/log4j/xml/XMLLayout.java#L147
             _cDataMode = CDataMode.Always;
         }
 
         internal Log4NetTextFormatterOptions Build()
-            => new(_formatProvider, _cDataMode, _log4NetXmlNamespace, CreateXmlWriterSettings(_lineEnding, _indentationSettings), _filterProperty, _formatException);
+            => new(_formatProvider, _cDataMode, _xmlNamespace, CreateXmlWriterSettings(_lineEnding, _indentationSettings), _filterProperty, _formatException);
 
         private static XmlWriterSettings CreateXmlWriterSettings(LineEnding lineEnding, IndentationSettings? indentationSettings)
         {

tests/Log4NetTextFormatterTest.cs

@@ -258,7 +258,7 @@ public void NoNamespace()
             // Arrange
             using var output = new StringWriter();
             var logEvent = CreateLogEvent();
-            var formatter = new Log4NetTextFormatter(options => options.UseLog4NetXmlNamespace(null));
+            var formatter = new Log4NetTextFormatter(options => options.UseNoXmlNamespace());
 
             // Act
             formatter.Format(logEvent, output);

tests/PublicApi.Serilog.Formatting.Log4Net.approved.txt

@@ -41,8 +41,8 @@ namespace Serilog.Formatting.Log4Net
         public Serilog.Formatting.Log4Net.Log4NetTextFormatterOptionsBuilder UseIndentationSettings(Serilog.Formatting.Log4Net.IndentationSettings indentationSettings) { }
         public Serilog.Formatting.Log4Net.Log4NetTextFormatterOptionsBuilder UseLineEnding(Serilog.Formatting.Log4Net.LineEnding lineEnding) { }
         public void UseLog4JCompatibility() { }
-        public Serilog.Formatting.Log4Net.Log4NetTextFormatterOptionsBuilder UseLog4NetXmlNamespace(System.Xml.XmlQualifiedName? log4NetXmlNamespace) { }
         public Serilog.Formatting.Log4Net.Log4NetTextFormatterOptionsBuilder UseNoIndentation() { }
+        public Serilog.Formatting.Log4Net.Log4NetTextFormatterOptionsBuilder UseNoXmlNamespace() { }
         public Serilog.Formatting.Log4Net.Log4NetTextFormatterOptionsBuilder UsePropertyFilter(Serilog.Formatting.Log4Net.PropertyFilter filterProperty) { }
     }
     public delegate bool PropertyFilter(Serilog.Events.LogEvent logEvent, string propertyName);