Skip to content

Commit 2bd298f

Browse files
snakefootsnakefoot
committed
NLog v6 - FileTarget with ArchiveSuffixFormat
1 parent 2b24b99 commit 2bd298f

File tree

1 file changed

+54
-18
lines changed

1 file changed

+54
-18
lines changed

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

Lines changed: 54 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -38,9 +38,10 @@ since right now the AOT-build cannot predict what types will be required by the
3838
But disabling automatic loading of the `NLog.config`-file is a huge breaking change,
3939
and would hurt lots of existing applications.
4040

41-
### NLog FileTarget without ConcurrentWrites
41+
### NLog FileTarget and ArchiveSuffixFormat
4242

43-
NLog FileTarget no longer uses `File.Move` by default, but instead rolls to the next filename.
43+
NLog FileTarget has received a major rewrite to simplify the archive-logic. NLog FileTarget
44+
no longer uses `File.Move` by default, but instead rolls to the next filename.
4445
This is to prevent file-locking issues with other background-applications, or if the log-file is
4546
held open by file-viewer.
4647

@@ -50,7 +51,7 @@ The new archive-logic:
5051
- LogFile_1.txt
5152
- LogFile_2.txt (Newest file)
5253

53-
The old archive-logic:
54+
The old static archive-logic:
5455

5556
- LogFile.txt (Newest file)
5657
- LogFile.1.txt (Oldest file)
@@ -60,37 +61,72 @@ NLog FileTarget still support static archive logic with `File.Move`, but it must
6061
by specifying `ArchiveFileName`. If not using `ArchiveFileName` but want to revert to old archive-logic
6162
with `File.Move`, then just assign `ArchiveFileName="..."` to have the same value as `FileName="..."`.
6263

64+
NLog FileTarget no longer has the following archive-options:
65+
66+
- EnableArchiveFileCompression - Removed because of dependency on compression-libraries.
67+
- ArchiveOldFileOnStartupAboveSize - Instead use ArchiveAboveSize / ArchiveOldFileOnStartup.
68+
- ArchiveDateFormat - Marked as obsolete. Instead use new ArchiveSuffixFormat
69+
- ArchiveNumbering - Marked as obsolete. Instead use new ArchiveSuffixFormat (Rolling is unsupported).
70+
- ArchiveFileKind - Removed because it is now implicit.
71+
- FileNameKind - Removed because it is now implicit.
72+
73+
The `ArchiveSuffixFormat`-option has been introduced to handle `{#}`, and instead of specifying
74+
`archiveFilename="LogFile.{##}.txt"` then one should specify `archiveFilename="LogFile.txt"` with `archiveSuffixFormat="{1:yyyyMMdd}_{0:00}"`.
75+
The `ArchiveSuffixFormat`-option doesn't support NLog Layout, and works like `string.Format` and supports these place-holders:
76+
- `{0}` - The archive sequence-number. Supports format option `{0:000}`.
77+
- `{1}` - The archive created-datetime. Supports format option `{1:yyyyMMdd}` (Only works when also specifying `archiveFileName="..."`).
78+
79+
Old Configuration Example:
80+
```xml
81+
<target xsi:type="file" name="logfile"
82+
fileName="logfile.txt"
83+
archiveFilename="logfile.{#}.txt"
84+
archiveNumbering="Date"
85+
archiveEvery="Day"
86+
archiveDateFormat="yyyyMMdd">
87+
```
88+
New Configuration Example:
89+
```xml
90+
<target xsi:type="file" name="logfile"
91+
fileName="logfile.txt"
92+
archiveFilename="logfile.txt"
93+
archiveEvery="Day"
94+
archiveSuffixFormat="{1:yyyyMMdd}">
95+
```
96+
97+
Alternative options for replacing `EnableArchiveFileCompression = true`:
98+
- Activate NTFS compression for the logging-folder.
99+
- Setup cron-job / scheduled-task that performs ZIP-compression and cleanup of the logging-folder.
100+
- Implement background task in the application, which monitors the logging-folder and performs ZIP-compression and cleanup.
101+
- Use the new nuget-package [NLog.Targets.GZipFile](https://www.nuget.org/packages/NLog.Targets.GZipFile) where GZipFileTarget writes directly to a compressed log-file using `GZipStream`.
102+
103+
### NLog FileTarget without ConcurrentWrites
104+
105+
NLog FileTarget no longer supports `ConcurrentWrites`-option, where multiple processes running
106+
on the same machine can write to the same file with help from global operating-system-mutex.
107+
108+
This feature was removed to simplify the NLog FileTarget, and not rely on features that was
109+
only supported on certain operating system platforms. Still there is support for `KeepFileOpen` = true / false.
110+
63111
NLog FileTarget no longer has the following options:
64112

65113
- ConcurrentWrites - Removed because of dependency on global mutex and exotic file-locks.
66-
- EnableArchiveFileCompression - Removed because of dependency on compression-libraries.
67114
- CleanupFileName - Removed because it is now implicit.
68-
- FileNameKind - Removed because it is now implicit.
69-
- ArchiveFileKind - Removed because it is now implicit.
70115
- FileAttributes - Removed because of dependency on Windows-only API.
71116
- ForceManaged - Removed because of dependency on Windows-only API.
72117
- ConcurrentWriteAttempts - Removed together with ConcurrentWrites.
73118
- ConcurrentWriteAttemptDelay - Removed together with ConcurrentWrites.
74119
- ForceMutexConcurrentWrites - Removed together with ConcurrentWrites.
75120
- NetworkWrites - Replaced by KeepFileOpen.
76-
- ArchiveOldFileOnStartupAboveSize - Instead use ArchiveAboveSize / ArchiveOldFileOnStartup.
77-
- ArchiveDateFormat - Marked as obsolete. Instead use new ArchiveSuffixFormat
78-
- ArchiveNumbering - Marked as obsolete. Instead use new ArchiveSuffixFormat (Rolling is unsupported).
79121

80-
If one still requires these options, then one can use the new [NLog.Targets.ConcurrentFile](https://www.nuget.org/packages/NLog.Targets.ConcurrentFile)-nuget-package.
81-
The [NLog.Targets.ConcurrentFile](https://www.nuget.org/packages/NLog.Targets.ConcurrentFile)-nuget-package is the original NLog FileTarget with all its features and complexity.
82-
It is the goal that [NLog.Targets.ConcurrentFile](https://www.nuget.org/packages/NLog.Targets.ConcurrentFile)-nuget-package should become legacy, but it might be helpful when upgrading to NLog v6.
122+
There is a new [NLog.Targets.ConcurrentFile](https://www.nuget.org/packages/NLog.Targets.ConcurrentFile)-nuget-package, which is
123+
the original NLog FileTarget with all its features and complexity. It is the goal that [NLog.Targets.ConcurrentFile](https://www.nuget.org/packages/NLog.Targets.ConcurrentFile)-nuget-package
124+
should become legacy, but it might be helpful when upgrading to NLog v6.
83125

84126
Alternative options for replacing `ConcurrentWrites = true`:
85127
- Use the new nuget-package [NLog.Targets.AtomicFile](https://www.nuget.org/packages/NLog.Targets.AtomicFile) where AtomicFileTarget uses atomic file-appends and supports Windows / Linux with NET8.
86128
- Change to use `KeepFileOpen = false` where file is opened / closed when writing LogEvents. For better performance then consider to also use `<targets async="true">`.
87129

88-
Alternative options for replacing `EnableArchiveFileCompression = true`:
89-
- Activate NTFS compression for the logging-folder.
90-
- Setup cron-job / scheduled-task that performs ZIP-compression and cleanup of the logging-folder.
91-
- Implement background task in the application, which monitors the logging-folder and performs ZIP-compression and cleanup.
92-
- Use the new nuget-package [NLog.Targets.GZipFile](https://www.nuget.org/packages/NLog.Targets.GZipFile) where GZipFileTarget writes directly to a compressed log-file using `GZipStream`.
93-
94130
### NLog AtomicFileTarget without mutex
95131

96132
New AtomicFileTarget has been introduced with [NLog.Targets.AtomicFile](https://www.nuget.org/packages/NLog.Targets.AtomicFile),

0 commit comments

Comments
 (0)