Source Schema for the Logging Application Block

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" />
</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 (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 Minimum Severity (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:

• ActivityTracing. 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.

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 an <add> section for a 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 Minimum Severity (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 Minimum Severity (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 Minimum Severity (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 alphabetically by attribute name.

Attribute	Description
addCategoryStoredProcedure	The name of the stored procedure that adds a category. It applies to the database trace listener. The default is AddCategory. This is required for this listener.
databaseInstanceName	The name of the database instance to use. It applies to the database trace listener. this is required for this listener.
fileName	The name of the file that receives the log entry. This attribute applies to the flat file trace listener, the XML trace listener, and to the rolling flat file trace listener. It is required for these listeners.
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 ActivityTracing. The setting effectively means "the specified level and everything more important." For example, the Warning setting will detect warnings, errors, and critical events.
footer	Additional information contained in the file footer. This attribute is a string and it applies to the flat file trace listener. It is optional.
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 theflat file trace listener, the e-mail trace listener, the event log trace listener, the message queuing trace listener, 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 message queuing trace listener but not for other trace listeners.
fromAddress	The address where the log entry originated. This attribute is an e-mail address and it applies to the e-mail trace listener. It is required for this listener.
header	Additional information contained in the file header. This attribute is a string and it applies to the flat file trace listener. It is optional.
listenerDataType	The type name of a class that derives from the TraceListenerData class. This attribute is required.
log	The name of the log where entries are written. This attribute is a string and it applies to the event log trace listener. It is optional.
machineName	The name of the computer on which to write log entries. This attribute is a string and it applies to the event log trace listener. It is optional.
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 Message Queuing Trace Listener class. This attribute is optional.
name	The name of the trace listener. This can be any name. This attribute is required.
queuePath	The path to the queue that the message queuing trace listener uses. This attribute is a message queuing path and it applies to the message queuing trace listener. It is required for this listener.
recoverable	Specifies whether the log entry is guaranteed to be delivered if there is a computer failure or network problem. Possible values are true and false. It applies tothe message queuing trace listener. This attribute is optional.
rollFileExistsBehavior	The behavior that occurs when the roll file is created. It applies to the rolling flat file trace listener. Possible values are Overwrite (the default), which overwrites the existing fileand 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" in the topic Trace Listener Properties.
rollInterval	The time interval that determines when the file rolls over. It applies to the rolling flat file trace listener. Possible values are None (the default), Minute, Hour, Day, Midnight, Week, Month, and Year. 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 flat file trace listener. This is optional.
smtpPort	The SMTP port that receives e-mail messages. This attribute is an integer and it applies to the e-mail trace listener. It is optional.
smtpServer	The SMTP server used to send e-mail messages. This attribute is a string and it applies to the e-mail trace listener. It is optional.
source	The source name to use when writing to the log. This attribute is a string and it applies to the event log trace listener. It is required for this listener.
subjectLineEnder	The subject line suffix. This attribute is a string and it applies to thee-mail trace listener. It is optional.
subjectLineStarter	The subject line prefix. This attribute is a string and it applies to the e-mail trace listener. It is optional.
timeStampPattern	The format of the date that is appended to the name of the new file. It applies to the rolling flat file trace listener. This is required for this listener.
timeToBeReceived	The total time for a log entry to be received by the destination queue. It applies to the message queuing trace listener. This attribute is of type Timespan. It is optional.
timeToReachQueue	The maximum amount of time for the log entry to reach the queue. It applies to the message queuing trace listener. This attribute is of type Timespan. It is optional.
toAddress	The address where the log entry is sent. This attribute is an e-mail address and it applies to the e-mail trace listener. It is required for this listener.
traceOutputOptions	A property used by trace listeners that do not output to a text formatter 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.
transactionType	Specifies the type of a Message Queuing transaction. Possible values are Automatic, None, and Single. It applies to the message queuing trace listener. This attribute is optional.
type	The type name of a class that derives from the TraceListener class. This attribute is required.
useAuthentication	Specifies whether the message was (or must be)authenticated before being sent. Possible values are true or false. It applies to the message queuing trace listener. 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 message queuing trace listener. This attribute is optional.
useEncryption	Specifies whether to make the message private. Possible values are true or false. It applies to the message queuing trace listener. This attribute is optional.
writeLogStoredProcedureName	The name of the stored procedure that writes the log entries. It applies to the database trace listener. The default is WriteLog. This is required for this listener.

Remarks

The meanings of the values for the traceOutputOptions attribute are shown in the table in the topic TraceOutputOptions Values. The values for the messagePriority attribute are as follows, in descending order of priority: Highest, VeryHigh, High, AboveNormal, Normal, Low, VeryLow, and Lowest. 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.