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 the invocation of the selected method or accessing the selected property of the target object, depending on settings in the application configuration.

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

The logging handler does the following:

• It uses the values of a list of properties that define the logging behavior.

• 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

  Note

  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 preprocessing tasks and post-processing tasks occur, and it logs this along with any other configured values.

Creating Instances of the Logging Handler

When you use this call handler with the Unity interception mechanism, you must provide values for any mandatory parameters of its constructors, and optionally provide values for other parameters. If you configure the container with Enterprise Library's classes, then you want that configured LogWriter to be injected. If you are using an unconfigured container then you will need to get the facade's writer, which will belong to Enterprise Library's default container. If you want to inject the log writer from the container being configured, then you must provide it by using typeof(LogWriter) or new ResolvedParameter<LogWriter>() as the first element in the InjectionConstructor to specify that the constructor parameter is to be resolved The values provided are used to set the properties of the handler at run time. The constructors you can use are shown in the following code.

// Uses the default values. Gets the logWriter from the Logger.Writer facade method.
LogCallHandler()

LogCallHandler(LogWriter writer)

LogCallHandler(LogWriter writer, int eventId,
               bool logBeforeCall, bool logAfterCall, 
               string beforeMessage, string afterMessage,
               bool includeParameters, bool includeCallStack,
               bool includeCallTime, int priority)

LogCallHandler(LogWriter writer, int eventId,
               bool logBeforeCall, bool logAfterCall, 
               string beforeMessage, string afterMessage,
               bool includeParameters, bool includeCallStack,
               bool includeCallTime, int priority, int order)

'Usage
LogCallHandler()

LogCallHandler(writer As LogWriter)

LogCallHandler(writer As LogWriter, eventId As Integer, _
               logBeforeCall As Boolean, logAfterCall As Boolean, _
               beforeMessage As String, afterMessage As String, _
               includeParameters As Boolean, includeCallStack As Boolean, _
               includeCallTime As Boolean, priority As Integer)

LogCallHandler(writer As LogWriter, eventId As Integer, _
               logBeforeCall As Boolean, logAfterCall As Boolean, _
               beforeMessage As String, afterMessage As String, _
               includeParameters As Boolean, includeCallStack As Boolean, _
               includeCallTime As Boolean, priority As Integer, order As Integer)

The following table describes the values for the parameters shown above.

The Logging Handler also exposes these values as the LogWriter, EventId, LogBeforeCall, LogAfterCall, BeforeMessage, AfterMessage, IncludeParameters, IncludeCallStack, IncludeCallTime, Priority, and Order properties. It also exposes the Categories property as a List of String values, and the Severity property as a value from the TraceEventType enumeration (such as Critical, Error, or Warning).

The following code extract shows how you can add a Logging Handler to a policy using the Unity type resolution and interception mechanisms. This example specifies that LogWriter is to be resolved by the container and it provides values for the LogCallHandler property values.

myContainer.Configure<Interception>()
           .AddPolicy("MyPolicy")
               .AddMatchingRule<TypeMatchingRule>(
                    new InjectionConstructor("My.Order.Object", true))
               .AddCallHandler<LogCallHandler>( 
                  new ContainerControlledLifetimeManager(),
                  new InjectionConstructor(
                      typeof(LogWriter), 
                      9000, true, true, 
                      "started", "finished", true, false, true, 1, 5
                      ));

'Usage
myContainer.Configure(Of Interception)() _
    .AddPolicy("MyPolicy") _
        .AddMatchingRule(Of TypeMatchingRule) _
            (New InjectionConstructor("My.Order.Object", True)) _
        .AddCallHandler(Of LogCallHandler) _
            (New ContainerControlledLifetimeManager(), _
                New InjectionConstructor(GetType(LogWriter), _
                9000, True, True, "started", "finished", _
                True, False, True, 1, 5))

Using the Logging Handler Attribute

Instead of configuring a call handler as part of a call hander pipeline, you force it to be applied by adding the appropriate attribute to your classes. 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.

[LogCallHandler]
public void Deposit(decimal depositAmount)
{
  balance += depositAmount;
}

'Usage
<LogCallHandler> _
Public Sub Deposit(depositAmount As Decimal)
  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")>

For more information about using call handler attributes and attribute driven policies, see Attribute-Driven Policies.