OrchestrationBinding (BizTalk Server Sample)

The Orchestration Binding sample demonstrates using the Microsoft.BizTalk.ExplorerOM administrative objects to configure and manage orchestrations.

Prerequisites

• This sample requires that the HelloWorld sample be deployed by running setup.bat located in the <Samples Path>\Orchestrations\HelloWorld directory.

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

• The Windows PowerShell script example 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 administrative objects in the Microsoft.BizTalk.ExplorerOM namespace to manage orchestrations. The sample demonstrates the following operations using the ExplorerOM objects:

• Connecting to the BizTalk Management database by using theMicrosoft.BizTalk.ExplorerOM.BtsCatalogExplorer class.

• Stopping and starting orchestrations by changing the Status property of the Microsoft.BizTalk.ExplorerOM.BtsOrchestration class.

• Enlisting and unenlisting orchestrations by changing the Status property of the Microsoft.BizTalk.ExplorerOM.BtsOrchestration class.

• Binding and unbinding orchestrations by using the Ports collection on the Microsoft.BizTalk.ExplorerOM.BtsOrchestration class.

Where To Find This Sample

The sample is located in the following SDK location:

<Samples Path>\Admin\ExplorerOM\OrchestrationBinding

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

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

Build this sample

1. Make sure you have completed the steps for building and initializing the HelloWorld sample. Those steps are provided in HelloWorld (BizTalk Server Sample).

2. In Visual Studio, open the solution file OrchestrationBinding.sln.

3. On the Build menu, click Build Solution.

Run this sample

1. Open a command window and navigate to the following folder:

   <Samples Path>\Admin\ExplorerOM\OrchestrationBinding\bin\Debug

2. Run the file OrchestrationBinding.exe and follow the directions provided by the sample.

Windows PowerShell Script Example

The following Windows PowerShell script can be used to demonstrate the same features of the ExplorerOM classes.

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:

• Security in BizTalk Server
• Security for sending and receiving messages
• Access control and data security

Function RefreshPrompt($oldstatus,$newstatus)
{
  Write-Host Orchestration Status should now be `"$oldstatus`"
  Write-Host Press F5 in the Orchestrations view of BizTalk Server Administration Console to refresh and verify

  if ($newstatus)
  {
    Write-Host Pressing `<Enter`> now will $newstatus the orchestration using ExplorerOM`.`.`.
    Read-Host
    Write-Host "=== Please wait, attempting to $newstatus the orchestration... ===`r`n"
  }
  else
  {
    write-host `r`n
  }
}

#===================#
#=== 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"

#=== This sample expects the HelloWorld sample orchestration to be using the ===#
#=== default name "Biztalk Application 1"                                    ===#

$HelloWorldApp = $Catalog.Applications["Biztalk Application 1"]
$orch = $HelloWorldApp.orchestrations["Microsoft.Samples.BizTalk.HelloWorld.HelloSchedule"]

#==================================================================#
#=== Register a trap handler to discard changes on exceptions   ===#
#=== Execution will continue in the event we need to re-enlist, ===#
#=== re-bind, or restart the orchestration.                     ===#
#==================================================================#

$ErrorActionPreference="silentlycontinue"
trap { "Exception encountered:`r`n"; $_; "`r`nDiscarding Changes and continuing execution...`r`n";$Catalog.DiscardChanges();}

write-host `r`nMake sure the "HelloWorld" sample application is deployed and running.
write-host By default it will be listed in the BizTalk Server Administration Console
write-host with the application name: `"BizTalk.Application.1`"`r`n

#==========================================================#
#=== Change orchestration state from Started to stopped ===#
#==========================================================#

RefreshPrompt Started stop
$orch.Status = [Microsoft.BizTalk.ExplorerOM.OrchestrationStatus] "Enlisted"
$Catalog.SaveChanges()

#=============================================================#
#=== Change orchestration state from stopped to unenlisted ===#
#=============================================================#

RefreshPrompt Stopped unenlist
$orch.Status = [Microsoft.BizTalk.ExplorerOM.OrchestrationStatus] "Unenlisted"
$Catalog.SaveChanges()

#=============================================================#
#=== Change orchestration state from unenlisted to unbound ===#
#=============================================================#

RefreshPrompt Unenlisted unbind
$orch.Ports["SendInvoicePort"].SendPort = $null
$orch.Ports["ReceivePOPort"].ReceivePort = $null;
$orch.Host = $null
$Catalog.SaveChanges()

#==================================================================#
#=== Change orchestration state from unbound back to unenlisted ===#
#==================================================================#

RefreshPrompt Unenlisted`(Unbound`) re-bind
$orch.Ports["SendInvoicePort"].SendPort = $Catalog.SendPorts["HelloWorldSendPort"]
$orch.Ports["ReceivePOPort"].ReceivePort = $Catalog.ReceivePorts["HelloWorldReceivePort"]
$orch.Host = $Catalog.Hosts["BizTalkServerApplication"]
$Catalog.SaveChanges()

#==================================================================#
#=== Change orchestration state from unenlisted back to stopped ===#
#==================================================================#

RefreshPrompt Unenlisted enlist
$orch.Status = [Microsoft.BizTalk.ExplorerOM.OrchestrationStatus] "Enlisted"
$Catalog.SaveChanges()

#===============================================================#
#=== Change orchestration state from stopped back to started ===#
#===============================================================#

RefreshPrompt Stopped restart
$orch.Status = [Microsoft.BizTalk.ExplorerOM.OrchestrationStatus] "Started"
$Catalog.SaveChanges()

RefreshPrompt Started

Here is an example output from running the Windows PowerShell script.

PS C:\> .\OrchestrationBind.ps1

Make sure the HelloWorld sample application is deployed and running.
By default it will be listed in the BizTalk Server Administration Console
with the application name: "BizTalk.Application.1"

Orchestration Status should now be "Started"
Press F5 in the Orchestrations view of BizTalk Server Administration Console to refresh and verify
Pressing <Enter> now will stop the orchestration using ExplorerOM...

=== Please wait, attempting to stop the orchestration... ===

Orchestration Status should now be "Stopped"
Press F5 in the Orchestrations view of BizTalk Server Administration Console to refresh and verify
Pressing <Enter> now will unenlist the orchestration using ExplorerOM...

=== Please wait, attempting to unenlist the orchestration... ===

Orchestration Status should now be "Unenlisted"
Press F5 in the Orchestrations view of BizTalk Server Administration Console to refresh and verify
Pressing <Enter> now will unbind the orchestration using ExplorerOM...

=== Please wait, attempting to unbind the orchestration... ===

Orchestration Status should now be "Unenlisted(Unbound)"
Press F5 in the Orchestrations view of BizTalk Server Administration Console to refresh and verify
Pressing <Enter> now will re-bind the orchestration using ExplorerOM...

=== Please wait, attempting to re-bind the orchestration... ===

Orchestration Status should now be "Unenlisted"
Press F5 in the Orchestrations view of BizTalk Server Administration Console to refresh and verify
Pressing <Enter> now will enlist the orchestration using ExplorerOM...

=== Please wait, attempting to enlist the orchestration... ===

Orchestration Status should now be "Stopped"
Press F5 in the Orchestrations view of BizTalk Server Administration Console to refresh and verify
Pressing <Enter> now will restart the orchestration using ExplorerOM...

=== Please wait, attempting to restart the orchestration... ===

Orchestration Status should now be "Started"
Press F5 in the Orchestrations view of BizTalk Server Administration Console to refresh and verify

See Also

Admin-ExplorerOM (BizTalk Server Samples Folder) HelloWorld (BizTalk Server Sample)