Using Log4Net

To assist in debugging your BizTalk application during development and even into production, it is often critical to have a mechanism for saving messages to one or more easily-accessible locations. The open-source logging framework Log4Net is one good solution, and the Deployment Framework for BizTalk offers built-in support for it.

To enable Log4Net support, edit your Deployment Framework for BizTalk project file (.btdfproj) as follows:

1. Set the Includelog4net property to true

The property may be included in any PropertyGroup, but is commonly placed in the first PropertyGroup in the project file.

...

...

</PropertyGroup>

2. Add and configure a log4net configuration file

The Log4Net configuration is loaded from an XML configuration file that is deployed with your BizTalk application. In the parent folder of your deployment project, which is often the same folder as the solution file, add an XML file named $(ProjectName).log4net. $(ProjectName) is the value of the ProjectName MSBuild property in your .btdfproj file. Remember to add this file to your source control system.

Here's an example of a .log4net config file to write to a text file:

<?xml version="1.0" encoding="utf-8" ?>

<appender name="File"

type="log4net.Appender.FileAppender, log4net, Version=1.2.9.0, Culture=Neutral, PublicKeyToken=b32731d11ce58905">

</appender>

<root>

<appender-ref ref="File" />

</root>

<appender-ref ref="File"/>

</logger>

</log4net>

3. Copy Log4Net.dll and Log4Net.Ext.Serializable.dll from the Deployment Framework for BizTalk install folder to a reference location in your BizTalk solution

Before you can use Log4Net in your application, locate the two DLL's in <BTDFInstallFolder>\Framework\DeployTools and copy them to a folder within your BizTalk solution folder hierarchy. It's a good idea to check the DLL's into your source control system and reference them in that location vs. the Deployment Framework's install folder.

4. Add references to Log4Net.dll and Log4Net.Ext.Serializable.dll to your project

In every BizTalk or .NET project where you want to write log entries, add a reference to the copies of Log4Net.dll and Log4Net.Ext.Serializable.dll stored within your solution folder structure.

5. Write log entries from an orchestration

The Deployment Framework for BizTalk includes two special serializable helper classes for Log4Net that can be used with orchestration variables. Create two variables in your orchestration: one of type log4net.Ext.Serializable.SLog and another of type log4net.helpers.PropertiesCollectionEx.

You can then initialize and write to the log within an Expression shape using code like the following example:

// Create the logger using the ProjectName property value from the .btdfproj

logger = log4net.Ext.Serializable.SLogManager.GetLogger("MyProjectName", log4net.helpers.CallersTypeName.Name);

// Configure the logger by referencing the registry key written during the deployment process

logger.RegistryConfigurator();

// Set some properties in the PropertiesCollectionEx object

logProps.Set("InstanceId", MyOrchestration(Microsoft.XLANGs.BaseTypes.InstanceId));

// Write a debug level entry to Log4Net including the properties object

logger.Debug(logProps, "Received top level request...");

// We can even pass the logger to C# code via a param typed as log4net.ILog

BizTalkSample.Components.MyClass.Execute(sampleRequest, logger);

6. Write log entries from a C# helper class

As the sample code above demonstrates, you can pass the SLog object to a C# method as type log4net.ILog. You're free to use the entire ILog interface to write log entries. You can also create and initialize the logger directly from C# code if you don't want or need to do it in an orchestration. That may include helper classes, pipeline components, map helper classes, etc.

When Log4Net deployment is enabled, the deployment process will automatically add log4net.dll and log4net.Ext.Serializable.dll to the GAC.

NOTE: On Windows x64, you might find issues with the registry configurator. The deployment script typically runs as a 32-bit process, which means that it sees and works with the 32-bit "view" of the registry (SysWow6432). If your host(s) are 64-bit, they will see the 64-bit view of the registry. That might mean that they will not see the log4net registry entry because it only exists in the 32-bit registry.

On a 64-bit system the registry key will appear at HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\<YourProjectName>. For 64-bit hosts, the key needs to be duplicated at HKEY_LOCAL_MACHINE\SOFTWARE\<YourProjectName>. You can do this in a CustomPostDeploy target in your deployment project file.

Created with the Personal Edition of HelpNDoc: Free EPub producer