Sunday, November 15, 2009

Using the BizTalk HTTPReceiver

During the creation of the ebMS Getting started environment i ran into problems with using IIS and the HTTPReceiver. Some problems that i had were:

- messages would not be picked up the the HTTP Receive Adapter

- messages remain in the dehydrated state

One of the most difficult things about the HTTPReceive Adapters is the dis-ability to do some hi-tech debugging…even the tool ‘DebugView’ / ‘Fiddler’ will not help when trying to find out what the problem is, TCP/IP Listeners might provide some help but the best thing you should be doing is to walk through all the MSDN steps.

Since i had some trouble finding the steps, hereby the steps for setting up the Adapter for IIS 6 en IIS7.

‘Creating the virtual directory for the HTTPReceiver’

The BizTalk HTTP Receive Adapter can be used in a http receive location configured in Internet Information Services (IIS) inside a virtual directory. Read the Microsoft guidelines for setting up an HTTP BizTalk Receive location (see reference ‘Enable the BTS ISAPI Filter’).

1.1.1 Internet information services 6

To enable the BTS ISAPI Filter perform the following actions:

1) Click Start, point to All Programs, point to Administrative Tools, and then click Internet Information Services (IIS) Manager.

2) In the IIS Manager dialog box, right-click Web Service Extensions, and then click Add a new Web service extension.

3) In the New Web Service Extension dialog box, enter BTS Http Receive ISAPI Filter in Extension Name.

4) Click Add.

5) In the Add file dialog box, browse to drive:\Program Files\Microsoft BizTalk Server <version>\HttpReceive. Select BTSHTTPReceive.dll, and then click Open.

6) In the Add file dialog box, click OK.


When you perform step 6, you may receive the following (or a similar) message: "This file is already required by HWSMessages HttpReceive." If you receive this message, click Cancel, and then click Cancel again. In this case, the BTSHTTPReceive.dll file is already required by another Web service extension, and you do not have to complete this "Add File" or "Add a new Web service extension" procedure.

7) In the New Web Service Extension dialog box, click OK.

8) In the Web Service Extension pane of IIS Manager, right-click BTS Http Receive ISAPI Filter, and then click Allow.

To create the virtual directory, perform the following actions:

Start Internet Information Services and select the Default Web Site. Right click and select New/Virtual Directory. The alias name is very important and must match the port configuration!

Type ‘ebMSReceive’ as shown in the figure below;


The HTTPReceive uses the BizTalk receive dll, this dll is located in the Program Files\BizTalk Server 2006\HttpReceive directory. Select the Web site context directory as shown in the figure below.


Select the permissions as shown in the figure below to allow access to the http location.


The properties of the virtual directory should look like the figure below


An Application Pool can contain one or more applications. This allows us to configure a level of isolation between different Web applications. In the example we have used the ‘DefaultAppPool’.

To ensure that the BizTalk HTTPReceive Adapter is able to process the messages, the identity of the application pool must be set to a user account that is a member of the ‘BizTalk Isolated Host users’. Right click the properties of the application pool under which the virtual directory is created. Go to the tab ‘Identity’ and configure the user to an account that is a member of the ‘BizTalk Isolated Host users’ as shown in the figure below;


Ensure that the correct port is used, in this screenshot port 8080 was used, to configure the website to use this port change the configuration of the appropriate web site. In this case we have chosen the Default Website, right click the default web site and select properties from the context menu. Modify the TCP port as shown in the figure below.


1.1.2 Internet information services 7

To enable the BTS ISAPI Filter perform the following actions:

1) Click Start, point to All Programs, point to Administrative Tools, and then click Internet Information Services (IIS) Manager.

2) Select the root Web server entry and in the Features View, double-click Handler Mappings and then in the Actions pane, click Add Script Map.


Configuring the script mapping at the Web server level will cause this mapping to apply to all child Web sites. If you wish to restrict the mapping to a specific Web site or virtual folder, select the target site or folder instead of the Web server.

3) In the Add Script Map dialog box, enter BtsHttpReceive.dll in the Request path field.

4) In the Executable field, click the ellipsis (…) button and browse to drive:\Program Files\Microsoft BizTalk Server <version>\HttpReceive. Select BtsHttpReceive.dll, and then click OK.

5) Enter BizTalk HTTP Receive in the Name field, and then click Request Restrictions.

6) In the Request Restrictions dialog box, select the Verbs tab and then select One of the following verbs. Enter POST as the verb.

7) On the Access tab, select Script, and then click OK.

8) Click OK and when prompted to allow the ISAPI extension, click Yes.

9) Right-click the BTSHttpReceive.dll entry, and then select Edit Feature Permissions.

10) Ensure that Read, Script and Execute are selected, and then click OK.

11) Click Features View, and then double-click ISAPI and CGI Restrictions.

12) Ensure that an entry for BTSHTTPReceive.dll exists, and that Restriction is set to Allowed.


The ISAPI and CGI Restriction entry for BTSHTTPReceive.dll is created automatically when you create the script map.

13) Create the Virtual Directory. The procedure was described previously in this section.


That it….


Charles Storm said...

Nice overview of the steps.

One tiny thingy: Might be a better idea to just create a new apppool(Like BT_Http_AppPool) with the correct identity settings (Isolated Hostinstance?) and leave the Default pool as it is. If I am not mistaken, every isolated receivehandler needs it's own application pool so you are likely to run into problems at some point. Also for HTTP receive, scripting access is not needed: read and execute will be enough: the ISAPI dll is the only thing getting called in a HTTP Receive application.

Tarun said...


would you be able to point me to the right direction of the ebMS getting started guide? Thanks!


Sander Nefs said...

You can also use the BizTalk 2013 WCF-WebHTTP adapter now

Sander (snefs)