How to debug a BizTalk 2004 pipeline: tips and tricks

  • Article

BizTalk server 2004 allows you to send and receive pretty much any kind of message. This is achieved by the combination of adapters and pipelines .

In a nutshell, pipelines allow you to decode (or encode), disassemble (or assemble), Validate and Resolve parties. BizTalk comes with numerous out of the box components for all those actions and you can use the pipeline editor in Visual Studio .NET to arrange components (almost) as you see fit. If you need a component that is not available out of the box (for instance, a special kind of decoder), you can always use the SDK to write your own.

To run in production, pipelines need to be compiled and deployed to your server(s). However, the deployment process is not very developer friendly. You have to ensure that no active instance is using the pipeline and/or its related objects, you have to undeploy before you can deploy the new version ...

When developing, the time between two tests should be as minimal as possible. I describe a few tips and tricks that may save you time.

1 - Debugging pipelines the hard way

You can always build the solution, fix any other (possibly non related) compile errors, undeploy the previous version of the adequate assemblies and deploy the new version. Now, you can send a message to activate your pipeline and observe the results using HAT and/or the event viewer. This is not too friendly but this offers the advantage of running the test exactly as it will be later in production, including the credentials of the user which runs the hosts.

If you have a custom pipeline component, you can source level debug using Visual Studio .NET by following those steps:

  • Arrange for the output of the solution (i.e. your custom DLL) to be saved inside <BizTalk root install>\Pipeline Components. This can be done by changing the output directory in Visual Studio
  • Rebuild the solution and do a deploy in Visual Studio
  • Stop and Start the host which runs the pipeline. Until you do this, the old version will still run. This is because the .NET framework cannot unload an assembly. It has to unload the whole application domain
  • Attach a .NET debugger to BTSNTSVC.EXE
  • Put your breakpoints
  • Send a message

Your breakpoints should be hit. If your code throws an exception, BizTalk will catch it, log it to the event log and suspend the message (not resumable). So I suggest you break on first chance exceptions if you experience such an error.

As far as sending the message, I personally like to use a FILE adapter. I then drop a copy of a file in the directory to initiate debugging. After doing this a few times, you might find this to be really too long and complex. Well, there is another better way to do this.

2 - A faster way: use pipeline.exe, Luke

What we really want here is to be able to start all the pipeline processing without actually deploying to BizTalk. It turns out that there is a tool (in fact there are many tools) that help doing that. One of them, the most powerful is called pipeline.exe. It can be found in <BizTalk root install>\SDK\Utilities\Pipeline Tools. The documentation is here .

Now, we can use this tool to greatly simplify our custom pipeline component debugging. Here is how to do this:

  • Arrange for the output of the solution (i.e. your custom DLL) to be saved inside <BizTalk root install>\Pipeline Components. This can be done by changing the output directory in Visual Studio
  • In the properties of your Visual Studio project, switch to the Debug options and switch the Debug mode to be "Program"
  • In "Start Application", put the full path to pipeline.exe
  • In "Command Line Arguments, specify the options you need. To get you started, you want to put the full path to the pipeline file (.btp), followed by -d and the full path to a flat file to test and -c, to output the result to the console. This ends up being something like C:\mybtsproject\Pipeline.btp -d C:\mybtsproject\sampleflatfile.txt -c
  • Put your breakpoints
  • Press F5 to start debugging

Now, every time you start (F5), you can save the deployment time and the activation time (copying the message into a directory, waiting for the adapter to pick it up).

There is one caveat: pipeline.exe does not access the BizTalk databases, so some pipelines (ones with the out of the box assembler/disassembler for instance) will not execute properly. However, you can break up your your pipeline and test your custom components separately using pipeline.exe.