Instance Query and Control

This sample shows how to use the persistence store query and control providers. The query provider exposes a C# API that allows the user to query for instances stored in a persistence store. The control provider exposes a C# API that allows the user to issue control commands (suspend, resume, cancel, terminate, delete) against an instance stored in a persistence store.

This sample contains a WF test service, a Windows console application for querying for instances, and a Windows console application for controlling instances.

Prerequisites

• Internet Information Services (IIS) version 7.0

• Persistence store initialized

• Visual Studio 2010 and Windows Server AppFabric on the same computer

Sample Location and Files

The readme document is located in <samples>\Samples\Hosting\InstanceQueryAndControl.

All files that you will need to run this sample are located in <samples>\Samples\Hosting\InstanceQueryAndControl:

• The folder InstanceControl contains all files that are required for the instance control sample application.

• The folder InstanceQuery contains all files that are required for the instance query sample application.

• The folder TestWorkflow contains all files that are required for the sample workflow.

• The solution file InstanceQueryAndControl.sln defines the solution that builds all of the sample artifacts.

Setting Up and Running This Sample

1. Create a persistence store if you have not done so during Windows Server AppFabric Setup.

   1. Run C:\Windows\System32\AppFabric\Microsoft.ApplicationServer. Configuration.exe as Administrator. In the Configure Worker step, select the Set persistence configuration check box. Select sqlStoreProvider as your persistence provider and then click Configure.

   2. In the Persistence SQL Store Configuration window, select the Add persistence store registration to root web config and Initialize persistence store check boxes. Specify the name of the persistence store database as ApplicationServerWorkflowInstanceStore. Click OK to create a persistence store database with the specified name. If you decide to choose a different database name the sample code needs to be changed (see below).

2. If you run this sample on a 64-bit system, copy the file C:\Windows\System32\AppFabric\Microsoft.ApplicationServer.StoreManagement.dll into your project folder.

   Note

   You will use this path in step 3.

3. Build the solution.

   1. Open Visual Studio 2010 as Administrator: Click Start --> All Programs --> Microsoft Visual Studio 2010. Right-click Microsoft Visual Studio 2010 and select Run as administrator.

   2. Open the sample project: In Visual Studio, click File --> Open --> Project/Solution. Select the sample solution file <samples>\Samples\InstanceQueryAndControl\InstanceQueryAndControl.sln. When opening the file Visual Studio warns that the local IIS URL for the sample service has not been created yet. Confirm the creation of the new virtual directory.

   3. If you run this sample on a 64-bit system, execute the following steps for InstanceQuery and the InstanceControl project: In line 17 of the file Program.cs change the path of the file Microsoft.ApplicationServer.StoreManagement.dll to the location you copied the file to in step 2.

   4. This sample assumes that the workflow persists in the persistence database ApplicationServerWorkflowInstanceStore that is hosted by SQL Express. You can change the database name and SQL server instance in lines 44 and 45 of Program.cs of the InstanceControl project and lines 37 and 38 of Program.cs of the InstanceQuery project.

   5. Press F6 to build the solution. This automatically deploys the TestWorkflow application to IIS.

4. Configure the TestWorkflow application.

   1. Open IIS Manager: Click Start -->Control Panel->Administrative Tools --> Information Services (IIS) Manager.

   2. Set the correct AppPool and enable the net.pipe protocol for the site.

      • In the IIS Connections window, select node <computer>/Sites/Default Web Site.

      • In the IIS Actions window, click Advanced Settings.

      • Change the Application Pool setting to ASP.NET v4.0.

      • Change the Enabled Protocols to http,net.pipe. Caution: There must be no space between the comma and net.pipe.

      • Click OK.

   3. Set the correct AppPool and enable the net.pipe protocol for the application.

      • In the IIS Connections window, select node <computer>/Sites/Default Web Site/TestWorkflow.

      • In the IIS Actions window, click Advanced Settings.

      • Change the Application Pool setting to ASP.NET v4.0.

      • Change the Enabled Protocols to http,net.pipe. Caution: There must be no space between the comma and net.pipe.

      • Click OK.

5. Create instances of the TestService.

   1. Open the WCF Test Client.

      • In the IIS Manager Connections window, select node <computer>/Sites/Default Web Site/TestWorkflow.

      • Right-click TestWorkflow and select Switch to Content View.

      • Right-click TestService.xamlx and select Browse. A Web browser starts and shows the welcome page of the TestService.

      • Open the WCF Test Client as follows: Open the WCF Test Client. Click Start --> All Programs --> Microsoft Visual Studio 2010 --> Visual Studio Tools --> Visual Studio Command Prompt (2010). At the command prompt, issue the command wcftestclient.

      • In the Web browser's URL window, copy the URL of the TestService (e.g., "https://localhost/TestWorkflow/TestService.xamlx"). In the WCF Test Client, right-click My Service Projects and select Add Service. When prompted for the endpoint address, paste the URL of the TestService.

   2. Invoke the TestService as follows:

      • In the WCF Test Client window, double-click the Invoke() node under the node IService (BasicHttpBinding_IService).

      • On the Invoke tab, click the (null) field in the Value column. Change the selection from (null) to System.Nullable<System.Int32>. Now expand the int node in the Name column. A new row appears with the Value 0.

      • Click Invoke. This creates an instance of the TestService that will run for 10 minutes.

      • Change the Value to 1 and click Invoke. This creates an instance of the TestService that will immediately complete.

      • Change the Value to 2 and click Invoke. This creates an instance of the TestService that will throw an exception and suspend.

6. Query for instances.

   1. In Visual Studio, make sure InstanceQuery is the default startup project and press F5 to query for instances. A console window opens and displays the three instances you created in step 5.b.

   2. Alternatively, execute the InstanceQuery command at a command prompt:

      • Open a command prompt. Execute the command <samples>\Samples\Hosting\InstanceQueryAndControl\InstanceQuery\bin\Debug\InstanceQuery.exe [List|Count|Group].

7. Control instances.

   1. At a command prompt, execute the command <samples>\Samples\Hosting\InstanceQueryAndControl\InstanceControl\bin\Debug\InstanceControl.exe <InstanceId> [Suspend|Resume|Cancel|Terminate|Delete]. Use the 20-character Instance ID GUID of any of the instances that you createdUse the 20-character Instance ID GUID of any of the instances that you created previously.

Removing This Sample

1. Delete all service instances of the TestWorkflow service from the persistence store. Open an Admin console window and issue the following commands:

   > powershell
   > import-module applicationServer
   > Get-ASAppServiceInstance -SiteName "Default Web Site" -VirtualPath "/TestWorkflow/TestService.xamlx" | Remove-AsAppServiceInstance
   

Demonstrates

The sample contains three projects:

• TestWorkflow implements a WF service. The service is hosted in IIS. Every time the service is invoked a new instance of the service is created. When invoking the service through the WCF Test Client, the user passes a parameter to the service. Depending on that parameter the instance runs for 10 minutes, immediately completes, or throws an exception.

• InstanceQuery implements a console application that issues a query against the persistence store and prints the results on the screen. The user must specify the query type, query parameters, and the connection string of the persistence store.

• InstanceControl implements a console application that issues a control command against an instance that resides in a persistence store. The user must specify the command type, instance ID, and the connection string of the persistence store.

Instance Query sample application

The instance query sample application demonstrates the functionality and API of the AppFabric query provider. The query provider allows the user to issue three types of queries:

• Obtain a list of instances that reside in a persistence store and whose properties match the query. This query returns an array of instanceInfo.

• Obtain the number of instances that reside in a persistence store and whose properties match the query. This query returns an int32.

• Obtain the number of instances that reside in a persistence store and whose properties match the query, and group them according to defined categories. This query returns an enumerable of type groupingResult.

For each query type the query provider provides an asynchronous API that executes the query. The input and return type vary with the query type. For all query types, the user can specify a set of query filters. The sample sets all of them to null, which means that the query picks up all instances that are in the store. In addition to the query filter parameters, the user has to provide the connection string of the persistence store. The sample assumes that the instances reside in the DefaultSqlWorkflowInstanceStore. It also assumes that the database uses Windows integrated security to authenticate database access.

When requesting a list of instances the user must specify the maximum number of instances returned and how the instances should be sorted. Currently the query provider only offers to sort by LastUpdatedTime or return an unsorted list.

When requesting a grouped count of instances the user must specify the grouping parameters. These parameters are supplied as a List<GroupingMode>. The first element defines the main group, and each following element defines a subgroup.

Instance Control sample application

The instance control sample application demonstrates the functionality and API of the AppFabric control provider. The control provider allows the user to issue a suspend, resume, cancel, terminate, or delete command against an instance. In addition to the command type and the instance ID the user must supply the service identifiers SiteName, RelativeApplicationPath, and VirtualPath. Those parameters are required for the WMS to compute the control endpoint of the service instance. (The service identifiers are required for Suspend, Resume, Cancel, and Terminate only. The Delete command is not issued against the control endpoint. Instead, it is directly executed in the database.)

In addition to the query filter parameters, the user must provide the connection string of the persistence store. The sample assumes that the instances reside in the DefaultSqlWorkflowInstanceStore. It also assumes that the database uses Windows integrated security to authenticate database access.

Note that the instance control sample application enqueues any Suspend, Resume, Cancel, or Terminate command in the command queue of the persistence store. The command is executed at a later point in time. Use the instance query sample application to see whether and when the command has been executed.

Note that a command for an instance can be enqueued only if there is no other pending command enqueued for that instance.

The following table describes the effect of commands when issued against instances in various states.