Table of Contents

Class PatternString

Namespace
log4net.Util
Assembly
log4net.dll

This class implements a patterned string.

public class PatternString : IOptionHandler
Inheritance
PatternString
Implements
Inherited Members

Remarks

This string has embedded patterns that are resolved and expanded when the string is formatted.

This class functions similarly to the PatternLayout in that it accepts a pattern and renders it to a string. Unlike the PatternLayout however the PatternString does not render the properties of a specific LoggingEvent but of the process in general.

The recognized conversion pattern names are:

Conversion Pattern NameEffect
appdomain

Used to output the friendly name of the current AppDomain.

appsetting

Used to output the value of a specific appSetting key in the application configuration file.

date

Used to output the current date and time in the local time zone. To output the date in universal time use the %utcdate pattern. The date conversion specifier may be followed by a date format specifier enclosed between braces. For example, %date{HH:mm:ss,fff} or %date{dd MMM yyyy HH:mm:ss,fff}. If no date format specifier is given then ISO8601 format is assumed (Iso8601DateFormatter).

The date format specifier admits the same syntax as the time pattern string of the DateTime.ToString(string).

For better results it is recommended to use the log4net date formatters. These can be specified using one of the strings "ABSOLUTE", "DATE" and "ISO8601" for specifying AbsoluteTimeDateFormatter, DateTimeDateFormatter and respectively Iso8601DateFormatter. For example, %date{ISO8601} or %date{ABSOLUTE}.

These dedicated date formatters perform significantly better than DateTime.ToString(string).

env

Used to output the a specific environment variable. The key to lookup must be specified within braces and directly following the pattern specifier, e.g. %env{COMPUTERNAME} would include the value of the COMPUTERNAME environment variable.

The env pattern is not supported on the .NET Compact Framework.

identity

Used to output the user name for the currently active user (Principal.Identity.Name).

newline

Outputs the platform dependent line separator character or characters.

This conversion pattern name offers the same performance as using non-portable line separator strings such as "\n", or "\r\n". Thus, it is the preferred way of specifying a line separator.

processid

Used to output the system process ID for the current process.

property

Used to output a specific context property. The key to lookup must be specified within braces and directly following the pattern specifier, e.g. %property{user} would include the value from the property that is keyed by the string 'user'. Each property value that is to be included in the log must be specified separately. Properties are stored in logging contexts. By default the log4net:HostName property is set to the name of machine on which the event was originally logged.

If no key is specified, e.g. %property then all the keys and their values are printed in a comma separated list.

The properties of an event are combined from a number of different contexts. These are listed below in the order in which they are searched. 

    </td></tr><tr><td class="term">random</td><td class="description">
        <p>
        Used to output a random string of characters. The string is made up of
        uppercase letters and numbers. By default the string is 4 characters long.
        The length of the string can be specified within braces directly following the
		pattern specifier, e.g. <b>%random{8}</b> would output an 8 character string.
        </p>
    </td></tr><tr><td class="term">username</td><td class="description">
		<p>
		Used to output the WindowsIdentity for the currently
		active user.
		</p>
    </td></tr><tr><td class="term">utcdate</td><td class="description">
		<p>
		Used to output the date of the logging event in universal time. 
		The date conversion 
		specifier may be followed by a <i>date format specifier</i> enclosed 
		between braces. For example, <b>%utcdate{HH:mm:ss,fff}</b> or
		<b>%utcdate{dd MMM yyyy HH:mm:ss,fff}</b>.  If no date format specifier is 
		given then ISO8601 format is
		assumed (<xref href="log4net.DateFormatter.Iso8601DateFormatter" data-throw-if-not-resolved="false"></xref>).
		</p>
		<p>
		The date format specifier admits the same syntax as the
		time pattern string of the <xref href="DateTime.ToString(string)" data-throw-if-not-resolved="false"></xref>.
		</p>
		<p>
		For better results it is recommended to use the log4net date
		formatters. These can be specified using one of the strings
		"ABSOLUTE", "DATE" and "ISO8601" for specifying 
		<xref href="log4net.DateFormatter.AbsoluteTimeDateFormatter" data-throw-if-not-resolved="false"></xref>, 
		<xref href="log4net.DateFormatter.DateTimeDateFormatter" data-throw-if-not-resolved="false"></xref> and respectively 
		<xref href="log4net.DateFormatter.Iso8601DateFormatter" data-throw-if-not-resolved="false"></xref>. For example, 
		<b>%utcdate{ISO8601}</b> or <b>%utcdate{ABSOLUTE}</b>.
		</p>
		<p>
		These dedicated date formatters perform significantly
		better than <xref href="DateTime.ToString(string)" data-throw-if-not-resolved="false"></xref>.
		</p>
    </td></tr><tr><td class="term">%</td><td class="description">
		<p>
		The sequence %% outputs a single percent sign.
		</p>
	</td></tr></tbody></table>

Additional pattern converters may be registered with a specific PatternString instance using AddConverter(ConverterInfo) or .

See the PatternLayout for details on the format modifiers supported by the patterns.

Constructors

PatternString()

Default constructor

public PatternString()

Remarks

Initialize a new instance of PatternString

PatternString(string)

Constructs a PatternString

public PatternString(string pattern)

Parameters

pattern string

The pattern to use with this PatternString

Remarks

Initialize a new instance of PatternString with the pattern specified.

Properties

ConversionPattern

Gets or sets the pattern formatting string

public string ConversionPattern { get; set; }

Property Value

string

The pattern formatting string

Remarks

The ConversionPattern option. This is the string which controls formatting and consists of a mix of literal content and conversion specifiers.

Methods

ActivateOptions()

Initialize object options

public virtual void ActivateOptions()

Remarks

This is part of the IOptionHandler delayed object activation scheme. The ActivateOptions() method must be called on this object after the configuration properties have been set. Until ActivateOptions() is called this object is in an undefined state and must not be used.

If any of the configuration properties are modified then ActivateOptions() must be called again.

AddConverter(string, Type)

Add a converter to this PatternString

public void AddConverter(string name, Type type)

Parameters

name string

the name of the conversion pattern for this converter

type Type

the type of the converter

Remarks

Add a converter to this PatternString

AddConverter(ConverterInfo)

Add a converter to this PatternString

public void AddConverter(ConverterInfo converterInfo)

Parameters

converterInfo ConverterInfo

the converter info

Remarks

This version of the method is used by the configurator. Programmatic users should use the alternative AddConverter(string,Type) method.

Format()

Format the pattern as a string

public string Format()

Returns

string

the pattern formatted as a string

Remarks

Format the pattern to a string.

Format(TextWriter)

Produces a formatted string as specified by the conversion pattern.

public void Format(TextWriter writer)

Parameters

writer TextWriter

The TextWriter to write the formatted event to

Remarks

Format the pattern to the writer.