Module 14: Using WCF Send AdaptersTime estimated: 90 minutes

Module objective:In this module, you will learn how to configure BizTalk Server 2010 send ports to send messages and call web services using the Windows Communication Foundation (WCF) send adapters.

IntroductionMicrosoft BizTalk Server 2010 includes a collection of send adapters that support integration with web services by making use of the Windows Communication Foundation (WCF).

You can use the BizTalk WCF Service Consuming Wizard to import the metadata for a web service and generate the schema and binding files that are required to integrate with it.

Lesson 1: Introduction to WCF Send Adapters

Lesson objective:

Describe how the WCF send adapters can be applied to BizTalk Server 2010 applications

IntroductionThis lesson then focuses on the Microsoft BizTalk Server 2010 WCF send adapters. It provides examples for usage, and it includes a discussion of the architecture on which the WCF send adapters are based.

WCF Send Adapter Scenarios

Describe some common scenarios for using the WCF send adapters.

OverviewWith the WCF send adapters built-in to Microsoft BizTalk Server 2010, developers can consume web services that are exposed by external systems, and they can benefit from the rich integration support offered by WCF.

Some common integration scenarios in which a developer might want to consume a WCF web service include:

1. To enable a BizTalk application to send invoice messages to an external trading partner’s supply chain system over the internet, making use of WS-Security features such as encryption and digital signatures to ensure that the message has not been compromised while en-route.

2. To enable a BizTalk application to query a warehouse database, such as Oracle 11g, to check the availability of stock to meet the requirements of a new purchase order.

3. To enable a BizTalk application to update to an internal SQL Server 2008 database, and to make a web service call to a vendor server, with full support for ACID transactions across the disparate systems.

WCF Send Adapter Architecture

Explain the architecture of a WCF send adapter

OverviewA BizTalk WCF send adapter receives messages from the BizTalk MessageBox, communicates with a service endpoint, and publishes any service response messages back in to the MessageBox.

BizTalk Server 2010 provides a number of different send WCF adapters to meet the requirements of various messaging and transport protocols. The WCF send adapter architecture is somewhat simpler than the receive adapter architecture because it acts as a WCF client, and therefore it doesn’t have to deal with the issues that arise from WCF hosting. Each WCF send adapter requires a set of configuration data as dictated by its transport, encoding and WS-* protocol support.

When a WCF send adapter is activated, it prepares the BizTalk message to be processed by a WCF channel. A WCF send adapter does not check the format of a message that it is transmitting. Consequently, you need to ensure that the application’s send ports are configured with the pipelines and maps that produce the message format required by the destination service. In lieu of schema type information, the send adapter requires you to specify the service “action” value that that should accompany the message as it is sent via the transport.

An important consideration is that the WCF send adapter is only compatible with request-reply operations even when used on one-way send ports. WCF service operations can return void but they shouldn’t be marked with IsOneWay=true if you want to call them from a WCF send port. The only exception is when you’re using NetMsmqBinding, in which case the service operations must be one-way. This is a common for developers to stumble on when they first start using the WCF send adapters, but the constraint is by design in order to support transactional consistency within the message box.

Finally, send ports can be configured to route incoming fault messages (returned by the service) through traditional message box subscription techniques. This functionality, however, is disabled by default.

Lesson 2: Consuming a Web Service

Lesson objective:

Learn how to configure a WCF send adapter to call a web service.

Introduction

Consuming WCF services enables you to add existing web services to your business process. You can aggregate several web services into a single orchestration.

You can begin to configure your application to make a web service call by using the BizTalk WCF Service Consuming Wizard. The BizTalk WCF Service Consuming Wizard creates the schema and binding files that are required to call a given web service.

Steps for Consuming a Web Service

Identify the steps required to consume a Web service from an orchestration.

OverviewBizTalk Server 2010 provides tools that simplify the procedure to implement web service calls in a BizTalk application. You can get started by performing the following four steps:

1. Add Generated Item. In your Microsoft Visual Studio BizTalk project, in Solution Explorer, right-click your project, click Add, and then click Add Generated Items. In the Add Generated Items - <Project name> dialog box, in the Templates section, select Consume WCF Service, and then click Add.

2. Complete the BizTalk WCF Service Consuming Wizard. The BizTalk WCF Service Consuming Wizard walks you through the process of importing the service’s metadata, and then it creates the schema and binding files that are required to call the web service. It also generates an orchestration containing type definitions for the web service messages and orchestration ports.

3. Build and deploy the project. In most cases, this step will be necessary, since your application will probably need to map a message to the web service call format. In the rare cases that this mapping is not necessary, you can skip this step.

4. Import generated binding file. The WCF Service Consuming Wizard creates two binding files: <ServiceName>.BindingInfo.xml and <ServiceName>_Custom.BindingInfo.xml. The first file contains the settings required to configure a send port with the standard binding WCF adapters—for example, the WCF-NetMsmq and WCF-WSHttp adapters. The second binding file contains the settings required to configure a send port with the WCF-Custom adapter.

The BizTalk WCF Service Consuming Wizard

Describe the process of completing the BizTalk WCF Service Consuming Wizard

OverviewThe BizTalk WCF Service Consuming Wizard simplifies the process of importing web service metadata and creating the corresponding BizTalk artifacts. You can launch and complete the BizTalk WCF Service Consuming Wizard by completing the following steps:

1. Add Generated Item. In your Microsoft Visual Studio BizTalk project, in Solution Explorer, right-click your project, click Add, and then click Add Generated Items. In the Add Generated Items - <Project name> dialog box, in the Templates section, select Consume WCF Service, and then click Add.

2. Complete the BizTalk WCF Service Consuming Wizard.

a. On the Welcome to the BizTalk WCF Service Consuming Wizard page, click Next.

b. On the Metadata source page, select the source of the metadata to import, and then click Next.

i. To download metadata documents from the metadata exchange endpoint of a running service, select the Metadata Exchange (MEX) endpoint option. This allows you to create a send port that acts as a client to the WCF service. To use this option, the service endpoint must

publish service metadata for retrieval using an HTTP/GET or HTTPS/GET request. The service endpoint must also allow access to the metadata with anonymous user credentials or user credentials in the form of a user name and password with the basic authentication scheme.

ii. For any other metadata documents to import, select the Metadata Files (WSDL and XSD) option to import metadata from a file system.

c. If you selected the Metadata Exchange (MEX) endpoint option on the Metadata source page, the Metadata Endpoint page appears. On the Metadata Endpoint page, specify the URL to the running service that provides metadata for download through WS-Metadata Exchange or Http-Get. To get the metadata document from the URL, click Get. If the running service requires a user credential with the basic authentication scheme, click Edit to open the BizTalk WCF Service Consuming Wizard dialog box in which you can supply user name and password to use when accessing running the service.

d. If you selected the Metadata Files (WSDL and XSD) option on the Metadata source page, the Metadata Endpoint page appears. On the Metadata Endpoint page, specify metadata files to import. Click Add to add the metadata files to import to the Metadata Files view. This opens the Add metadata files dialog box in which you can search disk locations for metadata files.

i. In the Add metadata files dialog box, select a complete set of WSDL and XSD files to use for metadata.

e. On the Import WCF Service Metadata Summary page, review your settings. You can click Back to make any changes. Then click Import to create the BizTalk artifacts and types to be used for consuming the WCF service.

f. On the Completing the BizTalk WCF Service Consuming Wizard page, click Finish. If you want to run this wizard again, select the Run this wizard again option, and then click Finish.

Demonstration: Consuming a Web Service

Learn to run the BizTalk WCF Service Consuming Wizard

Set up the Demo Application1. In Windows Explorer, navigate to C:\AllFiles\DemoCode\Module14\, and double-click

Setup.cmd.

2. Verify that the installation completed successfully, and close the command window.

Run the WCF Service Consuming Wizard1. In Windows Explorer, navigate to C:\AllFiles\DemoCode\Module14\Northwind, and

double-click Northwind.sln.

2. Right-click the Schemas project, then click Add, and then click Add Generated Items.

3. In the Add Generated Items dialog box, click Consume WCF Service, and then click Add.

4. On the Welcome page of the BizTalk WCF Service Consuming Wizard, click Next.

5. On the Metadata Source page, click Metadata Exchange (MEX) endpoint, then click Next.

6. On the Metadata Endpoint page, in the Metadata Address (URL) box, enter http://localhost:8080/FederalShipping/ShippingCharges.svc, and then click Get.

7. Wait for the ShippingCharges Service documentation page to appear, and then click Next.

8. On the Import WCF Service Metadata Summary page, click Import, and then click Finish.

9. Notice that the wizard has added five files to the Schemas project: two schema files, one orchestration, and two binding files.

One of the binding files contains the settings for a send port that is configured to call the web service with the WCF-BasicHttp adapter. The other binding file holds configuration settings for a send port configured with the WCF-Custom adapter. You can import either one.

10. Open the file named ShippingCharges_federal_shipping_com_shipping.xsd.

This schema defines the format of the request message that will be sent to the web service, and the response message that the web service will return. The other schema file defines types that are used for XML serialization.

11. Cut and Paste the ShippingCharges.odx file from the Schemas project to the Orchestrations project.

This file contains the message and port type definitions that can be used to call the web service from an orchestration.

12. Right-click the Northwind solution, and then click Build Solution.

Create a New Map1. Right-click the Maps project, point to Add, then click New Item.

2. In the Add New Item dialog box, click Map, then in the Name box, enter OrderInternalToGetShippingPriceQuote.btm, and then click Add.

3. Click Open Source Schema, and in the BizTalk Type Picker dialog box, expand Maps, Reference, Schemas and Schemas, then click Demos.Northwind.Schemas.OrderInternal.

4. Click Open Destination Schema, and in the BizTalk Type Picker dialog box, expand Maps, Reference, Schemas and Schemas, then click Demos.Northwind.Schemas.ShippingCharges_federal_shipping_com_shipping, then click GetShippingPriceQuote, and then click OK.

5. Expand the source and destination schemas, then drag a String Concatenate functoid from the toolbox to the map grid.

6. Drag a link from the source schema’s CustomerID node to the new functoid, then drag a link from the source schema’s OrderDate node to the functoid.

7. Drag a link from the functoid to the destination schema’s orderID node.

8. Drag a link from the Country node beneath the source schema’s ShipTo node, and connect it to the destination schema’s shipToCountry node.

9. Drag a link from the source schema’s OrderTotal node to the destination schema’s orderAmount node, then close the map.

Deploy the Schemas and Maps

1. Right-click the Maps project, and then click Deploy.

2. In the BizTalk Adminstration Console, expand the Demos.Northwind application, click Receive Ports, then double-click Northwind_ReceiveOrders_TwoWay.

3. Click Inbound Maps, and in the Map list, click ExternalToInternal.

Import the Generated WCF Send Port Binding1. In the BizTalk Administration Console, click Send Ports, and notice that the application

does not have any send ports configured.

2. Right-click the Demos.Northwind application, point to Import, then click Bindings, and then navigate to C:\AllFiles\DemoCode\Module14\Northwind\Shemas and double-click ShippingCharges.BindingInfo.xml.

The Demos.Northwind application now has a send port that is configured with the WCF-BasicHttp adapter.

3. Double-click the new send port, then click Configure.

Notice that the adapter is configured with the Endpoint Address taken from the WSDL document, and that the SOAP Action header mappings are defined.

4. Click Cancel, and then click Outbound Maps.

5. In the Map list, click OrderInternalToGetShippingPriceQuote.

6. Click Filters and in the Property list, select BTS.ReceivePortName.

7. Ensure that the Operator is ==, and in the Value field, enter Northwind_ReceiveOrders_TwoWay.

8. Click OK.

Test the Web Service Call1. Right-click the Demos.Northwind application, and click Start twice.

2. In Windows Explorer, navigate to C:\AllFiles\DemoCode\Module14 and double-click submitOrderGetResponse.cmd.

3. Wait for the call to complete, and verify that the response is a shipping price quote.

BizTalk accepted the order message through the Northwind_ReceiveOrders_TwoWay receive port, then made the call to the shipping web service, and returned the response to the receive port.

4. Pause the bt10d-demo virtual machine.

Lesson 3: Consuming Services from Orchestrations

Lesson objective:

Learn how to set up a web service call in the Orchestration designer.

IntroductionOrchestrations offer the ability to provide error handling and transaction compensation while they coordinate calls to web services. This lesson will show you how to use the type definitions created by the BizTalk WCF Service Consuming Wizard to make a web service call from an orchestration.

Steps for Consuming a Service from an Orchestration

Describe the steps required to implement a web service call in an orchestration.

OverviewAfter completing the BizTalk WCF Service Consuming Wizard, you will find that an orchestration and two schema files have been added to your BizTalk project.

The orchestration will be named after the service, following the naming convention of <ServiceName>Type.odx. There are no shapes in this orchestration. It simply contains a port type definition, and one or more multipart message type definitions. The recommended approach for using the type definitions is to avoid modifying the generated orchestration, and then simply reference the type definitions from other orchestrations in the BizTalk project.

One schema file will be named after the service following the naming convention of <ServiceName>Type_biztalk_WCF_<AdapterBindingType>.xsd. This schema defines the format of the web service request and response messages.

The other schema file will be named following the naming convention of <ServiceName>Type_schemas_microsoft_com_2003_10_Serialization.xsd. This schema is exported by DataContractSerializer for the types, elements, and attributes from the namespace, http://schemas.microsoft.com/2003/10/Serialization/.

Implementing the web service call in the orchestration takes four steps:

1. Create a new configured port in the orchestration. You can use the Orchestration Designer’s port wizard to create a send port of the wizard-generated port type.

2. Define message variables using new message types. Create one message variable for the web service request and, if the service will be returning a response, create a message variable for the response as well. Assign the corresponding generated multipart message type(s) to the new message variable(s).

3. Construct the web service request message. Use either a Transform shape, or a Message Assignment shape to construct the web service request message.

4. Connect send and receive shapes to the new port. Drag and drop connections between the send and receive shapes, and their corresponding operations on the send port.

Mapping Operations to Actions

Specifying the SOAP Action header

OverviewWhen you import the generated binding file, it populates the WCF.Action property in the action mapping format. To see how this property is configured, look at the Action text box on the General tab in the WCF send port transport properties dialog box in the BizTalk Administration console.

You can specify the WCF.Action property in two different ways: (1) the single action format and (2) the action mapping format.

If you set this property in the single action format, for example, http://contoso.com/Svc/Op1, then the SOAPAction header for outgoing messages is always set to the value specified in this property.

If you set this property in the action mapping format, the outgoing SOAPAction header is determined by the outbound message’s BTS.Operation context property. For example, if this property is set to the XML format shown below, and the BTS.Operation property is set to Op1, the WCF send adapter uses http://contoso.com/Svc/Op1 for the outgoing SOAPAction header.

<BtsActionMapping> <Operation Name="Op1" Action="http://contoso.com/Svc/Op1" /> <Operation Name="Op2" Action="http://contoso.com/Svc/Op2" /></BtsActionMapping>

Orchestrations set the BTS.Operation property with the operation name of the orchestration send port. The ports generated by the BizTalk WCF Consuming Wizard have operations with names that match the Name attributes in the <BtsActionMapping> element, so you do not have to explicitly set the BTS.Operation property in orchestrations when you send messages through ports that were generated by the wizard.

Formatting the Request Message

Understand how to specify the format of the body of the outbound SOAP message.

OverviewThe WCF send adapters offer two options for constructing the SOAP message from the outbound BizTalk message. You can choose to use the body of the BizTalk message as the body of the <soap:Envelope> or you can provide an explicit XML template that specifies what should go in the <soap:Body>.

Within the custom XML template, you use <bts-msg-body> to indicate where the BizTalk message body should go. The <bts-msg-body> element also has an “encoding” attribute that you can use to specify how the BizTalk message body should be encoded in the <soap:Body> element: “xml”, “base64”, “hex”, or “string”.

The following template will wrap the outbound BizTalk message within an <Invoice> element:

<Invoice xmlns="http://northwind.com/billing"> <bts-msg-body xmlns="http://www.microsoft.com/schemas/bts2007" encoding="xml"/> </Invoice>

Selecting Content from the Response Message

Understand how to specify the content to be extracted from the body of the SOAP response message.

OverviewThe WCF send adapters offer the option to configure how much of the content of a response message should be published to the MessageBox. The send adapter is responsible for creating the BizTalk message (multi-part) consisting of a message context and a single body part. You can choose which node from the incoming SOAP envelope to use in the BizTalk message body.

You can choose to use the entire SOAP envelope, the body of the SOAP envelope, or a particular element within the SOAP envelope identified by an XPath expression. The default setting is “Body”, which means the first child of the <soap:Body> element will be used in the BizTalk message body.

When you select “Envelope”, the entire <soap:Envelope> will be used within the BizTalk message body, which means the SOAP headers will be found within the BizTalk message body for future processing. However, if you are using the XmlDisassembler in your receive pipeline, it will actually strip everything from the SOAP message except for the first child of the <soap:Body> (similar to the “Body” option), thereby negating the “Envelope” behavior if that was the selected option. This behavior stems from the fact that the SOAP schema is registered with BizTalk Server as an “envelope” schema. Hence, you will want to ensure you’re using the PassThruReceive pipeline when selecting the Envelope option above.

The final option is to specify a node within the <soap:Body> to use within the BizTalk message body. You provide an XPath expression (in the “Body path expression” text box) to specify exactly which node to use. The expression is evaluated relative to the <soap:Body> element, which means an expression of “*” (short for “child:*”) identifies the children of <soap:Body>. If the expression selects more than one node, only the first selected node will be used. Also, another important point is that you can’t use XML namespace prefixes in the XPath expression. Instead, you’ll need to use full XPath expressions that test the local name and namespace values manually as illustrated in this example:

*/*[local-name()="invoice"]/*[local-name()="CustomerName"]

This XPath expression identifies the <CustomerName> element within <invoice>. Since BizTalk Server uses an optimized forward-only XPath reader to process these XPath expressions, you must ensure that your expressions only use forward axes (e.g., child, descendant, etc). You must avoid any axis that requires reverse navigation (e.g., preceding, preceding-sibling, ancestor, etc).

The node encoding controls how the node is processed after it has been selected. The available options include Xml, Base64, Hex, and String. The default is “Xml”, which means the XML representation of the selected node will be used in the message body. When the selected node doesn’t contain XML but rather some form of text, you specify what encoding should be used to extract the text. You can specify “String” if the node contains UTF-8 encoded text, or “Base64” or “Hex” if the node contains either form of encoded binary data. If the matched node doesn’t have data encoded as specified in the node encoding, an empty BizTalk message body is created by default. This general functionality is handy when you only want to publish the binary data found in a particular element to the message box.

Demo: Consuming Services from Orchestrations

Learn to configure a web service call from an orchestration

Create a Port for the Web Service Call1. Resume the bt10d-demo virtual machine.

2. In Visual Studio, open the RouteOrder.odx orchestration.

3. Right-click on the right port surface, click New Configured Port, and then click Next.

4. In the Name box, enter ShippingChargesPort, then click Next.

5. On the Select a Port Type page, click Use an existing Port Type, and in the Available Port Types tree, click Demos.Northwind.Schemas.ShippingCharges, then click Next.

6. On the Port Binding page, select I’ll be sending a request and receiving a response, then click Next, and then click Finish.

Create the Web Service Message Variables1. In Orchestration view, right-click Messages, then click New Message, and in the

Properties window, in the Identifier box, enter ShippingQuoteRequest.

2. In the Message Type list, expand Multi-part Message Types, and then click Demos.Northwind.Schemas.ShippingCharges_GetShippingPriceQuote_InputMessage.

3. Right-click Messages, then click New Message, and in the Properties window, in the Identifier box, enter ShippingQuoteResponse.

4. In the Message Type list, expand Multi-part Message Types, and then click Demos.Northwind.Schemas.ShippingCharges_GetShippingPriceQuote_OutputMessage.

Construct and Send the Web Service Request Message1. In the “Get Shipping Quote” Group shape, add a Transform shape, followed by a Send

shape, and then add a Receive shape immediately beneath the Send shape.

2. Click the Construct Message shape that automatically encloses the Transform shape, and in the Properties window, in the Messages Constructed list, click ShippingQuoteRequest.

3. Double-click the Transform shape, and click Existing Map.

4. In the Fully Qualified Map Name list, click <Select from referenced assembly …>, and then click OrderInternalToGetShippingPriceQuote, and click OK.

5. Click Source, and in the Variable Name list, click OrderMessage.

6. Click Destination, and in the Variable Name list, click ShippingQuoteRequest.parameters, then click OK.

7. Click the new Send shape, and in the Properties window, in the Message list, click ShippingQuoteRequest.

8. Click the new Receive shape, and in the Properties window, in the Message list, click ShippingQuoteResponse.

9. Connect the new send and receive shapes to the ShippingChargesPort.

Process the Response Message1. In Solution Explorer, open ShippingCharges_federal_shipping_com_shipping.xsd.

2. Right-click <Schema>, click Promote, then click Show Promotions.

3. In the Promote Properties dialog box, expand the GetShippingQuoteResponse node, click the Price node, then click Add, and then click OK.

4. On the File menu, click Save All.

5. In RouteOrder.odx, inside the Construct Billing Message shape, immediately after the Order to Billing Transform shape, add a Message Assignment shape.

6. Double-click the new Message Assignment shape and enter the following line of code, and click OK.

BillingMessage.OrderTotal = BillingMessage.OrderTotal + ShippingQuoteResponse.parameters.GetShippingPriceQuoteResult.Price;

Deploy and Test the Orchestration1. In Solution Explorer, right-click the Northwind solution, then click Rebuild Solution, and

then click Deploy Solution.

2. In the BizTalk Administration Console, right-click the Demos.Northwind application, and then click Refresh.

3. Click Send Ports, and then double-click the generated WCF send port.

4. Click Outbound Maps, and then click Remove.

5. Click Filters, then click Delete, and then click OK.

These maps and filters a no longer necessary, since these functions will now be handled by the orchestration.

6. Right-click the Demos.Northwind application, point to Import and then click Bindings.

7. Navigate to C:\AllFiles\DemoCode\Module14\Northwind, and double-click Demos.Northwind.Bindings.2.xml.

8. Right-click the Demos.Northwind application, and click Configure.

9. Click the RouteOrder orchestration, and in the Host list, click BizTalkServerApplication.

10. Configure the RouteOrder ports by binding the logical ports to the physical ports with the following mappings:

Logical Port Physical Port

OrderReceivePort Northwind_ReceiveOrders_OneWay

ShippingChargesPort WcfSendPort_ShippingCharges_..._ShippingCharges

OrderBillingSendPort Northwind_SendToBilling

OrderAuditSendPort Northwind_SendToAudit

ShippingUSASendPort Northwind_SendToShippingUSA

ShippingInternationalSendPort Northwind_SendToShippingForeign

11. Click the ShippingChargesClient orchestration, and in the Host list, click BizTalkServerApplication, then click OK.

12. Right-click the Demos.Northwind application, and then click Start twice.

13. Drop a copy of the OrderExternal.xml message from C:\AllFiles\DemoCode\Module14\ in to the C:\AllFiles\DemoCode\Northwind\Ports\FileIN folder.

14. Open the order message that appears in the C:\AllFiles\DemoCode\Northwind\Ports\Audit folder, and take note of the OrderTotal value.

15. Open the billing message that appears in the C:\AllFiles\DemoCode\Northwind\Ports\BillingDept folder, and verify that shipping charges have been included in the OrderTotal value.

16. Close all open windows, and shut down the bt10d-demos virtual machine.

Lesson 4: WCF Send Adapter Security

Lesson objective:

Understand how to configure WCF send adapter security settings.

IntroductionWCF provides numerous security options that differ across the various bindings, and you can take things even further via custom bindings. The purpose of this section is not to cover the details of the various WCF security features, but rather to show how the adapters surface those configuration settings.

Configuring WCF Send Adapter Security

Understand how to configure transport-specific WCF send adapters.

Overview

WCF provides numerous security options that differ across the various bindings, and you can take things even further via custom bindings. Since the set of security options vary across the different WCF bindings, each WCF adapter only provides configuration options that are consistent with the underlying binding.

Each of the WCF adapter configuration dialog boxes provides a “Security” tab, which surfaces the security options available for that particular adapter. The main setting you choose is the WCF security mode, either “None”, “Message”, “Transport”, or “TransportWithMessageCredential”. Not all WCF adapters support all the different security modes. For example, the WCF-NetNamedPipe adapter only supports “Transport” or “None”. Also, the WCF-NetMsmq adapter supports “Transport”, “Message”, or “Both”, which is a full combination of transport + message security.

When you select message or transport, you must specify the type of client credential to use. For message security the options include “None”, “Windows”, “Username”, and “Certificate”. When you choose anything but “Windows”, you must provide a service certificate allowing clients to

authenticate the service. For transport security the client credential options include “None”, “Basic”, “Digest”, “Ntlm”, “Windows”, and “Certificate”.

With message security, you can also specify the algorithm suite to use for message encryption and key wrapping. And you can control whether the service credential is negotiated (as with Kerberos) or provisioned at the client (as with certificates) and whether a secure session should be established. These settings control whether WS-Trust and WS-SecureConversation are used within the channel stack.

Most of the WCF receive adapters support SSO – simply select “Use Single Sign-On” to request an SSO ticket using the client credentials – check the documentation for details on which configurations do support SSO and which do not. When specifying “User name credentials” in the send port adapter configuration, you can indicate you want to use SSO for the outbound credentials.

Configuring WCF-Custom Send Adapter Security

Expose an XML schema as a Web service.

OverviewIf you are configuring a WCF-Custom adapter, you have a wider array of options for security configuration. If you are passing simple credentials, such as name and password, then you can use the Credentials tab to specify the credential values.

Otherwise, you will need to open the Behavior tab to configure the WCF behaviors that support the security features required by your application. You will need to ensure that the BizTalk Host user account has the privileges that might be required by the WCF behavior, such as privileges to access a certificate store.

Lab: Calling a Web Service from an Orchestration

Time estimated: 30 minutes

OverviewThe purpose of this lab is to introduce you to the integration between the BizTalk Server messaging components and Web services. You’ll use a built-in WCF adapter, which provides integration with Web services using Windows Communication Foundation.

First, you will add a service reference to generate the necessary artifacts for consuming a web service using the WCF adapters. Next you’ll walk through the process of consuming a web service from within an orchestration.

Start the Virtual MachineProcedure List

1. If the Server Manager window is not already open, click on the Server Manager icon located in the task bar next to the Start button.

2. Expand Roles, Hyper-V, Hyper-V Manager. The last node to appear displays the machine name. Click on it to see the list of virtual machines available.

3. Double-click the virtual machine bt10d-14 to open a Virtual Machine Connection window.

4. Click on the Action menu in the Virtual Machine Connection window and choose Start.

5. Once the virtual machine starts, press CTRL+ALT+END.

6. Log on using the user name Administrator and the password pass@word1.

7. At the Windows Activation prompt, click “Ask Me Later”, then click “OK”

Ensure that the BizTalk Services are startedProcedure List

1. In Windows Explorer, navigate to C:\AllFiles.

2. Double click startBtServices.cmd.

3. When prompted, press any key to close the command-line window.

Exercise 1: Setup a Web Service Call in the Orchestration Designer

OverviewIn the first part of this lab, you will modify an orchestration to call a web service that returns the credit rating for a given customer. You will set up a two-way send port in the orchestration to the customer ID to the web service, and receive the response.

Review the CustomerService Web ServiceProcedure List

1. In Internet Explorer, browse to http://localhost:8080/Northwind/CustomerCredit.svc

2. Verify that the CustomerCredit Service documentation page appears.

3. Click on the link at the top of the page to view the WSDL document. Notice that the service has a single operation named GetCustomerRating.

The GetCustomerRating operation is designed to check the credit status for a particular customer. The orchestration will use the returned information to make a decision about whether to approve the order.

4. Close Internet Explorer.

Add a Service Reference to the Orchestrations ProjectProcedure List

1. In Windows Explorer, navigate to C:\AllFiles\LabFiles\Lab14\Northwind, and then open Northwind.sln.

2. Double-click RouteOrder.odx in the Orchestrations project.

3. In Solution Explorer, right-click on the Orchestrations project, click Add, and then click Add Generated Items.

4. In the dialog that appears, select Consume WCF Service and click Add.

5. In the Consume WCF Service wizard, click Next until you can enter the URL for the service.

6. In the URL box, enter http://localhost:8080/Northwind/CustomerCredit.svc

7. Click Get to retrieve the service description.

8. Click Next, and then click Import.

This downloads the service's WSDL definition and generates the corresponding orchestration type definitions in the CustomerCredit.odx file

Add the Web Service Messages to the OrchestrationProcedure List

1. Make sure RouteOrder.odx is still visible in the Orchestration Designer, click on the Orchestration View tab, and then expand the Types node.

You should see CustomerCredit in the list of port types. This port type models the request/response message pair needed to invoke the service. Notice that it contains a single operation named GetCustomerRating

2. Expand the Multi-part Message Types node.

Notice it contains two new message types, one for the GetCustomerRating request message and another for the corresponding response

3. Right-click on the Messages folder (in Orchestration View), and select New Message.

4. In the Properties window, in the Identifier box, enter GetCustomerRatingRequest.

5. In the Message Type list, expand the Multi-part Message Types node and then click Northwind.Orchestrations.CustomerService_GetCustomerRating_InputMessage

6. Right-click on the Messages folder (in Orchestration View), and select New Message.

7. In the Properties window, in the Identifier box, enter GetCustomerRatingResponse.

8. In the Message Type list, expand the Multi-part Message Types node and then click OrderProcessing.Orchestrations.CustomerService_GetCustomerRating_OutputMessage

Add the Web Service Send Port to the OrchestrationProcedure List

1. Right-click on the right-side port surface.

2. Click New Configured Port, and in the Port Configuration Wizard, click Next.

3. On the Port Properties page, in the Name box, enter CheckCustomerCredit, and click Next.

4. On the Select a Port Type page, click Use an existing Port Type, and in the Available Port Types tree, click Northwind.Orchestrations.CustomerCredit.

5. Select I'll be sending a request and receiving a response for the direction of communication and click Next.

6. Click Finish.

You should now see a Port on the port surface that models the interaction with CustomerCredit.svc. Notice that the port type provided all of the operations from the service, driven by the metadata you consumed with the wizard.

Add Orchestration Shapes to Call the Web ServiceProcedure List

1. Place a Group shape just under the initial Receive shape.

2. In the Properties window, in the Name box, type Call CheckCustomerCredit.

3. Place a Construct Message shape within the Group shape.

4. In the Properties window, in the Name box, type Construct GetCustomerRatingRequest.

5. In the Messages Constructed list, click GetCustomerRatingRequest.

6. Place a Message Transform shape within the Construct Message shape, and name it CopyCustomerID.

7. Double-click on the CopyCustomerID shape to open the map configuration.

8. Rename the map to Northwind.Orchestrations.MapOrderToGetCustomerRatingRequest.

9. Configure the Source message to be the OrderMessage.

10. Configure the Destination message to be GetCustomerRatingRequest.parameters.

11. Click OK, and when the map opens, drag a link from the source CustomerID node to the destination CustomerID node, and close the map.

12. Place a Send shape within the Group under the Construct Message shape.

13. Name the new Send shape SendGetCustomerRatingRequest.

14. Set its Message to GetCustomerRatingRequest.

15. Place a Receive shape within the Group, under the Send shape.

16. Name the Receive shape ReceiveGetCustomerRatingResponse.

You're going to use the Send/Receive shapes to invoke the service by sending the required messages to the Port

17. Drag a connection from the Send shape to the port’s Request connector.

18. Drag a connection from the Receive shape to the port’s Response connector.

19. Your orchestration should look like the following screenshot:

Promote Distinguished Fields in the Web Service Response SchemaAfter calling the Web service, the orchestration can inspect the information in the response message to determine whether to approve the order for this particular customer.

Procedure List1. In Solution Explorer, double-click on

CustomerCredit_northwind_com_fbts_customers.xsd.

2. Right-click on GetCustomerRatingResponse, and click Promote, then click Show Promotions.

3. In Promote Properties dialog box, in the left pane, expand GetCustomerRatingResponse and GetCustomerRatingResult.

4. Click Rating, and then click Add.

5. Click CreditLimit, and then click Add.

6. Press OK to accept the promotions, and on the File menu, click Save All.

Now the orchestration will have access to these fields (via the GetCustomerRatingResponse message).

Add Shapes to Handle the Credit DecisionAfter calling the Web service, the orchestration can inspect the information in the response message to determine whether to approve the order for this particular customer.

Procedure List1. In Solution Explorer, double-click RouteOrder.odx.

2. Place a Decide shape just under the new Group and in the Properties window, in the Name box, enter If customer has sufficient credit.

3. Rename Rule_1 to Rule_CheckCustomerCredit.

4. Double-click on Rule_CheckCustomerCredit to open the BizTalk Expression Editor. Then enter the following expression:

GetCustomerRatingResponse.parameters.GetCustomerRatingResult.Rating > 2.5

5. Click OK to accept the expression.

When this expression evaluates to true, the left branch of the decision is followed. Otherwise the right branch is followed.

6. Drag all of the remaining shapes in the orchestration into the left branch.

Normal processing will only occur when the customer has sufficient credit.

When the customer doesn't have sufficient credit, we need to send the OrderMessage to a "Rejected" queue for human processing (we'll just use a folder on the file system).

Add a Port to Handle Rejected OrdersProcedure List

1. Right-click on the right-side port surface and select New Configured Port.

2. On the Welcome page of the Port Configuration Wizard, click Next.

3. On the Port Properties page, in the Name box, enter RejectedPort.

4. Click Create a new Port Type and in the Port Type Name box, enter PortType_Rejected, then click Next.

5. Choose I'll always be sending messages on this port and leave Specify later for the binding, then click Next.

6. Press Finish to create the new port.

7. Place a Send shape within the decision shape's Else branch.

8. In the Send shape’s Properties window, in the Name box, enter SendRejectedOrder.

9. In the Message list, click OrderMessage.

10. Connect the Send shape to the RejectedPort Request connector.

11. At this point, your orchestration should look like this screenshot:

Build and Deploy the ApplicationProcedure List

1. In Solution Explorer, right-click on the Northwind solution and click Build Solution.

2. Verify that the build completes successfully.

3. Right-click on the Northwind solution and click Deploy Solution.

4. Verify that the deployment succeeds.

Exercise 2: Configure the Orchestration and Send Ports

OverviewIn this exercise, you will configure the Northwind application using the BizTalk Administration console. The first binding file that you will import does not include the bindings for the new WCF ports. The second binding file that you import will configure the WCF send port required for the web service call. Finally, you will bind the orchestration to its ports to complete the configuration.

Import a Binding FileProcedure List

1. Open the BizTalk Administration Console and navigate to the Northwind application.

2. Right-click the Northwind application, point to Import, and click Bindings.

3. Navigate to C:\AllFiles\LabFiles\Lab14\Northwind, click Northwind.Bindings.xml, and then click Open.

4. Validate that five send ports and one receive location are created.

Import the Configuration for the WCF Send PortProcedure List

1. In the BizTalk Administration Console, right-click the Northwind application, point to Import, and click Bindings.

2. Navigate to C:\AllFiles\LabFiles\Lab14\Northwind\Orchestrations, click CustomerCredit.BindingInfo.xml, and then click Open.

This binding file contains information that was gathered when you added a service reference. It can be used to configure the send port so that it properly communicates with the listening service.

Configure the Orchestration BindingsProcedure List

1. Within the Northwind application, select the Orchestrations folder.

2. Double-click on Northwind.RouteOrder, and select the Bindings tab.

3. Bind the logical CheckCustomerCreditPort to the physical WcfSendPort_CustomerCredit_BasicHttpBinding_CustomerCredit port that was created by the import.

4. Bind the logical RejectedPort to the physical Northwind_SendToRejected port.

All of the other ports should already be bound to their physical counter parts.

5. Click OK to accept the bindings.

6. Double-click the Northwind.Orchestrations.CustomerCredit orchestration.

7. Select the Bindings tab.

8. Select BizTalkServerApplication for the host.

9. Click OK to close the dialog.

Exercise 3: Test the Orchestration

OverviewIn this exercise, you will submit a message to the orchestration that will initiate a call to the CustomerCredit web service.

Send a Message to the OrchestrationProcedure List

1. In the BizTalk Administration Console, right-click on Northwind and click Start, and in the Start ‘Northwind’ Application prompt, click Start.

2. Verify that the application starts successfully.

3. In Windows Explorer, copy C:\AllFiles\LabFiles\Lab14\OrderExternal.xml to the C:\AllFiles\LabFiles\Ports\OrderIN folder, and click paste several times to generate multiple copies of the order.

CheckCustomerService returns a random rating for each customer between 0-5. Our rule rejects orders when the rating isn't greater than 2.5. Verify that some of the orders are approved and some rejected. Approved orders will get inserted into the Northwind database orders table, while rejected orders should show up in the c:\ports\rejected folder.

4. You have successfully invoked a WCF service from within a BizTalk orchestration.

In production solutions, you will want to put the service interactions within Scope shapes so you can handle SOAP faults and deal with them appropriately.