Problem Statement

When  we need to implement the HTTP adapter to receive messages to BizTalk, there are different steps that we need 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, we need to go through the same procedure mentioned above.

Proposed Solution

PowerShell is an important utility in the hands of the BizTalk administrator. we can use PowerShell to automate the task of creating and configuring the HTTP receive locations. The script is configurable and can be used on any BizTalk server with slight modifications.

PowerShell Script

The script is structured as a set of individual function blocks performing each of the activities mentioned above. These individual blocks are called from the parent function and thus executing the parent function creates and configures the HTTP Receive Location. The functions in the script are as follows

  1. AddHandlerMapping
  2. CreateIISApplication 
  3. CreateHTTPRecievePort
  4. CreateAndConfigureHTTPRcvLocation 

Each of these steps are mentioned in more details below.

Add Handler Mapping :  This function creates the Handler mapping for the BTSHTTPReceive location and creates an Isapi module with access permissions set to script.This function creates a handler which supports the POST operation(Different operations can be added to this handler). It has following parameters

  • $BTInstallPath : The path where the Microsoft BizTalk Server is installed
  • $HandlerName : The name with which the Handler mapping will be added to IIS

The PowerShell Script for this function is as below.

Function AddHandlerMapping ($BTInstallPath,$HandlerName)
 
{
    #The integral part of creating a HTTP Receive Location for the first time is to have the
    #ISAPI module for the BTSHTTPReceive.dll registered in the IIS
    #This Function Creates the Handler mappings for the receive location
    #If the mapping exist before hand it just skips the creation of the Handler
    #Once the Handler is created The function is completed
    # Check If the Handler Mapping Exist already
    Import-Module webadministration
    Write-Host $BTInstallPath
    Write-Host $HandlerName
    $WebHandler= Get-WebHandler $HandlerName
    Write-Host "Started Execution"
    if($WebHandler.Name -ne $null)
    {
        # WebHandler Exists
        Write-Host $WebHandler.Name
    }
    else
    {
        # Check if the Machine is 64 bit or 32 bit. Then select the Folder for the HTTP receive location
        # If the machine follows the 64 bit architecture we create a HTTP receive for the 64 bit
        # if the machine follows the 32 bit architecture we create a 32 bit HTTP receive location
 
        $MachArchitecture= (Get-WmiObject Win32_OperatingSystem).OSArchitecture
        if($MachArchitecture -eq "64-bit")
        {
            $HTTPFolderName= "HttpReceive64\BTSHTTPReceive.dll"             
        }
        else
        {
            $HTTPFolderName ="HttpReceive\BTSHTTPReceive.dll"
        }
        Write-Host $BTInstallPath\$HTTPFolderName
 
        # Create a WebHandler
        
        New-WebHandler -Name $HandlerName -Verb "POST" -Path "BtsHttpReceive.dll"  -ScriptProcessor $BTInstallPath\$HTTPFolderName -Modules "IsapiModule" -ResourceType File -RequiredAccess Script
 
        Write-Host "Mapping Created"
    }
}

CreateIISApplication: This function creates an IIS application and sets the application pool for the application. This function assumes that a valid Application Pool(Which has identity matching to the Biztalk Isolated Host Instance) is provided as input. The function accepts following inputs 

  • $BTInstallPath : The path where the Microsoft BizTalk Server is installed
  • $HandlerName : The name with which the Handler mapping will be added to IIS
  • $AppPool:  The name of the application pool which is attached to the Isolated HostInstance  for HTTP receive
  • $WebSite: The website under which the application will be hosted
  • $IISApplicationName : The name of the application

The PowerShell Script for this function is as below.

Function CreateIISApplication ($IISApplicationName, $BTInstallPath, $AppPool,$WebSite)
{
     # Once the Handler Mapping is created, an IISapplication which points to the Physical Path of the
     #BTSHTTPReceive.dll needs to be created. The application must be a assigned an app pool which is responsible
     #for processing HTTP protocol requests. The function expects that such dedicated app pool is already created
     #and configured. If the IIS application already exist, then the step is skipped.
     #Check If the application exist already.
 
     $WebApp= Get-WebApplication $IISApplicationName
      Write-Host $WebApp.Name + "is the application Name"
      $Appname=$WebApp.Name
      Write-Host $Appname
 
      if($WebApp -ne $null)
      {
        write-Host "Application Already Exist"
         
      }
      else
      {
            # Check if the Machine is 64 bit or 32 bit. Then select the Folder for the HTTP receive location
            # If the machine follows the 64 bit architecture we create a HTTP receive for the 64 bit
            #if the machine follows the 32 bit architecture we create a 32 bit HTTP receive location
         
            $MachArchitecture= (Get-WmiObject Win32_OperatingSystem).OSArchitecture
            if($MachArchitecture -eq "64-bit")
            {
                $HTTPFolderName= "HttpReceive64"             
            }
            else
            {
                $HTTPFolderName ="HttpReceive"
            }
        Import-Module webadministration
        Write-Host $BTInstallPath\$HTTPFolderName
     
        New-WebApplication -Name $IISApplicationName -PhysicalPath $BTInstallPath\$HTTPFolderName -ApplicationPool $AppPool -Site $WebSite
  
        Write-Host "Application Created"
      }
     
}

CreateHTTPRecievePortThis function actually creates and configures the BizTalk Receive Location and then enables it. The function accepts following parameters

  • $AppName: The name of the BizTalk Application where the Receive Location Needs to be created
  • $ReceivePortName: The name of the send port
  • $ReceiveLocName: The name of the HTTP Receive location
  • $ReceiveHandler: The Receive Handler which will be bound to the receive location
  • $DBServerName: Name of BizTalk database server
  • $MgmtDbName : name of the Management database
  • $IISAppName: Name of the IIS application created in step 2

The PowerShell Script for this function is as below.

Function CreateHTTPRecievePort ($AppName , $ReceivePortName,$ReceiveLocName, $RecieveHandler,$DBServerName , $MgmtDbName, $IISAppName)
{
 
        #This Step Assumes that the Receivehandler is added To The HTTP Adapter
        #If the receive Handler is not added then the configuration will fail
        #In this step,if error occurs the transaction will not be committed to the BizTalk Management Database
        #and receive location will not be created.
        #The name of the Receive Port, Location are all read from the config file in the parent function
        #The pipelines assigned are default BizTalk Pipelines. In case user wishes to implement the custom pipelines
        #Same can be added.
        [System.Reflection.Assembly]::LoadFile("C:\Windows\assembly\GAC_MSIL\Microsoft.BizTalk.ExplorerOM\3.0.1.0__31bf3856ad364e35\Microsoft.BizTalk.ExplorerOM.dll")
        $bto=New-Object  Microsoft.BizTalk.ExplorerOM.BtsCatalogExplorer
        $bto.ConnectionString = "Integrated Security=SSPI;database=$MgmtDbName;server=$DBServerName"
        $appColl=$bto.Applications
        foreach($app in $appColl)
        {
           if($app.Name -eq $AppName )
           {
            $rp= $app.AddNewReceivePort($true)
            $rp.Name=$ReceivePortName
            $rp.SendPipeline = $bto.Pipelines["Microsoft.BizTalk.DefaultPipelines.PassThruTransmit"]
            $rl= $rp.AddNewReceiveLocation()
            $rl.Name= $ReceiveLocName
            $rl.TransportType = $bto.ProtocolTypes["HTTP"]
             
            #The Transport type data mentioned below  implies that all settings with 0 
                 #values will not be used in the communication
            #In case user wants to enable any one or all of them then assign -1 
                 #as the value to that particular field
 
            $rl.TransportTypeData= "<CustomProps><UseSSO vt='11'>0</UseSSO><ReturnCorrelationHandle vt='11'>0</ReturnCorrelationHandle><ResponseContentType vt='8'>application/xml</ResponseContentType><LoopBack vt='11'>0</LoopBack></CustomProps>"
            $rl.Address="/$IISAppName/BTSHTTPReceive.dll"
            $rl.PublicAddress ="http://localhost/$IISAppName"
            $rl.ReceivePipeline =$bto.Pipelines["Microsoft.BizTalk.DefaultPipelines.XMLReceive"]
              
            #Check if the Receive Handler is present for the HTTP adapter, if yes then go ahead
            #Else the changes will be rolled back at the end of function
 
            foreach($rlHandler in  $bto.ReceiveHandlers)
            {
                if($rlHandler.TransportType.name -eq  "HTTP")
                {
                    $rl.ReceiveHandler=$rlHandler
                }
            }
             
            #This steps commits the changes to the BizTalk database. If there is any errror in the above execution
            #then the changes will not be committed to the database.
            #After the changes are committed to the database, then the BizTalk Catalog explorer is cleared.   
                $bto.SaveChanges()
                $bto.Refresh()
             
           }
        }
}

CreateAndConfigureHTTPRcvLocation: This is the parent application which invokes the above three functions in the order mentioned above. This function accepts the path of the config file which stores the information about the parameters passed to the individual functions.

The Config File looks like below

<ConfigurationFile>
  <BTINstallPath>Path Where Biztalk is installed</BTINstallPath>
  <ISAPIHandlerName>name of the IIS handler</ISAPIHandlerName>
  <AppPoolName>App pool Name</AppPoolName>
  <WebsiteName>Default Web Site</WebsiteName>
  <IISAppName>HTTPCommon</IISAppName>
  <BizTalkAppNAme>BizTalk Application 1</BizTalkAppNAme>
  <RPName>Rp_HTTPReceive</RPName>
  <RLOcName>RL_HTTPReceive</RLOcName>
  <RcvHandler>Temp</RcvHandler>
  <DbServerName>localhost</DbServerName>
  <MgmtDbName>BizTalkMgmtDb</MgmtDbName>
</ConfigurationFile>

The PowerShell Script for the function is as below.

Function CreateAndConfigureHTTPRcvLocation
{
    param
    (
        #reads the path where the configuration file is stored
        [Parameter(Position=0,Mandatory=$true,HelpMessage="Path of the SConfig file must be provided...")]
        [Alias("PathofConfigfile")]
        [string]$ConfigPath
         
    )  
     
    if(Test-Path $ConfigPath)
    {
        [xml]$Config= get-Content "$ConfigPath/Config.xml"
      
        #Now We read the details in the configuration File.
        # Read where the Biztalk server is installed so that the HTTPReceive dll can be picked up
        $BTInstallPath= $Config.ConfigurationFile.BTINstallPath
 
        #Read the name of the Handler which will be created as  apart of the Process.
        $HandlerName= $Config.ConfigurationFile.ISAPIHandlerName
 
        #Read the Name of the IIS app we will create as the part of the process
        $IISApplicationName= $Config.ConfigurationFile.IISAppName
 
        #Read the Name of the website where you want to create this application
        $WebSite= $Config.ConfigurationFile.WebsiteName
 
        #Read the Name of the app pool which will be assigned to the application
        #Note: Makes sure that the application pool for the HTTP protocol receive location 
           #should be different and dedicated
        # and other receives using protocol like SOAP and basicHttp should not be used
 
        $AppPool = $Config.ConfigurationFile.AppPoolName
 
        #Read the Nameof the BizTalk application where the receive location will be created.
 
        $AppName= $Config.ConfigurationFile.BizTalkAppNAme
 
        #Read the Name of the receive Port under which the actual;receive Location will be created.
 
        $ReceivePortName= $Config.ConfigurationFile.RPName
 
        #Read the Name of the receive location which will be created.
 
        $ReceiveLocName= $Config.ConfigurationFile.RLOcName
 
        #Read the Name of the Receive Handler which will be mapped to the receive location
        #Note- Make sure that the receive handler is added to the HTTP adapter in the Admin Console
 
        $RecieveHandler = $Config.ConfigurationFile.RcvHandler
 
        #Read the Nameof the DatabServer and the Name of the BizTalk Management Db
        $DbServerName= $Config.ConfigurationFile.DbServerName
        $MgmtDbName= $Config.ConfigurationFile.MgmtDbName
         
             # The process for the creation of the receive Location is
        #1. Create a Handler Mapping for the BTSHTTPReceive.dll with the IsapiModule and 
           #necessary execution permissions
        #2. Create an IIS application which will accept the request from the external world for the HTTP
        #3. Create the HTTP receive Location using the BTS ExplorerOM namespace
        # There are some thing that need to be noted
        #1.There should be a separate application pool that should be created for the HTTP receive
        #  as the creation of app pool requires setting of the user identity, 
           #the part has been skipped and it is assumed that
        #  app pool is already created and properly Configured
        #2. The receive Handler is present in the HTTP adapter
          
         AddHandlerMapping -BTInstallPath $BTInstallPath -HandlerName $HandlerName
         CreateIISApplication -IISApplicationName $IISApplicationName -AppPool $AppPool -BTInstallPath $BTInstallPath -WebSite $WebSite
         CreateHTTPRecievePort -AppName $AppName -ReceivePortName $ReceivePortName -ReceiveLocName $ReceiveLocName -RecieveHandler $RecieveHandler `
         -DBServerName $DbServerName -MgmtDbName $MgmtDbName -IISAppName $IISApplicationName
          
    }
 
    else
    {
        Write-Host "The provided File Path Does not exist!!!"
    }
     
}

Once this script is executed, The Receive Location will be created with all the necessary prerequisites steps taken care of.

See Also

Another important place to find a huge amount of BizTalk related articles is the TechNet Wiki itself. The best entry point is BizTalk Server Resources on the TechNet Wiki

References

For manual configuration refer to the following links

Download

 The sample can be found in the TechNet gallery at following link
PowerShell Script To Create and Configure HTTP Receive Location