How to write a custom target for structured logging

Introduced with NLog 4.5

It is really easy:

• Create a class that inherits from NLog.Targets.TargetWithContext
• Override the Write(LogEventInfo logEvent) method.
• In the body of this method invoke this.RenderLogEvent(this.Layout, logEvent) to get the message text, and invoke this.GetAllProperties(logEvent) to get structured properties.

⚠️ Don't forget to register your custom component when loading NLog config!

See also the updated How to write a custom async target

Example

using NLog;
using NLog.Config;
using NLog.Targets;
 
namespace MyNamespace 
{ 
    [Target("MyFirst")] 
    public sealed class MyFirstTarget : TargetWithContext
    { 
        public MyFirstTarget()
        {
            this.IncludeEventProperties = true; // Include LogEvent Properties by default
        }
 
        [RequiredParameter] 
        public Layout Host { get; set; } = "localhost";
 
        protected override void Write(LogEventInfo logEvent) 
        { 
            string logMessage = this.RenderLogEvent(this.Layout, logEvent); 
            string hostName = this.RenderLogEvent(this.Host, logEvent); 
            IDictionary<string,object> logProperties = this.GetAllProperties(logEvent);
            SendTheMessageToRemoteHost(hostName, logMessage, logProperties); 
        } 
 
        private void SendTheMessageToRemoteHost(string hostName, string message, IDictionary<string, object> properties) 
        { 
            // TODO - write me 
        } 
    } 
}

TargetWithContext Features

Additional Context Properties

Users can easily configure additional context information:

<target type="MyFirst" name="first">
   <contextproperty name="MachineName" layout="${machinename}" />
   <contextproperty name="ThreadId" layout="${threadid}" />
</target>

Without needing to inject the details upfront when doing the logging. It is automatically captured by the NLog engine.

Include ScopeContext

ScopeContext Properties can be used to provide context-specific details (Ex. request-correlationid from ILogger.BeginScope).

To automatically capture properties injected into ScopeContext (Before NLog 5.0 it was called IncludeMDLC)

<target type="MyFirst" name="first" includeScopeProperties="true">
   ...
</target>