To fix some small issues (submitted on GitHub - thanks), we are working on 3.2.1. This release will contain two bugfixes:
LogManager.Configuration.Variables property wasn’t implemented in the correct class. Full details are available on GitHub.
With the upcoming release of 4.0, we’re doing some things differently: we are time-boxing the release and so the release date is now already known: June 2nd, 2015, a year after the release of 3.0!
Issues for 4.0 are now prioritized with the MoSCoW method. In short this means:
The roadmap of 4.0:
Please note that “pull requests” (PR’s), if accepted a week before release, are also released with 4.0!
I would also like to emphasize that NLog is a fully open source project. So also the roadmap and internal discussions are open. If you’re interested in the NLog process and discussions, just look at the discussions at the Github issues list
NLog 3.2.1 has been released yesterday. The release contains the following bug fixes:
LogManager.Configuration.Variables.Unit tests have been added for the above issues to prevent regression bugs. Details of the bug fixes can be seen on the GitHub milestone
Last, but certainly not least: thanks for reporting these issues!
The release candidate of NLog 4.0 is online. More than 100 issues are closed in GitHub. The release candidate can be downloaded from NuGet.
First of all, thanks for the reported issues and requested features!
This release contains the following features:
The FileTarget can now compress the archived files to zip format.
Example: set EnableArchiveFileCompression in config file:
<targetname="file"xsi:type="File"layout="${longdate} ${logger} ${message}"fileName="${basedir}/logs/logfile.txt"archiveFileName="${basedir}/archives/log.{#}.txt"archiveEvery="Day"archiveNumbering="Rolling"maxArchiveFiles="7"enableArchiveFileCompression="true"/>Logging of exceptions is now more consistent and complete than before. This is a breaking change.
All the logger methods, such as .Debug, Error etc. now contains a first optional parameter of the type Exception.
Only this parameter would be written as Exception to the log and can be used in the layout renderer, for example ` ${exception:format=tostring}`.
Exception parameter. E.g. Error(Exception exception, string message, params object[] args).IFormatProvider as parameter.Changes that are not backwards-compatible.
* removed “exceptionCandidate” hack: Log(string message, Exception ex) would write to exception property instead of message. This is non-backwards compatible in behaviour!
* all other “exception methods”: Eg. ErrorException and Error(string message, Exception exception) are marked as Obsolete, also in the interfaces.
//NLog 4.0Logger.Error(ex,"ow noos");Logger.Error(ex,"ow noo {0}","s");//ObsoleteLogger.ErrorException(ex,"ow noos");//BREAKING CHANGE: no compile error, but exception is used in message formatting.Logger.Error("ow noos",ex);//don't do this.//consistent with:Logger.Error("ow noos {0}",var1");In extreme cases logging could affect the performance of your application. There is a small overhead when writing a lot of log messages, like Tracing.
In this case it’s now possible to only include the Trace and Debug call with a debug release.
Instead of:
Logger.Trace("entering method {0}",methodname);Use:
Logger.ConditionalTrace("entering method {0}",methodname);This call will be removed by the .Net compiler if the DEBUG conditional compilation symbol is not set – default on a release build.
Assemblies with the name “NLog*.dll”, like “NLog.CustomTarget.dll” are now loaded automatically. This assembly should be in the same folder as NLog.dll.
Of course you can load NLog extensions manually with the <Extensions> config
A new layout renderer which outputs all of the event’s properties. Format and separator can be manually configured. Usage examples:
${all-event-properties}${all-event-properties:Separator=|}${all-event-properties:Separator= | :Format=[key] is [value]}This combines nicely with the fluent interface introduced in 3.2.0.
Examples:
varlogger=LogManager.GetCurrentClassLogger();logger.Info().Message("This is a test fluent message '{0}'.",DateTime.Now.Ticks).Property("Test","InfoWrite").Property("coolness","200%").Property("a","not b").Write();${all-event-properties} this would produce: Test=InfoWrite, coolness=200%, a=not b${all-event-properties:Format=[key] is [value]} this would produce: Test is InfoWrite, coolness is 200%, a is not bA new layout that renders log events as structured JSON documents. Example:
<targetname="jsonFile"xsi:type="File"fileName="${logFileNamePrefix}.json"><layoutxsi:type="JsonLayout"><attributename="time"layout="${longdate}"/><attributename="level"layout="${level:upperCase=true}"/><attributename="message"layout="${message}"/></layout></target>would write: { "time": "2010-01-01 12:34:56.0000", "level": "ERROR", "message": "hello, world" }
The behavior of the final attribute has been changed. Example:
<loggername="logger1"level="Debug"final=true/>Before 4.0 it would mark all messages from the logger “logger1” as final. In 4.0 it will only mark the debug messages as final.
When writing to the Eventlogger, NLog would writes to Information, Warning or Error entrytype, depending on the level. This is now configurable (with layout renderes) and offers the opportunity to write also a FailureAudit or SuccessAudit and/or use it with conditions.
EventLogTarget.Source now accepts layout-renderers. Note: layout renderers can not be used when in- or uninstalling the target. Console- and ColorConsole target has an encoding property.${appdomain}, ${appdomain:format=short} or ${appdomain:format=long}.CallSiteLineNumber layout renderer. usage: ${callsite-linenumber}SkipFrames option to the Stacktrace layout rendererWebserviceTarget has the option IncludeBOM. Possible options: null: doesn’t change BOM.true: always include UTF-8 BOM UTF-8 encodings.false: default, always skip BOM on UTF-8 encodings.FileTarget uses time from the current TimeSource for date-based archiving. LogReceiverTarget is now possibleMailtarget has less required parameters (at least To, CC or BCC should be set) and the Mailtarget logs their errors correctly to the internal logger now. Counter.Sequence now accepts layout renderers.Over 30 bugs has been solved. The full list can be viewed on Github.
The most noticeable bugs:
DatabaseTarget.CommandType could lead to exceptionsLogmanager.GetCurrentClassLogger was not thread-safe and with many concurrent calls it would throw an exception.WebserviceTarget wrote encoded UTF-8 preamble.NLog 4.0 has some breaking changes. To sum up:
LoggingRule.Final behaviour has been changed.Please note that the wiki hasn’t been updated yet.
Any feedback or issues to report? Please post them in this GitHub issue or create a new issue.
NLog 4.0 has been released! More than 100 issues are closed in GitHub. The release can be downloaded from NuGet.
We had a small delay (less than a week) on releasing this version. We underestimated the need for a release candidate and the time needed for documenting a changes on the wiki .
Thanks again for the reported issues and requested features!
This post is almost identical to the release candidatie news post
This release contains the following features:
The FileTarget can now compress the archived files to zip format.
Example: set EnableArchiveFileCompression in config file:
<targetname="file"xsi:type="File"layout="${longdate} ${logger} ${message}"fileName="${basedir}/logs/logfile.txt"archiveFileName="${basedir}/archives/log.{#}.txt"archiveEvery="Day"archiveNumbering="Rolling"maxArchiveFiles="7"enableArchiveFileCompression="true"/>Because we use the standard stuff of .Net for this, it’s only available in .Net 4.5 and higher.
Logging of exceptions is now more consistent and complete than before. This is a breaking change.
All the logger methods, such as .Debug, Error etc. now contains a first optional parameter of the type Exception.
Only this parameter would be written as Exception to the log and can be used in the layout renderer, for example ` ${exception:format=tostring}`.
Exception parameter. E.g. Error(Exception exception, string message, params object[] args).IFormatProvider as parameter.Changes that are not backwards-compatible.
* removed “exceptionCandidate” hack: Log(string message, Exception ex) would write to exception property instead of message. This is non-backwards compatible in behaviour!
* all other “exception methods”: Eg. ErrorException and Error(string message, Exception exception) are marked as Obsolete, also in the interfaces.
//NLog 4.0Logger.Error(ex,"ow noos");Logger.Error(ex,"ow noo {0}","s");//ObsoleteLogger.ErrorException(ex,"ow noos");//BREAKING CHANGE: no compile error, but exception is used in message formatting.Logger.Error("ow noos",ex);//don't do this.//consistent with:Logger.Error("ow noos {0}",var1");In extreme cases logging could affect the performance of your application. There is a small overhead when writing a lot of log messages, like Tracing.
In this case it’s now possible to only include the Trace and Debug call with a debug release.
Instead of:
Logger.Trace("entering method {0}",methodname);Use:
Logger.ConditionalTrace("entering method {0}",methodname);This call will be removed by the .Net compiler if the DEBUG conditional compilation symbol is not set – default on a release build.
Assemblies with the name “NLog*.dll”, like “NLog.CustomTarget.dll” are now loaded automatically. This assembly should be in the same folder as NLog.dll.
Of course you can load NLog extensions manually with the <Extensions> config
A new layout renderer which outputs all of the event’s properties. Format and separator can be manually configured. Usage examples:
${all-event-properties}${all-event-properties:Separator=|}${all-event-properties:Separator= | :Format=[key] is [value]}This combines nicely with the fluent interface introduced in 3.2.0.
Examples:
varlogger=LogManager.GetCurrentClassLogger();logger.Info().Message("This is a test fluent message '{0}'.",DateTime.Now.Ticks).Property("Test","InfoWrite").Property("coolness","200%").Property("a","not b").Write();${all-event-properties} this would produce: Test=InfoWrite, coolness=200%, a=not b${all-event-properties:Format=[key] is [value]} this would produce: Test is InfoWrite, coolness is 200%, a is not bA new layout that renders log events as structured JSON documents. Example:
<targetname="jsonFile"xsi:type="File"fileName="${logFileNamePrefix}.json"><layoutxsi:type="JsonLayout"><attributename="time"layout="${longdate}"/><attributename="level"layout="${level:upperCase=true}"/><attributename="message"layout="${message}"/></layout></target>would write: { "time": "2010-01-01 12:34:56.0000", "level": "ERROR", "message": "hello, world" }
The behavior of the final attribute has been changed. Example:
<loggername="logger1"level="Debug"final=true/>Before 4.0 it would mark all messages from the logger “logger1” as final. In 4.0 it will only mark the debug messages as final.
When writing to the Eventlogger, NLog would writes to Information, Warning or Error entrytype, depending on the level. This is now configurable (with layout renderes) and offers the opportunity to write also a FailureAudit or SuccessAudit and/or use it with conditions.
EventLogTarget.Source now accepts layout-renderers. Note: layout renderers can not be used when in- or uninstalling the target. Console- and ColorConsole target has an encoding property.${appdomain}, ${appdomain:format=short} or ${appdomain:format=long}.CallSiteLineNumber layout renderer. usage: ${callsite-linenumber}SkipFrames option to the Stacktrace layout rendererWebserviceTarget has the option IncludeBOM. Possible options: null: doesn’t change BOM.true: always include UTF-8 BOM UTF-8 encodings.false: default, always skip BOM on UTF-8 encodings.FileTarget uses time from the current TimeSource for date-based archiving. LogReceiverTarget is now possibleMailtarget has less required parameters (at least To, CC or BCC should be set) and the Mailtarget logs their errors correctly to the internal logger now. Counter.Sequence now accepts layout renderers.Over 30 bugs has been solved. The full list can be viewed on Github.
The most noticeable bugs:
DatabaseTarget.CommandType could lead to exceptionsLogmanager.GetCurrentClassLogger was not thread-safe and with many concurrent calls it would throw an exception.WebserviceTarget wrote encoded UTF-8 preamble.NLog 4.0 has some breaking changes. To sum up:
LoggingRule.Final behaviour has been changed.With the release of NLog 4.0 we have split the package NLog.Extended to NLog.Web and NLog.Windows.Forms. This will give us the opportunity to clean up the references in NLog.Extended. There are also some targets and layout renderers still in NLog.Extended, we will also create new packages for those in the future.
For now this this will results in:
${appsetting} layout renderer. Version 4.0 is compatible with NLog 4.0This wasn’t communicated in the initial NLog 4.0 release post - which could lead to upgrade issues - we are sorry for that.
The wiki has been updated to make more clear which Targets and which Layout Renderers are in each package.
The new extension packages, NLog.Web and NLog.Windows.Forms have their own GitHub reposities. Please post questions, feature requests or bug reports to the related repository.
Because we introduced auto load of extentions in NLog 4.0 (see news post), there is no need for additional configuration. Just install NLog.Web, NLog.Windows.Forms and/or NLog.Extended with Nuget.
We just released a patch release for 4.0. This release fixes the following problems:
MailTarget. The SMTP property is not required anymore. This is consistent with 3.x.OverflowExceptions in 64-bit runtime. This was a bug since NLog 2.0.Thanks for reporting those issues and creating Pull Requests! Without your help we could not release of 4.0.1 on short time.
PS: details of the fixed issues can be found on the GitHub 4.0.1 milestone.
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.
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!
I will describe creating your own layout renderer and custom target in this post.
Create a class which inherits from NLog.LayoutRenderers.LayoutRenderer, set the [LayoutRenderer("your-name"] on the class and override the Append(StringBuilder builder, LogEventInfo logEvent) method.
Invoke in this method builder.Append(..) to render your custom layout renderer.
We create a ${hello-universe} layout renderer, which renders… “hello universe!”.
[LayoutRenderer("hello-universe")]publicclassHelloUniverseLayoutRenderer:LayoutRenderer{protectedoverridevoidAppend(StringBuilderbuilder,LogEventInfologEvent){builder.Append("hello universe!");}}Just create public properties on the layout renderer. The properties can be decorated with the [RequiredParameter] and [DefaultParameter] attributes.
With the [RequiredParameter] attribute, NLog checks if this property has a value and throws an exception when it hasn’t.
The property names are required in your config by default. The property name of the first value can be skipped, if the property is decorated with the [DefaultParameter] attribute - see the examples below.
It’s not required for the property to be a string.
NLog takes care of the appropriate conversions when necessary. You can use, inter alia, the following types for the properties: integer, string, datetime and boolean.
For example:
[LayoutRenderer("hello-universe")]publicclassHelloUniverseLayoutRenderer:LayoutRenderer{/// <summary>/// I'm not required/// </summary>publicstringConfig1{get;set;}/// <summary>/// I'm required! /// </summary> [RequiredParameter]publicstringConfig2{get;set;}/// <summary>/// Hi! I'm the default parameter. You can also set me as required./// </summary> [DefaultParameter]publicboolCaps{get;set;}Example usages:
${hello-universe} - Raises exception: required parameter “Config2” isn’t set.${hello-universe:Config2=abc} - OK, “Config2” property set.${hello-universe:true:config2=abc} - Default parameter “Caps” set to true.${hello-universe:true:config2=abc:config1=yes} - All the three properties set.Creating a custom target is almost identical 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.
An example of a custom target:
[Target("MyFirst")]publicsealedclassMyFirstTarget:TargetWithLayout{publicMyFirstTarget(){this.Host="localhost";} [RequiredParameter]publicstringHost{get;set;}protectedoverridevoidWrite(LogEventInfologEvent){stringlogMessage=this.Layout.Render(logEvent);SendTheMessageToRemoteHost(this.Host,logMessage);}privatevoidSendTheMessageToRemoteHost(stringhost,stringmessage){// TODO - write me }}The property “host” is a configurable option to this target. You can pass the value as attribute in the config: <layout type="myFirst" host="test.com" />
First put your custom target or layout renderer in a separate assembly (.dll). Then you should register your assembly. Starting from NLog 4.0, assemblies with the name “NLog*.dll”, such as “NLog.CustomTarget.dll” are now registered automatically - they should be in the same folder as “NLog.dll”.
If that’s not the case you should register your assembly manually: reference your assembly from the the config file using the <extensions /> clause. Only the assembly name is needed (without “.dll”).
Configuration file example:
<nlog><extensions><addassembly="MyAssembly"/></extensions><targets><targetname="a1"type="MyFirst"host="localhost"/><targetname="f1"type="file"layout="${longdate} ${hello-universe}"fileName="${basedir}/logs/logfile.log"/></targets><rules><loggername="*"minLevel="Info"appendTo="a1"/><loggername="*"minLevel="Info"appendTo="f1"/></rules></nlog>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.
staticvoidMain(string[]args){//layout rendererConfigurationItemFactory.Default.LayoutRenderers.RegisterDefinition("hello-universe",typeof(MyNamespace.HelloUniverseLayoutRenderer));//targetConfigurationItemFactory.Default.Targets.RegisterDefinition("MyFirst",typeof(MyNamespace.MyFirstTarget));// start logging here }This year the NLog project has grown a lot:
However, we want to grow even more. We’d like to:
Currently the NLog team consists of two people. If we want to develop NLog further, we need more horsepower! And so we are looking for developers!
If you are interested in contributing to one of the most popular .Net libraries –we are ranked in the top 100 of NuGet, and when excluding the non-.Net and Microsoft packages, we rank in the top 10.– then get in touch with us on Gitter or Github :)
Get in touch with us on Gitter or Github :)
A new version of NLog has been released!
We fixed around 25 bugs, added some new features and made the migration of NLog 3 to 4 easier. The release can be downloaded from NuGet.
Check for all the details the GitHub 4.1 milestone.
This release contains the following features:
Since 4.0 you can read the variables defined in the configuration file. We also claimed you could change the values, but we were wrong… The variables where implemented like a kind of macros and changing them would not give the expected results.
In NLog 4.1, we created a new method to render the variables, which fits a lot better in the NLog library: we created a layout renderer for the variables! With the same syntax you can define the variables, but rendering is a bit different.
In NLog 4.0 you would define:
<nlog><variablename='user'value='admin'/><variablename='password'value='realgoodpassword'/><targets><targetname='debug'type='Debug'layout='${message} and ${user}=${password}'/></targets><rules><loggername='*'minlevel='Debug'writeTo='debug'/></rules></nlog>In 4.1 you can use the $var{} layout renderer:
<nlog><variablename='user'value='admin'/><variablename='password'value='realgoodpassword'/><targets><targetname='debug'type='Debug'layout='${message} and ${var:user}=${var:password}'/></targets><rules><loggername='*'minlevel='Debug'writeTo='debug'/></rules></nlog>What’s the real advantage here?
${var:password:default=unknown}You might wonder: why has the old method not been replaced? The answer is simple: the new method only works on Layout types and not on plain strings.
The context classes, GCD, MCD and NDC, now support using object values instead of strings. This is mostly beneficial from the API perspective.
The get method still returns a string - for backwards-compatibility reasons. We created a new method: getObject.
When writing to the logs, the object is converted to a string
GlobalDiagnosticsContext.Set("myDataBase","someValue");//already possibleGlobalDiagnosticsContext.Set("myDataBaseNumber",2);//4.1+With the release of NLog 4.0 we made some breaking changes. Those breaking changes made upgrading an issue: all the code has to be upgraded to NLog 4 at once.
The main cause was the change of behavior of Log(string message, Exception ex). This call should be replaced by Log(Exception ex, string message) in NLog 4.0.
Changing all those calls can be difficult at once. So we have introduced the following option:
<nlogexceptionLoggingOldStyle='true'>With this option enabled, you can still use Log(string message, Exception ex) in NLog 4.
So the upgrade path to NLog 4
Log(string message, Exception ex) etc.Note: we will remove this feature in NLog 5.0
New options have been added for writing JSON output.
<layoutxsi:type="JsonLayout"SuppressSpaces="false"><attributename="process_name"layout="${processname}"/><attributename="short_message"layout="${message}"/></layout><layoutxsi:type="JsonLayout"><attributename="Message"layout="${message}"encode="false"/></layout>Example call:
logger.Info("{ \"hello\" : \"world\" }");See the wiki
The NLog.Contrib code has been integrated with the core of NLog. The following features are now available on the NLog package:
${mdlc}${activityid} write the System.Diagnostics his trace correlation id.The all events layout renderer introduced in NLog 4.0 was unexpectedly writing caller information, like current method etc, to the targets. This is now an option and disabled by default.
For example:
${all-event-properties} writes “Test=InfoWrite, coolness=200%, a=not b” ${all-event-properties:includeCallerInformation=true} writes “Test=InfoWrite, coolness=200%, a=not b, CallerMemberName=foo, CallerFilePath=c:/test/log.cs, CallerLineNumber=1001”Officially introduced in NLog 4.0, but was not available due to a merge fault. The ${callsite-linenumber} writes the line number of the caller.
With the ${replace} layout renderer it was already possible to replace the newlines, but it was a bit tricky to use - different systems, different newlines.
The ${replace-newlines} layout renderer fixes this.
4.0.0 introduced an unattended breaking changing that replaced the WcfLogReceiverClient with the WcfLogReceiverClientFacade (NLog/NLog#783). It was not only a naming issue, but also some functionality was lost and there was a lot of code duplication.
Unfortunately, there was not an easy fix, so the following was done to try to make it less of a breaking change. The changes are still breaking, but minus a recompilation, the changes should be mostly transparent. See NLog/NLog#874 for all of the changes related to WCF Log Receiver.
Compared to 3.2.x, these the changes:
ILogReceiverTwoWayClient instead of ILogReceiverClient. ILogReceiverClient is still in the code, but is marked obsolete.ClientBase, then change it to WcfLogReceiverClientBaseCompared to 4.0.x, these the changes:
CreateWcfLogReceiverClient() in LogReceiverWebServiceTarget is WcfLogReceiverClient again, but is marked obsolete.CreateLogReceiver(), which returns IWcfLogReceiverClient to reduce breaking changes in the future.The event properties are object values. When writing them with ${event-properties} to the logs, the values are converted to strings. It’s now possible to control the culture and format.
Examples: ${event-properties:prop1:format=yyyy-M-dd} and ${event-properties:aaa:culture=nl-NL}
Various bugs are fixed in this version. The most notable ones:
4.0.1 did gave issues with configuration files or binaries hosted on UNC locations.
Multiple bugs are fixed with file archiving:
DeleteOldDateArchive could delete files not being actual archives. #847This release finally builds again on Mono! We are busy adding Travis CI integration to keep the Mono build working.
Writing an exception as only argument to a logger, like logger.Info(new Exception()) was not correctly registering the exception to the log messages.
Some small improved has been made to the internal logger.
We just released a new version of NLog which fixes a few issues in NLog 4.1.0.
In the NLog 4.1.1, the full name is the same as NLog 4.0.0 and 4.0.1.
If nuget is adding the following to your (main) .config:
<dependentAssembly><assemblyIdentityname="NLog"publicKeyToken="5120e14c03d0593c"culture="neutral"/><bindingRedirectoldVersion="0.0.0.0-4.1.0.0"newVersion="4.1.0.0"/></dependentAssembly>You should remove it, or change it to:
<dependentAssembly><assemblyIdentityname="NLog"publicKeyToken="5120e14c03d0593c"culture="neutral"/><bindingRedirectoldVersion="0.0.0.0-4.1.0.0"newVersion="4.0.0.0"/></dependentAssembly>We are sorry if the upgrade to 4.1.0 caused any issues. We are aware that the strong naming sometimes gives more issues than solving things and that versioning issues with strong naming are common. But some users need the strong name, and therefore we will keep it for at least version 4.
Download it from nuget!
Do you have a feature request or another idea how we can improve NLog?
We are now also on UserEcho, so vote or add ideas!
Happy coding, Julian
PS: if you like to have more status updates, just follow us on Twitter.
NLog 4.2 has been released. This release contains some small features and (important) bug fixes.
We take semver serious, so all changes are backwards-compatible.
pickupDirectoryLocation and deliveryMethod are configurable from the NLog config.clearCache option has been added for more control over clearing the cache. See wiki. .zip to compressed archive when archiveName isn’t specified. An inner layout can now contain colons, but it needs an escape.
It is required to escape : and } in an inner layout because:
: because it’s a value separator. ${when:when=1 == 1:Inner=Test\: Hello}} because it can be the end of another layout renderer when double nested. ${rot13:inner=${rot13:inner=${when:when=1 == 1:Inner=Test \} Hello}}}useSystemNetMailSettings was false, some settings were still used from the <mailSettings> of the .Net config.Improved document and error messages regarding the ‘type’ argument of Getcurrentclasslogger and GetLogger.
Please keep in mind:
- It should inherit from
Logger.- Instead of creating an instance of
Logger, it will create an instance ofloggerType.typeargument necessary when using custom Loggers. Most of the time it isn’t required to pass a type to those methods.
We improved other docs and internal logging in the code. Our code coverage has also been increased.
The NLog team has expanded greatly! We’d like to thank all the collaborators who have made this release possible:
Happy coding!
Julian (@304NotModified)
Release notes:
NLog.Windows.Forms 4.2 has been released including a new feature for the RichTextBoxTarget— it is now possible to add clickable links to log messages.
This release contains the following features:
It is now possible to add clickable links to messages show in in the RichTextBox control and receive whole event info in the link click handler.
To do this, set target’s newly introduced supportLink parameter to true and use new ${rtb-link} layout renderer to specify link part of the layout.
To receive link click events, add a handler to RichTextBoxTarget.LinkClicked event. Use RichTextBoxTarget.GetTargetByControl(RichTextBox control) static method to access the target attached to a specific RichTextBox control.
Not sure how to use it? Here are few examples.
When logging exceptions to RichTextBoxTarget you have to find a compromise between flooding the control with huge stacktraces and missing important information. Not anymore! Now you may long only a short description into textbox, and show whole details when user clicks a link:
Just setup a proper layout (don’t forget to enable supportLinks)
<targetxsi:type="RichTextBox"layout="${message}${onexception:inner= ${exception:format=Message} ${rtb-link:details}}"....supportLinks="true"..../>And add a link click handler:
publicForm1(){InitializeComponent();RichTextBoxTarget.ReInitializeAllTextboxes(this);//more on this laterRichTextBoxTarget.GetTargetByControl(richTextBox1).LinkClicked+=Form1_LinkClicked;}privatevoidForm1_LinkClicked(RichTextBoxTargetsender,stringlinkText,LogEventInfoevent){MessageBox.Show(event.Exception.ToString(),"Exception details",MessageBoxButtons.OK);}Sometimes you may need to not only notify user of some problem (like validation failing), but also help him navigate to the problematic item (for example when the list is huge). In this case you may store item’s id of some sort in the LogEventInfo.Property, turn it into a link and navigate to the item in link click handler:
The layout:
<targetxsi:type="RichTextBox"layout="${message} ${rtb-link:${event-properties:item=Index}}"....supportLinks="true"..../>Validation code:
privatevoidvalidateButton_Click(objectsender,EventArgse){logger.Info("Validation started");foreach(ListViewItemiteminlistView1.Items){if(item.SubItems[1].Text.Contains("bad")){logger.Info().Message("Validation failed on line").Property("Index",(int)item.Tag).Write();return;}}logger.Info("Validation succeeded");}Event handling code:
publicForm2(){InitializeComponent();RichTextBoxTarget.ReInitializeAllTextboxes(this);RichTextBoxTarget.GetTargetByControl(richTextBox1).LinkClicked+=Form2_LinkClicked;}privatevoidForm2_LinkClicked(RichTextBoxTargetsender,stringlinkText,LogEventInfoevent){intlineIndex=(int)event.Properties["Index"];listView1.EnsureVisible(lineIndex);listView1.SelectedIndices.Add(lineIndex);listView1.Select();}Hope you could find more useful applications of this new feature!
In case you are not sure whatRichTextBoxTarget.ReInitializeAllTextboxes(this)call does, then you might have missed a feature added in 4.1 release. It improves the RichTextBoxTarget functional by allowing it to be configured and initialized before the actual control is created. CheckallowAccessoryFormCreationandmessageRetentionoptions description in the target’s documentation
update 27 march: RC 2 is now online which resolves a bug in finding the correct stackframe in for ${callsite} etc. This was broken since 4.3-beta 1.
NLog 4.3 is almost ready. There are some changes in the core, so therefore a Release Candidate (RC) has been released. Right now there are 132 closed issues in NLog 4.3, which makes NLog 4.3 the largest release since years. We have had a lot of contributions from the community (thanks!) and have you noticed that NLog has more main contributors than before?
The release can be downloaded from NuGet.
Check for all the details the GitHub 4.3 milestone.
Please note that currently not all the docs have been updated yet.
This release contains the following features:
In NLog 4.3 support has been added for the following platforms: Windows Phone 8, Xamarin Android and Xamarin iOS. The support is still in beta as we didn’t get the unit tests running.
Not every feature is working on those platforms, for example auto reloading the configuration is not supported in Xamarin. A full overview of what is supported on each platform can be viewed on the wiki.
The logging and throwing of exceptions was previously inconsistent. Not all of it was logged to the internal logger and some times they got lost. For example, the async wrapper (or async attribute) was catching all exceptions without a proper rethrow.
This is bad as it is sometimes unclear why NLog isn’t working (got it myself multiple times). This has been fixed in NLog 4.3!
Advise: disable throwExceptions in production environments! (this the default)
<nlogthrowConfigExceptions="false">The following is stated in multiple locations: > By default exceptions are not thrown under any circumstances.
This was not true for configuration errors - those were always rethrown in the past. If you change the config at runtime, this could lead to exceptions to the users!
We now introduce the “throwConfigExceptions” option:
<nlogthrowConfigExceptions="true|false|<empty>">LogManager.ThrowConfigExceptions=true|false|nulltrue, if will throw exceptions for configuration errors.
Set this to true if you like the behaviour from NLog 4.2 and ealier.null in the API), this option will follow the “throwExceptions” option (previous section)false, don’t throw exceptions for configuration errors.Also throwing exceptions for a configuration error
could lead to System.TypeInitializationException which is bad and confusing as sending info with the exception is difficult or sometimes impossible
- see stackoverflow.
There are some notable changes in the API, so it’s easier to create or edit the configuration in C#
(or other .Net language).
The existence of the SimpleConfigurator was a hint things weren’t simple enough ;)
Changes:
LogManager has now AddRule methods. See examples below.LoggingRule constructor.TargetAttribute is used as fallback for every target now.LogManager now has AddRule methodsRules can now be created directly in the LogManager.
There are some overloads to keep things simple.
Before:
varconfig=newLoggingConfiguration();varfileTarget=newFileTarget();config.AddTarget("f1",fileTarget);config.LoggingRules.Add(newLoggingRule("*",LogLevel.Debug,LogLevel.Error,fileTarget));LogManager.Configuration=config;now also possible:
varconfig=newLoggingConfiguration();varfileTarget=newFileTarget("f1");config.AddTarget(fileTarget);config.AddRule(LogLevel.Debug,LogLevel.Fatal,"f1");LogManager.Configuration=config;or
varconfig=newLoggingConfiguration();varfileTarget=newFileTarget{name:"f1"};config.AddRule(LogLevel.Debug,LogLevel.Fatal,fileTarget);LogManager.Configuration=config;FileTarget now supports relative paths. No need for ${basedir} in the file target anymore!
It’s now possible to write to let the internal logger write to System.Diagnostics.Trace.
The trace is easy to follow within Visual Studio.
<nloginternalLogToTrace="true"or c#
InternalLogger.LogToTrace = true;
Smaller improvements
<connectionStrings>MappedDiagnosticsLogicalContextGetLogger() and GetCurrentClassLogger()Logger.Swallow(Task task)<NLog><appSettings>NLOG_INTERNAL_INCLUDE_TIMESTAMP environment settingLogManager.Configuration=newXmlLoggingConfiguration("assets/nlog.config");Various bugs have been fixed in this version. The most noticeable:
${callsite} works now for async methods!${basedir}${variable}${processtime}: incorrect milliseconds formatting${processtime}: fix incorrect negative time (rounding issue)We’re proud to announce that the former community project NLogAdapter is now part of NLog as NLog.Owin.Logging to provide a Microsoft.Owin.Logging.ILoggerFactory implementation for your OWIN pipeline.
Usage is as simple as:
PM > Install-Package NLog.Owin.LoggingusingNLog.Owin.Logging;publicclassStartup{publicvoidConfiguration(IAppBuilderapp){app.UseNLog();}}After three RC releases, NLog 4.3 has been released! With more than 150 issues closed, this is one of the largest release since years. Main features: Xamarin support, Windows Phone 8 support, improved error handling and logging of NLog self and a lot of bug fixes!
The release can be downloaded from NuGet.
Check for all the details the GitHub 4.3 milestone.
For those who have contributed to NLog, big thanks!
This release contains the following features:
In NLog 4.3 support has been added for the following platforms: Windows Phone 8, Xamarin Android and Xamarin iOS. The support is still in beta as we didn’t get the unit tests running.
Not every feature is working on those platforms, for example auto reloading the configuration is not supported in Xamarin. A full overview of what is supported on each platform can be viewed on the wiki.
The logging and throwing of exceptions was previously inconsistent. Not all of it was logged to the internal logger and some times they got lost. For example, the async wrapper (or async attribute) was catching all exceptions without a proper rethrow.
This is bad as it is sometimes unclear why NLog isn’t working (got it myself multiple times). This has been fixed in NLog 4.3!
Advise: disable throwExceptions in production environments! (this the default)
<nlogthrowExceptions="false">The following is stated in multiple locations: > By default exceptions are not thrown under any circumstances.
This was not true for configuration errors - those were always rethrown in the past. If you change the config at runtime, this could lead to exceptions to the users!
We now introduce the “throwConfigExceptions” option:
<nlogthrowConfigExceptions="true|false|<empty>">LogManager.ThrowConfigExceptions=true|false|nulltrue, if will throw exceptions for configuration errors.
Set this to true if you like the behaviour from NLog 4.2 and ealier.null in the API), this option will follow the “throwExceptions” option (previous section)false, don’t throw exceptions for configuration errors.Also throwing exceptions for a configuration error
could lead to System.TypeInitializationException which is bad and confusing as sending info with the exception is difficult or sometimes impossible
- see stackoverflow.
There are some notable changes in the API, so it’s easier to create or edit the configuration in C#
(or other .Net language).
The existence of the SimpleConfigurator was a hint things weren’t simple enough ;)
Changes:
LogManager has now AddRule methods. See examples below.LoggingRule constructor.TargetAttribute is used as fallback for every target now.LogManager now has AddRule methodsRules can now be created directly in the LogManager.
There are some overloads to keep things simple.
Before:
varconfig=newLoggingConfiguration();varfileTarget=newFileTarget();config.AddTarget("f1",fileTarget);config.LoggingRules.Add(newLoggingRule("*",LogLevel.Debug,LogLevel.Error,fileTarget));LogManager.Configuration=config;now also possible:
varconfig=newLoggingConfiguration();varfileTarget=newFileTarget("f1");config.AddTarget(fileTarget);config.AddRule(LogLevel.Debug,LogLevel.Fatal,"f1");LogManager.Configuration=config;or
varconfig=newLoggingConfiguration();varfileTarget=newFileTarget{name:"f1"};config.AddRule(LogLevel.Debug,LogLevel.Fatal,fileTarget);LogManager.Configuration=config;FileTarget now supports relative paths. No need for ${basedir} in the file target anymore!
It’s now possible to write to let the internal logger write to System.Diagnostics.Trace.
The trace is easy to follow within Visual Studio.
<nloginternalLogToTrace="true"or c#
InternalLogger.LogToTrace = true;
Smaller improvements
<connectionStrings>MappedDiagnosticsLogicalContextGetLogger() and GetCurrentClassLogger()Logger.Swallow(Task task)<NLog><appSettings>NLOG_INTERNAL_INCLUDE_TIMESTAMP environment settingVarious bugs have been fixed in this version. The most noticeable:
${callsite} works now for async methods!${basedir}${variable}${processtime}: incorrect milliseconds formatting${processtime}: fix incorrect negative time (rounding issue)We have the following releases planned for NLog:
Originally NLog 4.4 would have .NET Core support. We have released multiple alpha and beta releases with support .NET Core (or to be precise .NET Standard).
Unfortunately, there is a show-stopper: the behavior of GetCurrentClassLogger is wrong and we can’t fix it as the StackTrace API is limited in .NET Core
(see here). You can read more about it here.
We will postpone .NET Core support to NLog 5.
Will this delay a RTM with .NET Core support? Yes. As long as the StackTrace API is missing, we can’t fix it. It seems that .NET Standard 2 (Q1 2017) will support the StackTrace API.
Currently, some mistakes in the config could lead to no logging at all.
For example, if ${aspnet-item} is used in the file target and NLog.Web was not included, no files are written.
We will fix this in NLog 4.4 and we will replace the wrong part with an empty string. See this PR.
A lot of feature requests could be easily implemented by writing a custom target or layout renderer. Currently it’s a bit difficult to register your custom code. We will improve that. Also a custom layout renderer should be as easy as one line of code:
LayoutRenderer.RegisterLayoutRenderer("trace-identifier", (logEvent) => HttpContext.Current.TraceIdentifier );Currently under development, thanks to @bjornbouetsmith and @snakefoot!
This change will decrease memory pressure and prevent (excessive) garbage collection.
For details, see PR 1397 and and PR 1663
We would like to support structural logging like Serilog. We are currently working on an own parser and renderer. More info here.
NLog 5 will have .NET Core support and we will push some small breaking changes.
NLog 6 will split all the functionality to multiple packages. Why is this not the case in NLog 5? Well the .NET Core support consists of more than 250 commits and almost 400 changed files. If something is broken by those changes, it’s easier to find the previous code if we won’t move all the code around!
NLog 4.4 contains new features, performance improvements and makes it easier to write custom components (e.g. targets, layout renderers) for NLog!
A lot of stuff has been contributed by the community! Thanks for making NLog great!
The WebServiceTarget was always a bit odd as it was posting the data Form-encoded (application/x-www-form-urlencoded). This has now been fixed with the support for JSON and XML, just pick one!
Example
<targettype='WebService'name='ws'url='http://localhost:1234/logme'protocol='JsonPost'encoding='UTF-8'><parametername='param1'type='System.String'layout='${message}'/><parametername='param2'type='System.String'layout='${level}'/></target>With the support of JSON in the WebServiceTarget, it can be important to give the opportunity to choose your JSON serializer implementation. This implementation will be also used for all other JSON serialization in NLog, like the JsonLayout.
We really like JSON.NET, but we don’t like to depend on it! It’s a great library, but it can lead to issues with strong names and other versions in your project. See also the statement of RestSharp library (which is also a great library)
So we now have our own implementation, which is sufficient for most cases.
Do you like to choose your implementation? Implement SerializeObject(..) in IJsonSerializer and set it to ConfigurationItemFactory.JsonSerializer.
The JsonLayout has two new properties which will help you creating better JSON documents:
Example:
<layoutxsi:type="JsonLayout"includeAllProperties="true"excludeProperties="BadPropertyName1, BadProperty2"><fieldname="message"layout="My message for you is this ${message}"/></layout>Previously, if you made an error in a layout, e.g. typos:
<targetname="file"xsi:type="File"layout="${message} ${oops-I-made-a-typo}">or just using a layout renderer from a non-included package, nothing got logged!
This is unneccesary and we are skipping the invalid parts now. The invalid parts are replaced with an empty string.
NB: If throwExceptions or throwConfigExceptions is true, there will be still an error thrown
Layout renders (those things between ${}) can help you writing context information.
Since NLog 4.4 there is a new way to create a custom layout renderer, which can be written on one line!
The new LayoutRenderer.Register accepts a lamba function,
which accepts 1 or 2 parameters and should return a string.
logEventInfo.logEventInfo and the current NLog config.Examples
//register ${text-fixed}LayoutRenderer.Register("test-fixed",(logEvent)=>"2");//register ${trace-identifier}LayoutRenderer.Register("trace-identifier",(logEvent)=>HttpContext.Current.TraceIdentifier);//Using logEventInfo, ${message-length}LayoutRenderer.Register("message-length",(logEvent)=>logEvent.Message.Length);//Using config, ${targetCount}LayoutRenderer.Register("targetCount",(logEvent,config)=>config.AllTargets.Count);See the wiki
There is a new syntax introduced so it’s easier to register your custom extensions:
//targetTarget.Register<MyNamespace.MyFirstTarget>("MyFirst");//genericTarget.Register("MyFirst",typeof(MyNamespace.MyFirstTarget));//OR, dynamic//layout rendererLayoutRenderer.Register<MyNamespace.MyFirstLayoutRenderer>("MyFirst");//genericLayoutRenderer.Register("MyFirst",typeof(MyNamespace.MyFirstLayoutRenderer));//dynamic//layoutLayout.Register<MyNamespace.CsvLayout>("csv");//genericLayout.Register("csv",typeof(MyNamespace.CsvLayout));//dynamicFor more info, see the wiki
Custom Targets, layout etc. can have properties. There are only limitations if you’d like to set them from the XML config.
The following types are supported:
Allowed types for Targets, Layouts and Layout renderers.
EncodingCultureInfoTypeLineEndingModeUriLayout, SimpleLayout& ConditionExpressionstringTypeDescriptor from string (not Silverlight)Introduced in NLog 4.4, the following collection types can be used.
Usage in XML: comma separated string. If the value contains a comma, single quote the whole value.
Examples:
value="one arg"value="1,2"value="value1,'value2, with comma'"Collections of type:
IList<T> / IListIEnumerable<T> / IEnumerableISet<T> / HashSet<T>with the following types:
Not supported:
ListIListPS: .NET 3.5 has HashSet but no ISet
Something you would like to flush in special cases only, e.g. sending a mail when there is an error. Of course you would like to have the trace logs in your mail too, as that can help identifying the problem!
This is now possible by using the Condition property on AutoFlushWrappper
Example:
<targetname="file"xsi:type="AutoFlushWrapper"condition="level >= LogLevel.Error"><targetxsi:type="BufferingWrapper"..><targetname="gmail"xsi:type="Mail"smtpServer="smtp.gmail.com"smtpPort="587"smtpAuthentication="Basic"/></target></target>Like sending mail but not every 10 seconds? With the LimitingTargetWrapper you can control the maximum events per interval.
Example, max 5 messages per 10 minutes
<targetname='limiting'type='LimitingWrapper'messagelimit='5'interval='0:10:00'><targetname="gmail"xsi:type="Mail"smtpServer="smtp.gmail.com"smtpPort="587"smtpAuthentication="Basic"/></target>In Windows there is a new file writing implementation. From tests we have 10-40% performance increase!
The URL encoding for the WebServiceTarget was not behaving to any RFC as far as we know. This has been changed!
For the WebServiceTarget & ${UrlEncode},
NLog will by default encode parameters as UTF8 and escape special characters according to Rfc2396.
Also the following properties have been added to WebServiceTarget & ${UrlEncode}
truetrue${exception} - Added support for AggregateExceptionconcurrentWrites="true" and keepFileOpen="true"[Obsolete] warnings - include the Nlog version when it became obsoleteThanks for the contributions!
Structural logging!
We could use your help to introduce this feature soon!
Like to help with coding or testing? Please let us know!
