Service Station
BizTalk Server 2006 Web Services
Aaron Skonnard
Contents
Web Services Adapters
Using the SOAP Adapter
SOAP Transport Properties
Using the SOAP Adapter in Orchestrations
The WSE 2.0 Adapter
The WCF Adapter
Summary
This month I'll introduce you to the exciting world of BizTalk Server 2006 and its support for today's Web services technologies. You'll learn how to use the SOAP and Web Services Enhancements (WSE) adapters available right now, and I'll tell you about the forthcoming Windows® Communication Foundation (WCF) adapter included in the BizTalk® Server 2006 R2 release.
BizTalk Server 2006 is built on a flexible messaging subsystem that promotes loosely coupled messaging interactions across heterogeneous applications. The messaging layer provides numerous integration benefits such as message routing, schema transformations, and format translations. At the heart of the messaging layer is a SQL Server™ database referred to as the message box. All messages processed by the messaging layer travel through the message box for routing, tracking, and error-handling purposes. The message box operates by a "leave no message behind" mantra, which is a key feature when reliability is paramount. However, to be fair, this feature can also become a liability when performance is more important.
You control how messages are routed between applications by defining message subscriptions (also known as "filters") in the message box. You can define filters in the administration console (on send ports) or you can define them indirectly within orchestrations using logical port definitions. As illustrated in Figure 1, when a message is published, the message box evaluates the incoming message against subscriptions and routes the message to all matching subscribers (send ports or orchestrations). This publish/subscribe architecture completely decouples senders from receivers.
Figure 1** BizTalk Messaging Architecture **(Click the image for a larger view)
BizTalk interacts with the outside world through adapters. An adapter receives bytes over a particular transport and creates a new BizTalk message that will be published to the message box after the receive pipeline and a map (an XSLT transform) have had a chance to operate on the incoming message (see Figure 2). The reverse is true for transmitting outgoing messages. After the map and send pipeline have had a chance to operate on the outgoing message, the adapter transmits the resulting bytes to the transport. You configure these details through send and receive ports in BizTalk.
Figure 2** BizTalk Port Internal **(Click the image for a larger view)
BizTalk supports one-way and two-way ports. On the receive side, you can define one-way receive ports that simply receive messages but don't return anything. You can also define request-response receive ports that return response messages to the caller. Similarly, on the send side, you can define one-way or solicit-response ports.
BizTalk Server 2006 comes with a variety of adapters that support a wide range of transports and protocols, including several designed specifically for SOAP and WS-*. The fact that BizTalk supports numerous communication mechanisms in addition to SOAP and WS-* is one of its most compelling characteristics. This makes BizTalk a central figure in systems that must straddle legacy applications and newer service-oriented investments.
Web Services Adapters
BizTalk Server 2006 integrates with SOAP and WS-* through the different Web service adapters listed in Figure 3. The SOAP adapter, which ships with BizTalk Server 2004 and later versions, supports WS-I Basic Profile 1.1 (BP 1.1) messages. If you need support for WS-* protocols, you'll have to turn to one of the WSE adapters available today or wait for the Windows Communication Foundation adapter coming in the BizTalk Server 2006 R2 release.
Figure 3 BizTalk Web Service Adapters from Microsoft
| Adapter | BizTalk Server 2004 | BizTalk Server 2006 | BizTalk Server 2006 R2 |
|---|---|---|---|
| SOAP | Included | Included | Included |
| WSE 2.0 | Download available | Download available (requires SP1) | Download available (requires SP1) |
| WCF | Not included | Not included | Included |
Microsoft provides a WSE 2.0 adapter that you can download from microsoft.com/biztalk/evaluation/adapter/adapters/wse. The WSE 2.0 adapter runs on both BizTalk Server 2004 and BizTalk Server 2006 (although the latter requires the SP1 release). Microsoft chose not to implement an adapter for WSE 3.0 because the forthcoming Windows Communication Foundation adapter will provide equivalent functionality. However, there are third-party WSE 3.0 adapters available.
Figure 4** Using a Web Services Adapter **(Click the image for a larger view)
You can use any of these adapters to send and receive SOAP messages in BizTalk. You can use them in conjunction with one-way or two-way ports. For example, you can use the SOAP adapter to send and receive simple SOAP messages that conform to BP 1.1, or you can use the WSE 2.0 adapter to send and receive SOAP messages that are secured according to the WS-Security, WS-Trust, and WS-SecureConversation specifications.
On the receive side, it's the adapter's job to perform the SOAP and WS-* processing and to publish the body of the message to the message box. In Figure 4, the ASMX endpoint is essentially the adapter. At run time, the ASMX code communicates with BizTalk to retrieve the receive location details from the configuration database so that it can use the configured receive pipeline and map set during publishing. The fact that you can preprocess incoming SOAP messages with traditional BizTalk pipelines and maps is a powerful combination that will increase your integration options.
BizTalk requires that all HTTP-based receive locations run in an isolated host process such as IIS instead of a BizTalk-managed process. This means BizTalk does not fully control the configuration of SOAP/HTTP receive locations. Instead, it assumes the isolated host will control the various SOAP/HTTP processing details. You'll also have to write (or better yet, automatically generate) the isolated host application code.
You typically use a wizard to produce the adapter code that will run in the isolated host. However, you don't have to use a wizard; it's possible to write a generic SOAP endpoint capable of receiving and publishing any SOAP message into BizTalk.
You can also use any of the Web service adapters listed in Figure 3 to send BizTalk messages from the message box to external Web services. You simply define a send port that uses one of the adapters and then you configure it with any of the various settings it provides for transmitting the outgoing SOAP message.
It's important to note that you can do all of this directly within the BizTalk messaging layer without using orchestrations. Of course, you can also consume Web services within orchestrations. This, is an attractive option because the orchestration designer greatly simplifies the developer experience while offering advanced support for long-running processes, correlation, and error handling. It's also possible to publish an orchestration as a Web service to automatically expose its public receive ports.
Now let's take a closer look at performing some of the tasks I've just described using the SOAP and WSE adapters available today.
Using the SOAP Adapter
Let's assume you already have a BizTalk solution in place for processing orders. You already have several receive locations configured for receiving orders over different transports, say MSMQ and FTP, and you already have subscriptions in place for processing the published order messages. And now you simply want to add support for receiving orders via SOAP in addition to everything else. In this case, you already have the order message schema-you just need to generate an ASMX service around it.
You can generate an ASMX service from existing schema types by running the BizTalk Web Services Publishing Wizard. The wizard lets you choose between publishing schemas or an orchestration. In this case, you want to publish schemas.
Next, you'll be asked to describe the Web service contract that you wish to expose. Since you're just publishing a schema, you must manually define the name of the Web service and the name of each WebMethod operation that you want to create. Then, for each WebMethod, you can map the request/response messages to a specific schema type found within a BizTalk assembly (see Figure 5). The wizard asks for additional details about the ASMX code that it's about to generate, such as the target namespace, the ASMX parameter style, and whether you'd like to make BP 1.1 conformance claims. It also asks if you would like to support additional or unknown SOAP headers to allow for future processing.
Figure 5** Publishing a Schema **(Click the image for a larger view)
Finally, it asks for the virtual directory where it should deploy the generated ASMX code. It will also create a corresponding receive location in an existing BizTalk application for you. When you finish the wizard, it generates the ASMX code, publishes it to the specified directory, and creates a BizTalk receive location configured for the service.
Before you can browse to the generated ASMX endpoint, however, you'll need to verify that the virtual directory is configured to run within an application pool that has permission to access the BizTalk databases (the identity of the application pool needs to be a member of IIS_WPG and BizTalk Isolated Hosts Users). At this point, you can also configure other aspects of HTTP and ASP.NET processing using traditional configuration techniques in IIS and the Microsoft® .NET Framework.
The other half of the configuration is found within the BizTalk receive location. If you open the BizTalk administration console, you'll find the SOAP receive location created by the wizard. The receive location properties will look similar to Figure 6. Notice it's configured to run in the isolated host instance. Also, if you click the Configure button to configure the SOAP transport, you'll notice it only contains the address of the service (this is the key used by the isolated host to look up other aspects of the BizTalk configuration at run time, such as the receive pipeline and maps).
Figure 6** SOAP Receive Location Configuration **(Click the image for a larger view)
After the virtual directory is configured properly, you can browse to the generated ASMX endpoint and you'll see the traditional ASMX documentation page. If you inspect the operation details, you'll notice that the body of each SOAP message is simply the schema type you specified in the wizard. Now clients can access the ASMX endpoint to retrieve the service's Web Services Description Language (WSDL) definition for generating client code. WSDL code generation makes it a lot easier for SOAP-savvy clients to integrate with the BizTalk solution.
Now let's suppose that there's an external billing service that you need to send messages to in response to an incoming order message. And let's also assume that you already have a Web services proxy class developed for the purpose of communicating with the external Web service. (You would have created this using wsdl.exe or Add Web Reference.)
You can create a send port capable of sending messages to the external billing service. Simply choose the SOAP adapter and specify the address of the external Web service (see Figure 7). Then, on the Web Service tab, select a Web service proxy class and method to use (see Figure 8). BizTalk will use this proxy class when sending the message. The assembly needs to be in the global assembly cache (GAC) at run time.
Figure 7** SOAP Send Port Configuration **(Click the image for a larger view)
Figure 8** Specifying a Proxy Class **(Click the image for a larger view)
The hardest part about making this work is supplying the correct message to the SOAP adapter at run time. If the specified proxy class method takes more than one parameter, BizTalk expects you to supply a multi-part message where each part corresponds to a parameter in the signature. BizTalk will deserialize each message part into the corresponding .NET Framework type before invoking the Web service proxy method, which then serializes everything back into a SOAP message.
Note that when you need to implement an existing WSDL definition, you can use the BizTalk Business Process Execution Language (BPEL) import wizard to generate an orchestration skeleton from the WSDL. You can also use the traditional wsdl.exe /server in conjunction with some manual intervention to produce the correct adapter code.
SOAP Transport Properties
When using the SOAP adapter, there are numerous SOAP-specific message context properties available to you. They are all found within the SOAP namespace and you can access them from within pipeline components and orchestration shapes.
For example, SOAP.AssemblyName and SOAP.MethodName identify the Web service proxy class and method to use when sending messages through a SOAP send port. You may also want to configure client credentials dynamically through SOAP.Username and SOAP.Password. Or you may need to increase the response timeout value by setting SOAP.ClientConnectionTimeout. You can use these properties to configure a variety of dynamic send port properties at run time. Refer to the SOAP adapter documentation for a complete list of SOAP adapter properties and how they work.
On the receive side, you may need to process various SOAP headers found in the incoming SOAP message. There are two ways to accomplish this task. First, if you defined any known SOAP headers when using the publishing wizard, these headers will be made available to you as custom properties in a special SOAPHeader namespace. Otherwise, all unknown SOAP headers are stored in the SOAP.UnknownHeaders property. In addition, if you need to add more SOAP headers to outgoing SOAP messages, you can populate the SOAP header properties before sending the message.
One last thing I should mention before continuing is the new failed message routing feature in BizTalk Server 2006. When enabled on send/receive ports, this feature causes failed messages to be republished to the message box with additional error report properties (found in the ErrorReport namespace) in the message context. This makes it possible to subscribe to the various ErrorReport properties in order to be notified when certain errors occur within your SOAP send/receive ports.
Using the SOAP Adapter in Orchestrations
So far I've covered the fundamentals of using the SOAP adapter within the messaging layer without using BizTalk orchestrations. Of course, you can also use the SOAP adapter in conjunction with orchestrations, which is typically an easier proposition.
You can publish an orchestration as a Web service by running the same BizTalk Web Services Publishing wizard, only this time you'll choose to publish an orchestration. The wizard asks you to choose an orchestration and the public ports that you wish to expose. The service contract will be derived from the selected ports, so you won't have to define the contract manually as you did in the past. The rest of the steps in the wizard will be the same as before: it asks for the various IIS and ASP.NET settings and it generates an ASMX service. The main difference is that the wizard is able to automatically derive the contract from the orchestration.
You can also consume Web services from within orchestrations. You start by using the Add Web Reference command in Visual Studio®. This brings in the required schema and port types that you'll need to invoke the external service from an orchestration. Then you define a new orchestration port and select the Web port type added by the Add Web Reference command. Using the generated Web port type ensures that you'll be sending and receiving the correct XML messages to or from the Web service. Finally, you simply connect Send and Receive shapes to the Web port to model the Web service invocation.
It's also possible to invoke Web services from within orchestration expression shapes. In this case, the messages do not travel through the BizTalk messaging layer and have the low-latency characteristics of a traditional Web services call. However, heavy use of this technique can also make your orchestrations more difficult to manage after deployment.
You can handle SOAP faults returned by the service within the orchestration by using a Scope shape and an exception handling block. If you want to process the details of the SOAP fault, the exception handling block should be configured to catch exceptions of type System.Web.Services.Protocols.SoapException. Likewise, your orchestrations can return SOAP faults to callers when you've published the orchestration as a service.
The WSE 2.0 Adapter
The process of using the WSE 2.0 adapter is similar to that of using the SOAP adapter described in the previous sections. Let's focus on the differences now.
The first thing you'll notice is that the WSE 2.0 adapter comes with its own publishing wizard. When you run the wizard, it looks almost identical to the one for the SOAP adapter, until you get to the step shown in Figure 9, where it asks you to configure the security policy for the request, response, and fault messages. You can specify the token type you want to use, and even some token details within the wizard.
If you inspect the code generated by the WSE 2.0 wizard, the first thing you'll see is that the application is configured with a WSE 2.0 policy file found in the virtual directory. The wizard generates this policy based on the settings you provide. In some cases, you may need to run the WSE 2.0 configuration tool to complete the policy configuration after using the wizard, and there's no problem with doing so.
You may also notice that the generated code is no longer using the ASMX programming model, but rather the WSE 2.0 messaging API. The generated BizTalk receive location also looks similar to the SOAP version, but the WSE transport configuration dialog looks a bit different because it exposes a few more security-related configuration options.
On the send side, things are a little simpler than with the SOAP adapter. With WSE 2.0 send ports, you don't need to specify a Web service proxy class anymore. You simply specify the Web service URL and the appropriate policy configuration; the adapter takes care of producing and sending the appropriate message automatically.
When using the WSE 2.0 adapter to consume Web services within orchestrations, you no longer use the Add Web Reference command either. Instead, you use the Add Generated Items command and select the Add Adapter Metadata option. When the Add Adapter Wizard appears, select WSE from the list of registered adapters and click Next. Then the BizTalk Adapter for WSE Schema Generation Wizard appears.
The BizTalk Adapter for WSE Schema Generation Wizard asks you for the address to the WSDL definition, which it downloads, and to retrieve a list of possible services and operations. From this list, it asks you to choose a service and a set of methods. Then it asks you to configure the WSE 2.0 policy file needed to communicate with the service. You can either download the policy from a URL (if available) or you can configure it manually using the policy configuration dialog shown in Figure 9.
As with Add Web Reference, the wizard adds the schemas and port types you'll need to talk to the service. It also generates a WSE 2.0 policy file named PolicyCache.xml and saves it to the Policy directory within the WSE 2.0 adapter installation directory (see %PROGRAMFILES%\Microsoft BizTalk Server Adapter for WSE 2.0\Policy). This is where BizTalk looks for all WSE 2.0 policies. When you install the WSE 2.0 adapter, it actually updates BTSNTSvc.exe.config with a <policy> element referencing this global PolicyCache.xml file.
The WSE 2.0 adapter also introduces a variety of new message properties that provide access to WSE-specific information such as WSE.SoapAction, WSE.SoapHeaders, WSE.AddressingHeaders, WSE.ReferralHeaders, WSE.SecurityHeaders, and WSE.ClientCertificate. You can take a look at the WSE 2.0 adapter documentation for further information.
To summarize, the main new features offered by the WSE 2.0 adapter are support for message-based security policies and support for content-based routing in messaging-only solutions where you're not using orchestrations.
BizTalk Resource
The WCF Adapter
The BizTalk Server 2006 R2 release will ship with several Windows Communication Foundation adapters that will collectively provide full support for WS-* and transport-neutral messaging. There will actually be a separate adapter for many of the built-in Windows Communication Foundation bindings such as BasicHttpBinding, WSHttpBinding, NetTcpBinding, NetNamedPipeBinding, and NetMsmqBinding. There will also be a custom Windows Communication Foundation adapter that will allow you to fully configure its binding. Although this custom adapter will be the only one you really need, the other bindings are much easier to use when targeting a common messaging scenario.
The custom adapter will make it possible to do what you can do today with the SOAP and WSE adapters plus much more. It will provide full support for the WS-* stack including the various security, reliable messaging, and transaction specifications. The support for these specifications will allow you to handle more sophisticated security and routing scenarios, and you'll even be able to include the message box in Web service transactions.
Moreover, it will also offer simplified hosting, communication, and configuration options. For example, with the Windows Communication Foundation adapter, you'll be able to host non-HTTP services within BTSNtSvc.exe by simply configuring a receive location and enabling it within the BizTalk administration console (no publishing necessary).
But perhaps the most compelling feature is unification. Specifically, the Windows Communication Foundation adapter will unify the features provided by the SOAP and WSE adapters, thereby removing the need to use them. In the future, you should only need the various Windows Communication Foundation adapters when integrating with a variety of different service configurations. For more information on Windows Communication Foundation and its interoperability with ASP.NET and WSE Web services, see the Windows SDK at msdn2.microsoft.com/ms735119.aspx.
Summary
BizTalk Server 2006 provides support for today's Web services technologies through the built-in SOAP adapter and the WSE adapters discussed previously. (For more information on BizTalk, see the "BizTalk Resources" sidebar.) The SOAP adapter offers BP 1.1 communications while the WSE adapters offer more advanced WS-* support. However, the promise of transport-neutral WS-* messaging will not be fully realized until the Windows Communication Foundation adapter ships with BizTalk Server 2006, which is just around the corner. These are just the Windows Communication Foundation adapter highlights. I promise to provide in-depth coverage in a future column, closer to the first public beta release.
Send your questions and comments for Aaron to sstation@microsoft.com.
Aaron Skonnard is a cofounder of Pluralsight, a Microsoft .NET training provider. Aaron is the author of Pluralsight's Applied Web Services 2.0, Applied BizTalk Server 2006, and Introducing Windows Communication Foundation courses. Aaron has spent years developing courses, speaking at conferences, and teaching professional developers.