NLog

Moving NLog Forward

2012-07-23T00:00:00-07:00

Dear NLog Community,

It’s been almost exactly a year since NLog 2.0 was released. Since v1.0 release in 2006 NLog has been very popular among .NET developers, but as you may have noticed, the development has stagnated a bit after 2.0 release.

In the last 6 months or so I found myself having less and less free time to spend on coding in general, and developing NLog in particular. The fact that my day job now involves programming in Java and not .NET does not really help.

NLog clearly needs your help to remain the coolest logging library for .NET: I’m looking for a passionate person, a group of people or a company, who could gradually take over the responsibility of running NLog project and moving it forward.

It involves planning, managing automated builds, releases, bugs, forums, wiki, running website, NuGet, tools, integrating community contributions, etc. The reward is huge: thousands of satisfied developers, who have downloaded NLog 2.0 about 100.000 times in the last year alone!

Please contact me if you’re interested in owning part of NLog’s future at jaak@jkowalski.net or post on the Forum.

Using NLog with Mono

2011-10-30T00:00:00-07:00

After releasing NLog 2.0 a number of people have reported problems with running on latest versions of Mono. Basically at the end of program execution (after the Main() has finished) the program locks up waiting for NLog logs to be flushed, so mono process never completes and needs to be killed.

This behavior is only specific to NLog 2.0 - NLog 1.0 did not exhibit this behavior. It seems to be related to threading and timers used by NLog 2.0 which are somehow not available in Mono when the program is about to be terminated. The same code works with .NET just fine. I haven’t fully investigated this issue - maybe Mono folks can see if this issue can be fixed in Mono itself?

Anyway - there is a simple way prevent the deadlock: just make sure you set LogManager.Configuration property to null before your application exits. This will cause Flush() to be executed before Main() finishes and will prevent appdomain unload handler from locking up.

In NLog 2.0.0.2005 (nightly build - available on CodePlex, source code on GitHub as usual) I have disabled automatic flushing of logs in Mono builds. That means that when running on Mono (same as with Silverlight and .NET Compact Framework), it is developer’s responsibility to flush logs before program exits. I’m hoping to restore automatic flushing behavior when the issue is fixed in Mono or if I can find a way to work around the problem.

NLog 2.0 has been released!

2011-07-17T00:00:00-07:00

It is my great pleasure to announce that NLog 2.0 has been released.

NLog 2.0 release is focused on adding support for new platforms (Silverlight, .NET Framework 4, Windows Phone 7.x), improving logging architecture and manageability and addressing most frequently reported user issues.

Binaries can be downloaded from CodePlex.
Sources are available at GitHub.
NuGet packages are also available.

You can read the release notes at http://nlog-project.org/nlog-2-0-release-notes.html.

NLog 2.0 Release Candidate is now available

2011-06-17T00:00:00-07:00

It is our pleasure to announce that the Release Candidate (RC) of NLog 2.0 is now available for download. This is the last milestone before NLog 2.0 final release.

Binary downloads are available on CodePlex
Source code on GitHub
Full release notes can be found here.

Please download the release and report any problems you may find. Assuming no critical issues are found, NLog 2.0 will be released within a month from the RC release.

Exception logging enhancements

2011-04-20T00:00:00-07:00

One of the frequent feature requests I’ve been getting was to improve the way exceptions are logged. Recent builds of NLog 2.0 include several usability enhancements that should make working with exceptions much easier.

Conditional formatting

Conditional logging allows you to make your layouts somewhat more dynamic - you can include/exclude fields based on conditions, provide default values and so on. In order to achieve this, you have 3 new layout renderers at your disposal.

${onexception:INNER} - output

To render a layout when the exception is being logged, use ${onexception:INNER}, it will output INNER only when current log event includes an exception (in other words when it was emitted using any of the Logger.Exception() methods. INNER can include other layouts, for example:

<targets>
  <target name="f" type="File" layout="${message}${onexception:EXCEPTION OCCURRED\:${exception:format=tostring}}" />
</targets>

It will output log message, but in case of exception, it will also log detailed exception information prefixed with “EXCEPTION OCCURRED:”.

${when} - advanced conditional formatting

You can also conditionally include or exclude layout renderers based on conditions by using ${when} layout renderer wrapper. You can even use ambient property called “when” as if it were declared on any other layout renderer:

For example ${message:when=logger==’logger’} will only print the message when it was emitted by ‘logger’. The conditions can be much more complex - you have the full power of conditions language at your disposal.

${whenEmpty} - empty value coalescing

Sometimes you may want to print an indication that a layout renderer has produced an empty value, instead of completely skipping its output. That’s where ${whenEmpty} layout renderer wrapper comes in handy. You can also use the ambient property form, just by using ‘whenEmpty’ property in any other layout renderer. For example:

${message:whenEmpty=(no message)}

Inner exception logging

Recent builds also include improvements to ${exception} layout renderer which now lets you output inner exceptions. There are several new properties:

${exception:maxInnerExceptionLevel=N} - controls how many inner exceptions are logged. defaults to zero for backwards compatibility.
${exception:innerExceptionSeparator=TEXT} - defines text that separates inner exceptions. Defaults to new line string (platform specific).
${exception:innerFormat=FORMATSTRING} - defines the format of inner exceptions the same way that ${exception:format=FORMATSTRING} defines the format of the top-level exception. If this parameter is not specified, the same format is used for both top-level and inner exceptions.

A complete usage example is:

<targets>
  <target name="f" type="File" layout="${message}${onexception:EXCEPTION OCCURRED\:${exception:format=type,message,method:maxInnerExceptionLevel=5:innerFormat=shortType,message,method}}" />
</targets>

This will print top-level exception with full type name, message and method that raised the exception, but for inner exceptions only short type name is used instead.

As always, comments and suggestions are welcome.

Simplifying NLog.Extended.dll usage

2011-04-14T00:00:00-07:00

I’d like to let you know about small simplification to using targets and layout renderers from NLog.Extended.dll. Previously you had to register them using configuration section:

<extensions>
  <add assembly="NLog.Extended" />
</extensions>

Starting with today’s Nightly build, this is no longer required - you can simply use extended items without extra registration (exactly like it worked in NLog 1.0). The only change is that you must have NLog.Extended.dll in the same directory as NLog.dll - you will get exception if it’s not present.

If you need NLog.Extended, please give this feature a try and report any issues you find.

NLog for Windows Phone 7

2011-01-09T00:00:00-08:00

This week I have checked in a port of NLog 2.0 for Windows Phone 7. It’s still very experimental and the intention of this release is to get feedback from people. Please use at your own risk.

Current build supports 8 targets:

Console - can be used to write logs to the console (only works in Emulator - see this post for instruction on how to enable console output)
Memory - stores traces in memory
MethodCall - runs user-provided method for each log message
Network, NLogViewer and Chainsaw - write XML-formatted log event over the network. Only HTTP:// and HTTPS:// protocols are supported.
WebService - sends log events to a web service using SOAP or POST
LogReceiverService - sends log events to LogReceiver web service using WCF

Note that File target and several others are not included because of current constraints of the platform APIs.

Here is a simple step-by-step tutorial for adding NLog to your WP7 app:

Download and install the bits

Go to http://nlog.codeplex.com/releases and download one of the recent nightly builds - choose build later than 2011/1/9
Pick a package named = NLog2-All-.msi (includes builds for all platforms - recommended) or NLog2-WP-.msi (which includes only WP7 bits).
Run the setup and wait - setup will add code snippets and templates for all development environments you have on the machine, which can take some time (couple minutes, so be patient)

Add NLog to your Windows Phone app project

Open your project
Add NLog.config to your project - the easiest way is to select ’Add new item’ and choose ’Empty NLog Configuration File’ from the ’NLog’ section.

This will also add a reference to NLog:

If you prefer, you manually add reference to ”C:\Program Files (x86)\NLog\Silverlight for Windows Phone 7\NLog.dll” instead and create NLog.config manually
One last thing is changing Build Action for NLog.config to ’Content’ (this ensures that the file will be included in the XAP package).

Set logging configuration

In this tutorial we will use LogReceiverService target, but you can use any other target supported by NLog. To do this open NLog.config and paste the following configuration:

<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <targets>
      <target xsi:type="LogReceiverService" name="webService" endpointAddress="http://localhost:5000/LogReceiver.svc"/>
    </targets>

    <rules>
      <logger name="*" minlevel="Debug" writeTo="webService" />
    </rules>
</nlog>

Emit log messages

To emit log messages you need to get a Logger instance from LogManager and call one of the log methods. See .NET Logging API for more information. Let’s add some logging code to MainPage.xaml.cs:

namespace WindowsPhoneApplication2
{
    using System.Windows;
    using Microsoft.Phone.Controls;

    public partial class MainPage : PhoneApplicationPage
    {
        private static NLog.Logger logger = NLog.LogManager.GetCurrentClassLogger();

        // Constructor
        public MainPage()
        {
            InitializeComponent();
            logger.Info("Main page loaded.");
        }

        private void button1_Click(object sender, RoutedEventArgs e)
        {
            logger.Debug("Button 1 clicked.");
        }

        private void button2_Click(object sender, RoutedEventArgs e)
        {
            logger.Debug("Button 2 clicked.");
        }
    }
}

When you run the code, log messages will be sent to http://localhost:5000/LogReceiver.svc

Receive log messages

In order to receive log messages you need to have an endpoint that implements ILogReceiverServer contract. NLog comes with an example that does just that and listens on (incidentally) http://localhost/LogReceiver.svc , or if you prefer you can implement your own server. You can find it the example in the source code under examples\NLogReceiverForwarderService. The sample will basically forward NLog messages received from the network through NLog running on the server machine.

Download NLog source code
Open the project file examples\NLogReceiverForwarderService\NLogReceiverForwarderService.csproj (Visual Studio needs to be running as an Administrator)
Edit NLog.config and adjust log outputs as necessary.
Run the project. Notice how when you click on buttons in your Windows Phone 7 application, the logs are displayed on your console:

Let’s do more…

Having rich NLog do log routing on both client and server opens a lot of possibilities. You can for example send much richer information from the client to the server. In order to do this we’ll be using parameters. Let’s modify client side configuration to send thread id along with each log message:

<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <targets>
      <target xsi:type="LogReceiverService" name="webService" endpointAddress="http://localhost:5000/LogReceiver.svc">
        <parameter name="t" layout="${threadid}" />
      </target>
    </targets>

    <rules>
      <logger name="*" minlevel="Debug" writeTo="webService" />
    </rules>
</nlog>

On the server side, we can now extract ‘t’ parameter using ${event-context} layout renderer. Let’s also add timestamp to each message:

<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <targets>
        <target name="console" xsi:type="Console" layout="${longdate} ${message} ${event-context:t}" />
    </targets>

    <rules>
        <logger name="*" minlevel="Debug" writeTo="console" />
    </rules>
</nlog>

Now when you restart both client and server you should see this picture - we can now see that all log events were sent from thread #2 - the UI thread of the Silverlight application.

I would love to hear your feedback about this build and using NLog in Windows Phone 7 applications in general. Please use Forum for any questions or suggestions or Issue Tracker if something does not work correctly.

NLog 2.0 Beta 1 has been released

2010-09-26T00:00:00-07:00

It is my pleasure to announce that NLog 2.0 Beta 1 has been released.

NLog 2.0 release is focused on adding support for new platforms (Silverlight, .NET Framework 4), improving logging architecture and manageability and addressing most frequently reported user issues.

The following platforms are supported in this release:

.NET Framework 2.0 SP1 and above, 3.5 (Client and Extended profiles), 4.0 (Client and Extended profiles)
Silverlight 2.0, 3.0, 4.0
.NET Compact Framework 2.0, 3.5
Mono 2.x profile

Read full release notes: http://nlog-project.org/nlog2-beta1-release-notes.html

Download Beta 1 bits on CodePlex: http://nlog.codeplex.com/releases/view/52957

Source code is available on GitHub: http://github.com/jkowalski/NLog/

Bugs can be reported on CodePlex: http://nlog.codeplex.com/workitem/list/basic

Discuss on forum: http://nlog-project.org/forum

Subscribe to NLog RSS feed: http://nlog-project.org/feed

Follow @JarekKowalski on Twitter: http://twitter.com/JarekKowalski

Deploying NLog configuration files

2010-09-25T00:00:00-07:00

Some of the targets supported by NLog require installation to be performed on the machine before the target can be used. For example, when logging to a database, a DBA needs to create the necessary tables, when logging to event log or performance counter, administrator of the machine must create them before the application can write to them.

NLog 2.0 comes with a new tool and APIs that lets you manage installation and uninstallation of objects which support logging.

Say you want to write logs to:

local SQLEXPRESS database
Event Log on the local machine
increase performance counter each time log message occurs.

With NLog 2.0, you can embed installation/uninstallations steps directly in the log configuration file, like in the following example:

<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <targets>
    <target xsi:type="Database" name="db">
      <!-- SQL command to be executed for each entry -->
      <commandText>INSERT INTO [LogEntries](TimeStamp, Message, Level, Logger) VALUES(getutcdate(), @msg, @level, @logger)</commandText>

      <!-- parameters for the command -->
      <parameter name="@msg" layout="${message}" />
      <parameter name="@level" layout="${level}" />
      <parameter name="@logger" layout="${logger}" />

      <!-- connection string -->
      <dbProvider>System.Data.SqlClient</dbProvider>
      <connectionString>server=.\SQLEXPRESS;database=MyLogs;integrated security=sspi</connectionString>

      <!-- commands to install database -->
      <install-command>
        <text>CREATE DATABASE MyLogs</text>
        <connectionString>server=.\SQLEXPRESS;database=master;integrated security=sspi</connectionString>
        <ignoreFailures>true</ignoreFailures>
      </install-command>

      <install-command>
        <text>
          CREATE TABLE LogEntries(
          id int primary key not null identity(1,1),
          TimeStamp datetime2,
          Message nvarchar(max),
          level nvarchar(10),
          logger nvarchar(128))
        </text>
      </install-command>

      <!-- commands to uninstall database -->
      <uninstall-command>
        <text>DROP DATABASE MyLogs</text>
        <connectionString>server=.\SQLEXPRESS;database=master;integrated security=sspi</connectionString>
        <ignoreFailures>true</ignoreFailures>
      </uninstall-command>
    </target>

    <target xsi:type="EventLog" name="eventLog" source="NLog Demo"
            layout="${message}${newline}Call site: ${callsite:className=true:methodName=true}${newline}Logger: ${logger}">
    </target>

    <target xsi:type="PerfCounter" name="pc1" categoryName="My Log" counterName="My Counter">
    </target>

  <rules>
    <logger name="*" minlevel="Trace" writeTo="db,eventLog,pc1" />
  </rules>
</nlog>

In order to deploy the database, event log and performance counter, you can use simply use InstallNLogConfig.exe tool that comes with NLog. Open elevated command prompt and run the following command:

> InstallNLogConfig.exe c:\path\to\NLog.config
Installing 'Database Target[db]'
Finished installing 'Database Target[db]'.
Installing 'EventLog Target[eventLog]'
Finished installing 'EventLog Target[eventLog]'.
Installing 'PerfCounter Target[pc1]'
Finished installing 'PerfCounter Target[pc1]'.

Uninstalling is equally easy:

> InstallNLogConfig.exe" -u c:\path\to\NLog.config 
Uninstalling 'Database Target[db]' 
Finished uninstalling 'Database Target[db]'. 
Uninstalling 'EventLog Target[eventLog]' 
Finished uninstalling 'EventLog Target[eventLog]'. 
Uninstalling 'PerfCounter Target[pc1]' 
Finished uninstalling 'PerfCounter Target[pc1]'.

Passing parameters to installation

Sometimes there is a need to pass parameters to the installation routing, which should not be normally visible in the NLog.config file. One example might be DBA username and password for connecting to the database. You can pass parameters on the command line by using –p NAME=VALUE option:

> InstallNLogConfig.exe" –p ADMIN_USER=sa –p ADMIN_PASSWORD=megaSecret1234 c:\path\to\NLog.config

The parameters are accessible using ${install-context} layout renderer. For example, we can easily modify the above example to use SQL authentication where user name and password are passed from command line:

<install-command>
  <text>CREATE DATABASE MyLogs</text>
    <connectionString>server=.\SQLEXPRESS;database=master;
                      user id=${install-context:ADMIN_USER};password=${install-context:PASSWORD}</connectionString>
    <ignoreFailures>true</ignoreFailures>
</install-command>

Installation API

In order to install logging configuration, you can simply use Install() and Uninstall() methods on LoggingConfiguration object. They both take InstallationContext arguments, which can be used pass parameters and specify logging and other options:

namespace NLog.Config
{
    public sealed class InstallationContext : IDisposable
    {
        /// <summary>
        /// Gets or sets the installation log level.
        /// </summary>
        public LogLevel LogLevel { get; set; }

        /// <summary>
        /// Gets or sets a value indicating whether to ignore failures during installation.
        /// </summary>
        public bool IgnoreFailures { get; set; }

        /// <summary>
        /// Gets the installation parameters.
        /// </summary>
        public IDictionary<string, string> Parameters { get; private set; }

        /// <summary>
        /// Gets or sets the log output.
        /// </summary>
        public TextWriter LogOutput { get; set; }
    }
}

Typical installation code will look like this:

using (var context = new InstallationContext())
{
  var config = new XmlLoggingConfiguration("NLog.config");

  // output detailed installation logs
  context.LogLevel = LogLevel.Trace;

  context.Parameters["ADMIN_USER"] = "sa";
  context.Parameters["ADMIN_PASSWORD"] = "megaSecret1234";

  // write logs to a log file
  using (var logFile = File.CreateText("InstallLog.txt"))
  {
    context.LogOutput = logFile;

    config.Install(context);  
  }
}

In order to support custom installation in your target or any other configuration item (such as layout, filter, etc.), you simply need to implement IIinstallable interface:

public interface IInstallable
{
  void Install(InstallationContext installationContext);
  void Uninstall(InstallationContext installationContext);
  bool? IsInstalled(InstallationContext installationContext);
}

See DatabaseTarget sources for example implementation.

New exception handling rules in NLog 2.0

2010-09-05T00:00:00-07:00

NLog will introduce a change to logging exception handling and suppression. In NLog 1.0 all exceptions were disabled by default, but could be enabled by setting

<nlog throwExceptions=”true”>

</nlog>

or in code:

LogManager.ThrowExceptions = true;

This flag applied to configuration errors as well as runtime errors, which was problematic, because a simple configuration file typo could cause entire logging to be disabled silently.

To address this, NLog 2.0 will treat configuration errors separately from runtime errors. There will be two kinds of exceptions:

Configuration exceptions - raised during parsing of configuration file and wrapped in NLogConfigurationException. Such errors are fatal and will prevent your application from starting (this is the same as having malformed App.config or Web.config). The errors that cause this exception are:
- syntax errors in NLog.config
- invalid target names
- invalid property names
- invalid property values
Runtime exceptions (such as permission issues, connection failures, etc.) - raised during logging and initialization and wrapped in NLogRuntimeException. They can be controlled by throwExceptions flag.

I would love to hear your comments.

Routing System.Diagnostics.Trace and System.Diagnostics.TraceSource logs through NLog

2010-09-02T00:00:00-07:00

I have recently added a trace listener class for NLog, which enables routing of System.Diagnostics.Trace and System.Diagnostics.TraceSource logs through your favorite log routing engine. This can be very useful for integrating components that don’t necessarily support logging through NLog as well as analyzing traces produced .NET Framework itself.

By using NLog trace listener you can send those logs via email, save them to a database, file or to any other supported log targets.

Let’s create a simple example – application that makes network call. We will then enable network call tracing without touching a single line of code.

namespace TraceDemo 
{ 
  using System.Net; 

  class Program 
  { 
    static void Main(string[] args) 
    { 
      var webClient = new WebClient(); 
      webClient.DownloadString("http://somehost/nosuchfile.txt"); 
    } 
  } 
}

As you can see the example is just using WebClient from System.Net namespace, and has no tracing-specific code. Internally WebClient is capable of outputting traces through System.Net trace source. To route those traces through NLog you need to assign a listener to each source in the application configuration file. It is convenient to define NLogTraceListener as a shared listener and reference by name in all sources that you need as in the following example:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <system.diagnostics>
    <sources>
      <source name="System.Net" switchValue="All">
        <listeners>
          <add name="nlog" />
        </listeners>
      </source>
      <source name="System.Net.Sockets" switchValue="All">
        <listeners>
          <add name="nlog" />
        </listeners>
      </source>
    </sources>
    <sharedListeners>
      <add name="nlog" type="NLog.NLogTraceListener, NLog" />
    </sharedListeners>
  </system.diagnostics>
</configuration>

Obviously you also need NLog.dll and NLog.config to be located in the application directory. For our purposes we’ll use simple configuration with single target:

<nlog>
  <targets>
    <target name="console" type="ColoredConsole" layout="${longdate} ${windows-identity} ${message}" />
  </targets>

  <rules>
    <logger name="*" minlevel="Trace" writeTo="console" />
  </rules>
</nlog>

When you run this application, you will get nice color-coded trace that includes lots of diagnostics information straight from the guts of .NET Framework. Having access to detailed trace like this can be very helpful in diagnosing hard-to-reproduce problems that are often impossible to figure out with a debugger.

Intellisense for NLog configuration files

2010-06-30T00:00:00-07:00

I have recently updated tools to build NLog.xsd which are needed to Intellisense in Visual Studio. Instead of one, in NLog 2.0 there will be multiple schema files - one for each framework plus a unified schema for all frameworks.

File Name	XML Namespace	Frameworks
NLog.xsd	http://www.nlog-project.org/schemas/NLog.xsd	(all frameworks)
NLog.Mono2.xsd	http://www.nlog-project.org/schemas/NLog.mono2.xsd	Mono 2.x
NLog.NetCf20.xsd	http://www.nlog-project.org/schemas/NLog.netcf20.xsd	.NET Compact Framework 2.0
NLog.NetCf35.xsd	http://www.nlog-project.org/schemas/NLog.netcf35.xsd	.NET Compact Framework 3.5
NLog.NetFx20.xsd	http://www.nlog-project.org/schemas/NLog.netfx20.xsd	.NET Framework 2.0
NLog.NetFx35.xsd	http://www.nlog-project.org/schemas/NLog.netfx35.xsd	.NET Framework 3.5
NLog.NetFx40.xsd	http://www.nlog-project.org/schemas/NLog.netfx40.xsd	.NET Framework 4.0
NLog.SL2.xsd	http://www.nlog-project.org/schemas/NLog.sl2.xsd	Silverlight 2.0
NLog.SL3.xsd	http://www.nlog-project.org/schemas/NLog.sl3.xsd	Silverlight 3.0
NLog.SL4.xsd	http://www.nlog-project.org/schemas/NLog.sl4.xsd	Silverlight 4.0

The idea is that each XSD file only contains items (targets, layouts, filters, etc.) supported by a particular framework and unified schema supports all the targets supported by at least one framework. Because of that Intellisense will provide smart editing help and validation that’s specific to the target framework.

Intellisense In Action

When you add NLog.config to your project using Add Item, it will be using a unified schema (so you will see both Silverlight-specific and .NET Framework specific targets there)

When you change the XML to a particular framework - for example Silverlight 2.0, you will immediately see that File target is not supported on that platform and XML editor will highlight the place where the error occurs.

This also works for individual properties. For example, LogReceiverService target does not support certain properties on .NET Compact Framework 3.5 (because of lack of WCF). Sure enough, when you use .NET CF-specific schema those errors will be highlighted.

XSD schemas also provide help when editing NLog.config files:

Customizing XSD Schemas

Starting with NLog 2.0 it is also easy to customize NLog.xsd, which can be useful if your organization uses private extensions to NLog. Let’s say you have created your NLog extensions and put them in SampleExtensions.dll. In order to generate customized NLog.xsd, you need to follow this simple process:

The first step is to download and unpack NLog sources (from GitHub or zip package) and build everything by running:

build.cmd build xsd

from command line. This will build NLog and the tools necessary to customize XSD files. First tool we’ll be using is called DumpApiXml, which analyzes a DLL and generates API file from it as described here. We must run it on our extensions assembly and pass it directory (or directories) where all reference assemblies are located.

<nlog-dir>\tools\DumpApiXml\bin\Debug\DumpApiXml.exe -assembly  <path>\SampleExtensions.dll
  -ref "D:\Work\NLog\build\bin\Debug\.NET Framework 4.0" -output <path>\SampleExtensions.api

Once we have the SampleExtensions.api project, we need to convert it to XSD using MakeNLogXSD. It accepts multiple .api files and can produce XSD files with custom namespaces:

<nlog-dir>\tools\MakeNLogXSD\bin\Debug\MakeNLogXSD.exe -api "<nlog-dir>\build\bin\Debug\.NET Framework 4.0\API\NLog.api"
  -api <path>\SampleExtensions.api -xmlns http://mycompany.com/NLog.xsd -out <path>\MyNLog.xsd

The command will produce MyNLog.xsd which will use http://mycompany.com/NLog.xsd schema. You can now install the schema in Visual Studio (by dropping it in ”%ProgramFiles%\Microsoft Visual Studio 9.0\Xml\Schemas” directory) and you should be able to enjoy Intellisense and validation against your custom schema:

Nlog 2 0 Small Api Reorganizations And Breaking Changes

2010-06-10T00:00:00-07:00

I just checked a set of API changes, which may break code which uses recent nightly builds from NLog 2.0 branch. If you are upgrading to the latest build (2010.06.11.01 or newer) you may need to update your code:

NLog.Targets.Compound namespace was removed and classes were merged into NLog.Targets.Wrappers namespace. In NLog 2.0 there is no distinction between wrappers and compound targets – they will be collectively referred to as wrappers.
NLog.Contexts namespace was removed and classes were merged into NLog namespace (this is actually the situation we had in NLog 1.0, so this change is really undoing previous breaking change which was unnecessary)

The changes are consistent with general breaking change policy and should not impact people only using file-based configuration and simple logging APIs.

New, smaller NLog installer is available

2010-06-10T00:00:00-07:00

I’ve just checked in code changes to produce much smaller installer packages for NLog 2.0. Until now, the combined installer package for all framework was 20.8MB, after the change it is less than 6 MB. What made the installer huge was not the size of NLog.dll (it is are between 200KB and 300KB depending on the platform), but the documentation: 9 chm files, each about 2MB. it was clearly a big waste, given that the documentation for most platforms is almost the same.

The new installer includes single documentation file generated from a special build of NLog with DOCUMENTATION flag turned on. The combined assembly includes superset of all APIs available for all platforms - the produced assembly won’t necessarily run, but is good enough to generate documentation. The same technique was used in NLog 1.0 timeframe - I originally thought it would not work for 2.0 given large differences between .NET and Silverlight build, but now I think it is a reasonable compromise between the size and accuracy of the doc file.

The new suite of installers should show up on CodePlex in the next couple hours.

NLog 2.0 documentation is available on the wiki

2010-06-05T00:00:00-07:00

Documentation for NLog 2.0 is now available on the Wiki. It includes reference documents generated automatically from code as well as hand-written documents and tutorials, some of which have been migrated from WordPress pages to the Wiki format.

Documentation for targets, layouts, layout renderers and filters has been enhanced to include usage examples which you can paste into your configuration code. Because of the new format, it is possible to enhance reference documents with user-created content, such as code or configuration samples. See documentation for the File target for an example.

Note that it is not possible to edit certain parts of automatically generated pages. Things like parameter list, supported platforms and usage example do not show up in Wiki source. Instead you will see a special tag which looks like: >generatedDoc id='File_target' hash='db5419b5ab45ec8defc51cb5dabeaaf4′ /<, and causes generated doc to be inserted. The tags and contents are automatically updated whenever I re-upload documentation.

Now that every piece of documentation is in Wiki format, I’m looking for volunteers to help maintain and enhance it, so if you like technical writing and want to own part of the documentation, please let me know.

Please report any issues you find with the Wiki as comments here, or (even better), register for an account and fix those issues yourself.

NLog nightly builds are now available

2010-05-22T00:00:00-07:00

Nightly builds of NLog are now available on CodePlex. They are generated every night around 1AM PST which is 10AM in most of Europe. Builds are generated using CruiseControl.NET which is pretty awesome piece of software - except the fact that they don’t use NLog yet :).

After each build, binaries are automatically pushed to CodePlex servers using CodePlex Web Services API. Once the release is uploaded, a direct link to it is also placed on the Download page. I still haven’t figured out how to delete older releases automatically because CodePlex API does not support this, so I’ll be doing that manually for now.

You can subscribe to the RSS feed at http://feeds.feedburner.com/nlogreleases to be notified about new builds.

Asynchronous Makeover - NLog Edition

2010-05-18T00:00:00-07:00

I just checked in code to enable asynchronous execution of wrappers in NLog. This is the last big architectural change before bug-fixing and stabilization for 2.0 release.

New features

Exceptions thrown from wrappers such as AsyncTargetWrapper, BufferingTargetWrapper, AspNetBufferingTargetWrapper are now handled as opposed to being swallowed.
LogReceiverWebServiceTarget now handles asynchronous exceptions.
Exceptions from batch-aware targets are now handled for each item separately. It means that if you write 100 messages to a BufferedWrapper which wraps File target and one of those file writes fails, you will get 99 successes and 1 failure as opposed to one massive failure which no wrapper can reasonably handle. The same thing applies to email, etc.

There has been a small change to the design described in the last post. Asynchronous continuations are represented as delegates instead of interface. It makes makes it much easier to use ad-hoc continuations in code without sacrificing composability.

Downloads

The source code is available in GitHub repository. I’ve published a private build from the master branch: http://nlog-project.org/public/asyncpreview1/.

I would appreciate people giving this build a spin and reporting any anomalies. Given the scope of changes and lack of unit tests in some areas I expect many things to be broken, so any usage in production is highly discouraged.

NLog project metrics on Ohloh.net

2010-05-14T00:00:00-07:00

Today I came by Ohloh.net which I found to be very interesting. It provides detailed statistics about open source projects. NLog was already registered by some good soul, but was pointing at the old source repository on sourceforge.net, so I updated it to use Github repo and recomputed the stats.

The statistics are generally pretty interesting, and seem pretty accurate - but there are also some entertaining ones, like the estimation of the cost it would take to recreate such a project from scratch (obviously in corporate environment):

There are many more interesting statistics, so go and check them out.

I’ve also put I USE IT button on top of this page. You can add NLog to your tool stack on Ohloh by clicking on it, which will count in project statistics.

Asynchronous logging in NLog 2.0

2010-05-09T00:00:00-07:00

NLog 1.0 supports asynchronous logging, but there is no good support for asynchronous exception handling. This is because wrappers targets are not capable of receiving exceptions which are raised on other threads.

Since NLog 2.0 is going to support Silverlight where entire networking stack is completely asynchronous, it is critical to enable wrappers for those scenarios. Without it some important wrapper-based features, such as load balancing or failover would not work properly.

This post will present new APIs to support asynchronous logging features that are coming in the next release of NLog.

Exception Handling in NLog 1.0

NLog 1.0 uses very simple, synchronous exception handling pattern:

try
{
    // do something
}
catch (Exception ex)
{
    // handle exception
}

The problem arises if the code block inside try { } clause performs an asynchronous operation such as network call which may result in an exception, as in the following example:

try
{
    WebClient client = new WebClient();
    client.DownloadStringCompleted += (sender, e) =>
    {
        // this event will be raised asynchronously
        // on another thread, long after try/catch block completes
 
        // any exceptions raised here will not be handled by the catch {} block below
    }

    client.DownloadStringAsync(new Uri("http://example.com"));
}
catch (Exception ex)
{
    // handle exception
}

NLog cannot handle exceptions in such cases, since the original stack frame is gone, so it just swallows exceptions raised asynchronously and logs them to the internal log. Not catching exceptions on background threads would be fatal and might result in application termination.

You can probably see why swallowing exceptions prevents wrappers, such as RetryingWrapper from working. If you write declare the following wrappers in your configuration file, the outermost wrapper will never implement any retry logic, since AsyncWrapper will never pass any asynchronous exceptions to RetryingWrapper.

<target type="RetryingWrapper" ...>
   <target type="AsyncWrapper" ...>
      <target type="File" ...>
   </target>
</target>

Asynchronous Exception Handling in NLog 2.0

In order to implement proper asynchronous exception handling we need to let asynchronous methods know what to do in case of success and failure. This is typically done through continuation functions. There are many ways to represent continuation information, I’ve decided to represent it as an interface with two methods:

public interface IAsyncContinuation
{
    void OnSuccess();
    void OnException(Exception exception);
}

The Target.Write() API will be refactored to look like this:

public void WriteLogEvent(LogEventInfo logEvent, IAsyncContinuation asyncContinuation)
{
    try
    {
        this.Write(logEvent, asyncContinuation);
    }
    catch (Exception ex)
    {
        asyncContinuation.OnException(ex);
    }
}

protected virtual void Write(LogEventInfo logEvent, IAsyncContinuation asyncContinuation)
{
    try
    {
        this.Write(logEvent);
    }
    catch (Exception ex)
    {
        asyncContinuation.OnException(ex);
        return;
    }

    asyncContinuation.OnSuccess();
}

protected abstract void Write(LogEventInfo logEvent);

As you can see, by default the asynchronous code gets forwarded to the synchronous Write method. This lets us keep the existing extensibility interface for targets. If you want to implement asynchronous target, you need to override both synchronous and asynchronous write methods:

public class MyAsyncTarget : TargetWithLayout
{
    [RequiredParameter]
    public Uri TargetUri { get; set; }

    protected override void Write(LogEventInfo logEvent)
    {
        throw new NotSupportedException("Synchronous write operation is not supported.");
    }

    protected override void Write(LogEventInfo logEvent, IAsyncContinuation asyncContinuation)
    {
        var wc = new WebClient();
        wc.UploadDataCompleted += (sender, e) =>
            {
                wc.Dispose();
                if (e.Error != null)
                {
                    asyncContinuation.OnException(e.Error);
                    return;
                }

                asyncContinuation.OnSuccess();
            };

        byte[] data = Encoding.UTF8.GetBytes(this.Layout.GetFormattedMessage(logEvent));
        wc.UploadDataAsync(this.TargetUri, data);
    }
}

Target.Flush() method will be changed in a similar way, except it will be asynchronous only:

public void Flush(IAsyncContinuation asyncContinuation)
{
    try
    {
        this.FlushAsync(asyncContinuation);
    }
    catch (Exception ex)
    {
        asyncContinuation.OnException(ex);
    }
}

protected virtual void FlushAsync(IAsyncContinuation asyncContinuation)
{
    asyncContinuation.OnSuccess();
}

LogManager and LogFactory will also be enhanced with asynchronous Flush() methods. Their synchronous overloads will not be available in Silverlight, since there is no way to wait on a potential network call without causing a deadlock:

public class LogFactory
{
#if !SILVERLIGHT
  void Flush();
  void Flush(TimeSpan timeout);
  void Flush(int timeoutMilliseconds);
#endif

  void Flush(IAsyncContinuation asyncContinuation);
  void Flush(IAsyncContinuation asyncContinuation, TimeSpan timeout);
  void Flush(IAsyncContinuation asyncContinuation, int timeoutMilliseconds);
}

Working with continuations

NLog 2.0 will provide default implementation of continuations creatable through AsyncHelpers.MakeContinuation() factory method:

IAsyncContinuation continuation = AsyncHelpers.MakeContinuation(
    () => { /* code to execute on success */ }
    ex => { /* code to execute on failure */ });

In addition to this I am planning to expose helpers which will make working with and composing continuations easier:

public delegate void AsynchronousAction(IAsyncContinuation asyncContinuation);
public delegate void AsynchronousAction<T>(IAsyncContinuation asyncContinuation, T argument);

public static class AsyncHelpers
{
  public static void RunSequentially<T>(IEnumerable<T> values, IAsyncContinuation asyncContinuation, AsynchronousAction<T> callback);
  public static void RunInParallel<T>(IEnumerable<T> values, IAsyncContinuation asyncContinuation, AsynchronousAction<T> action);
  public static void Repeat(int repeatCount, IAsyncContinuation asyncContinuation, AsynchronousAction action);
  public static IAsyncContinuation FollowedBy(this IAsyncContinuation asyncContinuation, AsynchronousAction action);
  public static IAsyncContinuation WithTimeout(this IAsyncContinuation asyncContinuation, TimeSpan timeout);
  public static void RunSynchronously(AsynchronousAction action);
}

Impact on wrappers

Because of the way the API is designed, the impact on existing targets should be very limited. Unfortunately this does not apply to wrappers, which have to be completely rewritten to be fully asynchronous. Asynchronous code tends to be larger and more difficult to read and follow, as demonstrated in the following example:

For example, the code for retrying wrapper in NLog 1.0 looked like this:

protected internal override void Write(LogEventInfo logEvent)
{
    for (int i = 0; i < RetryCount; ++i)
    {
        try
        {
            if (i > 0)
                InternalLogger.Warn("Retry #{0}", i);
            WrappedTarget.Write(logEvent);
            // success, return
            return;
        }
        catch (Exception ex)
        {
            InternalLogger.Warn("Error while writing to '{0}': {1}", WrappedTarget, ex);
            if (i == RetryCount - 1)
                throw ex;
            System.Threading.Thread.Sleep(RetryDelayMilliseconds);
        }
    }
}

The code for the same operation in NLog 2.0 is much more complex:

protected override void Write(LogEventInfo logEvent, IAsyncContinuation asyncContinuation)
{
    FailureAction failure = null;
    int counter = 0;

    failure = ex =>
        {
            InternalLogger.Warn("Error while writing to '{0}': {1}", this.WrappedTarget, ex);
            int retryNumber = Interlocked.Increment(ref counter);

            // exceeded retry count
            if (retryNumber == this.RetryCount)
            {
                asyncContinuation.OnException(ex);
                return;
            }

            // sleep and try again
            Thread.Sleep(this.RetryDelayMilliseconds);
            InternalLogger.Warn("Retry #{0}", retryNumber);

            this.WrappedTarget.WriteLogEvent(logEvent, AsyncHelpers.MakeContinuation(asyncContinuation.OnSuccess, failure));
        };

    this.WrappedTarget.WriteLogEvent(logEvent, AsyncHelpers.MakeContinuation(asyncContinuation.OnSuccess, failure));
}

Summary

Asynchronous processing is a very difficult matter, and it is very difficult to write correct and robust asynchronous code. I am hoping that proposed APIs and abstraction level are the right ones and will not make the source code too difficult to read and maintain.

Any comments or suggestions are welcome.

NLog 2.0 installer is available for testing

2010-05-01T00:00:00-07:00

I’ve spent last couple nights working on MSI installer for NLog 2.0 and I have first version of MSI packages ready for testing. They should be reasonably usable - the code passes all unit tests but did not get much integration testing yet.

There are 5 installer packages:

.NET Framework package (NLog2-NetFX-PrivateBuild.msi - 8.4 MB) which includes NLog for .NET Framework 2.0, 3.5 and 4.0
Silverlight package (NLog2-SL-PrivateBuild.msi - 6.4 MB) which includes NLog for Silverlight 2.0, 3.0 and 4.0
Compact Framework package (NLog2-NetCF-PrivateBuild.msi - 4.6 MB) which includes NLog for .NET Compact Framework 2.0 and 3.5
Mono package (NLog2-Mono-PrivateBuild.msi - 3.1 MB) which includes NLog for .NET Compact Framework 2.0 and 3.5
Full package (NLog2-All-PrivateBuild.msi - 20 MB) which includes all 9 frameworks

Each package comes with Visual Studio integration, which supports VS2010, VS2008 and VS2005 (completely untested) and should have the same functionality as in NLog 1.0:

Code snippets for C# and VB (just type ‘nlogger’ and it will include logger declaration)
Item templates for empty, console and typical log file
XSD for intellisense

Note that unlike in NLog 1.0, the installer installs those VS items for all users on the machine, not for the user who ran the installer.

Please also note that debug symbols (pdb/mdb), binaries and documentation for some older frameworks, such as Silverlight 2.0 and .NET Framework 2.0 are excluded by default - use custom or full installation to enable them.

Please give the installer a try on as many platform configurations as you can and report success/failure along with your configuration information as comments to this post. I’m particularly interested in testing the following dimensions:

various combinations of Visual Studio SKUs installed on the same machine (with or without add-on packages such as Silverlight SDK, Resharper, etc.)
different versions of Windows
x86 and x64 CPUs
non-English versions of Windows
non-English versions of Visual Studio

Thanks in advance for all your help.