Export (0) Print
Expand All

WorkflowInstance Class

WorkflowInstance is a lightweight, per-instance runtime for executing a workflow program. It can be constructed to create a new workflow instance or from existing instance state. The APIs that WorkflowInstance::WorkflowInstanceControl exposes are the minimal set of runtime controls from which higher level operations can be implemented. This API set represents the entire breadth of functionality of the runtime. WorkflowInstance is an abstract class and relies on a host’s implementation of its abstract methods in order to provide host functionality such as synchronization, persistence, tracking, and extensions.

System::Object
  System.Activities.Hosting::WorkflowInstance
    System.Activities::WorkflowApplication

Namespace:  System.Activities.Hosting
Assembly:  System.Activities (in System.Activities.dll)

public ref class WorkflowInstance abstract

The WorkflowInstance type exposes the following members.

  NameDescription
Protected methodWorkflowInstanceInitializes a new instance of the WorkflowInstance class with the specified workflow definition.
Top

  NameDescription
Protected propertyControllerGets the WorkflowInstance::WorkflowInstanceControl instance for this WorkflowInstance.
Public propertyHostEnvironmentGets or sets the root environment for the workflow instance’s arguments and variables.
Public propertyIdGets the unique identifier for the workflow instance.
Protected propertyIsReadOnlyGets a value that indicates whether the workflow instance has been initialized.
Protected propertySupportsInstanceKeysGets a value that indicates whether the host supports the association of InstanceKeys() with a run-time instance.
Public propertySynchronizationContextGets or sets the SynchronizationContext used for scheduling the workflow instance.
Public propertyWorkflowDefinitionGets the workflow definition of the workflow instance.
Top

  NameDescription
Protected methodDisposeExtensionsCalls Dispose() on all extensions that implement IDisposable.
Public methodEquals(Object)Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Protected methodGetExtension<T>Returns an extension of the specified type.
Protected methodGetExtensions<T>Returns all extensions found for the specified type.
Public methodGetHashCodeServes as a hash function for a particular type. (Inherited from Object.)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Protected methodInitialize(Object)Called by the host to initialize the workflow instance with the workflow run-time state.
Protected methodInitialize(IDictionary<String, Object>, IList<Handle>)Called by the host to initialize the workflow instance with the argument values and execution properties.
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Protected methodOnBeginAssociateKeysCalled by the workflow runtime to notify the host that new instance keys should be associated with this instance.
Protected methodOnBeginFlushTrackingRecordsAsynchronous call to ask host to flush pending tracking records to tracking participants.
Protected methodOnBeginPersistAsynchronous call to ask the host to persist the workflow.
Protected methodOnBeginResumeBookmarkCalled by the workflow runtime to notify the host that a resume bookmark operation is beginning.
Protected methodOnDisassociateKeysCalled by the workflow runtime to notify the host that a certain set of instance keys should no longer be associated with this instance.
Protected methodOnEndAssociateKeysCalled by the workflow runtime to notify the host that an associate keys operation is complete.
Protected methodOnEndFlushTrackingRecordsCalled by the workflow runtime to notify the host when the flush tracking records operation is complete.
Protected methodOnEndPersistCalled by the workflow runtime to notify the host that a persist operation is complete.
Protected methodOnEndResumeBookmarkCalled by the workflow runtime to notify the host that a resume bookmark operation is complete.
Protected methodOnNotifyPausedCalled by the workflow runtime to notify the host that the workflow instance has transitioned from the running state to the paused state.
Protected methodOnNotifyUnhandledExceptionCalled by the workflow runtime to notify the host an unhandled exception has occurred in the workflow instance.
Protected methodOnRequestAbortCalled by the workflow runtime to notify the host that an abort operation has been requested for the workflow instance.
Protected methodRegisterExtensionManagerCalled by the host to register the specified extension manager, validate that all required extensions are present, and to initialize the collection of extensions to be used.
Protected methodThrowIfReadOnlyThrows an InvalidOperationException if the workflow instance has been initialized, as determined by IsReadOnly.
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)
Top

WorkflowInstance is single threaded and assumes that the host synchronizes all access to it. An attempt to call multiple APIs simultaneously will result in an InvalidOperationException being thrown.

Internally, a WorkflowInstance has two states: Running and Paused. The only way to cause the runtime to transition from paused to running is to call Run(). All actions (except Pause) can only be taken while the runtime is Paused. The runtime will become spontaneously Paused in the following situations:

  • An error fatal to the runtime has occurred. The host will be signaled through OnRequestAbort(Exception) (which does not signal a transition to Paused) and then notified through OnNotifyPaused().

  • An exception in the workflow was uncaught and escaped the root. The host will be notified through the OnNotifyUnhandledException(Exception, Activity, String) method.

  • The scheduler has run out of work items and is now Idle. The host will be notified through the OnNotifyPaused() method. Note that the scheduler could have run out of work items because the instance is idle or because the instance is complete. The State value of the Controller property can be used to differentiate between the two.

The host can request a change from Running to Paused by calling the RequestPause() or PauseWhenPersistable() methods of the WorkflowInstance::WorkflowInstanceControl instance returned by the Controller property. This request should not be considered to have a specific response meaning that the host should not attempt to correlate an OnNotify* or OnRequestAbort(Exception) with a specific call to pause. In response to a pause request, the runtime may transition to Paused and call OnNotifyPaused() while the scheduler still has pending work items. The State value of the Controller property can be used to determine whether the scheduler has no more work or was interrupted by a request to pause.

The RequestPause() method of the WorkflowInstance::WorkflowInstanceControl instance returned by the Controller property is the only method which can be called while the WorkflowInstance is in the Running state. All other methods will throw an InvalidOperationException if called.Given the rules for how WorkflowInstance transitions from one state to another, the public notion of Running and Paused can be defined as follows:

  • Running – The state between a call to Run() and the next WorkflowInstance.OnNotify*.

  • Paused – The state between the last WorkflowInstance.OnNotify* and the next call to Run().

.NET Framework

Supported in: 4

.NET Framework Client Profile

Supported in: 4

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Community Additions

ADD
Show:
© 2014 Microsoft