Share via

BizTalk Server DevOps: Configuring Receive and Send Handlers in BizTalk Ports with PowerShell

  • Article

Introduction

An adapter handler is an instance of a BizTalk host in which the adapter code runs. When you specify a send or receive handler for an adapter you are specifying which host instance the adapter code will run in the context of. An adapter handler is responsible for executing the adapter and contains properties for a specific instance of an adapter.

The default BizTalk Server configuration will only create one in-process host, "BizTalkServerApplication", that will be associated as a receive and send adapter handler for all of the installed adapters, with the exception of HTTP, SOAP, WCF-BasicHttp, WCF-WSHttp and WCF-CustomIsolated  adapter receive handlers that can only be running in an isolated host.

But, for purposes of load balancing, to provide process isolation for a particular adapter handler or to providing High Availability for BizTalk Hosts and according to  best practices we should strategically create dedicated logical hosts to run specific areas of functionality such as tracking, receiving messages, sending messages and processing orchestrations.  You can learn more and perform this type of BizTalk Host High Availability configuration using PowerShell scripts in the following TechNet article: BizTalk Server Best Practices: Create and Configure BizTalk Server Host and Host Instances.

However, if we create different or dedicated host and host instances for each functionality (receive, send, process and tracking) we will also need to associate the "new" receive and send host instances as a handler of each adapter (receive or send handler). You can accomplish that using the a BizTalk Server Administration Console by:

  • Expand BizTalk Server Administration, expand BizTalk Group, expand Platform Settings, and then expand Adapters.
  • In the expanded adapter list, right-click the adapter for which you would like to add a send or receive handler, point to New, and then click Send Handler to create a send handler or click Receive Handler to create a receive handler.
  • In the <host name> Properties dialog box, on the General tab, in the Host Name list, select the host with which the adapter handler will be associated.
  • If you are creating an adapter send handler, select the option to Make this the default handler if you would like for this to be the default send handler for this adapter.
  • Click OK.

Nonetheless one of the major problems is if we want to also delete the “BizTalkServerApplication” as a receive handler and send handler, because, before we remove an adapter handler, we must remove or re-configure all receive locations or send ports with which it is associated. 

All of these tasks are time consuming, and to be fair, they are a little boring to do after we know how to do it manually. The good news is that all of these task can easily be automated, reusable and at the same time saving significant time for other tasks... how? By, for example, using PowerShell.

Windows PowerShell is a Windows command-line shell designed especially for system administrators and can be used by BizTalk administrators to help them in automating repetitive tasks or tasks that are time consuming to perform manually.

Configuring Receive Handlers in existing Receive locations

When we are configuring/optimizing a new environment, if some features are configured like EDI features or RosettaNet Accelerator, they will create during the configuration some Receive Ports like:

  • "BatchControlMessageRecvPort" with a receive location "BatchControlMessageRecvLoc" using SQL Adapter
  • "ResendReceivePort" with a receive location "ResendReceiveLocation" using SQL Adapter
  • "LOB_To_PrivateInitiator" with a receive location "LOB_To_PrivateInitiator" using SQL Adapter
  • "LOB_To_PrivateResponder" with a receive location "LOB_To_PrivateResponder" using SQL Adapter

And all these ports, will by default during the configuration, be configured with the only existing Receive handler available at the time: “BizTalkServerApplication”, or the default Host if you already have create others.

To accomplish the task of deleting “BizTalkServerApplication” as a receive handler of each adapter, we need to:

  • Manually reconfigure the Receive handler for each existing receive location first, configuring them with the new Receive Handler;
  • and then manually delete the “BizTalkServerApplication” as a Receive handler for each adapter;

This task may occur more often on the first time we are configuring/optimizing the environment – BizTalk Server day one – but it may be more critical if you reach to an existing environment, already containing several BizTalk Applications running, that is not configured according to best practices in terms of host and host instances.

So how can we automate tasks? And reuse them whenever necessary and at the same time saving significant time for other tasks?

This is a simple script that allows you to configure the receive handlers associated with all the existing Receive Ports in your environment that are using the SQL Adapter, but this can be easily changed to cover all the Receive Locations independently of the configured adapter:

$catalog = New-Object Microsoft.BizTalk.ExplorerOM.BtsCatalogExplorer
$catalog.ConnectionString = "SERVER=$bizTalkDbServer;DATABASE=$bizTalkDbName;Integrated Security=SSPI"
  
foreach($receivePort in  $catalog.ReceivePorts)
{
    # For each receive location in your environment
    foreach($recLocation in  $receivePort.ReceiveLocations)
    {
        # In this case I want only Receive location that are using SQL Adapter
        if($recLocation.ReceiveHandler.TransportType.Name -eq 'SQL')
        {
            # Let's look for receive handlers associated with SQL Adapter
            foreach ($handler in  $catalog.ReceiveHandlers)
            {
                # if is a SQL Adapter Receive Handler
                if ($handler.TransportType.Name -eq "SQL")
                {
                    # And is not BizTalkServerApplication, then configure that as the handler of the receive location
                    # Note: that in this case we will configure as a Receive Handler of the Receive location, the first 
                    #       receive handler that we find that is not the "BizTalkServerApplication"
                    #       because the goal is to delete this handler
                    if($handler.Name -ne 'BizTalkServerApplication')
                    { 
                        $recLocation.ReceiveHandler = $handler
                        break
                    }
                }
            }
        }
    }
}
$catalog.SaveChanges()

Prerequisites for this script: The host, host instances and Receive handlers needs to be already configured in your environment before you run the script;

You can find and download the full PowerShell script on TechNet Gallery here: PowerShell to Configure Receive Handlers from existing Receive locations

Configuring the Default Send Handler as the Send Handler in existing static Send Ports

Although less critical, static send ports can also be a problem in some scenarios, for example:

  • If you configure ESB Toolkit before configuring your hosts for each functionality, because the ESB Toolkit configuration will create a static send port call “ALL.Exceptions” that connects with SQL “EsbExceptionDb” database. 
    • And, once again, this port will be configured with the default send handler (at that time) configured in your environment, that is by default the “BizTalkServerApplication”
  • but also if you reach to an existing environment, already containing several BizTalk Applications running, that is not configured according to best practices in terms of host and host instances (dedicated logical hosts for each functionality).

Once again, we need to basically do the same steps described earlier to accomplish the task of deleting “BizTalkServerApplication”, this time as a send handler of each adapter:

  • Manually reconfigure the Send handler for each existing Static Send Port first, configuring them with the new or correct Send Handler;
  • and then manually delete the “BizTalkServerApplication” as a Send handler for each adapter;

So how can we automate tasks? And reuse them whenever necessary and at the same time saving significant time for other tasks?

This is a simple script that allows you to configure the Send handler associated with all the existing Static Send Ports in your environment independently of the adapter that is configured:

$catalog = New-Object Microsoft.BizTalk.ExplorerOM.BtsCatalogExplorer
$catalog.ConnectionString = "SERVER=$bizTalkDbServer;DATABASE=$bizTalkDbName;Integrated Security=SSPI"
  
foreach($SendPort in  $catalog.SendPorts)
{
    # For each receive location in your environment
    if($sendPort.IsDynamic -eq $False)
    {
        # Let's look for send handlers associated with Adapter configured in the send port
        foreach ($handler in  $catalog.SendHandlers)
        {
            # if the Send Handler is associated with the Adapter configured in the send port
            if ($handler.TransportType.Name -eq $sendPort.PrimaryTransport.TransportType.Name)
            {
                # We will configured the port with the default send handler associated in each adapter in you system  
                # independently if it is "BizTalkServerApplication" or not.
                # Note: it's is recommended that you first configure the default send handlers for each adapter 
                #       and also not to use the "BizTalkServerApplication" (my personal recommendation)
                if($handler.IsDefault)
                { 
                    $sendPort.PrimaryTransport.SendHandler = $handler
                    break
                }
            }
        }
    }
}
$catalog.SaveChanges()

Prerequisites for this script: The host, host instances and Receive handlers needs to be already configured in your environment before you run the script;

You can find and download the full PowerShell script on TechNet Gallery here: PowerShell to Configure the Default Send Handler for each static Send Port

Configuring Default Send Handlers for each adapter in existing Dynamic Send Port

Since BizTalk Server 2013 we have available a new feature: Configurable Dynamic Send Port Handler. Which means that, when we are creating a Dynamic Send Port, an adapter Send Handler can be configurable for every installed adapter, by default it uses the default send handler associated in each adapter. This Includes both One-Way and Solicit-Response Dynamic Ports.

Note that in previous BizTalk versions, a dynamic send port uses the adapter’s default host, and we cannot change this behavior.

However, this new features also brings us some setbacks, especially for BizTalk Administrators, for example:

  • When we are configuring a new environment, if we have EDI features configured, this will add a dynamic port call “ResendPort” (don’t need to describe the propose of this port) and the default send handler for each adapter will be the “BizTalkServerApplication”;
    • If we create different or dedicated host and host instances for each functionality (receive, send, process and tracking), of course also need to associate the receive and send host as a specific handler of each adapter (receive or send handler), and if we want to delete the “BizTalkServerApplication” as a send handler for each adapter… we can’t, we first need to:
      • Manually reconfigure the default send handlers of each adapter in all the existing dynamic Send ports first, configure them with the new default send handler;
      • and then manually delete the “BizTalkServerApplication” as a send handler for each adapter;
  • The same happens when we install a new adapter. By default, it assumes the default host in the group as the default send handler of the adapter and in consequence the default send handler associated with this adapter in the existing dynamic send ports. Which means that once again we need to manually reconfigure the send handler in all the existing dynamic send ports for this new adapter;
  • And so on;

So how can we automate tasks? And reuse them whenever necessary and at the same time saving significant time for other tasks?

This is a simple script that allows you to configure the default send handlers of each adapter associated with all the existing Dynamic Send ports in your environment:

[string] $sendHost32bits = "BizTalkServerSend32Host"
[string] $sendHost64bits = "BizTalkServerSendHost"
  
$catalog = New-Object Microsoft.BizTalk.ExplorerOM.BtsCatalogExplorer
$catalog.ConnectionString = "SERVER=$bizTalkDbServer;DATABASE=$bizTalkDbName;Integrated Security=SSPI"
  
foreach($sendPort in  $catalog.SendPorts)
{
    if($sendPort.IsDynamic -eq' True')
    {
        # A Dynamic send port was found so now we need to configure the send handler as desired
        # 64 bits adapters
        # Changing the default send handlers of the dynamic port
        $sendPort.SetSendHandler("FILE", $sendHost64bits)
        $sendPort.SetSendHandler("HTTP", $sendHost64bits)
        $sendPort.SetSendHandler("MQSeries", $sendHost64bits)
        $sendPort.SetSendHandler("MSMQ", $sendHost64bits)
        $sendPort.SetSendHandler("SB-Messaging", $sendHost64bits)
        $sendPort.SetSendHandler("SFTP", $sendHost64bits)
        $sendPort.SetSendHandler("SOAP", $sendHost64bits)
        $sendPort.SetSendHandler("WCF-BasicHttp", $sendHost64bits)
        $sendPort.SetSendHandler("WCF-BasicHttpRelay", $sendHost64bits)
        $sendPort.SetSendHandler("WCF-Custom", $sendHost64bits)
        $sendPort.SetSendHandler("WCF-NetMsmq", $sendHost64bits)
        $sendPort.SetSendHandler("WCF-NetNamedPipe", $sendHost64bits)
        $sendPort.SetSendHandler("WCF-NetTcp", $sendHost64bits)
        $sendPort.SetSendHandler("WCF-NetTcpRelay", $sendHost64bits)
        $sendPort.SetSendHandler("WCF-SQL", $sendHost64bits)
        $sendPort.SetSendHandler("WCF-WebHttp", $sendHost64bits)
        $sendPort.SetSendHandler("WCF-WSHttp", $sendHost64bits)
        $sendPort.SetSendHandler("Windows SharePoint Services", $sendHost64bits)      
  
        # 32 bits adapters
        # SMTP Supports 64 bits but I want to run in 32 because of the MIME/SMIME Encoder
        $sendPort.SetSendHandler("FTP", $sendHost32bits)
        $sendPort.SetSendHandler("SMTP", $sendHost32bits)
        $sendPort.SetSendHandler("SQL", $sendHost32bits)
    }
}
  
$catalog.SaveChanges()

Prerequisites for this script: The host, host instances and Receive handlers needs to be already configured in your environment before you run the script;

You can find and download the full PowerShell script on TechNet Gallery here: PowerShell to configure Default Dynamic Send Port Handlers for each Adapter

Source Code

The PowerShell scripts belonging to this article can be found on TechNet Gallery:

See Also

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