My task (well one of them) for the week was to update one of our Custom BizTalk adapters. Be sure to read my post on how to Install a custom BizTalk Adapter for some background information.

One of the changes I needed to make (which I had been putting off), was changing the namespace. Namespaces are case sensitive in the world of BizTalk. So if you change the namespace, you have to update the registry entry for the adapter with the new case sensitive namespace. Also, it seems like you need to uninstall the adapter from BizTalk in order to use the new assembly, since the TypeName changed.

In order to do this, I used the BizTalk admin tool to delete the adapter (BizTalk Group\Platform Settings\Adapters), update the registry, then re-add the adapter. If you are making calls to resource files where you are specifying the type name, be sure to update the string you are passing in as those calls will now fail. Even better, you should have a single string constant that defines the type name so you only have to make this change once.

Once the namespace change was finished, further changes to the assembly, only required me to copy over the existing assembly and restart the host process. Exceptions in adapters, at least our custom adapter, would cause the host process to keep restarting, so I ended up disabling the windows service for the host process after restarting/starting it, just to keep down on the repetitive errors.

Robust and proper error handling is a must in custom BizTalk artifacts. I find that writing errors to the event log works the best, and to include a domain specific error message, error code, and Exception.ToString(). The error codes are nice because you can go back in search for them in the code. They also are easily referenced in tech support and trouble shooting documentation.

In my specific case, a custom adapter which used the BizTalk PollTask mechanism, uncaught exceptions are written to the event log with the full stack trace. This means, that you don't need to catch general exceptions (and static code analysis says we shouldn't). Starting from exceptions thrown by PollTask, I added specific catch blocks to log specific information useful for trouble shooting, and re-threw the exception using "throw;" which re-throws the original exception. This causes the adapter to error out, and to be honest I do not know if this is the best way to handle things. It results in the host process restarting as mentioned above. When the out of the box adapters have errors, like the File adapter not having permissions to the specified folder, the adapter is eventually shut down.