NLog v6 major changes

_posts/2015-06-30-extending-nlog-is-easy.md

@@ -7,7 +7,7 @@ title: Extending NLog is... easy!
 
 Not everyone knows NLog is easy to extend to your own wishes. 
 There can be various reasons for wanting to extend NLog. 
-For example when you want to write your log messages to a custom output or you would like to use your own `${}` macros. 
+For example when you want to write your log messages to a custom output target, or include additional details in the output with own custom `${layout-renderer}`. 
 
 With some attributes you can create your own custom target, layout or layout renderer with ease. 
 Also creating your own conditions for filter messages is possible!
@@ -78,7 +78,7 @@ Example usages:
 
 
 ## How to write a custom target?
-Creating a custom target is almost identical to creating a custom layout renderer. 
+Creating a custom target is very similar to creating a custom layout renderer. 
 
 The created class should now inherit from `NLog.Targets.TargetWithLayout` and override the `Write()` method. In the body of the method invoke `this.Layout.Render()` to render the message text.
 
@@ -96,13 +96,14 @@ public sealed class MyFirstTarget: TargetWithLayout
     }
 
     [RequiredParameter] 
-    public string Host { get; set; }
+    public Layout Host { get; set; }
 
     protected override void Write(LogEventInfo logEvent) 
     { 
        string logMessage = this.Layout.Render(logEvent); 
+       string hostName = this.Host.Render(logEvent); 
 
-       SendTheMessageToRemoteHost(this.Host, logMessage); 
+       SendTheMessageToRemoteHost(hostName, logMessage); 
     } 
 
     private void SendTheMessageToRemoteHost(string host, string message) 
@@ -144,7 +145,7 @@ Configuration file example:
 
 
 ### Do I really need to create a separate assembly?
-Not really. You should then register your target programmatically. Just make sure to register your stuff at the very beginning of your program, before any log messages are written. 
+Not really. You should then register your target programmatically. Just make sure to register your stuff at the very beginning of your program, before the loading of NLog config and actual logging. 
 {% highlight csharp %}
 static void Main(string[] args) 
 { 
@@ -156,7 +157,7 @@ static void Main(string[] args)
     ConfigurationItemFactory.Default.Targets
           .RegisterDefinition("MyFirst", typeof(MyNamespace.MyFirstTarget));
 
-    // start logging here 
+    // start loading NLog config and logging here
 }
 {% endhighlight %}
 

_posts/2022-05-16-nlog-5-0-finally-ready.md

@@ -19,6 +19,7 @@ NLog 5.0 has completed preview testing, and is ready for release.
 - Parsing of type-alias will now ignore dashes (-)
 - NLog v5.1 enables support for ISpanFormattable in FormattedMessage and serializing JSON.
 - NLog v5.2 includes annotations for application trimming without build warnings.
+- NLog v5.3 introduces support for `Layout.FromMethod` for typed Layout
 
 See details [here](https://nlog-project.org/2021/08/25/nlog-5-0-preview1-ready.html)
 

_posts/2024-10-01-nlog-6-0-goals.md

@@ -17,7 +17,7 @@ NLog v6.0 has the following goals:
 - Extract NLog.Targets.NetworkTarget to its own nuget-package
 - Extract NLog.Targets.MailTarget to its own nuget-package
 - Extract NLog.Targets.FileTarget to its own nuget-package NLog.Targets.ConcurrentFileTarget
-  - NLog will instead have a simple FileTarget without ConcurrentWrites-support but only KeepFileOpen = false
+- NLog will instead have a simple FileTarget without ConcurrentWrites-support, but still supports KeepFileOpen true / false
 
 The overall goal for NLog v6.0 is to continue being a fully working logging-library in a single nuget-package.
 The NLog-package will out of the box only handle file- and console-output, which will probably cover 90 pct.

_posts/2025-04-01-nlog-6-0-major-changes.md

@@ -0,0 +1,309 @@
+---
+layout: post
+title: NLog 6.0 - List of major changes
+---
+
+NLog 6.0 is a major version release, and introduces breaking changes to support AOT-builds by splitting into multiple nuget packages.
+
+## Major changes
+
+### NLog supports AOT
+
+NLog has traditionally relied on reflection to dynamically discover requirements for target output.
+But reflection does not always work well with build trimming, and before NLog marked itself to be excluded from trimming.
+
+NLog includes many features, and each feature often introduces additional dependencies on the .NET library.
+This can lead to overhead for AOT builds, as it must include and compile all the relevant source code.
+
+NLog v6 attempts to reduce its footprint by extracting several features into separate nuget-packages:
+
+- NLog.RegEx - Depends on System.Text.RegularExpressions which is a huge dependency for a logging library.
+- NLog.Targets.ConcurrentFile - ConcurrentWrites using global mutex from operating system API.
+- NLog.Targets.AtomicFile - ConcurrentWrites using atomic file-append from operating system API.
+- NLog.Targets.GZipFile - EnableArchiveFileCompression using GZipStream for writing GZip compressed log-files.
+- NLog.Targets.Mail - Depends on System.Net.Mail.SmtpClient.
+- NLog.Targets.Network - Depends on TCP and UDP Network Socket, and adds support for Syslog and Graylog.
+- NLog.Targets.Trace - Depends on System.Diagnostics.TraceListener.
+- NLog.Targets.WebService - Depends on System.Net.Http.HttpClient.
+
+NLog v6 also no longer depends on `System.Xml.XmlReader`, but now includes its own basic XmlParser for loading `NLog.config` files.
+
+NLog v6 still introduces an overhead when compared with just using `Console.WriteLine`,
+but now reduced to 5 MByte in comparison to 14 MBytes with NLog v5. 
+
+If the `NLog.config`-file had to be explicitly loaded, then the AOT-build could trim much more,
+since right now the AOT-build cannot predict what types will be required by the `NLog.config`-file.
+But disabling automatic loading of the `NLog.config`-file is a huge breaking change,
+and would hurt lots of existing applications.
+
+### NLog FileTarget without ConcurrentWrites
+
+NLog FileTarget no longer uses `File.Move` by default, but instead rolls to the next filename.
+This is to prevent file-locking issues with other background-applications, or if the log-file is
+held open by file-viewer.
+
+The new archive-logic:
+
+- LogFile.txt (Oldest file)
+- LogFile_1.txt
+- LogFile_2.txt (Newest file)
+
+The old archive-logic:
+
+- LogFile.txt (Newest file)
+- LogFile.1.txt (Oldest file)
+- LogFile.2.txt
+
+NLog FileTarget still support static archive logic with `File.Move`, but it must be explictly activated
+by specifying `ArchiveFileName`. If not using `ArchiveFileName` but want to revert to old archive-logic
+with `File.Move` then just ensure to assign `ArchiveFileName="..."` with the same value as `FileName="..."`.
+
+NLog FileTarget no longer has the following options:
+
+- ConcurrentWrites - Removed because of dependency on global mutex and exotic file-locks.
+- EnableArchiveFileCompression - Removed because of dependency on compression-libraries.
+- CleanupFileName - Removed because it is now implicit.
+- FileNameKind - Removed because it is now implicit.
+- ArchiveFileKind - Removed because it is now implicit.
+- FileAttributes - Removed because of dependency on Windows-only API.
+- ForceManaged - Removed because of dependency on Windows-only API.
+- ConcurrentWriteAttempts - Removed together with ConcurrentWrites.
+- ConcurrentWriteAttemptDelay - Removed together with ConcurrentWrites.
+- ForceMutexConcurrentWrites - Removed together with ConcurrentWrites.
+- NetworkWrites - Replaced by KeepFileOpen.
+- ArchiveOldFileOnStartupAboveSize - Instead use ArchiveAboveSize / ArchiveOldFileOnStartup.
+- ArchiveDateFormat - Marked as obsolete. Instead use new ArchiveSuffixFormat
+- ArchiveNumbering - Marked as obsolete. Instead use new ArchiveSuffixFormat (Rolling is unsupported).
+
+If one still requires these options, then one can use the new NLog.Targets.ConcurrentFile-nuget-package.
+NLog.Targets.ConcurrentFile-nuget-package is the original NLog FileTarget with all its features and complexity.
+The goal is that NLog.Targets.ConcurrentFile-nuget-package should become legacy, but it might help some when upgrading to NLog v6.
+
+Alternative options for replacing `ConcurrentWrites = true`:
+- Use the new nuget-package NLog.Targets.AtomicFile where AtomicFileTarget uses atomic file-appends and supports Windows / Linux with NET8.
+- Change to use `KeepFileOpen = false` where file is opened / closed when writing LogEvents. Recommended to use `<targets async="true">`.
+
+Alternative options for replacing `EnableArchiveFileCompression = true`:
+- Activate NTFS compression for the logging-folder.
+- Setup cron-job / scheduled-task that performs ZIP-compression and cleanup of the logging-folder.
+- Implement background task in the application, which monitors the logging-folder and performs ZIP-compression and cleanup.
+- Use the new nuget-package NLog.Targets.GZipFile where GZipFileTarget writes directly to a compressed log-file using GZipStream.
+
+### NLog AtomicFileTarget without mutex
+
+New AtomicFileTarget has been introduced, that supports atomic file-append with help from the operating system,
+and supports both Windows and Linux (with help from Mono Posix) for NET8 (and newer).
+
+Extends the standard FileTarget and adds support for `ConcurrentWrites = true`, but without using global mutex.
+
+Linux users must use `dotnet publish` with `--configuration release --runtime linux-x64` to ensure
+correct publish of the `Mono.Posix.NETStandard`-nuget-package dependency.
+
+### NLog GZipFileTarget with GZipStream
+
+New GZipFileTarget has been introduced, that writes directly to a compressed log-file using GZipStream.
+
+Extends the standard FileTarget and adds support for `EnableArchiveFileCompression = true`, but only supports
+GZip file compression.
+
+The GZip File compression doesn't allow appending to existing GZip Archive without rewriting the entire GZip Archive.
+Therefore these options are set by default `KeepFileOpen = true` and `ArchiveOldFileOnStartup = true`.
+
+The GZip File compression has better handling of large log-files compared to the old `EnableArchiveFileCompression = true`,
+where the old ZIP compression would stall the file-logging until completed.
+
+### NLog LogFactory FlushAsync
+
+NLog LogFactory `Flush()` and `Shutdown()` are synchronous API methods, that schedules background worker-threads
+to execute NLog Target Flush. This doesn't work well on platforms that simulates worker-threads,
+by running everything on main thread.
+
+Instead NLog LogFactory `FlushAsync`-method has been introduced that will support multi-threaded flush.
+
+The NLog LogFactory now also implements `IDisposableAsync` which includes `FlushAsync` before closing. This allows the following:
+```
+await using var logFactory = NLog.LogManager.Setup().LoadConfigurationFromFile().LogFactory; // Automatic Shutdown()
+```
+
+The NLog LogFactory `Dispose()`-method has been changed to skip flush with help from worker-threads,
+but will only perform synchronous NLog Target Close.
+
+### NLog GelfTarget and GelfLayout
+
+The NLog.Targets.NetworkTarget nuget-package also includes support for the Graylog Extended Log Format (GELF).
+
+The `GelfTarget` extends the standard `NetworkTarget` with the new `GelfLayout`.
+
+It depends on the builtin NLog JSON serializer, but follows the 'standard' of prefixing all
+custom property-names with underscore `_`.
+
+## NLog SyslogTarget and SyslogLayout
+
+The NLog.Targets.NetworkTarget nuget-package also includes support for the Syslog Output Format.
+
+The `SyslogTarget` extends the standard `NetworkTarget` with the new `SyslogLayout`.
+
+The `SyslogLayout` supports both RFC-3164 (simple) + RFC-5424 (structured) logging output.
+
+### NLog NetworkTarget with NoDelay = true
+
+The NLog.Targets.NetworkTarget nuget-package includes support for configuring TCP_NODELAY.
+The `NetworkTarget` will by default use `NoDelay = true` to turn off delayed ACK,
+to avoid delays of 200ms because of nagle-algorithm.
+
+Believe most users will not notice the overhead of additional ACK-packages, but will notice
+a delay of 200ms.
+
+### NLog NetworkTarget with SendTimeoutSeconds = 100
+
+The NLog.Targets.NetworkTarget nuget-package changes the default value of TCP SendTimeout
+from waiting forever to 100 secs. 
+
+The `NetworkTarget` should now react to the network-cable being unplugged and the TCP send-window being filled.
+
+The `NetworkTarget` should now automatically attempt to reconnect when the endpoint suddenly becomes unresponsive.
+
+### NLog NetworkTarget with SslCertificateFile
+
+The NLog.Targets.NetworkTarget nuget-package introduces the ability to specify custom SSL certificate from file.
+
+The `NetworkTarget` now recognizes these new settings:
+ - `Layout SslCertificateFile`
+ - `Layout SslCertificatePassword`
+
+The `NetworkTarget` can now perform SSL handshake with custom SSL certificate from file, without needing to register the certificate in the global operating-system cache.
+
+## Breaking changes
+
+### Removed legacy Target-Frameworks
+NetStandard 1.3 and NetStandard 1.5 has now been removed, since less relevant as most have moved to NetStandard 2.0 (or newer).
+
+Removes platform support for:
+
+- NET CoreApp 1.0 + 1.1
+- UAP + UAP10.0 (UWP ver. 1)
+- Tizen30
+
+Considering to also remove NET35 + NET45, since those Target-Frameworks requires extra effort to build when using Visual Studio 2022.
+Removing old Target-Frameworks will also reduce the file-size of the NLog-nuget-package.
+If this will break your entire eco-system then [Please tell](https://github.com/NLog/NLog/issues/4931).
+
+### NLog Structured Message formatting without quotes
+
+NLog v4.5 introduced support for message-templates, where it followed the Serilog approach by adding quotes around string-values:
+```csharp
+Logger.Info("Hello {World}", "Earth"); // Outputs Hello "Earth" with NLog v4.5
+```
+
+Microsoft Extension Logging decided not to implement that behavior, and now NLog also changes to not using quotes by default. Thus avoiding surprises when using NLog Logger directly instead as LoggingProvider for Microsoft Extension Logging.
+
+To apply string-quotes for a single value:
+```csharp
+Logger.Info("Hello {@World}", "Earth"); // Outputs Hello "Earth" with NLog v6
+```
+
+It is possible to globally revert to old behavior:
+```csharp
+LogManager.Setup().SetupSerialization(s => s.RegisterValueFormatterWithStringQuotes());
+```
+
+### NLog JsonLayout EscapeForwardSlash obsolete
+
+NLog v5 changed `JsonLayout` to have the default value `EscapeForwardSlash = false`, and now NLog v6
+marks the NLog `JsonLayout` `EscapeForwardSlash` as completely obsolete and no longer having any effect.
+
+### NLog JsonLayout SuppressSpaces default true
+
+The `JsonLayout` now have the new default value `SuppressSpaces = true`, 
+since log-file-size / network-traffic-usage doesn't benefit from the extra spaces.
+
+If the output from `JsonLayout` needs to be more human readable, then one can explictly assign
+`SuppressSpaces = false` or `IndentJson = true`.
+
+### NLog ColoredConsoleTarget with Errors in red
+
+NLog `ColoredConsoleTarget` used the color Yellow for Errors and Magenta for Warnings.
+This has now been changed to color Red for Errors and Yellow for Warnings.
+
+This is to align with the normal color standards that most other systems seems to be using.
+
+### NLog ColoredConsoleTarget without RegEx
+
+RegularExpressions (RegEx) is a huge API, and a big dependency for a logging library,
+so to reduce the footprint of NLog then RegEx support have been removed.
+
+This means word-highlighting rules no longer can scan for word-matches using RegEx.
+But logic has been implemented to continue support `IgnoreCase` and `WholeWords`
+for the string-matching logic.
+
+### NLog Replace LayoutRenderer without RegEx
+
+RegularExpressions (RegEx) is a huge API, and a big dependency for a logging library,
+so to reduce the footprint of NLog then RegEx support have been removed.
+
+Logic has been implemented to continue support `IgnoreCase` and `WholeWords`
+for the string-matching logic. 
+
+This means the following has been removed for the `${replace}` LayoutRenderer:
+- `bool RegEx`
+- `bool CompileRegex`
+- `string ReplaceGroupName`
+
+If RegEx replace-logic is important then one can use the new nuget-package `NLog.RegEx`, which includes `${regex-replace}`.
+
+### NLog InternalLogger without LogToTrace
+
+NLog `InternalLogger.LogToTrace` has been remnoved. This reduces the NLog footprint by
+removing references to `System.Diagnostics.Trace` and `System.Diagnostics.TraceListener`.
+
+If it is important to redirect NLog InternalLogger output to `System.Diagnostics.Trace`,
+then one can use NLog `InternalLogger.LogWriter` to assign a custom `StringWriter` that performs the forwarding.
+Alternative one can setup custom subscriber to NLog `InternalLogger.InternalEventOccurred` event handler.
+
+### NLog XmlParser replaces XmlReader
+
+The .NET `System.Xml.XmlReader` is a heavy dependency that both loads XML using HttpClient, and support
+code generation to optimize serialization for types. To reduce dependencies and minimize AOT-build-filesize,
+then NLog now includes its own XML-parser.
+
+It could have been nice if Microsoft could refactor `System.Xml.XmlReader`,
+so it only introduced a minimal AOT-footprint, but that is probably too late.
+
+The NLog XML-parser only provides basic XML support, but it should be able to load any XML file that was
+working with NLog v5. 
+
+### NLog EventLog with more Layout
+Use Layout for Log + MachineName + MaxMessageLength + MaxKilobytes
+
+### NLog SimpleLayout Immutable
+NLog `SimpleLayout` have removed the setter-method for its `Text`-property, and is now a sealed class.
+
+This is to simpilfy the NLog `SimpleLayout` API, and to make it clear that NLog will optimize based on the initial layout.
+
+### Minimal Logger-API
+Not ready yet, and post-poned because major breaking change, which makes it harder to test first NLog v6-Preview.
+
+### Logger API with string interpolation
+Not ready yet, and post-poned because waiting for minimal Logger-API
+
+Idea is to skip string interpolation, when LogLevel is not enabled.
+
+### Logger API with ReadOnlySpan params
+Not ready yet, and post-poned because waiting for minimal Logger-API
+
+Idea is to skip params array-allocation, when LogLevel is not enabled.
+
+And if structured-logging then skip params allocation, but only rely on properties-dictionary.
+
+### NLog Nullable References
+Not ready yet, and post-poned because waiting for minimal Logger-API
+
+## Many other improvements
+
+For full list of all changes: [NLog 6.0 Pull Requests](https://github.com/NLog/NLog/pulls?q=is%3Apr+is%3Amerged+milestone:%226.0%22)
+
+- [Breaking Changes](https://github.com/NLog/NLog/pulls?q=is%3Apr+label%3A%22breaking%20change%22+is%3Amerged+milestone:%226.0%22)
+- [Breaking Behavior Changes](https://github.com/NLog/NLog/pulls?q=is%3Apr+label%3A%22breaking%20behavior%20change%22+is%3Amerged+milestone:%226.0%22)
+- [Features](https://github.com/NLog/NLog/pulls?q=is%3Apr+label%3A%22Feature%22+is%3Amerged+milestone:%226.0%22)
+- [Improvements](https://github.com/NLog/NLog/pulls?q=is%3Apr+label%3A%22Enhancement%22+is%3Amerged+milestone:%226.0%22)
+- [Performance](https://github.com/NLog/NLog/pulls?q=is%3Apr+label%3A%22Performance%22+is%3Amerged+milestone:%226.0%22)