Module 14: Using WCF Send Adapters
Time 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.
Introduction
Microsoft 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
Introduction
This 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.
Overview
With 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
Overview
A 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.
Overview
BizTalk 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
Overview
The 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 Application
1. 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 Wizard
1. 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 Map
1. 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 Binding
1. 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 doubleclick 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 Call
1. 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.
Introduction
Orchestrations 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.
Overview
After 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
Overview
When 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.
Overview
The 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.
Overview
The 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 Call
1. 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 Variables
1. 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_OutputMessag
e.
Construct and Send the Web Service Request Message
1. 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 Message
1. 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 Orchestration
1. 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.
Introduction
WCF 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.
Overview
If 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
Overview
The 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 Machine
Procedure 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 started
Procedure 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
Overview
In 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 Service
Procedure 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 Project
Procedure 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 Orchestration
Procedure 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 Orchestration
Procedure 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 Service
Procedure 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 Schema
After 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 List
1. 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 Decision
After 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 List
1. 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 Orders
Procedure 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 Application
Procedure 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
Overview
In 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 File
Procedure 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 Port
Procedure 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 Bindings
Procedure 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
Overview
In 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 Orchestration
Procedure 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.