Today marks the very important milestone of NLog 2.0 development – I now have fully automated set of NLog unit tests running on all supported platforms.

Why is this such a big deal? In NLog 1.0 timeframe I was not able to run automated unit tests in some environments (such as .NET Compact Framework which did not support NUnit). Because of that I had to resort to ad-hoc testing which unfortunately missed some pretty big bugs.

The .NET ecosystem has grown significantly in the last couple years, and because NLog 2.0 is going to support at least 5 versions of .NET Framework, 3 versions of Silverlight, 2 versions of .NET Compact Framework and Mono, the ability to run the entire test suite on all frameworks became even more important.

Common test library

Since I wanted to use the same set of unit tests in all supported environments, I’ve decided to switch from NUnit-based tests to MSTest. Main reason was the fact that NUnit is not available for Silverlight and .NET Compact Framework and MSTest is available inside Visual Studio. Switching was relatively painless and in most cases was just a simple search/replace of using statements.

MSTest has the advantage of supporting all versions of .NET and .NET Compact Framework inside Visual Studio and is nicely integrated with the IDE. There are some annoyances, such as pretty complicated debugging experience with mobile devices, but I did not have to write almost any custom code to use it and there is no need for 3rd-party download, which is another plus.

Supporting Silverlight was a bit more tricky, because MSTest does not support it directly, but thankfully there is Silverlight Toolkit on CodePlex which provides required libraries and test runner, which requires just a little bit of custom coding.

I still don’t have automated test coverage in Mono, but I think it should be doable – if you know of some ready-to-use MSTest replacement for Mono (ideally one which works on Unix), please let me know.

Build System

In NLog I’ve switched from NAnt to MSBuild as the build automation platform. MSBuild scripts have the huge advantage of being able to use them in Visual Studio directly while enabling deep customizations. MSBuild is installed as part of .NET Framework so almost everyone should already have it on their machines.

In order to make building and running tests in NLog a bit easier, I’ve created a batch file (build.cmd) which is a wrapper for MSBuild. It lets me select which platforms I want to build and test against and do everything in one shot.

In order to build NLog 2.0 for all supported platforms run:

build.cmd

To build and run tests for all platforms:

build.cmd buildtests runtests

If you want to only target specific frameworks, just put their mnemonics on the command line:

build.cmd netfx20 netfx35client doc

To generate documentation for Silverlight 2.0 and Silverlight 3 use:

Documentation for NLog 1.0 is available online at http://nlog-project.org/doc/1.0/

Starting with NLog 2.0 there will be a separate documentation build for each supported framework. They will be all accessible from the following base url:

http://nlog-project.org/doc/2.0/

or you can jump directly to the documentation for your framework of choice:

• NLog for .NET Framework 2.0
• NLog for .NET Framework 3.5
• NLog for .NET Framework 3.5 Client Profile
• NLog for .NET Framework 4.0
• NLog for .NET Framework 4.0 Client Profile
• NLog for .NET Compact Framework 2.0
• NLog for .NET Compact Framework 3.5
• NLog for Silverlight 2.0
• NLog for Silverlight 3.0
• NLog for Mono 2.x

Note that conceptual documentation (tutorials, configuration information, etc.) is not included yet in NLog 2.0 builds and it will be added later.

Producing such a complex set of documentation was a real challenge. I used excellent Sandcastle and Sandcastle Help File Builder from CodePlex which helped a lot. Getting those tools to produce customized documentation for all NLog 2.x frameworks was a complex task with lots of custom scripting to support the build process.

As always – feedback is more than welcome.

NLog v2 branch has a new cool feature called Wrapper Layout Renderers which would help me restructure code to make it more maintainable and testable. I’d like to hear your opinion about it.

What are Wrapper Layout Renderers (WLRs)?

Similar to wrapper targets, WLRs can modify output of other layout renderers, by doing textual transformations like:

• uppercase/lowercase conversion
• padding, trimming, alignment
• search/replace
• elision of excessive text
• encryption / masking of sensitive information
• cryptographic transformations (calculating MD5, SHA1 hashes, HMAC checksums)
• encoding: base64/uuencode, etc.

Note that in NLog v1 many of those concerns are handled by LayoutRenderer itself. Being able to separate them into standalone, extensible classes is very convenient as you can add them separately and all existing layout renderers will be able to benefit from them.
 
Here’s how you use them:

${uppercase:${level}} – will print log level in uppercase
${rot13:${message}} -  will print ROT13 “encrypted” message
 
For configuration file compatibility, you will still be able to use uppercase, lowercase, padding attributes that you know from NLog v1 directly on layout renderers etc.
 
To implement a wrapper, all you have to do is to create a class derived from WrapperLayoutRendererBase that overrides the Transform() method and apply the usual LayoutRenderer attribute.
Here’s the ROT13 wrapper, which implements Caesar’s cipher.
 
[LayoutRenderer("rot13")]
public sealed class Rot13LayoutRendererWrapper: WrapperLayoutRendererBase
{
    protected override string Transform(string text)
    {
        return DecodeRot13(text);
    }
}
 
You can of course define public properties as be able to set their values as with regular layout renderers.
I’m planning to add an additional concept called ambient properties which will help maintain NLog v1 compatibility while being very extensible. Ambient properties are properties that appear as if they were present on all layout renderers and when you actually use them, they add an implicit wrapper. This allows you to write: ${level:uppercase=true:padding=-10} instead of ${padding:padding=-10:${uppercase:${level}}}

Whenever layout parser encounters an unknown property (such as “uppercase” which doesn’t exist on LevelLayoutRenderer anymore) it will look for layout renderers which define [AmbientProperty("UpperCase")] and will instantiate them and use to wrap the original layout renderer:

 [LayoutRenderer("uppercase")]
[AmbientProperty("UpperCase")]
public sealed class UpperCaseLayoutRendererWrapper : WrapperLayoutRendererBase
{
    private bool _upperCase = false;
    public bool UpperCase
    {
        get { return _upperCase; }
        set { _upperCase = value; }
    }
    protected override string Transform(string text)
    {
        return UpperCase ? text.ToUpperInvariant() : text;
    }
}