BizTalk send and receive adapters can be debugged by attaching Visual Studio debugger to the BTSNTSvc.exe process, except for when debugging isolated receive adapters, in which case the debugger needs to be attached to the process that hosts the adapter.

A common error one could encounter when debugging custom adapter code is that breakpoints are not getting hit. Most likely this is because debug symbols for adapter dll are not loaded. In order to check if this is the case, go to Debug -> Windows -> Modules, find your assembly and check the Symbol Status column. It should say Symbols loaded. If this is not the case, additional information can be obtained by right clicking the assembly in the list and selecting Symbol Load information option from the context menu. Listed there are paths were Debugger tried to load symbols from. Most likely, you will get Cannot find or open the PDB file or PDB does not match image error message. This usually happens if PDB file doesn’t exist at the specified location, or if the version of the loaded dll assembly doesn’t match the PDB object file. This could be down to various reasons

  • You could be debugging code that isn’t installed to the the GAC. Try installing your adapter assemblies to the GAC and make sure to use f flag in order to force any existing assembly version overwrite.
  • Host instances for the adapter haven’t been restarted and hence the new assemblies just aren’t loaded yet. This is the step that gets overlooked very often when it comes to any kind of BizTalk development. Try restarting host instances.
  • Another cause might be that the project was built with Release configuration, which by default doesn’t generate PDB files, and although the right assembly is loaded, PDB file just don’t exist for that assembly file. To fix this issue, right click on the solution and then on Batch Build, choose your project and click Clean. Then, build your project and the generated PDB file should be loaded correctly when you attach debugger to the process.

As we’ve seen, BizTalk adapter assemblies must be installed into the system global assembly cache (GAC) and consequently they also have to be updated in GAC each time your code changes and you wish to test or debug your adapter. Also, host instance your adapter runs in must be restarted in order to load new version of adapter assemblies.

Manually performing these steps soon becomes a tedious and error-prone process - failing to perform any of the mentioned steps can lead to nerve-wrecking debugging experience. That’s why it is a good idea to define a simple Post-Build Event that will automate these steps for you.

net stop "BTSSvc$BizTalkServerApplication"
gacutil -if "$(TargetPath)"
net start "BTSSvc$BizTalkServerApplication"

Here, we assumed that the adapter runs in the default BizTalkServerApplication host instance. Host instance service is stopped using net stop command, project’s target assembly is installed to GAC, forcing it to overwrite any existing version with gacutil -if, and finally, host instance is started with net start.