About Consuming Web Services

You can consume (call) a Web service from your orchestration by using Web ports. To consume a Web service from an orchestration, you create a Web port and construct Web messages. You can use SOAP headers with the consumed Web service, change the URI of a consumed Web service, and dynamically set the URI for a consumed Web service. Important An orchestration is required to consume a Web service. You cannot use the SOAP send port in scenarios that only use messaging. SOAP send ports must be used with an orchestration. See Also SOAP Headers with Consumed Web Services Consuming Web Services To download updated BizTalk Server 2004 Help from www.microsoft.com, go to http://go.microsoft.com/fwlink/?linkid=20616. Copyright 2004 Microsoft Corporation. All rights reserved.

Adding Web References

Before you can add a Web port, you need to add a Web reference to your BizTalk project. A Web reference is a description of a Web service that is available to your project. When you add a Web reference to your project, BizTalk creates an orchestration Web port type, Web message types, Reference.map (map file), Reference.odx (orchestration file), <WebService>.disco (discovery file), and <WebService>.wsdl (Web Service Description Language file) to your project. If your Web Service Description Language (WSDL) file contains schema Web message types, BizTalk adds Reference.xsd to your project. A Web reference includes: y y y A Universal Resource Locator (URL) for the Web service. A WSDL file that offers information about the service such as available methods, ports, and message types. A reference map (Reference.map).

When you add a Web reference, all the Web methods for that Web service must be compatible with BizTalk Server. You cannot specify conditional attributes for specific Web methods in a Web service. Important Web method parameters of type array are not supported. You add a Web reference to your project by using the Add Web Reference dialog box. For more information about adding Web references, see Using the Project Menu.

If you are planning to export your orchestration using the Business Process Execution Language (BPEL) export process, you cannot reference a Web reference from an existing BizTalk project. When you reference a Web reference from an existing BizTalk project, the BPEL export process will auto-generate a second WSDL file and you will lose your binding information.

Creating Web Ports

Web ports are specially configured ports that you use to consume (call) Web services. A Web port can contain multiple operations that represent a mix of one-way (request only) and two-way (requestresponse) Web methods. Each operation in a Web port represents one method of a Web service. You must add a Web reference before you can create a Web port. Note You cannot delete, cut, copy, paste, or modify the configuration for Web port types and Web message types.

Adding a Web Port

You add a Web port on the port surface in Orchestration Designer. Unlike other configured ports, Web ports support a mixture of request (one-way) and request/response (two-way) operations. Each operation in the Web port represents a Web method. If the Web method contains input and output parameters, BizTalk creates a request/response operation. If the Web service contains only an input parameter, BizTalk only creates a one-way operation. To add a Web port 1. 2. 3. 4. In Orchestration Designer, with an orchestration open, right-click the port surface, and then select New Configured Port. In the Name text box, type a name for the port, and then click Next. In the Select a Port Type page, select Use an existing Port Type. In the Available Port Types box, expand the Web Port Types node and select the Web port type that corresponds to the added Web service, and then click Next.

The following figure shows the Select a Port Type dialog box.

1.

In the Port Binding page, in the Port binding drop down box, select Specify now. BizTalk automatically places the values from the referenced Web service in the URI, transport, and receive and send pipelines. BizTalk uses these values to create the send port when you deploy your BizTalk project. Important The default authentication method for the send port is anonymous access. If the Web service requires a different authentication or encryption method, you must change the configuration to supply the appropriate user credentials or Single Sockets Layer (SSL) to run Web services.

2.

Click Next, and then Finish to complete the wizard.

Port Configuration Wizard

You use the Port Configuration Wizard to create and configure a port in Orchestration Designer. A port must have a port type associated with it, and you use the wizard to select an existing port type or to create a new port type. For more information about ports and port types, see Using Ports in Orchestrations.

Starting the wizard

Orchestration Designer starts the Port Configuration Wizard automatically when you select to create a new port in any of the following ways:

y y y

Dragging a Port shape from the Toolbox onto a Port Surface on the design surface. Double-clicking the Port shape in the Toolbox. Selecting the New Configured Port command from the shortcut menu of the Ports folder in the Orchestration View window.

Additionally, you can start the wizard explicitly by: y y y Right-clicking a port (on the design surface or in the Orchestration View window) and clicking Configure Port. Running Smart Tag items whose associated actions cause a port to be created. Selecting the New Configured Port Parameter command from the shortcut menu of the Orchestration Parameters folder in the Orchestration View window.

Running the wizard

1. 2. Open the Port Configuration Wizard. Specify port information. To help you, the wizard displays several pages. After completing each page, move to the following one by clicking Next, or move to the preceding one by clicking Back. o Port Properties. Type in a name for the port. o Select a Port Type. On this page, you first select whether you want a New Port Type or an Existing Port Type. If you select Existing Port Type, you then use a tree control to choose which existing port type to assign. If you select New Port Type, you then need to type the name of the port type in the Name text box, or accept the suggested default name. You also select the port type's communication pattern (one-way or request-response) and any access restrictions to impose on the new port type. o Port Binding. On this page you specify the direction of communication, also known as the polarity, and the binding type of the port. The polarity choice you make depends in part on the communication pattern of the port type that you selected on the preceding page of the wizard, Select a Port Type. Your choices are summarized in the following table:

Port direction
Send Receive Send-Receive Receive-Send

Communication pattern
One-way One-way Request-response Request-response

Direction of communication to ch

I will always be sending messages on this p

I will always be receiving messages on this I will be sending a request and receiving a I will be receiving a request and sending a

You have a choice of four different binding types: Specify later, Specify now, Dynamic, and Direct. Each choice displays a different set of configuration options, as summarized here: Specify later. After selecting this option, you make no further configuration choices in the wizard because binding information is not determined at design time. Typically it is added by an Administrator at deployment time. Specify now. You can specify at design time a URI that defines the entity to which the port is to be bound. You also need to select from a list of transport types that includes options such as BizTalk Message Queuing, FILE, and HTTP. Finally, you select a receive pipeline and a send pipeline from a list of available pipelines. The list for each includes all pipelines in the current project plus the option of selecting a pipeline from a referenced assembly, which displays the Select Artifact Type dialog box. Dynamic. This option has similar choices to Specify now, but it is available only for a send port. You can specify a send pipeline to use. You can specify the port separately in an Expression shape so that it is assigned at run time, Direct. For direct binding, you can either select a port to connect to, to do routing based on filter expressions on incoming messages in the Message Box database, or to make it a self-correlating port. You can select a port from a drop-down list box. For more information, see Port Bindings. 3. Complete the wizard. The final page of the Port Configuration Wizard, entitled Completing the Port Wizard, displays the choices you made on the preceding pages so that you can verify them before committing the changes. If the changes are correct, click Finish. Otherwise, click Back to re-enter any information you want to change. Then move through the wizard again and click Finish when the information displayed on the final page matches the changes you want to make. Note If you are creating a new port and you click Cancel in the wizard at any time before finishing port configuration, the port is not created. If you were using the wizard to modify an existing port, canceling the wizard undoes any changes you have made. Otherwise, if you click Cancel in the wizard, the adapter is still created, but its properties are not set. You can set port properties manually in the Properties window for the port, or you can run the wizard again.

Using Ports in Orchestrations

Ports specify how your orchestration will send messages to and receive messages from other business processes. Each port has a type, a direction, and a binding, which together determine the direction of communication, the pattern of communication, the location to or from which the message is sent or received, and how the communication takes place.

Note There is a distinction between a port and a port type. A port is an instance of a port type; several different ports may have the same port type. Depending on these factors, a port may have associated with it a URI (a physical location), a transport (either file, HTTP, or BizTalk Message Queuing), a send pipeline to prepare a message for sending (for example, by assembling, encrypting, compressing, or performing some other action on it), and a receive pipeline to prepare a received message for processing (for example, by disassembling, decrypting, or decompressing it). You add ports to an orchestration in much the same way that you add controls to a Web Form or Windows Form. You can also add ports by using the Orchestration View window. To add a new port y Right-click a Port Surface or a Role Link, and then click New Port. Or In the Orchestration View window, right-click Ports and then click New Port. A DesignTip appears on ports that are not yet fully configured. Tip You can also drag ports into a Role Link. To add and configure a new port 1. From the BizTalk Orchestrations tab of the Toolbox, drag the Port shape onto a Port Surface or a Role Link. Or Right-click a Port Surface or a Role Link, and then click New Configured Port. Or In the Orchestration View window, right-click Ports and then click New Configured Port. The Port Configuration Wizard appears. 2. Follow the steps in the wizard to configure the port. For more information, see Port Configuration Wizard.

To remove a port y Right-click the port to remove, and then click Delete.

Note If you delete a port after it has been connected to a Send or Receive shape in an orchestration that has been compiled, the port operations on the shape will not be deleted, and you will receive errors when you try to compile. Connect the shape to another port and reconfigure the port operations . To configure a port by using the Port Configuration Wizard 1. 2. Right-click the port to configure, and then click Configure Port. Follow the steps in the Port Configuration Wizard to configure the port. For more information, see Port Configuration Wizard.

To configure a port manually by using the Properties window 1. 2. Select the port to configure. In the Properties window, specify the following properties:

Property
Port Type Communication Direction Communication Pattern Binding

Description

Determines the communication pattern, operations, and multi-part message types

Determines whether this orchestration is the sender or the receiver for this comm

Determines if this port is used for request-response or one-way communication. ( Type property and is read-only.)

Determines how a message gets to its destination: DirectCommunication is with another orchestration. DynamicCommunication is with an endpoint that is determined at run time. Specify laterCommunication is with an endpoint that is determined by an admi Specify nowCommunication is with an endpoint that is known at design time. The name used for this port in the orchestration.

Identifier Delivery Notification

For send ports, determines whether want to receive an acknowledgment when a m information, see "Delivery Notification" under Using the Send Shape.

3.

The remaining properties to specify are determined by the Binding property: o Direct bindingUsed when communicating directly with another orchestration.

Property
Partner Orchestration Port

Description

Determines to which port the partner orchestrations will b

Dynamic bindingUsed when communicating with an endpoint that is determined at run time.

Property
Receive Pipeline Send Pipeline
o o

Description
Determines which pipeline to use for incoming messages. Determines which pipeline to use for outgoing messages.

Specify laterUsed when communicating with an endpoint that is configured by an administrator. Specify nowUsed when communicating with an endpoint that is known at design time.

Property
Receive Pipeline Send Pipeline Transport URI
To add a port operation y

Description
Determines which pipeline to use for incoming messages. Determines which pipeline to use for outgoing messages. Determines which transport to use for sending messages. Determines where to send messages.

Right-click the port to which you want to add an operation, and then click New Operation.

To remove a port operation y Right-click the port operation to remove, and then click Delete.

This section contains: y y y y Working with Port Types Communication Pattern Communication Direction Port Bindings

Working with Port Types

A port type consists of a communication pattern, a set of operations (requests or responses), and the message types that those operations can work on. The pattern can be either one-way or request-response (two-way), and all operations defined on that port type must use the same pattern. Note that port types are direction-agnostic: direction is specified on individual ports.

The scope of a port type is defined by the Type Modifier property. A port type can be public, private, or internal. If it is public, it is visible to anyone interacting with the orchestration. If it is private, it is visible to other orchestrations within the same project and namespace. If it is internal, the port type is visible only within the project. Since a port type definition includes message types, the scope of the message type must encompass that of any port type that uses it. Note A port type can be applied to any number of ports. You can think of a port as an instance of a port type. Note A port type does not inherently have a communication direction; you set direction on individual ports. To add a request-response port type 1. In the Orchestration View window, right-click Port Types and then click New Request-response Port Type. The Port Types node expands, if collapsed, and a new request-response port type is added with one default operation. 2. 3. Specify a name for the port type. Define one or more port operations. You can name your port operations, but when you are selecting them from another project, you will see them only as "Request" and "Response." If you select a port operation from another project, verify that it has the correct message type. To add a one-way port type 1. In the Orchestration View window, right-click Port Types and then click New One-way Port Type. The Port Types node expands, if collapsed, and a new one-way port type is added with one default operation. 2. 3. Specify a name for the port type. Define one or more port operations.

To add a Web port type y Add a project reference to an assembly containing a proxy class for a Web service. For more information, see Creating Web Ports.

To remove a port type y In the Orchestration View window, right-click the port type to delete, and then click Delete.

Note If the port type is in use, deleting it will impact the configuration of any ports that are configured to use it. Note Items that appear as read-only are defined in another orchestration. To set the type modifier for a port type y In the Properties window, set the following property:

Property
Type Modifier

Description
Determines the scope of the port type: PrivateAccess to this port type is limited to the containing module. PublicAccess to this port type is not limited. InternalAccess to this port type is limited to modules within the same project.

Communication Pattern
Each port type has a communication pattern. The communication pattern determines whether one-way or two-way (request-response) transmissions can take place on ports of the given type. For more information, see Port Configuration Wizard. Note Different ports of the same type will always have the same communication pattern, but not necessarily the same communication direction.

Communication Direction
Each port has its own communication direction. The communication direction is used in combination with the communication pattern of the port's type to complete the definition of how a port can be used. The communication direction, or polarity, determines in which direction messages will be transmitted over that port. If the port's type has a one-way communication pattern, its communication direction can be either Send or Receive. If the port's type has a two-way (request-response) communication pattern, its communication direction can be Send-Receive, in which a request is sent and a response is received, or Receive-Send, in which a request is received and a response is sent.

Port Bindings
A port binding is the configuration information that determines where and how a message will be sent or received. Depending on type, bindings might refer to physical locations, pipelines, or other orchestrations.

Binding at Deployment Time

You can bind your port to a receive location or to a send port. If you do not have all of the information you need to specify a physical location, you can select the "Specify Later" port binding option in Orchestration Designer, and you only need to specify the port type that describes the port. The information about the actual location will be specified separately after the application has been deployed, either by an administrator in BizTalk Explorer or programmatically, perhaps using script.

Binding at Design Time

You can select the "Specify Now" port binding option in Orchestration Designer to specify at design time what pipeline you want to use and the location you want to communicate with. This is useful if you know in advance the source or destination of transmitted messages.

Direct Binding
Your orchestration can communicate directly with another orchestration by using direct binding. In this case, the message is processed internally by the engine, and no external transport of the message takes place. There are three flavors of direct binding. You can use direct binding to bind a send or receive action to one of the following: y y A known port on a partner orchestration. A port with routing information defined by a message subscription on incoming messages, based on a filter expression in a Receive shape.

Caution You must use a filter expression if you have an activate Receive shape receiving a message of type XmlDocument on a direct-bound port with subscription-defined routing. y A self-correlating port, in which the orchestration engine will generate a correlation token on a message that is particular to the orchestration instance, and you do not have to specify any correlation sets yourself.

Caution Direct binding is not compliant with the standards of the Business Process Engineering Language for Web Services (BPEL4WS). If you require BPEL4WS compliance, use another kind of binding. Caution When you use direct binding, you cannot exchange messages between one request-response port and two one-way ports.

Dynamic Binding
If you will not know the location of a communication until run time, you can use dynamic binding for a send port. The location might, for example, be determined from a property on an incoming message. For information about how to dynamically assign values to ports, see Assigning to Dynamic Ports.

Web Ports
If your project contains a reference to a Web service, Orchestration Designer will detect it and will make available a corresponding Web port type. You simply add a port to your orchestration and assign it an existing Web port type, and you will have a complete Web port. For more information, see Creating Web Ports. See Also

Constructing Web Messages

You construct a Web message from a Web message type. When you add a Web reference, BizTalk automatically creates Web message types, which BizTalk creates based on the Web methods from the added Web service. You add a Web message to your orchestration, setting the message type to one of the Web message types. You create individual message parts based on primitive .NET or schema types. You can construct a Web message that contains no message parts.

Web messages types

Web message types are identical to a normal message type, except you cannot modify, rename or delete them. To delete a Web message type, you must remove the Web reference from your BizTalk project. BizTalk creates one request and one response Web message type for each Web method in the added Web service. If the Web method is a one-way operation, BizTalk only creates a request Web message type. A request Web message type contains one message part for each input parameter of the Web method. A response Web message type contains one message part for the return value and one message part for each output parameter of the Web method. Depending on the Web method parameter (input or output), BizTalk creates a Web message type from a primitive .NET type or a schema type. If the Web method parameter is a primitive .NET type, the message part uses a primitive .NET type. If the Web method parameter is a schema type, BizTalk adds the schema type to the BizTalk project as a schema in Reference.xsd. The schema is the basis for the message part. You can find Reference.xsd in the Web references folder. Alternatively, you can create both primitive and schema .NET types by calling a .NET class. For more information on creating message types by using a .NET class, seeConstructing Messages in User Code.

Web messages
Web messages are the messages you use when you consume (call) a Web service. You add a Web message to an orchestration the same way that you add a regular message, except that you set the message type to one of the Web message types that BizTalk created when you added a Web reference.

Message parts
After you create the Web message, you construct the individual message parts. If your message part uses a primitive .NET type, you use a Message Assignment shape. If your message part uses a schema type, you use a Transform shape.

Adding Web Messages

You create Web message variables in the Orchestration View window. You must set the message type for the Web message to a Web message type. To add a Web message 1. 2. 3. 4. 5. With an orchestration open, on the View menu, click Other Windows, and then click Orchestration View. Right-click the Message node and then click New Message. Message_x appears under the Message node. In the Properties window, from the Message Type drop-down box, select a Web message type. Scroll through the drop-down box to the Web message type you want to use, and then click the Web messsage type to select it. The following figure shows the Orchestration View window with Message_1 selected and the Properties window, selecting a Web message type for Message_1.