How-To: Expose your schemas as web services in Biztalk

Hire Me!

There are two ways to expose your business process as web service. One allows you to expose your orchestration within Biztalk as a web service and the other allows you to create new web service based on a schema file (xsd). Either way you will be converting a HTTP SOAP request to a biztalk message, do all your processing based on the message within the Biztalk world and then return a SOAP response. If you need to expose some of your existing business processes then you would likely be exposing an orchestration. If you starting off, exposing schemas could be a better option. My advice stick with the first option unless you really have good reasons not to. Once you read the rest of this How-To you will know why. What should have been a piece of cake, something that shouldn't have take more than few hours took forever. The web publishing wizard will gather some information from you about your schema and will auto generate c# code for you that will call your biztalk component responsible to send this SOAP request to a SOAP adapter. Bring up the web publishing wizard and select "Publish schemas as web services" option.

The second screen allows you to name your web service, the web methods and the parameters. There is bug in the component that is auto generating code. What the wizards calls your web service description is actually the namespace under which the class will be defined. If you give these two the same name the generated code will NOT compile. Make sure that the web service description, the root node and the class name, the child node of the root node DO NOT have the same name. In the next screen change the target namespace of the web service. Specify the location you want to host your web service at, if there is a web service already present in that location you will get the option to overwrite it. Check allow anonymous access to your web service. Also check the create Biztalk receive location and select the Biztalk application under which you want to create this receive location. Next screen gives you a summary. Review it, if everything looks good keep going. If you get errors at this point then it will most probably be an issues with permissions related to IIS or Biztalk. If there were no errors then you will given the URL to the published web service and file location of the .net solution. Open up the URL in your browser to make sure everything went well. You will have a link that says Something.asmx, click on that if you don't see any errors you are good. You are not done yet. You have exposed your schema as a web service and also created a receive location in Biztalk but there are no subscribers to that receive location. So if you try to invoke the web service will greeted by "Internal SOAP error" message. Very useful huh. Yeah that's all you get. Create an orchestration and subscribe to this port. Here is big gotcha that isn't documented any where in MSDN documents. The operation type of your logical receive port should match your web method name or else the message will NOT be picked up the orchestration. You might want to use the Biztalk subscription viewer to make sure you are subscribed to the port.   Don't start your Biztalk app and send a SOAP request, yet. You are not done. Now you know why this is so painful. Bring up your Biztalk admin console. Go to the receive port that the web publishing wizard created for you.   By default the wizard will select PassThru pipeline for both receive and send pipelines. Now technically you should select XMLReceive and XMLTransmit. Do this unless your schema is multi part in which case you want to select PassThruReceive and XMLTransmit. The SOAP adapter for some reason, I don't know if this is another bug, puts the wrong DocumentSpecName property in the message context in case of a multi part message. So when if you do PassThru there won't be any checking and it goes through. Obviously this won't work if you have inbound schemas.