HTTP Adapter for Microsoft BizTalk
Requirements: /n software Adapters for BizTalk
Introduction
The /n software Adapters for BizTalk include fully-managed .NET Adapters that seamlessly integrate with the BizTalk Messaging Pipeline. The /n software adapters extend the features of BizTalk with advanced Internet communications and secure messaging capabilities.
This guide will focus specifically on the HTTP adapter, which is used to send and receive data over HTTP(S) to and from web servers.
Contents
HTTP Send Adapter
The HTTP Send Adapter can be used to both send (POST or PUT) or receive (GET) data to and from a web server over HTTP(S). The adapter may be used in a one-way send port, or a solicit-response send port. If used in a solicit-response send port the response message will contain the reply returned by the server.
The adapter is designed to require only a minimum number of properties. For instance, to perform a GET only the URL property is required.
The HTTPVersion property species the HTTP version to use. The adapter supports both HTTP/2 and HTTP/1.1.
The HTTPMethod property indicates the HTTP method to be used. This controls whether data is sent (POST or PUT) or retrieved (GET). The following values are supported:
- DELETE
- GET (default)
- HEAD
- POST
- PUT
- TRACE
- GET (default)
Getting Data (GET)
If HTTPMethod is set to GET, the request is issued to the server specified by URL. Additional custom headers may be specified in the request by setting OtherHeaders.
The response received by the adapter will be used as the body of the submitted BizTalk message. The response message is only returned when the adapter is configured in a solicit response port (recommended). The HTTP headers of the response are available via the TransferredHeaders context property of the message.
Sending Data (POST and PUT)
The RequestParams property specifies one or more parameters to add to the POST or PUT request. This property is only applicable when the HTTPMethod property is set to POST or PUT.
To specify additional parameters set this property to one or more name value pairs. Set one pair on each line. For instance:
name1=value1
name2=value2
The adapter will format a request with parameters slightly differently depending on whether the request is made by the Send or Receive adapter.
Note: To have complete control over the data being sent set PostData instead.
When sending a POST or PUT request, the BizTalk message body will always be used as the last parameter regardless of the values specified in RequestParams. If no values are set here then a request will be made with only one parameter which is the content of the BizTalk message. Several examples and additional details follow.
Basic Example:
Setting the RequestParams to a value of:
name1=value1
name2=value2
Will result in a HTTP request like:
POST / HTTP/1.1
Host: www.nsoftware.com
Accept-Encoding: gzip, deflate
User-Agent: IPWorks HTTP Component - www.nsoftware.com
Connection: close
Content-Type: multipart/form-data boundary="boundaryV+iTxA=="
Content-Length: 335
--boundaryV+iTxA==
Content-Disposition: form-data name="name1"
Content-Type: text/plain
value1
--boundaryV+iTxA==
Content-Disposition: form-data name="name2"
Content-Type: text/plain
value2
--boundaryV+iTxA==
Content-Disposition: form-data
Content-Type: application/octet-stream
biztalk msg body
--boundaryV+iTxA==--
Notice that the default "Content-Type" for the individual request parameters is "text/plain", and the default "Content-Type" for the BizTalk message form variable is "application/octet-stream" and has no defined name attribute. See the following examples for further details.
Custom Request Parameter Content-Type Values:
When sending requests, the RequestParams may optionally include a custom Content-Type value. The syntax is:
[ContentType]name=value
For instance, setting RequestParams to a value of:
[text/html]name1=value1
[my/type]name2=value2
name3=value3
Will result in a HTTP request like:
POST / HTTP/1.1
Host: www.nsoftware.com
Accept-Encoding: gzip, deflate
User-Agent: IPWorks HTTP Component - www.nsoftware.com
Connection: close
Content-Type: multipart/form-data boundary="boundaryQDNEUw=="
Content-Length: 439
--boundaryQDNEUw==
Content-Disposition: form-data name="name1"
Content-Type: text/html
value1
--boundaryQDNEUw==
Content-Disposition: form-data name="name2"
Content-Type: my/type
value2
--boundaryQDNEUw==
Content-Disposition: form-data name="name3"
Content-Type: text/plain
value3
--boundaryQDNEUw==
Content-Disposition: form-data
Content-Type: application/octet-stream
biztalk msg body
--boundaryQDNEUw==--
Note the updated Content-Type header values for the "name1" and "name2" parameters.
Custom Content-Type and Name Values for the BizTalk Message Variable:
The default Content-Type value for the BizTalk Message form variable is "application/octet-stream" and no "name" attribute is defined in the Content-Disposition header. These can be explicitly defined in the ContentType and ContentFilename properties. These properties are applicable to the BizTalk Message form variable even if RequestParams is not set. For instance, setting:
- ContentType to "text/html"
- ContentFilename to "myfile.txt"
And leaving RequestParams unspecified (no parameters) will result in a HTTP request like:
POST / HTTP/1.1
Host: www.nsoftware.com
Accept-Encoding: gzip, deflate
User-Agent: IPWorks HTTP Component - www.nsoftware.com
Connection: close
Content-Type: multipart/form-data boundary="boundaryVAJHkA=="
Content-Length: 142
--boundaryVAJHkA==
Content-Disposition: form-data name="myfile.txt"
Content-Type: text/html
biztalk msg body
--boundaryVAJHkA==--
To maintain complete control over the POST body PostData may be set instead.
HTTP Receive Adapter
The HTTP Receive Adapter can be used to both send (POST or PUT) or receive (GET) data to and from a web server over HTTP(S). The submitted BizTalk message will contain the reply returned by the server.
The adapter is designed to require only a minimum number of properties. For instance, to perform a GET only the URL property is required.
The HTTPVersion property species the HTTP version to use. The adapter supports both HTTP/2 and HTTP/1.1.
The HTTPMethod property indicates the HTTP method to be used. This controls whether data is sent (POST or PUT) or retrieved (GET). The following values are supported:
- DELETE
- GET (default)
- HEAD
- POST
- PUT
- TRACE
- GET (default)
Getting Data (GET)
If HTTPMethod is set to GET the request is issued to the server specified by URL. Additional custom headers may be specified in the request by setting OtherHeaders.
The response received by the adapter will be used as the body of the submitted BizTalk message. The response message is only returned when the adapter is configured in a solicit response port (recommended). The HTTP headers of the response are available via the TransferredHeaders context property of the message.
Sending Data (POST and PUT)
In the receive adapter, the RequestParams are used to form the body of the POST or PUT request using the more lightweight encoding "application/x-www-form-urlencoded". For instance, setting the request parameters to:
name1=value1
name2=value2
Will result in a HTTP request like:
POST / HTTP/1.1
Host: www.nsoftware.com
Accept-Encoding: gzip, deflate
User-Agent: IPWorks HTTP Component - www.nsoftware.com
Connection: close
Content-Type: application/x-www-form-urlencoded
Content-Length: 25
name1=value1&name2=value2
To maintain complete control over the POST body PostData may be set instead.
Additional Functionality
In addition to the basic operation as discussed above the adapter supports a variety of other settings that control authentication, proxy settings, and other behavior. Some of additional features include:
- Authentication (NTLM, Kerberos, Digest, Basic) via the AuthScheme, User, and Password properties.
- Full Proxy/Firewall support using the HTTPProxy and Firewall properties.
- CustomRequestMethod provides support for custom HTTP methods.
- Specify redirect behavior with FollowRedirects.
- Add cookies to the request via Cookies.
- Configurable UserAgent.
- And many more!
This article demonstrates the use of the HTTP adapter in particular, but /n software provides a full set of adapters for connecting to various types of internet servers. The adapter properties are kept to a minimum for simplicity, but we make an effort to provide those properties that are necessary for effective control over configurations.
Please contact support@nsoftware.com with any questions.
We appreciate your feedback. If you have any questions, comments, or suggestions about this article please contact our support team at support@nsoftware.com.