BizTalk 2010 Recipes : Adapters - Configuring HTTP Receives

4/28/2011 3:35:42 PM

1. Problem

You want to configure an HTTP receive location to allow posts from a client machine to BizTalk Server. Additionally, you want to understand how to configure IIS and create a virtual directory to allow the receive location to operate correctly.

2. Solution

This solution will describe how to configure an HTTP receive location to allow documents to be posted to BizTalk. The first task is to configure IIS to allow for the redirection of documents to BizTalk. The second task is to create a virtual directory to handle specific requests, and the third step is to configure the HTTP receive. The majority of servers will have IIS 7.0 installed, and this solution describes the steps necessary for 7.0 (IIS 5.0 and 6.0 have different configuration steps—refer to the BizTalk documentation for details). After IIS has been configured, you will work through the steps needed to create a virtual directory and configure an HTTP receive port.

To configure IIS 7.0, follow these steps:

Open Internet Information Services Manager by selecting Control Panel→Administrative Tools.
Click the name of the server, and open the Handler Mappings in the IIS options (see Figure 1).

Figure 1. Handler Mappings in IIS 7.0
Under the Actions section, click Add Script Map, and set the properties as follows:
1. Set the Request path property to BTSHTTPReceive.dll.
2. Set the Executable property to the location of BTSHTTPReceive.dll (browse to BTSHTTPReceive.dll located in $\Program Files\Microsoft BizTalk Server 2010\HttpReceive).
3. Set the Name property to BTSHTTPReceive.
  NOTE
  
  If an error occurs indicating that the file is already required by another process, you don't need to continue, because the HTTP receive adapter has already been created and configured appropriately. Cancel out, and move to step 3.
4. Click the Request Restrictions button. Set the value of POST on the Verbs tab, and the value of Script on the Access tab, as show in Figures 2 and 3.
  
  Figure 2. The Verbs tab in Request Restrictions of IIS 7.0
  
  Figure 3. The Access tab in Request Restrictions of IIS 7.0
5. Click OK, and save to exit Add Script Map settings.
6. On the Add Script Map dialogue box that opens, click Yes (shown in Figure 4).

Figure 4. Add Script Map dialogue box

Once IIS is configured, the next order of business is to create a virtual directory. Each solution that requires an HTTP receive to be set up will require a separate virtual directory. BizTalk listens to this URL and, through the use of BTSHTTPReceive.dll and the HTTP receive adapter, passes the information to the BizTalk MessageBox.

The following steps demonstrate how to create a virtual directory. This directory is where clients will post HTTP requests to BizTalk.

In Internet Information Services Manager, expand the Sites folder, right-click the Default Web Site folder, and select Add Virtual Directory.
Set the following properties:
1. The Alias of the virtual directory should be what you want exposed to clients. For example, SampleHTTPReceive would be exposed to the client as http://[server]/SampleHTTPReceive.
2. Set the Physical path property to the location of the BTSHTTPReceive.dll file, generally located in $\Program Files\Microsoft BizTalk Server 2010\HttpReceive.
3. For the Connect As properties, specify the appropriate credentials. The default is Application user.
4. Validate the setting by clicking Test Connection, and click OK when the test is complete to save the settings.

At this point, IIS and the virtual directory are set up to route requests to BizTalk Server. The next steps are to create a receive port and configure a receive location for HTTP. These will be specific to each solution, so you will need to set up separate instances for different BizTalk solutions.

Using the BizTalk Administration Console, right-click the Receive Ports folder, and select New→Request Response Receive Port. Give the receive port a name, and click OK to create the port.
Right-click the Receive Locations folder, and select New→Request Response Receive Location. Select the port you created in the previous step as the container port.
In the Receive Location Properties dialog box that opens, use the following settings:
1. Set Transport Type to HTTP. This will automatically set the receive handler to BizTalkServerIsolatedHost.
2. Set Receive Pipeline to Microsoft.BizTalk.DefaultPipelines.XMLReceive.
3. Set Send Pipeline to Microsoft.BizTalk.DefaultPipelines.XMLTransmit.
Click the Address (URI) ellipsis button, and use the following settings:
1. Set the Virtual Directory plus ISAPI extension property to the virtual directory created during the IIS configuration earlier in this solution. The entry should follow this format: /SampleHTTPReceive/BTSHTTPReceive.dll.
2. The Public address property is not used by BizTalk; instead, it is used for reference purposes only. The intention is for it to be configured such that it contains the full external address that clients would use to post to the receive location. The intended format for this reference field would be http://[servername]/SampleHTTPReceive.
3. The Return Content-Type property is generally set to text/xml but can be modified depending on the format of the response expected.
4. The Loopback flag is set when the request document is intended to be the response back. Generally, this flag is set for test purposes only. For this solution, it should be unchecked.
5. The Return correlation handle on success property is for one-way ports only. It is intended to allow the creation of a unique identifier to be able to correlate the request to the document sent. Regardless of the setting, it will be ignored in this solution, because you are creating a request-response port.
6. The Use Single Sign On property is to be used in conjunction with SSO. Leave this property unchecked.
7. If checked, the Suspend Failed Requests property will, on error, suspend the document in the BizTalk MessageBox and will send an accepted notification to the client that posted the request (meaning the client will have successfully posted the document, but the document will be in a suspended state and will require administrative attention). If unchecked, any errors receiving the document will result in an immediate response back to the client indicating failure. For this solution, keep this property unchecked.

Figure 5 shows the final configuration.

Figure 5. Viewing the final HTTP transport properties

3. How It Works

You can set several configurations at the HTTP receive adapter level that will affect the way the adapter functions. You can set certain properties in the Registry that will provide for more control and optimization over large implementations that use the HTTP adapter. In many cases, however, the server and solution infrastructure may require that this default be reduced or increased. You can set this property using the following steps:

In the Registry Editor, locate the following path: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\BTSSvc.3.0.
Right-click this path, and select New→Key. Enter HttpReceive for the key's name.
Right-click the HTTPReceive key, and select New→DWORD. Name the key RequestQueueSize. Give this a decimal value from 10 to 2048.

Table 1. HTTP Receive Adapter Registry Entries
Property	Description
DisableChunkEncoding	DWORD whose default is 0. Any nonzero number turns off this setting. Indicates whether communications back to the client will be sent using chunked encoding.
HTTPReceiveThreadsPerCPU	DWORD whose default is 2. Can be set to any value from 1 to 10. Indicates the number of threads per CPU that are allocated to the HTTP receive adapter.
RequestQueueSize	DWORD whose default value is 256. Can be set anywhere from 10 to 2048. The value indicates the total number of concurrent requests that BizTalk will process simultaneously.