NLog - Documentation

Last updated: 2006-09-18

This website is based on NLog v1.0. Click here to view the documentation for other versions.

AsyncWrapper Target

A target wrapper that provides asynchronous, buffered execution of target writes.

Assembly	Class	.NET Framework			.NET CF		Mono on Windows		Mono on Unix
Assembly	Class	1.0	1.1	2.0	1.0	2.0	1.0	2.0	1.0	2.0
NLog.dll	NLog.Targets.Wrappers.AsyncTargetWrapper

Remarks:

Asynchronous target wrapper allows the logger code to execute more quickly, by queueing messages and processing them in a separate thread. You should wrap targets that spend a non-trivial amount of time in their Write() method with asynchronous target to speed up logging.

Because asynchronous logging is quite a common scenario, NLog supports a shorthand notation for wrapping all targets with AsyncWrapper. Just add async="true" to the <targets/> element in the configuration file.

<targets async="true"> 
  ... your targets go here ... 
</targets>

Parameters (blue fields are required):

Name Type Description

name

string

The name of the target.

batchSize

integer

The number of log events that should be processed in a batch by the lazy writer thread.

Default value is: 100.

overflowAction

AsyncTargetWrapperOverflowAction

The action to be taken when the lazy writer thread request queue count exceeds the set limit.

Default value is: Discard.

Possible values are:

Grow - Grow the queue.
Discard - Discard the overflowing item.
Block - Block until there's more room in the queue.

queueLimit

integer

The limit on the number of requests in the lazy writer thread request queue.

Default value is: 10000.

timeToSleepBetweenBatches

integer

The time in milliseconds to sleep between batches.

Default value is: 50.

wrappedTarget

Target

The target that this target wraps.

Example:

To set up the target in the configuration file, use the following syntax:

<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd" 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> 
  <targets> 
    <!-- Log in a separate thread, possibly queueing up to
        5000 messages. When the queue overflows, discard any
        extra messages--> 
    <target name="file" xsi:type="AsyncWrapper" queueLimit="5000" 
            overflowAction="Discard"> 
      <target xsi:type="File" fileName="${basedir}/logs/${level}.txt"/> 
    </target> 
  </targets> 
  <rules> 
    <logger name="*" minlevel="Debug" writeTo="file"/> 
  </rules> 
</nlog>

The above examples assume just one target and a single rule. See below for a programmatic configuration that's equivalent to the above config file:

using NLog; 
using NLog.Targets; 
using NLog.Targets.Wrappers; 
 
class Example 
{ 
    static void Main(string[] args) 
    { 
        FileTarget target = new FileTarget(); 
        target.Layout = "${longdate} ${logger} ${message}"; 
        target.FileName = "${basedir}/logs/logfile.txt"; 
        target.KeepFileOpen = false; 
        target.Encoding = "iso-8859-2"; 
 
        AsyncTargetWrapper wrapper = new AsyncTargetWrapper(); 
        wrapper.WrappedTarget = target; 
        wrapper.QueueLimit = 5000; 
        wrapper.OverflowAction = AsyncTargetWrapperOverflowAction.Discard; 
 
        NLog.Config.SimpleConfigurator.ConfigureForTargetLogging(wrapper, LogLevel.Debug); 
 
        Logger logger = LogManager.GetLogger("Example"); 
        logger.Debug("log message"); 
 
        wrapper.Flush(); 
    } 
}

Back to the target list.