Debugging an external assembly that’s called from within a BizTalk process

External assemblies are being called from within BizTalk orchestrations in almost every BizTalk application.
Knowing how to debug them is important. This guideline will show you how you can debug those external assemblies on
your workstation or a remote box using a very simple sample application.

Debugging external assemblies on a local box with one BizTalk host instance sample application

In the sample application an orchestration has been created that calls a method in an external C#.Net assembly.
Both projects are built and deployed. The BizTalk project is deployed on the workstation by using the deploy solution function.
The deploy solution can be used after setting the project deployment configuration properties. The external C#.Net assembly is
installed into the GAC.


When your project is deployed and configured, be sure to restart the host instances that host the project you want to debug.
In Visual Studio set breakpoints in your code. To debug you must attach to the process that is running the .Net code.
This process will be the BizTalk host that runs the orchestration calling the .Net code.

In Visual Studio, click the Debug menu and choose Attach to Process.

The BTSNTSvc.exe process, which represents one host instance, is probably running under a different account than your personal account. Therefor you must activate the Show processes from all users checkbox.

If you only have one host instance on the machine you are debugging on, choosing the right process is simple. Later on we will show you what to do when multiple host instances are present. Click attach after selecting the correct process. An error can occur specifying that Transact SQL debugging is not possible. Ignore this.

Now activate your orchestration so that it will call the .Net code. Your breakpoint should be hit and you can debug like any other .Net code.

Remote debugging, multiple host instances

It is not a common thing to do but if it is really necessary you can also debug code that is running on a remote box.

PDB file

A difference between debugging locally and remote is the availability of the PDB file that contains your debug symbols.
These are necessary for your breakpoints to be hit. To make the PDB file available, you need to copy it in the GAC, together with your assembly.

Copy your PDB file out of your external assembly project bin folder and copy it to the machine.
Open a command window and type the following command:

copy <your_pdb_location> c:\windows\assembly\gac_msil\<your_dll>\<version>__<public_key>

When the BizTalk host restarts it will detect the PDB file and load the debug symbols. Later in this article you will be able to see if the symbols are indeed being loaded.

Remote debugging tool

Now the Visual Studio running on your workstation needs to be able to communicate with the remote box to receive the debugging information. To do this, the VS remote debugging monitor needs to be running on the remote box. To activate the debug monitor you need to copy the contents of the C:\Program Files\Microsoft Visual Studio 8\Common7\IDE\Remote Debugger\x86 folder to the remote box and run the msvsmon.exe process. If Visual Studio is installed on the remote box, msvsmon might already be available. This process allows Visual Studio to access the box and exchange debugging information. This is a security leak so only start this process when it is necessary.

When the debug monitor is running you can start to debug. Open the debug menu and choose attach to process.
In the qualifier field you enter the username under which the debug monitor is running followed by the computername, divided by an @.

Determining which process to attach to

Now you need to choose the right BTSNTSvc.exe process by determining the process ID.
You can use the tasklist command to query the processes. Execute the following command in a command prompt on the remote box.

tasklist /SVC /FI “IMAGENAME eq btsnt*”

A list of running BizTalk processes with their hostname and processID is shown.

Start debugging

Start the orchestration on the specified server and you will be able to debug.
On a multiserver environment you will have to stop the host instances on the servers where you are not attached to.
It might be possible that your test instance will be run on the other server.


If your breakpoint is not hit you can check if the debug symbols are loaded.
In visual studio, press CTRL+ALT+U. The modules window opens for the process you attached to.
Check if your external assembly is loaded and if the symbols are loaded.

If the symbols are not loaded you can try to also place the PDB file into the folder where you installed the external assembly. Restart the host instance and attach again.