Lesson 4: Monitoring the Order Service with Windows PowerShell

Article
09/12/2012

Time to complete: 25 minutes

Objective: To learn how to monitor real-time and historical monitoring data by using Microsoft AppFabric 1.1 for Windows Server cmdlets for Windows PowerShell.

Purpose: The purpose of this lesson is to help you become more familiar with instance information reported by using AppFabric cmdlets for Windows PowerShell, and how to use that information to control instances.

Prerequisites

Note the following prerequisites before beginning this lesson:

You must complete Lesson 3: Configuring the Order Service with Windows PowerShell before beginning this lesson.

Procedure

You will perform the following exercises in this lesson:

Report monitoring information with Windows PowerShell.
Control a workflow instance with Windows PowerShell.
Use Windows PowerShell to view tracked workflow events from the AppFabric monitoring database.

Reporting Monitoring Information with Windows PowerShell

To report WF instances for the OrderWorkflowService deployed with the Order Service application

Run OrderClient.exe from the C:\DublinTutorial\OrderServiceSolution\Completed\OrderClient\bin\Debug directory. This file was built in Lesson 2: Deploying the Order Service Application with Windows PowerShell. You can copy the following command into Windows PowerShell to run the OrderClient.
```
C:\DublinTutorial\OrderServiceSolution\Completed\OrderClient\bin\Debug\OrderClient.exe
```
Click Submit on the Contoso.com Order Form. Verify that the status section at the bottom of the form shows Your order has been received before continuing. After this is displayed by the form, an instance of the OrderWorkflowService is running simulating the processing of an order.
Make a note of the time so you can cross-reference with the creation time of a workflow instance.
To report workflow instances of the OrderWorkflowService by using the AppFabric cmdlets, execute the following command in Windows PowerShell.
```
Get-ASAppServiceInstance -SiteName "OrderService_PS" -VirtualPath "/OrderWorkflowService/OrderWorkflow.xamlx" | fl InstanceId, Status, Condition, CreationTime, LastUpdateTime, SiteName, VirtualPath, ExceptionMessage
```
This command gets all instances of the OrderWorkflowService in the OrderService_PS database. The instances are piped into the Format-List cmdlet by using its fl alias to report only desired workflow properties.

Verify that your command generated a list of workflow instances similar to the following list.

InstanceId       : 95a25419-0d71-42c4-ab70-aa523ba603fc
Status           : Running
Condition        : Active
CreationTime     : 11/1/2009 2:04:48 AM
LastUpdateTime   : 11/1/2009 2:04:56 AM
SiteName         : OrderService_PS
VirtualPath      : /OrderWorkflowService/OrderWorkflow.xamlx
ExceptionMessage :

You can use this information to monitor instances for status and exception information.

Find an instance with the CreationTime you noted in step 3.

Controlling Workflow Instances with Windows PowerShell

In this section you will suspend, resume, and stop a workflow instance.

Run OrderClient.exe again to make sure you have an instance in a running state. The following command in Windows PowerShell runs the OrderClient.
```
C:\DublinTutorial\OrderServiceSolution\Completed\OrderClient\bin\Debug\OrderClient.exe
```
Click Submit on the Contoso.com Order Form. Verify that the status section at the bottom of the form shows Your order has been received before continuing. After this is displayed by the form, an instance of the OrderWorkflowService is running simulating the processing of an order.
Make a note of the time so you can cross-reference with the creation time of a workflow instance.

Report the workflow instances of OrderWorkflowService by using the AppFabric cmdlets by executing the following command in Windows PowerShell.

Get-ASAppServiceInstance -SiteName "OrderService_PS" -VirtualPath "/OrderWorkflowService/OrderWorkflow.xamlx" –Status Running | fl InstanceId, Status, Condition, CreationTime, LastUpdateTime, SiteName, VirtualPath, ExceptionMessage

Verify that your command generated a list of workflow instances similar to the following list.

InstanceId       : 95a25419-0d71-42c4-ab70-aa523ba603fc
Status           : Running
Condition        : Active
CreationTime     : 11/1/2009 2:04:48 AM
LastUpdateTime   : 11/1/2009 2:04:56 AM
SiteName         : OrderService_PS
VirtualPath      : /OrderWorkflowService/OrderWorkflow.xamlx
ExceptionMessage :

Find an instance with the CreationTime you noted in step 3. Highlight the GUID value shown for the InstanceId by dragging the mouse over the GUID with the left mouse button pressed.
After the entire GUID is highlighted, right-click inside the highlighted GUID to copy the GUID to the Clipboard.
To suspend the running workflow instance identified by the InstanceId on your Clipboard, execute the following command, substituting your InstanceId for the GUID shown below.
```
Get-ASAppServiceInstance -InstanceId 95a25419-0d71-42c4-ab70-aa523ba603fc | Suspend-ASAppServiceInstance
```
This command gets the workflow instance identified by the InstanceId and pipes it into the Suspend-ASAppServiceInstance cmdlet to suspend the workflow.
To resume the workflow, execute the following command, substituting your InstanceId for the GUID shown below.
```
Get-ASAppServiceInstance -InstanceId 95a25419-0d71-42c4-ab70-aa523ba603fc | Resume-ASAppServiceInstance
```
This command gets the workflow instance identified by the InstanceId and pipes it into the Resume-ASAppServiceInstance cmdlet to resume the suspended workflow.
To stop and terminate the instance, execute the following command, substituting your InstanceId for the GUID shown below.
```
Get-ASAppServiceInstance -InstanceId 95a25419-0d71-42c4-ab70-aa523ba603fc | Stop-ASAppServiceInstance -Terminate
```
This command gets the workflow instance identified by the InstanceId and pipes it into the Stop-ASAppServiceInstance cmdlet to stop and terminate the workflow.

Viewing Tracked WF Events with Windows PowerShell

Based on the monitoring level and tracking profile configured for a workflow you can track many data points in a workflow. You set the monitoring level to HealthMonitoring by using the Set-ASAppMonitoring cmdlet in Lesson 2: Deploying the Order Service Application with Windows PowerShell. In this section you will generate a report of the WF events tracked for your instance. To report this information you will again use a script function that you will add to your Utility.ps1 script module.

In Windows PowerShell, enter the following command to open the Utility.ps1 script file.
```
Notepad .\Utility.ps1
```

Copy and paste the following script function into Notepad at the bottom of the Utility.ps1 script.

#============================================================================================#
#===                                                                                      ===#
#===                   Make sure the modules and snapins are loaded                       ===#
#===                                                                                      ===#
#============================================================================================#

function RegisterSnapIn($snapin)
{
$reg = Get-PSSnapin -Registered -Name $snapin
$added = Get-PSSnapin -Name $snapin -ErrorAction SilentlyContinue
if ($reg.Name -eq $snapin)
{
if ($added.Name -ne $snapin)
{
Add-PSSnapin $snapin
}
}
}


RegisterSnapIn "SqlServerProviderSnapin100"
RegisterSnapIn "SqlServerCmdletSnapin100"
Import-Module ApplicationServer



#============================================================================================#
#===                                                                                      ===#
#=== Retrieves WF Events for the given InstanceId from the specified monitoring database. ===#
#===                                                                                      ===#
#============================================================================================#


Function GetWFEvents($InstanceId,$database)
{

  $SQL = "SELECT  EventSources.Name AS WorkflowName, " +
                  "EventSources.Computer, " +
                  "EventSources.Site, " +
                  "EventSources.VirtualPath, " + 
                  "WfEvents.Id AS EventID, " + 
                  "WfEvents.WorkflowInstanceId, " +
                  "WfEvents.TimeCreated, " + 
                  "WfEvents.Name AS EventName, " + 
                  "WfEvents.State, " + 
                  "WfEvents.ActivityName, " + 
                  "WfEvents.Exception " +
          "FROM    EventSources INNER JOIN " +
                  "WfEvents ON EventSources.Id = WfEvents.EventSourceId " +
          "WHERE   WfEvents.WorkflowInstanceId = `'$InstanceId`'"


  Invoke-Sqlcmd -Query $SQL -Database $database
}

This script code makes sure that the components required for using the SQL Server cmdlets are loaded in the Windows PowerShell session. It also adds a utility function named GetWFEvents. That function allows you to query the monitoring database, retrieving workflow event information from the Wfevents view. The SQL query used by the function performs an inner join with the EventSources view to identify the workflow associated to the events.

Close Notepad and click Save to save the changes to Utility.ps1.
In Windows PowerShell execute the following command to import the new changes to Utility.ps1 into your Windows PowerShell session.
```
Import-Module .\Utility.ps1
```
Enter the following command in Windows PowerShell to use the new script function to query the workflow events recorded in the monitoring database for your workflow instance. Make sure to substitute your instance ID for the GUID shown below.
```
GetWFEvents 95a25419-0d71-42c4-ab70-aa523ba603fc OrderService_PS
```

The output in Windows PowerShell should be a list of events similar to the one shown below.

WorkflowName       : Microsoft.Samples.Dublin.Tutorials.OrderService.OrderWorkflowService.OrderWorkflow
Computer           : server1
Site               : OrderService_PS
VirtualPath        : /OrderWorkflowService/OrderWorkflow.xamlx
EventID            : 975
WorkflowInstanceId : 95a25419-0d71-42c4-ab70-aa523ba603fc
TimeCreated        : 2009-11-01 10:06:57.6974305
EventName          : Order completed
State              : Closed
ActivityName       :
Exception          :

WorkflowName       : Microsoft.Samples.Dublin.Tutorials.OrderService.OrderWorkflowService.OrderWorkflow
Computer           : server1
Site               : OrderService_PS
VirtualPath        : /OrderWorkflowService/OrderWorkflow.xamlx
EventID            : 976
WorkflowInstanceId : 95a25419-0d71-42c4-ab70-aa523ba603fc
TimeCreated        : 2009-11-01 10:06:57.6974305
EventName          : Order Service
State              : Closed
ActivityName       :
Exception          :

WorkflowName       : Microsoft.Samples.Dublin.Tutorials.OrderService.OrderWorkflowService.OrderWorkflow
Computer           : server1
Site               : OrderService_PS
VirtualPath        : /OrderWorkflowService/OrderWorkflow.xamlx
EventID            : 977
WorkflowInstanceId : 95a25419-0d71-42c4-ab70-aa523ba603fc
TimeCreated        : 2009-11-01 10:06:57.6974305
EventName          :
State              : Completed
ActivityName       :
Exception          :

The events reported in this step provide information about the status and state for activities and operations in the workflow. This information is useful to monitor the progress of a workflow during run time.

For more information about querying the monitoring database, see Monitoring Database Views and Tables.

You may also want to review the script sample Querying the SQL Monitoring Database using Windows PowerShell. For more information, see Samples.

What Did I Just Do?

In this lesson you learned how to report workflow information monitored by AppFabric and identify an instance. You also learned how to use the suspend, resume, and stop control operations on instances. Finally you used a new script function added to the Utility.ps1 script module to report workflow events from the monitoring database.

Next Steps

Lesson 5: Tracking the Workflow with Windows PowerShell