BizTalk Server 2009 : Administrative Tools (part 3) – ExplorerOM

February 18, 2013

4. ExplorerOM

The ExplorerOM object model is a set of classes and interfaces from the ExplorerOM namespace used by BizTalk Explorer to configure applications. You can consider ExplorerOM as an API to the Management Database that allows you to perform application management and configuration tasks. To use it in your .NET applications, you have to add a reference to the [BizTalk Installation directory]\Developer Tools\Microsoft.Biztalk.ExplorerOM.dll assembly. All artifacts in ExplorerOM are stored in collections, and there are three classes hosting collections of artifacts, as listed in Table 13

Table 38. ExplorerOM Container Classes
Class Description
BtsCatalogExplorer Provides methods and properties to manipulate artifacts at the BizTalk Server Group level
BtsApplication Provides methods and properties to manipulate artifacts at the BizTalk application level
Assembly Provides properties to access artifacts at the assembly level
4.1. BtsCatalogexplorer Class

This class provides access to all artifacts in the Management Database, regardless of their association with a specific BizTalk application or assembly. You can also use this class to add or remove artifacts from the different collections and then commit changes to the Management Database. This class is the most fundamental, since all ExplorerOM code you write will have one thing in common: instantiating the BtsCatalogExplorer class and setting the ConnectionString property to access the Management Database.

Table 14 lists the properties of the BtsCatalogExplorer class. As you can guess, all these properties except the ConnectionString property are collections of different BizTalk artifacts stored in the Management Database.

Table 14. BtsCatalogExplorer Properties
Property Name Description
ConnectionString Connection string to the Management Database.
Applications Read-only. Returns a collection of applications in the Management Database.
Assemblies Read-only. Returns a collection of deployed assemblies.
Certificates Read-only. Returns a collection of certificates installed on the computer.
Hosts Read-only. Returns a collection of hosts in the Management Database.
Parties Read-only. Returns a collection of parties in the Management Database.
Pipelines Read-only. Returns a collection of pipelines in the Management Database.
ProtocolTypes Read-only. Returns a collection of protocol types in the Management Database.
ReceiveHandlers Read-only. Returns a collection of receive handlers in the Management Database.
ReceivePorts Read-only. Returns a collection of receive ports in the Management Database.
Schemas Read-only. Returns a collection of schemas in the Management Database.
SendPortGroups Read-only. Returns a collection of send port groups in the Management Database.
SendPorts Read-only. Returns a collection of send ports in the Management Database.
StandardAliases Read-only. Returns a collection of standard aliases.
Transforms Read-only. Returns a collection of transforms.

Let’s put everything mentioned previously in practice and write a utility that enumerates all send ports in the Management Database and prints out the port name and status, as shown in Listing 4.

Example 4. Enumeration of Send Ports
using System;
using System.Text;
using Microsoft.BizTalk.ExplorerOM;

namespace SendPorts
{
    class Program
    {

        static void Main(string[] args)
        {
            EnumerateSendPorts();
            Console.ReadKey();
        }

        public static void EnumerateSendPorts()
        {
            BtsCatalogExplorer catalog = new BtsCatalogExplorer();
            catalog.ConnectionString = "Server=.;Initial Catalog=BizTalkMgmtDb;
Integrated Security=SSPI;";


            foreach (SendPort sendPort in catalog.SendPorts )
            {
                Console.WriteLine("\tPortName:{0},Status:{1}",
                     sendPort.Name ,sendPort.Status);
            }
        }
    }
}

 

Alternatively, you can get access to the collections of artifacts exposed by the BtsCatalogExplorer class by calling the GetCollection method and passing as a parameter values from the CollectionType enumeration. The member names of this enumeration are exactly the same as the names of the properties of the BtsCatalogExplorer class. Listing 5 shows how to print out port names and status using the GetCollection method.

Example 5. Enumeration of Send Ports Using the GetCollection Method
using System;
using System.Text;
using Microsoft.BizTalk.ExplorerOM;

namespace SendPorts
{
    class Program
    {

        static void Main(string[] args)
        {
            EnumerateSendPorts();
            Console.ReadKey();
        }

        public static void EnumerateSendPorts()
        {
            BtsCatalogExplorer catalog = new BtsCatalogExplorer();
            catalog.ConnectionString = "Server=.;Initial Catalog=BizTalkMgmtDb;
Integrated Security=SSPI;";
            SendPortCollection spCollection =
(SendPortCollection)catalog.GetCollection(CollectionType.SendPort);

            foreach (SendPort sendPort in spCollection)
            {
                Console.WriteLine("\tPortName:{0},Status:{1}",
                     sendPort.Name, sendPort.Status);
            }
        }
    }
}

 

The BtsCatalogExplorer class not only allows you to walk through existing artifacts but also provides methods to add, delete, and configure them and commit changes to the Management Database. Table 15 lists such methods.

Table 15. BtsCatalogExplorer Methods
Method Name Description
AddNewApplication Creates and adds a new Application object to the Application collection. Specific to BizTalk Server 2006.
RemoveApplication Removes the specified application from the Application collection. Specific to BizTalk 2006.
AddNewParty Creates and adds a new Party object to the Parties collection.
RemoveParty Removes the specified party from the Parties collection.
AddNewReceivePort Creates and adds a new ReceivePort object to the ReceivePorts collection.
RemoveReceivePort Removes the specified receive port from the ReceivePorts collection.
AddNewSendPort Creates and adds a new SendPort object to the SendPorts collection.
RemoveSendPort Removes the specified send port from the SendPorts collection.
AddNewSendPortGroup Creates and adds a new SendPortGroup object to the SendPortGroups collection.
RemoveSendPortGroup Removes the specified send port group.
SaveChanges Commits all BtsCatalogExplorer object changes to the Management Database.
SaveChangesWithTransaction Commits all BtsCatalogExplorer object changes to the Management Database in a specified transaction.
DiscardChanges Discards all BtsCatalogExplorer object changes.

The code in Listing 6 shows how to create a send port using the AddNewSendPort method of the BtsCatalogExplorer class.

Example 6. Creating a New Send Port Using the AddNewSendPort Method
using System;
using Microsoft.BizTalk.ExplorerOM

namespace AddSendPort
{
    class Program
    {
        static void Main(string[] args)
        {
            CreateSendPort();

        }

 

private static void CreateSendPort()
        {
            // Connect to the BizTalk configuration database
           BtsCatalogExplorer catalog = new BtsCatalogExplorer();
            catalog.ConnectionString = "Server=PROBIZTALK;Initial Catalog=
BizTalkMgmtDb;Integrated Security=SSPI;";

            try
            {
               // Create static one-way send port
                SendPort myStaticOnewaySendPort =
catalog.AddNewSendPort(false, false);
                myStaticOnewaySendPort.Name = "PROBiztalkSendPort";
                myStaticOnewaySendPort.PrimaryTransport.TransportType =
catalog.ProtocolTypes["HTTP"];
                myStaticOnewaySendPort.PrimaryTransport.Address =
"http://DestinationUrl";
                myStaticOnewaySendPort.SendPipeline =
catalog.Pipelines["Microsoft.BizTalk.DefaultPipelines.XMLTransmit"];

                // Commit changes to BizTalk configuration database
                catalog.SaveChanges();
            }
            catch (Exception ex)
            {
                catalog.DiscardChanges();
            }
        }
    }
}

 

In BizTalk Server 2009 all artifacts must be associated with a BizTalk application. It is important to note that the code in Listing 6 adds a new port and associates it automatically with the current default application. How to associate artifacts with a specific application will be discussed in the next section, which we devote to the Application class.

4.2. application Class

The second class hosting collections of BizTalk artifacts is the Application class. As you can guess, this class provides similar methods and properties as the BtsCatalogExplorer class. The main difference is that the Application class deals with the artifacts belonging to a specific application.

If you want to perform actions on the artifacts belonging to a specific BizTalk application, you have to obtain a reference on the desired application and then use the methods and properties of the Application class listed in Tables 16 and 17.

Table 16. Application Class Properties
Property Name Description
Assemblies Read-only. Returns a collection of assemblies associated with the application.
BackReferences Read-only. Returns a collection of applications referencing the application.
BtsCatalogExplorer Read-only. Returns the BtsCatalogExplorer object containing the Application object.
Description Gets or sets the application description.
IsConfigured Read-only. Returns a Boolean value indicating that all orchestrations’ ports in the application are bound.
IsDefaultApplication Read-only. Returns a Boolean value indicating whether the application is the default application.
IsSystem Read-only. Returns a Boolean value indicating whether or not the application is the system application.
Name Gets or sets the name of the application.
Orchestrations Read-only. Returns a collection of the orchestrations associated with the application.
Pipelines Read-only. Returns a collection of the pipelines associated with the application.
Policies Read-only. Returns a collection of the policies associated with the application.
ReceivePorts Read-only. Returns a collection of the receive ports associated with the application.
References Read-only. Returns a collection of the applications referenced by the application.
Roles Read-only. Returns a collection of the roles associated with the application.
Schemas Read-only. Returns a collection of the schemas associated with the application.
SendPortGroups Read-only. Returns a collection of send port groups associated with the application.
SendPorts Read-only. Returns a collection of the send ports associated with the application.
Status Read-only. Returns the status of the application.
Transforms Read-only. Returns a collection of the maps associated with the application.
Table 17. Application Class Public Methods
Method Name Description
AddNewReceivePort Adds a new receive port to the ReceivePorts collection
AddNewSendPort Adds a new send port to the SendPorts collection
AddNewSendPortGroup Adds a new send port group to the SendPortGroups collection
AddReference Adds a BizTalk application to the References collection
RemoveReference Removes a BizTalk application from the References collection
Start Starts all orchestrations, send ports, and send port groups, and enables all receive locations belonging to this and referenced applications
Stop Stops all orchestrations, send ports, and send port groups, and disables all receive locations belonging to this and referenced applications

Assuming you have an application named PROBIZTALK Application, the code in Listing 7 shows how you can obtain a reference to this application and to add a send port to it.

Example 7. Adding a New Send Port to a Specific BizTalk Application
using System;
using Microsoft.BizTalk.ExplorerOM

namespace AddSendPort
{

    class Program
    {
        static void Main(string[] args)
        {
            CreateSendPort();

        }


        private static void CreateSendPort()
        {
            // Connect to the BizTalk configuration database
           BtsCatalogExplorer catalog = new BtsCatalogExplorer();
            catalog.ConnectionString = "Server=PROBIZTALK;Initial Catalog=
BizTalkMgmtDb;Integrated Security=SSPI;";

            try
            {
               // Get a reference on existing BizTalk Application
               Application app = catalog.Applications["PROBIZTALK Application"]

 

// Create static one-way send port
               SendPort myStaticOnewaySendPort = app.AddNewSendPort(false, false);
               myStaticOnewaySendPort.Name = "PROBiztalkSendPort";
               myStaticOnewaySendPort.PrimaryTransport.TransportType =
catalog.ProtocolTypes["HTTP"];
               myStaticOnewaySendPort.PrimaryTransport.Address =
"http://DestinationUrl";
               myStaticOnewaySendPort.SendPipeline =
catalog.Pipelines["Microsoft.BizTalk.DefaultPipelines.XMLTransmit"];

               // Commit changes to BizTalk configuration database
               catalog.SaveChanges();
            }
            catch (Exception ex)
            {
               catalog.DiscardChanges();
            }
        }
    }
}

 

If you happened to work with previous versions of BizTalk Server, you are no doubt aware that starting BizTalk solutions was not easy. For example, if one orchestration called another, they had to be started and stopped in the following strict order: called orchestrations first, calling orchestrations last in case of starting, and in reverse order in case of stopping. That’s not a problem if you had only a few orchestrations, but what if there were dozens of them and they were interdependent? And how about starting dozens or even hundreds of ports one by one manually? Fortunately, BizTalk Server 2009 provides an easy solution. Simply use the Start and Stop methods of the Application class, taking values from the ApplicationStartOption and ApplicationStopOption enumerations as parameters. Available values are listed in Tables 18 and 19.

Table 18. ApplicationStartOption Enumeration
Enumeration Value Description
DeployAllPolicies Specifies all policies to be deployed
EnableAllReceiveLocations Specifies all receive locations to be enabled
StartAllOrchestrations Specifies all orchestrations to be started
StartAllSendPortGroups Specifies all send port groups to be started
StartAllSendPorts Specifies all send ports to be started
StartReferencedApplications Specifies all referenced applications to be started
StartAll Specifies all of the preceding to be enabled and started

 

Table 19. ApplicationStopOption Enumeration
Enumeration Value Description
UndeployAllPolicies Specifies all policies to be undeployed
DisableAllReceiveLocations Specifies all receive locations to be disabled
UnenlistAllOrchestrations Specifies all orchestrations to be unenlisted and stopped
UnenlistAllSendPortGroups Specifies all send port groups to be unenlisted and stopped
UnenlistAllSendPorts Specifies all send ports to be unenlisted and stopped
StopReferencedApplications Specifies referenced applications to be stopped
StopAll Specifies all of the preceding options

In order to start your application, you can use the code shown in Listing 8.

Example 8. Starting Biztalk Application
using System;
using Microsoft.BizTalk.ExplorerOM;

namespace BTSApplication
{
    class Program
    {

        static void Main(string[] args)
        {
            BtsCatalogExplorer catalog = new BtsCatalogExplorer();
            catalog.ConnectionString = "Server=.;Initial Catalog=BizTalkMgmtDb;
Integrated Security=SSPI;";
            Application app = catalog.Applications["PROBIZTALK Application"]
            app.Start(StartApplicationOptions.StartAll);
        }
    }
}

 
4.3. Btsassembly

The last class we are going to consider is BtsAssembly. Using the properties of this class listed in Table 20, you can get access to the collections of compiled artifacts contained in the assembly.

Table 20. BtsAssembly Class Properties
Property Name Description
Application Read-only. Returns the application this assembly is associated with.
BtsCatalogExplorer Read-only. Returns the IBtsCatalogExplorer interface, which represents the database hosting the assembly.
Culture Read-only. Returns the culture of the assembly.
DisplayName Read-only. Returns the display name of the assembly.
IsSystem Read-only. Indicates whether or not the assembly is system (deployed during Biztalk installation).
Name Read-only. Returns the name of the assembly.
Orchestrations Read-only. Returns the collection of orchestrations in the assembly.
Pipelines Read-only. Returns the collection of pipelines in the assembly.
PortTypes Read-only. Returns the collection of port types in the assembly.
PublicToken Read-only. Returns the public token of the assembly.
Roles Read-only. Returns the collection of roles in the assembly.
Schemas Read-only. Returns the collection of schemas in the assembly.
Transforms Read-only. Returns the collection of maps in the assembly.
Version Read-only. Returns the version of the assembly.

Assuming you have a deployed assembly named BTSOrchestrations, Listing 9 shows how you can print out orchestration names contained in this assembly using properties of the BtsAssembly class.

Example 9. Enumerating Orchestrations
using System;
using System.Text;
using Microsoft.BizTalk.ExplorerOM;

namespace EnumerateOrchestrations
{
    class Program
    {
        static void Main(string[] args)
        {
            EnumerateOrchestrations();
            Console.ReadKey();
        }

 

public static void EnumerateOrchestrations()
        {
            BtsCatalogExplorer catalog = new BtsCatalogExplorer();
            catalog.ConnectionString = "Server=.;Initial Catalog=BizTalkMgmtDb;
Integrated Security=SSPI;";
            BtsAssembly assembly = catalog.Assemblies["BTSOrchestrations"];

            foreach (BtsOrchestration orch in assembly.Orchestrations )
            {
                Console.WriteLine("\tOrchestrationName:{0}",
                     orch.FullName);

            }
        }
    }
}

 

As you see, programming using ExplorerOM is not very complicated. Once you get a fundamental idea how classes representing BizTalk artifacts are related to each other, the rest is quite straightforward. For the full list of classes and interfaces, please refer to the product documentation.