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" ?><nlogxmlns="http://www.nlog-project.org/schemas/NLog.xsd"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><targets><targetxsi: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 --><parametername="@msg"layout="${message}"/><parametername="@level"layout="${level}"/><parametername="@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><targetxsi:type="EventLog"name="eventLog"source="NLog Demo"layout="${message}${newline}Call site: ${callsite:className=true:methodName=true}${newline}Logger: ${logger}"></target><targetxsi:type="PerfCounter"name="pc1"categoryName="My Log"counterName="My Counter"></target><rules><loggername="*"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:
namespaceNLog.Config{publicsealedclassInstallationContext:IDisposable{/// <summary>/// Gets or sets the installation log level./// </summary>publicLogLevelLogLevel{get;set;}/// <summary>/// Gets or sets a value indicating whether to ignore failures during installation./// </summary>publicboolIgnoreFailures{get;set;}/// <summary>/// Gets the installation parameters./// </summary>publicIDictionary<string,string>Parameters{get;privateset;}/// <summary>/// Gets or sets the log output./// </summary>publicTextWriterLogOutput{get;set;}}}Typical installation code will look like this:
using(varcontext=newInstallationContext()){varconfig=newXmlLoggingConfiguration("NLog.config");// output detailed installation logscontext.LogLevel=LogLevel.Trace;context.Parameters["ADMIN_USER"]="sa";context.Parameters["ADMIN_PASSWORD"]="megaSecret1234";// write logs to a log fileusing(varlogFile=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:
publicinterfaceIInstallable{voidInstall(InstallationContextinstallationContext);voidUninstall(InstallationContextinstallationContext);bool?IsInstalled(InstallationContextinstallationContext);}See DatabaseTarget sources for example implementation.