BizTalk Server 2009 : Administrative Tools (part 2) – WMI

3. WMI

Windows Management Instrumentation provides a standard way of managing a computer system. WMI allows you to

  • Gather information about systems.

  • Configure systems.

  • Fire or consume specific WMI events occurring on c = omputers or servers.

Tables 11 and 12 describe the different BizTalk WMI classes and events. To utilize these classes, you must use the WMI COM API or the System.Management assembly, which is a .NET COM Interop assembly. Listing 1 demonstrates how to create a host using WMI API from managed code.

Table 11. BizTalk WMI Classes
WMI Class Name Specific Methods Purpose
MSBTS_AdapterSetting None Registers new adapters.
MSBTS_DeploymentService Deploy, Export, Import, Remove Deploys/undeploys assemblies and imports/exports binding files.
MSBTS_GroupSetting
RegisterLocalServer,
UnRegisterLocalServer

 

Represents information about BTS Groups.
MSBTS_Host Start, Stop Represents a host. Used to start/stop all host instances in a given BizTalk host. It is also used to get/set host properties.
MSBTS_HostInstance
GetState, Install, Start, Stop,
Uninstall

 

Represents a host instance. Used to install/uninstall and start/stop a specific host instance in a given BizTalk host.
MSBTS_HostInstanceSetting None Represents host settings.
MSBTS_HostQueue
ResumeServiceInstancesByID,
SuspendServiceInstancesByID,
TerminateServiceInstancesByID

 

Resumes, suspends, or terminates service instances.
MSBTS_HostSetting None Sets host settings.
MSBTS_MessageInstance SaveToFile Represents a message instance.
MSBTS_MsgBoxSetting ForceDelete Represents a single Messagebox setting in the BizTalk Server Group.
MSBTS_Orchestration
Enlist, QueryDependencyInfo,
QueryInstanceInfo, Start,
Stop, Unenlist

 

Represents an orchestration. Used to start/stop and enlist/unenlist orchestrations.
MSBTS_ReceiveHandler None Represents a receive handler. Used to configure receive handlers.
MSBTS_ReceiveLocation Disable, Enable Represents a receive location. Used to enable and disable the receive location.
MSBTS_ReceiveLocation
Orchestration

 

None Represents all possible combinations of orchestrations and receive locations.
MSBTS_ReceivePort None Represents a receive port. Used to configure receive ports.
MSBTS_SendHandler None Represents a send handler. Used to configure send handlers.
MSBTS_SendPort Enlist, Start, Stop, Unenlist Represents a send port. Used to configure send ports.
MSBTS_SendPortGroup Enlist, Start, Stop, UnEnlist Represents a send port group. Used to start/stop and enlist/unenlist send port groups.
MSBTS_SendPortGroup2
SendPort

 

None Represents a many-to-many relationship between send port groups and send ports.
MSBTS_Server CheckIfCanInstallHost Instances, Start, Stop Represents a computer within a BizTalk Server Group. Used to start services on a given server.
MSBTS_ServerHost ForceUnmap, Map, Unmap Represents a mapping between BizTalk hosts and host instances. Used to map and unmap relationships.
MSBTS_ServiceInstance Resume, Suspend, Terminate Represents an instance of a service. Used to resume, suspend, and terminate services.
MSBTS_TrackedMessage
Instance

 

SaveToFile Represents a tracked message instance saved in the Messagebox or Archive databases. Used to save a message to a file.
Table 12. BizTalk WMI Events
WMI Event Name Specific Properties Purpose
MSTBS_MessageInstance
SuspendentEvent

 

ErrorCategory, ErrorDescription,
ErrorId, HostName, Message
InstanceID, MessageType,
ReferenceType, ServiceClass,
ServiceClassID, Service
InstanceID, ServiceTypeID

 

Represents a suspended event for a BizTalk Message Queuing (MSMQT) message instance
MSTBS_ServiceInstance
SuspendentEvent

 

ErrorCategory, ErrorDescription,
ErrorId, HostName, InstanceID,
ServiceClass, ServiceClassID,
ServiceStatus, ServiceTypeID

 

Represents a suspended event for a service instance
Example 1. Create Host Example Using Managed Code
[C#]
using System.Management;

      // Basic WMI operation - Create
      // sample to show MSBTS_HostSetting instance creation
      public void CreateHost(string ServerName, string HostName, int HostType,
string NTGroupName, bool AuthTrusted)
      {
         try
         {
            PutOptions options = new PutOptions();
            options.Type = PutType.CreateOnly;

            // Create a ManagementClass object and spawn a ManagementObject instance
            ManagementClass objHostSettingClass = new ManagementClass("\\\\" +
ServerName + "\\root\\MicrosoftBizTalkServer", "MSBTS_HostSetting", null);
            ManagementObject objHostSetting = objHostSettingClass.CreateInstance();

            // Set the properties for the Host
            objHostSetting["Name"] = HostName;
            objHostSetting["HostType"] = HostType;
            objHostSetting["NTGroupName"] = NTGroupName;
            objHostSetting["AuthTrusted"] = AuthTrusted;

            // Creating the host
            objHostSetting.Put(options);
            System.Console.WriteLine(string.Format("The Host '{0}'has been
created successfully", HostName ));
         }
         catch(Exception ex)

					  

 

{
            System.Console.WriteLine("CreateHost - " + HostName +
" - failed: " + ex.Message);
         }
      }

 

The same example using VBScript instead of managed code is shown in Listing 2.

Example 2. Create Host Example Using VBScript
[VBScript]
Option Explicit
' wbemChangeFlagEnum Setting
const UpdateOnly = 1
const CreateOnly = 2
Sub CreateHost (ServerName, HostName, HostType, NTGroupName, AuthTrusted)
   On Error Resume Next
   Dim objLocator, objService, objHostSetting, objHS

   ' Connects to local server WMI Provider BizTalk namespace
   Set objLocator = Createobject ("wbemScripting.SwbemLocator")
   Set objService = objLocator.ConnectServer(ServerName,
"root/MicrosoftBizTalkServer")

   ' Get WMI class MSBTS_HostSetting
   Set objHostSetting = objService.Get ("MSBTS_HostSetting")

   Set objHS = objHostSetting.SpawnInstance_

   objHS.Name = HostName
   objHS.HostType = HostType
   objHS.NTGroupName = NTGroupName
   objHS.AuthTrusted = AuthTrusted

   ' Create Host
   objHS.Put_(CreateOnly)

   CheckWMIError
   wscript.echo "Host - " & HostName & " - has been created successfully"
end Sub

					  

 

Another interesting task you can accomplish with WMI is to subscribe to MSTBS_MessageInstanceSuspendentEvent and MSTBS_ServiceInstanceSuspendentEvent. Consuming these events will allow you to handle certain situations gracefully in your BizTalk solution. For instance, when a mapping error occurs on a send or receive port, you could decide to send an e-mail to an administrator and automatically terminate the service instance. Listing 3 shows how to subscribe to a WMI event.

Example 3. Subscribing to a BizTalk WMI Event
using System.Management;

static public void ListenForSvcInstSuspendEvent()
 {
     try
     {
        // Set up an event watcher and a handler for the
MSBTS_ServiceInstanceSuspendedEvent event
       ManagementEventWatcher watcher =
new ManagementEventWatcher( new ManagementScope("root\\MicrosoftBizTalkServer"),
new EventQuery("SELECT * FROM MSBTS_ServiceInstanceSuspendedEvent") );

        watcher.EventArrived += new EventArrivedEventHandler(MyEventHandler);

        // Start watching for MSBTS_ServiceInstanceSuspendedEvent events
        watcher.Start();

        Console.WriteLine("Press enter to quit");
        Console.ReadLine();
        watcher.Stop();
     }
     catch (Exception ex)
     {
        Console.WriteLine("Error: " + ex.Message);
     }
  }

  static public void MyEventHandler(object sender, EventArrivedEventArgs e)
  {
     // Print out the service instance ID and error description upon receiving
     // of the suspend event
     Console.WriteLine("A MSBTS_ServiceInstanceSuspendEvent has occurred!");
     Console.WriteLine(string.Format("ServiceInstanceID: {0}",
e.NewEvent["InstanceID"]));
     Console.WriteLine(string.Format("ErrorDescription: {0}",
e.NewEvent["ErrorDescription"]));
     Console.WriteLine("");
  }