How to debug a BizTalk 2004 pipeline: tips and tricks

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.

Comments (9)

  1. Ben Cops says:

    I had all sorts of trouble making pipeline.exe see my schemas – nothing i did in the command line would "see" or resolve them. An awful time was had by all…

    Have you had any success with disassemblers in pipelines tested in pipeline.exe?

  2. Gilles says:

    Ben: As I mentionned, sometimes, disassembler/assemblers do not work with pipeline.exe. However, you can use FDAsm/FFAsm to debug the disassembling part only w. the flat file disassembler/assembler.

    When you know this stage is working, you can use pipeline.exe to debug the other parts of the pipeline, by removing temporary the disassembling stage.

  3. 七里香 says:

    Why No comments posted yet?

  4. Mattea Cirrincione says:

    BizTalk Opportunity


    Are you currently available for a 3 month contract assignment located in

    Libertyville, IL? Our client needs a Sr. BizTalk Developer for Software and

    Database Development using BizTalk 2004. You will be the primary BizTalk Development Specialist working with 2 existing development teams on a variety of projects creating transactions specific to our Client’s web based applications.

    The position requires:

    * Recent (within 18 months hands on experience developing in BizTalk).

    * MUST have 2004 experience.

    * Web Service development experience in the BizTalk context.

    * Able to document programming and software/hardware setup for Biztalk.

    * Able to support the Consumer Internet project for payment estimator.

    * Ability to understand complex business rules.

    * Strong/Extensive Microsoft Tools and Technology background.

    I noticed your background on the web and thought we should talk. If you are available and interested please let me know as soon as possible. If not feel free to pass my contact information to any BizTalk expert you know.


    Mattea Cirrincione

    Technical Recruiter

    Sierra ITS

    847-692-0616 dir

Skip to main content