Edit

Share via

ReceiveLocations (BizTalk Server Sample)

  • Article

The ReceiveLocations sample demonstrates how to create receive locations in the BizTalk Server environment by using the ExplorerOM administration objects. For more information about receive locations in general, see Receive Locations.

Prerequisites

  • You must have BizTalk Server administrative privileges to use the administrative objects in this sample.

  • The Windows PowerShell script requires the Windows PowerShell execution policy to allow script execution. For more information see Examining the Execution Policy.

What This Sample Does

This sample demonstrates using the ExplorerOM administrative classes to create and configure receive ports and receive locations. A Windows PowerShell example script is also included in this topic. The sample performs the following operations:

  • Create a new receive port named “My Receive Port”.

  • Create a new receive location associated with the new port and configured to use the HTTP transport protocol.

  • This sample also contains example procedures to delete and enumerate receive ports and locations.

Where To Find This Sample

This sample is located in the following SDK location:

<Samples Path> \Admin\ExplorerOM\ReceiveLocations

The following table shows the files in this sample and describes their purpose.

File(s) Description
ReceiveLocations.cs Visual C# source file for the operations demonstrated in this sample.
ReceiveLocations.sln and ReceiveLocations.csproj Solution and project files for this sample.

Building and Running This Sample

To build this sample

  1. In Visual Studio, open the solution file ReceiveLocations.sln.

  2. On the Build menu, click Build Solution.

To run this sample

  1. Open a command prompt with BizTalk Server administrative privileges.

  2. Change to the <Samples>\Admin\ExplorerOM\ReceiveLocations\bin\debug directory.

  3. Run ReceiveLocations.exe.

  4. View the new receive port and receive location with the BizTalk Server Administration console.

Windows PowerShell Script Example

The following PowerShell example script demonstrates the same operations as the Visual C# version. Make sure the script execution policy has been properly configured as mentioned in the requirements section of this topic.

Caution

This example or guidance references sensitive information, such as a connection string or a username and password. Never hardcode these values in your code, and make sure that you protect confidential data by using the most secure authentication available. For more information, see the following documentation:

#==================================================================#
#===                                                            ===#
#=== Create a new receive port named "My Receive Port" as an    ===#
#=== example.                                                   ===#
#===                                                            ===#
#=== A new receive location will also be created and associated ===#
#=== with the receive port.                                     ===#
#===                                                            ===#
#==================================================================#
Function CreateAndConfigureReceiveLocation()
{
   $myreceivePort = $catalog.AddNewReceivePort($false)

   #=== Note that if you don’t set the name property for the receieve port, ===#
   #=== it will create a new receive location and add it to the receive     ===#
   #=== port.                                                               ===#

   $myreceivePort.Name = "My Receive Port"

   #=== Create a new receive location and add it to the receive port ===#
   $myreceiveLocation = $myreceivePort.AddNewReceiveLocation()

   foreach ($handler in $catalog.ReceiveHandlers)
   {
      if ($handler.TransportType.Name -eq "HTTP")
      {
         $myreceiveLocation.ReceiveHandler = $handler
         break
      }
   }

   #=== Associate a transport protocol and URI with the receive location. ===#
   $myreceiveLocation.TransportType = $catalog.ProtocolTypes["HTTP"]
   $myreceiveLocation.Address = "/home"

   #=== Assign the first receive pipeline found to process the message. ===#
   foreach ($pipeline in $catalog.Pipelines)
   {
      if ($pipeline.Type -eq [Microsoft.Biztalk.ExplorerOM.PipelineType] "Receive")
      {
         $myreceiveLocation.ReceivePipeline = $pipeline
         break
      }

      #=== Enable the receive location. ===#
      $myreceiveLocation.Enable = $true

      #=== Optional Properties ===#
      $myreceiveLocation.FragmentMessages = [Microsoft.BizTalk.ExplorerOM.Fragmentation] "Yes"
      $myreceiveLocation.ServiceWindowEnabled = $false
   }

    #=== Try to commit the changes made so far. If the commit fails, ===#
    #=== roll back all changes.                                      ===#
    $catalog.SaveChanges()
}

#===============================================================#
#===                                                         ===#
#=== Delete the receive port named "My Receive Port"         ===#
#===                                                         ===#
#===============================================================#
Function DeleteReceivePort
{
  $receivePort = $catalog.ReceivePorts["My Receive Port"]

  if ($receivePort -ne $null)
  {

    #=== Enumerate the receive locations. ===#
    foreach ($location in $receivePort.ReceiveLocations)
    {
        if (($location.Name -eq "Receive Location1") -and ($location.IsPrimary -eq $false))
        {
          $receivePort.RemoveReceiveLocation($location)
        }
    }

    $catalog.RemoveReceivePort($receivePort)

    #=== Try to commit the changes made so far. If the commit fails, ===#
    #=== roll back all changes in the trap handler.                  ===#
    $catalog.SaveChanges()
  }
}

#================================================================#
#===                                                          ===#
#=== Enumerate the receive ports and their receive locations. ===#
#===                                                          ===#
#================================================================#
Function EnumerateReceiveLocations
{
   #=== Enumerate the receive locations in each of the receive ports. ===#
   foreach ($receivePort in $catalog.ReceivePorts)
   {
      Write-host "`r`n$($receivePort.Name)"

      #=== Enumerate the receive locations. ===#
      foreach ($location in $receivePort.ReceiveLocations)
      {
         Write-Host "`t$($location.Name)"
      }
   }

   Write-host ""
}

#===================#
#=== Main Script ===#
#===================#

#=== Make sure the ExplorerOM assembly is loaded ===#

[void] [System.reflection.Assembly]::LoadWithPartialName("Microsoft.BizTalk.ExplorerOM")

#=== Connect to the BizTalk Management database ===#

$Catalog = New-Object Microsoft.BizTalk.ExplorerOM.BtsCatalogExplorer
$Catalog.ConnectionString = "SERVER=.;DATABASE=BizTalkMgmtDb;Integrated Security=SSPI"

#==================================================================#
#=== Register a trap handler to discard changes on exceptions   ===#
#=== Execution will continue in the event we want to delete the ===#
#=== receive port.                                              ===#
#==================================================================#

$Script:NoExceptionOccurred = $true
$ErrorActionPreference="silentlycontinue"
trap
{
  $Script:NoExceptionOccurred = $false
  "Exception encountered:`r`n"; $_; "`r`nDiscarding Changes and continuing execution so we can attempt to clean up the receive port...`r`n"
  $Catalog.DiscardChanges()
}

#=== Create the new receive port with its new receive location ===#
CreateAndConfigureReceiveLocation
Write-Host "`r`n`"My Receive Port`" created."

#=== Enumerate each receive port along with its receive locations ===#
Write-Host "`r`nEnumerating all receive ports...`r`n"
EnumerateReceiveLocations

#=== Prompt before removing the new example receive port and location ===#
Write-Host "`r`nPress <ENTER> to delete `"My Receive Port`"..."
Read-Host
DeleteReceivePort

#=== Enumerate again to show the receive port and location was removed ===#
Write-Host "`r`nEnumerating all receive ports to show `"My Receive Port`" was removed...`r`n"
EnumerateReceiveLocations

Here is example output from the PowerShell script execution showing the receive port and location being created and deleted:

PS C:\> .\ReceiveLocations.ps1

"My Receive Port" created.

Enumerating all receive ports...

BatchControlMessageRecvPort
        BatchControlMessageRecvLoc

ResendReceivePort
        ResendReceiveLocation

HelloWorldReceivePort
        HelloWorldReceiveLocation

CBRReceivePort
        CBRReceiveLocation

RP_ReceivePOFromInternal
        RL_ReceivePOFromInternal

RP_ShipmentAgency1_OrderFiles
        RL_ShipmentAgency1_OrderFiles

RP_ShipmentAgency2_OrderFiles
        RL_ShipmentAgency2_OrderFiles

RP_ReceivePOFromBuyer
        RL_ReceivePOFromBuyer

RP_Receive_ShipmentAgency_Ack
        RL_Receive_ShipmentAgency_Ack

My Receive Port
        Receive Location1

Press <ENTER> to delete "My Receive Port"...

Enumerating all receive ports to show "My Receive Port" was removed...

BatchControlMessageRecvPort
        BatchControlMessageRecvLoc

ResendReceivePort
        ResendReceiveLocation

HelloWorldReceivePort
        HelloWorldReceiveLocation

CBRReceivePort
        CBRReceiveLocation

RP_ReceivePOFromInternal
        RL_ReceivePOFromInternal

RP_ShipmentAgency1_OrderFiles
        RL_ShipmentAgency1_OrderFiles

RP_ShipmentAgency2_OrderFiles
        RL_ShipmentAgency2_OrderFiles

RP_ReceivePOFromBuyer
        RL_ReceivePOFromBuyer

RP_Receive_ShipmentAgency_Ack
        RL_Receive_ShipmentAgency_Ack

See Also

Receive Locations Admin-ExplorerOM (BizTalk Server Samples Folder)