Skip to content

Commit 0ff685d

Browse files
snakefootsnakefoot
committedApr 13, 2025
NLog v6 major changes
1 parent aa756d7 commit 0ff685d

3 files changed

+291
-6
lines changed
 

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

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ title: Extending NLog is... easy!
77

88
Not everyone knows NLog is easy to extend to your own wishes.
99
There can be various reasons for wanting to extend NLog.
10-
For example when you want to write your log messages to a custom output or you would like to use your own `${}` macros.
10+
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}`.
1111

1212
With some attributes you can create your own custom target, layout or layout renderer with ease.
1313
Also creating your own conditions for filter messages is possible!
@@ -78,7 +78,7 @@ Example usages:
7878

7979

8080
## How to write a custom target?
81-
Creating a custom target is almost identical to creating a custom layout renderer.
81+
Creating a custom target is very similar to creating a custom layout renderer.
8282

8383
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.
8484

@@ -96,13 +96,14 @@ public sealed class MyFirstTarget: TargetWithLayout
9696
}
9797

9898
[RequiredParameter]
99-
public string Host { get; set; }
99+
public Layout Host { get; set; }
100100

101101
protected override void Write(LogEventInfo logEvent)
102102
{
103103
string logMessage = this.Layout.Render(logEvent);
104+
string hostName = this.Host.Render(logEvent);
104105

105-
SendTheMessageToRemoteHost(this.Host, logMessage);
106+
SendTheMessageToRemoteHost(hostName, logMessage);
106107
}
107108

108109
private void SendTheMessageToRemoteHost(string host, string message)
@@ -144,7 +145,7 @@ Configuration file example:
144145

145146

146147
### Do I really need to create a separate assembly?
147-
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.
148+
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.
148149
{% highlight csharp %}
149150
static void Main(string[] args)
150151
{
@@ -156,7 +157,7 @@ static void Main(string[] args)
156157
ConfigurationItemFactory.Default.Targets
157158
.RegisterDefinition("MyFirst", typeof(MyNamespace.MyFirstTarget));
158159

159-
// start logging here
160+
// start loading NLog config and logging here
160161
}
161162
{% endhighlight %}
162163

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ NLog 5.0 has completed preview testing, and is ready for release.
1919
- Parsing of type-alias will now ignore dashes (-)
2020
- NLog v5.1 enables support for ISpanFormattable in FormattedMessage and serializing JSON.
2121
- NLog v5.2 includes annotations for application trimming without build warnings.
22+
- NLog v5.3 introduces support for `Layout.FromMethod` for typed Layout
2223

2324
See details [here](https://nlog-project.org/2021/08/25/nlog-5-0-preview1-ready.html)
2425

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

Lines changed: 283 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,283 @@
1+
---
2+
layout: post
3+
title: NLog 6.0 - List of major changes
4+
---
5+
6+
NLog 6.0 is a major version release that introduces breaking changes, including the splitting into multiple NuGet packages, and other improvements to support AOT builds.
7+
8+
## Major changes
9+
10+
### NLog supports AOT
11+
12+
NLog has traditionally relied on reflection to dynamically discover requirements for target output.
13+
But reflection does not always work well with build trimming, and before NLog marked itself to not be trimmed.
14+
15+
NLog includes many features, each of these feature often introduce additional dependencies on the .NET library.
16+
This can lead to overhead for AOT builds, as it must include and compile all the relevant source code.
17+
18+
NLog v6 attempts to reduce its footprint by extracting several features into separate nuget-packages:
19+
20+
- NLog.AutoReloadConfig - AutoReload depends on FileWatcher.
21+
- NLog.RegEx - RegularExpressions is a huge dependency for a logging library.
22+
- NLog.Targets.ConcurrentFile - ConcurrentWrites depends on global Mutex.
23+
- NLog.Targets.AtomicFile - ConcurrentWrites depends on atomic file-append using operating system API.
24+
- NLog.Targets.Mail - Depends on SmtpClient.
25+
- NLog.Targets.Network - Depends on TCP and UDP Network Socket.
26+
- NLog.Targets.Trace - Depends on TraceListener-API.
27+
- NLog.Targets.WebService - Depends on HttpClient.
28+
29+
NLog v6 also no longer supports automatic loading of `NLog.config`-file. This is because dynamic configuration
30+
loading, prevents build trimming of any NLog types, as the AOT-build cannot determine upfront what types
31+
will be used by the `NLog.config`-file.
32+
33+
### NLog without automatic loading of NLog.config
34+
35+
NLog will no longer automatically load the NLog LoggingConfiguration, when creating the first NLog Logger by calling `LogManger.GetCurrentClassLogger()` or `LogManger.GetLogger()`.
36+
37+
Instead one must explicit load the `NLog.config` file at application-startup:
38+
```csharp
39+
var logger = NLog.LogManager.Setup().LoadConfigurationFromFile().GetCurrentClassLogger();
40+
logger.Info("Hello World");
41+
```
42+
43+
When using Microsoft HostBuilder with `UseNLog()`, then it will continue to automatically load the NLog LoggingConfiguration without having to make any changes.
44+
45+
.NET Framework will continue to probe NLog LoggingConfiguration from the `app.config` / `web.config`, so one can consider doing this:
46+
```xml
47+
<?xml version="1.0" encoding="utf-8" ?>
48+
<configuration>
49+
<configSections>
50+
<section name="nlog" type="NLog.Config.ConfigSectionHandler, NLog"/>
51+
</configSections>
52+
<nlog include="NLog.config" />
53+
</configuration>
54+
```
55+
56+
### NLog FileTarget without ConcurrentWrites
57+
58+
NLog FileTarget no longer uses `File.Move` by default, but instead rolls to the next filename.
59+
This is to prevent file-locking issues with other background-applications, or if the log-file is
60+
held open by file-viewer.
61+
62+
The new archive-logic:
63+
64+
- LogFile.txt (Oldest file)
65+
- LogFile_1.txt
66+
- LogFile_2.txt (Newest file)
67+
68+
The old archive-logic:
69+
70+
- LogFile.txt (Newest file)
71+
- LogFile.1.txt (Oldest file)
72+
- LogFile.2.txt
73+
74+
NLog FileTarget still support static archive logic with `File.Move`, but it must be explictly activated
75+
by specifying `ArchiveFileName`.
76+
77+
NLog FileTarget no longer has the following options:
78+
79+
- ConcurrentWrites - Removed because of dependency on global mutex and exotic file-locks.
80+
- EnableArchiveFileCompression - Removed because of dependency on compression-libraries.
81+
- CleanupFileName - Removed because it is now implicit.
82+
- FileNameKind - Removed because it is now implicit.
83+
- ArchiveFileKind - Removed because it is now implicit.
84+
- FileAttributes - Removed because of dependency on Windows-only API.
85+
- ForceManaged - Removed because of dependency on Windows-only API.
86+
- ConcurrentWriteAttempts - Removed together with ConcurrentWrites.
87+
- ConcurrentWriteAttemptDelay - Removed together with ConcurrentWrites.
88+
- ForceMutexConcurrentWrites - Removed together with ConcurrentWrites.
89+
- NetworkWrites - Replaced by KeepFileOpen.
90+
- ArchiveOldFileOnStartupAboveSize - Instead use ArchiveAboveSize / ArchiveOldFileOnStartup.
91+
- ArchiveDateFormat - Marked as obsolete. Instead use new ArchiveSuffixFormat
92+
- ArchiveNumbering - Marked as obsolete. Instead use new ArchiveSuffixFormat (Rolling is unsupported).
93+
94+
If one requires these options, then one can use the NLog.Targets.ConcurrentFile-nuget-package.
95+
96+
### NLog AtomicFileTarget without mutex
97+
98+
New AtomicFileTarget has been introduced, that supports atomic file-append with help from the operating system,
99+
and supports both Windows and Linux (with help from Mono Posix) for NET8.
100+
101+
Extends the standard FileTarget and adds support for `ConcurrentWrites = true`, but without using global mutex.
102+
103+
Linux must use `dotnet publish` with `--framework net8.0 --configuration release --runtime linux-x64`
104+
105+
### NLog LogFactory FlushAsync
106+
107+
NLog LogFactory `Flush()` and `Shutdown()` are synchronous API methods, that schedules background worker-threads
108+
to execute NLog Target Flush. This doesn't work well on platforms that simulates worker-threads,
109+
by running everything on main thread.
110+
111+
Instead NLog LogFactory `FlushAsync`-method has been introduced that will support multi-threaded flush.
112+
113+
The NLog LogFactory now also implements `IDisposableAsync` which includes `FlushAsync` before closing. This allows the following:
114+
```
115+
await using var logFactory = NLog.LogManager.Setup().LoadConfigurationFromFile().LogFactory; // Automatic Shutdown()
116+
```
117+
118+
The NLog LogFactory `Dispose()`-method has been changed to skip flush with help from worker-threads,
119+
but will only perform synchronous NLog Target Close.
120+
121+
### NLog GelfTarget and GelfLayout
122+
123+
The NLog.Targets.NetworkTarget nuget-package also includes support for the Graylog Extended Log Format (GELF).
124+
125+
The `GelfTarget` extends the standard `NetworkTarget` with the new `GelfLayout`.
126+
127+
It depends on the builtin NLog JSON serializer, but follows the 'standard' of prefixing all
128+
custom property-names with underscore `_`.
129+
130+
## NLog SyslogTarget and SyslogLayout
131+
132+
The NLog.Targets.NetworkTarget nuget-package also includes support for the Syslog Output Format.
133+
134+
The `SyslogTarget` extends the standard `NetworkTarget` with the new `SyslogLayout`.
135+
136+
The `SyslogLayout` supports both RFC-3164 (simple) + RFC-5424 (structured) logging output.
137+
138+
### NLog NetworkTarget with NoDelay = true
139+
140+
The NLog.Targets.NetworkTarget nuget-package includes support for configuring TCP_NODELAY.
141+
The `NetworkTarget` will by default use `NoDelay = true` to turn off delayed ACK,
142+
to avoid delays of 200ms because of nagle-algorithm.
143+
144+
Believe most users will not notice the overhead of additional ACK-packages, but will notice
145+
a delay of 200ms.
146+
147+
### NLog NetworkTarget with SendTimeoutSeconds = 100
148+
149+
The NLog.Targets.NetworkTarget nuget-package changes the default value of TCP SendTimeout
150+
from waiting forever to 100 secs.
151+
152+
The `NetworkTarget` should now react to the network-cable being unplugged and the TCP send-window being filled.
153+
154+
The `NetworkTarget` should now automatically attempt to reconnect when the endpoint suddenly becomes unresponsive.
155+
156+
### NLog NetworkTarget with SslCertificateFile
157+
158+
The NLog.Targets.NetworkTarget nuget-package introduces the ability to specify custom SSL certificate from file.
159+
160+
The `NetworkTarget` now recognizes these new settings:
161+
- `Layout SslCertificateFile`
162+
- `Layout SslCertificatePassword`
163+
164+
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.
165+
166+
## Breaking changes
167+
168+
### NLog Structured Message formatting without quotes
169+
170+
NLog v4.5 introduced support for message-templates, where it followed the Serilog approach by adding quotes around string-values:
171+
```csharp
172+
Logger.Info("Hello {World}", "Earth"); // Outputs Hello "Earth" with NLog v4.5
173+
```
174+
175+
Microsoft Extension Logging decided not to implement that behavior, and NLog now follows that direction. Thus avoiding surprises when using NLog Logger directly instead as LoggingProvider for Microsoft Extension Logging.
176+
177+
To apply string-quotes for a single value:
178+
```csharp
179+
Logger.Info("Hello {@World}", "Earth"); // Outputs Hello "Earth" with NLog v6
180+
```
181+
182+
It is possible to globally revert to old behavior:
183+
```csharp
184+
LogManager.Setup().SetupSerialization(s => s.RegisterValueFormatterWithStringQuotes());
185+
```
186+
187+
### NLog JsonLayout EscapeForwardSlash obsolete
188+
189+
NLog v5 changed `JsonLayout` to have the default value `EscapeForwardSlash = false`, and now NLog v6
190+
marks the NLog `JsonLayout` `EscapeForwardSlash` as completely obsolete and no longer having any effect.
191+
192+
### NLog JsonLayout SuppressSpaces default true
193+
194+
The `JsonLayout` has now have a new default value for `SuppressSpaces = true`,
195+
since log-file-size / network-traffic-usage doesn't benefit from the extra spaces.
196+
197+
If the output from `JsonLayout` needs to be more human readable, then one can explictly assign
198+
`SuppressSpaces = false` or `IndentJson = true`.
199+
200+
### NLog ColoredConsoleTarget with Errors in red
201+
202+
NLog `ColoredConsoleTarget` used the color Yellow for Errors and Magenta for Warnings.
203+
This has now been changed to color Red for Errors and Yellow for Warnings.
204+
205+
This is to align with the normal color standards that most other systems seems to be using.
206+
207+
### NLog ColoredConsoleTarget without RegEx
208+
209+
RegularExpressions (RegEx) is a huge API, and a big dependency for a logging library,
210+
so to reduce the footprint of NLog then RegEx support have been removed.
211+
212+
This means word-highlighting rules no longer can scan for word-matches using RegEx.
213+
But logic has been implemented to continue support `IgnoreCase` and `WholeWords`
214+
for the string-matching logic.
215+
216+
### NLog Replace LayoutRenderer without RegEx
217+
218+
RegularExpressions (RegEx) is a huge API, and a big dependency for a logging library,
219+
so to reduce the footprint of NLog then RegEx support have been removed.
220+
221+
Logic has been implemented to continue support `IgnoreCase` and `WholeWords`
222+
for the string-matching logic.
223+
224+
This means the following has been removed for the `${replace}` LayoutRenderer:
225+
- `bool RegEx`
226+
- `bool CompileRegex`
227+
- `string ReplaceGroupName`
228+
229+
If RegEx replace-logic is important then one can use the new nuget-package `NLog.RegEx`, which includes `${regex-replace}`.
230+
231+
### NLog InternalLogger without LogToTrace
232+
233+
NLog `InternalLogger.LogToTrace` has been remnoved. This reduces the NLog footprint by
234+
removing references to `System.Diagnostics.Trace` and `System.Diagnostics.TraceListener`.
235+
236+
If it is important to redirect NLog InternalLogger output to `System.Diagnostics.Trace`,
237+
then one can use NLog `InternalLogger.LogWriter` to assign a custom `StringWriter` that performs the forwarding.
238+
Alternative one can setup custom subscriber to NLog `InternalLogger.InternalEventOccurred` event handler.
239+
240+
### NLog XmlParser replaces XmlReader
241+
242+
The .NET `System.Xml.XmlReader` is a heavy dependency that both loads XML using HttpClient, and support
243+
code generation to optimize serialization for types. To reduce dependencies and minimize AOT-build-filesize,
244+
then NLog now includes its own XML-parser.
245+
246+
The NLog XML-parser only provides basic XML support, but it should be able to load any XML file that was
247+
working with NLog v5.
248+
249+
### NLog EventLog with more Layout
250+
Use Layout for Log + MachineName + MaxMessageLength + MaxKilobytes
251+
252+
### NLog SimpleLayout Immutable
253+
NLog `SimpleLayout` have removed the setter-method for its `Text`-property.
254+
255+
This is to simpilfy the NLog `SimpleLayout` API, and to make it clear that NLog will optimize based on the initial layout.
256+
257+
### Minimal Logger-API
258+
Not ready yet, and post-poned because major breaking change, which makes it harder to test first NLog v6-Preview.
259+
260+
### Logger API with string interpolation
261+
Not ready yet, and post-poned because waiting for minimal Logger-API
262+
263+
Idea is to skip string interpolation, when LogLevel is not enabled.
264+
265+
### Logger API with ReadOnlySpan params
266+
Not ready yet, and post-poned because waiting for minimal Logger-API
267+
268+
Idea is to skip params array-allocation, when LogLevel is not enabled.
269+
270+
And if structured-logging then skip params allocation, but only rely on properties-dictionary.
271+
272+
### NLog Nullable References
273+
Not ready yet, and post-poned because waiting for minimal Logger-API
274+
275+
## Many other improvements
276+
277+
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)
278+
279+
- [Breaking Changes](https://github.com/NLog/NLog/pulls?q=is%3Apr+label%3A%22breaking%20change%22+is%3Amerged+milestone:%226.0%22)
280+
- [Breaking Behavior Changes](https://github.com/NLog/NLog/pulls?q=is%3Apr+label%3A%22breaking%20behavior%20change%22+is%3Amerged+milestone:%226.0%22)
281+
- [Features](https://github.com/NLog/NLog/pulls?q=is%3Apr+label%3A%22Feature%22+is%3Amerged+milestone:%226.0%22)
282+
- [Improvements](https://github.com/NLog/NLog/pulls?q=is%3Apr+label%3A%22Enhancement%22+is%3Amerged+milestone:%226.0%22)
283+
- [Performance](https://github.com/NLog/NLog/pulls?q=is%3Apr+label%3A%22Performance%22+is%3Amerged+milestone:%226.0%22)

0 commit comments

Comments
 (0)