The BizTalk CAT Instrumentation Framework provides a reusable framework intended to help BizTalk developers enrich their solutions with high-performance instrumentation based on the Event Tracing for Windows (ETW) infrastructure. As a developer you can instrument your BizTalk artefact, WCF/WF component, or custom component (.NET) for the purpose of logging, tracing or testing to observe behavior. ETW enables you to log kernel or application events to a log file. An application can be monitored in total, meaning that a BizTalk solution containing custom pipeline components, mappings, and an orchestration can be logged from end to end. This can also be done using log4net or System.Diagnostics namespace.

The framework was built as a result of research within Microsoft which found both log4net and System.Diagnostics did not deliver enough agility or acceptable performance. ETW infrastructure within the Microsoft OS provided a high-speed tracing facility and combined with a TracePovider in from the Microsoft.BizTalk.Diagnostics namespace in Microsoft.BizTalk.Tracing.dll are basically the main ingredients of the framework. The most important part within the framework is the ComponentTraceProvider class. This class is a wrapper around the TraceProvider providing various tracing methods for common logging requirements such as information, warning, and exceptions. In addition to these methods the team also enriched the framework with support for tracing method calls, measuring durations using high-resolution timers and ability to correlate events using Guid-based tokens.


The BizTalk CAT Instrumentation Framework can be used to instrument the following BizTalk artifacts:

  • Custom Pipeline Components
  • BizTalk Mapping
  • Orchestrations
  • Business Rules
  • BAM Activity Tracking Components

The following scenario will demonstrate how to instrument an orchestration. In this article the Compensation sample from the SDK will be used. The sample is a part of sample to be found in the SDK folder of the BizTalk installation (i.e. <install directory>:\Program Files (x86)\Microsoft BizTalk Server 2013 R2\SDK). This sample will be
demonstrate how you can use the compensation shape in an orchestration. It will be combined with the ETW.


To leverage ETW for BizTalk you will to download the BizTalk CAT Instrumentation Framework v1.4 and build it locally on your machine with Visual Studio 2013. You will need to open the solution with Visual Studio 2013 to migrate to newer version of the .NET framework. To build the project the following code in class IcomponentTraceProvider needs to be commented out:

void TraceInfo(Func<string> expensiveDataProvider);

Next to the Instrumentation Framework you can download the BizTalk CAT Instrumentation Framework Controller, which is an easy-to-use GUI for the BizTalk CAT Instrumentation Framework. This will let you start and stop a traces and adjust filter options. It can easily enable real-time tracing to the Microsoft SysInternals DebugView (or other debuggers), or to a log file or to do both at the same time.

Instrumenting an orchestration with the BizTalk CAT Instrumentation Framework

An orchestration can be instrumented using TraceManager.WorkflowComponent, which is designed for the purpose this BizTalk artefact. The TraceManager can be useful to test:

  • Tracing calls in the orchestration flow at start and end using TraceIn and TraceOut;
  • Measuring the duration of the above methods using TraceStartScope and TraceEndScope, which will be demonstrated in the orchestration
  • Tracing the internal state of the in this case custom archiving pipeline component, which could in turn assist with troubleshooting using TraceInfo;
  • Writing detailed information about a runtime exception using TraceError in case an error occurs in the flow.

Figure 1. Scenario using ETW with an orchestration.

The BizTalk CAT Instrumentation Framework in action

To capture and review the behavior of the orchestration a specific message will be offered to BizTalk to trigger the flow. Before the message is sent the BizTalk CAT Instrumentation Framework Controller will be launched. Selecting the Orchestration/Workflow component trace filter setting:

Picture 2. BizTalk CAT Instrumentation Controller.
DebugView will be launched. The message will be place in a folder. The debug trace will look like below in the DebugView:

Picture 3. DebugView capturing the traces.

When the text editor will be opened that the same trace information displayed in debugview can be found.

Picture 4. Captured trace information in text editor notepad++.

The calltoken is used in each TraceInfo statement, TraceStartScope and TraceEndScope to correlate the tracing statements.

Wrap up

This article demonstrated how to instrument an orchestration with the BizTalk CAT Instrumentation Framework that leverages Event Tracing for Windows (ETW), which is able to trace in a very performant way to a log file. ETW is suitable to be used with mappings, pipelines, custom code, BRE and BAM. Examples on how to instrument them is similar to a custom pipeline component. Various samples can be found online demonstrating that like the excellent blog post Best Practices for Instrumenting High Performance BizTalk Solutions written by the team that build the BizTalk CAT Instrumentation Framework. The BizTalk CAT Instrumentation Framework Controller can be seen as a add-on for the framework to stop/start traces and specify options for enabling debugview and a texteditor.

See Also

Another important place to find an extensive amount of BizTalk related articles is the TechNet Wiki itself. The best entry point is BizTalk Server Resources on the TechNet Wiki.