Class LogWriter

Namespace

Microsoft.Practices.EnterpriseLibrary.Logging

Assembly

Microsoft.Practices.EnterpriseLibrary.Logging.dll

Instance based class to write log messages based on a given configuration. Messages are routed based on category.

public class LogWriter : ILogFilterErrorHandler, IDisposable

Inheritance

object

LogWriter

Implements

ILogFilterErrorHandler

IDisposable

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

To write log messages to the default configuration, use the Logger facade.

The LogWriter works as an entry point to the System.Diagnostics trace listeners. It will trace the LogEntry through the Microsoft.Practices.EnterpriseLibrary.Logging.TraceListenerss associated with the LogSources for all the matching categories in the elements of the Categories property of the log entry. If the "all events" special log source is configured, the log entry will be traced through the log source regardles of other categories that might have matched. If the "all events" special log source is not configured and the "unprocessed categories" special log source is configured, and the category specified in the logEntry being logged is not defined, then the logEntry will be logged to the "unprocessed categories" special log source. If both the "all events" and "unprocessed categories" special log sources are not configured and the property LogWarningsWhenNoCategoriesMatch is set to true, then the logEntry is logged to the "logging errors and warnings" special log source.

Constructors

LogWriter(LogWriterStructureHolder)

Initializes a new instance of the LogWriter class with the specified logging stack.

public LogWriter(LogWriterStructureHolder structureHolder)

Parameters

structureHolder LogWriterStructureHolder

The initial implementation of the logging stack

LogWriter(LoggingConfiguration)

Initializes a new instance of the LogWriter class with the specified configuration.

public LogWriter(LoggingConfiguration config)

Parameters

config LoggingConfiguration

The configuration to use.

LogWriter(IEnumerable<ILogFilter>, IDictionary<string, LogSource>, LogSource, LogSource, LogSource, string, bool, bool)

Initializes a new instance of the LogWriter class with the specified filters, trace sources, default category, and tracing options.

public LogWriter(IEnumerable<ILogFilter> filters, IDictionary<string, LogSource> traceSources, LogSource allEventsTraceSource, LogSource notProcessedTraceSource, LogSource errorsTraceSource, string defaultCategory, bool tracingEnabled, bool logWarningsWhenNoCategoriesMatch)

Parameters

filters IEnumerable<ILogFilter>

The collection of filters to use when processing an entry.

traceSources IDictionary<string, LogSource>

The trace sources to dispatch entries to.

allEventsTraceSource LogSource

The special LogSource to which all log entries should be logged.

notProcessedTraceSource LogSource

The special LogSource to which log entries with at least one non-matching category should be logged.

errorsTraceSource LogSource

The special LogSource to which internal errors must be logged.

defaultCategory string

The default category to set when the entry categories list of a log entry is empty.

tracingEnabled bool

The tracing status.

logWarningsWhenNoCategoriesMatch bool

true to log warnings when a non-matching category is found; otherwise, false.

LogWriter(IEnumerable<ILogFilter>, IDictionary<string, LogSource>, LogSource, LogSource, LogSource, string, bool, bool, bool)

Initializes a new instance of the LogWriter class with the specified filters, trace sources, default category, tracing options, and impersonation option.

public LogWriter(IEnumerable<ILogFilter> filters, IDictionary<string, LogSource> traceSources, LogSource allEventsTraceSource, LogSource notProcessedTraceSource, LogSource errorsTraceSource, string defaultCategory, bool tracingEnabled, bool logWarningsWhenNoCategoriesMatch, bool revertImpersonation)

Parameters

filters IEnumerable<ILogFilter>

The collection of filters to use when processing an entry.

traceSources IDictionary<string, LogSource>

The trace sources to dispatch entries to.

allEventsTraceSource LogSource

The special LogSource to which all log entries should be logged.

notProcessedTraceSource LogSource

The special LogSource to which log entries with at least one non-matching category should be logged.

errorsTraceSource LogSource

The special LogSource to which internal errors must be logged.

defaultCategory string

The default category to set when the entry categories list of a log entry is empty.

tracingEnabled bool

The tracing status.

logWarningsWhenNoCategoriesMatch bool

true to log warnings when a non-matching category is found; otherwise, false.

revertImpersonation bool

true to revert impersonation while logging; otherwise, false.

LogWriter(IEnumerable<ILogFilter>, IDictionary<string, LogSource>, LogSource, string)

Initializes a new instance of the LogWriter class with the specified filters, trace sources, and default category.

public LogWriter(IEnumerable<ILogFilter> filters, IDictionary<string, LogSource> traceSources, LogSource errorsTraceSource, string defaultCategory)

Parameters

filters IEnumerable<ILogFilter>

The collection of filters to use when processing an entry.

traceSources IDictionary<string, LogSource>

The trace sources to dispatch entries to.

errorsTraceSource LogSource

The special LogSource to which internal errors must be logged.

defaultCategory string

The default category to set when the entry categories list is empty.

LogWriter(IEnumerable<ILogFilter>, IEnumerable<LogSource>, LogSource, LogSource, LogSource, string, bool, bool)

Initializes a new instance of the LogWriter class with the specified filters, trace sources, default category, tracing options, and warning options.

public LogWriter(IEnumerable<ILogFilter> filters, IEnumerable<LogSource> traceSources, LogSource allEventsTraceSource, LogSource notProcessedTraceSource, LogSource errorsTraceSource, string defaultCategory, bool tracingEnabled, bool logWarningsWhenNoCategoriesMatch)

Parameters

filters IEnumerable<ILogFilter>

The collection of filters to use when processing an entry.

traceSources IEnumerable<LogSource>

The trace sources to dispatch entries to.

allEventsTraceSource LogSource

The special LogSource to which all log entries should be logged.

notProcessedTraceSource LogSource

The special LogSource to which log entries with at least one non-matching category should be logged.

errorsTraceSource LogSource

The special LogSource to which internal errors must be logged.

defaultCategory string

The default category to set when the entry categories list is empty.

tracingEnabled bool

The tracing status.

logWarningsWhenNoCategoriesMatch bool

true to log warnings when a non-matching category is found; otherwise, false.

LogWriter(IEnumerable<ILogFilter>, IEnumerable<LogSource>, LogSource, string)

Initializes a new instance of the LogWriter class with the specified filters, trace sources, and default category.

public LogWriter(IEnumerable<ILogFilter> filters, IEnumerable<LogSource> traceSources, LogSource errorsTraceSource, string defaultCategory)

Parameters

filters IEnumerable<ILogFilter>

The collection of filters to use when processing an entry.

traceSources IEnumerable<LogSource>

The trace sources to dispatch entries to.

errorsTraceSource LogSource

The special LogSource to which internal errors must be logged.

defaultCategory string

The default category to set when the entry categories list is empty.

Fields

LogWriterFailureEventID

EventID used on LogEntries that occur when internal LogWriter mechanisms fail.

public const int LogWriterFailureEventID = 6352

Field Value

int

Properties

TraceSources

Gets the LogSource mappings available for the LogWriter.

public IDictionary<string, LogSource> TraceSources { get; }

Property Value

IDictionary<string, LogSource>

Methods

Configure(Action<LoggingConfiguration>)

Configures the LogWriter object.

public void Configure(Action<LoggingConfiguration> configurationScript)

Parameters

configurationScript Action<LoggingConfiguration>

An action that configures the log writer.

Remarks

Logging is delayed until the configuration changes are applied.

Dispose()

Releases the resources used by the LogWriter.

public void Dispose()

Dispose(bool)

Releases the resources used by the LogWriter.

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

">true to release managed and unmanaged resources; false to release only unmanaged resources.

FilterCheckingFailed(Exception, LogEntry, ILogFilter)

This method supports the Enterprise Library infrastructure and is not intended to be used directly from your code. Performs any action to handle an error during checking.

public bool FilterCheckingFailed(Exception ex, LogEntry logEntry, ILogFilter filter)

Parameters

ex Exception

The exception that was raised during filter evaluation.

logEntry LogEntry

The log entry that was evaluated.

filter ILogFilter

The filter that raised the exception.

Returns

bool

true, to indicate that processing should continue.

~LogWriter()

Finalizes an instance of the LogWriter class.

protected ~LogWriter()

FlushContextItems()

Empties the dictionary of context items.

[SecurityCritical]
public void FlushContextItems()

GetFilter(string)

Returns the filter named name.

public ILogFilter GetFilter(string name)

Parameters

name string

The name of the filter required.

Returns

ILogFilter

The filter named name in the filters collection, or null if there is no such filter.

GetFilter<T>()

Returns the filter of type T.

public T GetFilter<T>() where T : class, ILogFilter

Returns

T

The instance of T in the filters collection, or null if there is no such instance.

Type Parameters

T

The type of filter requiered.

GetFilter<T>(string)

Returns the filter of type T named name.

public T GetFilter<T>(string name) where T : class, ILogFilter

Parameters

name string

The name of the filter required.

Returns

T

The instance of T named name in the filters collection, or null if there is no such instance.

Type Parameters

T

The type of filter required.

GetMatchingTraceSources(LogEntry)

Gets a list of LogSource objects for the log entry.

public IEnumerable<LogSource> GetMatchingTraceSources(LogEntry logEntry)

Parameters

logEntry LogEntry

The LogEntry to get the matching trace sources.

Returns

IEnumerable<LogSource>

A collection of LogSource objects.

IsLoggingEnabled()

Queries whether logging is enabled.

public bool IsLoggingEnabled()

Returns

bool

true if logging is enabled.

IsTracingEnabled()

Queries whether tracing is enabled.

public bool IsTracingEnabled()

Returns

bool

true if tracing is enabled.

SetContextItem(object, object)

Adds a key/value pair to the System.Runtime.Remoting.Messaging.CallContext dictionary.
Context items will be recorded with every log entry.

[SecurityCritical]
public void SetContextItem(object key, object value)

Parameters

key object

Hashtable key

value object

Value. Objects will be serialized.

Examples

The following example demonstrates use of the AddContextItem method.

Logger.SetContextItem("SessionID", myComponent.SessionId);

ShouldLog(LogEntry)

Queries whether the specified LogEntry should be logged.

public bool ShouldLog(LogEntry log)

Parameters

log LogEntry

The log entry to check.

Returns

bool

true if the entry should be logged; otherwise, false.

Write(LogEntry)

Writes the specified log entry.

public void Write(LogEntry log)

Parameters

log LogEntry

The log entry to write.

Write(object)

Write a new log entry to the default category.

public void Write(object message)

Parameters

message object

Message body to log. Value from ToString() method from message object.

Write(object, IDictionary<string, object>)

Write a new log entry and a dictionary of extended properties.

public void Write(object message, IDictionary<string, object> properties)

Parameters

message object

Message body to log. Value from ToString() method from message object.

properties IDictionary<string, object>

Dictionary of key/value pairs to log.

Write(object, IEnumerable<string>)

Write a new log entry to a specific collection of categories.

public void Write(object message, IEnumerable<string> categories)

Parameters

message object

Message body to log. Value from ToString() method from message object.

categories IEnumerable<string>

Category names used to route the log entry to a one or more trace listeners.

Write(object, IEnumerable<string>, IDictionary<string, object>)

Write a new log entry to a specific collection of categories with a dictionary of extended properties.

public void Write(object message, IEnumerable<string> categories, IDictionary<string, object> properties)

Parameters

message object

Message body to log. Value from ToString() method from message object.

categories IEnumerable<string>

Category names used to route the log entry to a one or more trace listeners.

properties IDictionary<string, object>

Dictionary of key/value pairs to log.

Write(object, IEnumerable<string>, int)

Write a new log entry with a specific collection of categories and priority.

public void Write(object message, IEnumerable<string> categories, int priority)

Parameters

message object

Message body to log. Value from ToString() method from message object.

categories IEnumerable<string>

Category names used to route the log entry to a one or more trace listeners.

priority int

Only messages must be above the minimum priority are processed.

Write(object, IEnumerable<string>, int, IDictionary<string, object>)

Write a new log entry to with a specific collection of categories, priority and a dictionary of extended properties.

public void Write(object message, IEnumerable<string> categories, int priority, IDictionary<string, object> properties)

Parameters

message object

Message body to log. Value from ToString() method from message object.

categories IEnumerable<string>

Category names used to route the log entry to a one or more trace listeners.

priority int

Only messages must be above the minimum priority are processed.

properties IDictionary<string, object>

Dictionary of key/value pairs to log.

Write(object, IEnumerable<string>, int, int)

Write a new log entry with a specific collection of categories, priority and event id.

public void Write(object message, IEnumerable<string> categories, int priority, int eventId)

Parameters

message object

Message body to log. Value from ToString() method from message object.

categories IEnumerable<string>

Category names used to route the log entry to a one or more trace listeners.

priority int

Only messages must be above the minimum priority are processed.

eventId int

Event number or identifier.

Write(object, IEnumerable<string>, int, int, TraceEventType)

Write a new log entry with a specific collection of categories, priority, event id and severity.

public void Write(object message, IEnumerable<string> categories, int priority, int eventId, TraceEventType severity)

Parameters

message object

Message body to log. Value from ToString() method from message object.

categories IEnumerable<string>

Category names used to route the log entry to a one or more trace listeners.

priority int

Only messages must be above the minimum priority are processed.

eventId int

Event number or identifier.

severity TraceEventType

Log entry severity as a TraceEventType enumeration. (Unspecified, Information, Warning or Error).

Write(object, IEnumerable<string>, int, int, TraceEventType, string)

Write a new log entry with a specific collection of categories, priority, event id, severity and title.

public void Write(object message, IEnumerable<string> categories, int priority, int eventId, TraceEventType severity, string title)

Parameters

message object

Message body to log. Value from ToString() method from message object.

categories IEnumerable<string>

Category names used to route the log entry to a one or more trace listeners.

priority int

Only messages must be above the minimum priority are processed.

eventId int

Event number or identifier.

severity TraceEventType

Log message severity as a TraceEventType enumeration. (Unspecified, Information, Warning or Error).

title string

Additional description of the log entry message

Write(object, IEnumerable<string>, int, int, TraceEventType, string, IDictionary<string, object>)

Write a new log entry with a specific category, priority, event Id, severity title and dictionary of extended properties.

public void Write(object message, IEnumerable<string> categories, int priority, int eventId, TraceEventType severity, string title, IDictionary<string, object> properties)

Parameters

message object

Message body to log. Value from ToString() method from message object.

categories IEnumerable<string>

Category names used to route the log entry to a one or more trace listeners.

priority int

Only messages must be above the minimum priority are processed.

eventId int

Event number or identifier.

severity TraceEventType

Log message severity as a TraceEventType enumeration. (Unspecified, Information, Warning or Error).

title string

Additional description of the log entry message.

properties IDictionary<string, object>

Dictionary of key/value pairs to log.

Write(object, string)

Write a new log entry to a specific category.

public void Write(object message, string category)

Parameters

message object

Message body to log. Value from ToString() method from message object.

category string

Category name used to route the log entry to a one or more trace listeners.

Write(object, string, IDictionary<string, object>)

Write a new log entry to a specific category with a dictionary of extended properties.

public void Write(object message, string category, IDictionary<string, object> properties)

Parameters

message object

Message body to log. Value from ToString() method from message object.

category string

Category name used to route the log entry to a one or more trace listeners.

properties IDictionary<string, object>

Dictionary of key/value pairs to log.

Write(object, string, int)

Write a new log entry with a specific category and priority.

public void Write(object message, string category, int priority)

Parameters

message object

Message body to log. Value from ToString() method from message object.

category string

Category name used to route the log entry to a one or more trace listeners.

priority int

Only messages must be above the minimum priority are processed.

Write(object, string, int, IDictionary<string, object>)

Write a new log entry to with a specific category, priority and a dictionary of extended properties.

public void Write(object message, string category, int priority, IDictionary<string, object> properties)

Parameters

message object

Message body to log. Value from ToString() method from message object.

category string

Category name used to route the log entry to a one or more trace listeners.

priority int

Only messages must be above the minimum priority are processed.

properties IDictionary<string, object>

Dictionary of key/value pairs to log.

Write(object, string, int, int)

Write a new log entry with a specific category, priority and event id.

public void Write(object message, string category, int priority, int eventId)

Parameters

message object

Message body to log. Value from ToString() method from message object.

category string

Category name used to route the log entry to a one or more trace listeners.

priority int

Only messages must be above the minimum priority are processed.

eventId int

Event number or identifier.

Write(object, string, int, int, TraceEventType)

Write a new log entry with a specific category, priority, event id and severity.

public void Write(object message, string category, int priority, int eventId, TraceEventType severity)

Parameters

message object

Message body to log. Value from ToString() method from message object.

category string

Category name used to route the log entry to a one or more trace listeners.

priority int

Only messages must be above the minimum priority are processed.

eventId int

Event number or identifier.

severity TraceEventType

Log entry severity as a TraceEventType enumeration. (Unspecified, Information, Warning or Error).

Write(object, string, int, int, TraceEventType, string)

Write a new log entry with a specific category, priority, event id, severity and title.

public void Write(object message, string category, int priority, int eventId, TraceEventType severity, string title)

Parameters

message object

Message body to log. Value from ToString() method from message object.

category string

Category name used to route the log entry to a one or more trace listeners.

priority int

Only messages must be above the minimum priority are processed.

eventId int

Event number or identifier.

severity TraceEventType

Log message severity as a TraceEventType enumeration. (Unspecified, Information, Warning or Error).

title string

Additional description of the log entry message

Write(object, string, int, int, TraceEventType, string, IDictionary<string, object>)

Write a new log entry with a specific category, priority, event Id, severity title and dictionary of extended properties.

public void Write(object message, string category, int priority, int eventId, TraceEventType severity, string title, IDictionary<string, object> properties)

Parameters

message object

Message body to log. Value from ToString() method from message object.

category string

Category name used to route the log entry to a one or more trace listeners.

priority int

Only messages must be above the minimum priority are processed.

eventId int

Event number or identifier.

severity TraceEventType

Log message severity as a TraceEventType enumeration. (Unspecified, Information, Warning or Error).

title string

Additional description of the log entry message.

properties IDictionary<string, object>

Dictionary of key/value pairs to log.

Examples

The following example demonstrates use of the Write method with a full set of parameters.