Scopes

Contextual data can be set in different scopes. These contexts have progressively narrower visibility. In the logging event itself the values from all of the contexts are combined together such that values specified in a lower scoped context hide values from a higher context.

Context Properties

The log4net contexts store properties, i.e. name value pairs. The name is a string the value is any object. A property can be set as follows:

log4net.GlobalContext.Properties["name"] = value;

If properties with the same name are set in more than one context scope then the value in the narrowest scope (lower down in the list above) will hide the other values.

The property values are stored as objects within the LoggingEvent. The PatternLayout supports rendering the value of a named property using the %property{name} syntax. The value is converted to a string by passing it to the log4net.ObjectRenderer.RendererMap which will locate any custom renderer for the value type. The default behavior for custom types is to call the object's ToString() method.

public class GCAllocatedBytesHelper
{
    public override string ToString()
    {
        return GC.GetTotalMemory(true).ToString();
    }
}

log4net.GlobalContext.Properties["GCAllocatedBytes"] = new GCAllocatedBytesHelper();

Context Stacks

Sometimes simple key value pairs are not the most convenient way of capturing contextual information. A stack of information is a very convenient way of storing data especially as our applications tend to be stack based.

The ThreadContext and LogicalThreadContext also support storing contextual data in a stack. The stack is stored in context property, therefore stacks have names and more than one stack can exist in the same context. A property value set in a narrower context would override a stack with the same property name set in a wider scoped context.

The stack supports Push and Pop methods. As more contextual data is pushed onto the stack the stack grows. When the stack is rendered all the data pushed onto the stack is output with the most recent data to the right hand end of the string.

As the stack is just an object stored in the context properties it is also rendered using the same PatternLayout syntax: %property{name}. Where name is the name of the stack.

Calls the the stack's Push and Pop methods must be matched up so that each push has a corresponding pop. The Push method also returns an IDisposable object that will perform the required pop operation when it is disposed. This allows the C# using syntax to be used to automate the stack management.

using(log4net.ThreadContext.Stacks["NDC"].Push("context"))
{
    log.Info("Message");
}

The INFO level log has a stack stored in its NDC property. The top item in the stack is the string context. The using syntax ensures that the value context is popped off the stack at the end of the block.

The using syntax is recommended because it removes some work load from the developer and reduces errors in matching up the Push and Pop calls, especially when exceptions can occur.

Nested Diagnostic Contexts

The NDC (Nested Diagnostic Context) exists for compatibility with older versions of log4net. This helper class implements a stack which is stored in the thread context property named NDC.

Mapped Diagnostic Contexts

The MDC (MappedDiagnostic Context) exists for compatibility with older versions of log4net. This helper class implements a properties map which is mapped directly through to the thread context properties.