Customizing the WSDL generated by the‘BizTalk Webservice Publishing Wizard’

Exposing BizTalk interfaces as webservices is very easy using the ‘BizTalk Webservice Publishing Tool’. In almost all cases this tool generates a correct functioning web service which does not need any code modification.

However, there are situations where tweaking the code of the generated web service is necessary. Recently I needed two different BizTalk interfaces to expose the exact same WSDL. Because the two interfaces had different names for namespaces and artifacts, the generated webservices and WSDL were not the same.

You can solve this by using the SoapExtensionReflector. The BizTalk Webservice Publishing Wizard generates a class called ‘WsdlExtensions.cs’ for every webservice that is generated. By including this file in the generated VS.Net webservice project and adding the type in the 'soapExtensionReflectorTypes' section of the web.config (see header comments of
WsdlExtensions.cs), you’re able to control the generated WSDL for the webservice.

By default this file is generated with code for XML schema replacement in the WSDL, but you can use this to change other parts. For example, to override the SOAP service name, you can use:

public override void ReflectMethod()

{

    ProtocolReflector reflector = this.ReflectionContext;

    reflector.Service.Name = "MyNewServiceName";

}

After recompiling the web service the service name in the WSDL is changed to the new value.

"multiple schemas match the message type"may be caused by web services

I was stuck recently with what seemed like a pair of contradictory errors.

I had an application deployed which was exposed as a web service. To test the application we built a test harness which picked up a flat file and called the web service for us and then dumped the result on the file system to see the result.

This testing system worked fine until I needed to use that same deployed schema to do some additional messaging. I wanted to route a message via a receive port and have a send port subscribe to it, then map the message to a new format and deliver it to a destination. Pretty simple, right?

Well, no. When I have my project deployed I got the following error when routing:

There was a failure executing the receive pipeline: "Microsoft.BizTalk.DefaultPipelines.XMLReceive" Source: "XML disassembler" Receive Location: " D:\dat\FileReceive\RoundTrip\*.xml Reason: Cannot locate document specification as multiple schemas match the message type "http://BO.Get.EV2#Method".

That error left me scratching my head. It means I probably have the schema deployed twice, right? I didn't, so I thought. When I undeployed the application the messaging engine could no longer match my message type:

There was a failure executing the receive pipeline: "Microsoft.BizTalk.DefaultPipelines.XMLReceive" Source: "XML disassembler" Receive Location: "D:\dat\FileReceive\RoundTrip\*.xml"
Reason: Finding document specification by message type "http://BO.Get.EV2#Method" failed. Verify that the schema is deployed properly.

When I deployed the project with the schemas, everything suddenly worked fine. That means that, somewhere, the schema was again deployed.

So I looked thru the BizTalk Server Assemblies viewer and discovered that the web reference which existed in my test harness was the culprit. The messaging engine recognized the web reference as a second deployment of my schema. This was technically accurate but rather frustrating to find. I've seen so many of these errors posted on the newsgroups that I thought I'd mention this as a possible cause.

If you are using test harnesses coupled with web services be aware that your schema is actually deployed twice.

BizTalk exception handling with web services

Recently I needed to include exception handling in a web service call to an external party. I learned a couple of things and thought I’d highlight them here.

Exception handling doesn’t always behave the way you expect when you are trying to catch exceptions when calling a web service. While using one is very useful some things must be considered or you will not get the result you wanted.

Here is one way to do it as well as a few things to keep in mind when you want to set one up:

• Include the external web service call (both send and receive shapes) in either a non-transactional scope shape or a long running transaction.
• Decide if you need to catch any specific exceptions, if you don’t, using the General Exception will suffice. If you need to catch specific errors, you can use multiple catch exception blocks.
• It may sound obvious to say this, but make sure your orchestration doesn’t have a timeout that is the same length (or shorter) than the timeout of your scope transaction.
• Most important: in your send port which holds the reference to the web service, make sure you are not using any retries (unless, of course, you explicitly need to). If the web service fails with an error such as “There is an error in XML document (5, 10)” and you have retries enabled you will only see warnings in your event viewer (which means the exception block won’t be activated until the SOAP timeout).