PartnerManagement (BizTalk Server Sample)

Article
07/07/2021

The PartnerManagement sample demonstrates how to manage parties in the BizTalk Server environment by using the ExplorerOM administration objects.

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 administrative classes from the Microsoft.BizTalk.ExplorerOM namespace to manage parties. Parties represent trading partners or back-end applications with which a business process can interact. For more information about parties in general, see the documentation for Parties or Role Links and Service Link Roles. The sample is written in Microsoft Visual C#. A Windows PowerShell example script is also included in this topic. The sample demonstrates the following operations:

Creating a new party with a custom or standard alias and adding existing BizTalk Server send ports to the party.
Enlisting the new party with an existing role link on the BizTalk server.
Un-enlisting the new party.
Deleting the new party.

Where To Find This Sample

The sample is located in the following SDK location:

<Samples Path>\Admin\ExplorerOM\PartnerManagement

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

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

Building and Running This Sample

Before you build the sample, you need to make four code modifications to customize the sample for the BizTalk server. This is necessary because the sample uses arbitrary names for send ports associated with the party and an arbitrary role name for the enlistment. Therefore you need to provide valid names to the sample. To demonstrate this sample, this topic describes first building the PartyResolution sample from the following directory: <Samples Path>\Orchestrations\PartyResolution. This approach is used to make sure a valid role name and send port names are present on the BizTalk server to demonstrate the sample procedures.

To build this sample

First make sure the PartyResolution sample has been built and initialized so that a valid role name and send port names can be used by the sample. This is documented in the section entitled “Building and Initializing This Sample” in PartyResolution (BizTalk Server Sample).
In Visual Studio, open the solution file PartnerManagement.sln.
In Solution Explorer, open the source file PartnerManagement.cs.

Scroll down into the function named CreateParty and insert the two send port names from the PartyResolution sample or use valid names from the BizTalk server environment. The following code example demonstrates the change using the send ports from the PartyResolution sample.

// Replacing arbitrary send port names with PartyResolution send port names ===

//            myParty.SendPorts.Add(catalog.SendPorts["NormalDelivery"]);
//            myParty.SendPorts.Add(catalog.SendPorts["ExpressDelivery"]);
            myParty.SendPorts.Add(catalog.SendPorts["SP_FilesToShipmentAgency1"]);
            myParty.SendPorts.Add(catalog.SendPorts["SP_FilesToShipmentAgency2"]);

Scroll down into the function named EnlistParty and change the foreach loop so that it searches the Supplier assembly for a role named “ShipmentRole” to use with the enlistment. The following code example demonstrates the change to use the ShipmentRole from the PartyResolution sample.

            // Search for the “Shipmentrole” instead of “shipperRole”
            Role svcRole = null;
//===       foreach (Role role in catalog.Assemblies[0].Roles)
            foreach (Role role in catalog.Assemblies["Supplier"].Roles)
            {
//===          if (role.Name == "ShipperRole")
               if (role.Name == "ShipmentRole")
               {
                  svcRole = role;
                  break;
               }
            }

Scroll down into the function named UnenlistParty and change the foreach loop to search the Supplier assembly for the ShipmentRole. The following code example demonstrates this change.

            // Search for the “ShipmentRole” instead of “shipperRole”
            Role svcRole = null;
//===       foreach (Role role in catalog.Assemblies[0].Roles)
            foreach (Role role in catalog.Assemblies["Supplier"].Roles)
            {
//===          if (role.Name == "ShipperRole")
               if (role.Name == "ShipmentRole")
               {
                  svcRole = role;
                  break;
               }
            }

After creating and enlisting the new party with the ShipmentRole, the sample is designed to immediately un-enlist the party and delete it. Add the following code change to the main procedure to pause execution and allow you to view the created enlistment for the new party in the BizTalk Server Administration console.
```
static void Main(string[] args)
{
   CreateParty();
   EnlistParty();

   Console.WriteLine("\nNew Party created and enlisted.\n\nPress <Enter> to unenlist and delete.\n");
   Console.ReadLine();

   UnenlistParty();
   DeleteParty();
}
```
On the Build menu, click Build Solution.

To run this sample

Open a command window and navigate to the following folder:

<Samples Path>\Admin\ExplorerOM\PartnerManagement\bin\Debug
Run the file PartnerManagement.exe.
When the sample displays the message that the new party is created and enlisted, open the BizTalk Server Administration console and view the new party named FedEx under the Parties node.
In the BizTalk Server Administration console, navigate the tree view to the ShipmentRole under Applications\BizTalk Application 1\Role Links. Double-click ShipmentRole and notice ShipmentAgency1 mapped to the SupplierAdvice operation and ShipmentAgency2 mapped to the SupplierOrder operation in the enlistment.
In the command window, press ENTER to allow the sample to un-enlist and delete the new party.
In the BizTalk Server Administration console, verify the party was un-enlisted from the ShipmentRole and deleted from the Parties node.

Windows PowerShell Script Example

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

#===============================================================#
#===                                                         ===#
#=== Create a new party named "FedEx" as an example.         ===#
#===                                                         ===#
#=== Two Shipment agency send ports from the PartyResolution ===#
#=== sample will be added to the party.                      ===#
#===                                                         ===#
#===============================================================#
Function CreateParty
{
  #=== Create a party =====================#
  $myParty = $Catalog.AddNewParty()
  $myParty.Name = "FedEx"

  #=== create a standard alias ==========================#
  $standardAlias = $myParty.AddNewAlias()
  $standardAlias.Name = "D-U-N-S (Dun & Bradstreet)"
  $standardAlias.Value = "Value1"

  #=== Create a custom alias ==================#
  $customAlias = $myParty.AddNewAlias()
  $customAlias.Name = "Telephone"
  $customAlias.Qualifier = "100"
  $customAlias.Value = "4255550234"

  #=== Add party send ports =====================================================#

  #===============================================================#
  #=== Have to use IList directly on this sendports collection ===#
  #=== to work around a PowerShell issue.                      ===#
  #===============================================================#
  $iList = [System.Collections.IList]

  $sendport1 = $Catalog.SendPorts["SP_FilesToShipmentAgency1"]
  [void] $iList.GetMethod("Add").Invoke($myParty.SendPorts,$sendport1)

  $sendport2 = $Catalog.SendPorts["SP_FilesToShipmentAgency2"]
  [void] $iList.GetMethod("Add").Invoke($myParty.SendPorts,$sendport2)

  #=== Specify a signature certificate, make sure the certificate is available ===#
  #=== in the AddressBook store of the Local Machine                           ===#

  foreach ($certificate in $Catalog.Certificates)
  {
    if ($certificate.ShortName -eq "BR, Certisign Certificadora Digital Ltda., Certisign - Autoridade Certificadora - AC2")
    {
      $myParty.SignatureCert = $certificate
    }
  }

  #=== Commit the changes ===#
  $catalog.SaveChanges()
}

#===============================================================#
#===                                                         ===#
#=== Delete the party named "FedEx"                          ===#
#===                                                         ===#
#===============================================================#
Function DeleteParty
{
  $Catalog.RemoveParty($Catalog.Parties["FedEx"])

  #=== Commit the changes ===#
  $catalog.SaveChanges()
}

#===============================================================#
#===                                                         ===#
#=== Enlist the "FedEx" party with the "ShipmentRole"        ===#
#===                                                         ===#
#===============================================================#
Function EnlistParty
{
  $myParty = $Catalog.Parties["FedEx"]

  #=== Get the "ShipmentRole" in the Supplier assembly.        ===#
  $svcRole = $Catalog.Assemblies["Supplier"].Roles["ShipmentRole"]

  #=== Enlist the party under the shipper role ===#
  $enlistedParty = $svcRole.AddNewEnlistedParty($myParty)

  #===============================================================#
  #=== Have to use IList directly on this sendports collection ===#
  #=== to work around a PowerShell issue.                      ===#
  #===============================================================#
  $iList = [System.Collections.IList]

  #===============================================================#
  #=== Example port to be used for the role's "SupplierAdvice" ===#
  #=== operation.                                              ===#
  #=== Using the first send port added to the new party which  ===#
  #=== is "SP_FilesToShipmentAgency1" at index 0 in the        ===#
  #=== sendports collection.                                   ===#
  #===============================================================#
  $enlistedParty.Mappings[0].SendPort = $iList.GetProperty("Item").GetValue($myParty.SendPorts,0)

  #===============================================================#
  #=== Example port to be used for the role's "SupplierOrder"  ===#
  #=== operation.                                              ===#
  #=== Using the second send port added to the new party which ===#
  #=== is "SP_FilesToShipmentAgency2" at index 1 in the        ===#
  #=== sendports collection.                                   ===#
  #===============================================================#
  $enlistedParty.Mappings[1].SendPort = $iList.GetProperty("Item").GetValue($myParty.SendPorts,1)

  #=== Commit the changes ===#
  $Catalog.SaveChanges()
}

#===============================================================#
#===                                                         ===#
#=== Unenlist the "FedEx" party from the ShipmentRole        ===#
#===                                                         ===#
#===============================================================#
Function UnenlistParty
{
  #=== Get the "ShipmentRole" from the Supplier assembly. ===#
  $svcRole = $Catalog.Assemblies["Supplier"].Roles["ShipmentRole"]

  #=== Remove the "FedEx" party ===#
  foreach ($enlistedparty in $svcRole.EnlistedParties)
  {
    if ($enlistedparty.Party.Name -eq "FedEx")
    {
      $svcRole.RemoveEnlistedParty($enlistedparty)
      break
    }
  }

  #=== Commit the changes ===#
  $Catalog.SaveChanges()
}

#===================#
#=== 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 PartyResolution sample to be built and deployed  ===#
#=== to the BizTalk Server.                                                   ===#

write-host `r`nMake sure the "PartyResolution" sample application from the Orchestrations
write-host sample directory 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

$SupplierAssembly = $Catalog.Assemblies["Supplier"]

#==================================================================#
#=== Register a trap handler to discard changes on exceptions   ===#
#=== Execution will continue in the event we want to unenlist,  ===#
#=== and delete the party.                                      ===#
#==================================================================#

$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 party...`r`n"
  $Catalog.DiscardChanges()
}

CreateParty
EnlistParty

if ($Script:NoExceptionOccurred)
{
  Write-Host "`r`nExample Party `"FedEx`" should be created and enlisted with the `"ShipmentRole`".`r`n"
  Write-Host You can view the results in the BizTalk Server Administration console.`r`n
  Write-Host "Press <Enter> to unenlist and delete...`r`n"
  Read-Host
}

UnenlistParty
DeleteParty

Here is example output from running the PowerShell example script. If the script fails to run, make sure PowerShell scripting is enabled according to the requirements note at the top of this topic.

PS C:\> .\PartnerManagement.ps1

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

Example Party "FedEx" should be created and enlisted with the "ShipmentRole".

You can view the results in the BizTalk Server Administration console.

Press <Enter> to unenlist and delete...