The Logging Handler

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 Logging Handler provides the capability to write log messages and trace messages as the client code invokes the selected method or accesses the selected property of the target object. This handler uses the Logging Application Block, taking advantage of the wide range of log types, formatting, and tracing features that it provides.

The Logging Handler applies both before and after invoking the selected method or accessing the selected property of the target object, depending on settings in the Policy Injection Application Block configuration.

Note

The Logging Handler will initialize the Logging Application Block using the same configuration source as used to create the Logging Handler. By default, this will be the default configuration source. It is possible to specify an alternative configuration source if you instantiate the Logging Handler yourself using code. If you do this, you should create the configuration source once and use the same instance each time you create a Logging Handler to prevent performance issues and memory leaks.

Behavior of the Logging Handler

In more detail, the Logging Handler does the following:

  • It reads the values of a list of properties that define the logging behavior from the Policy Injection Application Block configuration.
  • It builds up an instance of the TraceLogEntry class, which inherits from LogEntry, and contains (in addition to the properties exposed by the LogEntry class) the following strongly-typed properties:
    • TypeName
    • MethodName
    • ReturnValue
    • CallStack
    • Exception
    • CallTime
      Ff648155.note(en-us,PandP.10).gifNotes:

      The values of parameters passed to the target member are available through the ExtendedProperties property of the LogEntry base class, which returns a populated Dictionary instance.

      You can optimize performance by configuring the properties the handler will collect information for and populate.

      Be aware that, because the properties in the preceding list are not available in the standard LogEntry class in the Logging Application Block, the default formatter templates will not display their values. You can use the {property} formatter token in the Log Formatter template to display these values—for example, {property(TypeName)}.

  • It sends the TraceLogEntry to the Logging Application Block before, after, or both before and after the method call, depending on the configuration settings.
  • If the configuration specifies logging after the method call and includes the option to log the call duration, the Logging Handler records the difference between the times when its pre-processing tasks and post-processing tasks occur, and it logs this along with any other configured values.

Configuration Settings of the Logging Handler

The following configuration settings are available for the Logging Handler:

  • Categories (String collection). This is the list of categories to which the Logging Handler will write events. Each category can be a literal value, and/or include the following tokens:
    • {method}
    • {type}
    • {namespace}
    • {assembly}
  • LogBehavior (Before | After | BeforeAndAfter). This specifies whether logging should occur before the handler passes the call to the next handler in the pipeline or to the target object (during the pre-processing stage); after the target object process completes and before the handler passes the call back to the previous handler in the pipeline (during the post-processing stage); or at both stages.
  • BeforeMessage (String). This is the message that the Logging Handler will log before the target method executes.
  • AfterMessage (String). This is the message that the Logging Handler will log after the target method executes.
  • EventId (Integer). This is the ID of the event to generate when writing to Windows Event Log.
  • IncludeCallStack (Boolean). This specifies whether the Logging Handler will include the call stack in the log message. The default setting is False.
  • IncludeCallTime (Boolean). This specifies whether the Logging Handler will time the call duration and include this in the AfterMessage for the log entry. The default setting is True.
  • IncludeParameterValues (Boolean). This specifies whether the Logging Handler will include the parameter values in the log message. The default setting is False.
  • Priority (Integer). This is the priority value the Logging Handler will include in the log message.
  • Severity (TraceEventType). This is the severity value the Logging Handler will include in the log message. It is a value from the TraceEventType enumeration, such as Critical, Error, or Warning.

The next procedure describes how to configure the Logging Handler using the Configuration Console or the Visual Studio 2005 Configuration Editor.

To configure the Logging Handler

  1. If you have not already added the Logging Application Block to the configuration of your application, do this first. You must add at least one category source to the Logging Application Block to use the Logging Handler with the Policy Injection Application Block. For details about configuring logging category sources, see Entering Configuration Information in the documentation for the Logging Application Block.
  2. Right-click the Handlers node in the Enterprise Library Configuration Console or Visual Studio Configuration Editor, point to New, and then click LogCall Handler.
  3. In the right pane of the Enterprise Library Configuration Console, or in the Visual Studio Properties window, select the Name property, and then change the default name to the name you want to use for the new handler.
  4. Select the Categories property, and then click the ellipsis button (...) to open the LogCategory Collection Editor dialog box.
  5. Click Add and, in the right pane of the dialog box, enter the name of the category source in the Logging Application Block that defines the logging behavior for the Logging Handler.
  6. If you want to log to more than one category source, repeat the previous step to specify additional category sources already configured in the Logging Application Block, and then click OK to close the LogCategoryCollection Editor dialog box.
  7. Select the AfterMessage property, and then enter any text you want to include in logging messages created after target member invocation (in the post-processing stage of the handler). You can click the ellipsis button (...) to open a larger text editing area.
  8. Select the BeforeMessage property, and then enter any text you want to include in logging messages created before target member invocation (in the pre-processing stage of the handler). You can click the ellipsis button (...) to open a larger text editing area.
  9. Select the EventId property, and then enter an integer value for the ID of the event to create when writing to Windows Event Log.
  10. Select the IncludeCallStack property, and then click True in the drop-down list if you want to include the call stack in the log message or click False if you do not want to include this information.
  11. Select the IncludeCallTime property, and then click True in the drop-down list if you want to include the time taken for the call to execute in the log message or click False if you do not want to include this information.
  12. Select the IncludeParameterValues property, and then click True in the drop-down list if you want to include the names and values of all the parameters passed to the target method or property in the log message or click False if you do not want to include this information.
  13. Select the LogBehavior property, and then click one of the following in the drop-down list:
    • Before. Click this if you want the handler to create a log message before the call to the target object (in the pre-processing stage).
    • After. Click this if you want the handler to create a log message after the call to the target object (in the post-processing stage).
    • BeforeAndAfter. Click this if you want the handler to create a log message both before and after the call to the target object.
  14. Select the Priority property, and then enter a numeric value that indicates the priority of the log message.
  15. Select the Severity property, and then select a value that indicates the severity (importance) of the log message in the drop-down list.

Attribute-based Targeting with the Logging Handler

The following code shows the use of the [LogCallHandler] attribute on a simple method. This attribute can also be applied to the class declaration, in which case it applies to all members of that class. The [LogCallHandler] has no mandatory parameters.

[LogCallHandler]
public void Deposit(decimal depositAmount)
{
  balance += depositAmount;
}
<LogCallHandler> _
Public Sub Deposit(Decimal depositAmount)
  balance += depositAmount
End Sub

Table 1 describes the properties of the LogCallHandlerAttributeclass.

Table 1: Properties of the LogCallHandler

Property

Description

Categories

String collection. The list of categories to which the Logging Handler will write events. Each category can be a literal value, and/or include the tokens {method}, {type}, {namespace}, and {assembly}.

LogBeforeCall

Boolean. Whether to write a log entry before the call passes to the target object. Note that, when this property is set to true in a LogCallHandler attribute, the LogAfterCall property is always also true.

LogAfterCall

Boolean. Whether to write a log entry after the call returns from the target object. Note that this property is true when the LogBeforeCall property is set to true in a LogCallHandler attribute.

BeforeMessage

String. The message that the Logging Handler will log before the target method executes.

AfterMessage

String. The message that the Logging Handler will log after the target method executes.

IncludeParameters

Boolean. Whether to include the parameter values in the log message.

IncludeCallStack

Boolean. Whether to include the call stack in the log message.

IncludeCallTime

Boolean. Whether to include the call duration in the AfterMessage for the log entry.

Priority

Integer. The priority value to include in the log message.

Severity

The severity value of an exception to include in the log message, using values from theTraceEventType enumeration, such as Critical, Error, and Warning.

To set these properties using an attribute, add them as parameters to the attribute declaration, as shown in the following code.

[LogCallHandler(Categories=new string[]{"My Category"}, LogBeforeCall=true, 
         BeforeMessage="This occurs before the call to the target object")]
<LogCallHandler(Categories:=New String(){"My Category"}, LogBeforeCall:=True, _
         BeforeMessage:="This occurs before the call to the target object")>
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.