1. Problem
You want to programmatically configure an HTTP send port from an orchestration using a Message Assignment shape.
2. Solution
This solution will
describe how to post a document using a send port configured with
authentication to post via a secure HTTPS site. The following solution
assumes you have a BizTalk project open in Visual Studio with a BizTalk
orchestration and a schema that can be used to create an orchestration
message. Here are the steps to follow:
Create a new orchestration message by right-clicking the Messages
folder in the Orchestration View window and selecting New Message.
Enter msgSend for the message name, and give it a message type (this
should be the schema of the document that will be sent via HTTP).
Setting
HTTP properties requires constructing the message that will be sent.
Drop a Message Assignment shape in the orchestration. This will create a
Construct Message shape that should be configured such that the Message Constructed property is set to the message created in step 1.
Double-click the Message Assignment shape, and enter the property settings as shown in Listing 1. Figure 1 shows the properties available in the Message Assignment Editor. Click OK when complete.
Example 1. Message Assignment Code
// Set HTTP send port properties; the username and password can be
// configurable by using the config file or BizTalk rules engine
// rather than hard-coded values
msgSend(HTTP.AuthenticationScheme) = "Basic";
msgSend(HTTP.Username) = "User"; // can be loaded from config file, also
msgSend(HTTP.Password) = "Password"; // can be loaded from config file
// configure additional parameters as appropriate
|
NOTE
When selecting properties from the drop-down list in the Message
Assignment shape, you'll see all the properties you can set. Specific to
HTTP, both the Send and Receive properties are listed. A complete list of Send properties appears in Table 1.
Drop a Send shape on the orchestration surface. Set the Message property to the message created in step 1.
Right-click
the port surface, and select New Configured Port. On the Port Binding
page, set the parameters as indicated in the following substeps and
shown in Figure 2:
Set "Port direction of communication" to "I'll always be sending messages on this port."
Set "Port binding" to "Specify now".
Set the pipeline to the default XMLTransmit pipeline.
Table 1
describes the details of each of the port properties you can set for
the HTTP port via code in an Expression shape of an orchestration. These
are the same parameters you set when configuring an HTTP send port in
the BizTalk Explorer.
Table 1. HTTP Port Parameters
| Property | Type |
|---|
| AffiliateApplicationName | When
using SSO, you can specify an affiliate application. You enter the name
of the application as a string. When using this property, the UseSSO property must be set to True. |
| AuthenticationScheme | You can set four types of authentication: Anonymous, Basic, Digest, and Kerberos. When using Basic and Digest, you should set the Password and Username properties. |
| Certificate | If
you are using a certificate (for HTTPS), you should enter the
thumbprint of the certificate as a string here. Thumbprints are
typically found in the properties of the certificate and are 40-digit
hexadecimal values. |
| ContentType | The default value is Text/XML. This is a string. |
| EnableChunkedEncoding | Boolean value that indicates whether to send the document in chunked packets of information. |
| HttpCookie | Properties available if using cookies. |
| InboundHttpHeaders | The HTTP headers may be available on inbound HTTP messages. |
| MaxRedirects | The HTTP adapter can be set to allow for 0 to 10 redirects. |
| Password | Password used when posting to a secure site. AuthenticationScheme should be set to Basic or Digest. |
| ProxyName | If a proxy server is used, enter the name of the server as a string. |
| ProxyPassword | Password for proxy server. The UseProxy property should be set to True, and UseHandlerProxySettings should be set to False. |
| ProxyPort | Port for proxy server. An example would be 80. |
| ProxyUsername | Username for proxy server. The UseProxy property should be set to True, and UseHandlerProxySettings should be set to False. |
| RequestTimeout | By
default, the timeout will be managed based on the size of the document.
This can be overridden with a specific timeout value entered as a
numeric entry (in seconds). |
| ResponseStatusCode | Properties available regarding the status code of the response. |
| SubmissionHandle | Submission handle, if available. |
| UseHandlerProxySettings | If set to True, other proxy properties that may be set are overridden, and the send port will use the proxy handler configuration. |
| UseProxy | Boolean value. Use other proxy properties in conjunction with this value. |
| UserHttpHeaders | HTTP headers, if available. |
| Username | Username used when posting to a secure site. AuthenticationScheme should be set to Basic or Digest. |
| UseSSO | A Boolean value indicating whether to use the SSO server. Use the AffiliateApplicationName property in conjunction with this. |
3. How It Works
When sending documents via a send
port, exceptions can occur—perhaps the HTTP server is unavailable or
the URL is incorrect. In such cases, it is often useful to be able to
catch the exception immediately in the orchestration, especially when
specific error handling routines need to occur.
By default, send ports are set
up to automatically retry in case of failure. This means an
orchestration will call the send port and then continue processing
asynchronously while the adapter manages the transmission of the
document. If an exception is thrown, it is handled by the adapter and is
never bubbled up to the orchestration. With the adapter operating
asynchronously from the orchestration, exceptions that are thrown can
result in lost messages and unexpected error messages.
To force the adapter to
execute synchronously with the orchestration moving on to the next steps
only when a message has been posted successfully by the adapter, you
should set the Delivery Notification property on the send port to Transmitted, as shown in Figure 3.
