BizTalk Admin: Powershell script to save suspended messages and terminate suspended instances.

My latest BizTalk administration powershell scripting mission has been to save suspended messages and terminate all suspended service instances. WMI exposes both message instances and service instances and corresponding methods.


The following script is in two steps. First all suspended messages are saved to file and then all suspended service instances are terminated. This script is used as part of a deployment process when the BizTalk cluster is not taking any messages. If the server is actively processing messages, a message could get suspended between the two steps and not get saved but the owning service instance could be terminated.

I have been thinking that one could use the serviceinstanceid to connect directly to the service instance from the message instance and terminate it then thereby avoiding the possibility of deleting a service instance without its corresponding message being saved. However, routing failure reports cannot be saved, (attempting to save them causes an exception) so the routing failure messages and service instances would still need to be cleaned up.
The simplest form of this script looks like this(note that blog software wraps the code):

$nameSpace ="root\MicrosoftBizTalkServer"
$path = "c:\messagedump" 

$filter="(ServiceClass=1 OR ServiceClass=4) AND (ServiceInstanceStatus=4 OR ServiceInstanceStatus=32)"
get-wmiobject MSBTS_MessageInstance -namespace $nameSpace -filter $filter | invoke-wmiMethod -name SaveToFile -arg $path > $null

$filter="(ServiceStatus=4 OR ServiceStatus=32)"
get-wmiobject MSBTS_ServiceInstance -namespace $nameSpace -filter $filter | invoke-wmiMethod -name Terminate > $null

The first filter specifies orchestration or messaging service classes that are suspended(resumable) or suspended(not resumable). All message instance meeting this criteria get returned by the call to get-wmiobject and are piped directly into invoke-wmiMethod. The SaveToFile method exposed by WMI has a path parameter specifying where messages should be written.

Invoke-wmiMethod returns information that is not particularly meaningful in this context so it gets piped out to $null to minimize clutter.

The second filter specifies all resumable and non-resumable service instances and is used to select the service instances. Again the results are piped directly to Invoke-wmiMethod which will invoke the Terminate method. The terminate method has no parameters.

For further reference: here is the MSDN documentatation for the Service Instance Status codes http://msdn.microsoft.com/en-us/library/ee268242(v=bts.10).aspx and for Message Instance Service Class http://msdn.microsoft.com/en-US/library/ee253972(v=bts.10).aspx

In the dev and test environments we don't normally want to save the suspended messages so I extended the script to accept parameters for flexibility. I also had some exceptions during development so I added a function to handle each message with a try/catch. The exception information will be printed but does not stop the processing. This would allow for eventually finetuning the catches if I wanted to account for specific errors.

The longer version of the script looks like this(again beware of line wrapping):

# define parameters: $path is where messages will be saved
# $save - a switch to trigger saving of suspended messages
# $purge - a switch to trigger purging suspended service instances

param([string] $path, [switch] $save, [switch] $purge)
$nameSpace ="root\MicrosoftBizTalkServer"
 
function Save-Message ($messageInstance)
{
  try
  {
    $messageInstance.SaveToFile($path) > $null
  }
  catch
  {
    $messageInstance.MessageInstanceId
    $_.Exception.GetType().FullName
    $_.Exception
  }
}
 
If ($save) {
  if (! $path) { $path = ".\messages"; }
  if (! (Test-Path $path)) { mkdir $path }

  $filter="(ServiceClass=1 OR ServiceClass=4) AND (ServiceInstanceStatus=4 OR ServiceInstanceStatus=32)"
   
  get-wmiobject MSBTS_MessageInstance -namespace $nameSpace -filter $filter | %{Save-Message($_)}
}
   
if ($purge) {
  $filter="(ServiceStatus=4 OR ServiceStatus=32)"
  get-wmiobject MSBTS_ServiceInstance -namespace $nameSpace -filter $filter | invoke-wmiMethod -name Terminate > $null
}

The main changes here are that the path becomes a parameter to the script. If the path is not specified then a default path is used. If the path doesn't exist it will be created. I also added a save and a purge switch to allow complete flexibility around saving and terminating.

I also call the SaveToFile method directly on the message object instead of using invoke-wmiMethod. In case you are new to powershell, the % operator used before the call to Save-Message is an alias for for-each.

Powershell scripts to stop/start BizTalk Applications

We are finally almost finished with a migration project from BizTalk 2006 to BizTalk 2010. Some of my 'tools' need updating. First up is my application start/stop utility since this is the only one that flat out doesn't work.

Out of curiosity I wanted to test different methods of accessing the BizTalk applications. WMI was automatically out because it doesn't expose BizTalk applications. My options were using the BizTalk Explorer OM which is part of the BizTalk installation or the BizTalkFactory Powershell Provider on CodePlex which requires an installation. It is pretty common for production environments to have strict limitations on what third-party code can be installed so the BizTalkFactory route is not always an option.

This first example uses the BizTalk Explorer OM. Beware of line wrapping from the blog software.

# declare -stop -start switch parameters
param([switch] $start, [switch] $stop)
 
 # Get local BizTalk DBName and DB Server from WMI
 $btsSettings = get-wmiobject MSBTS_GroupSetting -namespace 'root\MicrosoftBizTalkServer'
 $dbInstance = $btsSettings.MgmtDbServerName
 $dbName = $btsSettings.MgmtDbName
 
 # Load BizTalk ExplorerOM
 [void] [System.reflection.Assembly]::LoadWithPartialName("Microsoft.BizTalk.ExplorerOM")
 $BizTalkOM = New-Object Microsoft.BizTalk.ExplorerOM.BtsCatalogExplorer
 $BizTalkOM.ConnectionString = "SERVER=$dbInstance;DATABASE=$dbName;Integrated Security=SSPI"


 if ($stop)
 {
   $BizTalkOM.Applications | where-object{$_.status -eq "started"}  | ForEach-Object{ $_.stop("StopAll")}
   $BizTalkOM.SaveChanges()  
 } 
 if ($start)
 {
   $BizTalkOM.Applications | where-object{$_.status -eq "stopped"}  | ForEach-Object{ $_.start("StartAll")}
   $BizTalkOM.SaveChanges()  
 }
 

The very first line sets up parameters so this script can be called with a -start or -stop switch (or both for a restart).

I prefer to have universal scripts that find their own BizTalk databases without hardcoding server names into scripts since we have multiple enironments. In this case I get the database server and management database information from WMI.

The next step is to load the BizTalk ExplorerOM and connect it to the BizTalk database.

Finally the applications are filtered on their status and then stopped or started using the ForEach-Object. Once all applications have been set to stop or start call SaveChanges to actually commit the start or stop.

The following example demonstrates using the BizTalkFactory PowerShell Provider.

# declare -start -stop switch parameters
param([switch] $start, [switch] $stop)

 # Get local BizTalk DBName and DB Server from WMI
 $btsSettings = get-wmiobject MSBTS_GroupSetting -namespace 'root\MicrosoftBizTalkServer'
 $dbInstance = $btsSettings.MgmtDbServerName
 $dbName = $btsSettings.MgmtDbName
 
 new-psdrive -name Biztalk -psprovider Biztalk -root biztalk:\ -instance $dbInstance -database $dbName

 if ($stop) { get-childitem -path biztalk:\applications\* | where-object {$_.status -eq "started"} | stop-application }
 
 if ($start) { get-childitem -path biztalk:\applications\* | where-object {$_.status -eq "stopped"} | start-application }

This script sets up the BizTalkFactory PowerShell Provider instead of the BizTalkExplorerOM.

The other difference is piping the filtered applications into the BizTalkFactory PowerShell Provider stop and start methods rather than the foreach-object loop.

Both of these scripts are pretty compact so the deciding factor becomes whether the BizTalkFactory PowerShell Provider is even an option in a specific environment.

I have a third version that follows a pattern Tomas Restrepo uses for starting and stopping host instances.

I mainly like this pattern because it allows for checking the status of an application just before starting or stopping it. In the previous examples the where-object returns a collection of applications which may be dependent on each other so some of them may be started already earlier in the loop.

In this example, I also added the functionality for specifying a specific application. Note the change to the parameter definition and the new get-applications function. If no application is specified then all applications will be processed.

# declare -stop -start switch parameters
param([switch] $start, [switch] $stop, [string] $app)
 
 function start-application($application)
 {
    # If the application is stopped, start it.
    if ( $application.status -eq "Stopped")
    {
      "Starting application " + $application.name
      $application.Start("StartAll")
    }
 }

 function stop-application($application)
 {
    # If the application is started, stop it.
    if ( $application.status -eq "Started")
    {
      "Stopping application " + $application.name
      $application.Stop("StopAll")
    }
 }

 function get-applications()
 {
    #if there is an application specified in the command line parameter, return just that application
    if ($app)
      { return $BizTalkOM.Applications[$app] }
    else
      { return $BizTalkOM.Applications }
 }

 # Get local BizTalk DBName and DB Server from WMI
 $btsSettings = get-wmiobject MSBTS_GroupSetting -namespace 'root\MicrosoftBizTalkServer'
 $dbInstance = $btsSettings.MgmtDbServerName
 $dbName = $btsSettings.MgmtDbName
 
 # Load BizTalk ExplorerOM
 [void] [System.reflection.Assembly]::LoadWithPartialName("Microsoft.BizTalk.ExplorerOM")
 $BizTalkOM = New-Object Microsoft.BizTalk.ExplorerOM.BtsCatalogExplorer
 $BizTalkOM.ConnectionString = "SERVER=$dbInstance;DATABASE=$dbName;Integrated Security=SSPI"

 # if no commandline parameters are supplied do a stop and a start
 if ( !($stop) -and !($start) )
 {
    $stop = $true
    $start = $true
 } 

 if ($stop) 
{
   get-applications | %{stop-application($_)}
   
   # Commit changes
   $BizTalkOM.SaveChanges()  
  }

 
 if ($start)
 {
   get-applications | %{start-application($_)}

   # Commit changes
   $BizTalkOM.SaveChanges()  
 }

Just like the other scripts I use stop and start switch parameters and WMI to find out what BizTalk database to use. The stop and start functions give the opportunity to do a little more with each application object. I could have crammed them into one liners but they would not have been as easy to read. Since PowerShell is not very wide-spread where I work readability is important. The drawback is it makes the script look more complicated.