Problem Statement


When a BizTalk application need to implement the HTTP adapter to receive messages to BizTalk, there are different steps that the developer/administrator needs to take care for the adapter to function properly. 

  1. Setting up the handling Mapping for the BizTalk HTTP receive location
  2. Creating an IIS application and binding it to correct app pool
  3. Creating receive port and receive locations
  4. Configure the receive location to accept the messages
The process is long and missing a step can result into the rework. If New receive locations are to be configured to work with the HTTP protocol, the developer/administrator needs to go through the same procedure mentioned above. 


Possible Solutions 



There are multiple ways to create the HTTP receive location, few of them are 
  1. Manually Creating the Receive Location by following all the four steps mentioned above.
  2. Using PowerShell to automate the task for the four steps mentioned above
  3. Using BTDF to create the receive location and mappings.
In case of Way 1, the documentation in the references section titled "How to Configure an HTTP Receive Location" can be used.
In case of Way 2, following technet wiki article can be followed to set up the PowerShell Script.
BizTalk: PowerShell Script To Create and Configure HTTP Receive Location 

This article aims to discuss the way 3:  To set up the HTTP Receive location of a BizTalk application using BTDF. 



Using BTDF to Create  HTTP Receive Location



Introduction To BTDF 



BTDF is an open source deployment framework used for deploying BizTalk applications on local dev boxes as well as different environments. It provides many facilities that can be used to club together the task that require to be performed pre and post deployment of the BizTalk deployment e.g restarting of the concerned Host Instances, IIS reset etc. Another advantage of BTDF is that it is very flexible and can be configured to do a lot of tasks before, during and after the deployment of BizTalk application. All these tasks can be packaged up as a single msi file and can be installed on the target environment. It also provides facility to define the variables related to different environments in a spreadsheet which simplifies the task of manually maintaining the binding files for the BizTalk application for Multiple environment. These are some of the features of BTDF. BTDF has proven to be a very reliable tool for creating build msi for BizTalk. It is a necessary weapon in the arsenal of a professional working on BizTalk platform. 

This article uses the latest version 5.7 that is released. To learn more about the installation of the btdf and step by step guide for configuring the BTDF, refer following link. The link discusses the steps taken for BizTalk 2016 and Visual Studio 2015 , but same can be followed for other versions of BizTalk.

Step by Step Guide For Installation and Configuration of BTDF for BizTalk 2016 and Visual Studio 2015

Following steps are required to set up the HTTP Receive Location for a BizTalk app using BTDF.
  1. Setting Up Initial Properties 
  2. Create Application Pool to Process the Requests received 
  3. Create the IIS application
  4. Configure the Receive Location in the Port Bindings Master.

Setting Up Initial Properties



In order to create the IIS application and reset the application pool after the deployment , following properties need to be set under the <PropertyGroup> record in the btdf project file.

<IncludeVirtualDirectories>True</IncludeVirtualDirectories>
<SkipIISReset>False</SkipIISReset>

In case if the IISReset is not required, the the <SkipIISReset> property can be set to True 

Create Application Pool



In order to create the application pool to process the request received at IIS, an <ItemGroup> has to be added to the  btdf project file. BTDF gives the flexibility to the developers to deploy their application from Visual Studio also and by creating a build server msi. So two different setting need to be made based upon the method of deployment. The main difference between the two settings is the way they read the user ID and password for the identity to be set up for the application pool. In case of the Visual studio deployment the user Id and password can be configured in the item group itself while in case of server deploy using msi it can be asked from the administrator installing the msi.

Deploying from Visual Studio.


Following are the properties that need to be set up in the item group.

<ItemGroup>
       <IISAppPool Include="BTSHTTPReceiveAppPool" Condition="'$(Configuration)' != 'Server'">
       <DeployAction>Create</DeployAction>
       <DotNetFrameworkVersion>v4.0</DotNetFrameworkVersion>
       <IdentityType>SpecificUser</IdentityType>
       <UserName>hostname\localUserAddedToIsolatedHostUsersGroup</UserName>
       <Password>password</Password>
       <PipelineMode>Integrated</PipelineMode>
       <UndeployAction>Delete</UndeployAction>
     </IISAppPool>
   </ItemGroup>

Deploying on Server using MSI



Following are the properties that need to be set up in the item group.

<ItemGroup>
     <IISAppPool Include="BTSHTTPReceiveAppPool" Condition="'$(Configuration)' == 'Server'">
       <DeployAction>Create</DeployAction>
       <DotNetFrameworkVersion>v4.0</DotNetFrameworkVersion>
       <IdentityType>SpecificUser</IdentityType>
       <UserName>$(IsolatedHostUserName)</UserName>
       <Password>$(IsolatedHostUserPassword)</Password>
       <PipelineMode>Integrated</PipelineMode>
       <UndeployAction>Delete</UndeployAction>
     </IISAppPool>
</ItemGroup>

The $(IsolatedHostUserName) and $(IsolatedHostUserPassword) are the environment variables that need to be configured in the InstallWizard.xml file . A typical InstallWizard.xml file would look like below.

<?xml version="1.0" encoding="utf-8" ?>
<!--
    Deployment Framework for BizTalk
    Copyright (C) 2008-14 Thomas F. Abraham, 2004-08 Scott Colestock
-->
<!-- Each SetEnvUIConfigItem element defines a single page in the wizard that appears during a server deployment. -->
<!-- The EnvironmentVarName element specifies the name of an environment variable that will contain the value of the -->
<!-- user's selection. Each environment variable automatically becomes an MSBuild property that you may reference in -->
<!-- your .btdfproj file. -->
   <DialogCaption>ConfigureHTTPReceiveUsingBTDF</DialogCaption>
  <SetEnvUIConfigItem>
    <PromptText>Select the XML file that contains configuration information specific to this environment:</PromptText>
    <PromptValue></PromptValue>
    <ValueType>FileSelect</ValueType>
    <EnvironmentVarName>ENV_SETTINGS</EnvironmentVarName>
  </SetEnvUIConfigItem>
  <SetEnvUIConfigItem>
    <PromptText>Enter the domain qualified username for the IIS app pool</PromptText>
    <PromptValue></PromptValue>
    <ValueType>Text</ValueType>
    <EnvironmentVarName>IsolatedHostUserName</EnvironmentVarName>
  </SetEnvUIConfigItem>
  <SetEnvUIConfigItem>
    <PromptText>Enter the Password for the Username entered in previous step</PromptText>
    <PromptValue></PromptValue>
    <ValueType>Password</ValueType>
    <EnvironmentVarName>IsolatedHostUserPassword</EnvironmentVarName>
  </SetEnvUIConfigItem>
 
  <SetEnvUIConfigItem>
      <PromptText>Is this the LAST server in the BizTalk Group you are deploying to?
      
If so, BizTalk assemblies will be deployed to the BizTalk Management Database.</PromptText>
      <Caption>This is the LAST server in the BizTalk Group</Caption>
      <PromptValue>true</PromptValue>
      <ValueType>Checkbox</ValueType>
      <EnvironmentVarName>BT_DEPLOY_MGMT_DB</EnvironmentVarName>
   </SetEnvUIConfigItem>
</SetEnvUIConfig>

Creating IIS application



In order to create an IIS application to house the BTSHTTPReceive.dll,  following<ItemGroup> needs to be added to the btdf project file.

<ItemGroup>
  <IISApp Include="BTSHTTPReceiveDemo" >
    <AppPoolName>BTSHTTPReceiveAppPool</AppPoolName>
    <DeployAction>Create</DeployAction>
    <SiteName>Default Web Site</SiteName>
    <PhysicalPath>C:\Program Files (x86)\Microsoft BizTalk Server 2016\HttpReceive64</PhysicalPath>
    <VirtualPath>/BTSHTTPReceiveDemo</VirtualPath>
    <IsapiFileName>BTSHTTPReceive.dll</IsapiFileName>
    <UndeployAction>Delete</UndeployAction>
  </IISApp
</ItemGroup>

Above settings will ensure that the IIS app will be created while deployment and will be deleted when doing an undeployment.
The <IsapiFileName> creates the handler mapping required to process the request received on the IIS app.

Configure the Receive Location in the Port Bindings Master



A typical entry for a receive location will look like following.

<ReceivePort Name="HTTPReceivePort" IsTwoWay="true" BindingOption="1" AnalyticsEnabled="false">
      <Description xsi:nil="true" />
      <ReceiveLocations>
        <ReceiveLocation Name="HTTPReceiveLocation">
          <Description xsi:nil="true" />
          <Address>/${HTTPReceiveIISAppName}/BTSHTTPReceive.dll</Address>
          <PublicAddress>http://localhost//${HTTPReceiveIISAppName}</PublicAddress>
          <Primary>true</Primary>
          <ReceiveLocationServiceWindowEnabled>false</ReceiveLocationServiceWindowEnabled>
          <ReceiveLocationFromTime>2017-11-21T00:00:00</ReceiveLocationFromTime>
          <ReceiveLocationToTime>2017-11-21T23:59:59</ReceiveLocationToTime>
          <ReceiveLocationStartDateEnabled>false</ReceiveLocationStartDateEnabled>
          <ReceiveLocationStartDate>2017-11-21T00:00:00</ReceiveLocationStartDate>
          <ReceiveLocationEndDateEnabled>false</ReceiveLocationEndDateEnabled>
          <ReceiveLocationEndDate>2017-11-22T00:00:00</ReceiveLocationEndDate>
          <ReceiveLocationTransportType Name="HTTP" Capabilities="387" ConfigurationClsid="1c56d157-0553-4345-8a1f-55d2d1a3ffb6" />
          <ReceiveLocationTransportTypeData><CustomProps><SuspendFailedRequests vt="11">0</SuspendFailedRequests><LoopBack vt="11">0</LoopBack><UseSSO vt="11">0</UseSSO><ResponseContentType vt="8">application/xml</ResponseContentType><ReturnCorrelationHandle vt="11">-1</ReturnCorrelationHandle></CustomProps></ReceiveLocationTransportTypeData>
          <ReceivePipeline Name="Microsoft.BizTalk.DefaultPipelines.XMLReceive" FullyQualifiedName="Microsoft.BizTalk.DefaultPipelines.XMLReceive, Microsoft.BizTalk.DefaultPipelines, Version=3.0.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" Type="1" TrackingOption="None" Description="" />
          <ReceivePipelineData xsi:nil="true" />
          <SendPipeline Name="Microsoft.BizTalk.DefaultPipelines.PassThruTransmit" FullyQualifiedName="Microsoft.BizTalk.DefaultPipelines.PassThruTransmit, Microsoft.BizTalk.DefaultPipelines, Version=3.0.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" Type="2" TrackingOption="None" Description="" />
          <SendPipelineData xsi:nil="true" />
          <Enable>true</Enable>
          <ReceiveHandler Name="${IsolatedHostInstance}" HostTrusted="false">
            <TransportType Name="HTTP" Capabilities="387" ConfigurationClsid="1c56d157-0553-4345-8a1f-55d2d1a3ffb6" />
          </ReceiveHandler>
          <ScheduleRecurrenceType>None</ScheduleRecurrenceType>
          <ScheduleRecurenceFrom>2017-11-21T00:00:00</ScheduleRecurenceFrom>
          <ScheduleRecurrenceInterval>1</ScheduleRecurrenceInterval>
          <ScheduleDaysOfWeek>None</ScheduleDaysOfWeek>
          <ScheduleMonths>None</ScheduleMonths>
          <ScheduleMonthDays>None</ScheduleMonthDays>
          <ScheduleOrdinalDayOfWeek>None</ScheduleOrdinalDayOfWeek>
          <ScheduleOrdinalType>None</ScheduleOrdinalType>
          <ScheduleIsOrdinal>false</ScheduleIsOrdinal>
          <ScheduleLastDayOfMonth>false</ScheduleLastDayOfMonth>
          <ScheduleAutoAdjustToDaylightSaving>true</ScheduleAutoAdjustToDaylightSaving>
          <ScheduleTimeZone>UTC</ScheduleTimeZone>
        </ReceiveLocation>
      </ReceiveLocations>
      <SendPipelineData xsi:nil="true" />
      <Authentication>0</Authentication>
      <Tracking>0</Tracking>
      <Transforms />
      <OutboundTransforms />
      <RouteFailedMessage>false</RouteFailedMessage>
      <ApplicationName>ConfigureHTTPReceiveUsingBTDF</ApplicationName>
    </ReceivePort>

The variables ${HTTPReceiveIISAppName} and ${IsolatedHostInstance} need to be stored in the Environment SettingsFileGenerator file.



Verification Of Deployment



Following screenshots depict the artifacts created post the deployment.

  1.  Application Pool




  2. IIS Application





  3. BizTalk Receive Location 

      



  4. Sample Test Run done from SOAP UI 





Conclusion


As clear from the creation of the app pool, IIS app and BizTalk Receive Location along with a successful test from the SOAP UI, it can be concluded that BTDF can be used to simplify the creation and deployment of the HTTP Receive Location.



Sample Code



The sample code to implement this concept in BizTalk 2016 can be found at following link of technet gallery. The deployment project can be copied and edited for other versions of BizTalk as required. 

Sample Code for Creating and Deploying BizTalk HTTP Receive Locations using BTDF 



See Also




References


Following articles were referred while writing this article