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).
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.
