StellaOps.Workflow.Engine

Workflow engine: definition deployment, instance lifecycle, signal-driven task transitions, dead-letter handling and retention.

PackageStellaOps.Workflow.Engine
ComponentWorkflow
LicenceBUSL-1.1 (Workflow licence)
Package kindLibrary
Target frameworknet10.0

To add the package to a project, see Installing Stella Ops packages.

Namespaces

NamespaceTypes
StellaOps.Workflow.Engine.Authorization1
StellaOps.Workflow.Engine.Children4
StellaOps.Workflow.Engine.Constants7
StellaOps.Workflow.Engine.Definitions2
StellaOps.Workflow.Engine.Durability36
StellaOps.Workflow.Engine.Exceptions3
StellaOps.Workflow.Engine.Execution3
StellaOps.Workflow.Engine.ExternalActivities29
StellaOps.Workflow.Engine.History2
StellaOps.Workflow.Engine.HostedServices4
StellaOps.Workflow.Engine.Hosting3
StellaOps.Workflow.Engine.Licensing14
StellaOps.Workflow.Engine.Maps16
StellaOps.Workflow.Engine.Observability3
StellaOps.Workflow.Engine.Rendering2
StellaOps.Workflow.Engine.Scheduling3
StellaOps.Workflow.Engine.Services42
StellaOps.Workflow.Engine.Services.Converters4
StellaOps.Workflow.Engine.Signaling12

StellaOps.Workflow.Engine.Authorization namespace

TypeKindDescription
WorkflowTaskAuthorizationServiceclassDecides whether an actor may act on a task, through the registered assignment permission evaluator.

WorkflowTaskAuthorizationService class

public sealed class WorkflowTaskAuthorizationService

Decides whether an actor may act on a task, through the registered assignment permission evaluator.

Parameters

WorkflowTaskAuthorizationService(IWorkflowAssignmentPermissionEvaluator) constructor

public WorkflowTaskAuthorizationService(IWorkflowAssignmentPermissionEvaluator permissionEvaluator)

Decides whether an actor may act on a task, through the registered assignment permission evaluator.

Parameters

Evaluate(WorkflowAssignmentPermissionContext) method

public WorkflowAssignmentPermissionDecision Evaluate(WorkflowAssignmentPermissionContext context)

Evaluates an assignment permission.

Parameters

Returns

The decision.

StellaOps.Workflow.Engine.Children namespace

TypeKindDescription
WorkflowChildExecutionServiceclassRecords child workflow links: their start and completion, each with an outbox message for the parent, and their cancellation.
WorkflowChildLinkResultrecordThe link between a parent step and its child.
WorkflowCompleteChildRequestrecordA finished child workflow and its result.
WorkflowStartChildRequestrecordA child workflow to start and link to its parent step.

WorkflowChildExecutionService class

public sealed class WorkflowChildExecutionService

Records child workflow links: their start and completion, each with an outbox message for the parent, and their cancellation.

Parameters

WorkflowChildExecutionService(IWorkflowChildLinkStore, TimeProvider) constructor

public WorkflowChildExecutionService(IWorkflowChildLinkStore store, TimeProvider timeProvider)

Records child workflow links: their start and completion, each with an outbox message for the parent, and their cancellation.

Parameters

CancelAsync(string, long, CancellationToken) method

public Task<WorkflowChildLinkResult> CancelAsync(string linkId, long expectedVersion, CancellationToken cancellationToken = default)

Cancels a link. A completed or canceled link is returned as replayed.

Parameters

Returns

The link.

Exceptions

CompleteAsync(WorkflowCompleteChildRequest, CancellationToken) method

public Task<WorkflowChildLinkResult> CompleteAsync(WorkflowCompleteChildRequest request, CancellationToken cancellationToken = default)

Records a child result, canonicalized, with a WORKFLOW_CHILD_COMPLETED outbox message. A repeated completion with the same result hash is returned as replayed.

Parameters

Returns

The link.

Exceptions

StartAsync(WorkflowStartChildRequest, CancellationToken) method

public Task<WorkflowChildLinkResult> StartAsync(WorkflowStartChildRequest request, CancellationToken cancellationToken = default)

Records a child start with a WORKFLOW_CHILD_START outbox message. A start already recorded under the link is returned as replayed when it names the same child and request hash.

Parameters

Returns

The link.

Exceptions

WorkflowChildLinkResult record

public sealed record WorkflowChildLinkResult

The link between a parent step and its child.

WorkflowChildLinkResult() constructor

public WorkflowChildLinkResult()

Creates an instance of WorkflowChildLinkResult.

ChildWorkflowExecutionId property

public required string ChildWorkflowExecutionId { get; init; }

The child execution.

LinkId property

public required string LinkId { get; init; }

The link.

Replayed property

public required bool Replayed { get; init; }

Whether the operation had already been applied and was returned as recorded.

Status property

public required string Status { get; init; }

The link status.

WorkflowCompleteChildRequest record

public sealed record WorkflowCompleteChildRequest

A finished child workflow and its result.

WorkflowCompleteChildRequest() constructor

public WorkflowCompleteChildRequest()

Creates an instance of WorkflowCompleteChildRequest.

ChildWorkflowExecutionId property

public required string ChildWorkflowExecutionId { get; init; }

The child execution.

LinkId property

public required string LinkId { get; init; }

The link.

ResultDescriptorJson property

public required string ResultDescriptorJson { get; init; }

The child result descriptor, as JSON.

ResultSha256 property

public required string ResultSha256 { get; init; }

The SHA-256 of the result.

WorkflowStartChildRequest record

public sealed record WorkflowStartChildRequest

A child workflow to start and link to its parent step.

WorkflowStartChildRequest() constructor

public WorkflowStartChildRequest()

Creates an instance of WorkflowStartChildRequest.

ChildDefinitionCode property

public required string ChildDefinitionCode { get; init; }

The child workflow.

ChildDefinitionVersion property

public required string ChildDefinitionVersion { get; init; }

The child workflow version.

ChildWorkflowExecutionId property

public required string ChildWorkflowExecutionId { get; init; }

The child execution.

LinkId property

public required string LinkId { get; init; }

The link.

ParentScopeExecutionId property

public required string ParentScopeExecutionId { get; init; }

The parent scope.

ParentStepExecutionId property

public required string ParentStepExecutionId { get; init; }

The parent step.

ParentWorkflowExecutionId property

public required string ParentWorkflowExecutionId { get; init; }

The parent execution.

StartRequestSha256 property

public required string StartRequestSha256 { get; init; }

The SHA-256 of the child start request.

StellaOps.Workflow.Engine.Constants namespace

TypeKindDescription
ConstantsClassclassString values the engine stores and compares.
ConstantsClass.MapPoliciesclassThe fan-in and failure policies of a map step.
ConstantsClass.RetryBackoffKindsclassHow the delay between retries grows.
MessageKeysclassThe message ids of the engine’s business errors.
WorkflowInstanceStatusesclassThe statuses of a workflow instance.
WorkflowTaskEventTypesclassThe event types of a human task’s history.
WorkflowTaskStatusesclassThe statuses of a human task.

ConstantsClass class

public static class ConstantsClass

String values the engine stores and compares.

ChildCanceled constant

public const string ChildCanceled = "CANCELED"

Child link: the child was canceled.

ChildCompleted constant

public const string ChildCompleted = "COMPLETED"

Child link: the child completed and its result reached the parent.

ChildStartPending constant

public const string ChildStartPending = "START_PENDING"

Child link: the child start is queued.

ChildWaiting constant

public const string ChildWaiting = "WAITING"

A child link state that the engine sets on no link.

CursorCompacted constant

public const string CursorCompacted = "CURSOR_COMPACTED"

The timeline disposition when the requested events were compacted away.

DefinitionNotReadyCode constant

public const string DefinitionNotReadyCode = "DEFINITION_NOT_READY"

The refusal code of a start whose managed definition is not ready: not managed, another code, or no build and compatibility hashes.

DefinitionOriginManaged constant

public const string DefinitionOriginManaged = "MANAGED_EMBEDDED"

The origin of a managed definition.

DefinitionOriginOperator constant

public const string DefinitionOriginOperator = "OPERATOR_IMPORTED"

The origin of a definition an operator imported.

DurableOutboxPublished constant

public const string DurableOutboxPublished = "PUBLISHED"

Sent.

DurableOutboxReady constant

public const string DurableOutboxReady = "READY"

Appended, not yet sent.

ExecutionIntegrityReconciliationSchedule constant

public const string ExecutionIntegrityReconciliationSchedule = "STELLAOPS_EXECUTION_INTEGRITY_RECONCILIATION"

The name of the execution integrity reconciliation schedule.

OutboxInboxCompactionSchedule constant

public const string OutboxInboxCompactionSchedule = "STELLAOPS_OUTBOX_INBOX_COMPACTION"

The name of the outbox and inbox compaction schedule.

SafeProfile constant

public const string SafeProfile = "SAFE"

The execution console profile that shows only allowed state keys.

ServiceName constant

public const string ServiceName = "StellaOps.Workflow.Engine"

The service name of the engine.

TechnicalProfile constant

public const string TechnicalProfile = "TECHNICAL"

The execution console profile that shows more detail.

ConstantsClass.MapPolicies class

public static class MapPolicies

The fan-in and failure policies of a map step.

AllSucceeded constant

public const string AllSucceeded = "ALL_SUCCEEDED"

Fan-in: the map completes when every item succeeded.

CollectAll constant

public const string CollectAll = "COLLECT_ALL"

Fan-in: the map completes when every item finished, whatever the outcome.

CollectPartial constant

public const string CollectPartial = "COLLECT_PARTIAL"

Failure: the map waits for every item, then applies its fan-in policy.

FailFast constant

public const string FailFast = "FAIL_FAST"

Failure: the first failed item fails the map.

MinimumSucceeded constant

public const string MinimumSucceeded = "MIN_SUCCEEDED"

Fan-in: the map completes when at least the minimum number of items succeeded.

RouteManual constant

public const string RouteManual = "ROUTE_MANUAL"

Failure: when every item finished and one failed, the map waits for manual handling (ConstantsClass.MapStates.Manual).

ConstantsClass.RetryBackoffKinds class

public static class RetryBackoffKinds

How the delay between retries grows. Every kind is capped by the maximum delay, when one is set, and varied by the jitter.

Exponential constant

public const string Exponential = "EXPONENTIAL"

The delay starts at the initial delay and doubles with each retry.

Fixed constant

public const string Fixed = "FIXED"

Every retry waits the initial delay.

ProviderHint constant

public const string ProviderHint = "PROVIDER_HINT"

The delay the provider asks for, such as a retry-after value, capped by the provider-hint bound; the initial delay when the provider gives none.

MessageKeys class

public static class MessageKeys

The message ids of the engine’s business errors. The HTTP endpoints map each to a status.

WorkflowArbitrarySignalNotAllowed property

public static string WorkflowArbitrarySignalNotAllowed { get; }

An arbitrary signal is not allowed. The endpoints answer it with 400; the engine does not raise it.

WorkflowBusinessIdMissing property

public static string WorkflowBusinessIdMissing { get; }

A business id is missing. The endpoints answer it with 400; the engine does not raise it.

WorkflowDefinitionNotFound property

public static string WorkflowDefinitionNotFound { get; }

The workflow definition does not exist (404).

WorkflowInstanceNotFound property

public static string WorkflowInstanceNotFound { get; }

The workflow instance does not exist (404).

WorkflowPayloadFieldMissing property

public static string WorkflowPayloadFieldMissing { get; }

A payload or state field a step reads is missing (400).

WorkflowRuntimeFailed property

public static string WorkflowRuntimeFailed { get; }

The runtime failed. The endpoints answer it with 500; the engine does not raise it.

WorkflowServiceAudienceDenied property

public static string WorkflowServiceAudienceDenied { get; }

The calling service is not an allowed audience of the start (403).

WorkflowSortColumnNotAllowed property

public static string WorkflowSortColumnNotAllowed { get; }

The sort column is not one the list allows (400).

WorkflowStartExactReplayConflict property

public static string WorkflowStartExactReplayConflict { get; }

A start replay conflicts with an earlier start. The endpoints answer it with 409; the engine does not raise it.

WorkflowStartNotReady property

public static string WorkflowStartNotReady { get; }

The start is not ready. The endpoints answer it with 409; the engine does not raise it.

WorkflowTaskActionDenied property

public static string WorkflowTaskActionDenied { get; }

The caller may not act on the task (403).

WorkflowTaskAlreadyCompleted property

public static string WorkflowTaskAlreadyCompleted { get; }

The task is already completed (409).

WorkflowTaskCancelled property

public static string WorkflowTaskCancelled { get; }

The task was cancelled (409).

WorkflowTaskExpired property

public static string WorkflowTaskExpired { get; }

The task has expired (409).

WorkflowTaskNotFound property

public static string WorkflowTaskNotFound { get; }

The task does not exist (404).

WorkflowTransportFailed property

public static string WorkflowTransportFailed { get; }

A transport call failed and no failure branch handled it (502).

WorkflowInstanceStatuses class

public static class WorkflowInstanceStatuses

The statuses of a workflow instance.

Completed constant

public const string Completed = "Completed"

Completed.

Open constant

public const string Open = "Open"

Running.

Stale constant

public const string Stale = "Stale"

Past its stale date without completing.

WorkflowTaskEventTypes class

public static class WorkflowTaskEventTypes

The event types of a human task’s history.

Assigned constant

public const string Assigned = "Assigned"

The task was assigned.

Cancelled constant

public const string Cancelled = "Cancelled"

The task was cancelled.

Completed constant

public const string Completed = "Completed"

The task was completed.

Created constant

public const string Created = "Created"

The task was opened.

Expired constant

public const string Expired = "Expired"

The task expired.

Reassigned constant

public const string Reassigned = "Reassigned"

The task was assigned again.

Released constant

public const string Released = "Released"

The task was released.

WorkflowTaskStatuses class

public static class WorkflowTaskStatuses

The statuses of a human task.

Assigned constant

public const string Assigned = "Assigned"

Assigned to a user or to roles.

Cancelled constant

public const string Cancelled = "Cancelled"

Cancelled, for example when its fork ended or its instance was cancelled.

Completed constant

public const string Completed = "Completed"

Completed.

Expired constant

public const string Expired = "Expired"

Closed by its timeout.

Open constant

public const string Open = "Open"

Open for any user with a matching role.

Stale constant

public const string Stale = "Stale"

Past its stale date while open.

StellaOps.Workflow.Engine.Definitions namespace

TypeKindDescription
WorkflowRuntimeDefinitionStoreclassBuilds the runtime definitions of the registered workflows; a declarative workflow is compiled and validated, and one that fails raises an error naming its issues.
WorkflowRuntimeExecutionHandlerFactoryclassCreates the execution handlers of runtime definitions.

WorkflowRuntimeDefinitionStore class

public sealed class WorkflowRuntimeDefinitionStore : IWorkflowRuntimeDefinitionStore

Builds the runtime definitions of the registered workflows; a declarative workflow is compiled and validated, and one that fails raises an error naming its issues.

WorkflowRuntimeDefinitionStore(IWorkflowRegistrationCatalog, IWorkflowModuleCatalog, IWorkflowFunctionCatalog, IWorkflowExternalActivityRegistry) constructor

public WorkflowRuntimeDefinitionStore(IWorkflowRegistrationCatalog workflowRegistrationCatalog, IWorkflowModuleCatalog workflowModuleCatalog, IWorkflowFunctionCatalog workflowFunctionCatalog, IWorkflowExternalActivityRegistry? externalActivityRegistry = null)

Creates the store.

Parameters

GetDefinition(string, string) method

public WorkflowRuntimeDefinition? GetDefinition(string workflowName, string? workflowVersion = null)

Finds a runtime definition.

Parameters

Returns

The definition, or null.

GetDefinitions() method

public IReadOnlyCollection<WorkflowRuntimeDefinition> GetDefinitions()

Returns every runtime definition.

Returns

The definitions.

GetRequiredDefinition(string, string) method

public WorkflowRuntimeDefinition GetRequiredDefinition(string workflowName, string? workflowVersion = null)

Finds a runtime definition.

Parameters

Returns

The definition.

Exceptions

WorkflowRuntimeExecutionHandlerFactory class

public sealed class WorkflowRuntimeExecutionHandlerFactory : IWorkflowRuntimeExecutionHandlerFactory

Creates the execution handlers of runtime definitions.

Parameters

WorkflowRuntimeExecutionHandlerFactory(IServiceProvider) constructor

public WorkflowRuntimeExecutionHandlerFactory(IServiceProvider serviceProvider)

Creates the execution handlers of runtime definitions.

Parameters

TryCreateHandler(WorkflowRuntimeDefinition) method

public IWorkflowExecutionHandler? TryCreateHandler(WorkflowRuntimeDefinition definition)

Creates the handler: the custom handler of the registration, or the declarative handler; none for a definition-only workflow.

Parameters

Returns

The handler, or null.

StellaOps.Workflow.Engine.Durability namespace

TypeKindDescription
IWorkflowDurableStartAdmissionPolicyinterfaceDecides whether a durable start may run now.
IWorkflowOutboxMessagePublisherinterfaceSends outbox messages over a transport.
IWorkflowServiceAudienceResolverinterfaceMaps an authenticated service subject to its service audience.
WorkflowActivityCompletionMessageHandlerclassHandles WorkflowExternalActivityLanes.Completed: records the completion and resumes the waiting step (or map item) when it can resume.
WorkflowDefinitionStartAdmissionPolicyclassAdmits a durable start only for a permitted, managed and active definition whose content hash matches the request.
WorkflowDeliveryDispositionenumWhat the engine decided about one delivered durable message.
WorkflowDurableMaintenanceOptionsclassOptions of the durable maintenance tasks, bound from WorkflowMaintenance.
WorkflowDurableMaintenanceServiceclassThe engine’s periodic durable maintenance: the execution integrity check and the outbox/inbox compaction.
WorkflowDurableMessageTypesclassMessage types of the durable start protocol; an integration transport publishes and consumes them by these names.
WorkflowDurableMessagingServiceCollectionExtensionsclassRegisters the durable messaging of the engine.
WorkflowDurableOutboxMessagerecordA durable start message waiting in the outbox.
WorkflowDurableRootContinuationServiceclassContinues a durable start after its start decision committed: checks the stored receipt and the digest of the stored request, then runs the start.
WorkflowDurableStartAudienceclassWho may call the durable start lane.
WorkflowDurableStartOptionsclassThe workflow definitions a service may start durably (WorkflowDurableStart).
WorkflowDurableStartServiceclassDecides durable starts and prestart terminal commands once, each in one change scope with its outbox messages.
WorkflowExactReplayConflictExceptionclassRaised when a replay carries different content under an identity already recorded.
WorkflowOutboxBatchResultrecordThe counts of one outbox drain.
WorkflowOutboxDeliveryrecordOne outbox row as a message: the lane (channel), its id, the canonical body and the contract headers.
WorkflowOutboxDispatcherclassDrains the ready outbox rows (activity dispatches, activity cancellations and the durable start messages) through IWorkflowOutboxMessagePublisherand records every delivery attempt; an unconfirmed message stays ready for an exact replay.
WorkflowOutboxDispatcherHostedServiceclassRuns WorkflowOutboxDispatchercontinuously: quickly while rows are ready, slowly when idle.
WorkflowRegisteredSignalDispositionenumHow a raised signal was handled.
WorkflowRegisteredSignalOptionsclassThe registered signals and the service audiences that may use them (WorkflowRegisteredSignals).
WorkflowRegisteredSignalRaiseRequestrecordA signal raised for a registered wait.
WorkflowRegisteredSignalRaiseResponserecordHow a raised signal was handled.
WorkflowRegisteredSignalServiceclassRegistered signal waits: a step waits for a signal from a registered service audience until a deadline, and the signal or the deadline wins, whichever is recorded first.
WorkflowRegisteredSignalWaitRequestrecordA wait to register, with its deadline timer.
WorkflowRegisteredSignalWaitResultrecordThe state of a registered wait.
WorkflowRegisteredWaitOutcomeenumThe state of a registered wait.
WorkflowRootAlreadyStartedExceptionclassRaised when an execution already has a durable root.
WorkflowRootContinuationMessageHandlerclassHandles WorkflowDurableMessageTypes.RootContinuation.
WorkflowRootContinuationV1recordContinues a durable root after its start committed.
WorkflowServiceAudienceResolverclassMaps subjects to audiences with ServiceSubjects of the registered signal options.
WorkflowStartAdmissionDecisionrecordThe admission decision on a durable start.
WorkflowStartAdmissionDispositionenumWhether a durable start may run now.
WorkflowStartExecutionMessageHandlerclassHandles WorkflowDurableMessageTypes.StartExecution.
WorkflowStartNotReadyExceptionclassRaised when a durable start cannot run yet; the start is retried.

IWorkflowDurableStartAdmissionPolicy interface

public interface IWorkflowDurableStartAdmissionPolicy

Decides whether a durable start may run now.

EvaluateAsync(StartWorkflowExecutionV1, CancellationToken) method

Task<WorkflowStartAdmissionDecision> EvaluateAsync(StartWorkflowExecutionV1 request, CancellationToken cancellationToken = default)

Decides on a start request.

Parameters

Returns

The decision.

IWorkflowOutboxMessagePublisher interface

public interface IWorkflowOutboxMessagePublisher

Sends outbox messages over a transport. Returns true only when the transport confirmed the message.

PublishAsync(WorkflowOutboxDelivery, CancellationToken) method

Task<bool> PublishAsync(WorkflowOutboxDelivery message, CancellationToken cancellationToken)

Sends a message.

Parameters

Returns

Whether the transport confirmed it.

IWorkflowServiceAudienceResolver interface

public interface IWorkflowServiceAudienceResolver

Maps an authenticated service subject to its service audience.

ResolveAudience(string) method

string? ResolveAudience(string? authenticatedSubject)

Returns the audience of a subject.

Parameters

Returns

The audience, or null when the subject has none.

WorkflowActivityCompletionMessageHandler class

public sealed class WorkflowActivityCompletionMessageHandler

Handles WorkflowExternalActivityLanes.Completed: records the completion and resumes the waiting step (or map item) when it can resume.

WorkflowActivityCompletionMessageHandler(IServiceScopeFactory) constructor

public WorkflowActivityCompletionMessageHandler(IServiceScopeFactory scopeFactory)

Handles WorkflowExternalActivityLanes.Completed: records the completion and resumes the waiting step (or map item) when it can resume.

HandleAsync(ReadOnlyMemory<byte>, CancellationToken) method

public Task<WorkflowDeliveryDisposition> HandleAsync(ReadOnlyMemory<byte> body, CancellationToken cancellationToken)

Decodes an activity completion, records it and resumes the waiting step or map item.

Parameters

Returns

The disposition of the completion; RetryableFailure on a version conflict or when the resume did not apply; Poison when the body does not decode or validate; Rejected when the completion conflicts with its binding.

WorkflowDefinitionStartAdmissionPolicy class

public sealed class WorkflowDefinitionStartAdmissionPolicy : IWorkflowDurableStartAdmissionPolicy

Admits a durable start only for a permitted, managed and active definition whose content hash matches the request.

Parameters

WorkflowDefinitionStartAdmissionPolicy(IWorkflowDefinitionStore, IOptions<WorkflowDurableStartOptions>) constructor

public WorkflowDefinitionStartAdmissionPolicy(IWorkflowDefinitionStore definitionStore, IOptions<WorkflowDurableStartOptions> options)

Admits a durable start only for a permitted, managed and active definition whose content hash matches the request.

Parameters

EvaluateAsync(StartWorkflowExecutionV1, CancellationToken) method

public Task<WorkflowStartAdmissionDecision> EvaluateAsync(StartWorkflowExecutionV1 request, CancellationToken cancellationToken = default)

Decides on a start request. A definition the options do not name, or whose hash differs, is rejected permanently (DEFINITION_NOT_PERMITTED, DEFINITION_HASH_NOT_PERMITTED); a definition that is missing, not managed, without build digests or inactive is not ready yet.

Parameters

Returns

The decision.

WorkflowDeliveryDisposition enum

public enum WorkflowDeliveryDisposition

What the engine decided about one delivered durable message. A transport adapter maps it onto its own acknowledgement (ack, retry, park, reject).

ValueDescription
Applied = 0The message changed state.
TerminalHandoffCommitted = 1The message was handed over to its terminal step and committed.
AlreadyApplied = 2An exact replay of a message already applied.
AlreadyTerminal = 3The target is already terminal.
Late = 4The message arrived after its target moved on.
Ignored = 5Nothing to do for this message.
RetryableFailure = 6A transient conflict; deliver again.
WaitNotReady = 7The target is not ready yet; deliver again later.
Rejected = 8The message conflicts with recorded state and must not be retried.
Poison = 9The message cannot be decoded or validated.

WorkflowDurableMaintenanceOptions class

public sealed class WorkflowDurableMaintenanceOptions

Options of the durable maintenance tasks, bound from WorkflowMaintenance.

WorkflowDurableMaintenanceOptions() constructor

public WorkflowDurableMaintenanceOptions()

Creates an instance of WorkflowDurableMaintenanceOptions.

SectionName constant

public const string SectionName = "WorkflowMaintenance"

The configuration section the options bind from: WorkflowMaintenance.

CompactionRetentionDays property

public int CompactionRetentionDays { get; set; }

Days a delivered outbox or inbox row is kept before compaction; clamped to 7–3650.

WorkflowDurableMaintenanceService class

public sealed class WorkflowDurableMaintenanceService

The engine’s periodic durable maintenance: the execution integrity check and the outbox/inbox compaction. A host runs them from its own scheduler.

WorkflowDurableMaintenanceService(IWorkflowDurableMaintenanceStore, IWorkflowOutboxStore, IOptions<WorkflowDurableMaintenanceOptions>, TimeProvider) constructor

public WorkflowDurableMaintenanceService(IWorkflowDurableMaintenanceStore maintenanceStore, IWorkflowOutboxStore outboxStore, IOptions<WorkflowDurableMaintenanceOptions> options, TimeProvider timeProvider)

The engine’s periodic durable maintenance: the execution integrity check and the outbox/inbox compaction. A host runs them from its own scheduler.

CompactOutboxAsync(CancellationToken) method

public Task CompactOutboxAsync(CancellationToken cancellationToken)

Deletes delivered outbox and inbox rows older than the retention.

VerifyIntegrityAsync(CancellationToken) method

public Task VerifyIntegrityAsync(CancellationToken cancellationToken)

Fails with WORKFLOW_STEP_ATTEMPT_ORPHANED when a step attempt lost its execution.

WorkflowDurableMessageTypes class

public static class WorkflowDurableMessageTypes

Message types of the durable start protocol; an integration transport publishes and consumes them by these names.

PrestartTerminalAck constant

public const string PrestartTerminalAck = "workflow.prestart-terminal-ack.v1"

The lane of prestart terminal acknowledgements.

RootContinuation constant

public const string RootContinuation = "workflow.root-continuation.v1"

The lane of root continuations.

StartExecution constant

public const string StartExecution = "workflow.start-execution.v1"

The lane of durable start requests.

StartExecutionResult constant

public const string StartExecutionResult = "workflow.start-execution-result.v1"

The lane of durable start results.

RequiredLanes property

public static IReadOnlyList<string> RequiredLanes { get; }

Every lane the engine publishes to or consumes from; a transport must provide each one.

WorkflowDurableMessagingServiceCollectionExtensions class

public static class WorkflowDurableMessagingServiceCollectionExtensions

Registers the durable messaging of the engine.

AddWorkflowDurableMessaging(IServiceCollection) extension method

public static IServiceCollection AddWorkflowDurableMessaging(this IServiceCollection services)

Registers the durable lane handlers and the outbox dispatcher with its hosted service. The host registers an IWorkflowOutboxMessagePublisherfor its transport and feeds the handlers from its consumers.

WorkflowDurableOutboxMessage record

public sealed record WorkflowDurableOutboxMessage

A durable start message waiting in the outbox.

Parameters

WorkflowDurableOutboxMessage(string, string, string, string, string, int) constructor

public WorkflowDurableOutboxMessage(string EventId, string MessageType, string AggregateId, string PayloadSha256, string PayloadJson, int DeliveryAttempts)

A durable start message waiting in the outbox.

Parameters

AggregateId property

public string AggregateId { get; init; }

The aggregate the message belongs to.

DeliveryAttempts property

public int DeliveryAttempts { get; init; }

The delivery attempts so far.

EventId property

public string EventId { get; init; }

The message.

MessageType property

public string MessageType { get; init; }

The message type.

PayloadJson property

public string PayloadJson { get; init; }

The payload, as JSON.

PayloadSha256 property

public string PayloadSha256 { get; init; }

The SHA-256 of the payload.

WorkflowDurableRootContinuationService class

public sealed class WorkflowDurableRootContinuationService

Continues a durable start after its start decision committed: checks the stored receipt and the digest of the stored request, then runs the start.

Parameters

WorkflowDurableRootContinuationService(IWorkflowDurableStartStore, WorkflowRuntimeService) constructor

public WorkflowDurableRootContinuationService(IWorkflowDurableStartStore store, WorkflowRuntimeService runtimeService)

Continues a durable start after its start decision committed: checks the stored receipt and the digest of the stored request, then runs the start.

Parameters

ContinueAsync(WorkflowRootContinuationV1, CancellationToken) method

public Task<bool> ContinueAsync(WorkflowRootContinuationV1 continuation, CancellationToken cancellationToken = default)

Runs the start of the durable root a continuation names.

Parameters

Returns

true when the start ran; false when the execution already moved past the expected version.

Exceptions

WorkflowDurableStartAudience class

public static class WorkflowDurableStartAudience

Who may call the durable start lane.

EnsureAllowed(IWorkflowServiceAudienceResolver, WorkflowDurableStartOptions, string, string) method

public static void EnsureAllowed(IWorkflowServiceAudienceResolver audienceResolver, WorkflowDurableStartOptions options, string? callerSubject, string? definitionCode)

Only a configured start audience may call the lane: a definition configured for another audience is denied, an unconfigured definition (or none, for a pre-start terminal) is allowed to any configured audience and then meets admission. Throws MessageKeys.WorkflowServiceAudienceDeniedotherwise.

WorkflowDurableStartOptions class

public sealed class WorkflowDurableStartOptions

The workflow definitions a service may start durably (WorkflowDurableStart).

WorkflowDurableStartOptions() constructor

public WorkflowDurableStartOptions()

Creates an instance of WorkflowDurableStartOptions.

SectionName constant

public const string SectionName = "WorkflowDurableStart"

The configuration section the options bind from: WorkflowDurableStart.

Definitions property

public Dictionary<string, string> Definitions { get; set; }

Maps a definition code to the service audience allowed to start it durably and to fence its start. A durable start of a definition missing here is refused with DEFINITION_NOT_PERMITTED.

WorkflowDurableStartService class

public sealed class WorkflowDurableStartService

Decides durable starts and prestart terminal commands once, each in one change scope with its outbox messages.

Parameters

WorkflowDurableStartService(IWorkflowDurableStartStore, IWorkflowOutboxStore, IWorkflowMutationCoordinator, IWorkflowDurableStartAdmissionPolicy) constructor

public WorkflowDurableStartService(IWorkflowDurableStartStore store, IWorkflowOutboxStore outboxStore, IWorkflowMutationCoordinator mutationCoordinator, IWorkflowDurableStartAdmissionPolicy admissionPolicy)

Decides durable starts and prestart terminal commands once, each in one change scope with its outbox messages.

Parameters

GetPendingOutboxAsync(int, CancellationToken) method

public Task<IReadOnlyCollection<WorkflowDurableOutboxMessage>> GetPendingOutboxAsync(int limit, CancellationToken cancellationToken = default)

Returns the durable outbox messages ready to publish.

Parameters

Returns

The messages.

Exceptions

MarkOutboxPublishedAsync(string, CancellationToken) method

public Task<bool> MarkOutboxPublishedAsync(string eventId, CancellationToken cancellationToken = default)

Marks a ready durable outbox message published.

Parameters

Returns

false when the message is not ready: already published or missing.

ProcessPrestartTerminalAsync(WorkflowPrestartTerminalCommandV1, CancellationToken) method

public Task<WorkflowPrestartTerminalAckV1> ProcessPrestartTerminalAsync(WorkflowPrestartTerminalCommandV1 command, CancellationToken cancellationToken = default)

Records a terminal command that arrives before its start: fences the start request, so the start is not created, and acknowledges the command. A command already recorded under its event id returns the recorded acknowledgement.

Parameters

Returns

The acknowledgement.

Exceptions

ProcessStartAsync(StartWorkflowExecutionV1, CancellationToken) method

public Task<StartWorkflowExecutionResultV1> ProcessStartAsync(StartWorkflowExecutionV1 request, CancellationToken cancellationToken = default)

Decides a start request once. A request already decided returns its recorded result; a fenced request is FENCED_NOT_CREATED; a rejected definition, or an open execution of the definition with the same business reference, is REJECTED_NOT_CREATED; otherwise the root is created, STARTED, with a root continuation message.

Parameters

Returns

The start result.

Exceptions

WorkflowExactReplayConflictException class

public sealed class WorkflowExactReplayConflictException : InvalidOperationException

Raised when a replay carries different content under an identity already recorded.

Parameters

WorkflowExactReplayConflictException(string) constructor

public WorkflowExactReplayConflictException(string identity)

Raised when a replay carries different content under an identity already recorded.

Parameters

Identity property

public string Identity { get; }

The identity.

WorkflowOutboxBatchResult record

public sealed record WorkflowOutboxBatchResult

The counts of one outbox drain.

Parameters

WorkflowOutboxBatchResult(int, int, int) constructor

public WorkflowOutboxBatchResult(int Attempted, int Published, int Deferred)

The counts of one outbox drain.

Parameters

Attempted property

public int Attempted { get; init; }

The messages tried.

Deferred property

public int Deferred { get; init; }

The messages left ready for a later drain.

Published property

public int Published { get; init; }

The messages the transport confirmed.

WorkflowOutboxDelivery record

public sealed record WorkflowOutboxDelivery

One outbox row as a message: the lane (channel), its id, the canonical body and the contract headers.

Parameters

WorkflowOutboxDelivery(string, string, ReadOnlyMemory<byte>, string, IReadOnlyDictionary<string, object>) constructor

public WorkflowOutboxDelivery(string Channel, string MessageId, ReadOnlyMemory<byte> Body, string ContentType, IReadOnlyDictionary<string, object> Headers)

One outbox row as a message: the lane (channel), its id, the canonical body and the contract headers.

Parameters

Body property

public ReadOnlyMemory<byte> Body { get; init; }

The canonical body.

Channel property

public string Channel { get; init; }

The lane.

ContentType property

public string ContentType { get; init; }

The media type of the body.

Headers property

public IReadOnlyDictionary<string, object> Headers { get; init; }

The contract headers.

MessageId property

public string MessageId { get; init; }

The message id.

WorkflowOutboxDispatcher class

public sealed class WorkflowOutboxDispatcher

Drains the ready outbox rows (activity dispatches, activity cancellations and the durable start messages) through IWorkflowOutboxMessagePublisherand records every delivery attempt; an unconfirmed message stays ready for an exact replay.

WorkflowOutboxDispatcher(IServiceScopeFactory, IWorkflowOutboxMessagePublisher, TimeProvider) constructor

public WorkflowOutboxDispatcher(IServiceScopeFactory scopeFactory, IWorkflowOutboxMessagePublisher publisher, TimeProvider timeProvider)

Drains the ready outbox rows (activity dispatches, activity cancellations and the durable start messages) through IWorkflowOutboxMessagePublisherand records every delivery attempt; an unconfirmed message stays ready for an exact replay.

PublishBatchAsync(CancellationToken) method

public Task<WorkflowOutboxBatchResult> PublishBatchAsync(CancellationToken cancellationToken = default)

Drains one batch of ready outbox messages.

Parameters

Returns

The counts.

WorkflowOutboxDispatcherHostedService class

public sealed class WorkflowOutboxDispatcherHostedService : BackgroundService

Runs WorkflowOutboxDispatchercontinuously: quickly while rows are ready, slowly when idle.

WorkflowOutboxDispatcherHostedService(WorkflowOutboxDispatcher, ILogger<WorkflowOutboxDispatcherHostedService>) constructor

public WorkflowOutboxDispatcherHostedService(WorkflowOutboxDispatcher dispatcher, ILogger<WorkflowOutboxDispatcherHostedService> logger)

Runs WorkflowOutboxDispatchercontinuously: quickly while rows are ready, slowly when idle.

WorkflowRegisteredSignalDisposition enum

public enum WorkflowRegisteredSignalDisposition

How a raised signal was handled.

ValueDescription
CORRELATED = 0The signal resolved its wait.
ALREADY_RESOLVED = 1The wait was already resolved.
WAIT_NOT_READY = 2No wait is registered yet; the signal is kept for it.
RETRYABLE_FAILURE = 3The signal lost a race; it can be raised again.
REJECTED = 4The signal was refused.

WorkflowRegisteredSignalOptions class

public sealed class WorkflowRegisteredSignalOptions

The registered signals and the service audiences that may use them (WorkflowRegisteredSignals).

WorkflowRegisteredSignalOptions() constructor

public WorkflowRegisteredSignalOptions()

Creates an instance of WorkflowRegisteredSignalOptions.

SectionName constant

public const string SectionName = "WorkflowRegisteredSignals"

The configuration section the options bind from: WorkflowRegisteredSignals.

ServiceSubjects property

public Dictionary<string, string> ServiceSubjects { get; set; }

Maps an authenticated service subject to the service audience it acts as. Subjects compare ignoring case.

Signals property

public Dictionary<string, string> Signals { get; set; }

Maps a registered signal code to the only service audience that may wait for it and raise it.

WorkflowRegisteredSignalRaiseRequest record

public sealed record WorkflowRegisteredSignalRaiseRequest

A signal raised for a registered wait.

WorkflowRegisteredSignalRaiseRequest() constructor

public WorkflowRegisteredSignalRaiseRequest()

Creates an instance of WorkflowRegisteredSignalRaiseRequest.

OccurredAt property

public required DateTimeOffset OccurredAt { get; init; }

When the signal was raised.

PayloadJson property

public required string PayloadJson { get; init; }

The payload, as JSON.

PayloadSha256 property

public required string PayloadSha256 { get; init; }

The SHA-256 of the payload.

SignalCode property

public required string SignalCode { get; init; }

The signal code.

SignalEventId property

public required string SignalEventId { get; init; }

The signal event.

SignalKey property

public required string SignalKey { get; init; }

The signal key.

SignalRegistrationId property

public string? SignalRegistrationId { get; init; }

The wait, when the caller names one.

WorkflowExecutionId property

public required string WorkflowExecutionId { get; init; }

The execution.

WorkflowRegisteredSignalRaiseResponse record

public sealed record WorkflowRegisteredSignalRaiseResponse

How a raised signal was handled.

WorkflowRegisteredSignalRaiseResponse() constructor

public WorkflowRegisteredSignalRaiseResponse()

Creates an instance of WorkflowRegisteredSignalRaiseResponse.

Disposition property

public required WorkflowRegisteredSignalDisposition Disposition { get; init; }

How it was handled.

SafeCode property

public string? SafeCode { get; init; }

The safe code of a refusal or a lost race.

SignalEventId property

public required string SignalEventId { get; init; }

The signal event.

SignalRegistrationId property

public string? SignalRegistrationId { get; init; }

The wait the signal reached.

WorkflowExecutionId property

public required string WorkflowExecutionId { get; init; }

The execution.

WorkflowRegisteredSignalService class

public sealed class WorkflowRegisteredSignalService

Registered signal waits: a step waits for a signal from a registered service audience until a deadline, and the signal or the deadline wins, whichever is recorded first.

Parameters

WorkflowRegisteredSignalService(IWorkflowRegisteredSignalStore, IWorkflowMutationCoordinator, IOptions<WorkflowRegisteredSignalOptions>) constructor

public WorkflowRegisteredSignalService(IWorkflowRegisteredSignalStore store, IWorkflowMutationCoordinator mutationCoordinator, IOptions<WorkflowRegisteredSignalOptions> options)

Registered signal waits: a step waits for a signal from a registered service audience until a deadline, and the signal or the deadline wins, whichever is recorded first.

Parameters

FireDeadlineAsync(string, DateTimeOffset, CancellationToken) method

public Task<WorkflowRegisteredSignalWaitResult> FireDeadlineAsync(string timerId, DateTimeOffset now, CancellationToken cancellationToken = default)

Fires a deadline timer: the deadline wins a wait that is still open, at the version the timer armed, once the time is due. A timer that lost is marked lost.

Parameters

Returns

The wait and its outcome.

Exceptions

RaiseByIdAsync(WorkflowRegisteredSignalRaiseRequest, string, CancellationToken) method

public Task<WorkflowRegisteredSignalRaiseResponse> RaiseByIdAsync(WorkflowRegisteredSignalRaiseRequest request, string? authenticatedServiceAudience, CancellationToken cancellationToken = default)

Raises a signal for the wait the request’s registration id names; see WorkflowRegisteredSignalService.RaiseByKeyAsync(WorkflowRegisteredSignalRaiseRequest, string, CancellationToken). A request without a registration id is rejected.

Parameters

Returns

The disposition.

RaiseByKeyAsync(WorkflowRegisteredSignalRaiseRequest, string, CancellationToken) method

public Task<WorkflowRegisteredSignalRaiseResponse> RaiseByKeyAsync(WorkflowRegisteredSignalRaiseRequest request, string? authenticatedServiceAudience, CancellationToken cancellationToken = default)

Raises a signal for the wait of the execution, signal code and signal key. The signal is rejected when it lacks an identity, its code is not registered, the caller’s audience is not the registered one, its payload is empty or over 65,536 characters, its time is not UTC or its payload hash does not match. With no wait yet, the signal is kept (WAIT_NOT_READY); a resolved wait gives ALREADY_RESOLVED; otherwise the signal wins the wait (CORRELATED). A signal event already received returns its recorded disposition.

Parameters

Returns

The disposition.

RegisterWaitAsync(WorkflowRegisteredSignalWaitRequest, CancellationToken) method

public Task<WorkflowRegisteredSignalWaitResult> RegisterWaitAsync(WorkflowRegisteredSignalWaitRequest request, CancellationToken cancellationToken = default)

Registers a wait and arms its deadline timer. A signal already received for the wait wins at once. A wait already registered under its id is returned as recorded.

Parameters

Returns

The wait and its outcome.

Exceptions

WorkflowRegisteredSignalWaitRequest record

public sealed record WorkflowRegisteredSignalWaitRequest

A wait to register, with its deadline timer.

WorkflowRegisteredSignalWaitRequest() constructor

public WorkflowRegisteredSignalWaitRequest()

Creates an instance of WorkflowRegisteredSignalWaitRequest.

DeadlineAt property

public required DateTimeOffset DeadlineAt { get; init; }

The deadline.

ExpectedExecutionVersion property

public required long ExpectedExecutionVersion { get; init; }

The execution version the wait is registered at.

ServiceAudience property

public required string ServiceAudience { get; init; }

The service audience allowed to raise it.

SignalCode property

public required string SignalCode { get; init; }

The signal code.

SignalKey property

public required string SignalKey { get; init; }

The signal key.

SignalRegistrationId property

public required string SignalRegistrationId { get; init; }

The wait.

TimerId property

public required string TimerId { get; init; }

The deadline timer.

WorkflowExecutionId property

public required string WorkflowExecutionId { get; init; }

The execution.

WorkflowRegisteredSignalWaitResult record

public sealed record WorkflowRegisteredSignalWaitResult

The state of a registered wait.

WorkflowRegisteredSignalWaitResult() constructor

public WorkflowRegisteredSignalWaitResult()

Creates an instance of WorkflowRegisteredSignalWaitResult.

Outcome property

public required WorkflowRegisteredWaitOutcome Outcome { get; init; }

The state of the wait.

PayloadJson property

public string? PayloadJson { get; init; }

The signal payload, as JSON.

PayloadSha256 property

public string? PayloadSha256 { get; init; }

The SHA-256 of the signal payload.

SignalRegistrationId property

public required string SignalRegistrationId { get; init; }

The wait.

WaitVersion property

public required long WaitVersion { get; init; }

The wait version.

WinnerId property

public string? WinnerId { get; init; }

The signal event or timer that resolved it.

WorkflowRegisteredWaitOutcome enum

public enum WorkflowRegisteredWaitOutcome

The state of a registered wait.

ValueDescription
WAITING = 0The wait is open.
SIGNAL_WON = 1A signal resolved the wait.
DEADLINE_WON = 2The deadline timer resolved the wait.

WorkflowRootAlreadyStartedException class

public sealed class WorkflowRootAlreadyStartedException : InvalidOperationException

Raised when an execution already has a durable root.

Parameters

WorkflowRootAlreadyStartedException(string) constructor

public WorkflowRootAlreadyStartedException(string workflowExecutionId)

Raised when an execution already has a durable root.

Parameters

WorkflowExecutionId property

public string WorkflowExecutionId { get; }

The execution.

WorkflowRootContinuationMessageHandler class

public sealed class WorkflowRootContinuationMessageHandler

Handles WorkflowDurableMessageTypes.RootContinuation.

WorkflowRootContinuationMessageHandler(IServiceScopeFactory, ILogger<WorkflowRootContinuationMessageHandler>) constructor

public WorkflowRootContinuationMessageHandler(IServiceScopeFactory scopeFactory, ILogger<WorkflowRootContinuationMessageHandler> logger)

Handles WorkflowDurableMessageTypes.RootContinuation.

HandleAsync(ReadOnlyMemory<byte>, string, CancellationToken) method

public Task<WorkflowDeliveryDisposition> HandleAsync(ReadOnlyMemory<byte> body, string? messageId, CancellationToken cancellationToken)

Decodes a root continuation and runs it.

Parameters

Returns

Applied or AlreadyApplied; WaitNotReady when the start is not ready yet; Rejected on a replay conflict; RetryableFailure on a version conflict; Poison when the body does not decode or validate.

WorkflowRootContinuationV1 record

public sealed record WorkflowRootContinuationV1 : IContractValidatable

Continues a durable root after its start committed.

Parameters

WorkflowRootContinuationV1(string, string, string, long) constructor

public WorkflowRootContinuationV1(string StartRequestId, string WorkflowExecutionId, string RootScopeExecutionId, long ExpectedExecutionVersion)

Continues a durable root after its start committed.

Parameters

ExpectedExecutionVersion property

public long ExpectedExecutionVersion { get; init; }

The execution version the continuation expects.

RootScopeExecutionId property

public string RootScopeExecutionId { get; init; }

The root scope.

StartRequestId property

public string StartRequestId { get; init; }

The start request.

WorkflowExecutionId property

public string WorkflowExecutionId { get; init; }

The execution.

Validate() method

public void Validate()

Checks the fields.

Exceptions

WorkflowServiceAudienceResolver class

public sealed class WorkflowServiceAudienceResolver : IWorkflowServiceAudienceResolver

Maps subjects to audiences with ServiceSubjects of the registered signal options.

Parameters

WorkflowServiceAudienceResolver(IOptions<WorkflowRegisteredSignalOptions>) constructor

public WorkflowServiceAudienceResolver(IOptions<WorkflowRegisteredSignalOptions> options)

Maps subjects to audiences with ServiceSubjects of the registered signal options.

Parameters

ResolveAudience(string) method

public string? ResolveAudience(string? authenticatedSubject)

Returns the audience of a subject.

Parameters

Returns

The audience, or null when the subject has none.

WorkflowStartAdmissionDecision record

public sealed record WorkflowStartAdmissionDecision

The admission decision on a durable start.

Parameters

WorkflowStartAdmissionDecision(WorkflowStartAdmissionDisposition, string) constructor

public WorkflowStartAdmissionDecision(WorkflowStartAdmissionDisposition Disposition, string? SafeCode = null)

The admission decision on a durable start.

Parameters

Disposition property

public WorkflowStartAdmissionDisposition Disposition { get; init; }

The decision.

Ready property

public static WorkflowStartAdmissionDecision Ready { get; }

The decision that the start may run.

SafeCode property

public string? SafeCode { get; init; }

The safe code of a refusal or a delay.

WorkflowStartAdmissionDisposition enum

public enum WorkflowStartAdmissionDisposition

Whether a durable start may run now.

ValueDescription
Ready = 0The start may run.
TransientNotReady = 1The start cannot run yet; retry later.
PermanentReject = 2The start is refused.

WorkflowStartExecutionMessageHandler class

public sealed class WorkflowStartExecutionMessageHandler

Handles WorkflowDurableMessageTypes.StartExecution.

WorkflowStartExecutionMessageHandler(IServiceScopeFactory) constructor

public WorkflowStartExecutionMessageHandler(IServiceScopeFactory scopeFactory)

Handles WorkflowDurableMessageTypes.StartExecution.

HandleAsync(ReadOnlyMemory<byte>, CancellationToken) method

public Task<WorkflowDeliveryDisposition> HandleAsync(ReadOnlyMemory<byte> body, CancellationToken cancellationToken)

Decodes a start message and runs the start.

Parameters

Returns

TerminalHandoffCommitted when the start ran; WaitNotReady when it is not ready yet; Rejected on a replay conflict; Poison when the body does not decode or validate.

WorkflowStartNotReadyException class

public sealed class WorkflowStartNotReadyException : InvalidOperationException

Raised when a durable start cannot run yet; the start is retried.

Parameters

WorkflowStartNotReadyException(string) constructor

public WorkflowStartNotReadyException(string safeCode)

Raised when a durable start cannot run yet; the start is retried.

Parameters

SafeCode property

public string SafeCode { get; }

The safe code.

StellaOps.Workflow.Engine.Exceptions namespace

TypeKindDescription
WorkflowEngineErrorrecordA business error of the engine.
WorkflowEngineErrorsclassCreates the engine’s business errors.
WorkflowEngineExceptionclassThe engine’s business-result exception: a message key, optional interpolation arguments and a status code.

WorkflowEngineError record

public sealed record WorkflowEngineError

A business error of the engine.

Parameters

WorkflowEngineError(int, string, object[], Exception) constructor

public WorkflowEngineError(int Code, string MessageId, object[] Arguments, Exception? InnerException)

A business error of the engine.

Parameters

Arguments property

public object[] Arguments { get; init; }

The interpolation arguments.

Code property

public int Code { get; init; }

The HTTP status.

InnerException property

public Exception? InnerException { get; init; }

The cause, when there is one.

MessageId property

public string MessageId { get; init; }

The message id; see MessageKeys.

WorkflowEngineErrors class

public static class WorkflowEngineErrors

Creates the engine’s business errors. A host whose error pipeline expects its own exception type installs WorkflowEngineErrors.Factoryonce at startup; the default creates WorkflowEngineException.

DefaultCode constant

public const int DefaultCode = 400

The default HTTP status: 400.

Factory property

public static Func<WorkflowEngineError, Exception> Factory { get; set; }

Creates the exception of an error; WorkflowEngineErrors.DefaultFactory(WorkflowEngineError)by default.

Create(Exception, string, params object[]) method

public static Exception Create(Exception innerException, string messageId, params object[] args)

Creates the exception of an error with status 400.

Parameters

Returns

The exception to throw.

Create(int, string, params object[]) method

public static Exception Create(int code, string messageId, params object[] args)

Creates the exception of an error.

Parameters

Returns

The exception to throw.

Create(string, params object[]) method

public static Exception Create(string messageId, params object[] args)

Creates the exception of an error with status 400.

Parameters

Returns

The exception to throw.

DefaultFactory(WorkflowEngineError) method

public static Exception DefaultFactory(WorkflowEngineError error)

Creates a WorkflowEngineException.

Parameters

Returns

The exception.

WorkflowEngineException class

public class WorkflowEngineException : Exception

The engine’s business-result exception: a message key, optional interpolation arguments and a status code. The engine raises it through WorkflowEngineErrors, so a host can substitute its own type.

WorkflowEngineException(Exception, string) constructor

public WorkflowEngineException(Exception innerException, string messageId)

Creates the exception with status 400.

Parameters

WorkflowEngineException(Exception, string, params object[]) constructor

public WorkflowEngineException(Exception innerException, string messageId, params object[] args)

Creates the exception with status 400.

Parameters

WorkflowEngineException(int, string) constructor

public WorkflowEngineException(int code, string messageId)

Creates the exception.

Parameters

WorkflowEngineException(int, string, params object[]) constructor

public WorkflowEngineException(int code, string messageId, params object[] args)

Creates the exception.

Parameters

WorkflowEngineException(string) constructor

public WorkflowEngineException(string messageId)

Creates the exception with status 400.

Parameters

WorkflowEngineException(string, params object[]) constructor

public WorkflowEngineException(string messageId, params object[] args)

Creates the exception with status 400.

Parameters

Code property

public int Code { get; set; }

The HTTP status the endpoints answer with; 400 by default.

MessageId property

public string MessageId { get; set; }

The message id.

MessageInterpolationArguments property

public IReadOnlyList<object?> MessageInterpolationArguments { get; set; }

The interpolation arguments of the message.

StellaOps.Workflow.Engine.Execution namespace

TypeKindDescription
CanonicalWorkflowExecutionHandlerclassRuns a workflow from its canonical runtime definition: starts, task completions, signal resumes and map items.
ConfiguredWorkflowRuntimeOrchestratorclassSends starts and task completions to the configured default runtime provider (Stella.Engine when not set), and resumes to the provider that holds the instance.
WorkflowEngineRuntimeProviderclassThe Stella.Engine runtime: runs a definition through its execution handler and records the runtime state as an engine snapshot.

CanonicalWorkflowExecutionHandler class

public sealed class CanonicalWorkflowExecutionHandler : IWorkflowExecutionHandler, IWorkflowSignalResumableExecutionHandler, IWorkflowMapItemExecutionHandler

Runs a workflow from its canonical runtime definition: starts, task completions, signal resumes and map items.

Parameters

CanonicalWorkflowExecutionHandler(WorkflowRuntimeDefinition, IWorkflowEndpointTransport, IWorkflowRabbitTransport, IWorkflowGraphqlTransport, IWorkflowHttpTransport, IWorkflowFunctionRuntime, IWorkflowRegistrationCatalog, IWorkflowRuntimeDefinitionStore, IWorkflowRuntimeExecutionHandlerFactory) constructor

public CanonicalWorkflowExecutionHandler(WorkflowRuntimeDefinition runtimeDefinition, IWorkflowEndpointTransport endpointTransport, IWorkflowRabbitTransport rabbitTransport, IWorkflowGraphqlTransport graphqlTransport, IWorkflowHttpTransport httpTransport, IWorkflowFunctionRuntime workflowFunctionRuntime, IWorkflowRegistrationCatalog workflowRegistrationCatalog, IWorkflowRuntimeDefinitionStore workflowRuntimeDefinitionStore, IWorkflowRuntimeExecutionHandlerFactory workflowRuntimeExecutionHandlerFactory)

Runs a workflow from its canonical runtime definition: starts, task completions, signal resumes and map items.

Parameters

CompleteTaskAsync(WorkflowTaskExecutionContext, CancellationToken) method

public Task<WorkflowTaskCompletionPlan> CompleteTaskAsync(WorkflowTaskExecutionContext context, CancellationToken cancellationToken = default)

Plans the completion of a task.

Parameters

Returns

The plan.

ExecuteMapItemAsync(WorkflowMapItemExecutionRequest, CancellationToken) method

public Task<WorkflowMapItemExecutionDecision> ExecuteMapItemAsync(WorkflowMapItemExecutionRequest request, CancellationToken cancellationToken = default)

Runs the item until it waits or ends.

Parameters

Returns

What happens next.

StartAsync(WorkflowStartExecutionContext, CancellationToken) method

public Task<WorkflowStartExecutionPlan> StartAsync(WorkflowStartExecutionContext context, CancellationToken cancellationToken = default)

Plans the start of an instance.

Parameters

Returns

The plan.

ConfiguredWorkflowRuntimeOrchestrator class

public sealed class ConfiguredWorkflowRuntimeOrchestrator : IWorkflowRuntimeOrchestrator

Sends starts and task completions to the configured default runtime provider (Stella.Engine when not set), and resumes to the provider that holds the instance. A provider must be registered and, when the enabled list is not empty, enabled.

Parameters

ConfiguredWorkflowRuntimeOrchestrator(IEnumerable<IWorkflowRuntimeProvider>, IOptions<WorkflowRuntimeOptions>) constructor

public ConfiguredWorkflowRuntimeOrchestrator(IEnumerable<IWorkflowRuntimeProvider> runtimeProviders, IOptions<WorkflowRuntimeOptions> runtimeOptions)

Sends starts and task completions to the configured default runtime provider (Stella.Engine when not set), and resumes to the provider that holds the instance. A provider must be registered and, when the enabled list is not empty, enabled.

Parameters

CompleteAsync(WorkflowRegistration, WorkflowDefinitionDescriptor, WorkflowTaskExecutionContext, CancellationToken) method

public Task<WorkflowRuntimeExecutionResult> CompleteAsync(WorkflowRegistration registration, WorkflowDefinitionDescriptor definition, WorkflowTaskExecutionContext context, CancellationToken cancellationToken = default)

Completes a task.

Parameters

Returns

The outcome.

ResumeAsync(WorkflowRegistration, WorkflowDefinitionDescriptor, WorkflowSignalExecutionContext, CancellationToken) method

public Task<WorkflowRuntimeExecutionResult> ResumeAsync(WorkflowRegistration registration, WorkflowDefinitionDescriptor definition, WorkflowSignalExecutionContext context, CancellationToken cancellationToken = default)

Resumes an instance with a signal.

Parameters

Returns

The outcome.

StartAsync(WorkflowRegistration, WorkflowDefinitionDescriptor, WorkflowBusinessReference, StartWorkflowRequest, object, CancellationToken) method

public Task<WorkflowRuntimeExecutionResult> StartAsync(WorkflowRegistration registration, WorkflowDefinitionDescriptor definition, WorkflowBusinessReference? businessReference, StartWorkflowRequest request, object startRequest, CancellationToken cancellationToken = default)

Starts an instance.

Parameters

Returns

The outcome.

WorkflowEngineRuntimeProvider class

public sealed class WorkflowEngineRuntimeProvider : IWorkflowRuntimeProvider

The Stella.Engine runtime: runs a definition through its execution handler and records the runtime state as an engine snapshot.

Parameters

WorkflowEngineRuntimeProvider(IWorkflowRuntimeDefinitionStore, IWorkflowRuntimeExecutionHandlerFactory) constructor

public WorkflowEngineRuntimeProvider(IWorkflowRuntimeDefinitionStore workflowRuntimeDefinitionStore, IWorkflowRuntimeExecutionHandlerFactory workflowRuntimeExecutionHandlerFactory)

The Stella.Engine runtime: runs a definition through its execution handler and records the runtime state as an engine snapshot.

Parameters

ProviderName property

public string ProviderName { get; }

The provider name.

CompleteAsync(WorkflowRegistration, WorkflowDefinitionDescriptor, WorkflowTaskExecutionContext, CancellationToken) method

public Task<WorkflowRuntimeExecutionResult> CompleteAsync(WorkflowRegistration registration, WorkflowDefinitionDescriptor definition, WorkflowTaskExecutionContext context, CancellationToken cancellationToken = default)

Completes a task.

Parameters

Returns

The outcome.

ResumeAsync(WorkflowRegistration, WorkflowDefinitionDescriptor, WorkflowSignalExecutionContext, CancellationToken) method

public Task<WorkflowRuntimeExecutionResult> ResumeAsync(WorkflowRegistration registration, WorkflowDefinitionDescriptor definition, WorkflowSignalExecutionContext context, CancellationToken cancellationToken = default)

Resumes an instance with a signal.

Parameters

Returns

The outcome.

StartAsync(WorkflowRegistration, WorkflowDefinitionDescriptor, WorkflowBusinessReference, StartWorkflowRequest, object, CancellationToken) method

public Task<WorkflowRuntimeExecutionResult> StartAsync(WorkflowRegistration registration, WorkflowDefinitionDescriptor definition, WorkflowBusinessReference? businessReference, StartWorkflowRequest request, object startRequest, CancellationToken cancellationToken = default)

Starts an instance.

Parameters

Returns

The outcome.

StellaOps.Workflow.Engine.ExternalActivities namespace

TypeKindDescription
ConstantsClassclassThe states, dispositions, event types and stop values of external activities.
WorkflowActivityCancelOutboxMessagerecordA cancel request to publish on a cancel lane.
WorkflowActivityControlServiceclassControls external activity steps: classifies failures for retry, retries steps, records continuations, reprocesses scopes, stops activities and publishes their cancel messages.
WorkflowActivityFailureRequestrecordA failed attempt to decide a retry for.
WorkflowActivityReprocessScopeRequestrecordAn operator request to run a scope again.
WorkflowActivityReprocessScopeResultrecordThe new occurrence of a reprocessed scope.
WorkflowActivityRetryDecisionrecordWhether and when a failed step is retried.
WorkflowActivityRetryStepRequestrecordAn operator request to retry a step now.
WorkflowActivityStopRequestrecordA request to stop the activities of a target: a cancel or a deadline.
WorkflowActivityStopResultrecordThe outcome of a stop.
WorkflowContinuationRegistrationRequestrecordA continuation an attempt reported, to register for the next attempt.
WorkflowExternalActivityCompletionDecisionrecordThe outcome of a completion: the delivery disposition, and the signal that resumes the waiting step when there is one.
WorkflowExternalActivityCompletionRequestrecordA completion received on the completed lane.
WorkflowExternalActivityCompletionResultrecordHow a completion was handled.
WorkflowExternalActivityCompletionServiceclassRecords a completion from the completed lane and, when the step can resume, builds the signal that resumes it, with the result (or the outcome and the failure) as payload.
WorkflowExternalActivityContractKindsclassThe contract kinds of external activities.
WorkflowExternalActivityDispatchRequestrecordAn attempt to dispatch.
WorkflowExternalActivityDispatchResultrecordA recorded dispatch.
WorkflowExternalActivityDispatchServiceclassTurns an external activity wait into a durable dispatch; the step’s evaluated request travels inline.
WorkflowExternalActivityLanesclassThe default lanes of external activities.
WorkflowExternalActivityOutboxMessagerecordA request to publish on an execute lane.
WorkflowExternalActivityRegistryclassThe external activity registry of the host’s signed manifest.
WorkflowExternalActivityRegistryEntryrecordAn external activity of the manifest.
WorkflowExternalActivityRegistryExceptionclassRaised when the registry manifest cannot be loaded.
WorkflowExternalActivityRegistryHealthCheckclassHealthy once the signed external activity registry is verified; unhealthy, with the readiness failure code, until then.
WorkflowExternalActivityRegistryManifestrecordThe signed registry manifest of a host.
WorkflowExternalActivityRegistryOptionsclassThe signed manifest of the external activities the host may run (WorkflowExternalActivityRegistry).
WorkflowExternalActivityServiceclassRecords external activity dispatches and completions once, with their outbox entries.
WorkflowExternalActivitySignalDispatcherclassDispatches an external activity step durably (DurableDispatch pending signal).

ConstantsClass class

public static class ConstantsClass

The states, dispositions, event types and stop values of external activities.

AttemptApplied constant

public const string AttemptApplied = "APPLIED"

Attempt: its completion was applied.

AttemptCanceled constant

public const string AttemptCanceled = "CANCELED"

Attempt: canceled.

AttemptDeadlineLost constant

public const string AttemptDeadlineLost = "DEADLINE_LOST"

Attempt: its deadline passed first.

AttemptDispatched constant

public const string AttemptDispatched = "DISPATCHED"

Attempt: dispatched, waiting for its completion.

AttemptFailed constant

public const string AttemptFailed = "FAILED"

Attempt: failed.

CancelPublished constant

public const string CancelPublished = "PUBLISHED"

Cancel: sent.

CancelReady constant

public const string CancelReady = "READY"

Cancel: waiting in the outbox.

CompletionApplied constant

public const string CompletionApplied = "APPLIED"

Completion: applied.

CompletionCanceled constant

public const string CompletionCanceled = "CANCELED"

Completion: arrived after a cancel.

CompletionDeadlineLost constant

public const string CompletionDeadlineLost = "DEADLINE_LOST"

Completion: arrived after the deadline.

CompletionDuplicate constant

public const string CompletionDuplicate = "DUPLICATE"

Completion: a duplicate of one already applied.

CompletionLate constant

public const string CompletionLate = "LATE"

Completion: arrived after the attempt ended.

CompletionReconciliation constant

public const string CompletionReconciliation = "RECONCILING"

Completion: kept for reconciliation.

CompletionRejected constant

public const string CompletionRejected = "REJECTED"

Completion: refused.

ContinuationConsumed constant

public const string ContinuationConsumed = "CONSUMED"

Continuation: resumed by an attempt.

ContinuationReady constant

public const string ContinuationReady = "READY"

Continuation: waiting for the next attempt.

ContinuationRevoked constant

public const string ContinuationRevoked = "REVOKED"

Continuation: revoked by a cancel.

DispatchPublished constant

public const string DispatchPublished = "PUBLISHED"

Dispatch: sent.

DispatchReady constant

public const string DispatchReady = "READY"

Dispatch: waiting in the outbox.

DispatchRevoked constant

public const string DispatchRevoked = "REVOKED"

Dispatch: revoked before it was sent.

EventActivityCanceled constant

public const string EventActivityCanceled = "EXTERNAL_ACTIVITY_CANCELED"

History event: an activity was canceled.

EventActivityCompleted constant

public const string EventActivityCompleted = "EXTERNAL_ACTIVITY_COMPLETED"

History event: an activity completed.

EventActivityDeadlineWon constant

public const string EventActivityDeadlineWon = "EXTERNAL_ACTIVITY_DEADLINE_WON"

History event: the deadline ended an activity first.

EventActivityDispatched constant

public const string EventActivityDispatched = "EXTERNAL_ACTIVITY_DISPATCHED"

History event: an activity was dispatched.

EventActivityFailed constant

public const string EventActivityFailed = "EXTERNAL_ACTIVITY_FAILED"

History event: an activity failed.

FailureActivityDeadline constant

public const string FailureActivityDeadline = "ACTIVITY_DEADLINE"

Failure category of an activity that reached its deadline.

ReprocessRequested constant

public const string ReprocessRequested = "REQUESTED"

Scope reprocess: requested.

StepCanceled constant

public const string StepCanceled = "CANCELED"

Step: canceled.

StepCompleted constant

public const string StepCompleted = "COMPLETED"

Step: completed.

StepDeadlineFailure constant

public const string StepDeadlineFailure = "TECHNICAL_FAILURE_CLEANUP_PENDING"

Step: failed at its deadline; cleanup is pending.

StepDeadlinePendingReconciliation constant

public const string StepDeadlinePendingReconciliation = "DEADLINE_PENDING_RECONCILIATION"

Step: its deadline passed; reconciliation is pending.

StepRetryExhausted constant

public const string StepRetryExhausted = "RETRY_EXHAUSTED"

Step: no retry is left.

StepRetryPending constant

public const string StepRetryPending = "RETRY_PENDING"

Step: a retry is pending.

StepWaiting constant

public const string StepWaiting = "WAITING"

Step: waiting for its attempt.

StopModeCancel constant

public const string StopModeCancel = "CANCEL"

Stop mode: a cancel.

StopModeDeadline constant

public const string StopModeDeadline = "DEADLINE"

Stop mode: a deadline.

StopTargetExecution constant

public const string StopTargetExecution = "EXECUTION"

Stop target: a whole execution.

StopTargetMap constant

public const string StopTargetMap = "MAP"

Stop target: a map.

StopTargetScope constant

public const string StopTargetScope = "SCOPE"

Stop target: a scope.

StopTargetStep constant

public const string StopTargetStep = "STEP"

Stop target: one step.

WorkflowActivityCancelOutboxMessage record

public sealed record WorkflowActivityCancelOutboxMessage

A cancel request to publish on a cancel lane.

WorkflowActivityCancelOutboxMessage() constructor

public WorkflowActivityCancelOutboxMessage()

Creates an instance of WorkflowActivityCancelOutboxMessage.

AttemptId property

public required string AttemptId { get; init; }

The attempt.

CancelFenceVersion property

public required long CancelFenceVersion { get; init; }

The cancel fence of the request.

CancelId property

public required string CancelId { get; init; }

The cancel request.

CancelLane property

public required string CancelLane { get; init; }

The lane the cancel goes to.

CanonicalPayloadJson property

public required string CanonicalPayloadJson { get; init; }

The canonical payload, as JSON.

EventId property

public required string EventId { get; init; }

The cancel event.

PayloadSha256 property

public required string PayloadSha256 { get; init; }

The SHA-256 of the payload.

WorkflowActivityControlService class

public sealed class WorkflowActivityControlService

Controls external activity steps: classifies failures for retry, retries steps, records continuations, reprocesses scopes, stops activities and publishes their cancel messages.

Parameters

WorkflowActivityControlService(IWorkflowExternalActivityStore, IWorkflowMutationCoordinator, IWorkflowExternalActivityRegistry, TimeProvider) constructor

public WorkflowActivityControlService(IWorkflowExternalActivityStore store, IWorkflowMutationCoordinator mutationCoordinator, IWorkflowExternalActivityRegistry registry, TimeProvider timeProvider)

Controls external activity steps: classifies failures for retry, retries steps, records continuations, reprocesses scopes, stops activities and publishes their cancel messages.

Parameters

ClassifyFailureAsync(WorkflowActivityFailureRequest, CancellationToken) method

public Task<WorkflowActivityRetryDecision> ClassifyFailureAsync(WorkflowActivityFailureRequest request, CancellationToken cancellationToken = default)

Records a step failure and decides on a retry: the step waits for a retry after the policy’s delay, or its retries are exhausted when no attempt is left, the category is not retryable or the absolute deadline has passed.

Parameters

Returns

The retry decision.

GetReadyCancelsAsync(int, CancellationToken) method

public Task<IReadOnlyList<WorkflowActivityCancelOutboxMessage>> GetReadyCancelsAsync(int maxCount, CancellationToken cancellationToken = default)

Returns the cancel messages ready to publish.

Parameters

Returns

The messages.

Exceptions

MarkCancelPublishedAsync(string, DateTimeOffset, CancellationToken) method

public Task MarkCancelPublishedAsync(string cancelId, DateTimeOffset publishedAt, CancellationToken cancellationToken = default)

Marks a cancel message published.

Parameters

Returns

A task that completes when the message is marked.

RegisterContinuationAsync(WorkflowContinuationRegistrationRequest, CancellationToken) method

public Task<WorkflowContinuationLineage> RegisterContinuationAsync(WorkflowContinuationRegistrationRequest request, CancellationToken cancellationToken = default)

Records the continuation of an attempt, for the next attempt. A continuation already recorded under its lineage id is returned when its hash matches.

Parameters

Returns

The continuation lineage.

Exceptions

ReprocessScopeAsync(WorkflowActivityReprocessScopeRequest, CancellationToken) method

public Task<WorkflowActivityReprocessScopeResult> ReprocessScopeAsync(WorkflowActivityReprocessScopeRequest request, CancellationToken cancellationToken = default)

Records a request to reprocess a scope. The successor scope id is the source scope id followed by :r and the occurrence number.

Parameters

Returns

The reprocess and its successor scope.

RetryStepAsync(WorkflowActivityRetryStepRequest, CancellationToken) method

public Task<WorkflowActivityRetryDecision> RetryStepAsync(WorkflowActivityRetryStepRequest request, CancellationToken cancellationToken = default)

Dispatches the next attempt of a step that waits for a retry, once its delay has passed; marks the retries exhausted when no attempt is left.

Parameters

Returns

The retry decision, with the dispatch.

Exceptions

StopAsync(WorkflowActivityStopRequest, CancellationToken) method

public Task<WorkflowActivityStopResult> StopAsync(WorkflowActivityStopRequest request, CancellationToken cancellationToken = default)

Stops the activities of a target in one change scope: open steps are canceled, or fail with a deadline in deadline mode; their ready dispatches are revoked and cancel messages are queued.

Parameters

Returns

The counts of the stop.

Exceptions

WorkflowActivityFailureRequest record

public sealed record WorkflowActivityFailureRequest

A failed attempt to decide a retry for.

WorkflowActivityFailureRequest() constructor

public WorkflowActivityFailureRequest()

Creates an instance of WorkflowActivityFailureRequest.

DeterministicJitterSeed property

public int DeterministicJitterSeed { get; init; }

The seed of the deterministic jitter.

FailureCategory property

public required string FailureCategory { get; init; }

The failure category.

ProviderRetryAfterSeconds property

public int? ProviderRetryAfterSeconds { get; init; }

The delay the provider asked for, in seconds.

RetryPolicy property

public required WorkflowRetryPolicyDeclaration RetryPolicy { get; init; }

The retry policy.

StepExecutionId property

public required string StepExecutionId { get; init; }

The step execution.

WorkflowActivityReprocessScopeRequest record

public sealed record WorkflowActivityReprocessScopeRequest

An operator request to run a scope again.

WorkflowActivityReprocessScopeRequest() constructor

public WorkflowActivityReprocessScopeRequest()

Creates an instance of WorkflowActivityReprocessScopeRequest.

ReasonCode property

public required string ReasonCode { get; init; }

Why.

RequestedBy property

public required string RequestedBy { get; init; }

Who requested it.

SourceScopeExecutionId property

public required string SourceScopeExecutionId { get; init; }

The scope to run again.

WorkflowExecutionId property

public required string WorkflowExecutionId { get; init; }

The execution (workflow instance).

WorkflowActivityReprocessScopeResult record

public sealed record WorkflowActivityReprocessScopeResult

The new occurrence of a reprocessed scope.

WorkflowActivityReprocessScopeResult() constructor

public WorkflowActivityReprocessScopeResult()

Creates an instance of WorkflowActivityReprocessScopeResult.

OccurrenceNumber property

public required int OccurrenceNumber { get; init; }

The occurrence number.

ReprocessId property

public required string ReprocessId { get; init; }

The reprocess request.

Status property

public required string Status { get; init; }

The status.

SuccessorScopeExecutionId property

public required string SuccessorScopeExecutionId { get; init; }

The new scope occurrence.

WorkflowActivityRetryDecision record

public sealed record WorkflowActivityRetryDecision

Whether and when a failed step is retried.

WorkflowActivityRetryDecision() constructor

public WorkflowActivityRetryDecision()

Creates an instance of WorkflowActivityRetryDecision.

CompletedSemanticAttempts property

public required int CompletedSemanticAttempts { get; init; }

The attempts made.

Dispatch property

public WorkflowExternalActivityDispatchResult? Dispatch { get; init; }

The dispatch of the retry, when it was sent at once.

Disposition property

public required string Disposition { get; init; }

How it was handled.

NextSemanticAttempt property

public int? NextSemanticAttempt { get; init; }

The number of the next attempt.

NotBeforeUtc property

public DateTime? NotBeforeUtc { get; init; }

The earliest time of the retry, in UTC.

RetryAllowed property

public required bool RetryAllowed { get; init; }

Whether a retry is allowed.

ReuseBinding property

public required bool ReuseBinding { get; init; }

Whether the retry keeps the binding of the previous attempt.

StepExecutionId property

public required string StepExecutionId { get; init; }

The step execution.

WorkflowActivityRetryStepRequest record

public sealed record WorkflowActivityRetryStepRequest

An operator request to retry a step now.

WorkflowActivityRetryStepRequest() constructor

public WorkflowActivityRetryStepRequest()

Creates an instance of WorkflowActivityRetryStepRequest.

AttemptId property

public required string AttemptId { get; init; }

The attempt.

DispatchId property

public required string DispatchId { get; init; }

The dispatch.

ExpectedCancelFenceVersion property

public long ExpectedCancelFenceVersion { get; init; }

The cancel fence the step must still have.

RequestedBy property

public required string RequestedBy { get; init; }

Who requested it.

StepExecutionId property

public required string StepExecutionId { get; init; }

The step execution.

WorkflowActivityStopRequest record

public sealed record WorkflowActivityStopRequest

A request to stop the activities of a target: a cancel or a deadline.

WorkflowActivityStopRequest() constructor

public WorkflowActivityStopRequest()

Creates an instance of WorkflowActivityStopRequest.

DeadlineAt property

public DateTimeOffset? DeadlineAt { get; init; }

The deadline, for a deadline stop.

Mode property

public required string Mode { get; init; }

CANCEL or DEADLINE.

ReasonCode property

public required string ReasonCode { get; init; }

Why.

TargetId property

public required string TargetId { get; init; }

The target.

TargetKind property

public required string TargetKind { get; init; }

The kind of the target.

WorkflowActivityStopResult record

public sealed record WorkflowActivityStopResult

The outcome of a stop.

WorkflowActivityStopResult() constructor

public WorkflowActivityStopResult()

Creates an instance of WorkflowActivityStopResult.

AlreadyTerminalCount property

public required int AlreadyTerminalCount { get; init; }

The steps that had already ended.

CancelMessagesQueued property

public required int CancelMessagesQueued { get; init; }

The cancel requests queued.

ReconciliationCount property

public required int ReconciliationCount { get; init; }

The steps left for reconciliation.

TargetId property

public required string TargetId { get; init; }

The target.

TargetKind property

public required string TargetKind { get; init; }

The kind of the target.

WonCount property

public required int WonCount { get; init; }

The steps the stop ended.

WorkflowContinuationRegistrationRequest record

public sealed record WorkflowContinuationRegistrationRequest

A continuation an attempt reported, to register for the next attempt.

WorkflowContinuationRegistrationRequest() constructor

public WorkflowContinuationRegistrationRequest()

Creates an instance of WorkflowContinuationRegistrationRequest.

ContinuationRef property

public required string ContinuationRef { get; init; }

The provider’s continuation reference.

ContinuationSha256 property

public required string ContinuationSha256 { get; init; }

The SHA-256 of the continuation.

Generation property

public long Generation { get; init; }

The continuation generation.

LineageId property

public required string LineageId { get; init; }

The lineage.

ScopeExecutionId property

public required string ScopeExecutionId { get; init; }

The scope of the step.

SourceAttemptId property

public required string SourceAttemptId { get; init; }

The attempt that left the continuation.

SourceCompletionEventId property

public required string SourceCompletionEventId { get; init; }

The completion that carried it.

StepExecutionId property

public required string StepExecutionId { get; init; }

The step execution.

WorkflowExecutionId property

public required string WorkflowExecutionId { get; init; }

The execution (workflow instance).

WorkflowExternalActivityCompletionDecision record

public sealed record WorkflowExternalActivityCompletionDecision

The outcome of a completion: the delivery disposition, and the signal that resumes the waiting step when there is one.

Parameters

WorkflowExternalActivityCompletionDecision(WorkflowDeliveryDisposition, WorkflowSignalEnvelope) constructor

public WorkflowExternalActivityCompletionDecision(WorkflowDeliveryDisposition Disposition, WorkflowSignalEnvelope? ResumeSignal)

The outcome of a completion: the delivery disposition, and the signal that resumes the waiting step when there is one.

Parameters

Disposition property

public WorkflowDeliveryDisposition Disposition { get; init; }

The delivery disposition.

ResumeSignal property

public WorkflowSignalEnvelope? ResumeSignal { get; init; }

The signal that resumes the waiting step or map item; null when nothing resumes.

WorkflowExternalActivityCompletionRequest record

public sealed record WorkflowExternalActivityCompletionRequest

A completion received on the completed lane.

WorkflowExternalActivityCompletionRequest() constructor

public WorkflowExternalActivityCompletionRequest()

Creates an instance of WorkflowExternalActivityCompletionRequest.

AttemptId property

public required string AttemptId { get; init; }

The attempt.

CanonicalCompletionJson property

public required string CanonicalCompletionJson { get; init; }

The canonical completion, as JSON.

EventId property

public required string EventId { get; init; }

The completion event.

ReceivedAt property

public DateTimeOffset? ReceivedAt { get; init; }

When the completion was received; now when not set.

WorkflowExternalActivityCompletionResult record

public sealed record WorkflowExternalActivityCompletionResult

How a completion was handled.

WorkflowExternalActivityCompletionResult() constructor

public WorkflowExternalActivityCompletionResult()

Creates an instance of WorkflowExternalActivityCompletionResult.

AcknowledgedAfterCommit property

public required bool AcknowledgedAfterCommit { get; init; }

Whether the completion may be acknowledged: its handling committed.

AttemptId property

public required string AttemptId { get; init; }

The attempt.

Disposition property

public required string Disposition { get; init; }

How it was handled.

EventId property

public required string EventId { get; init; }

The completion event.

ExecutionVersion property

public long? ExecutionVersion { get; init; }

The execution version after the operation.

SafeCode property

public string? SafeCode { get; init; }

The safe code of a refusal.

WorkflowExternalActivityCompletionService class

public sealed class WorkflowExternalActivityCompletionService

Records a completion from the completed lane and, when the step can resume, builds the signal that resumes it, with the result (or the outcome and the failure) as payload.

Parameters

WorkflowExternalActivityCompletionService(IWorkflowExternalActivityStore, WorkflowExternalActivityService, IWorkflowMutationCoordinator, WorkflowMapCoordinator) constructor

public WorkflowExternalActivityCompletionService(IWorkflowExternalActivityStore store, WorkflowExternalActivityService activityService, IWorkflowMutationCoordinator? mutationCoordinator = null, WorkflowMapCoordinator? mapCoordinator = null)

Records a completion from the completed lane and, when the step can resume, builds the signal that resumes it, with the result (or the outcome and the failure) as payload.

Parameters

CompleteAsync(WorkflowActivityCompletionV1, string, CancellationToken) method

public Task<WorkflowExternalActivityCompletionDecision> CompleteAsync(WorkflowActivityCompletionV1 completion, string canonicalCompletionJson, CancellationToken cancellationToken)

Records a completion and decides how to acknowledge it.

Parameters

Returns

The disposition and the resume signal.

Exceptions

WorkflowExternalActivityContractKinds class

public static class WorkflowExternalActivityContractKinds

The contract kinds of external activities.

WorkflowActivity constant

public const string WorkflowActivity = "WORKFLOW_ACTIVITY_V1"

The workflow activity contract, version 1.

WorkflowExternalActivityDispatchRequest record

public sealed record WorkflowExternalActivityDispatchRequest

An attempt to dispatch.

WorkflowExternalActivityDispatchRequest() constructor

public WorkflowExternalActivityDispatchRequest()

Creates an instance of WorkflowExternalActivityDispatchRequest.

AbsoluteDeadlineAt property

public DateTimeOffset? AbsoluteDeadlineAt { get; init; }

The deadline over all attempts.

AttemptId property

public required string AttemptId { get; init; }

The attempt.

AttemptNumber property

public required int AttemptNumber { get; init; }

The attempt number, from 1.

CanonicalRequestJson property

public required string CanonicalRequestJson { get; init; }

The canonical request, as JSON.

ContractVersion property

public required string ContractVersion { get; init; }

The contract version of the activity.

CreatedAt property

public DateTimeOffset? CreatedAt { get; init; }

When the dispatch was created; now when not set.

DeadlineAt property

public required DateTimeOffset DeadlineAt { get; init; }

The deadline of the attempt.

DestinationCode property

public required string DestinationCode { get; init; }

The destination of the activity.

DispatchId property

public required string DispatchId { get; init; }

The dispatch.

ExpectedExecutionVersion property

public required long ExpectedExecutionVersion { get; init; }

The execution version the dispatch expects.

LogicalStepKey property

public required string LogicalStepKey { get; init; }

The step in the definition.

MapItemId property

public string? MapItemId { get; init; }

The map item the step runs for, when it runs in a map.

OperationCode property

public required string OperationCode { get; init; }

The operation of the activity.

RetryPolicy property

public WorkflowRetryPolicyDeclaration? RetryPolicy { get; init; }

The retry policy of the step.

ScopeExecutionId property

public required string ScopeExecutionId { get; init; }

The scope of the step.

StepExecutionId property

public required string StepExecutionId { get; init; }

The step execution.

WorkflowExecutionId property

public required string WorkflowExecutionId { get; init; }

The execution (workflow instance).

WorkflowExternalActivityDispatchResult record

public sealed record WorkflowExternalActivityDispatchResult

A recorded dispatch.

WorkflowExternalActivityDispatchResult() constructor

public WorkflowExternalActivityDispatchResult()

Creates an instance of WorkflowExternalActivityDispatchResult.

AttemptId property

public required string AttemptId { get; init; }

The attempt.

DispatchId property

public required string DispatchId { get; init; }

The dispatch.

ExecuteLane property

public required string ExecuteLane { get; init; }

The lane the request goes to.

ExecutionVersion property

public required long ExecutionVersion { get; init; }

The execution version after the operation.

Replayed property

public required bool Replayed { get; init; }

Whether the dispatch already existed and was returned as recorded.

RequestSha256 property

public required string RequestSha256 { get; init; }

The SHA-256 of the request.

WorkflowExternalActivityDispatchService class

public sealed class WorkflowExternalActivityDispatchService

Turns an external activity wait into a durable dispatch; the step’s evaluated request travels inline.

Parameters

WorkflowExternalActivityDispatchService(IWorkflowExternalActivityStore, IWorkflowExternalActivityRegistry, WorkflowExternalActivityService) constructor

public WorkflowExternalActivityDispatchService(IWorkflowExternalActivityStore store, IWorkflowExternalActivityRegistry registry, WorkflowExternalActivityService activityService)

Turns an external activity wait into a durable dispatch; the step’s evaluated request travels inline.

Parameters

DispatchAsync(string, WorkflowPendingSignalPlan, CancellationToken) method

public Task<WorkflowExternalActivityDispatchResult> DispatchAsync(string workflowExecutionId, WorkflowPendingSignalPlan pendingSignal, CancellationToken cancellationToken)

Dispatches the activity a pending signal plan waits for.

Parameters

Returns

The dispatch.

Exceptions

DispatchMapItemAsync(string, WorkflowPendingSignalPlan, string, WorkflowRetryPolicyDeclaration, DateTime?, CancellationToken) method

public Task<WorkflowExternalActivityDispatchResult> DispatchMapItemAsync(string workflowExecutionId, WorkflowPendingSignalPlan pendingSignal, string mapItemId, WorkflowRetryPolicyDeclaration retryPolicy, DateTime? absoluteDeadlineAtUtc, CancellationToken cancellationToken)

Dispatches the activity of a map item.

Parameters

Returns

The dispatch.

WorkflowExternalActivityLanes class

public static class WorkflowExternalActivityLanes

The default lanes of external activities.

Cancel constant

public const string Cancel = "workflow.activity.cancel.v1"

The cancel lane.

Completed constant

public const string Completed = "workflow.activity.completed.v1"

The completed lane.

Execute constant

public const string Execute = "workflow.activity.execute.v1"

The execute lane.

WorkflowExternalActivityOutboxMessage record

public sealed record WorkflowExternalActivityOutboxMessage

A request to publish on an execute lane.

WorkflowExternalActivityOutboxMessage() constructor

public WorkflowExternalActivityOutboxMessage()

Creates an instance of WorkflowExternalActivityOutboxMessage.

AttemptId property

public required string AttemptId { get; init; }

The attempt.

CanonicalRequestJson property

public required string CanonicalRequestJson { get; init; }

The canonical request, as JSON.

DispatchId property

public required string DispatchId { get; init; }

The dispatch.

ExecuteLane property

public required string ExecuteLane { get; init; }

The lane the request goes to.

RequestSha256 property

public required string RequestSha256 { get; init; }

The SHA-256 of the request.

WorkflowExternalActivityRegistry class

public sealed class WorkflowExternalActivityRegistry : IWorkflowExternalActivityRegistry

The external activity registry of the host’s signed manifest.

WorkflowExternalActivityRegistry(IOptions<WorkflowExternalActivityRegistryOptions>) constructor

public WorkflowExternalActivityRegistry(IOptions<WorkflowExternalActivityRegistryOptions> options)

Loads the manifest; a manifest that fails to load leaves the registry not ready, with the failure code.

Parameters

IsReady property

public bool IsReady { get; }

Whether the manifest loaded; a registry that is not ready resolves nothing.

ReadinessFailureCode property

public string? ReadinessFailureCode { get; }

Why the manifest did not load.

IsExternalTransportAddress(WorkflowTransportAddressDeclaration) method

public bool IsExternalTransportAddress(WorkflowTransportAddressDeclaration address)

Whether a transport address targets a lane of the registry: a RabbitMQ routing key or an endpoint path that an activity uses.

Parameters

Returns

Whether it does.

TryResolve(string, string, string, out WorkflowExternalActivityRegistration) method

public bool TryResolve(string destinationCode, string operationCode, string contractVersion, out WorkflowExternalActivityRegistration registration)

Finds an activity by destination, operation and contract version.

Parameters

Returns

Whether the registry is ready and has the activity.

WorkflowExternalActivityRegistryEntry record

public sealed record WorkflowExternalActivityRegistryEntry

An external activity of the manifest.

WorkflowExternalActivityRegistryEntry() constructor

public WorkflowExternalActivityRegistryEntry()

Creates an instance of WorkflowExternalActivityRegistryEntry.

CancelLane property

public string? CancelLane { get; init; }

The lane the cancels go to, when there is one.

CompletionLane property

public string? CompletionLane { get; init; }

The lane the completions come back on, when it differs.

ContractKind property

public required string ContractKind { get; init; }

The contract kind.

ContractVersion property

public required string ContractVersion { get; init; }

The contract version.

DestinationCode property

public required string DestinationCode { get; init; }

The destination.

ExecuteLane property

public required string ExecuteLane { get; init; }

The lane the requests go to.

HandlerBuildSha256 property

public required string HandlerBuildSha256 { get; init; }

The SHA-256 of the handler build.

OperationCode property

public required string OperationCode { get; init; }

The operation.

RequestSchemaId property

public required string RequestSchemaId { get; init; }

The schema of the request.

RequestSchemaVersion property

public required int RequestSchemaVersion { get; init; }

The version of the request schema.

ResultSchemaId property

public string? ResultSchemaId { get; init; }

The schema of the result, when there is one.

ResultSchemaVersion property

public int? ResultSchemaVersion { get; init; }

The version of the result schema.

WorkflowExternalActivityRegistryException class

public sealed class WorkflowExternalActivityRegistryException : Exception

Raised when the registry manifest cannot be loaded.

WorkflowExternalActivityRegistryException(string) constructor

public WorkflowExternalActivityRegistryException(string code)

Creates the exception.

Parameters

WorkflowExternalActivityRegistryException(string, Exception) constructor

public WorkflowExternalActivityRegistryException(string code, Exception innerException)

Creates the exception with its cause.

Parameters

Code property

public string Code { get; }

The failure code.

WorkflowExternalActivityRegistryHealthCheck class

public sealed class WorkflowExternalActivityRegistryHealthCheck : IHealthCheck

Healthy once the signed external activity registry is verified; unhealthy, with the readiness failure code, until then.

Parameters

WorkflowExternalActivityRegistryHealthCheck(WorkflowExternalActivityRegistry) constructor

public WorkflowExternalActivityRegistryHealthCheck(WorkflowExternalActivityRegistry registry)

Healthy once the signed external activity registry is verified; unhealthy, with the readiness failure code, until then.

Parameters

CheckHealthAsync(HealthCheckContext, CancellationToken) method

public Task<HealthCheckResult> CheckHealthAsync(HealthCheckContext context, CancellationToken cancellationToken = default)

See IHealthCheck.CheckHealthAsync(HealthCheckContext, CancellationToken).

WorkflowExternalActivityRegistryManifest record

public sealed record WorkflowExternalActivityRegistryManifest

The signed registry manifest of a host.

WorkflowExternalActivityRegistryManifest() constructor

public WorkflowExternalActivityRegistryManifest()

Creates an instance of WorkflowExternalActivityRegistryManifest.

ContractVersion property

public required int ContractVersion { get; init; }

The manifest contract version.

Entries property

public required IReadOnlyList<WorkflowExternalActivityRegistryEntry> Entries { get; init; }

The activities.

WorkflowExternalActivityRegistryOptions class

public sealed class WorkflowExternalActivityRegistryOptions

The signed manifest of the external activities the host may run (WorkflowExternalActivityRegistry). Without a manifest the host runs no external activity, and definition validation rejects an external activity step. With one, the SHA-256 of the canonical manifest must equal WorkflowExternalActivityRegistryOptions.ManifestSha256and its RSA signature must verify with the public key, or loading the registry fails.

WorkflowExternalActivityRegistryOptions() constructor

public WorkflowExternalActivityRegistryOptions()

Creates an instance of WorkflowExternalActivityRegistryOptions.

SectionName constant

public const string SectionName = "WorkflowExternalActivityRegistry"

The configuration section the options bind from: WorkflowExternalActivityRegistry.

ManifestJson property

public string? ManifestJson { get; set; }

The manifest as inline JSON; takes precedence over WorkflowExternalActivityRegistryOptions.ManifestPath.

ManifestPath property

public string? ManifestPath { get; set; }

The manifest file; WorkflowExternalActivityRegistryOptions.ManifestJsontakes precedence when set.

ManifestSha256 property

public string? ManifestSha256 { get; set; }

The expected SHA-256 of the canonical manifest JSON. Required with a manifest.

PublicKeyPath property

public string? PublicKeyPath { get; set; }

The PEM file of the RSA public key that verifies the signature; WorkflowExternalActivityRegistryOptions.PublicKeyPemtakes precedence when set.

PublicKeyPem property

public string? PublicKeyPem { get; set; }

The RSA public key in PEM form; takes precedence over WorkflowExternalActivityRegistryOptions.PublicKeyPath.

SignatureBase64 property

public string? SignatureBase64 { get; set; }

The base64 RSA signature (SHA-256, PKCS #1 v1.5) of the canonical manifest bytes; takes precedence over WorkflowExternalActivityRegistryOptions.SignaturePath.

SignaturePath property

public string? SignaturePath { get; set; }

The file that holds the base64 signature; WorkflowExternalActivityRegistryOptions.SignatureBase64takes precedence when set.

WorkflowExternalActivityService class

public sealed class WorkflowExternalActivityService

Records external activity dispatches and completions once, with their outbox entries.

Parameters

WorkflowExternalActivityService(IWorkflowExternalActivityStore, IWorkflowMutationCoordinator, IWorkflowExternalActivityRegistry) constructor

public WorkflowExternalActivityService(IWorkflowExternalActivityStore store, IWorkflowMutationCoordinator mutationCoordinator, IWorkflowExternalActivityRegistry registry)

Records external activity dispatches and completions once, with their outbox entries.

Parameters

CompleteAsync(WorkflowExternalActivityCompletionRequest, CancellationToken) method

public Task<WorkflowExternalActivityCompletionResult> CompleteAsync(WorkflowExternalActivityCompletionRequest request, CancellationToken cancellationToken = default)

Records an activity completion, canonicalized, and decides whether it applies to its attempt. A completion already recorded under its event id is returned as a duplicate when it names the same attempt and has the same hash.

Parameters

Returns

The completion and its disposition.

Exceptions

DispatchAsync(WorkflowExternalActivityDispatchRequest, CancellationToken) method

public Task<WorkflowExternalActivityDispatchResult> DispatchAsync(WorkflowExternalActivityDispatchRequest request, CancellationToken cancellationToken = default)

Records the dispatch of an activity attempt for its execute lane. A dispatch already recorded under the attempt id is returned as replayed when it has the same dispatch id and request hash.

Parameters

Returns

The dispatch.

Exceptions

GetReadyDispatchesAsync(int, CancellationToken) method

public Task<IReadOnlyList<WorkflowExternalActivityOutboxMessage>> GetReadyDispatchesAsync(int maxCount, CancellationToken cancellationToken = default)

Returns the dispatch messages ready to publish.

Parameters

Returns

The messages.

Exceptions

MarkPublishedAsync(string, DateTimeOffset, CancellationToken) method

public Task MarkPublishedAsync(string dispatchId, DateTimeOffset publishedAt, CancellationToken cancellationToken = default)

Marks a dispatch message published.

Parameters

Returns

A task that completes when the message is marked.

WorkflowExternalActivitySignalDispatcher class

public sealed class WorkflowExternalActivitySignalDispatcher : IWorkflowPendingSignalDispatcher

Dispatches an external activity step durably (DurableDispatch pending signal).

WorkflowExternalActivitySignalDispatcher(WorkflowExternalActivityDispatchService) constructor

public WorkflowExternalActivitySignalDispatcher(WorkflowExternalActivityDispatchService dispatchService)

Dispatches an external activity step durably (DurableDispatch pending signal).

CanDispatch(WorkflowPendingSignalPlan) method

public bool CanDispatch(WorkflowPendingSignalPlan pendingSignal)

Whether this dispatcher sends a pending signal.

Parameters

Returns

Whether it does.

DispatchAsync(string, WorkflowPendingSignalPlan, WorkflowRuntimeStateRecord, CancellationToken) method

public Task<long> DispatchAsync(string workflowInstanceId, WorkflowPendingSignalPlan pendingSignal, WorkflowRuntimeStateRecord runtimeState, CancellationToken cancellationToken = default)

Dispatches the signal and returns the execution version the next signal must expect.

StellaOps.Workflow.Engine.History namespace

TypeKindDescription
WorkflowHistoryPagerecordA page of the history events of an execution.
WorkflowHistoryServiceclassReads and compacts the history events of executions.

WorkflowHistoryPage record

public sealed record WorkflowHistoryPage

A page of the history events of an execution.

WorkflowHistoryPage() constructor

public WorkflowHistoryPage()

Creates an instance of WorkflowHistoryPage.

Disposition property

public required string Disposition { get; init; }

OK, or CURSOR_COMPACTED when the events after the requested sequence were compacted away; the page is then empty.

Events property

public required IReadOnlyList<WorkflowHistoryEvent> Events { get; init; }

The events.

HistoryFloorSequence property

public required long HistoryFloorSequence { get; init; }

The first history sequence still kept.

SnapshotSequence property

public required long SnapshotSequence { get; init; }

The last history sequence when the page was read.

WorkflowHistoryService class

public sealed class WorkflowHistoryService

Reads and compacts the history events of executions.

Parameters

WorkflowHistoryService(IWorkflowHistoryStore) constructor

public WorkflowHistoryService(IWorkflowHistoryStore store)

Reads and compacts the history events of executions.

Parameters

CompactPrefixAsync(string, long, int, CancellationToken) method

public Task<WorkflowHistoryCompactionResult> CompactPrefixAsync(string workflowExecutionId, long throughSequence, int maxCount, CancellationToken cancellationToken = default)

Deletes the events up to a sequence, unless the execution is under a legal hold or the HOLD_ALL retention policy.

Parameters

Returns

The events deleted and the new history floor.

GetEventsAsync(string, long, int, CancellationToken) method

public Task<WorkflowHistoryPage> GetEventsAsync(string workflowExecutionId, long afterSequence, int maxCount, CancellationToken cancellationToken = default)

Reads the events after a sequence.

Parameters

Returns

The page.

Exceptions

StellaOps.Workflow.Engine.HostedServices namespace

TypeKindDescription
WorkflowRetentionHostedServiceclassRuns the instance retention at the configured interval when it is enabled, on one service instance at a time (it takes the hosted job lock).
WorkflowSignalDeliveryAttemptTrackerclassPer-process tracker that records how many times the signal pump worker has dispatched a given signal envelope to the processor in the current host lifetime.
WorkflowSignalPumpHostedServiceclassRuns WorkflowEngine:MaxConcurrentSignalHandlers signal pump workers (at least one) until the host stops.
WorkflowSignalPumpWorkerclassMoves signals from the signal bus to the signal processor, one at a time.

WorkflowRetentionHostedService class

public sealed class WorkflowRetentionHostedService : BackgroundService

Runs the instance retention at the configured interval when it is enabled, on one service instance at a time (it takes the hosted job lock).

Parameters

WorkflowRetentionHostedService(IServiceScopeFactory, IOptions<WorkflowRetentionHostedJobOptions>, ILogger<WorkflowRetentionHostedService>) constructor

public WorkflowRetentionHostedService(IServiceScopeFactory serviceScopeFactory, IOptions<WorkflowRetentionHostedJobOptions> options, ILogger<WorkflowRetentionHostedService> logger)

Runs the instance retention at the configured interval when it is enabled, on one service instance at a time (it takes the hosted job lock).

Parameters

WorkflowSignalDeliveryAttemptTracker class

public sealed class WorkflowSignalDeliveryAttemptTracker

Per-process tracker that records how many times the signal pump worker has dispatched a given signal envelope to the processor in the current host lifetime. The worker counts a delivery as the larger of this count and the transport-reported IWorkflowSignalLease.DeliveryCount: the PostgreSQL and MongoDB stores keep that count with the signal, so it holds across nodes and restarts, and this tracker is the floor for a transport that reports fewer deliveries than it made.

Remarks

The tracker lives for the host lifetime: counts reset on host restart. A transport whose delivery count does not survive a restart needs its own queue-side retry limit to move a poison message that survives a worker restart to a dead-letter queue.

To bound memory under high cardinality the tracker is capped; the oldest entries are evicted FIFO when the cap is reached. The cap is large enough to cover real-world fan-out (~16K concurrent failing signals) but small enough to ensure a runaway tracker cannot exhaust process memory.

WorkflowSignalDeliveryAttemptTracker() constructor

public WorkflowSignalDeliveryAttemptTracker()

Creates an instance of WorkflowSignalDeliveryAttemptTracker.

Forget(string) method

public void Forget(string signalId)

Forget the tracking state for signalId. Called when the signal is acknowledged (processed, concurrency-skipped, or dead-lettered) so the tracker does not leak across distinct lifecycles of the same signal id.

Peek(string) method

public int Peek(string signalId)

Returns the current attempt count for signalId without mutating the tracker. Returns 0 when the signal is not tracked.

RegisterAttempt(string) method

public int RegisterAttempt(string signalId)

Record that the worker is about to dispatch signalId and return the resulting attempt count (1 for the first dispatch, 2 for the next, etc.).

WorkflowSignalPumpHostedService class

public sealed class WorkflowSignalPumpHostedService : BackgroundService

Runs WorkflowEngine:MaxConcurrentSignalHandlers signal pump workers (at least one) until the host stops.

Parameters

WorkflowSignalPumpHostedService(WorkflowSignalPumpWorker, IOptions<WorkflowAqOptions>, IOptions<WorkflowEngineOptions>, ILogger<WorkflowSignalPumpHostedService>) constructor

public WorkflowSignalPumpHostedService(WorkflowSignalPumpWorker worker, IOptions<WorkflowAqOptions> aqOptions, IOptions<WorkflowEngineOptions> engineOptions, ILogger<WorkflowSignalPumpHostedService> logger)

Runs WorkflowEngine:MaxConcurrentSignalHandlers signal pump workers (at least one) until the host stops.

Parameters

StopAsync(CancellationToken) method

public override Task StopAsync(CancellationToken cancellationToken)

Stops the workers and waits for them up to WorkflowEngine:GracefulShutdownTimeoutSeconds.

Parameters

Returns

A task that completes when the workers stopped or the timeout passed.

WorkflowSignalPumpWorker class

public sealed class WorkflowSignalPumpWorker

Moves signals from the signal bus to the signal processor, one at a time.

Parameters

WorkflowSignalPumpWorker(IServiceScopeFactory, IOptions<WorkflowAqOptions>, WorkflowSignalPumpTelemetryService, WorkflowSignalDeliveryAttemptTracker, ILogger<WorkflowSignalPumpWorker>) constructor

public WorkflowSignalPumpWorker(IServiceScopeFactory serviceScopeFactory, IOptions<WorkflowAqOptions> aqOptions, WorkflowSignalPumpTelemetryService telemetryService, WorkflowSignalDeliveryAttemptTracker deliveryAttemptTracker, ILogger<WorkflowSignalPumpWorker> logger)

Moves signals from the signal bus to the signal processor, one at a time.

Parameters

RunOnceAsync(string, CancellationToken) method

public Task<bool> RunOnceAsync(string consumerName, CancellationToken cancellationToken)

Receives one signal and processes it: completed when processed, put back after a failure, and dead-lettered at the last delivery attempt.

Parameters

Returns

true when a signal was received; false after an empty poll.

StellaOps.Workflow.Engine.Hosting namespace

TypeKindDescription
WorkflowAqOptionsclassSignal pump and queue settings (WorkflowAq).
WorkflowEngineOptionsclassEngine-wide execution settings (WorkflowEngine).
WorkflowRuntimeOptionsclassThe runtime provider of new instances and the limits of map steps (WorkflowRuntime).

WorkflowAqOptions class

public sealed class WorkflowAqOptions

Signal pump and queue settings (WorkflowAq). The signal pump reads WorkflowAqOptions.ConsumerNameand WorkflowAqOptions.MaxDeliveryAttemptswhatever the signalling transport. The queue owner, the queue names and the blocking dequeue time are read only by a database queue transport that is not available in this release; the released signalling transports ignore them.

WorkflowAqOptions() constructor

public WorkflowAqOptions()

Creates an instance of WorkflowAqOptions.

SectionName constant

public const string SectionName = "WorkflowAq"

The configuration section the options bind from: WorkflowAq.

BlockingDequeueSeconds property

public int BlockingDequeueSeconds { get; set; }

How long one blocking dequeue waits for a message, in seconds. The default is 30. Not read by the released signalling transports.

ConsumerName property

public string ConsumerName { get; set; }

The consumer name of the signal pump. With several signal handlers, each worker adds its number, for example WORKFLOW_SERVICE-2. The default is WORKFLOW_SERVICE.

DeadLetterQueueName property

public string DeadLetterQueueName { get; set; }

The queue of undeliverable signals. The default is WF_DLQ_Q. Not read by the released signalling transports.

MaxDeliveryAttempts property

public int MaxDeliveryAttempts { get; set; }

How many times the signal pump delivers a signal before it moves the signal to the dead-letter queue; a value below 1 counts as 1. The default is 10.

QueueOwner property

public string QueueOwner { get; set; }

The database schema that owns the queues. Not read by the released signalling transports.

ScheduleQueueName property

public string ScheduleQueueName { get; set; }

The queue of scheduled signals. The default is WF_SCHEDULE_Q. Not read by the released signalling transports.

SignalQueueName property

public string SignalQueueName { get; set; }

The queue of workflow signals. The default is WF_SIGNAL_Q. Not read by the released signalling transports.

WorkflowEngineOptions class

public sealed class WorkflowEngineOptions

Engine-wide execution settings (WorkflowEngine).

WorkflowEngineOptions() constructor

public WorkflowEngineOptions()

Creates an instance of WorkflowEngineOptions.

SectionName constant

public const string SectionName = "WorkflowEngine"

The configuration section the options bind from: WorkflowEngine.

ExecutionTimeoutSeconds property

public int? ExecutionTimeoutSeconds { get; set; }

Maximum time in seconds for a single workflow execution operation (start, complete, resume). Null means no engine-wide timeout (recommended for long-running business processes). Default: null (disabled).

GracefulShutdownTimeoutSeconds property

public int GracefulShutdownTimeoutSeconds { get; set; }

How long the signal pump waits at shutdown for its workers to finish, in seconds; a value below 1 counts as 1. The default is 30.

MaxConcurrentSignalHandlers property

public int MaxConcurrentSignalHandlers { get; set; }

The number of signal pump workers that handle signals in parallel; a value below 1 counts as 1. The default is the processor count.

MaxInlineWaitSeconds property

public int MaxInlineWaitSeconds { get; set; }

Maximum seconds to block a task-complete/start-workflow response waiting for the signal pump to create the next user task. 0 (or less) = no wait (return immediately). Default: 10 seconds.

WorkflowRuntimeOptions class

public sealed class WorkflowRuntimeOptions

The runtime provider of new instances and the limits of map steps (WorkflowRuntime). The limits are checked when the host starts.

WorkflowRuntimeOptions() constructor

public WorkflowRuntimeOptions()

Creates an instance of WorkflowRuntimeOptions.

SectionName constant

public const string SectionName = "WorkflowRuntime"

The configuration section the options bind from: WorkflowRuntime.

DefaultProvider property

public string DefaultProvider { get; set; }

The runtime provider of new instances. Stella.Engine (the default) runs every step kind; Stella.InProcess runs no fork, map, external activity, timer, external signal or task deadline, and a host that selects it with such a workflow registered fails at start-up.

EnabledProviders property

public List<string> EnabledProviders { get; set; }

The runtime providers the host may use. When the list is not empty, the start-up check fails if it does not name WorkflowRuntimeOptions.DefaultProvider, and an instance of a provider it does not name is refused. Empty by default: every registered provider may run.

MaxMapConcurrency property

public int MaxMapConcurrency { get; set; }

The largest number of map items that run at the same time, from 1 to 64. The default is 8; the WORKFLOW_MAX_MAP_CONCURRENCY setting overrides it.

MaxMapItems property

public int MaxMapItems { get; set; }

The largest number of items one map step may declare, from 1 to 10000. The default is 512; the WORKFLOW_MAX_MAP_ITEMS setting overrides it.

StellaOps.Workflow.Engine.Licensing namespace

TypeKindDescription
IWorkflowLicenceReleaseContextinterfaceThe inputs of a licence evaluation that come from the release and the operator, not from the installation’s use: the running version’s first-publication date and the vendor trust roots.
InMemoryWorkflowFirstSeenLedgerclassThe first-seen ledger of a host without a workflow store.
WorkflowComponentLicenceOptionsclassConfiguration of the component licence reader, section StellaOps:ComponentLicence.
WorkflowDesignatedWorkflowQueryServiceclassReads the Designated Workflows from the first-seen ledger for the self-attestation count, with the licence status and the licence notice of the latest licence evaluation.
WorkflowLicenceAssessorclassEvaluates the engine’s licence status: records the code catalogue and the definition store in the first-seen ledger, counts the ledger (the technical count of recorded workflow names), reads the licence records offline and runs the shared component licence evaluator against the running version’s first-publication date.
WorkflowLicenceFileReaderclassReads the configured licence records offline, from the path (StellaOps:ComponentLicence:Path) or the licence key (StellaOps:ComponentLicence:Key), and verifies them against the release context’s trust roots.
WorkflowLicenceFilesrecordThe licence records one read loaded, with the reason when they could not be read.
WorkflowLicenceHealthCheckclassThe licence entry of the health output.
WorkflowLicenceMetricsclassThe licence gauge: the count of recorded workflow names of the latest evaluation, tagged with its status name; no measurement while the count is unavailable.
WorkflowLicenceMonitorclassEvaluates the licence status once the host has started (after its startup migrations) and then once per hour, so the warning log appears at startup and hourly while the status warrants it.
WorkflowLicenceNoticeViewclassThe licence notice in the engine’s health and API output: the fields and case names the Router reports in its licence health output, so both components show it alike.
WorkflowLicenceReleaseContextclassThe release context of the running engine: the stamp of the engine assembly and the roots of ComponentLicenceTrustRoots.FromEnvironment(IEs256Verifier) (the embedded published root, or the set STELLAOPS_VENDOR_TRUST_ROOTS names).
WorkflowLicenceSnapshotrecordOne licence evaluation of the running engine, as the health detail, the gauge and the notice report it.
WorkflowLicenceStateclassThe latest licence evaluation of this process; read by the health detail and the gauge.

IWorkflowLicenceReleaseContext interface

public interface IWorkflowLicenceReleaseContext

The inputs of a licence evaluation that come from the release and the operator, not from the installation’s use: the running version’s first-publication date and the vendor trust roots.

PublishedAt property

DateOnly? PublishedAt { get; }

The StellaOps.Component.PublishedAt stamp of the engine’s source release; a build or adaptation of a released version keeps it, and its own build date is never used. null in a development build.

ResolveTrustRoots() method

ComponentLicenceTrustRoots ResolveTrustRoots()

The vendor-entitlement roots that licence file signatures are checked against, resolved per evaluation.

InMemoryWorkflowFirstSeenLedger class

public sealed class InMemoryWorkflowFirstSeenLedger : IWorkflowFirstSeenLedger

The first-seen ledger of a host without a workflow store. It lives in process memory, so it counts what this process has seen (in practice the code catalogue: such a host has no definition store to import into) and starts empty on every restart. This is the documented limitation of hosts without a workflow store; the PostgreSQL and MongoDB stores replace this ledger with a durable one. Its lock serialises recording within the process. Recording never refuses a workflow.

InMemoryWorkflowFirstSeenLedger() constructor

public InMemoryWorkflowFirstSeenLedger()

Creates an instance of InMemoryWorkflowFirstSeenLedger.

IsDurable property

public bool IsDurable { get; }

true when the record survives a restart (the PostgreSQL and MongoDB ledgers); false for the process-memory ledger of a host without a workflow store, which counts only what this process has seen.

CountAsync(CancellationToken) method

public Task<int> CountAsync(CancellationToken cancellationToken = default)

The number of distinct workflows ever recorded.

ListAsync(CancellationToken) method

public Task<IReadOnlyList<WorkflowFirstSeenRecord>> ListAsync(CancellationToken cancellationToken = default)

Every workflow ever recorded, one entry per workflow with its first sighting, ordered by WorkflowFirstSeenIdentity.Key(string)(ordinal). The number of entries is the count IWorkflowFirstSeenLedger.CountAsync(CancellationToken)returns for the same ledger state. Reads only; records nothing.

RecordAsync(IReadOnlyCollection<string>, string, DateTimeOffset, CancellationToken) method

public Task RecordAsync(IReadOnlyCollection<string> workflowNames, string source, DateTimeOffset seenOnUtc, CancellationToken cancellationToken = default)

Records the workflows in workflowNames that the ledger has not seen, with source (WorkflowFirstSeenSources) and seenOnUtc. A workflow already recorded is left as it is. Every recording is serialised against every other recording of the same ledger, so engines that share it record each name once.

RecordStoredDefinitionsAsync(CancellationToken) method

public Task RecordStoredDefinitionsAsync(CancellationToken cancellationToken = default)

Records every workflow the definition store holds that the ledger has not seen, active or not, with the creation time of its first stored version. It reconciles imports whose ledger write was interrupted and definitions stored before the ledger existed. A ledger without a durable definition store records nothing here.

WorkflowComponentLicenceOptions class

public sealed class WorkflowComponentLicenceOptions

Configuration of the component licence reader, section StellaOps:ComponentLicence. Every value is optional: without a licence record the engine reports its status from the count alone, and an invalid value never stops the host (the record is then not loaded, with the reason as a detail).

WorkflowComponentLicenceOptions() constructor

public WorkflowComponentLicenceOptions()

Creates an instance of WorkflowComponentLicenceOptions.

SectionName constant

public const string SectionName = "StellaOps:ComponentLicence"

The configuration section the options bind from: StellaOps:ComponentLicence.

InstallationId property

public string? InstallationId { get; set; }

The Installation identifier the licence files name: a lowercase UUID.

Key property

public string? Key { get; set; }

The licence key: the standard base64 of a licence file as one line, the same signed record as the file (an encoding, not a protection). Configure the path or the key; with both, neither is read and the details show conflicting_sources.

Path property

public string? Path { get; set; }

A licence file, or a directory whose *.dsse.json files are read. Local path only.

WorkflowDesignatedWorkflowQueryService class

public sealed class WorkflowDesignatedWorkflowQueryService

Reads the Designated Workflows from the first-seen ledger for the self-attestation count, with the licence status and the licence notice of the latest licence evaluation. It only reads: it records nothing, so the list is the ledger as the latest recording left it (the licence evaluation at startup and every hour, and each definition import). Nothing is sent anywhere.

WorkflowDesignatedWorkflowQueryService(IWorkflowFirstSeenLedger, WorkflowLicenceState) constructor

public WorkflowDesignatedWorkflowQueryService(IWorkflowFirstSeenLedger ledger, WorkflowLicenceState state)

Reads the Designated Workflows from the first-seen ledger for the self-attestation count, with the licence status and the licence notice of the latest licence evaluation. It only reads: it records nothing, so the list is the ledger as the latest recording left it (the licence evaluation at startup and every hour, and each definition import). Nothing is sent anywhere.

GetAsync(CancellationToken) method

public Task<WorkflowDesignatedWorkflowsGetResponse> GetAsync(CancellationToken cancellationToken = default)

Returns the designated workflows of the first-seen ledger, with the licence status and the notice of the latest licence evaluation.

Parameters

Returns

The designated workflows.

WorkflowLicenceAssessor class

public sealed class WorkflowLicenceAssessor

Evaluates the engine’s licence status: records the code catalogue and the definition store in the first-seen ledger, counts the ledger (the technical count of recorded workflow names), reads the licence records offline and runs the shared component licence evaluator against the running version’s first-publication date. Warnings only: it refuses, restricts and stops nothing, never fails readiness or liveness, makes no network call and sends nothing anywhere. A ledger that cannot be read gives the count-unavailable status, and a record that cannot be read a detail; neither is thrown.

WorkflowLicenceAssessor(IServiceScopeFactory, IWorkflowRegistrationCatalog, WorkflowLicenceFileReader, WorkflowLicenceState, TimeProvider, ILogger<WorkflowLicenceAssessor>) constructor

public WorkflowLicenceAssessor(IServiceScopeFactory scopeFactory, IWorkflowRegistrationCatalog catalog, WorkflowLicenceFileReader licenceFiles, WorkflowLicenceState state, TimeProvider timeProvider, ILogger<WorkflowLicenceAssessor> logger)

Evaluates the engine’s licence status: records the code catalogue and the definition store in the first-seen ledger, counts the ledger (the technical count of recorded workflow names), reads the licence records offline and runs the shared component licence evaluator against the running version’s first-publication date. Warnings only: it refuses, restricts and stops nothing, never fails readiness or liveness, makes no network call and sends nothing anywhere. A ledger that cannot be read gives the count-unavailable status, and a record that cannot be read a detail; neither is thrown.

EvaluateAsync(bool, CancellationToken) method

public Task<WorkflowLicenceSnapshot> EvaluateAsync(bool startup, CancellationToken cancellationToken = default)

Runs one evaluation and publishes it to WorkflowLicenceState. The licence notice is logged at information level on every evaluation (startup and hourly). The warning log is written on every evaluation whose status warns (ComponentLicenceAssessment.Warns: every status but within-free-limit and record-matches); those two are logged at information level at startup and when the status changes.

WorkflowLicenceFileReader class

public sealed class WorkflowLicenceFileReader

Reads the configured licence records offline, from the path (StellaOps:ComponentLicence:Path) or the licence key (StellaOps:ComponentLicence:Key), and verifies them against the release context’s trust roots. With both set neither is read (conflicting_sources). The licence evaluation reads them again at every pass. A failure to read is reported, never thrown.

WorkflowLicenceFileReader(IOptionsMonitor<WorkflowComponentLicenceOptions>, IWorkflowLicenceReleaseContext, ILogger<WorkflowLicenceFileReader>) constructor

public WorkflowLicenceFileReader(IOptionsMonitor<WorkflowComponentLicenceOptions> options, IWorkflowLicenceReleaseContext releaseContext, ILogger<WorkflowLicenceFileReader> logger)

Reads the configured licence records offline, from the path (StellaOps:ComponentLicence:Path) or the licence key (StellaOps:ComponentLicence:Key), and verifies them against the release context’s trust roots. With both set neither is read (conflicting_sources). The licence evaluation reads them again at every pass. A failure to read is reported, never thrown.

PublishedAt property

public DateOnly? PublishedAt { get; }

The running version’s first-publication date; null in a development build.

Read() method

public WorkflowLicenceFiles Read()

Reads and verifies the configured licence files for the Workflow component. No path and no key reads nothing; a read that fails is logged and reported as an issue, not raised.

Returns

The verified licence sources, any issue, and whether an installation id is configured.

WorkflowLicenceFiles record

public sealed record WorkflowLicenceFiles

The licence records one read loaded, with the reason when they could not be read.

WorkflowLicenceFiles() constructor

public WorkflowLicenceFiles()

Creates an instance of WorkflowLicenceFiles.

InstallationIdConfigured property

public required bool InstallationIdConfigured { get; init; }

Whether an Installation identifier is configured.

Issue property

public string? Issue { get; init; }

Set when the files could not be read; then WorkflowLicenceFiles.Sourcesis empty.

Sources property

public required IReadOnlyList<ComponentLicenceSource> Sources { get; init; }

Every record read (each file, or the licence key), loaded or not, with its verification.

WorkflowLicenceHealthCheck class

public sealed class WorkflowLicenceHealthCheck : IHealthCheck

The licence entry of the health output. Informational only: it always reports HealthStatus.Healthy, so it never fails readiness or liveness, never removes the engine from service and never triggers a restart; the licence status and the licence notice are in its data.

WorkflowLicenceHealthCheck(WorkflowLicenceState) constructor

public WorkflowLicenceHealthCheck(WorkflowLicenceState state)

The licence entry of the health output. Informational only: it always reports HealthStatus.Healthy, so it never fails readiness or liveness, never removes the engine from service and never triggers a restart; the licence status and the licence notice are in its data.

Name constant

public const string Name = "licence"

The health check name.

CheckHealthAsync(HealthCheckContext, CancellationToken) method

public Task<HealthCheckResult> CheckHealthAsync(HealthCheckContext context, CancellationToken cancellationToken = default)

See IHealthCheck.CheckHealthAsync(HealthCheckContext, CancellationToken).

WorkflowLicenceMetrics class

public sealed class WorkflowLicenceMetrics : IDisposable

The licence gauge: the count of recorded workflow names of the latest evaluation, tagged with its status name; no measurement while the count is unavailable. It is exported only through the host’s own metrics pipeline; nothing is sent to the vendor.

WorkflowLicenceMetrics(WorkflowLicenceState, IMeterFactory) constructor

public WorkflowLicenceMetrics(WorkflowLicenceState state, IMeterFactory? meterFactory = null)

Creates the gauge of the designated workflows, tagged with the licence status.

Parameters

GaugeName constant

public const string GaugeName = "stellaops.workflow.licence.designated_workflows"

The gauge name.

MeterName constant

public const string MeterName = "StellaOps.Workflow.Licence"

The meter name.

StatusTag constant

public const string StatusTag = "licence.status"

The status tag of the gauge.

Meter property

public Meter Meter { get; }

The meter of this instance.

Dispose() method

public void Dispose()

Disposes the meter when the metrics created it.

WorkflowLicenceMonitor class

public sealed class WorkflowLicenceMonitor : BackgroundService

Evaluates the licence status once the host has started (after its startup migrations) and then once per hour, so the warning log appears at startup and hourly while the status warrants it. It never stops, delays or degrades the engine: a failed evaluation is logged and retried at the next interval.

WorkflowLicenceMonitor(WorkflowLicenceAssessor, WorkflowLicenceMetrics, TimeProvider, ILogger<WorkflowLicenceMonitor>, IHostApplicationLifetime) constructor

public WorkflowLicenceMonitor(WorkflowLicenceAssessor assessor, WorkflowLicenceMetrics metrics, TimeProvider timeProvider, ILogger<WorkflowLicenceMonitor> logger, IHostApplicationLifetime? lifetime = null)

Evaluates the licence status once the host has started (after its startup migrations) and then once per hour, so the warning log appears at startup and hourly while the status warrants it. It never stops, delays or degrades the engine: a failed evaluation is logged and retried at the next interval.

EvaluationInterval field

public static readonly TimeSpan EvaluationInterval

The interval between evaluations.

WorkflowLicenceNoticeView class

public static class WorkflowLicenceNoticeView

The licence notice in the engine’s health and API output: the fields and case names the Router reports in its licence health output, so both components show it alike.

From(ComponentLicenceNotice) method

public static WorkflowLicenceNotice From(ComponentLicenceNotice notice)

Converts a licence notice for the API: the notice text and its fields.

Parameters

Returns

The notice view.

HealthData(WorkflowLicenceNotice) method

public static IReadOnlyDictionary<string, object?> HealthData(WorkflowLicenceNotice notice)

The notice as the nested notice object of the licence health data.

WorkflowLicenceReleaseContext class

public sealed class WorkflowLicenceReleaseContext : IWorkflowLicenceReleaseContext

The release context of the running engine: the stamp of the engine assembly and the roots of ComponentLicenceTrustRoots.FromEnvironment(IEs256Verifier) (the embedded published root, or the set STELLAOPS_VENDOR_TRUST_ROOTS names). Local reads only.

WorkflowLicenceReleaseContext() constructor

public WorkflowLicenceReleaseContext()

Creates an instance of WorkflowLicenceReleaseContext.

PublishedAt property

public DateOnly? PublishedAt { get; }

The StellaOps.Component.PublishedAt stamp of the engine’s source release; a build or adaptation of a released version keeps it, and its own build date is never used. null in a development build.

ResolveTrustRoots() method

public ComponentLicenceTrustRoots ResolveTrustRoots()

The vendor-entitlement roots that licence file signatures are checked against, resolved per evaluation.

WorkflowLicenceSnapshot record

public sealed record WorkflowLicenceSnapshot

One licence evaluation of the running engine, as the health detail, the gauge and the notice report it.

WorkflowLicenceSnapshot() constructor

public WorkflowLicenceSnapshot()

Creates an instance of WorkflowLicenceSnapshot.

Assessment property

public required ComponentLicenceAssessment Assessment { get; init; }

The component licence evaluator’s result: status, message, count and details.

InstallationIdConfigured property

public required bool InstallationIdConfigured { get; init; }

Whether an Installation identifier is configured.

LedgerDurable property

public required bool LedgerDurable { get; init; }

true when the count comes from a durable ledger (PostgreSQL or MongoDB).

LedgerIssue property

public string? LedgerIssue { get; init; }

Set when the ledger could not be read and the count fell back to the code catalogue.

LicenceFilesLoaded property

public required int LicenceFilesLoaded { get; init; }

Licence files read and loaded.

LicenceFilesNotLoaded property

public required int LicenceFilesNotLoaded { get; init; }

Licence files read and not loaded (the reasons are in the assessment details).

Notice property

public required ComponentLicenceNotice Notice { get; init; }

The licence notice of WorkflowLicenceSnapshot.Assessment.

NoticeHeadline property

public string NoticeHeadline { get; }

The short notice text: “Licensed to” the licensee, or the message of the notice case. Pass it to the SVG renderer, which writes it into every diagram.

Sequence property

public required long Sequence { get; init; }

The evaluation number in this process, from 1.

Warns property

public bool Warns { get; }

true while the status is one the monitor logs as a warning at startup and hourly: ComponentLicenceAssessment.Warns, every status but within-free-limit and record-matches. A warning refuses nothing.

WorkflowLicenceState class

public sealed class WorkflowLicenceState

The latest licence evaluation of this process; read by the health detail and the gauge.

WorkflowLicenceState() constructor

public WorkflowLicenceState()

Creates an instance of WorkflowLicenceState.

Current property

public WorkflowLicenceSnapshot? Current { get; }

The latest evaluation; null before the first one.

StellaOps.Workflow.Engine.Maps namespace

TypeKindDescription
IWorkflowMapItemExecutionHandlerinterfaceRuns the body of a map item.
WorkflowMapAdvanceDecisionrecordWhether a completed step belongs to a map item, and the signal that resumes it.
WorkflowMapCompletedSignalDispatcherclassMaterializes a durable map when the runtime reaches it (MapCompleted pending signal) and publishes the completion signal the coordinator returns once every item has finished.
WorkflowMapCoordinatorclassOwns normalized map materialization, bounded item dispatch and deterministic fan-in.
WorkflowMapCreateRequestrecordA map execution to create with its items.
WorkflowMapExecutionPlanrecordThe frozen plan of a map: its workflow, bounds, policies and body.
WorkflowMapItemExecutionDecisionrecordThe next step of a map item: an activity, a nested map, or its end.
WorkflowMapItemExecutionRequestrecordA map item to run or resume.
WorkflowMapItemExecutionStaterecordThe progress of a map item.
WorkflowMapItemLeaserecordA claimed map item.
WorkflowMapItemSeedrecordAn item to create in a map.
WorkflowMapMaterializationItemPlanrecordAn item of a map plan.
WorkflowMapMaterializationPlanrecordA map to create: its plan and items.
WorkflowMapRuntimeExceptionclassRaised when a map breaks a runtime rule, such as MAP_BOUND_INVALID or MAP_ITEM_LIMIT_EXCEEDED.
WorkflowMapRuntimeServiceclassRuns map executions: creates a map and its items, leases ready items to workers within the concurrency limits, and records item progress and outcomes.
WorkflowRetryClassifierclassComputes the delay before a retry from a retry policy: fixed, exponential (doubling with each attempt) or the provider’s hint up to its maximum; capped at the maximum delay and spread by a deterministic jitter.

IWorkflowMapItemExecutionHandler interface

public interface IWorkflowMapItemExecutionHandler

Runs the body of a map item.

ExecuteMapItemAsync(WorkflowMapItemExecutionRequest, CancellationToken) method

Task<WorkflowMapItemExecutionDecision> ExecuteMapItemAsync(WorkflowMapItemExecutionRequest request, CancellationToken cancellationToken = default)

Runs the item until it waits or ends.

Parameters

Returns

What happens next.

WorkflowMapAdvanceDecision record

public sealed record WorkflowMapAdvanceDecision

Whether a completed step belongs to a map item, and the signal that resumes it.

Parameters

WorkflowMapAdvanceDecision(bool, WorkflowSignalEnvelope) constructor

public WorkflowMapAdvanceDecision(bool IsMapItem, WorkflowSignalEnvelope? ResumeSignal)

Whether a completed step belongs to a map item, and the signal that resumes it.

Parameters

IsMapItem property

public bool IsMapItem { get; init; }

Whether the step runs for a map item.

ResumeSignal property

public WorkflowSignalEnvelope? ResumeSignal { get; init; }

The signal that resumes the item, when there is one.

WorkflowMapCompletedSignalDispatcher class

public sealed class WorkflowMapCompletedSignalDispatcher : IWorkflowPendingSignalDispatcher

Materializes a durable map when the runtime reaches it (MapCompleted pending signal) and publishes the completion signal the coordinator returns once every item has finished.

WorkflowMapCompletedSignalDispatcher(WorkflowMapCoordinator, IWorkflowSignalBus, IWorkflowRuntimeStateStore) constructor

public WorkflowMapCompletedSignalDispatcher(WorkflowMapCoordinator coordinator, IWorkflowSignalBus signalBus, IWorkflowRuntimeStateStore runtimeStateStore)

Materializes a durable map when the runtime reaches it (MapCompleted pending signal) and publishes the completion signal the coordinator returns once every item has finished.

CanDispatch(WorkflowPendingSignalPlan) method

public bool CanDispatch(WorkflowPendingSignalPlan pendingSignal)

Whether this dispatcher sends a pending signal.

Parameters

Returns

Whether it does.

DispatchAsync(string, WorkflowPendingSignalPlan, WorkflowRuntimeStateRecord, CancellationToken) method

public Task<long> DispatchAsync(string workflowInstanceId, WorkflowPendingSignalPlan pendingSignal, WorkflowRuntimeStateRecord runtimeState, CancellationToken cancellationToken = default)

Dispatches the signal and returns the execution version the next signal must expect.

WorkflowMapCoordinator class

public sealed class WorkflowMapCoordinator

Owns normalized map materialization, bounded item dispatch and deterministic fan-in. All mutations run in one Workflow mutation scope (the caller’s, when it has one) so a map item can never be visible without its durable activity dispatch, or terminal without the fan-in state that follows it.

WorkflowMapCoordinator(IWorkflowMapStore, IWorkflowExternalActivityStore, IWorkflowMutationCoordinator, WorkflowMapRuntimeService, WorkflowExternalActivityDispatchService, IWorkflowRuntimeDefinitionStore, IWorkflowRuntimeExecutionHandlerFactory) constructor

public WorkflowMapCoordinator(IWorkflowMapStore mapStore, IWorkflowExternalActivityStore activityStore, IWorkflowMutationCoordinator mutationCoordinator, WorkflowMapRuntimeService mapRuntimeService, WorkflowExternalActivityDispatchService activityDispatchService, IWorkflowRuntimeDefinitionStore runtimeDefinitionStore, IWorkflowRuntimeExecutionHandlerFactory executionHandlerFactory)

Owns normalized map materialization, bounded item dispatch and deterministic fan-in. All mutations run in one Workflow mutation scope (the caller’s, when it has one) so a map item can never be visible without its durable activity dispatch, or terminal without the fan-in state that follows it.

MaterializeAndDispatchAsync(string, WorkflowPendingSignalPlan, WorkflowRuntimeStateRecord, CancellationToken) method

public Task<WorkflowSignalEnvelope?> MaterializeAndDispatchAsync(string workflowExecutionId, WorkflowPendingSignalPlan pendingSignal, WorkflowRuntimeStateRecord runtimeState, CancellationToken cancellationToken = default)

Creates the map a map step plans, in one change scope, and dispatches the items the capacity allows.

Parameters

Returns

The signal that completes the map step when the map is already complete; null while items run.

Exceptions

TryAdvanceCompletedStepAsync(string, string, IReadOnlyDictionary<string, JsonElement>, CancellationToken) method

public Task<WorkflowMapAdvanceDecision> TryAdvanceCompletedStepAsync(string workflowExecutionId, string stepExecutionId, IReadOnlyDictionary<string, JsonElement> completionPayload, CancellationToken cancellationToken = default)

Advances the map item a completed step runs for, in one change scope: runs the item on, records its outcome, dispatches more items and builds the signal that resumes the item or completes the map.

Parameters

Returns

Whether the step runs for a map item, and the resume signal.

Exceptions

WorkflowMapCreateRequest record

public sealed record WorkflowMapCreateRequest

A map execution to create with its items.

Parameters

WorkflowMapCreateRequest(string, string, string, string, string, string, int?, int, int, int, string, string, string, DateTime?, IReadOnlyCollection<WorkflowMapItemSeed>) constructor

public WorkflowMapCreateRequest(string MapExecutionId, string WorkflowExecutionId, string ScopeExecutionId, string StepExecutionId, string FanInPolicy, string FailurePolicy, int? MinimumSucceeded, int MaxConcurrency, int MaxItems, int MaxAggregateStateBytes, string? GlobalActivityClass, string ExecutionPlanSha256, string ExecutionPlanJson, DateTime? AbsoluteDeadlineAtUtc, IReadOnlyCollection<WorkflowMapItemSeed> Items)

A map execution to create with its items.

Parameters

AbsoluteDeadlineAtUtc property

public DateTime? AbsoluteDeadlineAtUtc { get; init; }

The deadline of the map, in UTC.

ExecutionPlanJson property

public string ExecutionPlanJson { get; init; }

The map plan, as JSON.

ExecutionPlanSha256 property

public string ExecutionPlanSha256 { get; init; }

The SHA-256 of the map plan.

FailurePolicy property

public string FailurePolicy { get; init; }

The failure policy.

FanInPolicy property

public string FanInPolicy { get; init; }

The fan-in policy.

GlobalActivityClass property

public string? GlobalActivityClass { get; init; }

The class of activities whose concurrency is limited across all maps.

Items property

public IReadOnlyCollection<WorkflowMapItemSeed> Items { get; init; }

The items.

MapExecutionId property

public string MapExecutionId { get; init; }

The map execution.

MaxAggregateStateBytes property

public int MaxAggregateStateBytes { get; init; }

The size limit of the collected results, in bytes.

MaxConcurrency property

public int MaxConcurrency { get; init; }

The items in flight at once.

MaxItems property

public int MaxItems { get; init; }

The items allowed.

MinimumSucceeded property

public int? MinimumSucceeded { get; init; }

The items that must succeed under MIN_SUCCEEDED.

ScopeExecutionId property

public string ScopeExecutionId { get; init; }

The scope of the map.

StepExecutionId property

public string StepExecutionId { get; init; }

The map step.

WorkflowExecutionId property

public string WorkflowExecutionId { get; init; }

The execution.

WorkflowMapExecutionPlan record

public sealed record WorkflowMapExecutionPlan

The frozen plan of a map: its workflow, bounds, policies and body.

WorkflowMapExecutionPlan() constructor

public WorkflowMapExecutionPlan()

Creates an instance of WorkflowMapExecutionPlan.

AbsoluteDeadlineAtUtc property

public DateTime? AbsoluteDeadlineAtUtc { get; init; }

The deadline of the map, in UTC.

BodyResumePointer property

public required JsonElement BodyResumePointer { get; init; }

Where the body starts.

FailurePolicy property

public required string FailurePolicy { get; init; }

The failure policy.

FanInPolicy property

public required string FanInPolicy { get; init; }

The fan-in policy.

GlobalActivityClass property

public string? GlobalActivityClass { get; init; }

The class of activities whose concurrency is limited across all maps.

ItemResultExpression property

public required WorkflowExpressionDefinition ItemResultExpression { get; init; }

The result of an item, evaluated after its body.

ItemStateKey property

public required string ItemStateKey { get; init; }

The state key that holds the current item.

MapStepExecutionId property

public required string MapStepExecutionId { get; init; }

The map step.

MaxAggregateStateBytes property

public required int MaxAggregateStateBytes { get; init; }

The size limit of the collected results, in bytes.

MaxConcurrency property

public required int MaxConcurrency { get; init; }

The items in flight at once.

MaxItems property

public required int MaxItems { get; init; }

The items allowed.

MinimumSucceeded property

public int? MinimumSucceeded { get; init; }

The items that must succeed under MIN_SUCCEEDED.

RetryPolicy property

public required WorkflowRetryPolicyDeclaration RetryPolicy { get; init; }

The retry policy of an item.

StepName property

public required string StepName { get; init; }

The step name.

WorkflowName property

public required string WorkflowName { get; init; }

The workflow name.

WorkflowVersion property

public required string WorkflowVersion { get; init; }

The workflow version.

WorkflowMapItemExecutionDecision record

public sealed record WorkflowMapItemExecutionDecision

The next step of a map item: an activity, a nested map, or its end.

WorkflowMapItemExecutionDecision() constructor

public WorkflowMapItemExecutionDecision()

Creates an instance of WorkflowMapItemExecutionDecision.

ExecutionState property

public required WorkflowMapItemExecutionState ExecutionState { get; init; }

The progress after the step.

IsTerminal property

public bool IsTerminal { get; }

Whether the item ended.

PendingActivity property

public WorkflowPendingSignalPlan? PendingActivity { get; init; }

An activity to dispatch.

PendingMap property

public WorkflowPendingSignalPlan? PendingMap { get; init; }

A nested map to create.

SafeResultDescriptor property

public JsonElement? SafeResultDescriptor { get; init; }

The safe result descriptor.

TerminalOutcome property

public string? TerminalOutcome { get; init; }

The final outcome, when the item ended.

WorkflowMapItemExecutionRequest record

public sealed record WorkflowMapItemExecutionRequest

A map item to run or resume.

WorkflowMapItemExecutionRequest() constructor

public WorkflowMapItemExecutionRequest()

Creates an instance of WorkflowMapItemExecutionRequest.

BusinessReference property

public WorkflowBusinessReference? BusinessReference { get; init; }

The business reference.

CompletionPayload property

public IReadOnlyDictionary<string, JsonElement>? CompletionPayload { get; init; }

The payload of the completion that resumes the item.

CompletionSignalType property

public string? CompletionSignalType { get; init; }

The type of the signal that resumes the item.

ExecutionPlan property

public required WorkflowMapExecutionPlan ExecutionPlan { get; init; }

The map plan.

ItemDescriptor property

public required JsonElement ItemDescriptor { get; init; }

The item descriptor.

PriorExecutionState property

public WorkflowMapItemExecutionState? PriorExecutionState { get; init; }

The progress so far, when the item resumes.

RootWorkflowState property

public required IReadOnlyDictionary<string, JsonElement> RootWorkflowState { get; init; }

The state of the execution.

WorkflowMapItemExecutionState record

public sealed record WorkflowMapItemExecutionState

The progress of a map item.

WorkflowMapItemExecutionState() constructor

public WorkflowMapItemExecutionState()

Creates an instance of WorkflowMapItemExecutionState.

ResumeState property

public IReadOnlyDictionary<string, JsonElement> ResumeState { get; init; }

Where the body resumes.

WorkflowState property

public IReadOnlyDictionary<string, JsonElement> WorkflowState { get; init; }

The item state.

WorkflowMapItemLease record

public sealed record WorkflowMapItemLease

A claimed map item.

Parameters

WorkflowMapItemLease(string, string, int, long, string, string) constructor

public WorkflowMapItemLease(string MapItemId, string ItemKey, int Ordinal, long ClaimFence, string DescriptorSha256, string DescriptorJson)

A claimed map item.

Parameters

ClaimFence property

public long ClaimFence { get; init; }

The claim fence.

DescriptorJson property

public string DescriptorJson { get; init; }

The item descriptor, as JSON.

DescriptorSha256 property

public string DescriptorSha256 { get; init; }

The SHA-256 of the descriptor.

ItemKey property

public string ItemKey { get; init; }

The item key.

MapItemId property

public string MapItemId { get; init; }

The map item.

Ordinal property

public int Ordinal { get; init; }

The position of the item.

WorkflowMapItemSeed record

public sealed record WorkflowMapItemSeed

An item to create in a map.

Parameters

WorkflowMapItemSeed(string, string, string) constructor

public WorkflowMapItemSeed(string ItemKey, string DescriptorSha256, string DescriptorJson)

An item to create in a map.

Parameters

DescriptorJson property

public string DescriptorJson { get; init; }

The item descriptor, as JSON.

DescriptorSha256 property

public string DescriptorSha256 { get; init; }

The SHA-256 of the descriptor.

ItemKey property

public string ItemKey { get; init; }

The item key.

WorkflowMapMaterializationItemPlan record

public sealed record WorkflowMapMaterializationItemPlan

An item of a map plan.

WorkflowMapMaterializationItemPlan() constructor

public WorkflowMapMaterializationItemPlan()

Creates an instance of WorkflowMapMaterializationItemPlan.

DescriptorJson property

public required string DescriptorJson { get; init; }

The item descriptor, as JSON.

DescriptorSha256 property

public required string DescriptorSha256 { get; init; }

The SHA-256 of the descriptor.

ItemKey property

public required string ItemKey { get; init; }

The item key.

Ordinal property

public required int Ordinal { get; init; }

The position of the item.

WorkflowMapMaterializationPlan record

public sealed record WorkflowMapMaterializationPlan

A map to create: its plan and items.

WorkflowMapMaterializationPlan() constructor

public WorkflowMapMaterializationPlan()

Creates an instance of WorkflowMapMaterializationPlan.

ExecutionPlan property

public required WorkflowMapExecutionPlan ExecutionPlan { get; init; }

The plan.

Items property

public IReadOnlyCollection<WorkflowMapMaterializationItemPlan> Items { get; init; }

The items.

MapExecutionId property

public required string MapExecutionId { get; init; }

The map execution.

WorkflowMapRuntimeException class

public sealed class WorkflowMapRuntimeException : Exception

Raised when a map breaks a runtime rule, such as MAP_BOUND_INVALID or MAP_ITEM_LIMIT_EXCEEDED.

Parameters

WorkflowMapRuntimeException(string) constructor

public WorkflowMapRuntimeException(string code)

Raised when a map breaks a runtime rule, such as MAP_BOUND_INVALID or MAP_ITEM_LIMIT_EXCEEDED.

Parameters

Code property

public string Code { get; }

The code.

WorkflowMapRuntimeService class

public sealed class WorkflowMapRuntimeService

Runs map executions: creates a map and its items, leases ready items to workers within the concurrency limits, and records item progress and outcomes.

WorkflowMapRuntimeService(IWorkflowMapStore, TimeProvider) constructor

public WorkflowMapRuntimeService(IWorkflowMapStore store, TimeProvider timeProvider)

Creates the service with the default runtime options.

Parameters

WorkflowMapRuntimeService(IWorkflowMapStore, TimeProvider, IOptions<WorkflowRuntimeOptions>) constructor

public WorkflowMapRuntimeService(IWorkflowMapStore store, TimeProvider timeProvider, IOptions<WorkflowRuntimeOptions> options)

Creates the service.

Parameters

ClaimReadyAsync(string, string, int, TimeSpan, CancellationToken) method

public Task<IReadOnlyCollection<WorkflowMapItemLease>> ClaimReadyAsync(string mapExecutionId, string claimOwner, int requestedCount, TimeSpan leaseDuration, CancellationToken cancellationToken = default)

Leases ready items to a worker, up to the free capacity: the smaller of the map’s MaxConcurrency and the runtime’s MaxMapConcurrency, less the active claims, and for a global activity class also the class limit less its active claims. A map that is not ready or running leases nothing.

Parameters

Returns

The leased items.

Exceptions

CompleteItemAsync(string, string, long, string, string, CancellationToken) method

public Task CompleteItemAsync(string mapItemId, string claimOwner, long claimFence, string outcome, string? safeResultDescriptorJson, CancellationToken cancellationToken = default)

Records the outcome of a leased item and recalculates the map.

Parameters

Returns

A task that completes when the outcome is recorded.

Exceptions

CreateAsync(WorkflowMapCreateRequest, CancellationToken) method

public Task<WorkflowMapExecutionRecord> CreateAsync(WorkflowMapCreateRequest request, CancellationToken cancellationToken = default)

Creates a map and its items, each READY, with the id {map}:{ordinal}. A map without items completes at once, or fails under MIN_SUCCEEDED. A map already created under its id is returned when the request is the same.

Parameters

Returns

The map.

Exceptions

UpdateItemProgressAsync(string, string, long, string, string, CancellationToken) method

public Task UpdateItemProgressAsync(string mapItemId, string claimOwner, long claimFence, string activeStepExecutionId, string executionStateJson, CancellationToken cancellationToken = default)

Records the running step and the execution state of a leased item.

Parameters

Returns

A task that completes when the progress is recorded.

Exceptions

WorkflowRetryClassifier class

public static class WorkflowRetryClassifier

Computes the delay before a retry from a retry policy: fixed, exponential (doubling with each attempt) or the provider’s hint up to its maximum; capped at the maximum delay and spread by a deterministic jitter.

GetDelay(WorkflowRetryPolicyDeclaration, int, string, TimeSpan?, int) method

public static TimeSpan? GetDelay(WorkflowRetryPolicyDeclaration policy, int completedSemanticAttempts, string failureCategory, TimeSpan? providerHint, int deterministicJitterSeed)

The delay before the next retry, or null when no retry is left or the category is not retryable.

Parameters

Returns

The delay, or null.

StellaOps.Workflow.Engine.Observability namespace

TypeKindDescription
WorkflowMetricCatalogclassThe metric names reserved for the Workflow engine.
WorkflowMetricLabelPolicyclassThe metric labels the engine allows, so that no metric carries an unbounded label.
WorkflowObservabilityclassThe engine’s meter and activity source (StellaOps.Workflow): console requests and their duration, and terminal transitions.

WorkflowMetricCatalog class

public static class WorkflowMetricCatalog

The metric names reserved for the Workflow engine. The engine emits workflow.console.requests, workflow.console.duration.ms and workflow.execution.terminal.

Names field

public static readonly IReadOnlyCollection<string> Names

The names.

WorkflowMetricLabelPolicy class

public static class WorkflowMetricLabelPolicy

The metric labels the engine allows, so that no metric carries an unbounded label.

Validate(IEnumerable<KeyValuePair<string, object>>) method

public static void Validate(IEnumerable<KeyValuePair<string, object?>> labels)

Checks that every label is allowed.

Parameters

Exceptions

WorkflowObservability class

public sealed class WorkflowObservability : IDisposable

The engine’s meter and activity source (StellaOps.Workflow): console requests and their duration, and terminal transitions.

WorkflowObservability() constructor

public WorkflowObservability()

Creates an instance of WorkflowObservability.

ActivitySource field

public static readonly ActivitySource ActivitySource

The activity source.

InstrumentationName constant

public const string InstrumentationName = "StellaOps.Workflow"

The meter and activity source name.

Dispose() method

public void Dispose()

Disposes the meter.

ObserveConsole(string, string) method

public IDisposable ObserveConsole(string operation, string profile)

Counts an execution console request and times it until the result is disposed.

Parameters

Returns

Ends the timing when disposed.

RecordTerminal(string, string) method

public void RecordTerminal(string definition, string outcome)

Counts a terminal transition of an execution.

Parameters

StellaOps.Workflow.Engine.Rendering namespace

TypeKindDescription
WorkflowRenderGraphCompilerclassBuilds the render graph of a workflow definition: its start, steps, tasks and branches as nodes, and the flow between them as edges.
WorkflowRenderLayoutEngineResolverclassSelects a registered layout engine by provider name, ignoring case.

WorkflowRenderGraphCompiler class

public sealed class WorkflowRenderGraphCompiler : IWorkflowRenderGraphCompiler

Builds the render graph of a workflow definition: its start, steps, tasks and branches as nodes, and the flow between them as edges.

WorkflowRenderGraphCompiler() constructor

public WorkflowRenderGraphCompiler()

Creates an instance of WorkflowRenderGraphCompiler.

Compile(WorkflowRuntimeDefinition) method

public WorkflowRenderGraph Compile(WorkflowRuntimeDefinition definition)

Builds the render graph of a workflow definition.

Parameters

Returns

The render graph.

WorkflowRenderLayoutEngineResolver class

public sealed class WorkflowRenderLayoutEngineResolver : IWorkflowRenderLayoutEngineResolver

Selects a registered layout engine by provider name, ignoring case.

Parameters

WorkflowRenderLayoutEngineResolver(IEnumerable<INamedWorkflowRenderGraphLayoutEngine>, IOptions<WorkflowRenderingOptions>) constructor

public WorkflowRenderLayoutEngineResolver(IEnumerable<INamedWorkflowRenderGraphLayoutEngine> engines, IOptions<WorkflowRenderingOptions> options)

Selects a registered layout engine by provider name, ignoring case.

Parameters

Resolve(string) method

public INamedWorkflowRenderGraphLayoutEngine Resolve(string? providerName = null)

Returns the registered layout engine of a provider: providerName, else WorkflowRendering:LayoutProvider, else ElkSharp.

Parameters

Returns

The layout engine.

Exceptions

StellaOps.Workflow.Engine.Scheduling namespace

TypeKindDescription
NullWorkflowScheduleBusclassThe schedule bus of a host without scheduling: every call raises NotSupportedException.
NullWorkflowSignalSchedulerclassThe signal scheduler of a host without a signal store: it logs a warning and stores nothing.
WorkflowScheduleBusBridgeclassThe schedule bus over the registered signal scheduler.

NullWorkflowScheduleBus class

public sealed class NullWorkflowScheduleBus : IWorkflowScheduleBus

The schedule bus of a host without scheduling: every call raises NotSupportedException.

NullWorkflowScheduleBus() constructor

public NullWorkflowScheduleBus()

Creates an instance of NullWorkflowScheduleBus.

ScheduleAsync(WorkflowSignalEnvelope, DateTime, CancellationToken) method

public Task ScheduleAsync(WorkflowSignalEnvelope envelope, DateTime dueAtUtc, CancellationToken cancellationToken = default)

Stores a signal that becomes available at dueAtUtc.

Parameters

Returns

A task that completes when the signal is stored.

NullWorkflowSignalScheduler class

public sealed class NullWorkflowSignalScheduler : IWorkflowSignalScheduler

The signal scheduler of a host without a signal store: it logs a warning and stores nothing.

Parameters

NullWorkflowSignalScheduler(ILogger<NullWorkflowSignalScheduler>) constructor

public NullWorkflowSignalScheduler(ILogger<NullWorkflowSignalScheduler> logger)

The signal scheduler of a host without a signal store: it logs a warning and stores nothing.

Parameters

ScheduleAsync(WorkflowSignalEnvelope, DateTime, CancellationToken) method

public Task ScheduleAsync(WorkflowSignalEnvelope envelope, DateTime dueAtUtc, CancellationToken cancellationToken = default)

Stores a signal that becomes available at dueAtUtc.

Parameters

Returns

A task that completes when the signal is stored.

WorkflowScheduleBusBridge class

public sealed class WorkflowScheduleBusBridge : IWorkflowScheduleBus

The schedule bus over the registered signal scheduler.

Parameters

WorkflowScheduleBusBridge(IWorkflowSignalScheduler) constructor

public WorkflowScheduleBusBridge(IWorkflowSignalScheduler signalScheduler)

The schedule bus over the registered signal scheduler.

Parameters

ScheduleAsync(WorkflowSignalEnvelope, DateTime, CancellationToken) method

public Task ScheduleAsync(WorkflowSignalEnvelope envelope, DateTime dueAtUtc, CancellationToken cancellationToken = default)

Stores a signal that becomes available at dueAtUtc.

Parameters

Returns

A task that completes when the signal is stored.

StellaOps.Workflow.Engine.Services namespace

TypeKindDescription
DeclarativeWorkflowExecutionHandler<TWorkflow, TStartRequest>classRuns a declarative workflow class: starts, task completions and signal resumes.
DefaultWorkflowAssignmentPermissionEvaluatorclassThe default assignment rules: an actor in the effective roles (ignoring case) may assign a task to itself; assigning to another actor needs a permissions plugin; only the assignee may release; the assignee or an actor in the effective roles may complete.
GenericAssignmentPermissionEvaluatorclassA permission evaluator that recognizes configured admin roles.
GenericAssignmentPermissionOptionsclassOptions for the generic assignment permission evaluator.
InMemoryWorkflowDefinitionStoreclassIn-process definition store.
InMemoryWorkflowHostedJobLockServiceclassAn in-process hosted job lock, for a single-node host.
InMemoryWorkflowRuntimeStateStoreclassKeeps runtime states in process memory, the default when no store library registers a store; instance ids compare ignoring case, and the states end with the process.
InProcessWorkflowRuntimeOrchestratorclassThe Stella.InProcess runtime: runs the execution handler of a workflow in the calling process.
NullWorkflowDefinitionStoreclassUnsupported definition store used only as a local/test fallback until a backend-specific store is registered.
UnconfiguredWorkflowEndpointTransportclassThe endpoint transport used when none is configured: every call fails with an error that names the service and the route.
UnconfiguredWorkflowGraphqlTransportclassThe GraphQL transport used when none is configured: every call fails with an error that names the target.
UnconfiguredWorkflowHttpTransportclassThe HTTP transport used when none is configured: every call fails with an error that names the method, the target and the path.
UnconfiguredWorkflowRabbitTransportclassThe RabbitMQ transport used when none is configured: every call fails with an error that names the exchange and the routing key.
WorkflowBundledDefinitionstructA workflow an assembly ships as an embedded bundled *.definition.json.
WorkflowBundledDefinitionCoveragerecordHow many of an assembly’s bundled definitions its registrations cover, and which ones they miss.
WorkflowBundledDefinitionsclassReads the bundled definitions a workflow assembly embeds and compares them with what the assembly registered, so a host can refuse to report ready when a workflow it ships is not registered under its name and version.
WorkflowCanonicalDefinitionServiceclassServes the canonical definition schema and validates definitions.
WorkflowCanonicalJsonSchemaclassThe JSON schema of canonical workflow definitions.
WorkflowConsoleOptionsclassWhat the execution console shows of an instance’s state, per profile (WorkflowConsole).
WorkflowCoreServiceCollectionExtensionsclassRegisters the core services of the workflow engine.
WorkflowDefinitionCatalogclassThe definition descriptors of the registered workflows.
WorkflowDefinitionDeploymentServiceclassHandles import, export, versioning, and activation of canonical workflow definitions.
WorkflowDefinitionQueryServiceclassQueries the workflow definitions known to the engine: bundled in the catalog and imported into the store.
WorkflowDefinitionRenderServiceclassLays out the diagram of a registered definition.
WorkflowDiagramServiceclassLays out workflow diagrams, with the progress of an instance when the request names one.
WorkflowDurableServiceCollectionExtensionsclassRegisters the durable engine features.
WorkflowExecutionConsoleServiceclassThe execution console: lists executions and reads their resources for one profile.
WorkflowExecutionHandlerCatalogclassFinds the execution handler of a registered workflow: its registered handler type, else a declarative handler when the workflow is declarative.
WorkflowFunctionCatalogServiceclassServes the function catalog.
WorkflowMutationScopeAccessorclassHolds the change scope of the running operation.
WorkflowRegistrationCatalogclassThe registered workflows, ordered by name and then by version, newest first; names and versions compare ignoring case.
WorkflowRetentionHostedJobOptionsclassThe schedule of the retention job (WorkflowRetentionHostedJob), which marks stale instances and tasks and purges expired ones.
WorkflowRetentionOptionsclassWhen the retention job marks an open instance stale and purges a completed one (WorkflowRetention).
WorkflowRetentionRunResultrecordThe counts of a retention run.
WorkflowRetentionServiceclassRuns the instance retention: marks stale and purges projections and runtime states.
WorkflowRoleResolutionServiceclassComputes the roles that may work a task.
WorkflowRuntimeServiceclassThe engine’s workflow runtime: starts instances, reads instances and tasks, completes, assigns and releases tasks, raises signals, cancels instances, and resumes instances with signals.
WorkflowSignalDeadLetterServiceclassLists and replays dead-lettered signals.
WorkflowSignalPumpTelemetryServiceclassCounts the signal pump’s work in this process, for the pump statistics.
WorkflowStudioDescriptorclassDescribes the workflow service to tools.
WorkflowStudioOptionsclassNames the host and its diagram provider in the workflow service metadata.
WorkflowTaskCreationNotifierclassSingleton notification service that allows CompleteTaskAsync to block until the signal pump creates the next user task for a workflow instance.

DeclarativeWorkflowExecutionHandler<TWorkflow, TStartRequest> class

public sealed class DeclarativeWorkflowExecutionHandler<TWorkflow, TStartRequest> : IWorkflowExecutionHandler, IWorkflowSignalResumableExecutionHandler where TWorkflow : class, IDeclarativeWorkflow<TStartRequest>, new() where TStartRequest : class

Runs a declarative workflow class: starts, task completions and signal resumes.

Type parameters

Parameters

DeclarativeWorkflowExecutionHandler(IWorkflowEndpointTransport, IWorkflowGraphqlTransport, IWorkflowHttpTransport, IWorkflowRabbitTransport, IWorkflowFunctionRuntime, IWorkflowExecutionHandlerCatalog, IWorkflowRegistrationCatalog) constructor

public DeclarativeWorkflowExecutionHandler(IWorkflowEndpointTransport endpointTransport, IWorkflowGraphqlTransport graphqlTransport, IWorkflowHttpTransport httpTransport, IWorkflowRabbitTransport rabbitTransport, IWorkflowFunctionRuntime workflowFunctionRuntime, IWorkflowExecutionHandlerCatalog workflowExecutionHandlerCatalog, IWorkflowRegistrationCatalog workflowRegistrationCatalog)

Runs a declarative workflow class: starts, task completions and signal resumes.

Type parameters

Parameters

CompleteTaskAsync(WorkflowTaskExecutionContext, CancellationToken) method

public Task<WorkflowTaskCompletionPlan> CompleteTaskAsync(WorkflowTaskExecutionContext context, CancellationToken cancellationToken = default)

Plans the completion of a task.

Parameters

Returns

The plan.

StartAsync(WorkflowStartExecutionContext, CancellationToken) method

public Task<WorkflowStartExecutionPlan> StartAsync(WorkflowStartExecutionContext context, CancellationToken cancellationToken = default)

Plans the start of an instance.

Parameters

Returns

The plan.

DefaultWorkflowAssignmentPermissionEvaluator class

public sealed class DefaultWorkflowAssignmentPermissionEvaluator : IWorkflowAssignmentPermissionEvaluator

The default assignment rules: an actor in the effective roles (ignoring case) may assign a task to itself; assigning to another actor needs a permissions plugin; only the assignee may release; the assignee or an actor in the effective roles may complete.

DefaultWorkflowAssignmentPermissionEvaluator() constructor

public DefaultWorkflowAssignmentPermissionEvaluator()

Creates an instance of DefaultWorkflowAssignmentPermissionEvaluator.

Evaluate(WorkflowAssignmentPermissionContext) method

public WorkflowAssignmentPermissionDecision Evaluate(WorkflowAssignmentPermissionContext context)

Decides on an action.

Parameters

Returns

The decision.

GenericAssignmentPermissionEvaluator class

public sealed class GenericAssignmentPermissionEvaluator : IWorkflowAssignmentPermissionEvaluator

A permission evaluator that recognizes configured admin roles. Admin users receive full assignment permissions (AssignOther, AssignRoles, Release) in addition to standard permissions.

GenericAssignmentPermissionEvaluator(IOptions<GenericAssignmentPermissionOptions>) constructor

public GenericAssignmentPermissionEvaluator(IOptions<GenericAssignmentPermissionOptions> options)

A permission evaluator that recognizes configured admin roles. Admin users receive full assignment permissions (AssignOther, AssignRoles, Release) in addition to standard permissions.

Evaluate(WorkflowAssignmentPermissionContext) method

public WorkflowAssignmentPermissionDecision Evaluate(WorkflowAssignmentPermissionContext context)

Decides on an action.

Parameters

Returns

The decision.

GenericAssignmentPermissionOptions class

public sealed class GenericAssignmentPermissionOptions

Options for the generic assignment permission evaluator.

GenericAssignmentPermissionOptions() constructor

public GenericAssignmentPermissionOptions()

Creates an instance of GenericAssignmentPermissionOptions.

SectionName constant

public const string SectionName = "GenericAssignmentPermissions"

The configuration section the options bind from: GenericAssignmentPermissions.

AdminRoles property

public List<string> AdminRoles { get; set; }

Roles that are considered admin roles for workflow task assignment. Admin users can assign tasks to others, assign roles, and release tasks.

AssigneeCanComplete property

public bool AssigneeCanComplete { get; set; }

When true, the current assignee may complete the task even without one of its effective roles (for example after an admin assigned it to them). Default false.

InMemoryWorkflowDefinitionStore class

public sealed class InMemoryWorkflowDefinitionStore : IWorkflowDefinitionStore, IWorkflowDefinitionGovernanceStore

In-process definition store. Keeps imported definitions for the lifetime of the host process. Suitable for development, demonstrations and tests. For production deployments, register a durable store (PostgreSQL or MongoDB) that overrides this registration.

InMemoryWorkflowDefinitionStore(ILogger<InMemoryWorkflowDefinitionStore>) constructor

public InMemoryWorkflowDefinitionStore(ILogger<InMemoryWorkflowDefinitionStore> logger)

In-process definition store. Keeps imported definitions for the lifetime of the host process. Suitable for development, demonstrations and tests. For production deployments, register a durable store (PostgreSQL or MongoDB) that overrides this registration.

ActivateAsync(string, string, CancellationToken) method

public Task ActivateAsync(string workflowName, string version, CancellationToken cancellationToken = default)

Sets a specific version as active for a workflow name. Deactivates all other versions of the same workflow.

ActivateGovernedAsync(WorkflowDefinitionActivationRecord, CancellationToken) method

public Task ActivateGovernedAsync(WorkflowDefinitionActivationRecord activation, CancellationToken cancellationToken = default)

Activates a version under the activation fence and the rollback rule, and records the activation for the audit.

Parameters

Returns

A task that completes when the version is active.

Exceptions

FindByHashAsync(string, string, CancellationToken) method

public Task<WorkflowDefinitionRecord?> FindByHashAsync(string workflowName, string contentHash, CancellationToken cancellationToken = default)

Finds any definition record matching the given content hash, regardless of version. Used to detect duplicate imports.

GetActiveAsync(string, CancellationToken) method

public Task<WorkflowDefinitionRecord?> GetActiveAsync(string workflowName, CancellationToken cancellationToken = default)

Gets the active definition for a workflow name. Returns null if no definition is stored for this workflow.

GetAllActiveAsync(CancellationToken) method

public Task<IReadOnlyCollection<WorkflowDefinitionRecord>> GetAllActiveAsync(CancellationToken cancellationToken = default)

Gets all active definitions across all workflow names.

GetAsync(string, string, CancellationToken) method

public Task<WorkflowDefinitionRecord?> GetAsync(string workflowName, string version, CancellationToken cancellationToken = default)

Gets a specific version of a workflow definition.

GetVersionsAsync(string, CancellationToken) method

public Task<IReadOnlyCollection<WorkflowDefinitionRecord>> GetVersionsAsync(string workflowName, CancellationToken cancellationToken = default)

Gets all versions of a workflow definition, ordered by creation date descending.

UpsertAsync(WorkflowDefinitionRecord, CancellationToken) method

public Task UpsertAsync(WorkflowDefinitionRecord record, CancellationToken cancellationToken = default)

Inserts or updates a definition record.

InMemoryWorkflowHostedJobLockService class

public sealed class InMemoryWorkflowHostedJobLockService : IWorkflowHostedJobLockService

An in-process hosted job lock, for a single-node host.

InMemoryWorkflowHostedJobLockService() constructor

public InMemoryWorkflowHostedJobLockService()

Creates an instance of InMemoryWorkflowHostedJobLockService.

ReleaseAsync(string, string, CancellationToken) method

public Task ReleaseAsync(string lockName, string lockOwner, CancellationToken cancellationToken = default)

Releases a lock the owner holds.

Parameters

Returns

A task that completes when the lock is released.

TryAcquireAsync(string, string, DateTime, TimeSpan, CancellationToken) method

public Task<bool> TryAcquireAsync(string lockName, string lockOwner, DateTime acquiredOnUtc, TimeSpan lease, CancellationToken cancellationToken = default)

Takes a lock for an owner unless another owner holds an unexpired lease.

Parameters

Returns

Whether the owner holds the lock.

InMemoryWorkflowRuntimeStateStore class

public sealed class InMemoryWorkflowRuntimeStateStore : IWorkflowRuntimeStateStore

Keeps runtime states in process memory, the default when no store library registers a store; instance ids compare ignoring case, and the states end with the process.

InMemoryWorkflowRuntimeStateStore() constructor

public InMemoryWorkflowRuntimeStateStore()

Creates an instance of InMemoryWorkflowRuntimeStateStore.

DeleteAsync(IReadOnlyCollection<string>, CancellationToken) method

public Task<int> DeleteAsync(IReadOnlyCollection<string> workflowInstanceIds, CancellationToken cancellationToken = default)

Deletes the runtime states of instances.

Parameters

Returns

The states deleted.

GetAsync(string, CancellationToken) method

public Task<WorkflowRuntimeStateRecord?> GetAsync(string workflowInstanceId, CancellationToken cancellationToken = default)

Reads the runtime state of an instance.

Parameters

Returns

The state, or null.

GetManyAsync(IReadOnlyCollection<string>, CancellationToken) method

public Task<IReadOnlyCollection<WorkflowRuntimeStateRecord>> GetManyAsync(IReadOnlyCollection<string> workflowInstanceIds, CancellationToken cancellationToken = default)

Reads the runtime states of instances.

Parameters

Returns

The states found.

MarkStaleAsync(IReadOnlyCollection<string>, DateTime, CancellationToken) method

public Task<int> MarkStaleAsync(IReadOnlyCollection<string> workflowInstanceIds, DateTime updatedOnUtc, CancellationToken cancellationToken = default)

Marks instances stale.

Parameters

Returns

The instances marked.

UpsertAsync(WorkflowRuntimeStateRecord, CancellationToken) method

public Task UpsertAsync(WorkflowRuntimeStateRecord state, CancellationToken cancellationToken = default)

Writes a runtime state whose version is one above the stored one (or the first).

Parameters

Returns

A task that completes when the state is written.

Exceptions

InProcessWorkflowRuntimeOrchestrator class

public sealed class InProcessWorkflowRuntimeOrchestrator : IWorkflowRuntimeProvider

The Stella.InProcess runtime: runs the execution handler of a workflow in the calling process.

Parameters

InProcessWorkflowRuntimeOrchestrator(IWorkflowExecutionHandlerCatalog) constructor

public InProcessWorkflowRuntimeOrchestrator(IWorkflowExecutionHandlerCatalog workflowExecutionHandlerCatalog)

The Stella.InProcess runtime: runs the execution handler of a workflow in the calling process.

Parameters

ProviderName constant

public const string ProviderName = "Stella.InProcess"

The provider name: Stella.InProcess.

CompleteAsync(WorkflowRegistration, WorkflowDefinitionDescriptor, WorkflowTaskExecutionContext, CancellationToken) method

public Task<WorkflowRuntimeExecutionResult> CompleteAsync(WorkflowRegistration registration, WorkflowDefinitionDescriptor definition, WorkflowTaskExecutionContext context, CancellationToken cancellationToken = default)

Completes a task.

Parameters

Returns

The outcome.

ResumeAsync(WorkflowRegistration, WorkflowDefinitionDescriptor, WorkflowSignalExecutionContext, CancellationToken) method

public Task<WorkflowRuntimeExecutionResult> ResumeAsync(WorkflowRegistration registration, WorkflowDefinitionDescriptor definition, WorkflowSignalExecutionContext context, CancellationToken cancellationToken = default)

Resumes an instance with a signal.

Parameters

Returns

The outcome.

StartAsync(WorkflowRegistration, WorkflowDefinitionDescriptor, WorkflowBusinessReference, StartWorkflowRequest, object, CancellationToken) method

public Task<WorkflowRuntimeExecutionResult> StartAsync(WorkflowRegistration registration, WorkflowDefinitionDescriptor definition, WorkflowBusinessReference? businessReference, StartWorkflowRequest request, object startRequest, CancellationToken cancellationToken = default)

Starts an instance.

Parameters

Returns

The outcome.

NullWorkflowDefinitionStore class

public sealed class NullWorkflowDefinitionStore : IWorkflowDefinitionStore

Unsupported definition store used only as a local/test fallback until a backend-specific store is registered.

NullWorkflowDefinitionStore(ILogger<NullWorkflowDefinitionStore>) constructor

public NullWorkflowDefinitionStore(ILogger<NullWorkflowDefinitionStore> logger)

Unsupported definition store used only as a local/test fallback until a backend-specific store is registered.

ActivateAsync(string, string, CancellationToken) method

public Task ActivateAsync(string workflowName, string version, CancellationToken cancellationToken = default)

Sets a specific version as active for a workflow name. Deactivates all other versions of the same workflow.

FindByHashAsync(string, string, CancellationToken) method

public Task<WorkflowDefinitionRecord?> FindByHashAsync(string workflowName, string contentHash, CancellationToken cancellationToken = default)

Finds any definition record matching the given content hash, regardless of version. Used to detect duplicate imports.

GetActiveAsync(string, CancellationToken) method

public Task<WorkflowDefinitionRecord?> GetActiveAsync(string workflowName, CancellationToken cancellationToken = default)

Gets the active definition for a workflow name. Returns null if no definition is stored for this workflow.

GetAllActiveAsync(CancellationToken) method

public Task<IReadOnlyCollection<WorkflowDefinitionRecord>> GetAllActiveAsync(CancellationToken cancellationToken = default)

Gets all active definitions across all workflow names.

GetAsync(string, string, CancellationToken) method

public Task<WorkflowDefinitionRecord?> GetAsync(string workflowName, string version, CancellationToken cancellationToken = default)

Gets a specific version of a workflow definition.

GetVersionsAsync(string, CancellationToken) method

public Task<IReadOnlyCollection<WorkflowDefinitionRecord>> GetVersionsAsync(string workflowName, CancellationToken cancellationToken = default)

Gets all versions of a workflow definition, ordered by creation date descending.

UpsertAsync(WorkflowDefinitionRecord, CancellationToken) method

public Task UpsertAsync(WorkflowDefinitionRecord record, CancellationToken cancellationToken = default)

Inserts or updates a definition record.

UnconfiguredWorkflowEndpointTransport class

public sealed class UnconfiguredWorkflowEndpointTransport : IWorkflowEndpointTransport

The endpoint transport used when none is configured: every call fails with an error that names the service and the route.

UnconfiguredWorkflowEndpointTransport() constructor

public UnconfiguredWorkflowEndpointTransport()

Creates an instance of UnconfiguredWorkflowEndpointTransport.

ExecuteAsync(WorkflowEndpointRequest, CancellationToken) method

public Task<WorkflowEndpointResponse> ExecuteAsync(WorkflowEndpointRequest request, CancellationToken cancellationToken = default)

Sends the request and returns the response. A failure, such as a non-success status or a target that is not configured, is a response that did not succeed; a call that does not answer in time raises a TimeoutException.

Parameters

Returns

The response.

UnconfiguredWorkflowGraphqlTransport class

public sealed class UnconfiguredWorkflowGraphqlTransport : IWorkflowGraphqlTransport

The GraphQL transport used when none is configured: every call fails with an error that names the target.

UnconfiguredWorkflowGraphqlTransport() constructor

public UnconfiguredWorkflowGraphqlTransport()

Creates an instance of UnconfiguredWorkflowGraphqlTransport.

ExecuteAsync(WorkflowGraphqlRequest, CancellationToken) method

public Task<WorkflowGraphqlResponse> ExecuteAsync(WorkflowGraphqlRequest request, CancellationToken cancellationToken = default)

Sends the query and returns the response. A failure, such as a non-success status or an errors array in the response, is a response that did not succeed; a call that does not answer in time raises a TimeoutException.

Parameters

Returns

The response.

UnconfiguredWorkflowHttpTransport class

public sealed class UnconfiguredWorkflowHttpTransport : IWorkflowHttpTransport

The HTTP transport used when none is configured: every call fails with an error that names the method, the target and the path.

UnconfiguredWorkflowHttpTransport() constructor

public UnconfiguredWorkflowHttpTransport()

Creates an instance of UnconfiguredWorkflowHttpTransport.

ExecuteAsync(WorkflowHttpRequest, CancellationToken) method

public Task<WorkflowHttpResponse> ExecuteAsync(WorkflowHttpRequest request, CancellationToken cancellationToken = default)

Sends the request and returns the response. A failure, such as a non-success status or a target that is not configured, is a response that did not succeed; a call that does not answer in time raises a TimeoutException.

Parameters

Returns

The response.

UnconfiguredWorkflowRabbitTransport class

public sealed class UnconfiguredWorkflowRabbitTransport : IWorkflowRabbitTransport

The RabbitMQ transport used when none is configured: every call fails with an error that names the exchange and the routing key.

UnconfiguredWorkflowRabbitTransport() constructor

public UnconfiguredWorkflowRabbitTransport()

Creates an instance of UnconfiguredWorkflowRabbitTransport.

ExecuteAsync(WorkflowRabbitRequest, CancellationToken) method

public Task<WorkflowRabbitResponse> ExecuteAsync(WorkflowRabbitRequest request, CancellationToken cancellationToken = default)

Publishes the request, and for a command that expects a reply, waits for the correlated reply. A failure is a response that did not succeed; a reply that does not arrive in time raises a TimeoutException.

Parameters

Returns

The response.

WorkflowBundledDefinition struct

public readonly struct WorkflowBundledDefinition : IEquatable<WorkflowBundledDefinition>

A workflow an assembly ships as an embedded bundled *.definition.json.

Parameters

WorkflowBundledDefinition(string, string) constructor

public WorkflowBundledDefinition(string WorkflowName, string WorkflowVersion)

A workflow an assembly ships as an embedded bundled *.definition.json.

Parameters

WorkflowName property

public string WorkflowName { get; init; }

The workflow name.

WorkflowVersion property

public string WorkflowVersion { get; init; }

The workflow version.

ToString() method

public override string ToString()

Returns the name and the version, separated by a space.

Returns

The text.

WorkflowBundledDefinitionCoverage record

public sealed record WorkflowBundledDefinitionCoverage

How many of an assembly’s bundled definitions its registrations cover, and which ones they miss.

Parameters

WorkflowBundledDefinitionCoverage(string, IReadOnlyCollection<WorkflowBundledDefinition>, int, IReadOnlyCollection<WorkflowBundledDefinition>) constructor

public WorkflowBundledDefinitionCoverage(string AssemblyName, IReadOnlyCollection<WorkflowBundledDefinition> Bundled, int RegisteredCount, IReadOnlyCollection<WorkflowBundledDefinition> Missing)

How many of an assembly’s bundled definitions its registrations cover, and which ones they miss.

Parameters

AssemblyName property

public string AssemblyName { get; init; }

The assembly.

Bundled property

public IReadOnlyCollection<WorkflowBundledDefinition> Bundled { get; init; }

The bundled definitions.

Missing property

public IReadOnlyCollection<WorkflowBundledDefinition> Missing { get; init; }

The bundled definitions no registration covers.

RegisteredCount property

public int RegisteredCount { get; init; }

The registrations of the assembly.

WorkflowBundledDefinitions class

public static class WorkflowBundledDefinitions

Reads the bundled definitions a workflow assembly embeds and compares them with what the assembly registered, so a host can refuse to report ready when a workflow it ships is not registered under its name and version.

ResourceMarker constant

public const string ResourceMarker = ".WorkflowDefinitions."

Part of the manifest resource name of an embedded bundled definition: a workflow assembly embeds each *.definition.json as $(AssemblyName).WorkflowDefinitions.<file name>.

Compare(Assembly, IEnumerable<WorkflowRegistration>) method

public static WorkflowBundledDefinitionCoverage Compare(Assembly assembly, IEnumerable<WorkflowRegistration> registrations)

Compares the bundled definitions of assembly with the registrations its types made.

Read(Assembly) method

public static IReadOnlyCollection<WorkflowBundledDefinition> Read(Assembly assembly)

The bundled definitions assembly embeds (name and version of each).

WorkflowCanonicalDefinitionService class

public sealed class WorkflowCanonicalDefinitionService

Serves the canonical definition schema and validates definitions.

Parameters

WorkflowCanonicalDefinitionService(IWorkflowModuleCatalog, IWorkflowFunctionCatalog, IWorkflowExternalActivityRegistry) constructor

public WorkflowCanonicalDefinitionService(IWorkflowModuleCatalog workflowModuleCatalog, IWorkflowFunctionCatalog workflowFunctionCatalog, IWorkflowExternalActivityRegistry externalActivityRegistry)

Serves the canonical definition schema and validates definitions.

Parameters

GetSchema() method

public WorkflowCanonicalSchemaGetResponse GetSchema()

Returns the JSON schema of canonical definitions.

Returns

The schema.

Validate(WorkflowCanonicalValidateRequest) method

public WorkflowCanonicalValidateResponse Validate(WorkflowCanonicalValidateRequest request)

Validates a canonical definition without importing it.

Parameters

Returns

The findings.

WorkflowCanonicalJsonSchema class

public static class WorkflowCanonicalJsonSchema

The JSON schema of canonical workflow definitions.

DefinitionSchema property

public static JsonSchema DefinitionSchema { get; }

The schema.

GetSchemaJson() method

public static string GetSchemaJson()

Returns the schema as JSON.

Returns

The schema JSON.

ValidateJson(string) method

public static IReadOnlyCollection<WorkflowCanonicalValidationError> ValidateJson(string json)

Validates JSON against the schema.

Parameters

Returns

The findings.

WorkflowConsoleOptions class

public sealed class WorkflowConsoleOptions

What the execution console shows of an instance’s state, per profile (WorkflowConsole).

WorkflowConsoleOptions() constructor

public WorkflowConsoleOptions()

Creates an instance of WorkflowConsoleOptions.

SectionName constant

public const string SectionName = "WorkflowConsole"

The configuration section the options bind from: WorkflowConsole.

SafeStateKeys property

public List<string> SafeStateKeys { get; set; }

Top-level state keys the SAFE profile shows; everything else is hidden.

TechnicalRedactedFragments property

public List<string> TechnicalRedactedFragments { get; set; }

Name fragments the TECHNICAL profile removes from the top-level state.

WorkflowCoreServiceCollectionExtensions class

public static class WorkflowCoreServiceCollectionExtensions

Registers the core services of the workflow engine. Platform integrations, such as the data context, plugin loading, authentication, health checks and rendering layout engines, are registered separately.

AddWorkflowEngineCoreServices(IServiceCollection, IConfiguration) extension method

public static IServiceCollection AddWorkflowEngineCoreServices(this IServiceCollection services, IConfiguration configuration)

Registers the core services of the workflow engine: the backend, signal driver and runtime options; the module and function catalogs; the registration and definition catalogs; the execution handlers, the runtime providers and their orchestrator; signal processing and the signal pump; the definition deployment and query services; the licence services; the source format converters; and the render graph compiler. A runtime state store, a hosted job lock, the signal stores and the transports are registered only when none is, as in-memory, empty or unconfigured defaults.

Remarks

It does not register a projection store, a mutation coordinator or a projection retention store (the selected backend does), plugin loading, authentication, health checks or rendering layout engines; the host or another extension method registers them.

AddWorkflowEngineHostedServices(IServiceCollection) extension method

public static IServiceCollection AddWorkflowEngineHostedServices(this IServiceCollection services)

Registers the hosted services for signal pump and retention background processing, and the component licence monitor with its informational licence health entry. Call this only when running as the workflow engine service host.

ConfigureWorkflowRuntimeProviderDefault(IServiceCollection, IConfiguration, string) extension method

public static IServiceCollection ConfigureWorkflowRuntimeProviderDefault(this IServiceCollection services, IConfiguration configuration, string providerName)

Makes providerName the default runtime provider unless WorkflowRuntime:DefaultProvider is configured. The latest call wins, so a host calls it after WorkflowCoreServiceCollectionExtensions.AddWorkflowEngineCoreServices(IServiceCollection, IConfiguration)to replace the engine’s default.

WorkflowDefinitionCatalog class

public sealed class WorkflowDefinitionCatalog : IWorkflowDefinitionCatalog

The definition descriptors of the registered workflows.

Parameters

WorkflowDefinitionCatalog(IWorkflowRegistrationCatalog) constructor

public WorkflowDefinitionCatalog(IWorkflowRegistrationCatalog workflowRegistrationCatalog)

The definition descriptors of the registered workflows.

Parameters

GetDefinition(string, string) method

public WorkflowDefinitionDescriptor? GetDefinition(string workflowName, string? workflowVersion = null)

Finds a descriptor.

Parameters

Returns

The descriptor, or null.

GetDefinitions() method

public IReadOnlyCollection<WorkflowDefinitionDescriptor> GetDefinitions()

Returns every descriptor.

Returns

The descriptors.

WorkflowDefinitionDeploymentService class

public sealed class WorkflowDefinitionDeploymentService

Handles import, export, versioning, and activation of canonical workflow definitions.

WorkflowDefinitionDeploymentService(IWorkflowDefinitionStore, IWorkflowRuntimeDefinitionStore, IWorkflowRenderGraphCompiler, IWorkflowRenderLayoutEngineResolver, IWorkflowSourceFormatRegistry, WorkflowCanonicalDefinitionService, IWorkflowFirstSeenLedger, TimeProvider, ILogger<WorkflowDefinitionDeploymentService>, WorkflowLicenceState, IWorkflowRenderSvgRenderer) constructor

public WorkflowDefinitionDeploymentService(IWorkflowDefinitionStore definitionStore, IWorkflowRuntimeDefinitionStore runtimeDefinitionStore, IWorkflowRenderGraphCompiler renderGraphCompiler, IWorkflowRenderLayoutEngineResolver renderLayoutEngineResolver, IWorkflowSourceFormatRegistry sourceFormatRegistry, WorkflowCanonicalDefinitionService canonicalDefinitionService, IWorkflowFirstSeenLedger firstSeenLedger, TimeProvider timeProvider, ILogger<WorkflowDefinitionDeploymentService> logger, WorkflowLicenceState? licenceState = null, IWorkflowRenderSvgRenderer? svgRenderer = null)

Handles import, export, versioning, and activation of canonical workflow definitions.

ActivateAsync(WorkflowDefinitionActivateRequest, CancellationToken) method

public Task<WorkflowDefinitionActivateResponse> ActivateAsync(WorkflowDefinitionActivateRequest request, CancellationToken cancellationToken = default)

Activates a specific version of a workflow definition.

CreateImportRequestAsync(string, string, string, CancellationToken) method

public Task<WorkflowDefinitionImportRequest?> CreateImportRequestAsync(string workflowName, string? version, string importedBy, CancellationToken cancellationToken = default)

Exports a definition (with its rendering) as the import request another engine accepts; null when the definition or version does not exist. The caller chooses the transport that delivers it.

ExportAsync(WorkflowDefinitionExportRequest, CancellationToken) method

public Task<WorkflowDefinitionExportResponse> ExportAsync(WorkflowDefinitionExportRequest request, CancellationToken cancellationToken = default)

Exports a stored definition.

Parameters

Returns

The definition.

ExportMultiAsync(WorkflowDefinitionExportMultiRequest, CancellationToken) method

public Task<WorkflowDefinitionExportMultiResponse> ExportMultiAsync(WorkflowDefinitionExportMultiRequest request, CancellationToken cancellationToken = default)

Exports a definition in a source format.

Parameters

Returns

The content.

GetDefinitionByIdAsync(WorkflowDefinitionByIdRequest, CancellationToken) method

public Task<WorkflowDefinitionByIdResponse> GetDefinitionByIdAsync(WorkflowDefinitionByIdRequest request, CancellationToken cancellationToken = default)

Gets a single definition by name (and optional version) with optional rendering assets. Precedence matches the engine: runtime store (code-registered) first, persistent store (imported) fallback.

GetRenderGraphAsync(WorkflowRenderGraphGetRequest, CancellationToken) method

public Task<WorkflowRenderGraphGetResponse> GetRenderGraphAsync(WorkflowRenderGraphGetRequest request, CancellationToken cancellationToken = default)

Returns the typed render graph (nodes + edges) for a workflow, compiled from its canonical AST. Runtime store first, persistent store fallback (reconstructs a stub runtime definition).

GetSupportedFormats() method

public WorkflowSupportedFormatsGetResponse GetSupportedFormats()

Returns the source formats the server converts.

Returns

The formats.

GetVersionsAsync(WorkflowDefinitionVersionsGetRequest, CancellationToken) method

public Task<WorkflowDefinitionVersionsGetResponse> GetVersionsAsync(WorkflowDefinitionVersionsGetRequest request, CancellationToken cancellationToken = default)

Lists all versions of a workflow definition.

ImportAsync(WorkflowDefinitionImportRequest, CancellationToken) method

public Task<WorkflowDefinitionImportResponse> ImportAsync(WorkflowDefinitionImportRequest request, CancellationToken cancellationToken = default)

Imports an immutable canonical definition. Import and activation are deliberately separate. A stored workflow is then recorded in the first-seen ledger (the technical count of recorded workflow names). Nothing is refused for licence reasons: an import that fails before it is stored records nothing, and a ledger failure never fails the import.

ImportMultiAsync(WorkflowDefinitionImportMultiRequest, CancellationToken) method

public Task<WorkflowDefinitionImportMultiResponse> ImportMultiAsync(WorkflowDefinitionImportMultiRequest request, CancellationToken cancellationToken = default)

Converts content of a source format to a canonical definition and imports it.

Parameters

Returns

The outcome.

RenderAsync(WorkflowRenderingRequest, CancellationToken) method

public Task<WorkflowRenderingResponse> RenderAsync(WorkflowRenderingRequest request, CancellationToken cancellationToken = default)

Renders a workflow definition in the requested format (SVG, PNG, or JSON render graph).

WorkflowDefinitionQueryService class

public sealed class WorkflowDefinitionQueryService

Queries the workflow definitions known to the engine: bundled in the catalog and imported into the store.

WorkflowDefinitionQueryService(IWorkflowDefinitionCatalog, IWorkflowDefinitionStore) constructor

public WorkflowDefinitionQueryService(IWorkflowDefinitionCatalog workflowDefinitionCatalog, IWorkflowDefinitionStore workflowDefinitionStore)

Queries the workflow definitions known to the engine: bundled in the catalog and imported into the store.

QueryAsync(WorkflowDefinitionGetRequest) method

public Task<WorkflowDefinitionGetResponse> QueryAsync(WorkflowDefinitionGetRequest request)

Lists definitions from the catalog (bundled) and the store (imported); the catalog wins on a duplicate (name, version). Without a version or names filter each name keeps only its latest version.

WorkflowDefinitionRenderService class

public sealed class WorkflowDefinitionRenderService

Lays out the diagram of a registered definition.

Parameters

WorkflowDefinitionRenderService(IWorkflowRuntimeDefinitionStore, IWorkflowRenderGraphCompiler, IWorkflowRenderLayoutEngineResolver) constructor

public WorkflowDefinitionRenderService(IWorkflowRuntimeDefinitionStore runtimeDefinitionStore, IWorkflowRenderGraphCompiler renderGraphCompiler, IWorkflowRenderLayoutEngineResolver renderLayoutEngineResolver)

Lays out the diagram of a registered definition.

Parameters

RenderDefinitionAsync(string, string, string, WorkflowRenderLayoutRequest, CancellationToken) method

public Task<(string ProviderName, WorkflowRenderLayoutResult Layout)> RenderDefinitionAsync(string workflowName, string? workflowVersion = null, string? layoutProvider = null, WorkflowRenderLayoutRequest? layoutRequest = null, CancellationToken cancellationToken = default)

Lays out a definition.

Parameters

Returns

The provider used and the layout.

WorkflowDiagramService class

public sealed class WorkflowDiagramService

Lays out workflow diagrams, with the progress of an instance when the request names one.

Parameters

WorkflowDiagramService(IWorkflowDefinitionCatalog, WorkflowRuntimeService, WorkflowDefinitionRenderService) constructor

public WorkflowDiagramService(IWorkflowDefinitionCatalog workflowDefinitionCatalog, WorkflowRuntimeService workflowRuntimeService, WorkflowDefinitionRenderService definitionRenderService)

Lays out workflow diagrams, with the progress of an instance when the request names one.

Parameters

GetDiagramAsync(WorkflowDiagramGetRequest, CancellationToken) method

public Task<WorkflowDiagramGetResponse> GetDiagramAsync(WorkflowDiagramGetRequest request, CancellationToken cancellationToken = default)

Lays out a diagram.

Parameters

Returns

The diagram.

WorkflowDurableServiceCollectionExtensions class

public static class WorkflowDurableServiceCollectionExtensions

Registers the durable engine features.

AddWorkflowEngineDurableServices(IServiceCollection, IConfiguration) extension method

public static IServiceCollection AddWorkflowEngineDurableServices(this IServiceCollection services, IConfiguration configuration)

Registers the durable engine features on top of WorkflowCoreServiceCollectionExtensions.AddWorkflowEngineCoreServices(IServiceCollection, IConfiguration): durable start and root continuation, registered signals, external activities, maps, child executions, history, observability, the execution console and the Studio descriptor. Every store these services use comes from a store library (PostgreSQL or MongoDB).

ValidateWorkflowProviderRegistrations(IServiceCollection, IConfiguration) extension method

public static IServiceCollection ValidateWorkflowProviderRegistrations(this IServiceCollection services, IConfiguration configuration)

Fails fast when the configured backend (WorkflowBackend:Provider) or signal driver (WorkflowSignalDriver:Provider) was not registered by any store or driver library. Call it after every store and driver registration (manual, plug-in routine or host loader).

WorkflowExecutionConsoleService class

public sealed class WorkflowExecutionConsoleService

The execution console: lists executions and reads their resources for one profile.

Parameters

WorkflowExecutionConsoleService(IWorkflowExecutionConsoleReadStore, WorkflowHistoryService, WorkflowObservability, IOptions<WorkflowConsoleOptions>) constructor

public WorkflowExecutionConsoleService(IWorkflowExecutionConsoleReadStore readStore, WorkflowHistoryService historyService, WorkflowObservability? observability = null, IOptions<WorkflowConsoleOptions>? consoleOptions = null)

The execution console: lists executions and reads their resources for one profile.

Parameters

GetAttemptsAsync(WorkflowExecutionResourceRequest, CancellationToken) method

public Task<WorkflowExecutionResourceResponse> GetAttemptsAsync(WorkflowExecutionResourceRequest request, CancellationToken cancellationToken = default)

Reads the step attempts of an execution.

Parameters

Returns

The resource; not found when the execution does not exist.

GetDeliveryChronologyAsync(WorkflowExecutionResourceRequest, CancellationToken) method

public Task<WorkflowExecutionResourceResponse> GetDeliveryChronologyAsync(WorkflowExecutionResourceRequest request, CancellationToken cancellationToken = default)

Reads the activity dispatches and completions of an execution, in time order.

Parameters

Returns

The resource; not found when the execution does not exist.

GetExecutionAsync(WorkflowExecutionResourceRequest, CancellationToken) method

public Task<WorkflowExecutionResourceResponse> GetExecutionAsync(WorkflowExecutionResourceRequest request, CancellationToken cancellationToken = default)

Reads an execution: its identity, status and history position.

Parameters

Returns

The resource; not found when the execution does not exist.

GetGraphAsync(WorkflowExecutionResourceRequest, CancellationToken) method

public Task<WorkflowExecutionResourceResponse> GetGraphAsync(WorkflowExecutionResourceRequest request, CancellationToken cancellationToken = default)

Reads the scopes and steps of an execution as a graph.

Parameters

Returns

The resource; not found when the execution does not exist.

GetMapItemsAsync(WorkflowExecutionResourceRequest, CancellationToken) method

public Task<WorkflowExecutionResourceResponse> GetMapItemsAsync(WorkflowExecutionResourceRequest request, CancellationToken cancellationToken = default)

Reads the map items of an execution.

Parameters

Returns

The resource; not found when the execution does not exist.

GetMapsAsync(WorkflowExecutionResourceRequest, CancellationToken) method

public Task<WorkflowExecutionResourceResponse> GetMapsAsync(WorkflowExecutionResourceRequest request, CancellationToken cancellationToken = default)

Reads the map executions of an execution.

Parameters

Returns

The resource; not found when the execution does not exist.

GetScopesAsync(WorkflowExecutionResourceRequest, CancellationToken) method

public Task<WorkflowExecutionResourceResponse> GetScopesAsync(WorkflowExecutionResourceRequest request, CancellationToken cancellationToken = default)

Reads the scopes of an execution.

Parameters

Returns

The resource; not found when the execution does not exist.

GetSnapshotAsync(WorkflowExecutionResourceRequest, CancellationToken) method

public Task<WorkflowExecutionResourceResponse> GetSnapshotAsync(WorkflowExecutionResourceRequest request, CancellationToken cancellationToken = default)

Reads the state of an execution, filtered by the profile.

Parameters

Returns

The resource; not found when the execution does not exist.

GetStepsAsync(WorkflowExecutionResourceRequest, CancellationToken) method

public Task<WorkflowExecutionResourceResponse> GetStepsAsync(WorkflowExecutionResourceRequest request, CancellationToken cancellationToken = default)

Reads the external activity steps of an execution.

Parameters

Returns

The resource; not found when the execution does not exist.

GetTimelineAsync(WorkflowExecutionResourceRequest, CancellationToken) method

public Task<WorkflowExecutionResourceResponse> GetTimelineAsync(WorkflowExecutionResourceRequest request, CancellationToken cancellationToken = default)

Reads a page of the history events after a sequence.

Parameters

Returns

The resource; not found when the execution does not exist.

ListAsync(WorkflowExecutionListRequest, CancellationToken) method

public Task<WorkflowExecutionListResponse> ListAsync(WorkflowExecutionListRequest request, CancellationToken cancellationToken = default)

Lists executions, newest first, a page at a time.

Parameters

Returns

A page of executions.

Exceptions

RenderSvgAsync(WorkflowExecutionResourceRequest, CancellationToken) method

public Task<WorkflowExecutionResourceResponse> RenderSvgAsync(WorkflowExecutionResourceRequest request, CancellationToken cancellationToken = default)

Draws the execution graph as SVG.

Parameters

Returns

The resource; not found when the execution does not exist.

WorkflowExecutionHandlerCatalog class

public sealed class WorkflowExecutionHandlerCatalog : IWorkflowExecutionHandlerCatalog

Finds the execution handler of a registered workflow: its registered handler type, else a declarative handler when the workflow is declarative.

Parameters

WorkflowExecutionHandlerCatalog(IServiceProvider, IWorkflowRegistrationCatalog) constructor

public WorkflowExecutionHandlerCatalog(IServiceProvider serviceProvider, IWorkflowRegistrationCatalog workflowRegistrationCatalog)

Finds the execution handler of a registered workflow: its registered handler type, else a declarative handler when the workflow is declarative.

Parameters

GetHandler(string, string) method

public IWorkflowExecutionHandler? GetHandler(string workflowName, string workflowVersion)

Finds the handler of a workflow version.

Parameters

Returns

The handler, or null.

WorkflowFunctionCatalogService class

public sealed class WorkflowFunctionCatalogService

Serves the function catalog.

Parameters

WorkflowFunctionCatalogService(IWorkflowFunctionCatalog, IWorkflowModuleCatalog) constructor

public WorkflowFunctionCatalogService(IWorkflowFunctionCatalog workflowFunctionCatalog, IWorkflowModuleCatalog workflowModuleCatalog)

Serves the function catalog.

Parameters

GetCatalog() method

public WorkflowFunctionCatalogGetResponse GetCatalog()

Returns the functions and installed modules.

Returns

The catalog.

WorkflowMutationScopeAccessor class

public sealed class WorkflowMutationScopeAccessor : IWorkflowMutationScopeAccessor

Holds the change scope of the running operation.

WorkflowMutationScopeAccessor() constructor

public WorkflowMutationScopeAccessor()

Creates an instance of WorkflowMutationScopeAccessor.

Current property

public IWorkflowMutationScope? Current { get; set; }

The change scope of the running operation, when one is open.

WorkflowRegistrationCatalog class

public sealed class WorkflowRegistrationCatalog : IWorkflowRegistrationCatalog

The registered workflows, ordered by name and then by version, newest first; names and versions compare ignoring case.

Parameters

WorkflowRegistrationCatalog(IEnumerable<WorkflowRegistration>) constructor

public WorkflowRegistrationCatalog(IEnumerable<WorkflowRegistration> registrations)

The registered workflows, ordered by name and then by version, newest first; names and versions compare ignoring case.

Parameters

GetRegistration(string, string) method

public WorkflowRegistration? GetRegistration(string workflowName, string? workflowVersion = null)

Finds a registered workflow.

Parameters

Returns

The registration, or null.

GetRegistrations() method

public IReadOnlyCollection<WorkflowRegistration> GetRegistrations()

Returns every registered workflow.

Returns

The registrations.

WorkflowRetentionHostedJobOptions class

public sealed class WorkflowRetentionHostedJobOptions

The schedule of the retention job (WorkflowRetentionHostedJob), which marks stale instances and tasks and purges expired ones. A lease lock lets one host at a time run it.

WorkflowRetentionHostedJobOptions() constructor

public WorkflowRetentionHostedJobOptions()

Creates an instance of WorkflowRetentionHostedJobOptions.

SectionName constant

public const string SectionName = "WorkflowRetentionHostedJob"

The configuration section the options bind from: WorkflowRetentionHostedJob.

Enabled property

public bool Enabled { get; set; }

Whether the retention job runs. The default is true.

InitialDelay property

public TimeSpan InitialDelay { get; set; }

The wait before the first run when the job does not run at startup. The default is 5 minutes.

Interval property

public TimeSpan Interval { get; set; }

The time between runs. The default is 24 hours.

LockLease property

public TimeSpan LockLease { get; set; }

How long a host holds the lock for one run. The default is 2 hours.

LockName property

public string LockName { get; set; }

The name of the lock that lets one host at a time run the job. The default is workflow.retention.

RunOnStartup property

public bool RunOnStartup { get; set; }

Whether the job runs once when the host starts, without the initial delay. The default is false.

WorkflowRetentionOptions class

public sealed class WorkflowRetentionOptions

When the retention job marks an open instance stale and purges a completed one (WorkflowRetention).

WorkflowRetentionOptions() constructor

public WorkflowRetentionOptions()

Creates an instance of WorkflowRetentionOptions.

SectionName constant

public const string SectionName = "WorkflowRetention"

The configuration section the options bind from: WorkflowRetention.

CompletedPurgeAfterDays property

public int CompletedPurgeAfterDays { get; set; }

The number of days after completion after which the retention job purges an instance. The default is 180.

OpenStaleAfterDays property

public int OpenStaleAfterDays { get; set; }

The number of days after which the retention job marks an open instance and its tasks stale. The default is 30.

WorkflowRetentionRunResult record

public sealed record WorkflowRetentionRunResult

The counts of a retention run.

WorkflowRetentionRunResult() constructor

public WorkflowRetentionRunResult()

Creates an instance of WorkflowRetentionRunResult.

PurgedInstances property

public required int PurgedInstances { get; init; }

Instance projections purged.

PurgedRuntimeStates property

public required int PurgedRuntimeStates { get; init; }

Runtime states deleted.

PurgedTaskEvents property

public required int PurgedTaskEvents { get; init; }

Task events purged.

PurgedTasks property

public required int PurgedTasks { get; init; }

Task projections purged.

StaleInstancesMarked property

public required int StaleInstancesMarked { get; init; }

Instances marked stale: the larger of the projection count and the runtime state count.

StaleTasksMarked property

public required int StaleTasksMarked { get; init; }

Task projections marked stale.

WorkflowRetentionService class

public sealed class WorkflowRetentionService

Runs the instance retention: marks stale and purges projections and runtime states.

Parameters

WorkflowRetentionService(IWorkflowProjectionRetentionStore, IWorkflowRuntimeStateStore) constructor

public WorkflowRetentionService(IWorkflowProjectionRetentionStore projectionRetentionStore, IWorkflowRuntimeStateStore workflowRuntimeStateStore)

Runs the instance retention: marks stale and purges projections and runtime states.

Parameters

RunAsync(DateTime?, WorkflowRetentionOverride, CancellationToken) method

public Task<WorkflowRetentionRunResult> RunAsync(DateTime? nowUtc = null, WorkflowRetentionOverride? retentionOverride = null, CancellationToken cancellationToken = default)

Runs retention once.

Parameters

Returns

The counts.

RunAsync(WorkflowRetentionRunRequest, CancellationToken) method

public Task<WorkflowRetentionRunResponse> RunAsync(WorkflowRetentionRunRequest request, CancellationToken cancellationToken = default)

Runs retention for an operator request: ReferenceUtc (default now) and optional day thresholds that override the configured ones for this run.

WorkflowRoleResolutionService class

public sealed class WorkflowRoleResolutionService

Computes the roles that may work a task.

WorkflowRoleResolutionService() constructor

public WorkflowRoleResolutionService()

Creates an instance of WorkflowRoleResolutionService.

NormalizeRoles(IReadOnlyCollection<string>) method

public IReadOnlyCollection<string> NormalizeRoles(IReadOnlyCollection<string> roles)

Drops empty roles and duplicates, ignoring case.

Parameters

Returns

The roles.

ResolveEffectiveRoles(IReadOnlyCollection<string>, IReadOnlyCollection<string>, IReadOnlyCollection<string>) method

public IReadOnlyCollection<string> ResolveEffectiveRoles(IReadOnlyCollection<string> workflowRoles, IReadOnlyCollection<string> taskRoles, IReadOnlyCollection<string>? runtimeRoles = null)

The runtime roles when there are any, else the task roles, else the workflow roles; normalized.

Parameters

Returns

The effective roles.

WorkflowRuntimeService class

public sealed class WorkflowRuntimeService

The engine’s workflow runtime: starts instances, reads instances and tasks, completes, assigns and releases tasks, raises signals, cancels instances, and resumes instances with signals.

WorkflowRuntimeService(IWorkflowRegistrationCatalog, IWorkflowDefinitionCatalog, IWorkflowRuntimeOrchestrator, IWorkflowMutationCoordinator, IWorkflowProjectionStore, WorkflowTaskAuthorizationService, IWorkflowRuntimeStateStore, IWorkflowStateJsonPolicy, IWorkflowSignalBus, IWorkflowScheduleBus, IEnumerable<IWorkflowPendingSignalDispatcher>, WorkflowTaskCreationNotifier, IWorkflowActorRoleResolver, WorkflowExecutionActorContext, IWorkflowCallerIdentityAccessor, IWorkflowCancellationCleanupPolicy, IOptions<WorkflowRetentionOptions>, IOptions<WorkflowEngineOptions>, ILogger<WorkflowRuntimeService>, WorkflowObservability) constructor

public WorkflowRuntimeService(IWorkflowRegistrationCatalog workflowRegistrationCatalog, IWorkflowDefinitionCatalog workflowDefinitionCatalog, IWorkflowRuntimeOrchestrator workflowRuntimeOrchestrator, IWorkflowMutationCoordinator workflowMutationCoordinator, IWorkflowProjectionStore workflowProjectionStore, WorkflowTaskAuthorizationService workflowTaskAuthorizationService, IWorkflowRuntimeStateStore workflowRuntimeStateStore, IWorkflowStateJsonPolicy stateJsonPolicy, IWorkflowSignalBus workflowSignalBus, IWorkflowScheduleBus workflowScheduleBus, IEnumerable<IWorkflowPendingSignalDispatcher> pendingSignalDispatchers, WorkflowTaskCreationNotifier taskCreationNotifier, IWorkflowActorRoleResolver actorContextResolver, WorkflowExecutionActorContext executionActorContext, IWorkflowCallerIdentityAccessor callerIdentity, IWorkflowCancellationCleanupPolicy cancellationCleanupPolicy, IOptions<WorkflowRetentionOptions> retentionOptions, IOptions<WorkflowEngineOptions> engineOptions, ILogger<WorkflowRuntimeService> logger, WorkflowObservability observability)

The engine’s workflow runtime: starts instances, reads instances and tasks, completes, assigns and releases tasks, raises signals, cancels instances, and resumes instances with signals.

AssignTaskAsync(WorkflowTaskAssignRequest, CancellationToken) method

public Task<WorkflowTaskAssignResponse> AssignTaskAsync(WorkflowTaskAssignRequest request, CancellationToken cancellationToken = default)

Assigns a human task to a user or to roles.

Parameters

Returns

The assigned task.

CancelWorkflowAsync(WorkflowCancelRequest, CancellationToken) method

public Task<WorkflowCancelResponse> CancelWorkflowAsync(WorkflowCancelRequest request, CancellationToken cancellationToken = default)

Cancels an instance by queuing its cancel signal, and starts the cleanup workflow when the request names one.

Parameters

Returns

Whether the cancel signal was queued, and the cleanup instance.

CompleteTaskAsync(WorkflowTaskCompleteRequest, CancellationToken) method

public Task<WorkflowTaskCompleteResponse> CompleteTaskAsync(WorkflowTaskCompleteRequest request, CancellationToken cancellationToken = default)

Completes a human task with a payload; the task’s completion steps run.

Parameters

Returns

The outcome of the completion.

ContinueDurableStartAsync(StartWorkflowExecutionV1, long, CancellationToken) method

public Task<bool> ContinueDurableStartAsync(StartWorkflowExecutionV1 durableRequest, long expectedExecutionVersion, CancellationToken cancellationToken = default)

Runs the start of a durable root whose start decision committed.

Parameters

Returns

true when the start ran; false when the execution already moved past that version.

Exceptions

GetInstanceAsync(WorkflowInstanceGetRequest, CancellationToken) method

public Task<WorkflowInstanceGetResponse> GetInstanceAsync(WorkflowInstanceGetRequest request, CancellationToken cancellationToken = default)

Reads one workflow instance.

Parameters

Returns

The instance.

GetInstancesAsync(WorkflowInstancesGetRequest, CancellationToken) method

public Task<WorkflowInstancesGetResponse> GetInstancesAsync(WorkflowInstancesGetRequest request, CancellationToken cancellationToken = default)

Lists workflow instances.

Parameters

Returns

A page of instances.

GetTaskAsync(WorkflowTaskGetRequest, CancellationToken) method

public Task<WorkflowTaskGetResponse> GetTaskAsync(WorkflowTaskGetRequest request, CancellationToken cancellationToken = default)

Reads one human task.

Parameters

Returns

The task.

GetTasksAsync(WorkflowTasksGetRequest, CancellationToken) method

public Task<WorkflowTasksGetResponse> GetTasksAsync(WorkflowTasksGetRequest request, CancellationToken cancellationToken = default)

Lists human tasks.

Parameters

Returns

A page of tasks.

RaiseExternalSignalAsync(WorkflowSignalRaiseRequest, CancellationToken) method

public Task<WorkflowSignalRaiseResponse> RaiseExternalSignalAsync(WorkflowSignalRaiseRequest request, CancellationToken cancellationToken = default)

Queues a signal for an instance that waits for it.

Parameters

Returns

The queued signal.

ReleaseTaskAsync(WorkflowTaskReleaseRequest, CancellationToken) method

public Task<WorkflowTaskReleaseResponse> ReleaseTaskAsync(WorkflowTaskReleaseRequest request, CancellationToken cancellationToken = default)

Releases an assigned human task, so another user can take it.

Parameters

Returns

The released task.

ResumeSignalAsync(WorkflowSignalEnvelope, CancellationToken) method

public Task ResumeSignalAsync(WorkflowSignalEnvelope signal, CancellationToken cancellationToken = default)

Applies a signal to its instance; see WorkflowRuntimeService.TryResumeSignalAsync(WorkflowSignalEnvelope, CancellationToken).

Parameters

Returns

A task that completes when the signal is handled.

StartWorkflowAsync(StartWorkflowRequest, CancellationToken) method

public Task<StartWorkflowResponse> StartWorkflowAsync(StartWorkflowRequest request, CancellationToken cancellationToken = default)

Starts a workflow instance.

Parameters

Returns

The new instance.

TryResumeSignalAsync(WorkflowSignalEnvelope, CancellationToken) method

public Task<bool> TryResumeSignalAsync(WorkflowSignalEnvelope signal, CancellationToken cancellationToken = default)

Applies a signal to its instance. A signal that loses the version check is applied again on the reloaded instance, up to five times; a duplicate or stale signal is ignored.

Parameters

Returns

Whether the signal was applied.

Exceptions

WorkflowSignalDeadLetterService class

public sealed class WorkflowSignalDeadLetterService

Lists and replays dead-lettered signals.

Parameters

WorkflowSignalDeadLetterService(IWorkflowSignalDeadLetterStore) constructor

public WorkflowSignalDeadLetterService(IWorkflowSignalDeadLetterStore deadLetterStore)

Lists and replays dead-lettered signals.

Parameters

GetMessagesAsync(WorkflowSignalDeadLettersGetRequest, CancellationToken) method

public Task<WorkflowSignalDeadLettersGetResponse> GetMessagesAsync(WorkflowSignalDeadLettersGetRequest request, CancellationToken cancellationToken = default)

Lists the dead letters.

Parameters

Returns

A page of dead letters.

ReplayAsync(WorkflowSignalDeadLetterReplayRequest, CancellationToken) method

public Task<WorkflowSignalDeadLetterReplayResponse> ReplayAsync(WorkflowSignalDeadLetterReplayRequest request, CancellationToken cancellationToken = default)

Puts a dead letter back on the signal queue.

Parameters

Returns

The outcome.

WorkflowSignalPumpTelemetryService class

public sealed class WorkflowSignalPumpTelemetryService

Counts the signal pump’s work in this process, for the pump statistics.

WorkflowSignalPumpTelemetryService() constructor

public WorkflowSignalPumpTelemetryService()

Creates an instance of WorkflowSignalPumpTelemetryService.

GetStats() method

public WorkflowSignalPumpStatsGetResponse GetStats()

Returns the counts so far.

Returns

The statistics.

RecordConcurrencySkip(string, WorkflowSignalEnvelope, int, TimeSpan) method

public void RecordConcurrencySkip(string consumerName, WorkflowSignalEnvelope envelope, int deliveryCount, TimeSpan duration)

Counts a delivery put back because the instance kept changing.

Parameters

RecordDeadLetter(string, WorkflowSignalEnvelope, int, TimeSpan, string) method

public void RecordDeadLetter(string consumerName, WorkflowSignalEnvelope envelope, int deliveryCount, TimeSpan duration, string? message)

Counts a dead-lettered signal.

Parameters

RecordEmptyPoll(string) method

public void RecordEmptyPoll(string consumerName)

Counts a poll that found no signal.

Parameters

RecordFailure(string, WorkflowSignalEnvelope, int, TimeSpan, Exception) method

public void RecordFailure(string consumerName, WorkflowSignalEnvelope envelope, int deliveryCount, TimeSpan duration, Exception exception)

Counts a failed delivery.

Parameters

RecordProcessed(string, WorkflowSignalEnvelope, int, TimeSpan) method

public void RecordProcessed(string consumerName, WorkflowSignalEnvelope envelope, int deliveryCount, TimeSpan duration)

Counts a processed signal.

Parameters

WorkflowStudioDescriptor class

public sealed class WorkflowStudioDescriptor

Describes the workflow service to tools.

Parameters

WorkflowStudioDescriptor(IOptions<WorkflowStudioOptions>) constructor

public WorkflowStudioDescriptor(IOptions<WorkflowStudioOptions> options)

Describes the workflow service to tools.

Parameters

GetMetadata() method

public WorkflowServiceMetadata GetMetadata()

Returns the service metadata.

Returns

The metadata.

WorkflowStudioOptions class

public sealed class WorkflowStudioOptions

Names the host and its diagram provider in the workflow service metadata.

WorkflowStudioOptions() constructor

public WorkflowStudioOptions()

Creates an instance of WorkflowStudioOptions.

SectionName constant

public const string SectionName = "WorkflowStudio"

The configuration section the options bind from: WorkflowStudio.

DiagramProvider property

public string DiagramProvider { get; set; }

The diagram provider name the workflow service metadata reports. The default is StellaOps Engine.

ServiceName property

public string ServiceName { get; set; }

The service name the workflow service metadata reports. The default is StellaOps.Workflow.

WorkflowTaskCreationNotifier class

public sealed class WorkflowTaskCreationNotifier

Singleton notification service that allows CompleteTaskAsync to block until the signal pump creates the next user task for a workflow instance.

WorkflowTaskCreationNotifier() constructor

public WorkflowTaskCreationNotifier()

Creates an instance of WorkflowTaskCreationNotifier.

NotifyTaskCreated(string) method

public void NotifyTaskCreated(string workflowInstanceId)

Called by the projection store when a new task is created for a workflow instance. Unblocks any waiting CompleteTaskAsync call.

WaitForTaskAsync(string, TimeSpan, CancellationToken) method

public Task<bool> WaitForTaskAsync(string workflowInstanceId, TimeSpan timeout, CancellationToken cancellationToken)

Register a waiter for a workflow instance. Returns a task that completes when NotifyTaskCreated is called for this instance, or when the timeout expires.

StellaOps.Workflow.Engine.Services.Converters namespace

TypeKindDescription
CanonicalBundleSourceConverterclassCanonical workflow definition plus its rendering assets, packed as a single ZIP archive.
CanonicalJsonSourceConverterclassPass-through converter for the engine’s native canonical JSON format.
CanonicalYamlSourceConverterclassRound-trips canonical workflow definitions through YAML.
WorkflowSourceFormatRegistryclassThe registry of the source format converters.

CanonicalBundleSourceConverter class

public sealed class CanonicalBundleSourceConverter : IWorkflowSourceFormatConverter

Canonical workflow definition plus its rendering assets, packed as a single ZIP archive. Layout:

manifest.json              # { "schema": "stellaops.bundle/v1", "workflowName", "workflowVersion", "createdOnUtc" }
canonical.json             # the canonical definition JSON
renderings/elksharp.svg    # optional
renderings/elksharp.png    # optional
renderings/elksharp.render.json   # optional

CanonicalBundleSourceConverter() constructor

public CanonicalBundleSourceConverter()

Creates an instance of CanonicalBundleSourceConverter.

ContentType property

public string ContentType { get; }

MIME type of the content this converter produces / consumes.

DisplayName property

public string DisplayName { get; }

Human-friendly name, for example for a format picker.

FileExtension property

public string FileExtension { get; }

Canonical file extension including the leading dot (e.g., “.json”, “.yaml”, “.zip”).

FormatId property

public string FormatId { get; }

Stable, machine-readable identifier (e.g., “canonical-json”, “canonical-yaml”, “canonical-bundle”).

IsBinary property

public bool IsBinary { get; }

True when the format is not safely paste-able as text (e.g., binary ZIP). UI uses this to disable the textarea mode and force file upload.

SupportsExport property

public bool SupportsExport { get; }

True when the converter supports encoding a stored definition into its format.

SupportsImport property

public bool SupportsImport { get; }

True when the converter supports decoding its format into canonical JSON.

ExportAsync(WorkflowDefinitionRecord, CancellationToken) method

public Task<WorkflowSourceExportResult> ExportAsync(WorkflowDefinitionRecord record, CancellationToken cancellationToken = default)

Converts a stored definition to the format.

Parameters

Returns

The content, its media type and a file name.

ImportAsync(byte[], CancellationToken) method

public Task<WorkflowSourceImportResult> ImportAsync(byte[] content, CancellationToken cancellationToken = default)

Converts content of the format to a canonical definition.

Parameters

Returns

The canonical definition, or the diagnostics of a failed conversion.

CanonicalJsonSourceConverter class

public sealed class CanonicalJsonSourceConverter : IWorkflowSourceFormatConverter

Pass-through converter for the engine’s native canonical JSON format. Import does a light UTF-8 decode + structural probe; export emits the stored CanonicalDefinitionJson verbatim.

CanonicalJsonSourceConverter() constructor

public CanonicalJsonSourceConverter()

Creates an instance of CanonicalJsonSourceConverter.

ContentType property

public string ContentType { get; }

MIME type of the content this converter produces / consumes.

DisplayName property

public string DisplayName { get; }

Human-friendly name, for example for a format picker.

FileExtension property

public string FileExtension { get; }

Canonical file extension including the leading dot (e.g., “.json”, “.yaml”, “.zip”).

FormatId property

public string FormatId { get; }

Stable, machine-readable identifier (e.g., “canonical-json”, “canonical-yaml”, “canonical-bundle”).

IsBinary property

public bool IsBinary { get; }

True when the format is not safely paste-able as text (e.g., binary ZIP). UI uses this to disable the textarea mode and force file upload.

SupportsExport property

public bool SupportsExport { get; }

True when the converter supports encoding a stored definition into its format.

SupportsImport property

public bool SupportsImport { get; }

True when the converter supports decoding its format into canonical JSON.

ExportAsync(WorkflowDefinitionRecord, CancellationToken) method

public Task<WorkflowSourceExportResult> ExportAsync(WorkflowDefinitionRecord record, CancellationToken cancellationToken = default)

Converts a stored definition to the format.

Parameters

Returns

The content, its media type and a file name.

ImportAsync(byte[], CancellationToken) method

public Task<WorkflowSourceImportResult> ImportAsync(byte[] content, CancellationToken cancellationToken = default)

Converts content of the format to a canonical definition.

Parameters

Returns

The canonical definition, or the diagnostics of a failed conversion.

CanonicalYamlSourceConverter class

public sealed class CanonicalYamlSourceConverter : IWorkflowSourceFormatConverter

Round-trips canonical workflow definitions through YAML. YAML offers a friendlier authoring experience for the same schema; the engine’s validator is JSON-based, so the converter always converts YAML to JSON before the core import pipeline receives it.

CanonicalYamlSourceConverter() constructor

public CanonicalYamlSourceConverter()

Creates an instance of CanonicalYamlSourceConverter.

ContentType property

public string ContentType { get; }

MIME type of the content this converter produces / consumes.

DisplayName property

public string DisplayName { get; }

Human-friendly name, for example for a format picker.

FileExtension property

public string FileExtension { get; }

Canonical file extension including the leading dot (e.g., “.json”, “.yaml”, “.zip”).

FormatId property

public string FormatId { get; }

Stable, machine-readable identifier (e.g., “canonical-json”, “canonical-yaml”, “canonical-bundle”).

IsBinary property

public bool IsBinary { get; }

True when the format is not safely paste-able as text (e.g., binary ZIP). UI uses this to disable the textarea mode and force file upload.

SupportsExport property

public bool SupportsExport { get; }

True when the converter supports encoding a stored definition into its format.

SupportsImport property

public bool SupportsImport { get; }

True when the converter supports decoding its format into canonical JSON.

ExportAsync(WorkflowDefinitionRecord, CancellationToken) method

public Task<WorkflowSourceExportResult> ExportAsync(WorkflowDefinitionRecord record, CancellationToken cancellationToken = default)

Converts a stored definition to the format.

Parameters

Returns

The content, its media type and a file name.

ImportAsync(byte[], CancellationToken) method

public Task<WorkflowSourceImportResult> ImportAsync(byte[] content, CancellationToken cancellationToken = default)

Converts content of the format to a canonical definition.

Parameters

Returns

The canonical definition, or the diagnostics of a failed conversion.

WorkflowSourceFormatRegistry class

public sealed class WorkflowSourceFormatRegistry : IWorkflowSourceFormatRegistry

The registry of the source format converters.

Parameters

WorkflowSourceFormatRegistry(IEnumerable<IWorkflowSourceFormatConverter>) constructor

public WorkflowSourceFormatRegistry(IEnumerable<IWorkflowSourceFormatConverter> converters)

The registry of the source format converters.

Parameters

GetAll() method

public IReadOnlyCollection<IWorkflowSourceFormatConverter> GetAll()

Returns the converters, ordered by display name.

Returns

The converters.

GetRequired(string) method

public IWorkflowSourceFormatConverter GetRequired(string formatId)

Finds a converter by format id, ignoring case.

Parameters

Returns

The converter.

Exceptions

TryGet(string) method

public IWorkflowSourceFormatConverter? TryGet(string formatId)

Finds a converter by format id, ignoring case.

Parameters

Returns

The converter, or null.

StellaOps.Workflow.Engine.Signaling namespace

TypeKindDescription
IWorkflowSignalCommandDispatcherinterfaceRuns the start and resume commands that arrive as signals.
NullWorkflowSignalBusclassThe signal bus of a host without signaling: every call raises NotSupportedException.
NullWorkflowSignalClaimStoreclassA claim store that never has a signal to claim.
NullWorkflowSignalDeadLetterStoreclassThe dead letter store used when the backend registers none: every call raises NotSupportedException.
NullWorkflowSignalDriverclassThe signal driver None: it sends no wake and has no signal to receive.
NullWorkflowSignalStoreclassThe signal store of a host without one: it logs a warning and stores nothing.
NullWorkflowWakeOutboxclassA wake outbox that stores nothing.
NullWorkflowWakeOutboxReceiverclassA wake outbox receiver that never has a notification.
WorkflowSignalBusBridgeclassThe signal bus over the signal store and driver: it stores a signal, then wakes the consumers as the driver’s dispatch mode says, and receives through the driver.
WorkflowSignalCommandDispatcherclassRuns signal commands through the workflow runtime service.
WorkflowSignalEnvelopeSerializerclassSerializes signal envelopes as JSON with the web defaults (camel-case names); payload keys compare ignoring case.
WorkflowSignalProcessorclassApplies the engine’s signals: a timer, retry, external signal or child completion resumes its instance, and an internal continue starts the next workflow; another type raises NotSupportedException.

IWorkflowSignalCommandDispatcher interface

public interface IWorkflowSignalCommandDispatcher

Runs the start and resume commands that arrive as signals.

DispatchResumeWorkflowAsync(WorkflowSignalEnvelope, CancellationToken) method

Task DispatchResumeWorkflowAsync(WorkflowSignalEnvelope envelope, CancellationToken cancellationToken = default)

Applies a signal to its instance.

Parameters

Returns

A task that completes when the signal is handled.

DispatchStartWorkflowAsync(StartWorkflowRequest, CancellationToken) method

Task DispatchStartWorkflowAsync(StartWorkflowRequest request, CancellationToken cancellationToken = default)

Starts a workflow.

Parameters

Returns

A task that completes when the start has run.

NullWorkflowSignalBus class

public sealed class NullWorkflowSignalBus : IWorkflowSignalBus

The signal bus of a host without signaling: every call raises NotSupportedException.

NullWorkflowSignalBus() constructor

public NullWorkflowSignalBus()

Creates an instance of NullWorkflowSignalBus.

PublishAsync(WorkflowSignalEnvelope, CancellationToken) method

public Task PublishAsync(WorkflowSignalEnvelope envelope, CancellationToken cancellationToken = default)

Stores a signal for delivery.

Parameters

Returns

A task that completes when the signal is stored.

PublishDeadLetterAsync(WorkflowSignalEnvelope, CancellationToken) method

public Task PublishDeadLetterAsync(WorkflowSignalEnvelope envelope, CancellationToken cancellationToken = default)

Stores a signal that could not be processed as a dead letter.

Parameters

Returns

A task that completes when the signal is stored.

ReceiveAsync(string, CancellationToken) method

public Task<IWorkflowSignalLease?> ReceiveAsync(string consumerName, CancellationToken cancellationToken = default)

Waits for a signal to claim.

Parameters

Returns

The lease of the claimed signal, or null when none arrives in time.

NullWorkflowSignalClaimStore class

public sealed class NullWorkflowSignalClaimStore : IWorkflowSignalClaimStore

A claim store that never has a signal to claim.

NullWorkflowSignalClaimStore() constructor

public NullWorkflowSignalClaimStore()

Creates an instance of NullWorkflowSignalClaimStore.

TryClaimAsync(string, CancellationToken) method

public Task<IWorkflowSignalLease?> TryClaimAsync(string consumerName, CancellationToken cancellationToken = default)

Claims one available signal for a consumer.

Parameters

Returns

The lease of the claimed signal, or null when none is available.

NullWorkflowSignalDeadLetterStore class

public sealed class NullWorkflowSignalDeadLetterStore : IWorkflowSignalDeadLetterStore

The dead letter store used when the backend registers none: every call raises NotSupportedException.

NullWorkflowSignalDeadLetterStore() constructor

public NullWorkflowSignalDeadLetterStore()

Creates an instance of NullWorkflowSignalDeadLetterStore.

GetMessagesAsync(WorkflowSignalDeadLettersGetRequest, CancellationToken) method

public Task<WorkflowSignalDeadLettersGetResponse> GetMessagesAsync(WorkflowSignalDeadLettersGetRequest request, CancellationToken cancellationToken = default)

Lists the dead-lettered signals.

Parameters

Returns

A page of dead letters.

ReplayAsync(WorkflowSignalDeadLetterReplayRequest, CancellationToken) method

public Task<WorkflowSignalDeadLetterReplayResponse> ReplayAsync(WorkflowSignalDeadLetterReplayRequest request, CancellationToken cancellationToken = default)

Puts a dead letter back on the signal queue.

Parameters

Returns

The outcome.

NullWorkflowSignalDriver class

public sealed class NullWorkflowSignalDriver : IWorkflowSignalDriver

The signal driver None: it sends no wake and has no signal to receive.

NullWorkflowSignalDriver() constructor

public NullWorkflowSignalDriver()

Creates an instance of NullWorkflowSignalDriver.

DispatchMode property

public WorkflowSignalDriverDispatchMode DispatchMode { get; }

When the engine tells the driver that a signal is available.

DriverName property

public string DriverName { get; }

The driver name, as WorkflowSignalDriver:Provider selects it.

NotifySignalAvailableAsync(WorkflowSignalWakeNotification, CancellationToken) method

public Task NotifySignalAvailableAsync(WorkflowSignalWakeNotification notification, CancellationToken cancellationToken = default)

Tells the consumers that a signal is available.

Parameters

Returns

A task that completes when the notification is sent.

ReceiveAsync(string, CancellationToken) method

public Task<IWorkflowSignalLease?> ReceiveAsync(string consumerName, CancellationToken cancellationToken = default)

Waits up to the driver’s blocking wait for a signal to claim.

Parameters

Returns

The lease of the claimed signal, or null when none arrives in time.

NullWorkflowSignalStore class

public sealed class NullWorkflowSignalStore : IWorkflowSignalStore

The signal store of a host without one: it logs a warning and stores nothing.

Parameters

NullWorkflowSignalStore(ILogger<NullWorkflowSignalStore>) constructor

public NullWorkflowSignalStore(ILogger<NullWorkflowSignalStore> logger)

The signal store of a host without one: it logs a warning and stores nothing.

Parameters

PublishAsync(WorkflowSignalEnvelope, CancellationToken) method

public Task PublishAsync(WorkflowSignalEnvelope envelope, CancellationToken cancellationToken = default)

Stores a signal for delivery.

Parameters

Returns

A task that completes when the signal is stored.

PublishDeadLetterAsync(WorkflowSignalEnvelope, CancellationToken) method

public Task PublishDeadLetterAsync(WorkflowSignalEnvelope envelope, CancellationToken cancellationToken = default)

Stores a signal that could not be processed as a dead letter.

Parameters

Returns

A task that completes when the signal is stored.

NullWorkflowWakeOutbox class

public sealed class NullWorkflowWakeOutbox : IWorkflowWakeOutbox

A wake outbox that stores nothing.

NullWorkflowWakeOutbox() constructor

public NullWorkflowWakeOutbox()

Creates an instance of NullWorkflowWakeOutbox.

EnqueueAsync(WorkflowSignalWakeNotification, CancellationToken) method

public Task EnqueueAsync(WorkflowSignalWakeNotification notification, CancellationToken cancellationToken = default)

Writes a wake notification to the outbox.

Parameters

Returns

A task that completes when the notification is written.

NullWorkflowWakeOutboxReceiver class

public sealed class NullWorkflowWakeOutboxReceiver : IWorkflowWakeOutboxReceiver

A wake outbox receiver that never has a notification.

NullWorkflowWakeOutboxReceiver() constructor

public NullWorkflowWakeOutboxReceiver()

Creates an instance of NullWorkflowWakeOutboxReceiver.

ReceiveAsync(string, CancellationToken) method

public Task<IWorkflowWakeOutboxLease?> ReceiveAsync(string consumerName, CancellationToken cancellationToken = default)

Claims one wake notification of the outbox for a consumer.

Parameters

Returns

The lease of the notification, or null when there is none.

WorkflowSignalBusBridge class

public sealed class WorkflowSignalBusBridge : IWorkflowSignalBus

The signal bus over the signal store and driver: it stores a signal, then wakes the consumers as the driver’s dispatch mode says, and receives through the driver.

Parameters

WorkflowSignalBusBridge(IWorkflowSignalStore, IWorkflowSignalDriver, IWorkflowWakeOutbox, IWorkflowMutationScopeAccessor) constructor

public WorkflowSignalBusBridge(IWorkflowSignalStore signalStore, IWorkflowSignalDriver signalDriver, IWorkflowWakeOutbox wakeOutbox, IWorkflowMutationScopeAccessor mutationScopeAccessor)

The signal bus over the signal store and driver: it stores a signal, then wakes the consumers as the driver’s dispatch mode says, and receives through the driver.

Parameters

PublishAsync(WorkflowSignalEnvelope, CancellationToken) method

public Task PublishAsync(WorkflowSignalEnvelope envelope, CancellationToken cancellationToken = default)

Stores a signal for delivery.

Parameters

Returns

A task that completes when the signal is stored.

PublishDeadLetterAsync(WorkflowSignalEnvelope, CancellationToken) method

public Task PublishDeadLetterAsync(WorkflowSignalEnvelope envelope, CancellationToken cancellationToken = default)

Stores a signal that could not be processed as a dead letter.

Parameters

Returns

A task that completes when the signal is stored.

ReceiveAsync(string, CancellationToken) method

public Task<IWorkflowSignalLease?> ReceiveAsync(string consumerName, CancellationToken cancellationToken = default)

Waits for a signal to claim.

Parameters

Returns

The lease of the claimed signal, or null when none arrives in time.

WorkflowSignalCommandDispatcher class

public sealed class WorkflowSignalCommandDispatcher : IWorkflowSignalCommandDispatcher

Runs signal commands through the workflow runtime service.

Parameters

WorkflowSignalCommandDispatcher(WorkflowRuntimeService) constructor

public WorkflowSignalCommandDispatcher(WorkflowRuntimeService workflowRuntimeService)

Runs signal commands through the workflow runtime service.

Parameters

DispatchResumeWorkflowAsync(WorkflowSignalEnvelope, CancellationToken) method

public Task DispatchResumeWorkflowAsync(WorkflowSignalEnvelope envelope, CancellationToken cancellationToken = default)

Applies a signal to its instance.

Parameters

Returns

A task that completes when the signal is handled.

DispatchStartWorkflowAsync(StartWorkflowRequest, CancellationToken) method

public Task DispatchStartWorkflowAsync(StartWorkflowRequest request, CancellationToken cancellationToken = default)

Starts a workflow.

Parameters

Returns

A task that completes when the start has run.

WorkflowSignalEnvelopeSerializer class

public sealed class WorkflowSignalEnvelopeSerializer

Serializes signal envelopes as JSON with the web defaults (camel-case names); payload keys compare ignoring case.

WorkflowSignalEnvelopeSerializer() constructor

public WorkflowSignalEnvelopeSerializer()

Creates an instance of WorkflowSignalEnvelopeSerializer.

Deserialize(byte[]) method

public WorkflowSignalEnvelope Deserialize(byte[] payload)

Deserializes an envelope.

Parameters

Returns

The envelope.

Exceptions

Serialize(WorkflowSignalEnvelope) method

public byte[] Serialize(WorkflowSignalEnvelope envelope)

Serializes an envelope.

Parameters

Returns

The UTF-8 JSON.

WorkflowSignalProcessor class

public sealed class WorkflowSignalProcessor : IWorkflowSignalProcessor

Applies the engine’s signals: a timer, retry, external signal or child completion resumes its instance, and an internal continue starts the next workflow; another type raises NotSupportedException.

Parameters

WorkflowSignalProcessor(IWorkflowSignalCommandDispatcher, IWorkflowCallerIdentityAccessor) constructor

public WorkflowSignalProcessor(IWorkflowSignalCommandDispatcher commandDispatcher, IWorkflowCallerIdentityAccessor callerIdentity)

Applies the engine’s signals: a timer, retry, external signal or child completion resumes its instance, and an internal continue starts the next workflow; another type raises NotSupportedException.

Parameters

ProcessAsync(WorkflowSignalEnvelope, CancellationToken) method

public Task ProcessAsync(WorkflowSignalEnvelope envelope, CancellationToken cancellationToken = default)

Applies a signal to its instance.

Parameters

Returns

A task that completes when the signal is applied.