Overview
One of the useful features I’ve found when doing BizTalk 2010 development is the BizTalk WCF Service Publishing Wizard. This tool allows you to publish a schema or BizTalk orchestration as WCF Service. Typically, it is a best practice to expose a schema as a WCF Service as opposed to exposing an orchestration as WCF Service. By doing so, you can expose a schema as a WCF Service and bind a port within an orchestration to this published service. This allows you to change the port binding and/or protocol without redeploying the orchestration as well as modify the published schema without having to redeploy the orchestration that consumes it. In this tutorial, I will be describing the steps to publish a schema as a WCF Service and show how this service can be consumed within a BizTalk orchestration. This tutorial, as well as the rest in the BizTalk 2010 series, will be following a problem-design-solution format.
Problem
In this scenario, we will be developing a BizTalk messaging solution for the well known pharmaceutical company Wonderful Drugs Inc. Wonderful Drugs Inc. is currently sponsoring a clinical trial for a new drug they hope to release to the public. Typically, Wonderful Drugs Inc. pays medical institutions to manage and enroll patients into their clinical trials. Unfortunately, there is not a standardized format of patient demographics when enrolling patients into a clinical trial. Each of the multiple institutions enrolling patients collects demographics in a different format. Our objective is to provide an endpoint for a single institution to submit enrollment information to Wonderful Drugs Inc. using the institutions proprietary format. Fortunately, the first institution we will provide an endpoint for has given us an XSD schema describing the patient enrollments they will be submitting.
Design
To solve the problem at hand, we will be designing a BizTalk orchestration to receive enrollment information from ABC Institution and store those enrollments some where. For the time being, we will be storing the enrollments to the local file system. In later tutorials, we will be changing how the enrollments are stored.
Once our orchestration is configured, we will be exposing the XSD schema provided to us by ABC Institution as a WCF service so that they can consume this service. This service will be the endpoint at which ABC Institution will be submitting subjects to be enrolled within our clinical trial.
Enrollments submitted to the WCF endpoint will be similar to the one below:
<Enrollment TrialID="TRL25949">
<Patient SSN="510-26-7612">
<Name>John Q. Smith</Name>
<DOB>04/25/1959</DOB>
<MedicalRecordNumber>BCG-627-DQP</MedicalRecordNumber>
<Gender>Male</Gender>
<Race>Caucasian</Race>
</Patient>
</Enrollment>
The design of this solution is very simple and very straight forward. Let’s get started!
Solution
1. To begin, open Visual Studio 2010 and create a new Solution with the name of WonderfulDrugs.BizTalk.
2. Right click on the new solution and select “Add -> New Project”. Under the BizTalk Projects section of the installed templates, select Empty BizTalk Server Project. Finish by naming the project WonderfulDrugs.BizTalk.ExternalSchemas.
3. Now we need to configure this project to deploy properly. Right click on the ExternalSchemas project and click “Properties.” On the Properties page select the click the “Signing” tab. Each BizTalk project must be signed with a Strong Name Key. Now click the “Sign the assembly” checkbox. The “Choose a strong name key file:” dropdown will appear and select “<New…>”. Give the strong name key file the same name as the project (i.e. WonderfulDrugs.BizTalk.ExternalSchemas.snk).
4. Now select the Deployment tab on the properties page so we can set the Application Name that this project will be deployed to. Set the Application Name property to “WonderfulDrugs.BizTalk.ExternalSchemas”.
5. We are now ready to add our first BizTalk artifact. Right click on the ExternalSchemas project and select “Add -> New Item”. Then select “Schema” and change the name of the schema to ABCInstitution.Enrollment.xsd. Typically, a schema would be given to you by the institution, client, or vender, but we are going to create it instead.
6. Open the schema you just created.
a. Right click on the root element and select “Rename”. Rename the element to “Enrollment.”
b. Right click on the “Enrollment” element and select “Insert Schema Node -> Child Field Attribute”. Name the new child attribute “TrialID.” Then ensure the data type of this attribute is xs:string. You can do this by right-clicking the attribute, selecting properties and reviewing the “Data Type” property.
c. Now we need to add a Patient element to the enrollment. Right click on the “Enrollment” node and select “Insert Schema Node -> Child Record”. Now name the record “Patient”. On the Properties page, set the Max Occurs and Min Occurs to 1.
d. Now add a “Child Field Attribute” to the “Patient” node and give it the name “SSN” and a data type of xs:string.
e. Now add a “Child Field Element” to the “Patient” node and give it the name of “Name” and a data type of xs:string. On the Properties page, set the Max Occurs and Min Occurs to 1.
f. Now add a “Child Field Element” to the “Patient” node and give it the name of “DOB” and a data type of xs:date. On the Properties page, set the Max Occurs and Min Occurs to 1.
g. Now add a “Child Field Element” to the “Patient” node and give it the name of “MedicalRecordNumber” and a data type of xs:string. On the Properties page, set the Max Occurs and Min Occurs to 1.
h. Now add a “Child Field Element” to the “Patient” node and give it the name of “Gender” and a data type of xs:string. On the Properties page, set the Max Occurs and Min Occurs to 1.
i. Now add a “Child Field Element” to the “Patient” node and give it the name of “Race” and a data type of xs:string. On the Properties page, set the Max Occurs and Min Occurs to 1.
7. Now that your external schema has been created, we need a project to hold our orchestrations. Right click on the solution and select “Add->New Project”. From the BizTalk Projects template store select “Emtpy BizTalk Server Project” and give it the name of WonderfulDrugs.BizTalk.Orchestrations. Then click “OK”.
8. As we did before with the External Schemas project, we need to configure the Deployment and Signing for the Orchestrations project. Open the project properties and set the Application Name on the Deployment tab to WonderfulDrugs.BizTalk.Orchestrations and add a strong name key to the assembly.
9. You need to add a reference to the ExternalSchemas project. Right click on the “References” folder on the Orchestration project and select “Add Reference…” The Add Reference dialog box should appear. Select the Projects tab and double click the WonderfulDrugs.BizTalk.ExternalSchemas project. You should now be able to reference the schemas within the ExternalSchemas project.
10. Now we need to add an orchestration to our new project. Right click on the Orchestrations project and select “Add->New Item”. Select the BizTalk Orchestration item and name it WonderfulDrugs.Receive.odx and click Add.
11. You should now see an empty design surface for your BizTalk orchestration. From your Toolbox in Visual Studio drag a Receive shape onto the design surface. This shape will be used to receive messages from a port we will configure a little bit later on.
12. Now we must activate this receive shape. Right click on the shape and select “Properties Window”. Within the Properties Window change the Activate property from False to True.
13. The next shape we will add is a Send shape. In our example, this shape will just send the message that is passed by the receive shape to a file drop on the local file system. All we need to do is drag this shape from the Toolbox onto the design surface between the receive shape and the end of the orchestration which is signified by the red dot.
14. Our next step will be to add a new Port to the design surface that can be used as our endpoint to receive messages from the external clients or services. To do this, Right Click on the design surface in the are labeled “Port Surface”. The select the New Configured Port… option. This will start the Port Configuration Wizard.
a. The Port Configuration Wizard looks as follows. On the first screen click Next.
b. Now you must name the port to be configured. We will choose to name the port “ABCInstitutionReceivePort”.
c. The next screen will allow us to select a port type. We will be creating a new port type for our configured port. Under the “Port Type Name”, name your port “ABCInstitutionReceivePortType”. For the “Communication Pattern” leave it marked as One-Way since we will only be receiving on this port and not sending a response. As for the “Access Restriction” select “Public – no limit”.
d. On the Port Binding screen, leave the defaults selected. They should be marked as “I’ll always be receiving messages on this port” for the port direction of communication and “Specify Later” for the port binding.
e. One final screen, you will see a summary of your configured port. When finished reviewing click the “Finish” button.
15. After you finish the wizard, you will be able to see your newly configured port located on the “Port Surface.” Now you will need to set the operation name of the new port. Start by right clicking on the port’s only operation and clicking “Properties Window.” In the Properties Window change the Identifier or the operation from Operation_1 to “EnrollSubject”. This will be important down the road when we eventually publish the enrollment ABCInstitution.Enrollment schema as a WCF service.
16. Now we need to add another configured port to the Port Surface. Follow the same steps as the previous port, but use the following criteria:
Port Name: |
SubjectEnrollmentSendPort |
Port Type: |
Create a new Port Type |
Port Type Name: |
SubjectEnrollmentSendPortType |
Communication Pattern: |
One-Way |
Access Restrictions: |
Private – limited to the containing module |
Port Direction of Communication: |
I’ll always be sending messages on this port. |
Port Binding: |
Specify Later |
Your Port Configuration Wizard Summary should look like the one below:
17. Now you must add a message to this orchestration. Open the “Orchestration View” so that you can add a new Message. Typically, you can open this view by clicking the tab on your View Pane named Orchestration View.
Now right click the “Messages” folder within the Orchestration View and select “New Message.” A new message will appear. Open the Properties Window for this message and change the Identifier property from Message_1 to SubjectEnrollmentRequest.
Then select the drop down from the Message Type property. This will allow us to select what type of data the SubjectEnrollmentRequest will be made of. From the drop down, expand the Schemas node and double click <Select from a referenced assembly..>
The Select Artifact Type dialog box will appear. In the right pane will be a list of referenced assemblies that you can select a schema type from. You will be looking for the WonderfulDrugs.BizTalk.ExternalSchemas assembly (note: if it is not visible, you either forgot to reference the assembly, or you need to build your solution. Don’t worry if the solution doesn’t build successfully, it shouldn’t at this point.). Once you select the ExternalSchemas assembly, a list of schemas will appear. You should only see the ABCInstitution_Enrollment schema. Select this schema and click the OK button.
18. Now your orchestration needs to utilize the new message that was just created. Right click on the Receive shape in your orchestration and select Properties Window. Once the properties window opens select SubjectEnrollmentRequest for the Message property. This is telling the Receive shape, that it will be receiving messages of the schema type that the SubjectEnrollmentRequest is constructed from.
19. Follow the same steps for the Send shape so that this shape knows what type of message it will be sending.
20. The next step will be configuring the message types for both the receive and send port. Right click on the Request of the ABCInstitutionReceivePort and open the Properties Window.
From the Message Type property, open the drop down, expand the Schemas node and select <Select from a referenced assembly…>. As you did the step 17, select the ABCInstitution.Enrollment schema from the WonderfulDrugs.BizTalk.ExternalSchemas referenced assembly.
21. Do the same for the SubjectEnrollmentSendPort and assign the ABCInstitution.Enrollment schema to the Request’s Message Type.
22. Now that all of the ports and send and receive shapes have been configured with the appropriate message types, it is time to tie the orchestration together. From the ABCInstitutionReceivePort drag the Request to the endpoint on the Receive shape. This allows for the Receive shape to receive messages on that port. As you can see now, it is important that the receive port and receive shape are configured to receive messages of the same schema type.
Do the same to configure the send port by dragging the Request on the SubjectEnrollmentSendPort to the endpoint on the send shape. Your orchestration should now be fully configured and look like the one below:
23. Finally, build the entire solution. Your solution should build without errors and if it doesn’t try and work through any errors it produces.
24. This tutorial assumes that you have BizTalk Server 2010 installed and configured on your local machine. This will be crucial for deployment. Right click on the WonderfulDrugs.BizTalk.Orchestrations project and select Deploy. If you receive any errors about access being denied, close Visual Studio and reopen it as an administrator. A successful deployment will look as follows.
25. The next step will be to publish the ABCInstitution.Enrollment schema as a WCF service and configure our BizTalk orchestration to use this service as an endpoint for receiving enrollments. To begin, open the BizTalk WCF Service Publishing Wizard. You can start this wizard by clicking Start, pointing to All Programs, pointing to Microsoft BizTalk Server 2010, and then click BizTalk WCF Service Publishing Wizard.
26. The BizTalk WCF Service Publishing Wizard should now be visible.
a. Start the wizard by clicking Next.
b. On the next screen leave the Service endpoint radio button checked as we will actually be receiving messages on the endpoint. From the Adapter name (Transport type): drop down select WCF-BasicHttp. This transport type gives us the most interoperability across multiple platforms. Now, click both the Enable metadata endpoint and Create BizTalk receive locations in the following application checkboxes. Under the BizTalk application name select WonderfulDrugs.BizTalk.Orchestrations since this is the application we want to create the receive locations within. Then click Next.
c. On the Create WCF Service screen select Publish schemas as WCF service. By exposing a schema as a service as opposed to an orchestration, this reduces dependencies and allows the configuration of the orchestration to be more loosely coupled.
d. On the WCF Service screen, it will default to the configuration below:
Right click on Operation1 and select Delete web method. We want to create a One-way web method as opposed to a request-response. Right click on Service1 and select Add web method –> One-way. Now right click and rename Operation1 to EnrollSubject (note: this is the same name as was used in the configured receive port in the orchestration). Now right click and rename Service1 to Enrollment. We also want to change the service description from BizTalkWcfService to WonderfulDrugsEnrollmentService. The final step is to right click on the Request and select the appropriate schema type. Browse to the location of the of the WonderfulDrugs.BizTalk.ExternalSchemas assembly and select the ABCInstitution.Enrollment schema.
The fully configured service should look as follows:
e. On the WCF Service Properties screen set the target namespace to http://wonderfuldrugs.com/integration/servicetypes.
f. On the WCF Service Location leave the Location set to http://localhost/WonderfulDrugsEnrollmentService and check the Allow anonymous access to WCF service checkbox.
g. The WCF Service Summary screen will appear and complete the wizard by clicking Create.
27. Now that we have a schema published as a WCF service, it needs to be configured within our orchestration. Open the BizTalk Server Administration Console by going to Start –> All Programs –> Microsoft BizTalk Server 2010 –> BizTalk Server Administration.
Expand out the Console Root down to BizTalk Server Administration –> BizTalk Group –> Applications –> WonderfulDrugs.BizTalk. Orchestrations. Then right click on the WonderfulDrugs.BizTalk.Orchestrations and select Configure…
Then select Orchestration_1 under the Orchestrations header.
a. Set the Host: property to BizTalkServerApplication.
b. Set the ABCInstitutionReceivePort to WcfReceivePort_WOnderfulDrugsEnrollmentService/Enrollment
c. Then click the drop down on the SubjectEnrollmentSendPort and click <New send port…>. We need to create a new send port to bind to this configured port from within our orchestration. Configure the send port as follows:
d. Click Configure… to configure the destination folder where this file will be dropped. Leave the File name as %MessageID%.xml and set the Destination folder to C:\WonderfulDrugs\Enrollments\( you may have to create this folder structure if you haven’t done so already ). When you’ve finished click Apply and then Ok.
28. The final step to completing this tutorial is starting the application. To do so, right click on the WonderfulDrugs.BizTalk.Orchestrations application and click Start…
In the upcoming tutorial, I will show you how to consume the schema exposed as a WCF service and how messages our passed through the orchestration. Questions, comments, and general feedback is greatly appreciated.