BizTalk 2006 : Deploying and Managing BizTalk Applications - Administrative Tools (part 3) - ExplorerOM

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.

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 tored in the Management Database.

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 BtsCatalog- Explorer 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.

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();
            }
        }
    }
}

					  

BizTalk Server 2006 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.

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.

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. Not a problem if you only had 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 2006 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.

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);
        }
    }
}

					  

BtsAssembly

The last class we are going to consider in this section is the 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.

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 will be quite straightforward. For the full list of classes and interfaces, please refer to the product documentation.