Entering Configuration Information

  • 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 procedure explains how to configure the Logging Application Block. Properties associated with the nodes appear in the right pane of the Configuration Console or the Properties window of the Visual Studio Configuration Editor.

For details of the schema for the Logging Application Block configuration, see Source Schema for the Logging Application Block.

Note

Run-time changes to the configuration of the Logging Application Block are automatically detected after a short period, and the logging stack is updated. However, you cannot modify the logging stack at run time through code. For details of using configuration mechanisms that you can update at run time, see Updating Configuration Settings at Run Time.

To add the Logging Application Block

  1. Open the configuration file. For more information, see Configuring Enterprise Library.
  2. Right-click Application Configuration, point to New, and then click Logging Application Block.

After you add the Logging Application Block to the application configuration, you need to configure some or all of the following elements:

  • Formatters
  • Trace listeners
  • Custom trace listeners
  • Special trace sources
  • Category sources
  • Filters
  • The application block

In addition, if you are using the Logging Application Block with a Windows Communication Foundation (WCF) application, you must configure integration with WCF. For details, see Integrating the Logging Application Block with WCF Applications.

If you want to deliver log entries at a central location for processing, you can use the Logging Application Block with Message Queuing (also known as MSMQ) to allow you to do this. By configuring multiple applications to use the same message queue, you can deliver all the log entries to one place. For details of how to install and configure the Logging Application Block in this scenario, see Using the Distributor Service.

The following procedures describe how to configure each element. If you are not going to use one element, you can go on to the next procedure. For a list of the properties for each object used in the Logging Application Block, see Logging Application Block Properties.

Configuring Formatters

The first procedure describes how to configure the formatters. The Text Formatter converts a log entry into a text string. The contents of the string are determined by replacing tokens in the Text Formatter's Template property. The BinaryLogFormatter uses the .NET Framework BinaryFormatter to serialize and deserialize the log entry in binary format. The BinaryLogFormatter is required when using the MSMQ Trace Listener with the Message Queuing distributor service.

To configure formatters

  1. Right-click the Formatters node, point to New, and then click the formatter that you want to use.
  2. (Optional) Change the Name property. The default name is the name of the formatter.
  3. If you are adding a Text Formatter and want to change the template that contains the value placeholders, click <template> and click the ellipsis button (****…). Make the required changes in the Template Editor dialog. You can use the Insert Token button to add tokens with the appropriate syntax. After you finish making the changes, click OK.
  4. If you are adding a Custom Formatter and want to edit the settings, click the ellipsis button (****…) in the Attributes property value and use the EditableKeyValue Collection Editor to specify configuration information for the Custom Formatter. This configuration information is a collection of key/value string pairs.
  5. Repeat the procedure for each formatter you want to use.

Note

The timestamp token supports a local: prefix that indicates that the timestamp should be displayed in local time. Some examples of local timestamp format codes include {timestamp(local)}, which uses the default format stringand {timestamp(local:F)}, which uses the F format string that represents the "full date/time" pattern. For more information about date/time formatting, see Standard DateTime Format Strings on MSDN.

Configuring Trace Listeners

The following procedure describes how to configure the trace listeners. Trace listeners receive log entries and write them to the appropriate destinations. There is a specific procedure for configuring a custom trace listener (see Configuring Custom Trace Listeners), and a specific procedure for configuring the two trace listeners that are required for integration with WCF (see Integrating the Logging Application Block with WCF Applications).

To configure trace listeners

  1. Right-click the Trace Listeners node, point to New, and then click the trace listener that you want to use. Each trace listener has a set of properties associated with it. For information about these properties, see "Trace Listener Properties" in Logging Application Block Properties.
  2. If you are going to use the MSMQ distributor service, you must select the Msmq TraceListener option. For information about how to use the distributor service, see Using the Distributor Service.
  3. Set the Formatter property by clicking the formatter you want to use (if any) in the drop-down list. If you are configuring the Msmq TraceListener to use it with the Message Queuing distributor service, you must select the Binary Formatter.
  4. If necessary, change the values of other properties. To do this, either type a new value or select an option in the drop-down list.
  5. Repeat the procedure for each trace listener you add.

Note

When you add a System.Diagnostics trace listener and set the Type attribute, the Type Selector displays trace listener types that derive from the System.Diagnostics.TraceListener class. This means that the Type Selector displays the trace listener types that are a part of the EnterpriseLibrary.Logging.TraceListeners assembly as well as the trace listener types that are a part of the System.Diagnostics assembly. Only select types that belong to the System.Diagnostics assembly. It is possible to use some of the Enterprise Library trace listeners, but only those that require either no parameters or one parameter, which is the same as the System.Diagnostics trace listeners. These trace listeners are the Formatted EventLog TraceListener, the Flat File TraceListener, and the WMI TraceListener.

Configuring Custom Trace Listeners

To configure a custom trace listener

  1. Right-click the Trace Listeners node, point to New, and then click Custom Trace Listener.
  2. If you need to set attributes, click the ellipsis button (****…) in the Attributes property section of the properties pane. In the EditableKeyValue Collection Editor dialog box, enter the key name and the value of the property. Add more name/value pairs as appropriate, and then click OK.
  3. (Optional) Set the Formatter property by clicking the formatter you want to use in the drop-down list. The default is None.
  4. (Optional) Change the Name property. The default name is Custom Trace Listener.
  5. (Optional) Set the TraceOutputOptions property by clicking the value you want to use in the drop-down list. For an explanation of the values, see the table in the section "TraceOutputOptions Values" in the "Trace Listener Properties" section of Logging Application Block Properties. The default is None.
  6. In the Type property section, click the ellipsis button (****…).To filter the list, in the Filter edit box type the string to use to filter the list, for example type "string" to filter for all classes containing the word "string". If the type you want is not included in the Assemblies folder, click Load from File or Load From GAC in the Type Selector to find the assembly that contains the type you want.

Configuring Special Trace Sources

The next procedure describes how to configure the special trace sources. The Logging Errors & Warnings special source receives log entries for errors and warnings that occur during the logging process. The Unprocessed Category special source receives log entries for that are assigned to categories that are not processed by a category source. The All Events special source receives all log entries.

To configure special trace sources

  1. In the Special Sources node, click the special source you want to use.
  2. (Optional) Set the SourceLevels property. For information about the SourceLevels property values, see the section "Category Source Properties" in Logging Application Block Properties.
  3. Repeat the procedure for each special source you require.

Note

If an error occurs when the application block writes to a special trace source, there is no error reported and the original log message is discarded.

Configuring Category Sources

The next procedure describes how to assign log entries to categories.

To configure category sources

  1. Right-click the Category Sources node, point to New, and then click Category.
  2. (Optional) In the properties pane, type the name of the category.
  3. Click the SourceLevels property and select the severity level of the events that will be assigned to this category. For information about the category source properties, see the section "Category Source Properties" in Logging Application Block Properties.
  4. Click the AutoFlush property and select True if you want the listener to flush its data to the target after each new entry is written to this source. Select False if you want to flush the entries in your code only when required.
  5. Repeat the procedure for each category you require.

Configuring Filters

You can filter log entries based on their categories and their priorities. You can also entirely enable or disable logging. The following procedure describes how to configure the filters.

To configure filters

  1. Right-click the Filters node, point to New, and then click the filter you want to use.
  2. The Category Filter allows or denies log entries based on their categories:
    • If you want to use a Category Filter, you can change the CategoryFilterExpression property by clicking the ellipsis button (...). This opens the Category Filter Editor dialog box.
    • Select a Filter Mode, either Allow all or Deny all.
    • Type or select the category name for the category that will be filtered. You can either select a name from the drop-down list or type a category name. Then click Add Filter. The category name appears in the lower pane. Repeat to add any other categories you require.
    • To remove a category, click a category name in the lower pane, and then click Remove Filter. Repeat to remove any other categories you no longer require.
    • Click OK to close the Category Filter Editor dialog box.
    • (Optional) Change the name of the Category Filter. For information about the CategoryFilter properties, see the section "Filter Properties" in Logging Application Block Properties.
  3. The LogEnabled Filter provides a global switch that you can use to turn logging on and off:
    • If you want to log events, set the Enabled property to True. To prevent all logging, set the Enabled property to False.
    • (Optional) Change the name of the LogEnabled Filter. For information about the LogEnabled Filter properties, see the section "Filter Properties" in Logging Application Block Properties.
  4. The Priority Filter allows or denies log entries based on their priority:
    • (Optional) Set the MaximumPriority property. This is the maximum priority value a log entry can have in order to be logged. If you do not set this property, the value is 2147483647 (this is the largest possible value of a 32-bit signed integer).
    • (Optional) Set the MimimumPriority property. This is the minimum value a log entry must have to be logged. If you do not set this property, the value is -1.
    • (Optional) Change the name of the Priority Filter. For information about the Priority Filter properties, see the section "Filter Properties" in Logging Application Block Properties.
  5. A Custom Filter is a class that you have created that derives from the LogFilter class. Its configuration information consists of a collection of name/value string pairs:
    • Set the Type property by clicking the filter type name in the Type Selector dialog box. You must select a class that derives from the LogFilter class. It must also have the type CustomLogFilterData specified as the value of the ConfigurationElementType attribute placed on the class.
    • (Optional) Change the name of the Custom Filter. For information about the Custom Filter properties, see the section "Filter Properties" in Logging Application Block Properties.
  6. Repeat the preceding steps for each filter you require.

Configuring the Application Block

The following procedure describes how to configure the Logging Application Block properties.

To configure the Logging Application Block

  1. In the Logging Application Block node, click each property you want to change. For information about the Logging Application Block properties, see Logging Application Block Properties.
  2. Set the properties if you need to. If you want to use a default category, click the drop-down arrow and select one of the category names. Log entries that are not assigned to a category belong to the default category.
  3. The LogWarningWhenNoCategoriesMatch property sends log entries that are assigned to a category that is not specified in configuration to the Logging Errors & Warnings special source. If you want this to occur, click True in the drop-down list to enable this property.
  4. The TracingEnabled property specifies whether activity tracing is enabled. To enable it, click True in the drop-down list.