I’ve spent last couple weeks working on tools to support NLog 2.0 release process. Releasing library such as NLog which targets 8 frameworks is not an easy task and requires some pretty sophisticated automation support.

Each NLog release consists of several files:

• NLog.dll and NLog.Extended.dll – NLog library
• NLog.xml and NLog.Extended.xml – API documentation extracted from source code comments
• NLog.xsd – schema information used to author and validate NLog configuration files
• NLog.chm – documentation for each platform

Because each supported platform is slightly different (in terms of targets, layout renderers, etc.) a separate version of each artifact must be produced for every build.

Let’s take a look at the process which produces all of these:

Step 1: Compilation

At the very beginning, source files are compiled using csc.exe to produce NLog.dll and NLog.xml (additionally NLog.Extended.dll and NLog.Extended.xml for platforms which need it). This is using standard C# compiler functionality and there is nothing really fancy here. Maybe except for the fact that StyleCop is being used to make sure that in-source documentation is consistent and follows some established patterns.

Step 2: API Dump

The next step is to analyze output assemblies using reflection and extract information about targets, layout renderers, etc. that have been compiled in. This is done using DumpApiXml.exe and the result is a file called NLog.api – one for each supported platform. The reason why a dump file is being used is to simplify further processing: documentation, XSD and website generators can rely only on the API file without the need to duplicate (relatively complex) reflection code.

The API dump includes information about each target in a format that’s friendly for XSLT processing and includes pre-calculated pieces of information such as URI slugs, inline XML documentation, etc.

Step 3: Conceptual documentation generation

Before NLog.chm can be generated we need to generate conceptual documentation which explains configuration file format for each target, layout renderer, etc. This is all done by MakeApiDoc.exe and uses NLog.api for each platform, generated in the previous step. The result is a bunch of *.aml files which will be used by SHFB later. (Note that MakeApiDoc.exe is not checked in into public NLog repository yet).

Step 4: XSD schema generation

Similar to conceptual documentation, NLog.xsd is also generated from NLog.api – the result is a document with documented XSD types and elements which can be used in Visual Studio to provide Intellisense(tm) for authoring and validating NLog.config. (Note that MakeNLogXsd.exe in the public repository is not up-to-date yet and does not use NLog.api, instead it’s an older version from NLog 1.0 which uses reflection. It will be updated soon.)

Step 5: Website generation

NLog.api will also be used to generate documentation for the website, which includes:

• targets.html
• layoutrenderers.html
• filters.html
• layouts.html
• conditions.html
• conditionmethods.html
• and individual documentation pages for each target, layout renderer, etc.

The website will be generated using simple XSLT stylesheet, which is possible thanks to the relatively simple api file format. Since users will not need to generate the website, the tools used here will not be part of the NLog release.

Step 6: Documentation generation

Having assemblies, code comments (generated in step 1) and conceptual documentation (generated in step 3) we can finally launch SHFB to generate documentation each platform. The documentation is produced in two formats:

• NLog.chm – compiled help file which will be included in the download
• website files – which you can browse on the web

Step 7: Installer

The last remaining steps in getting NLog ready for release will be packaging. Most likely this is going to be automated using WIX, but I did not get to that part yet.

.NET Framework 4 client profile is a subset of .NET framework used for client programming. It’s a smaller download, because it does not have some server-specific assemblies such as System.Web.dll, compilers and design-time components. When your project targets the client profile, VS and the compiler will validate that it can actually run in that environment. Your application cannot (statically) reference any system DLLs which are not available in the client profile or any other dlls which may depend on such system assemblies.

Why am I writing about this and how is it related to NLog?

Historically NLog has been distributed as a single assembly with static references to all the required system assemblies, including ones which will no longer be available in the client profile:

As you can see, we have System.Web.dll (because of ASP.NET-specific layout renderers and modules) and System.Messaging.dll (because of MSMQ target) which are from extended profile. If I were to distribute NLog 2.0 with those dependencies, people would not be able to compile their client applications using it- this is bad.

Difficult choice

Since people use NLog for both client-side and server-side deployments (and removing ASP.NET support is not an option) I need to have builds of NLog which support both environments. There are 3 options I’m considering:

1. Release two versions of NLog.dll – one for .NET 4.0 Extended profile and one for .NET 4.0 Client profile
2. Remove static dependencies and release single NLog.dll which detects the profile at runtime and invokes System.Web/System.Messaging through reflection.
3. Release NLog.dll which would be client-only subset and NLog.Extended.dll which would include features specific to extended profile. This would mean that NLog 2.0 for other versions of the framework would also be split into NLog.dll and NLog.Extended.dll

Each option has different pros and cons, which makes this a hard choice:

Option 1 has the following advantages:

• Single assembly to deploy in all scenarios (now that NLog.ComInterop.dll has been merged with NLog.dll there is truly a singly dll)
• Relatively simple code – stuff which does not compile on client profile will be simply #ifdef-ed.
• No dynamic invocation

But there is possible confusion because of existence of two different builds of the same component (with the same name, version numbers and everything else) with slightly different feature set.

Option 2 means single assembly, but potentially slower and harder-to-maintain reflection code

Option 3 is probably the cleanest (there is no conditional compilation and no dynamic invocation), but it means that there will be sometimes 2 assemblies to deal with – in client apps you would reference NLog.dll and in extended profile apps, you can (optionally) use NLog.Extended.dll.

What do you think? Which of those options should I choose? Would you prefer a single assembly over multiple ones? Do you think reflection is a good practice to avoid having to deal with client profile limitations?

Please post your thought in comments.