Jaa

Instance Store, Query, and Control Providers

  • Artikkeli

An instance store is a logical container of instances. It is the location where the instance data and metadata is stored. An instance store does not imply dedicated physical storage. An instance store could contain durable information in a SQL Server database or non-durable state information in a memory. The .NET Framework version 4 includes the SQL Workflow Instance Store, which is a concrete implementation of an instance store that enables workflows to persist instance data and metadata into a SQL Server 2005 or SQL Server 2008 database. For more information, see Instance Stores (https://go.microsoft.com/fwlink/?LinkId=181533) in the .NET Framework help. AppFabricsupports persisting of workflow service instances to only SQL Server 2008 databases.

To use an instance store with AppFabric tooling (Windows PowerShell cmdlets and IIS Manager extensions) and with the Workflow Management Service, you need to develop an instance store provider, an instance query provider, and an instance control provider for that instance store. The following sections describe these three types of providers.

Note

The instance query and control provider API is based on the .NET Framework 2.0 whereas the instance store provider API is based on the .NET Framework version 4

Instance Store Providers

An instance store provider for an instance store exposes an API that clients invoke to create instance store objects. The client uses the instance store object to save a workflow instance to the underlying instance store (for example: a SQL Server database) or to load an instance from the instance store.

AppFabric includes an instance store provider for the SQL Workflow Instance Store. To support a different instance store, you must create an instance store provider for that instance store. To create an instance store provider, you need to create a class deriving from the InstanceStoreProvider class and implement methods that create an instance store such as SqlWorkflowInstanceStore. For more information, see How To: Develop an Instance Store Provider.

Instance Query Providers

An instance query provider for an instance store lets you issue queries against the instance store. When you use a cmdlet such as Get-ASAppServiceInstance to query for instances in an instance store, the cmdlet creates a query provider object and invokes methods on the object. The query provider object creates queries and executes queries against the instance store, and returns query results to the cmdlet. The AppFabric IIS Manager extensions use cmdlets in most scenarios to query against instance stores. Therefore, they also depend on query providers.

All query providers implement the same API and provide an abstraction layer over underlying diverse instance stores. AppFabric includes an instance query provider for the SQL Workflow Instance Store, which lets you query for instances stored in the SQL Server persistence database. When the SQL query provider receives a query from a client (such as a Windows PowerShell cmdlet), it queries and retrieves instance data from the SQL Server database and returns the result set to the client. The implementation of the instance query provider for the SQL Workflow Instance Store is in Microsoft.ApplicationServer.StoreManagement.dll.

To support querying a different type of instance store, you need to have an instance query provider for that store. To create a custom query provider, you need to create a class deriving from the InstanceQueryProvider class and implement methods to run queries on behalf of the client. For more information, see How To: Develop an Instance Query Provider.

Instance Control Providers

An instance control provider allows a client to issue control commands against instances in an instance store and to retrieve commands that need to be executed against an instance. When you use an AppFabric Windows PowerShell cmdlet to control (suspend, resume, and so on) an instance in the instance store, the cmdlet creates a control provider object and invokes a method on the object to add the command to a command queue. The control provider maintains the command queue stored in the instance store. A generic host such as the Workflow Management Service (WMS) creates a control provider object and invokes a method on it to retrieve the command stored in the command queue and executes the command. The WMS notifies the control provider about failure or success of the execution. If the execution was successful, the control provider removes the command from the queue; otherwise, the WMS notifies the control provider about the failure and the provider takes an appropriate action.

In addition to forwarding a command from the command queue to the WMS, an instance control provider forwards a property bag that contains metadata about the instance against which the command was issued. This property bag contains the site name and virtual service path of the instance. The control provider obtains this metadata from the instance store. The WMS uses this metadata to obtain access to the Instance Control Endpoint (ICE) exposed by the service instance and invokes appropriate methods on the endpoint.

All query providers implement the same API and provide an abstraction layer over underlying diverse instance stores. AppFabric includes an instance control provider for the SQL Workflow Instance Store, which lets you issue control commands against instances stored in the SQL Server persistence database. The implementation of the instance control provider for the SQL Workflow Instance Store is in Microsoft.ApplicationServer.StoreManagement.dll. To support issuing commands against instances stored in a different type of instance store, you need to develop an instance control provider for that store.

To create a custom control provider, you need to create a class deriving from the InstanceControlProvider class and implement methods to add and retrieve commands to/from the command queue on behalf of clients. For more information, see How To: Develop an Instance Control Provider.

Instance Control Provider for the SQL Workflow Instance Store

AppFabric includes an instance control provider for the SQL Workflow Instance Store. The instance control provider maintains the command queue in a SQL Server database. When you execute a control cmdlet against the SQL Workflow Instance Store, the instance control provider receives the request and stores the command information in the command queue in the SQL Server database. The WMS uses the instance control provider to retrieve the command from the command queue, executes the command against the SQL Workflow Instance Store, and deletes the command from the command queue if the command execution is successful. The implementation of the instance control provider for the SQL Workflow Instance Store is in Microsoft.ApplicationServer.StoreManagement.dll.

The following points apply to the instance control provider for the SQL Workflow Instance Store:

  • It immediately (synchronously) processes the Delete command. All other commands are enqueued in (added to) the command queue before the control provider hands over the commands to WMS for processing.

  • The command queue is a first-in-first-out (FIFO) queue. The control provider adds a new command at the end of the queue and reads the command from the front. The control provider returns the oldest command that is not locked to the WMS.

  • The control provider can store only one command per an instance in the queue. When the provider receives an enqueue request for a command for an instance for which a command already exists in the queue, it overwrites the existing command if the command is not locked. If the command is locked or if the command is in Pending state, the control provider returns an error.

  • The control provider places a temporary lock after it reads a command from the command queue. This lock expires after 65 seconds. After receiving a notification from the WMS about successful execution of the command, the provider removes the command from the command queue.

  • The control provider retries a command five times if the command execution fails. The command queue maintains a counter of failed execution attempts. If the execution of the command fails for the fifth time, the provider removes the command from the command queue.

  • The control provider maintains a command-execution error log in the database. This log stores metadata about failed commands and the reasons for failures. The log contains at most one failed command per instance. Each log entry contains the command type, instance ID, error code, error message, time of last execution attempt, the computer ID on which the command execution was performed, and the number of attempted executions.

    A log entry for an instance is removed when a new command is enqueued for the instance, or when a user removes the instance from the instance store. A user can remove the instance by using a cmdlet (for example: Remove-ASAppServiceInstance).

  • The control provider dequeues commands in batches of 10.

See Also

Concepts

How To: Develop an Instance Store Provider
How To: Develop an Instance Query Provider
How To: Develop an Instance Control Provider
How To: Configure Instance Store, Query, and Control Providers

  2012-09-12