Welcome!

.NET Authors: Liz McMillan, Yakov Werde, Matthew Pollicove , Kevin Benedict

Related Topics: .NET

.NET: Article

BizTalk Server 2006 Tutorial - A Walk Through the Process

Creating services with contract-first design using BizTalk Server 2006 R2 and Windows Communication Foundation

This highly simplified orchestration accepts a GetCustomerRequestMessage instance, creates an instance of the System.Xml.XmlDocument .NET class and loads into it the XML for a dummy GetCustomerResponseMessage, and finally sends the GetCustomerResponseMessage back to the caller.

Please refer to the sample solution download for the implementation of the RecordTransaction orchestration.

It's time to deploy the solution to BizTalk, and then we can publish it as a WCF service.

  1. From the Build menu, select "Configuration Manager" to display the "Configuration Manager" dialog box.
  2. In the "Active solution configuration" drop-down list, select "Deployment," then click the Close button.
  3. Rebuild the solution.
  4. Finally, from the Build menu, select the "Deploy Solution" menu item, then verify that the deployment completed. In the "BizTalk Server Administration" tool, you should now see an application called "BankAccountService."

Step 5: Publish the service as a Web Service using WCF
One of the most common ways to expose a service is as a SOAP Web Service. Now that our BizTalk application has been created, we can use the BizTalk WCF Service Publishing Wizard to create a WCF service in IIS. The wizard creates a folder under the IIS "Default Web Site" home directory (usually inetpub/wwwroot) that contains a .SVC file, a web.config file, a copy of the XSD files used by the service, and a definition file that describes the service operations and associated schemas. This gives IIS what it needs to host the service for us, and a way to tie the service back to the BizTalk engine.

  1. From the Start menu, locate and expand the "Microsoft BizTalk Server 2006" folder, then select the "BizTalk WCF Service Publishing Wizard." Click the Next button to bypass the wizard's welcome page.
  2. The wizard allows you to create a service endpoint or a metadata endpoint (see Figure 1). A metadata-enabled endpoint allows a client to download the WSDL and XSD's directly from the running instance of the service. It can be enabled or disabled depending on your security requirements. We will go ahead and choose a "Service endpoint" with "Enable metadata endpoint" checked.
  3. On this page you may also select the WCF HTTP binding: WCF-BasicHttp for a basic unsecured SOAP Web Service, WCF-WSHttp for a SOAP Web Service that can utilize WS-Security and other WS-* protocols, or WCF-CustomIsolated if you plan to manually configure the WCF bindings to your liking. Choose "WCF-BasicHttp" for this example.
  4. Last on this page, we can ask the wizard to create a receive port and location for us in our BizTalk application. We would like to do that, so check "Create BizTalk receive locations in the following application" and select "BankAccountService" from the drop-down list. Click the Next button to continue with the wizard.
  5. The next step of the wizard allows us to publish the service based on either orchestrations or schemas (see Figure 2). Since the whole purpose of our example is contract-first design, our schemas represent our service interface. Choose "Publish schemas as WCF service" and click the Next button.
  6. The wizard now asks us to describe the service interface. This information is necessary to dynamically build a WSDL file for the service. Starting at the top of the tree, right-click the "BizTalkWcfService" node and choose "Rename web service description." Type the new name "BankAccountService" and press Enter. On the next child node called "Service1" right-click the node and choose "Rename web service." Type the new name "BankAccountService" and press Enter.
  7. Now, we will configure the GetCustomer operation. Right-click the node "Operation1" and choose "Rename web method." Type the new name "GetCustomer" and press Enter.
  8. Select the schema for the GetCustomer "Request" node by right-clicking it and choosing "Select schema type." A new dialog will appear (see Figure 3). Click the "Browse" button then select the bin\Deployment\BankAccountService.dll file under the service project folder. In the Browse dialog, click Open to view the schemas inside the DLL. In the "Available schema types" list view, locate and select the schema "BankAccountService.GetCustomerRequestMessage" then click OK.
  9. Repeat the process in Step 8 for the "Response" node to select the "BankAccountService.GetCustomerResponseMessage" schema.
  10. The last part of the definition is the RecordTransaction operation. Right-click the child "BankAccountService" node and choose "Add web method," "Request-response." Follow the process in Steps 7-9 to define the RecordTransaction operation using the "BankAccountService.RecordTransactionRequestMessage" and "BankAccountService.RecordTransactionResponseMessage" schemas (see Figure 4). Click Next to continue.
  11. The next step of the wizard asks for an XML namespace for the service (see Figure 5). You will typically want to customize this namespace to follow your organization's standard format. For this example, just click the Next button.
  12. The last step of the wizard lets you specify the service's path in IIS (see Figure 6). The wizard will create a new virtual directory in IIS at the specified location. If you've previously exported to the same location, you must check the "Overwrite existing location" checkbox. The "Allow anonymous access to WCF service" checkbox determines whether anonymous access is enabled on the virtual directory security configuration. Click the Next button and then the Create button to publish the service to IIS then Finish when the publish operation is complete.

Now that our WCF service has been created, we need to enable the new receive location in our BizTalk application.

  1. Open the "BizTalk Server Administration" tool.
  2. Expand the "BizTalk Server 2006 Administration" node then the "BizTalk Group" node, the "Applications" node, and the "BankAccountService" node.
  3. Select the "Receive Locations" node and notice that the receive location named "WcfService_BankAccountService/BankAccountService" is currently disabled. Right-click the receive location and select "Enable."

Try out the service by opening your favorite Web browser and visiting http://localhost/BankAccountService/BankAccountService.svc. You should see a formatted page with sample C# and VB client code and a link to view the service WSDL.

A note on security configuration: the wizard creates the virtual directory under the default application pool on Windows Server 2003, so the service will attempt to run as the user identity configured in that application pool, or as the local ASPNET user on Windows XP. Either way, the user must be a member of the "BizTalk Isolated Host Users" security group. If the user doesn't have sufficient rights, you may get the error "Please verify that the receive location exists, and that the isolated adapter runs under an account that has access to the BizTalk databases" when you attempt to view the service in a Web browser.

The last step is to connect the receive location to the orchestrations so that calls to the service route those messages to the orchestrations.

  1. Switch back to the "BizTalk Server Administration" tool window.
  2. Select the "Orchestrations" node under "BankAccountService."
  3. Right-click the "BankAccountService.GetCustomer" orchestration and select Properties.
  4. Select Bindings from the left-hand list. Choose "BizTalkServerApplication" in the "Host" drop-down list. Choose "WcfService_BankAccountService/BankAccountService" in the "Bindings" list view where the current value is "<None>" for the logical port "GetCustomerPort." Click the OK button to close the dialog.
  5. Repeat Steps 3-4 for the "BankAccountService.RecordTransaction" orchestration.
  6. Right-click each of the two orchestrations and select "Start."

Our Web service is now deployed, started, and ready for use! The sample solution download includes everything we have created here, as well as a test client. (Download the sample solution.)

Step 6: Publish the service as a TCP endpoint
If you want to publish the service using a non-HTTP protocol like TCP or named pipes, BizTalk will host the service directly in the BizTalk Windows service versus IIS. In this situation you don't need to run the "WCF Service Publishing Wizard" at all, because there are no other artifacts to create. Instead, create a receive port and location in the application and simply select one of the non-HTTP WCF bindings such as "WCF-NetTcp" or "WCF-NetNamedPipe." This is quite a bit easier than the HTTP-based process that we walked through earlier. This scenario is left for you to play with on your own.

In summary, designing services with contract-first design is a natural fit with BizTalk Server since it works natively with XML Schemas. BizTalk includes tools to create the schemas that define a service contract and operation messages. It also includes tools to publish the schemas as a WCF service as well as monitoring, service hosting, message tracking, management tools, centralized configuration, a rules engine and more to round out the implementation and runtime management of your services.

More Stories By Thomas Abraham

Thomas Abraham, MCPD, MCT, is an Enterprise Consultant with Minneapolis, MN-based management and technology consulting firm Digineer (www.digineer.com). Thomas maintains a blog at http://blogs.digineer.com/blogs/tabraham.

Comments (0)

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.