The Logging Handler

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.

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
• 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.
• Order (Integer). This value specifies the position of the handler within the policy handler chain. The default value is zero, which means that there is no explicit order specified for the handler in relation to other handlers in the same handler chain. To specify an explicit order, set the Order property for each handler starting from 1. If you specify the same value for the Order property of two handlers in the same policy, the application block will add them to the policy handler chain in the order defined in the configuration.

The next procedure describes how to configure the Logging Handler using the Configuration Console or the Visual Studio 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 Log Call 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 LogCategory Collection 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.
16. (Optional) Enter a numeric value for the Order property if you want to specify the position of the handler within the policy handler chain. Set the Order property for each handler starting from 1.

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;
}

'Usage
<LogCallHandler> _
Public Sub Deposit(Decimal depositAmount)
  balance += depositAmount
End Sub

The following table describes the properties of the LogCallHandlerAttribute class.

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")]

'Usage
<LogCallHandler(Categories:=New String(){"My Category"}, LogBeforeCall:=True, _
         BeforeMessage:="This occurs before the call to the target object")>