Logging Application Block Properties
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. |
The tables in this topic explain the Logging Application Block properties.
Trace Listener Properties
These tables explain the properties for the different trace listeners. There are tables for the following trace listeners:
- CustomTrace Listener. This is a class you have created that derives from the CustomTraceListener class.
- EmailTrace Listener. This is a trace listener that sends out log entries as e-mail.
- Flat FileTrace Listener. This is a trace listener that writes log entries to a text file.
- Database Trace Listener. This is a trace listener that writes formatted log entries to a database.
- FormattedEvent LogTraceListener. This is a trace listener that formats log entries and writes them to an event log.
- MsmqTraceListener. This is a trace listener that writes log entries to a message queue.
- System DiagnosticsTraceListener. This is one of the .NET Framework trace listeners such as the Console Trace Listener.
- WMITraceListener. This is a****trace listener that raises a WMI management event for each log entry received.
- Rolling Flat File Trace Listener. This is a trace listener that creates a new log file depending on the current log file's age and/or size.
- XML TraceListener. This trace listener is used to integrate the Logging Application Block with applications that use WCF.
Custom TraceListener
Table 1 lists the properties that appear when you add a custom trace listener to the configuration.
Table 1: Custom TraceListener Properties
Property |
Description |
---|---|
Attributes |
The key/value pairs. To edit these, click the ellipsis button (…) and use the EditableKeyValueCollectionEditor. The attributes are a collection of key/value string pairs of configuration information for the custom trace listener. |
Formatter |
The formatter to use with this trace listener. Click the formatter you want to use in the drop-down list. The default is none. This is optional. |
Name |
The name of the trace listener. The default is CustomTrace Listener. This is required. |
TraceOutputOptions |
Trace listeners use this property 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 these values, see the TraceOutputOptions Values table. This is optional. |
Type |
The type of the trace listener. The type must derive from the CustomTraceListener class. Click the ellipsis (…) button to view the Type Selector dialog box, and then click the type you want. This is required. |
Database TraceListener
Table 2 lists the properties that appear when you add a DatabaseTraceListener.
Table 2 Database TraceListener Properties
Property |
Description |
---|---|
AddCategoryStoredProcedure |
The name of the stored procedure that adds a category. The default is AddCategory. This is required. |
DatabaseInstance |
The name of the database instance to use. The default is none. This is required. |
Formatter |
The formatter to use with this trace listener. Select from the drop-down list. The default is none. This is optional. |
Name |
The name of the trace listener. The default is Database 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 these values, see the TraceOutputOptions Values table. This is optional. |
WriteLogStoredProcedureName |
The name of the stored procedure that writes the log entries. The default is WriteLog. This is required. |
Email TraceListener
Table 3 lists the properties that appear when you add an EmailTraceListener.
Table 3: Email TraceListener Properties
Property |
Description |
---|---|
Formatter |
The formatter to use with this trace listener. Select from the drop-down list. The default is none. This is optional. |
FromAddress |
The address where the log entry originated. The default is from@example.com. This is required. |
Name |
The name of the trace listener. The default is EmailTraceListener. This is required. |
SmtpPort |
The SMTP port that receives e-mail messages. The default is 25. This is optional. |
SmtpServer |
The SMTP server used to send e-mail messages. The default is 127.0.0.1. This is optional. |
SubjectLineEnder |
The subject line suffix. This is optional. |
SubjectLineStarter |
The subject line prefix. This is optional. |
ToAddress |
The address where the log entry is sent. The default is to@example.com. This is required. |
TraceOutputOptions |
Trace listeners use this property 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 these values, see the TraceOutputOptions Values table. This is optional. |
Flatfile TraceListener
Table 4 lists the properties that appear when you add a FlatfileTraceListener.
Table 4: Flatfile TraceListener Properties
Property |
Description |
---|---|
Filename |
The name of the file where entries are written. The default name is trace.log. This is required. |
Footer |
Additional information contained in the file footer. The default is ----------------------------------------. This is optional. |
Formatter |
The formatter to use with this trace listener. Select from the drop-down list. The default is none. This is optional. |
Header |
Additional information contained in the file header. The default is ----------------------------------------. This is optional. |
Name |
The name of the trace listener. The default is FlatFile TraceListener. This is required. |
TraceOutputOptions |
Trace listeners use this property 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 these values, see the TraceOutputOptions Values table. This is optional. |
Note
When you use the FlatFileTraceListener class to write log information to a file, the application block locks the file until the application closes. It is possible to open and read the file but you cannot move or delete the log file until you close the application.
Formatted EventLog TraceListener
Table 5 lists the properties that appear when you add a FormattedEventLogTraceListener.
Table 5: Formatted EventLog TraceListener Properties
Property |
Description |
---|---|
Formatter |
The formatter to use with this trace listener. Select from the drop-down list. The default is none. This is optional. |
Log |
The name of the event log where entries are written. The default is Application. This is optional. |
MachineName |
The name of the computer on which to write log entries. This is optional. |
Name |
The name of the trace listener. The default is Formatted EventLog TraceListener. This is required. |
Source |
The source name to use when writing to the log. The default is Enterprise Library Logging. This is required. |
TraceOutputOptions |
Trace listeners use this property 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 these values, see the TraceOutputOptions Values table. This is optional. |
MSMQ TraceListener
Table 6 lists the properties that appear when you add an MsmqTraceListener.
Table 6: Msmq TraceListener Properties
Property |
Description |
---|---|
Formatter |
The formatter to use with this trace listener. Select from the drop-down list. This must be the Binary Formatter when you use this listener with the Message Queuing distributor service. This is optional. |
MessagePriority |
Sets the priority of a log entry. This determines its place while the log entry is traveling and when it is inserted into its destination queue. Possible values are AboveNormal,High, Highest, Low, Lowest, Normal, VeryHigh, and VeryLow. It applies to the MsmqTraceListener class. The default is Normal. This is optional. |
Name |
The name of the trace listener. The default is MsmqTraceListener. |
QueuePath |
The path to the queue that the MsmqTraceListener instance uses. This attribute is a message queuing path, and it applies to the MsmqTraceListener class. The default is .\Private$\myQueue. This is required. |
Recoverable |
Specifies whether the log entry is guaranteed to be delivered if there is a computer failure or network problem. The default is False. This is optional. |
TimeToBeReceived |
The total time for a log entry to be received by the destination queue. The default is 49710,06:28:15. This is optional. |
TimeToReachQueue |
The maximum time for the log entry to reach the queue. The default is 49710,06:28:15. This is optional. |
TraceOutputOptions |
Attaches additional information to platform-provided trace listener output. Possible values are CallStack, DateTime, LogicalOperationStack, None, ProcessId, ThreadId, and Timestamp. The default is None. This is optional. |
TransactionType |
The type of a Message Queuing transaction. Possible values are Automatic, None, and Single. It applies to the MsmqTraceListener class. The default is None. This is optional. |
UseAuthentication |
Specifies whether the message was (or must be) authenticated before being sent. The default is False. This is optional. |
UseDeadLetterQueue |
Specifies whether a copy of a message that could not be delivered should be sent to a dead-letter queue. The default is False. This is optional. |
UseEncryption |
Specifies whether to make the message private. The default is False. This is optional. |
Rolling Flat File Trace Listener
Table 7 lists the properties that appear when you add a Rolling Flat File Trace Listener. This trace listener allows you to control the size and age of a log file.
Table 7: Rolling Flat File Trace Listener Properties
Property |
Description |
---|---|
Name |
This is the name of the trace listener. This is required. |
FileName |
This is the name of the rolling flat file. This is required. |
Footer |
Additional information contained in the file footer. The default is ----------------------------------------. This is optional. |
Formatter |
The formatter to use with this trace listener. Select from the drop-down list. The default is none. This is optional. |
Header |
Additional information contained in the file header. The default is ----------------------------------------. This is optional. |
RollFileExistsBehavior |
This property determines what occurs to an existing file when it rolls over. If you select Overwrite, then the existing file is overwritten. If you select Increment, the application block creates a new file and names it by incrementing the timestamp. |
RollInterval |
This property determines when the log file rolls over. You can select none (the default), minute, hour, day, month, or year. This is optional. |
RollSizeKB |
This is the maximum size the file can reach, in Kilobytes, before it rolls over. This is optional. |
TimeStampPattern |
This is the date/time format that is appended to the new filename as mentioned below. This is required. |
TraceOutputOptions |
Trace listeners use this option 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 these values, see the TraceOutputOptions Values table. This is optional. |
Remarks
- You can control either or both the size of the file and its age. For example, if you specify in configuration a RollSizeKB value of 5KB and a RollInterval value of Day, the file rolls when its size exceeds 5KB and it also rolls at the end of the day.
- If you select Increment for the RoleFileExistsBehavior, the application block creates a new file when the existing file rolls over. The file’s name includes the current timestamp. If a file with this name already exists, the application block adds an integer to the end of the timestamp and increments it until it cannot find a file with that name. For example, assume there is a file named mylog2007-01-1.8.log and the file rolls over while that timestamp is still valid. The application block will then look for a file named mylog2007-01-18.1.log. If no such file exists, it will use that file name for the new file. If that file also exists, it will then attempt to locate the log with the next sequence number mylog2007-01-18.2.log.
- If you select Overwrite for the RoleFileExistsBehavior, the application block creates a new file when the current file rolls over. The name of the file includes the current timestamp. If a file with that name already exists, the application block overwrites the file. If, for some reason, it cannot overwrite the file, it will generate a name according to the same process that is used with the Increment value.
- Relative path names resolve to a location that is relative to the AppDomain.CurrentDomain.BaseDirectory directory.
XML TraceListener
Table 8: XML TraceListener Properties
Property |
Description |
---|---|
Name |
This is the name of the trace listener. This is required. |
FileName |
This is the name of the file where the trace listener writes the data it extracts an XmlLogEntry object. This is required. |
TraceOutputOptions |
Trace listeners use this property 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 these values, see the TraceOutputOptions Values table. This is optional. |
System.Diagnostics TraceListener
The TraceListener class provides the abstract base class for trace listeners that monitor trace and debug output. Table 9 lists the properties that appear when you add a System.DiagnosticsTraceListener.
Note
If you specify a System.Diagnostics trace listener that writes to a file and that file is read-only, the trace listener does not write the data to the file and no exception occurs. Make sure the file attributes are set to read/write.
Table 9: System.Diagnostics TraceListener Properties
Property |
Description |
---|---|
InitData |
If supplied, this property is used when the application block constructs a trace listener. It is a string whose meaning depends on the type of trace listener being constructed. For the .NET Framework trace listeners, the string has the following values: TextWriterTraceListener: filename; XmlWriterListener: filename; DelimitedLIstTraceListener: filename; ConsoleTraceListener: not applicable; DefaultTraceListener: not applicable; EventLogTraceListener: event source name. If the InitData field is not specified, the application block uses the default constructor. If the user specifies the InitData field for a trace listener that does not have a constructor overload that accepts a string, an error occurs. This is optional. |
Name |
The name of the trace listener. The default is System.Diagnostics Trace Listener. This is required. |
TraceOutputOptions |
Trace listeners use this property 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 these values, see the TraceOutputOptions Values table. This is optional. |
Type |
The type of the trace listener. Select from the drop-down list. This is required. |
WMI Trace Listener
The WMITraceListener is a****trace listener that raises a WMI management event for each log entry it receives. Table 10 lists the properties that appear when you add a WMITraceListener.
Table 10: WMI TraceListener Properties
Property |
Description |
---|---|
Name |
The name of the trace listener. The default is WMI Trace Listener. This is required. |
TraceOutputOptions |
Trace listeners use this property 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 these values, see the TraceOutputOptions Values table. This is optional. |
TraceOutputOptions Values
Table 11 lists the possible TraceOutputOptions values.
Table 11: TraceOutputOptions Values
Value |
Description |
---|---|
CallStack |
Write the call stack, which is represented by the return value of the Environment.StackTrace property. |
DateTime |
Write the date and time. |
LogicalOperationsStack |
Write the logical operation stack, which is represented by the return value of the CorrelationManager.LogicalOperationStack property. |
None |
Do not write any elements. |
ProcessId |
Write the process identity, which is represented by the return value of the Process.ID property. |
ThreadId |
Write the ThreadIdentity, which is represented by the return value of the Thread.ManagedThreadIdProperty for the current thread. |
Timestamp |
Write the timestamp, which is represented by the return value of the System.Diagnostics.Stopwatch.GetTimeStamp method. |
Category Source Properties
Table 12 lists the CategorySource properties.
Table 12: Category Source Properties
Property |
Description |
---|---|
Name |
The name of the category. The default is Category Source. |
SourceLevels |
Possible values are ActivityTracing, All, Critical, Error, Information, Off, Verbose, and Warning. The default is All. |
SwitchLevel Values
Table 13 lists the possible SourceLevels values.
Table 13: SwitchLevel Values
Value |
Description |
---|---|
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. A Warning event is a non-critical problem. |
Filter Properties
These tables explain the properties for the different types of filters. There are tables for the following filters:
CategoryFilter. This allows or denies log entries based on their categories.
LogEnabledFilter. This either enables or disables logging.
PriorityFilter. This allows or denies log entries based on their priorities.
CustomFilter. This is a filter that you have added to the Logging Application Block.
Category Filter
Table 14 lists the properties that appear when you add a CategoryFilter.
Table 14: Category Filter Properties
Property |
Description |
---|---|
CategoryFilterExpression |
Sets up the rule for denying or allowing the specified categories. Use the Category Filter Editor to configure the expression. |
Name |
The name of the filter. The default is Category Filter. |
LogEnabled Filter
Table 15 lists the properties that appear when you add a LogEnabled Filter.
Table 15: LogEnabled Filter Properties
Property |
Description |
---|---|
Enabled |
Filter is enabled if value is True. The default is False. |
Name |
The name of the filter. The default is LogEnabledFilter. |
Priority Filter
Table 16 lists the properties that appear when you add a PriorityFilter.
Table 16: Priority Filter Properties
Property |
Description |
---|---|
MaximumPriority |
The maximum value a log entry can have to be logged. If you do not set this property, there is no maximum value. |
MinimumPriority |
The minimum value a log entry must have to be logged. If you do not set this property, there is no minimum value. The default is -1. |
Name |
The name of the filter. The default is PriorityFilter. |
Custom Filter
Table 17 lists the properties that appear when you add a CustomFilter.
Table 17: Custom Filter Properties
Property |
Description |
---|---|
Attributes |
The key/value pairs for this filter. Click the ellipsis button (…) and use the EditableKeyValue Collection Editor. |
Name |
The name of the filter. The default is Custom Filter. |
Type |
The type of the trace listener. Select from the drop-down list. This is required. |
Logging Application Block Properties
Table 18 lists the properties that appear when you add the Logging Application Block.
Table 18: Logging Application Block Properties
Attribute |
Description |
---|---|
DefaultCategory |
Log entries go to this category if no other category is specified. The default is General. This is required. |
Name |
The name is LoggingApplicationBlock. This is required. |
TracingEnabled |
Specifies whether activity tracing is enabled. Possible values are true or false. The default is false. This is optional. |
LogWarningsWhenNoCategoriesMatch |
Specifies whether events should be sent to the errors special source trace listener if a log entry contains a category that is not specified in configuration. Possible values are true or false. The default is false. This is optional. |
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. |