BizTalk: Two versions of a schema side by side and using them in orchestrations

Schema versioning in BizTalk is always a difficult thing to do. When small changes are done on a schema (for a new solution), but this schema is already in use by a solution which is currently in production, you have to be very careful.

BizTalk defines the schema type of a message by the combination: targetnamespace#rootnode to make a MessageType unique (for example: This will define the type of the message and is also used in subscriptions.

If you deploy two schemas with the same MessageType in different assemblies and you try to receive an instance with this MessageType, BizTalk will give you a routing failure telling you it is not able to determine the exact MessageType (the MessageType is found multiple times in the database).

Suppose you have schema X in DLL Y version and you fix a bug (change a nodes’ default value for example) for a new version of a solution, and increase DLL Ys version to If you deploy this new version of DLL Y side by side with an old version, BizTalk is smart enough to see that it is a newer version and will use this newer version of schema X for received messages with this MessageType. No routing failure! This works excellent in a message-only scenario.

So far, so good. If you use the MessageType in a receive shape in an orchestration, this orchestration has a subscription on this MessageType. That is what you expect and see in the ‘View subscriptions’ panel of the Administration Console:

As you can see, there is no assembly version shown here! But since the orchestration is developed with a certain version of a schema, the actual orchestration code does expect a certain version of the schema for the received instance. Meaning that the subscription will work, but the orchestration can’t use the message, because it was typed as the version and the orchestrations expects the version. This will generate an error in the Administration Console as follows:

Uncaught exception (see the ‘inner exception’ below) has suspended an instance of service ‘VersioningTestBTProjOrchv1000.BizTalk_Orchestrationv0100(e0f5b7e2-7e31-550e-1022-af218b9002bc)’.
The service instance will remain suspended until administratively resumed or terminated.
If resumed the instance will continue from its last persisted state and may re-throw the same unexpected exception.
InstanceId: 8b5f3dd1-42b6-4bb0-b7a4-ecd87ced4813
Shape name: Receive_1
ShapeId: 4747131a-9c71-46e6-a99a-319053adcfe7
Exception thrown from: segment 1, progress 3
Inner exception: Received unexpected message type ‘VersioningTestProject.Schemas.SchemaIncoming_v0100, VersioningTestProject, Version=, Culture=neutral, PublicKeyToken=b5c9ca1ed57903d0’ does not match expected type ‘VersioningTestProject.Schemas.SchemaIncoming_v0100, VersioningTestProject, Version=, Culture=neutral, PublicKeyToken=b5c9ca1ed57903d0’.
Exception type: UnexpectedMessageTypeException
Source: Microsoft.XLANGs.Engine

BizTalk does not automatically know for which orchestration to use the old version and for which the new version. You could say that BizTalk should be smart enough to see that an orchestration obviously expects the older version and cast the message to the correct version before feeding it to the orchestration. But this might lead to unforeseen behaviour and probably is not done this way to avoid errors.

There is an easy fix for this problem. You probably have a different receive location for the newer version of the schema, since the old version is running side by side. You can tell BizTalk to cast a received message to a certain version of the schema. This way it will not automatically cast the message to the latest version, but it will cast it to your specified version. This can be done on the XMLReceive pipeline as follows:

1 – Open the XMLReceive pipeline properties:

2 – Enter the fully qualified name of the type you are going to receive as the DocumentSpecNames property.

The name should look like: ‘FullSchemaTypeName, FullAssemblyName’ (for example: VersioningTestProject.Schemas.SchemaIncoming_v0100, VersioningTestProject, Version=, Culture=neutral, PublicKeyToken=b5c9ca1ed57903d0). This information can be found by double clicking the deployed schema in the BizTalk Administration Console.

Voila, now BizTalk will cast your message to the specified version and your old orchestration will run just fine

Of course this only works if you have separate receive locations for all versions and you can use the XMLReceive pipeline (or any other pipeline containing the XML dissambler component), but it might just help you out. (Only tested in BizTalk Server 2006 R2)

Exposing BizTalk Schemas as a SOAP-RPC/Encoded webservice

Yesterday I had to connect a Delphi back-end system to the BizTalk 2006 R2 environment of my customer. Since this Delphi system could only call webservices exposed as SOAP-RPC/Encoded, I had to expose the needed schemas as such.

While searching on this subject I found a good post of Tomas Restrepo on consuming SOAP-RPC/Encoded webservices:

This explains how you have to work with multipart messagetypes to call a SOAP-RPC/Encoded webservice. At first I figured I would have to do something alike to expose my schemas as a SOAP-RPC/Encoded webservice. However, this is actually very easy.

With the .Net framework you can easily expose a webservice as SOAP-RPC/Encoded by setting the correct attribute on the webmethod. To achieve this you should do the following to the generated webservice code after exposing your schemas as a webservice using the default BizTalk Web Services Publishing Wizard:

  1. Comment out (or delete) the SoapDocumentMethodAttribute on the WebMethod and the SoapDocumentServiceAttribute on the class that are set by default by the wizard.
  2. Set the SoapRpcMethod attribute on the WebMethod and the SoapRpcService attribute on the class.
  3. You can set parameters on both new attributes to change the behaviour and settings of the SOAP-RPC/Encoded service

That’s it. Since the .Net Framework creates an object based on your schema of the webrequest and uses this to call BizTalk, you don’t have to change anything on the BizTalk side to expose your schema’s as a SOAP-RPC/Encoded webservice. Now that is easy!

While on the subject of exposing schemas as a webservice: the generated webservice has ‘ParameterStyle=System.Web.Services.Protocols.SoapParameterStyle.Default‘ set on the SoapDocumentMethodAttribute by default. This causes an extra node in the envelope body named like the WebMethod’s name. If you don’t want this extra node, you can set the ‘ParameterStyle’ to ‘System.Web.Services.Protocols.SoapParameterStyle.Bare‘ and the extra node is not used anymore.

Start to blog on BloggingAbout.Net

Today I have started a blog on BloggingAbout.Net. Here I will be posting my findings on Microsoft BizTalk Server and .Net development.

For the past five years I have been working with .Net (mostly ASP.NET) and Microsoft BizTalk Server and many times I turned to blogs for finding answers to tech related questions. I decided I would like to give back to the community I have turned to many times. From of today I will be posting my findings and hopefully help someone out the way blogs have always helped, and will always help, me out.

Expect the first technical post later today. Please do not hesitate to comment, so I can make this blog better!