Exposing Orchestration as a Web Service

• Download source project - 286.3 KB

Introduction

I was looking to develop an orchestration and expose its methods as a web service. This could be achieved relatively easily if the orchestration has only single operation. However, when we try to add new methods or modify few implementations and try to update the web service, it becomes necessary for us to follow the right approach and design the orchestration in a correct way, so that all the methods are added to the same web service. I have referred to several other sites for developing this sample. But I have combined the learnings/findings into this sample.

This is an orchestration (Calculator.odx) which has the methods Add, Subtract, Multiple, Divide. These methods are exposed in the web service which can be invoked from a test client.

Background

• BizTalk
• Orchestration
• Web service
• .NET
• SOAP

Developing the Orchestration

1. Create an orchestration Calculator.odx.
2. Create a two-way port type MathsPort, select the setting: I will be receiving a request and send a response and making its access modifier public as below:

   

   

3. For now, let us have the operations: Add, Subtract and expose them in the web service. Later, we can see how to modify the orchestration to add 2 more operations. Add these 2 operations in the MathsPort type.

   Create a configured port which is of the existing Port type: MathsPort. It should have 2 operations, Add and Subtract.

4. Create 2 schemas: MathReq and MathResp
   • MathReq: Has two fields: Num1 and Num2
   • MathResp: Has one output field: Out
5. Create 4 messages: AddReq, AddResp, SubReq and SubResp, which are of the MathReq and MathResp schema types.

   

6. Create 2 maps: AddMap.btm and SubMap.btm. AddMap.btm should transform AddReq to AddResp schema. Use the mathematical functoid + to map the two inputs to the Out field in the AddResp schema.

   AddMap.btm

   

   Similarly the mathematical functoid -  is used in the SubMap.btm.

   SubMap.btm

   

7. Add a parallel action shape to process multiple messages sent for Add and Subtract simultaneously. Add 2 branches for Add and Subtract that shall be executed in parallel.
8. Add a set of Receive, Transform, Send shapes for Add and Subtract branch each inside the parallel action.
9. Set the messages of Receive to AddReq/SubReq for Add and Subtract branches respectively. Similarly, set the messages of Send shapes to AddResp/SubResp. Configure the maps AddMap.btm and SubMap.btm inside the transform shapes in each of the branches.
10. Connect the Request operations of the Add/Subtract to the receive shapes of the Add/Subtract branches respectively. Similarly, Send ports and the Response operations should be connected.

Completed orchestration is like:

When we build the project, we will get an error related to the activation and Receive shapes. Since we have more than one receive shape, we need to have a correlation set defined. Create a new correlation type "CorrelationType_1" and select the BTS.ReceivePortName as the property to be used for correlation. Create a new Correlation Set and associate it with all the receive shape using the 'Initializing Correlation' property.  

Correlation Type:

Correlation Set:

Now build and deploy the project with the orchestration, schemas and maps.

Publishing the Orchestration as Web Service

From the start menu, under BizTalk Server, choose the 'BizTalk Web Services Publishing Wizard'. Select the option 'Publish orchestrations as web services' and select the project DLL file OrchAsWebService.dll. It shows the orchestration type: OrchAsWebService.Calculator and the single port 'MathsPort'.

In the Web Services project screen, choose the appropriate virtual directory/application in the IIS where you want the web service  to be hosted. It is also possible to create a web site/virtual directory via IIS and give the same here. Select 'Allow anonymous access to the web service' and also 'Create Biztalk receive locations in the following application'. Select the application that we deployed our application earlier. It will create the receive port using the SOAP transport type that needs to be configured in the orchestration.

Finish the wizard by creating the web service, which will create the necessary asmx/.cs files in the C:\inetpub\wwwroot\<Virtual Dir> folder as below:

Configure the orchestration by connecting the logical port 'MathsPort' of the orchestration with the receive port that we created in the Publishing wizard.

Orchestration configuration:

Restart the host instance and start the application in BizTalk.

Now, our web service and orchestrations should be fully functional. It can be executed using a client. Test the web service by browsing the URL from the IIS. We should be able to see the Add, Subtract methods in the web service.

Web Service:

Calling the Web Service methods:

1. Create a separate console application and Add Service reference and provide the full URL of our web service in the Address field.

   

2. Click on 'Advanced and check the 'Generate Asynchronous Operations' checkbox in the advanced options.

   

3. Select appropriate namespace such as 'MathServ' and click on 'Ok'.
4. Now the required references and schemas related to our web service should be added. Invoke the methods as shown below. We can execute the methods either in a synchronous or asynchronous manner.
5. Provide some test inputs as numbers and verify that the web service returns the result by performing Add or Subtract operations.

   

   

Adding More Operations Multiply, Divide

Adding more operations to the orchestration should be easy with the Parallel Actions shape. Add new operations Multiply, Divide in the port type: MathsPort. Add new maps MultiMap.btm, DivMap.btm which do the multiple and divide operations. Then, add a new branch similar to Add/Subtract branch, add the messages for Receive/Send shapes and transform the messages appropriately. Connect the request and response shapes similar to how we did for Add and Subtract.

Deploy the project to BizTalk.

Run the Biztalk Publish Web Service wizard again and this time, all the settings are the same, but choose to 'overwrite the existing project' so that our latest changes are updated.

Our web service should now be updated with the additional two methods.

Just update the web reference in the test client and we should now able to see the additional Multiply and Divide methods.

Remarks

We are able to create an orchestration with multiple operations and expose these in a single web service. Publishing and updating the changes can be done which updates the calling client application to just update the web references and they get the latest methods from the web service.

History

• 1^st December, 2015: Initial version