BizTalk 2010 Recipes : Orchestrations - Configuring a Send Port at Runtime

4/7/2011 3:18:13 PM

1. Problem

You need to send a message from BizTalk Server but will not have all of the required information to do so until the orchestration is executing.

2. Solution

To be able to configure a send port at runtime, you create a dynamic send port within the orchestration. This recipe demonstrates how to configure the outbound dynamic send port in the Message Construct shape. The first step is to copy the contents of the inbound message to the outbound message. Listing 1 shows an example of a dynamic XML message.

Example 1. Sample Dynamic XML Message

<ns0:DynamicMessage xmlns:ns0="http://DynamicSendPortProject.xsdDynamicMessage">
  <Header>
    <FTPServer>myFTPServer.com</FTPServer>
    <FTPUserName>FTPUserName</FTPUserName>
    <FTPPassword>FTPPassword</FTPPassword>
    <Retry>3</Retry>
    <RetryInterval>5</RetryInterval>
    <FileName>FileName.xml</FileName>
  </Header>
  <Body>
    <Content>This is a test message.</Content>
  </Body>
</ns0:DynamicMessage>

Next, configure the address that BizTalk will use to communicate the message. The address uses the same format as a standard URL. In this example, we specify ftp:// to transmit the file via FTP. The FTP transport protocol requires additional properties to be specified (such as the username and password). Listing 5-2 shows an example of a construct message configuration.

The following steps outline the procedure:

Open the project containing the orchestration that will be processing the inbound message and sending that message via a dynamic send port.
Create a new orchestration send port with a port binding that is dynamic (named oprtSendDynamic in this example).
NOTE

You will be required to choose a send pipeline when configuring the send port. You can choose from any deployed send pipeline, any send pipeline referenced by your project, or any send pipeline that is part of your existing solution.
Verify that you have a message that contains all of the properties required for configuring the send port and that the properties are promoted or distinguished. Your message may look similar to the message shown earlier in Listing 5-1.
Select the Message Assignment shape from the BizTalk Orchestrations section of the toolbox, and drag it to the appropriate location within the orchestration.
Select the Message Assignment shape, and update the properties.
- Change the default name if desired.
- Add a description if desired.
- Identify the output message(s) constructed.
- Set the Report To Analyst property. Leave the property as True if you would like the shape to be visible to the Visual Business Analyst Tool.

Update the Message Assignment shape to contain the information that constructs the outbound message as well as configures the properties on the outbound dynamic send port. Your construct message may look similar to the one shown earlier in Listing 2.

Example 2. Sample Message Assignment Code

// Construct Message
msgDynamicOut = msgDynamicIn;

// Set the FTP properties based on message content.
// Reference the send port to set properties.
oprtSendDynamic(Microsoft.XLANGs.BaseTypes.Address) =
    "ftp://" + msgDynamicIn.Header.FTPServer + "/"
    + msgDynamicIn.Header.FileName;

// Set message context properties for ftp.
msgDynamicOut(FTP.UserName) = msgDynamicIn.Header.FTPUserName;
msgDynamicOut(FTP.Password) = msgDynamicIn.Header.FTPPassword;
msgDynamicOut(BTS.RetryCount) =
                   System.Convert.ToInt32(msgDynamicIn.Header.Retry);
msgDynamicOut(BTS.RetryInterval) =
                   System.Convert.ToInt32(msgDynamicIn.Header.RetryInterval);

Complete the orchestration (as shown in Figure 1).

Figure 1. Completed dynamic send port orchestration

3. How It Works

Dynamic ports allow the physical location of a physical send port (one-way or solicit-response) to be determined at runtime. The only requirement for a dynamic port is setting a pipeline at design time. The ability to specify the transport protocol and address at runtime allows for the flexibility of routing messages based solely on message content or on the output of message processing in an orchestration.

For example, implementing the SMTP send adapter to send an e-mail from BizTalk requires configuration information (SMTP server, e-mail recipient, and subject). Rather than specifying the configuration information at design time, you can use a dynamic port, which allows you to configure the information programmatically and modify it based on the message content or processing. Additionally, dynamic send ports can be set via content returned from the Business Rule Engine.

This recipe's solution demonstrated setting up a dynamic send port to send a message via FTP. The inbound message contains the message content as well as the configuration information for transmitting the message to the FTP recipient. The properties of the message are distinguished fields and are therefore easily referenced. Depending on the transport protocol being specified for the dynamic port, different properties will be required and optional.

If you attempt to set the Microsoft.XLANGs.BaseTypes.Address field with an orchestration port that is not a dynamic port in BizTalk, you will receive a compile-time error.

Table 1 shows the required and optional properties for configuring the dynamic send port communicating via FTP.

Table 1. Dynamic Send Port Properties
Name	Description
Address	A required property that contains the location and possibly the file name of the output message to create. The Address property uses URL prefixes to indicate how to transmit the message. To transmit a message via FTP, the address must begin with the prefix ftp://. If the message is being sent via FTP or FILE, a file name attribute is required as part of the address.
UserName	Specifies the FTP username. If you are specifying a different protocol in the URL, a username may not be required.
Password	Specifies the FTP password. If you are specifying a different protocol in the URL, a password may not be required.
RetryCount	An optional property that specifies how many times to retry delivery of the message, in case there is a problem transmitting the message.
RetryInterval	An optional property that specifies the retry interval in minutes.

This recipe's solution demonstrated creating a dynamic send port in the orchestration. When the orchestration is deployed, the physical send port will be created, and specific binding of the orchestration to a physical send port is already done.