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.

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:

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.

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.

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.