I wrote this “How To” article for my company back in the spring, but thought it might be helpful to developers new to BizTalk. For me, troubleshooting schemas is always a pain point; this mostly due to all of the whacky file formats that are out there.
HOW-TO: Troubleshooting Schemas
One of the biggest frustrations about working with BizTalk can be the fact that schemas cannot really be “debugged” in the traditional sense. In the .NET world, we can attach a debugger to a process and break into our source code. While schemas are compiled into CLR classes, the source code is not a VB.NET or C# class: they are XSD files. You can’t put a break point into these files.
What you can do is use the developer tools in Visual Studio.NET to test your schemas, provided that you have a sample message which your solution must process.
Tools in Visual Studio.NET
Let’s start with schemas because these are likely to be the first thing which you will want to test. If you have a sample message which you have used to generate the schema, the schema is very likely to be correct. However, you may have more than one sample and the schema must accurately describe all three messages. Right click the .xsd file in the Solution Explorer and select Properties. In the property browser that appears you will find a property named Input Instance Filename: click the ellipsis button to browse to your sample file. Note that if your sample is a Flat File, you will need to set the Default Property Schema Name property to Native; otherwise the property should remain set to XML. Having set these property values, you can click OK. Then, right click the schema again and click Validate Instance. The result of this validation will be displayed in the Output window of Visual Studio. You will want to perform this test for each of your samples in order to ensure that your schema is accurate.
These tools are simple and easy to use at design-time. But you must have the correct version of Visual Studio.NET installed on the BizTalk Server host in order to use them to test messages. This is not always possible.
Here is an example: I once found myself having to troubleshoot a message received from an external business partner that had failed during the receive process. On my development machine (running BizTalk Server 2004 – Developer Edition) everything worked as expected. In order to troubleshoot the message and replicate the error, I needed to troubleshoot the schema on the machine which was experiencing the problem. Did I need to install VS.NET unto the production server in order to replay the exception?
What you can do instead is take a look at the Pipeline Utilities which come with the BizTalk Server SDK. These tools are located at:
These tools permit you to emulate the pipeline process without having to configure the BizTalk Server environment, such as send/receive ports. The most important tools used to troubleshoot schemas include:
FFasm.exe – Runs the flat file assembler component, directly invoking it by emulating a send pipeline to enable you to see how it serializes or assembles a user’s XML document(s) into a flat file document.
FFDasm.exe – Runs the flat file disassembler component, directly invoking it by emulating a receive pipeline to enable you to see how it parses or disassembles a user’s flat file document into one or more XML documents.
XMLAsm.exe – Runs the XML assembler component, directly invoking it by emulating a send pipeline to enable you to see how it serializes, assembles, or envelopes a user’s XML document(s) into an output XML document.
XMLDasm.exe – Runs the XML disassembler component, directly invoking it by emulating a receive pipeline to enable you to see how it parses, disassembles, or un-envelopes a user’s XML document into one or more XML documents.
As you have probably guessed, these command-line tools use the same components used by Visual Studio.NET, so you get the same troubleshooting support with or without Visual Studio.NET.
The command line syntax for these tools can be found in the BizTalk Server Help Documentation, but let’s see an example. In order to test a Flat File Schema for an incoming message, you will need:
- FFDasm.exe tool
- The message that failed
- The source code for the schema(s) (think XSD)
I asked a network engineer to create a share for me on the production server and copied these files to the share. Then I asked him to remotely connect to the server, open a command window from the within the share, and run the following command
FFDasm.exe failedMessage.txt –bs EB.CarrierTransactions.Aetna_Medical.xsd
So what happened? The response error on the command line was explicit enough to direct me to Service Pack 1, which had been installed on my development machine, but not yet on the production server. After some research, I was able to convince the client that the service pack was needed. One week later, we installed without a hitch, and the message was processed without error. Problem Solved.