Table of Contents

Class Activity

Namespace
Acuit.Pinpoint.Workflows.Activities
Assembly
Acuit.Pinpoint.Workflows.dll

A workflow activity that does not return a result value.

public abstract class Activity : IActivity
Inheritance
Activity
Implements
Derived
Inherited Members

Examples

public class MyActivity : Activity
{
    public ValueSource<int> InputArgument { get; set; }

    protected override async Task OnExecuteAsync(ActivityContext context, CancellationToken cancellationToken)
    {
        if (context is null) throw new ArgumentNullException(nameof(context));
        var inputArgument = await context.EvaluateRequiredArgumentAsync(InputArgument, nameof(InputArgument), cancellationToken).ConfigureAwait(true)
        var someService = context.ServiceProvider.GetRequiredService<ISomeService>();
        // Perform the activity logic asynchronously here...
    }
}

Remarks

A workflow activity executes with its own context instance that reflects its parameters and variables and has its own private state.

Arguments for the activity should be implemented via properties, following these guidelines:

  • Arguments of specific types should use ValueSource<T>. For example: 
    public ValueSource<string> Name { get; set; }
  • Optional arguments should use nullable types. For example: 
    public ValueSource<TimeSpan?> Timeout { get; set; }
  • Default values for arguments should be specified when appropriate. For example: 
    public ValueSource<bool> FailIfInvalid { get; set; } = true;
  • Arguments where the type needed will not be known until the activity executes should use ValueSource. For example (from SetVariable.Value): 
    public ValueSource Value { get; set; }
  • Collection<T> should be used for collection properties (e.g., as opposed to something like IList<T>) for better compatibity with the Visual Studio XAML editor. For example: 
    public Collection<IActivity> Activities { get; } = new Collection<IActivity>();
  • Child activities that can be of any type (whether it produces a result or not) should use IActivity. For example: 
    public IActivity Body { get; set; }
  • ContentPropertyAttribute should be used to indicate the XAML content property, when appropriate. For example: 
    [ContentProperty(nameof(Body))]

While executing the activity, derived classes should generally do the following.

  1. Evaluate and validate all argument properties (except for any whose usage depends on later evaluation). The helper extension methods in ValidationExtensions can be used to make this easier via fluent validation.
  2. Acquire required services via GetRequiredService<T>(IServiceProvider) on the ServiceProvider property of the provided ActivityContext.
  3. Perform the activity-specific execution logic asynchronously, ensuring the provided CancellationToken is checked as appropriate during execution.

In general, performance should be top priority. Expressions should be evaluated and services should be acquired only once determined they will actually be used. Second priority is exposing errors as soon as possible, so, once determined they will be used, expressions should be evaluated and services should be acquired as soon as possible. Property expressions should be evaluated when the activity starts execution unless the property usage requires otherwise (e.g., for a condition property that is not checked at the beginning of the execution).

Properties

DisplayName

Gets or sets the display name of the activity.

public string DisplayName { get; set; }

Property Value

string

Remarks

This is used by debug log messages.

Parameters

Gets the list of input parameters defined for the activity.

public Collection<ParameterBase> Parameters { get; }

Property Value

Collection<ParameterBase>

Variables

Gets the list of variables defined for the activity.

public Collection<Variable> Variables { get; }

Property Value

Collection<Variable>

Methods

OnExecuteAsync(ActivityContext, CancellationToken)

Derived classes must implement this to perform the activity.

protected abstract Task OnExecuteAsync(ActivityContext context, CancellationToken cancellationToken)

Parameters

context ActivityContext

The activity context.

cancellationToken CancellationToken

The cancellation token used to request canceling the activity.

Returns

Task

A task that represents the asynchronous operation.

Exceptions

ArgumentNullException

context is null.

InvalidOperationException

A service required by the activity is not available, or a required activity property value is not set. This will only occur asynchronously, wrapped in an AggregateException as the faulted task's Exception.

Exception

An error occurred while performing the activity. This will only occur asynchronously, wrapped in an AggregateException as the faulted task's Exception.

ToString()

Returns a string that represents the current object.

public override string ToString()

Returns

string

A string that represents the current object.

Remarks

This is expected to produce a string suitable for labeling this activity in a workflow diagram. It should be as specific as possible, but while keeping it very short. In general, it should be the short name of the class (as that is how it would typically be defined in the workflow XAML), optionally followed by other property values of interest in a diagram. The default implementation returns the short name of the class.