Log event properties data.

This has the same implementation as ${event-context}, but the latter is deprecated.

Platforms Supported: All

To log all properties, use ${all-event-properties}. See also NLog Context.

${event-properties:item=String:culture=String:format=String:objectpath=String}

• item - Name of the item. Required.
• ignoreCase - Name lookup should be case-insensitive. Default true. Introduced in NLog 5.0
• objectpath - property path if the value is an object. Nested properties are supported. Examples: Id, Details.Title. Introduced in NLog 4.6.3

• culture - The culture used for rendering. Introduced in NLog 4.1. Default value is CultureInfo.InvariantCulture
• format - Format for conversion from object to string. Introduced in NLog 4.1.
  • format=@ means serialize object properties into Json-format. Introduced in NLog 4.5.

NLog 4.5+

logger.Info("Order {orderid} created for {user}", 42, "Kenny");

and in your NLog.config file:

${event-properties:item=orderId} -- renders "42"
${event-properties:item=user} -- renders "Kenny"

In C# class, create an event and add an element to the Properties dictionary (or the deprecated Context dictionary):

...
Logger logger = LogManager.GetCurrentClassLogger();
LogEventInfo theEvent = new LogEventInfo(LogLevel.Debug, null, "Pass my custom value");
theEvent.Properties["MyValue"] = "My custom string";
theEvent.Properties["MyDateTimeValue"] = new DateTime(2015, 08, 30, 11, 26, 50);
theEvent.Properties["MyDateTimeValueWithCulture"] = new DateTime(2015, 08, 30, 11, 26, 50);
theEvent.Properties["MyDateTimeValueWithCultureAndFormat"] = new DateTime(2015, 08, 30, 11, 26, 50);
logger.Log(theEvent);
...

and in your NLog.config file:

${event-properties:item=MyValue} -- renders "My custom string"
${event-properties:MyDateTimeValue:format=yyyy-M-dd}"; -- renders "2015-8-30"
${event-properties:MyDateTimeValueWithCulture:culture=en-US} -- renders "8/30/2015 11:26:50 AM"
${event-properties:MyDateTimeValueWithCultureAndFormat:format=yyyy-M-dd HH:mm:ss:culture=en-US} -- renders "2015-8-30 11:26:50"

Introduced in NLog 4.6.3, where Logger have the method WithProperty.

The Logger can be enriched, so it automatically injects one (or more) log-event properties for all log-events being written by the Logger. This can work as an alternative to ScopeContext properties.

Examples:

// WithProperty will return a new unique Logger with the newly added property
var newLogger = logger.WithProperty("myProperty", myValue);
newLogger.Info("hello");
newLogger.Info("again"); // will also have "myProperty"
logger.Info("hi");       // is not affected

NLog 5.0 provides Fluent-Logger-API for building LogEvents:

_logger.ForInfoEvent()
       .Message("This is a fluent message {0}.", "test")
       .Property("PropertyName", "PropertyValue")
       .Log();

When LogEvent Property cannot be found (or has blank value), then one can use whenEmpty to specify fallback value:

${event-properties:EventId:whenEmpty=42}

Examples with usage of Objectpath. NLog 4.6.3+

Set the property:

var property1 = new { Id = 1, Name = "test", Nested = new { Id = 3 } };

var logger = LogManager.GetLogger("logger1");

// e.g. with WithProperty
logger.WithProperty("prop1", property1 ).Info("test message");

// or with structured logging
logger.Info("test Message with {prop1}", property1);

config examples:

${event-properties:prop1} -- renders: { Id = 1, Name = test, Nested = { Id = 3 } }
${event-properties:prop1:objectpath=Id} -- renders: 1
${event-properties:prop1:objectpath=Nested.Id} -- renders: 3

See also Transform captured properties