Intellisense for NLog configuration files

30 Jun 2010

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 (all frameworks)
NLog.Mono2.xsd Mono 2.x
NLog.NetCf20.xsd .NET Compact Framework 2.0
NLog.NetCf35.xsd .NET Compact Framework 3.5
NLog.NetFx20.xsd .NET Framework 2.0
NLog.NetFx35.xsd .NET Framework 3.5
NLog.NetFx40.xsd .NET Framework 4.0
NLog.SL2.xsd Silverlight 2.0
NLog.SL3.xsd Silverlight 3.0
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 -out <path>\MyNLog.xsd

The command will produce MyNLog.xsd which will use 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: