Share via

Source Schema for the Logging Application Block

  • Article
Retired Content

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
The latest Enterprise Library information can be found at the Enterprise Library site.

This topic lists the elements and attributes used to configure the Logging Application Block. The configuration file has the following section-handler declaration.

<configSections>
<section name="loggingConfiguration"
         type="Microsoft.Practices.EnterpriseLibrary.Logging.Configuration.LoggingSettings, 
               Microsoft.Practices.EnterpriseLibrary.Logging, Version=4.1.0.0,
               Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
</configSections>

The section-handler declaration contains the name of the configuration settings section and the name of the section-handler class that processes configuration data in that section. The name of the configuration settings section is loggingConfiguration. The name of the section-handler class is Microsoft.Practices.EnterpriseLibrary.Logging.Configuration.LoggingSettings.

loggingConfiguration Element

This element specifies the configuration of a Logging Application Block. This element is required.

Attributes and Child Elements

The following sections describe the attributes and child elements of the loggingConfiguration element. This element is required.

Attributes

The following table lists the attributes for the loggingConfiguration element.

Attribute

Description

defaultCategory

Send log entries to this category if no other category is specified. This attribute is required.

tracingEnabled

Specifies whether activity tracing is enabled. Possible values are true and false. The default is true. This attribute is optional.

logWarningsWhenNoCategoriesMatch

Specifies whether events should be sent to the errors special source if a log entry contains a category that is not specified in configuration. Possible values are true and false. The default is true. This attribute is optional.

revertImpersonation

Specifies whether to opt-out of impersonation-reverting. To opt-out of the impersonation-reverting default mode, set revertImpersonation to false. Support includes configuration support, design time support, and manageability support (both WMI and group policy). The default is true. This attribute is optional.

logFilters Child Element

The logFilters element is a child element of the loggingConfiguration element. It lists the filters that process the log entry before it is routed to the trace sources. This element is optional.

add Child Element

The add element is a child element of the logFilters element. The add element adds a log filter. This element is optional. There can be multiple add elements.

Attributes

The following table lists the attributes for the add element.

Attribute

Description

name

The name of the log filter. The name must be unique within the section. This attribute is required.

type

The type name of the class that implements the ILogFilter interface. This attribute is required.

enabled

Specifies whether logging is enabled or disabled for the application. This attribute applies to the LogEnabledFilter class. Possible values are true and false. This attribute is optional.

minimumPriority

Specifies the minimum priority a log entry must have to be logged. The attribute applies to the PriorityFilter class. It is an integer. If this attribute is omitted, there is no minimum. It is optional.

maximumPriority

Specifies the maximum priority a log entry can have to be logged. The attribute applies to the PriorityFilter class. It is an integer. If this attribute is omitted, there is no maximum. It is optional.

categoryFilterMode

Specifies whether the categories listed under <categoryFilters> are allowed or denied. This attribute applies to the CategoryFilter class. Possible values are AllowAllExceptDenied and DenyAllExceptAllowed. This attribute is required.

categoryFilters Child Element

The categoryFilters element is a child of the logFilters element. It lists the categories that are allowed or denied. This element is optional.

add Child Element

The add element is a child element of the categoryFilters element. The add element adds a category. This element is optional. There can be multiple add elements.

Attributes

The following table lists the attributes for the add element.

Attribute

Description

Name

The name of the category that is allowed or denied. This attribute is a string. It is required.

categorySources Child Element

The categorySources element is a child of the loggingConfiguration element. It defines the trace sources that route log entries belonging to specific categories to trace listeners.

add Child Element

The add element is a child element of the categorySources element. The add element adds a trace source. This element is optional. There can be multiple add elements.

Attributes

The following table lists the attributes for the add element.

Attribute

Description

name

The name of the log entry category that this trace source accepts. The name must be unique within the section. This attribute is required.

switchValue

Sets the SourceLevels property of the category. Specifies the severity level of events that are handled by this trace source. Possible values are ActivityTracing, All, Critical, Error, Information, Off, Verbose, and Warning. This attribute is required.

autoFlush

Specifies if the listener will flush its data to the target after every new entry is written to this source. The default value is true. When set to false, code can flush the entries when required.

Remarks

The meanings of the switchValue attribute values are as follows:

  • Activity Tracing. Allows the Stop, Start, Suspend, Transfer, and Resume events through.
  • All. Allows all events through.
  • Critical. Allows only Critical events through. A critical event is a fatal error or application crash.
  • Error. Allows Critical and Error events through. An Error event is a recoverable error.
  • Information. Allows Critical, Error, Warning, and Information events through. An information event is an informational message.
  • Off. Does not allow any events through.
  • Verbose. Allows Critical, Error, Warning, Information, and Verbose events through. A Verbose event is a debugging trace.
  • Warning. Allows Critical, Error, and Warning events through. A Warning event is a non-critical problem.

For more information about these values, see TraceEventType Enumeration in the .NET Class Framework Library on MSDN.

listeners Child Element (categorySources)

This listeners element is a child of the categorySources element. The listeners element specifies the trace listeners (listed in the listeners child element of the loggingConfiguration section) that the log entries are routed to. This element is optional.

add Child Element

The add element is a child element of the listeners element. The add element adds a trace listener. This element is optional. There can be multiple add elements.

Attributes

The following table lists the attributes for the add element.

Attribute

Description

name

The name of a listener from the listeners section. This attribute is required.

specialSources Child Element

The specialSources element is a child of the loggingConfiguration element. It specifies the special trace sources that can process certain types of log entries. This element is required.

errors Child Element

The errors element is a child of the specialSources element. It specifies the error special trace source. This trace source receives events for errors and warnings that occur during the logging process. This element is required.

Attributes

The following table lists the attributes for the errors element.

Attribute

Description

name

The name of the trace source. The name must be unique within the section. This attribute is required.

switchValue

Sets the SourceLevels property. Specifies the severity level of events that are handled by this trace source. Possible values are ActivityTracing, All, Critical, Error, Information, Off, Verbose, and Warning. This attribute is required.

Remarks

The switchValue attribute values are defined in the categorySources section of this topic.

listeners Child Element (errors)

This listeners element is a child of the errors element. It specifies the trace listeners (listed in the listeners child element of the loggingConfiguration section) that a log entry is routed to. This element is optional.

add Child Element

The add element is a child of the listeners element. It adds a trace listener. This element is optional. There can be multiple add elements.

Attributes

The following table lists the attributes for the add element.

Attribute

Description

Name

The name of a listener from the listeners section. This attribute is required.

notProcessed Child Element

The notProcessed element is a child of the specialSources element. It specifies the unprocessed special trace source. This trace source receives log entries that are included in categories that were not processed by a category-based trace source. This element is optional.

Attributes

The following table lists the attributes for the notProcessed element.

Attribute

Description

name

The name of the trace source. The name must be unique within the section. This attribute is required.

switchValue

Sets the SourceLevels property. Specifies the severity level of events that are handled by this trace source. Possible values are ActivityTracing, All, Critical, Error, Information, Off, Verbose, and Warning. This attribute is required.

Remarks

The switchValue attribute values are defined in the categorySources section of this topic.

listeners Child Element (notProcessed)

This listeners element is a child of the notProcessed element. It specifies the trace listeners (listed in the listeners child element of the loggingConfiguration section) that a log entry is routed to. This element is optional.

add Child Element

The add element is a child of the listeners element. It adds a trace listener (listed in the listeners child element of the loggingConfiguration section). This element is optional. There can be multiple add elements.

Attributes

The following table lists the attributes for the add element.

Attribute

Description

Name

The name of a listener from the listeners section. This attribute is required.

allEvents Child Element

The allEvents element is a child of the specialSources element. It specifies the all events special trace source. This trace source receives all log entries, whether or not they have been processed by other trace sources. This element is optional.

Attributes

The following table lists the attributes for the allEvents element.

Attribute

Description

name

The name of the trace source. The name must be unique within the section. This attribute is required.

switchValue

Sets the SourceLevels property. Specifies the severity level of events that are handled by this trace source. Possible values are ActivityTracing, All, Critical, Error, Information, Off, Verbose, and Warning. This attribute is required.

Remarks

The switchValue attribute values are defined in the categorySources section of this topic.

listeners Child Element (allEvents)

This listeners element is a child of the allEvents element. It specifies the trace listeners (listed in the listeners child element of the loggingConfiguration section) that a log entry is routed to. This element is optional.

add Child Element

The add element is a child of the listeners element. It adds a trace listener. This element is optional. There can be multiple add elements.

Attributes

The following table lists the attributes for the add element.

Attribute

Description

name

The name of a listener from the listeners section. This attribute is required.

listeners Child Element (loggingConfiguration)

The loggingConfiguration section contains details of the listeners referenced in other listeners elements. The listeners child element of the loggingConfiguration element lists the trace listeners that the Logging Application Block can use with the application. This element is optional.

add Child Element

The add element is a child element of the listeners element. The add element adds a trace listener. This element is optional. There can be multiple add elements.

Attributes

The following table lists the attributes for the add element.

Attribute

Description

name

The name of the trace listener. This can be any name. This attribute is required.

type

The type name of a class that derives from the TraceListener class. This attribute is required.

traceOutputOptions

Can attach additional information to platform-provided trace listener output. Possible values are CallStack, DateTime, LogicalOperationStack, None, ProcessId, ThreadId, and Timestamp. This attribute is optional.

listenerDataType

The type name of a class that derives from the TraceListenerData class. This attribute is required.

filter

Applies a filter that selects the level of message that it will detect. The valid values are All (the default), Off, Critical, Error, Warning, Information, Verbose, and Activity Tracing. The setting effectively means "the specified level and everything more important." For example, the Warning setting will detect warnings, errors, and critical events.

formatter

The name of the formatter that formats the LogEntry object into a string. This name must be included in the <formatters> section. This attribute applies to the FlatFile TraceListener, the Email TraceListener, the Formatted EventLog TraceListener, the Msmq TraceListener, the Database Trace Listener, the Rolling Flat File Trace Listener,the XML Trace Listener, and the Custom Trace Listener. This attribute is required for the Msmq TraceListener but not for other trace listeners.

fileName

The name of the file that receives the log entry. This attribute applies to the FlatFile TraceListener,the XML Trace Listener, and to the Rolling Flat File Trace Listener. It is required for these listeners.

header

Additional information contained in the file header. This attribute is a string and it applies to the FlatFile TraceListener. It is optional.

footer

Additional information contained in the file footer. This attribute is a string and it applies to the FlatFile TraceListener. It is optional.

toAddress

The address where the log entry is sent. This attribute is an e-mail address and it applies to the Email TraceListener. It is required for this listener.

fromAddress

The address where the log entry originated. This attribute is an e-mail address and it applies to the Email TraceListener. It is required for this listener.

subjectLineStarter

The subject line prefix. This attribute is a string and it applies to the Email TraceListener. It is optional.

subjectLineEnder

The subject line suffix. This attribute is a string and it applies to the Email TraceListener. It is optional.

smtpServer

The SMTP server used to send e-mail messages. This attribute is a string and it applies to the Email TraceListener. It is optional.

smtpPort

The SMTP port that receives e-mail messages. This attribute is an integer and it applies to the Email TraceListener. It is optional.

log

The name of the log where entries are written. This attribute is a string and it applies to the Formatted EventLog TraceListener. It is optional.

source

The source name to use when writing to the log. This attribute is a string and it applies to the Formatted EventLog TraceListener. It is required for this listener.

machineName

The name of the computer on which to write log entries. This attribute is a string and it applies to the Formatted EventLog TraceListener. It is optional.

queuePath

The path to the queue that the Msmq TraceListener uses. This attribute is a message queuing path and it applies to the Msmq TraceListener. It is required for this listener.

messagePriority

Sets the priority of a log entry. This determines its priority while it is in transit to the queue, and its position in the destination queue. Possible values are AboveNormal, High, Highest, Low, Lowest, Normal, VeryHigh, and VeryLow. It applies to the MsmqTraceListener class. This attribute is optional.

timeToReachQueue

The maximum amount of time for the log entry to reach the queue. It applies to the Msmq TraceListener. This attribute is of type Timespan. It is optional.

timeToBeReceived

The total time for a log entry to be received by the destination queue. It applies to the Msmq TraceListener. This attribute is of type Timespan. It is optional.

recoverable

Specifies whether the log entry is guaranteed to be delivered if there is a computer failure or network problem. Possible values are true a false. It applies tothe Msmq TraceListener. This attribute is optional.

useAuthentication

Specifies whether the message was (or must be)authenticated before being sent. Possible values are true or false. It applies to the Msmq TraceListener. This attribute is optional.

useDeadLetterQueue

Specifies whether a copy of a message that could not be delivered should be sent to a dead-letter queue. Possible values are true or false. It applies to the Msmq TraceListener. This attribute is optional.

useEncryption

Specifies whether to make the message private. Possible values are true or false. It applies to the Msmq TraceListener. This attribute is optional.

transactionType

Specifies the type of a Message Queuing transaction. Possible values are Automatic, None, and Single. It applies to the Msmq TraceListener. This attribute is optional.

AddCategoryStoredProcedure

The name of the stored procedure that adds a category. It applies to the Database TraceListener. The default is AddCategory. This is required for this listener.

DatabaseInstance

The name of the database instance to use. It applies to the Database TraceListener. This is required for this listener.

Formatter

The formatter to use with this trace listener. Select one from the drop-down list. The default is None. This is optional.

Name

The name of the trace listener. This is required.

TraceOutputOptions

A property used by trace listeners to determine which options, or elements, should be included in the trace output. Possible values are CallStack, DateTime, LogicalOperationStack, None, ProcessId, ThreadId, and Timestamp. The default is None. For an explanation of the values, see the "Remarks" section. This is optional.

WriteLogStoredProcedureName

The name of the stored procedure that writes the log entries. It applies to the Database TraceListener. The default is WriteLog. This is required for this listener.

rollSize

The size in kilobytes that the file can reach before it rolls over. It applies to the Rolling FlatFile TraceListener. This is optional.

timeStampPattern

The format of the date that is appended to the name of the new file. It applies to the Rolling FlatFile TraceListener. This is required for this listener.

rollInterval

The time interval that determines when the file rolls over. It applies to the Rolling FlatFile TraceListener. Possible values are None (the default), Minute, Hour, Day, Week, Month, and Year. This is required for this listener.

rollFileExistsBehavior

The behavior that occurs when the roll file is created. It applies to the Rolling FlatFile TraceListener. Possible values are Overwrite (the default), which overwrites the existing filea Increment, whichcreates a new file. It names the file by incrementing the time stamp.For more information, see the section "Rolling Flat File Trace Listener."

Remarks

The meanings of the values for the traceOutputOptions attribute are as follows:

  • Callstack. Write the call stack, which is represented by the return value of the System.Environment.StackTrace property.
  • DateTime. Write the date and time.
  • LogicalOperationStack. Write the logical operation stack, which is represented by the return value of the System.Diagnostics.CorrelationManager.LogicalOperationStack property.
  • None. Do not write any elements.
  • ProcessId. Write the process identity, which is represented by the return value the System.Diagnostics.Process.Id property.
  • ThreadId. Write the ThreadIdentity, which is represented by the return value the System.Threading.Thread.ManagedThreadId property for the current thread.
  • Timestamp. Write the timestamp, which is represented by the return value of the System.Diagnostics.Stopwatch.GetTimeStamp method.

For more information about these values, see TraceOptions Fields in the .NET Framework Class Library on MSDN.

The meanings of the values for the messagePriority attribute are as follows:

  • High. High message priority.
  • Highest. Highest priority.
  • Low. Low priority.
  • Lowest. Lowest priority.
  • Normal. Normal priority.
  • VeryHigh. Between Highest and High priority.
  • VeryLow. Between Low and Lowest priority.

For more information about these values, see MessagePriority Enumeration in the .NET Framework Class Library on MSDN.

The meanings of the values for the transactionType attribute are as follows:

  • Automatic. A transaction type used for Microsoft Transaction Server (MTS) or COM+ 1.0 Services. If there is already an MTS transaction context, it will be used when sending or receiving the message.
  • None. Operation will not be transactional.
  • Single. Transaction type used for single internal transactions.

For more information about these values, see MessageQueueTransactionType Enumeration in the .NET Framework Class Library on MSDN.

formatters Child Element

The formatters element is a child of the loggingConfiguration element. This element specifies formatters that format LogEntry objects. Formatters are used by formatting-aware trace listeners. This element is optional.

add Child Element

The add element is a child element of the formatters element. The add element adds a formatter. This element is optional. There can be multiple add elements.

Attributes

The following table lists the attributes for the add element.

Attribute

Description

name

The name of a formatter. The name must be unique within the section. This attribute is required.

type

The type name of a class that implements the ILogFormatter interface. This attribute is required.

template

This contains a template, including special tokens, that will be used by a formatter. This attribute applies to the TextFormatter class. It is a string and it is required for this formatter.

msmqDistributorSettings Element

The msmqDistributorSettings element controls the configuration of the Logging Application Block's distributor service. This element is required if you want to use Message Queuing to distribute log entries.

Attributes

The following table lists the attributes for the msmqDistributorSettings element.

Attribute

Description

msmqPath

The name of the message queue. The default is ".\Private$\entlib". This attribute is required.

queueTimerInterval

The time interval that controls how often the distributor polls the message queue for log entries. The interval is measured in milliseconds. The default is 1,000. This attribute is optional.

serviceName

The name of the distributor service. The default is "Enterprise Library Distributor Service". This attribute is required.