StellaOps.Workflow.Engine
Workflow engine: definition deployment, instance lifecycle, signal-driven task transitions, dead-letter handling and retention.
| Package | StellaOps.Workflow.Engine |
| Component | Workflow |
| Licence | BUSL-1.1 (Workflow licence) |
| Package kind | Library |
| Target framework | net10.0 |
To add the package to a project, see Installing Stella Ops packages.
Namespaces
StellaOps.Workflow.Engine.Authorization namespace
| Type | Kind | Description |
|---|---|---|
WorkflowTaskAuthorizationService | class | Decides 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
permissionEvaluator: The evaluator.
WorkflowTaskAuthorizationService(IWorkflowAssignmentPermissionEvaluator) constructor
public WorkflowTaskAuthorizationService(IWorkflowAssignmentPermissionEvaluator permissionEvaluator)
Decides whether an actor may act on a task, through the registered assignment permission evaluator.
Parameters
permissionEvaluator: The evaluator.
Evaluate(WorkflowAssignmentPermissionContext) method
public WorkflowAssignmentPermissionDecision Evaluate(WorkflowAssignmentPermissionContext context)
Evaluates an assignment permission.
Parameters
context: The actor, the task and the action.
Returns
The decision.
StellaOps.Workflow.Engine.Children namespace
| Type | Kind | Description |
|---|---|---|
WorkflowChildExecutionService | class | Records child workflow links: their start and completion, each with an outbox message for the parent, and their cancellation. |
WorkflowChildLinkResult | record | The link between a parent step and its child. |
WorkflowCompleteChildRequest | record | A finished child workflow and its result. |
WorkflowStartChildRequest | record | A 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
store: The child link store.timeProvider: The clock.
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
store: The child link store.timeProvider: The clock.
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
linkId: The link.expectedVersion: The link version the caller read.cancellationToken: Cancels the operation.
Returns
The link.
Exceptions
WorkflowStoreConcurrencyException: The link version differs.InvalidOperationException: The link does not exist.
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
request: The child result.cancellationToken: Cancels the operation.
Returns
The link.
Exceptions
InvalidOperationException: The hash does not match the result, the link does not exist or names another child, a completed link has another result, or the link was canceled.
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
request: The child start.cancellationToken: Cancels the operation.
Returns
The link.
Exceptions
ArgumentException: An identifier is missing, or the request hash is not 64 hexadecimal characters.InvalidOperationException: A start recorded under the link names another child or request hash.
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
| Type | Kind | Description |
|---|---|---|
ConstantsClass | class | String values the engine stores and compares. |
ConstantsClass.MapPolicies | class | The fan-in and failure policies of a map step. |
ConstantsClass.RetryBackoffKinds | class | How the delay between retries grows. |
MessageKeys | class | The message ids of the engine’s business errors. |
WorkflowInstanceStatuses | class | The statuses of a workflow instance. |
WorkflowTaskEventTypes | class | The event types of a human task’s history. |
WorkflowTaskStatuses | class | The 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
| Type | Kind | Description |
|---|---|---|
WorkflowRuntimeDefinitionStore | class | 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. |
WorkflowRuntimeExecutionHandlerFactory | class | Creates 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
workflowRegistrationCatalog: The registered workflows.workflowModuleCatalog: The installed function modules, for the module check.workflowFunctionCatalog: The function catalog, for compilation and validation.externalActivityRegistry: The external activity registry, for validation; none when not set.
GetDefinition(string, string) method
public WorkflowRuntimeDefinition? GetDefinition(string workflowName, string? workflowVersion = null)
Finds a runtime definition.
Parameters
workflowName: The workflow name.workflowVersion: The version; the latest when not set.
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
workflowName: The workflow name.workflowVersion: The version; the latest when not set.
Returns
The definition.
Exceptions
InvalidOperationException: No such definition is registered.
WorkflowRuntimeExecutionHandlerFactory class
public sealed class WorkflowRuntimeExecutionHandlerFactory : IWorkflowRuntimeExecutionHandlerFactory
Creates the execution handlers of runtime definitions.
Parameters
serviceProvider: Resolves custom handlers.
WorkflowRuntimeExecutionHandlerFactory(IServiceProvider) constructor
public WorkflowRuntimeExecutionHandlerFactory(IServiceProvider serviceProvider)
Creates the execution handlers of runtime definitions.
Parameters
serviceProvider: Resolves custom handlers.
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
definition: The runtime definition.
Returns
The handler, or null.
StellaOps.Workflow.Engine.Durability namespace
| Type | Kind | Description |
|---|---|---|
IWorkflowDurableStartAdmissionPolicy | interface | Decides whether a durable start may run now. |
IWorkflowOutboxMessagePublisher | interface | Sends outbox messages over a transport. |
IWorkflowServiceAudienceResolver | interface | Maps an authenticated service subject to its service audience. |
WorkflowActivityCompletionMessageHandler | class | Handles WorkflowExternalActivityLanes.Completed: records the completion and resumes the waiting step (or map item) when it can resume. |
WorkflowDefinitionStartAdmissionPolicy | class | Admits a durable start only for a permitted, managed and active definition whose content hash matches the request. |
WorkflowDeliveryDisposition | enum | What the engine decided about one delivered durable message. |
WorkflowDurableMaintenanceOptions | class | Options of the durable maintenance tasks, bound from WorkflowMaintenance. |
WorkflowDurableMaintenanceService | class | The engine’s periodic durable maintenance: the execution integrity check and the outbox/inbox compaction. |
WorkflowDurableMessageTypes | class | Message types of the durable start protocol; an integration transport publishes and consumes them by these names. |
WorkflowDurableMessagingServiceCollectionExtensions | class | Registers the durable messaging of the engine. |
WorkflowDurableOutboxMessage | record | A durable start message waiting in the outbox. |
WorkflowDurableRootContinuationService | class | Continues a durable start after its start decision committed: checks the stored receipt and the digest of the stored request, then runs the start. |
WorkflowDurableStartAudience | class | Who may call the durable start lane. |
WorkflowDurableStartOptions | class | The workflow definitions a service may start durably (WorkflowDurableStart). |
WorkflowDurableStartService | class | Decides durable starts and prestart terminal commands once, each in one change scope with its outbox messages. |
WorkflowExactReplayConflictException | class | Raised when a replay carries different content under an identity already recorded. |
WorkflowOutboxBatchResult | record | The counts of one outbox drain. |
WorkflowOutboxDelivery | record | One outbox row as a message: the lane (channel), its id, the canonical body and the contract headers. |
WorkflowOutboxDispatcher | class | 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. |
WorkflowOutboxDispatcherHostedService | class | Runs WorkflowOutboxDispatchercontinuously: quickly while rows are ready, slowly when idle. |
WorkflowRegisteredSignalDisposition | enum | How a raised signal was handled. |
WorkflowRegisteredSignalOptions | class | The registered signals and the service audiences that may use them (WorkflowRegisteredSignals). |
WorkflowRegisteredSignalRaiseRequest | record | A signal raised for a registered wait. |
WorkflowRegisteredSignalRaiseResponse | record | How a raised signal was handled. |
WorkflowRegisteredSignalService | class | 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. |
WorkflowRegisteredSignalWaitRequest | record | A wait to register, with its deadline timer. |
WorkflowRegisteredSignalWaitResult | record | The state of a registered wait. |
WorkflowRegisteredWaitOutcome | enum | The state of a registered wait. |
WorkflowRootAlreadyStartedException | class | Raised when an execution already has a durable root. |
WorkflowRootContinuationMessageHandler | class | Handles WorkflowDurableMessageTypes.RootContinuation. |
WorkflowRootContinuationV1 | record | Continues a durable root after its start committed. |
WorkflowServiceAudienceResolver | class | Maps subjects to audiences with ServiceSubjects of the registered signal options. |
WorkflowStartAdmissionDecision | record | The admission decision on a durable start. |
WorkflowStartAdmissionDisposition | enum | Whether a durable start may run now. |
WorkflowStartExecutionMessageHandler | class | Handles WorkflowDurableMessageTypes.StartExecution. |
WorkflowStartNotReadyException | class | Raised 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
request: The start request.cancellationToken: Cancels the operation.
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
message: The message.cancellationToken: Cancels the operation.
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
authenticatedSubject: The authenticated subject.
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
body: The message body.cancellationToken: Cancels the operation.
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
definitionStore: The definition store.options: The durable start options; theirDefinitionsname the permitted definitions.
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
definitionStore: The definition store.options: The durable start options; theirDefinitionsname the permitted definitions.
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
request: The start request.cancellationToken: Cancels the operation.
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).
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
EventId: The message.MessageType: The message type.AggregateId: The aggregate the message belongs to.PayloadSha256: The SHA-256 of the payload.PayloadJson: The payload, as JSON.DeliveryAttempts: The delivery attempts so far.
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
EventId: The message.MessageType: The message type.AggregateId: The aggregate the message belongs to.PayloadSha256: The SHA-256 of the payload.PayloadJson: The payload, as JSON.DeliveryAttempts: The delivery attempts so far.
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
store: The durable start store.runtimeService: Runs the start.
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
store: The durable start store.runtimeService: Runs the start.
ContinueAsync(WorkflowRootContinuationV1, CancellationToken) method
public Task<bool> ContinueAsync(WorkflowRootContinuationV1 continuation, CancellationToken cancellationToken = default)
Runs the start of the durable root a continuation names.
Parameters
continuation: The continuation.cancellationToken: Cancels the operation.
Returns
true when the start ran; false when the execution already moved past the expected version.
Exceptions
WorkflowStartNotReadyException: The receipt or its stored request does not exist yet.WorkflowExactReplayConflictException: The continuation or the stored request does not match the receipt.
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
store: The durable start store.outboxStore: The outbox store.mutationCoordinator: Begins the change scopes.admissionPolicy: Admits the starts.
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
store: The durable start store.outboxStore: The outbox store.mutationCoordinator: Begins the change scopes.admissionPolicy: Admits the starts.
GetPendingOutboxAsync(int, CancellationToken) method
public Task<IReadOnlyCollection<WorkflowDurableOutboxMessage>> GetPendingOutboxAsync(int limit, CancellationToken cancellationToken = default)
Returns the durable outbox messages ready to publish.
Parameters
limit: The most messages to return, from 1 to 500.cancellationToken: Cancels the operation.
Returns
The messages.
Exceptions
ArgumentOutOfRangeException: The limit is outside 1 to 500.
MarkOutboxPublishedAsync(string, CancellationToken) method
public Task<bool> MarkOutboxPublishedAsync(string eventId, CancellationToken cancellationToken = default)
Marks a ready durable outbox message published.
Parameters
eventId: The message.cancellationToken: Cancels the operation.
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
command: The terminal command.cancellationToken: Cancels the operation.
Returns
The acknowledgement.
Exceptions
WorkflowRootAlreadyStartedException: The root already started.WorkflowExactReplayConflictException: A recorded command or receipt does not match.
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
request: The start request.cancellationToken: Cancels the operation.
Returns
The start result.
Exceptions
WorkflowStartNotReadyException: The admission policy reports that the definition is not ready yet.WorkflowExactReplayConflictException: A decision recorded under the request id does not match the request.
WorkflowExactReplayConflictException class
public sealed class WorkflowExactReplayConflictException : InvalidOperationException
Raised when a replay carries different content under an identity already recorded.
Parameters
identity: The identity.
WorkflowExactReplayConflictException(string) constructor
public WorkflowExactReplayConflictException(string identity)
Raised when a replay carries different content under an identity already recorded.
Parameters
identity: The identity.
Identity property
public string Identity { get; }
The identity.
WorkflowOutboxBatchResult record
public sealed record WorkflowOutboxBatchResult
The counts of one outbox drain.
Parameters
Attempted: The messages tried.Published: The messages the transport confirmed.Deferred: The messages left ready for a later drain.
WorkflowOutboxBatchResult(int, int, int) constructor
public WorkflowOutboxBatchResult(int Attempted, int Published, int Deferred)
The counts of one outbox drain.
Parameters
Attempted: The messages tried.Published: The messages the transport confirmed.Deferred: The messages left ready for a later drain.
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
Channel: The lane.MessageId: The message id.Body: The canonical body.ContentType: The media type of the body.Headers: The contract headers.
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
Channel: The lane.MessageId: The message id.Body: The canonical body.ContentType: The media type of the body.Headers: The contract headers.
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
cancellationToken: Cancels the operation.
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.
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
store: The registered signal store.mutationCoordinator: Begins the change scopes.options: The registered signals: each signal code with the service audience allowed to raise it.
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
store: The registered signal store.mutationCoordinator: Begins the change scopes.options: The registered signals: each signal code with the service audience allowed to raise it.
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
timerId: The timer.now: The current time.cancellationToken: Cancels the operation.
Returns
The wait and its outcome.
Exceptions
KeyNotFoundException: The timer does not exist.
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
request: The signal.authenticatedServiceAudience: The service audience of the authenticated caller.cancellationToken: Cancels the operation.
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
request: The signal.authenticatedServiceAudience: The service audience of the authenticated caller.cancellationToken: Cancels the operation.
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
request: The wait.cancellationToken: Cancels the operation.
Returns
The wait and its outcome.
Exceptions
ArgumentException: The expected version is below 1, the deadline is not a UTC time after the epoch, or the signal code and audience are not registered.WorkflowExactReplayConflictException: A wait registered under the id differs.
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.
| Value | Description |
|---|---|
WAITING = 0 | The wait is open. |
SIGNAL_WON = 1 | A signal resolved the wait. |
DEADLINE_WON = 2 | The deadline timer resolved the wait. |
WorkflowRootAlreadyStartedException class
public sealed class WorkflowRootAlreadyStartedException : InvalidOperationException
Raised when an execution already has a durable root.
Parameters
workflowExecutionId: The execution.
WorkflowRootAlreadyStartedException(string) constructor
public WorkflowRootAlreadyStartedException(string workflowExecutionId)
Raised when an execution already has a durable root.
Parameters
workflowExecutionId: The execution.
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
body: The message body.messageId: The transport message id, for the log.cancellationToken: Cancels the operation.
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
StartRequestId: The start request.WorkflowExecutionId: The execution.RootScopeExecutionId: The root scope.ExpectedExecutionVersion: The execution version the continuation expects.
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
StartRequestId: The start request.WorkflowExecutionId: The execution.RootScopeExecutionId: The root scope.ExpectedExecutionVersion: The execution version the continuation expects.
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
ContractValidationException: A field breaks its rule.
WorkflowServiceAudienceResolver class
public sealed class WorkflowServiceAudienceResolver : IWorkflowServiceAudienceResolver
Maps subjects to audiences with ServiceSubjects of the registered signal options.
Parameters
options: The registered signal options.
WorkflowServiceAudienceResolver(IOptions<WorkflowRegisteredSignalOptions>) constructor
public WorkflowServiceAudienceResolver(IOptions<WorkflowRegisteredSignalOptions> options)
Maps subjects to audiences with ServiceSubjects of the registered signal options.
Parameters
options: The registered signal options.
ResolveAudience(string) method
public string? ResolveAudience(string? authenticatedSubject)
Returns the audience of a subject.
Parameters
authenticatedSubject: The authenticated subject.
Returns
The audience, or null when the subject has none.
WorkflowStartAdmissionDecision record
public sealed record WorkflowStartAdmissionDecision
The admission decision on a durable start.
Parameters
Disposition: The decision.SafeCode: The safe code of a refusal or a delay.
WorkflowStartAdmissionDecision(WorkflowStartAdmissionDisposition, string) constructor
public WorkflowStartAdmissionDecision(WorkflowStartAdmissionDisposition Disposition, string? SafeCode = null)
The admission decision on a durable start.
Parameters
Disposition: The decision.SafeCode: The safe code of a refusal or a delay.
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.
| Value | Description |
|---|---|
Ready = 0 | The start may run. |
TransientNotReady = 1 | The start cannot run yet; retry later. |
PermanentReject = 2 | The 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
body: The message body.cancellationToken: Cancels the operation.
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
safeCode: The safe code.
WorkflowStartNotReadyException(string) constructor
public WorkflowStartNotReadyException(string safeCode)
Raised when a durable start cannot run yet; the start is retried.
Parameters
safeCode: The safe code.
SafeCode property
public string SafeCode { get; }
The safe code.
StellaOps.Workflow.Engine.Exceptions namespace
| Type | Kind | Description |
|---|---|---|
WorkflowEngineError | record | A business error of the engine. |
WorkflowEngineErrors | class | Creates the engine’s business errors. |
WorkflowEngineException | class | The 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
Code: The HTTP status.MessageId: The message id; seeMessageKeys.Arguments: The interpolation arguments.InnerException: The cause, when there is one.
WorkflowEngineError(int, string, object[], Exception) constructor
public WorkflowEngineError(int Code, string MessageId, object[] Arguments, Exception? InnerException)
A business error of the engine.
Parameters
Code: The HTTP status.MessageId: The message id; seeMessageKeys.Arguments: The interpolation arguments.InnerException: The cause, when there is one.
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
innerException: The cause.messageId: The message id; seeMessageKeys.args: The interpolation arguments.
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
code: The HTTP status.messageId: The message id; seeMessageKeys.args: The interpolation arguments.
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
messageId: The message id; seeMessageKeys.args: The interpolation arguments.
Returns
The exception to throw.
DefaultFactory(WorkflowEngineError) method
public static Exception DefaultFactory(WorkflowEngineError error)
Creates a WorkflowEngineException.
Parameters
error: The error.
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
innerException: The cause.messageId: The message id; seeMessageKeys.
WorkflowEngineException(Exception, string, params object[]) constructor
public WorkflowEngineException(Exception innerException, string messageId, params object[] args)
Creates the exception with status 400.
Parameters
innerException: The cause.messageId: The message id; seeMessageKeys.args: The interpolation arguments.
WorkflowEngineException(int, string) constructor
public WorkflowEngineException(int code, string messageId)
Creates the exception.
Parameters
code: The HTTP status.messageId: The message id; seeMessageKeys.
WorkflowEngineException(int, string, params object[]) constructor
public WorkflowEngineException(int code, string messageId, params object[] args)
Creates the exception.
Parameters
code: The HTTP status.messageId: The message id; seeMessageKeys.args: The interpolation arguments.
WorkflowEngineException(string) constructor
public WorkflowEngineException(string messageId)
Creates the exception with status 400.
Parameters
messageId: The message id; seeMessageKeys.
WorkflowEngineException(string, params object[]) constructor
public WorkflowEngineException(string messageId, params object[] args)
Creates the exception with status 400.
Parameters
messageId: The message id; seeMessageKeys.args: The interpolation arguments.
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
| Type | Kind | Description |
|---|---|---|
CanonicalWorkflowExecutionHandler | class | Runs a workflow from its canonical runtime definition: starts, task completions, signal resumes and map items. |
ConfiguredWorkflowRuntimeOrchestrator | class | 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. |
WorkflowEngineRuntimeProvider | class | The 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
runtimeDefinition: The runtime definition.endpointTransport: The endpoint transport.rabbitTransport: The RabbitMQ transport.graphqlTransport: The GraphQL transport.httpTransport: The HTTP transport.workflowFunctionRuntime: Evaluates the expression functions.workflowRegistrationCatalog: The registered workflows, for child workflows.workflowRuntimeDefinitionStore: The runtime definitions, for child and parent workflows.workflowRuntimeExecutionHandlerFactory: Creates the handlers of child and parent workflows.
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
runtimeDefinition: The runtime definition.endpointTransport: The endpoint transport.rabbitTransport: The RabbitMQ transport.graphqlTransport: The GraphQL transport.httpTransport: The HTTP transport.workflowFunctionRuntime: Evaluates the expression functions.workflowRegistrationCatalog: The registered workflows, for child workflows.workflowRuntimeDefinitionStore: The runtime definitions, for child and parent workflows.workflowRuntimeExecutionHandlerFactory: Creates the handlers of child and parent workflows.
CompleteTaskAsync(WorkflowTaskExecutionContext, CancellationToken) method
public Task<WorkflowTaskCompletionPlan> CompleteTaskAsync(WorkflowTaskExecutionContext context, CancellationToken cancellationToken = default)
Plans the completion of a task.
Parameters
context: The task context.cancellationToken: Cancels the operation.
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
request: The item.cancellationToken: Cancels the operation.
Returns
What happens next.
StartAsync(WorkflowStartExecutionContext, CancellationToken) method
public Task<WorkflowStartExecutionPlan> StartAsync(WorkflowStartExecutionContext context, CancellationToken cancellationToken = default)
Plans the start of an instance.
Parameters
context: The start context.cancellationToken: Cancels the operation.
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
runtimeProviders: The registered providers; names compare ignoring case, and for a repeated name the last one wins.runtimeOptions: The runtime options: the default provider and the enabled providers.
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
runtimeProviders: The registered providers; names compare ignoring case, and for a repeated name the last one wins.runtimeOptions: The runtime options: the default provider and the enabled providers.
CompleteAsync(WorkflowRegistration, WorkflowDefinitionDescriptor, WorkflowTaskExecutionContext, CancellationToken) method
public Task<WorkflowRuntimeExecutionResult> CompleteAsync(WorkflowRegistration registration, WorkflowDefinitionDescriptor definition, WorkflowTaskExecutionContext context, CancellationToken cancellationToken = default)
Completes a task.
Parameters
registration: The workflow registration.definition: The definition descriptor.context: The task context.cancellationToken: Cancels the operation.
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
registration: The workflow registration.definition: The definition descriptor.context: The signal context.cancellationToken: Cancels the operation.
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
registration: The workflow registration.definition: The definition descriptor.businessReference: The business reference.request: The start request.startRequest: The typed start request.cancellationToken: Cancels the operation.
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
workflowRuntimeDefinitionStore: The runtime definitions.workflowRuntimeExecutionHandlerFactory: Creates the execution handlers.
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
workflowRuntimeDefinitionStore: The runtime definitions.workflowRuntimeExecutionHandlerFactory: Creates the execution handlers.
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
registration: The workflow registration.definition: The definition descriptor.context: The task context.cancellationToken: Cancels the operation.
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
registration: The workflow registration.definition: The definition descriptor.context: The signal context.cancellationToken: Cancels the operation.
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
registration: The workflow registration.definition: The definition descriptor.businessReference: The business reference.request: The start request.startRequest: The typed start request.cancellationToken: Cancels the operation.
Returns
The outcome.
StellaOps.Workflow.Engine.ExternalActivities namespace
| Type | Kind | Description |
|---|---|---|
ConstantsClass | class | The states, dispositions, event types and stop values of external activities. |
WorkflowActivityCancelOutboxMessage | record | A cancel request to publish on a cancel lane. |
WorkflowActivityControlService | class | Controls external activity steps: classifies failures for retry, retries steps, records continuations, reprocesses scopes, stops activities and publishes their cancel messages. |
WorkflowActivityFailureRequest | record | A failed attempt to decide a retry for. |
WorkflowActivityReprocessScopeRequest | record | An operator request to run a scope again. |
WorkflowActivityReprocessScopeResult | record | The new occurrence of a reprocessed scope. |
WorkflowActivityRetryDecision | record | Whether and when a failed step is retried. |
WorkflowActivityRetryStepRequest | record | An operator request to retry a step now. |
WorkflowActivityStopRequest | record | A request to stop the activities of a target: a cancel or a deadline. |
WorkflowActivityStopResult | record | The outcome of a stop. |
WorkflowContinuationRegistrationRequest | record | A continuation an attempt reported, to register for the next attempt. |
WorkflowExternalActivityCompletionDecision | record | The outcome of a completion: the delivery disposition, and the signal that resumes the waiting step when there is one. |
WorkflowExternalActivityCompletionRequest | record | A completion received on the completed lane. |
WorkflowExternalActivityCompletionResult | record | How a completion was handled. |
WorkflowExternalActivityCompletionService | class | 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. |
WorkflowExternalActivityContractKinds | class | The contract kinds of external activities. |
WorkflowExternalActivityDispatchRequest | record | An attempt to dispatch. |
WorkflowExternalActivityDispatchResult | record | A recorded dispatch. |
WorkflowExternalActivityDispatchService | class | Turns an external activity wait into a durable dispatch; the step’s evaluated request travels inline. |
WorkflowExternalActivityLanes | class | The default lanes of external activities. |
WorkflowExternalActivityOutboxMessage | record | A request to publish on an execute lane. |
WorkflowExternalActivityRegistry | class | The external activity registry of the host’s signed manifest. |
WorkflowExternalActivityRegistryEntry | record | An external activity of the manifest. |
WorkflowExternalActivityRegistryException | class | Raised when the registry manifest cannot be loaded. |
WorkflowExternalActivityRegistryHealthCheck | class | Healthy once the signed external activity registry is verified; unhealthy, with the readiness failure code, until then. |
WorkflowExternalActivityRegistryManifest | record | The signed registry manifest of a host. |
WorkflowExternalActivityRegistryOptions | class | The signed manifest of the external activities the host may run (WorkflowExternalActivityRegistry). |
WorkflowExternalActivityService | class | Records external activity dispatches and completions once, with their outbox entries. |
WorkflowExternalActivitySignalDispatcher | class | Dispatches 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
store: The external activity store.mutationCoordinator: Begins the change scopes.registry: The external activity registry; it names the cancel lanes.timeProvider: The clock.
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
store: The external activity store.mutationCoordinator: Begins the change scopes.registry: The external activity registry; it names the cancel lanes.timeProvider: The clock.
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
request: The failure.cancellationToken: Cancels the operation.
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
maxCount: The most messages to return, from 1 to 1,000.cancellationToken: Cancels the operation.
Returns
The messages.
Exceptions
ArgumentOutOfRangeException: The count is outside 1 to 1,000.
MarkCancelPublishedAsync(string, DateTimeOffset, CancellationToken) method
public Task MarkCancelPublishedAsync(string cancelId, DateTimeOffset publishedAt, CancellationToken cancellationToken = default)
Marks a cancel message published.
Parameters
cancelId: The cancel message.publishedAt: When it was published.cancellationToken: Cancels the operation.
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
request: The continuation.cancellationToken: Cancels the operation.
Returns
The continuation lineage.
Exceptions
ArgumentOutOfRangeException: The generation is not positive.InvalidOperationException: The attempt does not exist or names another execution, scope, step or completion, or a recorded continuation has another hash.
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
request: The reprocess request.cancellationToken: Cancels the operation.
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
request: The retry.cancellationToken: Cancels the operation.
Returns
The retry decision, with the dispatch.
Exceptions
WorkflowStoreConcurrencyException: The cancel fence version differs.InvalidOperationException: The step does not wait for a retry, its delay has not passed, or its prior attempt cannot be retried by an operator.
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
request: The stop request.cancellationToken: Cancels the operation.
Returns
The counts of the stop.
Exceptions
InvalidOperationException: The cancel lane of a workflow activity is not registered.
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
Disposition: The delivery disposition.ResumeSignal: The signal that resumes the waiting step or map item;nullwhen nothing resumes.
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: The delivery disposition.ResumeSignal: The signal that resumes the waiting step or map item;nullwhen nothing resumes.
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
store: The external activity store.activityService: Records the completion.mutationCoordinator: Begins the change scope; none when not set.mapCoordinator: Advances map items; needed for the completions of map items.
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
store: The external activity store.activityService: Records the completion.mutationCoordinator: Begins the change scope; none when not set.mapCoordinator: Advances map items; needed for the completions of map items.
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
completion: The completion.canonicalCompletionJson: The completion, as canonical JSON.cancellationToken: Cancels the operation.
Returns
The disposition and the resume signal.
Exceptions
InvalidOperationException: A step, an execution or a map binding the completion needs does not exist, or the step cannot resume.
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
store: The external activity store.registry: The external activity registry; its request schema describes the request.activityService: Records the dispatch.
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
store: The external activity store.registry: The external activity registry; its request schema describes the request.activityService: Records the dispatch.
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
workflowExecutionId: The execution.pendingSignal: The durable external activity plan.cancellationToken: Cancels the operation.
Returns
The dispatch.
Exceptions
InvalidOperationException: The plan is not a durable external activity dispatch, or lacks the destination, the operation or the contract version.
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
workflowExecutionId: The execution.pendingSignal: The durable external activity plan.mapItemId: The map item.retryPolicy: The retry policy of the item.absoluteDeadlineAtUtc: The deadline after which no retry runs, in UTC; none when not set.cancellationToken: Cancels the operation.
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
options: The manifest location and signature settings.
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
address: The address.
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
destinationCode: The destination.operationCode: The operation.contractVersion: The contract version.registration: The activity, when found.
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
code: The failure code.
WorkflowExternalActivityRegistryException(string, Exception) constructor
public WorkflowExternalActivityRegistryException(string code, Exception innerException)
Creates the exception with its cause.
Parameters
code: The failure code.innerException: The cause.
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
registry: The registry.
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
registry: The registry.
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
store: The external activity store.mutationCoordinator: Begins the change scopes.registry: The external activity registry; it validates the typed requests and names the lanes.
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
store: The external activity store.mutationCoordinator: Begins the change scopes.registry: The external activity registry; it validates the typed requests and names the lanes.
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
request: The completion.cancellationToken: Cancels the operation.
Returns
The completion and its disposition.
Exceptions
InvalidOperationException: A completion recorded under the event id names another attempt or has another hash.
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
request: The dispatch.cancellationToken: Cancels the operation.
Returns
The dispatch.
Exceptions
InvalidOperationException: A dispatch recorded for the attempt has another dispatch id or request hash.
GetReadyDispatchesAsync(int, CancellationToken) method
public Task<IReadOnlyList<WorkflowExternalActivityOutboxMessage>> GetReadyDispatchesAsync(int maxCount, CancellationToken cancellationToken = default)
Returns the dispatch messages ready to publish.
Parameters
maxCount: The most messages to return, from 1 to 1,000.cancellationToken: Cancels the operation.
Returns
The messages.
Exceptions
ArgumentOutOfRangeException: The count is outside 1 to 1,000.
MarkPublishedAsync(string, DateTimeOffset, CancellationToken) method
public Task MarkPublishedAsync(string dispatchId, DateTimeOffset publishedAt, CancellationToken cancellationToken = default)
Marks a dispatch message published.
Parameters
dispatchId: The dispatch.publishedAt: When it was published.cancellationToken: Cancels the operation.
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
pendingSignal: The signal.
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
| Type | Kind | Description |
|---|---|---|
WorkflowHistoryPage | record | A page of the history events of an execution. |
WorkflowHistoryService | class | Reads 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
store: The history store.
WorkflowHistoryService(IWorkflowHistoryStore) constructor
public WorkflowHistoryService(IWorkflowHistoryStore store)
Reads and compacts the history events of executions.
Parameters
store: The history store.
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
workflowExecutionId: The execution (workflow instance).throughSequence: The last sequence to delete.maxCount: The most events to delete.cancellationToken: Cancels the operation.
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
workflowExecutionId: The execution (workflow instance).afterSequence: The sequence after which events are read.maxCount: The most events, from 1 to 1000.cancellationToken: Cancels the operation.
Returns
The page.
Exceptions
ArgumentOutOfRangeException:maxCountis outside 1 to 1000.
StellaOps.Workflow.Engine.HostedServices namespace
| Type | Kind | Description |
|---|---|---|
WorkflowRetentionHostedService | class | 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). |
WorkflowSignalDeliveryAttemptTracker | class | 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. |
WorkflowSignalPumpHostedService | class | Runs WorkflowEngine:MaxConcurrentSignalHandlers signal pump workers (at least one) until the host stops. |
WorkflowSignalPumpWorker | class | Moves 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
serviceScopeFactory: Creates the scope of each run.options: Whether the job runs, and its interval.logger: Receives the diagnostics.
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
serviceScopeFactory: Creates the scope of each run.options: Whether the job runs, and its interval.logger: Receives the diagnostics.
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
worker: Processes one signal per call.aqOptions: The signal queue options.engineOptions: The worker count and the graceful shutdown timeout.logger: Receives the diagnostics.
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
worker: Processes one signal per call.aqOptions: The signal queue options.engineOptions: The worker count and the graceful shutdown timeout.logger: Receives the diagnostics.
StopAsync(CancellationToken) method
public override Task StopAsync(CancellationToken cancellationToken)
Stops the workers and waits for them up to WorkflowEngine:GracefulShutdownTimeoutSeconds.
Parameters
cancellationToken: Cancels the operation.
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
serviceScopeFactory: Creates a scope for each signal.aqOptions: The signal options;MaxDeliveryAttemptssets the delivery budget.telemetryService: Counts the pump’s work.deliveryAttemptTracker: Counts this process’s deliveries of each signal.logger: The logger.
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
serviceScopeFactory: Creates a scope for each signal.aqOptions: The signal options;MaxDeliveryAttemptssets the delivery budget.telemetryService: Counts the pump’s work.deliveryAttemptTracker: Counts this process’s deliveries of each signal.logger: The logger.
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
consumerName: The consumer.cancellationToken: Cancels the operation.
Returns
true when a signal was received; false after an empty poll.
StellaOps.Workflow.Engine.Hosting namespace
| Type | Kind | Description |
|---|---|---|
WorkflowAqOptions | class | Signal pump and queue settings (WorkflowAq). |
WorkflowEngineOptions | class | Engine-wide execution settings (WorkflowEngine). |
WorkflowRuntimeOptions | class | The 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
| Type | Kind | Description |
|---|---|---|
IWorkflowLicenceReleaseContext | interface | 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. |
InMemoryWorkflowFirstSeenLedger | class | The first-seen ledger of a host without a workflow store. |
WorkflowComponentLicenceOptions | class | Configuration of the component licence reader, section StellaOps:ComponentLicence. |
WorkflowDesignatedWorkflowQueryService | class | 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. |
WorkflowLicenceAssessor | class | 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. |
WorkflowLicenceFileReader | class | 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. |
WorkflowLicenceFiles | record | The licence records one read loaded, with the reason when they could not be read. |
WorkflowLicenceHealthCheck | class | The licence entry of the health output. |
WorkflowLicenceMetrics | class | 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. |
WorkflowLicenceMonitor | class | 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. |
WorkflowLicenceNoticeView | class | 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. |
WorkflowLicenceReleaseContext | class | 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). |
WorkflowLicenceSnapshot | record | One licence evaluation of the running engine, as the health detail, the gauge and the notice report it. |
WorkflowLicenceState | class | The 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
cancellationToken: Cancels the operation.
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
state: The licence state.meterFactory: Creates the meter; when not set, the metrics create their own meter and dispose it.
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
notice: The notice.
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
| Type | Kind | Description |
|---|---|---|
IWorkflowMapItemExecutionHandler | interface | Runs the body of a map item. |
WorkflowMapAdvanceDecision | record | Whether a completed step belongs to a map item, and the signal that resumes it. |
WorkflowMapCompletedSignalDispatcher | class | 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. |
WorkflowMapCoordinator | class | Owns normalized map materialization, bounded item dispatch and deterministic fan-in. |
WorkflowMapCreateRequest | record | A map execution to create with its items. |
WorkflowMapExecutionPlan | record | The frozen plan of a map: its workflow, bounds, policies and body. |
WorkflowMapItemExecutionDecision | record | The next step of a map item: an activity, a nested map, or its end. |
WorkflowMapItemExecutionRequest | record | A map item to run or resume. |
WorkflowMapItemExecutionState | record | The progress of a map item. |
WorkflowMapItemLease | record | A claimed map item. |
WorkflowMapItemSeed | record | An item to create in a map. |
WorkflowMapMaterializationItemPlan | record | An item of a map plan. |
WorkflowMapMaterializationPlan | record | A map to create: its plan and items. |
WorkflowMapRuntimeException | class | Raised when a map breaks a runtime rule, such as MAP_BOUND_INVALID or MAP_ITEM_LIMIT_EXCEEDED. |
WorkflowMapRuntimeService | class | Runs map executions: creates a map and its items, leases ready items to workers within the concurrency limits, and records item progress and outcomes. |
WorkflowRetryClassifier | class | 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. |
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
request: The item.cancellationToken: Cancels the operation.
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
IsMapItem: Whether the step runs for a map item.ResumeSignal: The signal that resumes the item, when there is one.
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: Whether the step runs for a map item.ResumeSignal: The signal that resumes the item, when there is one.
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
pendingSignal: The signal.
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
workflowExecutionId: The execution.pendingSignal: The map plan.runtimeState: The runtime state of the execution.cancellationToken: Cancels the operation.
Returns
The signal that completes the map step when the map is already complete; null while items run.
Exceptions
InvalidOperationException: The runtime state belongs to another execution, the root scope is missing, or the signal is not a map plan.
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
workflowExecutionId: The execution.stepExecutionId: The completed step.completionPayload: The completion payload of the step.cancellationToken: Cancels the operation.
Returns
Whether the step runs for a map item, and the resume signal.
Exceptions
InvalidOperationException: The step or its map does not exist, belongs to another execution, or its item has no active lease.
WorkflowMapCreateRequest record
public sealed record WorkflowMapCreateRequest
A map execution to create with its items.
Parameters
MapExecutionId: The map execution.WorkflowExecutionId: The execution.ScopeExecutionId: The scope of the map.StepExecutionId: The map step.FanInPolicy: The fan-in policy.FailurePolicy: The failure policy.MinimumSucceeded: The items that must succeed underMIN_SUCCEEDED.MaxConcurrency: The items in flight at once.MaxItems: The items allowed.MaxAggregateStateBytes: The size limit of the collected results, in bytes.GlobalActivityClass: The class of activities whose concurrency is limited across all maps.ExecutionPlanSha256: The SHA-256 of the map plan.ExecutionPlanJson: The map plan, as JSON.AbsoluteDeadlineAtUtc: The deadline of the map, in UTC.Items: The items.
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
MapExecutionId: The map execution.WorkflowExecutionId: The execution.ScopeExecutionId: The scope of the map.StepExecutionId: The map step.FanInPolicy: The fan-in policy.FailurePolicy: The failure policy.MinimumSucceeded: The items that must succeed underMIN_SUCCEEDED.MaxConcurrency: The items in flight at once.MaxItems: The items allowed.MaxAggregateStateBytes: The size limit of the collected results, in bytes.GlobalActivityClass: The class of activities whose concurrency is limited across all maps.ExecutionPlanSha256: The SHA-256 of the map plan.ExecutionPlanJson: The map plan, as JSON.AbsoluteDeadlineAtUtc: The deadline of the map, in UTC.Items: The items.
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
MapItemId: The map item.ItemKey: The item key.Ordinal: The position of the item.ClaimFence: The claim fence.DescriptorSha256: The SHA-256 of the descriptor.DescriptorJson: The item descriptor, as JSON.
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
MapItemId: The map item.ItemKey: The item key.Ordinal: The position of the item.ClaimFence: The claim fence.DescriptorSha256: The SHA-256 of the descriptor.DescriptorJson: The item descriptor, as JSON.
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
ItemKey: The item key.DescriptorSha256: The SHA-256 of the descriptor.DescriptorJson: The item descriptor, as JSON.
WorkflowMapItemSeed(string, string, string) constructor
public WorkflowMapItemSeed(string ItemKey, string DescriptorSha256, string DescriptorJson)
An item to create in a map.
Parameters
ItemKey: The item key.DescriptorSha256: The SHA-256 of the descriptor.DescriptorJson: The item descriptor, as JSON.
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
code: The code.
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: The code.
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
store: The map store.timeProvider: The clock.
WorkflowMapRuntimeService(IWorkflowMapStore, TimeProvider, IOptions<WorkflowRuntimeOptions>) constructor
public WorkflowMapRuntimeService(IWorkflowMapStore store, TimeProvider timeProvider, IOptions<WorkflowRuntimeOptions> options)
Creates the service.
Parameters
store: The map store.timeProvider: The clock.options: The runtime options;MaxMapConcurrencycaps the items in flight.
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
mapExecutionId: The map.claimOwner: The worker.requestedCount: The most items to lease; positive.leaseDuration: How long a lease lasts; positive.cancellationToken: Cancels the operation.
Returns
The leased items.
Exceptions
ArgumentOutOfRangeException: The count or the duration is not positive.
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
mapItemId: The map item.claimOwner: The worker that holds the lease.claimFence: The claim fence of the lease.outcome:SUCCEEDED,PARTIAL,SKIPPEDorFAILED.safeResultDescriptorJson: The result descriptor of the item, as JSON; none when not set.cancellationToken: Cancels the operation.
Returns
A task that completes when the outcome is recorded.
Exceptions
WorkflowMapRuntimeException: The outcome is not one of the four, the lease is not current, or the collected state would exceedMaxAggregateStateBytes.
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
request: The map and its items.cancellationToken: Cancels the operation.
Returns
The map.
Exceptions
WorkflowMapRuntimeException: More items thanMaxItems(MAP_ITEM_LIMIT_EXCEEDED), a repeated item key, or descriptors overMaxAggregateStateBytes.
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
mapItemId: The map item.claimOwner: The worker that holds the lease.claimFence: The claim fence of the lease.activeStepExecutionId: The running step.executionStateJson: The execution state of the item, as JSON.cancellationToken: Cancels the operation.
Returns
A task that completes when the progress is recorded.
Exceptions
WorkflowMapRuntimeException: The lease is not current (MAP_CLAIM_STALE), or the collected state would exceedMaxAggregateStateBytes.
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
policy: The retry policy.completedSemanticAttempts: The attempts made.failureCategory: The failure category.providerHint: The delay the provider asked for.deterministicJitterSeed: The seed of the deterministic jitter.
Returns
The delay, or null.
StellaOps.Workflow.Engine.Observability namespace
| Type | Kind | Description |
|---|---|---|
WorkflowMetricCatalog | class | The metric names reserved for the Workflow engine. |
WorkflowMetricLabelPolicy | class | The metric labels the engine allows, so that no metric carries an unbounded label. |
WorkflowObservability | class | The 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
labels: The labels.
Exceptions
InvalidOperationException: A label is not allowed.
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
operation: The console operation.profile: The console profile.
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
definition: The workflow definition.outcome: The outcome.
StellaOps.Workflow.Engine.Rendering namespace
| Type | Kind | Description |
|---|---|---|
WorkflowRenderGraphCompiler | class | Builds the render graph of a workflow definition: its start, steps, tasks and branches as nodes, and the flow between them as edges. |
WorkflowRenderLayoutEngineResolver | class | Selects 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
definition: The workflow definition.
Returns
The render graph.
WorkflowRenderLayoutEngineResolver class
public sealed class WorkflowRenderLayoutEngineResolver : IWorkflowRenderLayoutEngineResolver
Selects a registered layout engine by provider name, ignoring case.
Parameters
engines: The registered layout engines.options: The rendering options, with the default provider.
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
engines: The registered layout engines.options: The rendering options, with the default provider.
Resolve(string) method
public INamedWorkflowRenderGraphLayoutEngine Resolve(string? providerName = null)
Returns the registered layout engine of a provider: providerName, else WorkflowRendering:LayoutProvider, else ElkSharp.
Parameters
providerName: The provider name; the configured provider when not set.
Returns
The layout engine.
Exceptions
InvalidOperationException: No engine of that provider is registered.
StellaOps.Workflow.Engine.Scheduling namespace
| Type | Kind | Description |
|---|---|---|
NullWorkflowScheduleBus | class | The schedule bus of a host without scheduling: every call raises NotSupportedException. |
NullWorkflowSignalScheduler | class | The signal scheduler of a host without a signal store: it logs a warning and stores nothing. |
WorkflowScheduleBusBridge | class | The 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
envelope: The signal.dueAtUtc: When the signal is due, in UTC.cancellationToken: Cancels the operation.
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
logger: Receives the warnings.
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
logger: Receives the warnings.
ScheduleAsync(WorkflowSignalEnvelope, DateTime, CancellationToken) method
public Task ScheduleAsync(WorkflowSignalEnvelope envelope, DateTime dueAtUtc, CancellationToken cancellationToken = default)
Stores a signal that becomes available at dueAtUtc.
Parameters
envelope: The signal.dueAtUtc: When the signal is due, in UTC.cancellationToken: Cancels the operation.
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
signalScheduler: Stores the scheduled signals.
WorkflowScheduleBusBridge(IWorkflowSignalScheduler) constructor
public WorkflowScheduleBusBridge(IWorkflowSignalScheduler signalScheduler)
The schedule bus over the registered signal scheduler.
Parameters
signalScheduler: Stores the scheduled signals.
ScheduleAsync(WorkflowSignalEnvelope, DateTime, CancellationToken) method
public Task ScheduleAsync(WorkflowSignalEnvelope envelope, DateTime dueAtUtc, CancellationToken cancellationToken = default)
Stores a signal that becomes available at dueAtUtc.
Parameters
envelope: The signal.dueAtUtc: When the signal is due, in UTC.cancellationToken: Cancels the operation.
Returns
A task that completes when the signal is stored.
StellaOps.Workflow.Engine.Services namespace
| Type | Kind | Description |
|---|---|---|
DeclarativeWorkflowExecutionHandler<TWorkflow, TStartRequest> | class | Runs a declarative workflow class: starts, task completions and signal resumes. |
DefaultWorkflowAssignmentPermissionEvaluator | class | 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. |
GenericAssignmentPermissionEvaluator | class | A permission evaluator that recognizes configured admin roles. |
GenericAssignmentPermissionOptions | class | Options for the generic assignment permission evaluator. |
InMemoryWorkflowDefinitionStore | class | In-process definition store. |
InMemoryWorkflowHostedJobLockService | class | An in-process hosted job lock, for a single-node host. |
InMemoryWorkflowRuntimeStateStore | class | 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. |
InProcessWorkflowRuntimeOrchestrator | class | The Stella.InProcess runtime: runs the execution handler of a workflow in the calling process. |
NullWorkflowDefinitionStore | class | Unsupported definition store used only as a local/test fallback until a backend-specific store is registered. |
UnconfiguredWorkflowEndpointTransport | class | The endpoint transport used when none is configured: every call fails with an error that names the service and the route. |
UnconfiguredWorkflowGraphqlTransport | class | The GraphQL transport used when none is configured: every call fails with an error that names the target. |
UnconfiguredWorkflowHttpTransport | class | The HTTP transport used when none is configured: every call fails with an error that names the method, the target and the path. |
UnconfiguredWorkflowRabbitTransport | class | The RabbitMQ transport used when none is configured: every call fails with an error that names the exchange and the routing key. |
WorkflowBundledDefinition | struct | A workflow an assembly ships as an embedded bundled *.definition.json. |
WorkflowBundledDefinitionCoverage | record | How many of an assembly’s bundled definitions its registrations cover, and which ones they miss. |
WorkflowBundledDefinitions | class | 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. |
WorkflowCanonicalDefinitionService | class | Serves the canonical definition schema and validates definitions. |
WorkflowCanonicalJsonSchema | class | The JSON schema of canonical workflow definitions. |
WorkflowConsoleOptions | class | What the execution console shows of an instance’s state, per profile (WorkflowConsole). |
WorkflowCoreServiceCollectionExtensions | class | Registers the core services of the workflow engine. |
WorkflowDefinitionCatalog | class | The definition descriptors of the registered workflows. |
WorkflowDefinitionDeploymentService | class | Handles import, export, versioning, and activation of canonical workflow definitions. |
WorkflowDefinitionQueryService | class | Queries the workflow definitions known to the engine: bundled in the catalog and imported into the store. |
WorkflowDefinitionRenderService | class | Lays out the diagram of a registered definition. |
WorkflowDiagramService | class | Lays out workflow diagrams, with the progress of an instance when the request names one. |
WorkflowDurableServiceCollectionExtensions | class | Registers the durable engine features. |
WorkflowExecutionConsoleService | class | The execution console: lists executions and reads their resources for one profile. |
WorkflowExecutionHandlerCatalog | class | Finds the execution handler of a registered workflow: its registered handler type, else a declarative handler when the workflow is declarative. |
WorkflowFunctionCatalogService | class | Serves the function catalog. |
WorkflowMutationScopeAccessor | class | Holds the change scope of the running operation. |
WorkflowRegistrationCatalog | class | The registered workflows, ordered by name and then by version, newest first; names and versions compare ignoring case. |
WorkflowRetentionHostedJobOptions | class | The schedule of the retention job (WorkflowRetentionHostedJob), which marks stale instances and tasks and purges expired ones. |
WorkflowRetentionOptions | class | When the retention job marks an open instance stale and purges a completed one (WorkflowRetention). |
WorkflowRetentionRunResult | record | The counts of a retention run. |
WorkflowRetentionService | class | Runs the instance retention: marks stale and purges projections and runtime states. |
WorkflowRoleResolutionService | class | Computes the roles that may work a task. |
WorkflowRuntimeService | class | 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. |
WorkflowSignalDeadLetterService | class | Lists and replays dead-lettered signals. |
WorkflowSignalPumpTelemetryService | class | Counts the signal pump’s work in this process, for the pump statistics. |
WorkflowStudioDescriptor | class | Describes the workflow service to tools. |
WorkflowStudioOptions | class | Names the host and its diagram provider in the workflow service metadata. |
WorkflowTaskCreationNotifier | class | Singleton 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
TWorkflow: The workflow class.TStartRequest: The start request type.
Parameters
endpointTransport: The endpoint transport.graphqlTransport: The GraphQL transport.httpTransport: The HTTP transport.rabbitTransport: The RabbitMQ transport.workflowFunctionRuntime: Evaluates the expression functions.workflowExecutionHandlerCatalog: Finds the handlers of child and parent workflows.workflowRegistrationCatalog: The registered workflows, for child workflows.
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
TWorkflow: The workflow class.TStartRequest: The start request type.
Parameters
endpointTransport: The endpoint transport.graphqlTransport: The GraphQL transport.httpTransport: The HTTP transport.rabbitTransport: The RabbitMQ transport.workflowFunctionRuntime: Evaluates the expression functions.workflowExecutionHandlerCatalog: Finds the handlers of child and parent workflows.workflowRegistrationCatalog: The registered workflows, for child workflows.
CompleteTaskAsync(WorkflowTaskExecutionContext, CancellationToken) method
public Task<WorkflowTaskCompletionPlan> CompleteTaskAsync(WorkflowTaskExecutionContext context, CancellationToken cancellationToken = default)
Plans the completion of a task.
Parameters
context: The task context.cancellationToken: Cancels the operation.
Returns
The plan.
StartAsync(WorkflowStartExecutionContext, CancellationToken) method
public Task<WorkflowStartExecutionPlan> StartAsync(WorkflowStartExecutionContext context, CancellationToken cancellationToken = default)
Plans the start of an instance.
Parameters
context: The start context.cancellationToken: Cancels the operation.
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
context: The action and the task.
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
context: The action and the task.
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
activation: The activation.cancellationToken: Cancels the operation.
Returns
A task that completes when the version is active.
Exceptions
InvalidOperationException: The fence or the rollback rule refuses the activation; the message is theWORKFLOW_DEFINITION_*code.
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
lockName: The lock.lockOwner: The owner.cancellationToken: Cancels the operation.
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
lockName: The lock.lockOwner: The owner.acquiredOnUtc: The time, in UTC.lease: How long the lock is held.cancellationToken: Cancels the operation.
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
workflowInstanceIds: The instances.cancellationToken: Cancels the operation.
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
workflowInstanceId: The instance.cancellationToken: Cancels the operation.
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
workflowInstanceIds: The instances.cancellationToken: Cancels the operation.
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
workflowInstanceIds: The instances.updatedOnUtc: The change time, in UTC.cancellationToken: Cancels the operation.
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
state: The state.cancellationToken: Cancels the operation.
Returns
A task that completes when the state is written.
Exceptions
WorkflowRuntimeStateConcurrencyException: Another write changed the instance first.
InProcessWorkflowRuntimeOrchestrator class
public sealed class InProcessWorkflowRuntimeOrchestrator : IWorkflowRuntimeProvider
The Stella.InProcess runtime: runs the execution handler of a workflow in the calling process.
Parameters
workflowExecutionHandlerCatalog: Finds the handlers.
InProcessWorkflowRuntimeOrchestrator(IWorkflowExecutionHandlerCatalog) constructor
public InProcessWorkflowRuntimeOrchestrator(IWorkflowExecutionHandlerCatalog workflowExecutionHandlerCatalog)
The Stella.InProcess runtime: runs the execution handler of a workflow in the calling process.
Parameters
workflowExecutionHandlerCatalog: Finds the handlers.
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
registration: The workflow registration.definition: The definition descriptor.context: The task context.cancellationToken: Cancels the operation.
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
registration: The workflow registration.definition: The definition descriptor.context: The signal context.cancellationToken: Cancels the operation.
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
registration: The workflow registration.definition: The definition descriptor.businessReference: The business reference.request: The start request.startRequest: The typed start request.cancellationToken: Cancels the operation.
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
request: The endpoint request.cancellationToken: Cancels the operation.
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
request: The GraphQL request.cancellationToken: Cancels the operation.
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
request: The HTTP request.cancellationToken: Cancels the operation.
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
request: The RabbitMQ request.cancellationToken: Cancels the operation.
Returns
The response.
WorkflowBundledDefinition struct
public readonly struct WorkflowBundledDefinition : IEquatable<WorkflowBundledDefinition>
A workflow an assembly ships as an embedded bundled *.definition.json.
Parameters
WorkflowName: The workflow name.WorkflowVersion: The workflow version.
WorkflowBundledDefinition(string, string) constructor
public WorkflowBundledDefinition(string WorkflowName, string WorkflowVersion)
A workflow an assembly ships as an embedded bundled *.definition.json.
Parameters
WorkflowName: The workflow name.WorkflowVersion: The workflow version.
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
AssemblyName: The assembly.Bundled: The bundled definitions.RegisteredCount: The registrations of the assembly.Missing: The bundled definitions no registration covers.
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: The assembly.Bundled: The bundled definitions.RegisteredCount: The registrations of the assembly.Missing: The bundled definitions no registration covers.
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
workflowModuleCatalog: The installed modules.workflowFunctionCatalog: The function catalog.externalActivityRegistry: The external activity registry.
WorkflowCanonicalDefinitionService(IWorkflowModuleCatalog, IWorkflowFunctionCatalog, IWorkflowExternalActivityRegistry) constructor
public WorkflowCanonicalDefinitionService(IWorkflowModuleCatalog workflowModuleCatalog, IWorkflowFunctionCatalog workflowFunctionCatalog, IWorkflowExternalActivityRegistry externalActivityRegistry)
Serves the canonical definition schema and validates definitions.
Parameters
workflowModuleCatalog: The installed modules.workflowFunctionCatalog: The function catalog.externalActivityRegistry: The external activity registry.
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
request: The request.
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
json: The JSON.
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
workflowRegistrationCatalog: The registered workflows.
WorkflowDefinitionCatalog(IWorkflowRegistrationCatalog) constructor
public WorkflowDefinitionCatalog(IWorkflowRegistrationCatalog workflowRegistrationCatalog)
The definition descriptors of the registered workflows.
Parameters
workflowRegistrationCatalog: The registered workflows.
GetDefinition(string, string) method
public WorkflowDefinitionDescriptor? GetDefinition(string workflowName, string? workflowVersion = null)
Finds a descriptor.
Parameters
workflowName: The workflow name.workflowVersion: The version; the latest when not set.
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
request: The request.cancellationToken: Cancels the operation.
Returns
The definition.
ExportMultiAsync(WorkflowDefinitionExportMultiRequest, CancellationToken) method
public Task<WorkflowDefinitionExportMultiResponse> ExportMultiAsync(WorkflowDefinitionExportMultiRequest request, CancellationToken cancellationToken = default)
Exports a definition in a source format.
Parameters
request: The definition and format.cancellationToken: Cancels the operation.
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
request: The format and content.cancellationToken: Cancels the operation.
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
runtimeDefinitionStore: The runtime definitions.renderGraphCompiler: Builds the render graphs.renderLayoutEngineResolver: Selects the layout engines.
WorkflowDefinitionRenderService(IWorkflowRuntimeDefinitionStore, IWorkflowRenderGraphCompiler, IWorkflowRenderLayoutEngineResolver) constructor
public WorkflowDefinitionRenderService(IWorkflowRuntimeDefinitionStore runtimeDefinitionStore, IWorkflowRenderGraphCompiler renderGraphCompiler, IWorkflowRenderLayoutEngineResolver renderLayoutEngineResolver)
Lays out the diagram of a registered definition.
Parameters
runtimeDefinitionStore: The runtime definitions.renderGraphCompiler: Builds the render graphs.renderLayoutEngineResolver: Selects the layout engines.
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
workflowName: The workflow name.workflowVersion: The version; the latest when not set.layoutProvider: The layout provider; the configured one when not set.layoutRequest: The layout settings; the defaults when not set.cancellationToken: Cancels the operation.
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
workflowDefinitionCatalog: The definitions.workflowRuntimeService: Reads instances and tasks.definitionRenderService: Lays out the definitions.
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
workflowDefinitionCatalog: The definitions.workflowRuntimeService: Reads instances and tasks.definitionRenderService: Lays out the definitions.
GetDiagramAsync(WorkflowDiagramGetRequest, CancellationToken) method
public Task<WorkflowDiagramGetResponse> GetDiagramAsync(WorkflowDiagramGetRequest request, CancellationToken cancellationToken = default)
Lays out a diagram.
Parameters
request: The request.cancellationToken: Cancels the operation.
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
readStore: Reads the console rows.historyService: Reads the history events.observability: Counts and times the console requests, when given.consoleOptions: The profile settings; the defaults when not set.
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
readStore: Reads the console rows.historyService: Reads the history events.observability: Counts and times the console requests, when given.consoleOptions: The profile settings; the defaults when not set.
GetAttemptsAsync(WorkflowExecutionResourceRequest, CancellationToken) method
public Task<WorkflowExecutionResourceResponse> GetAttemptsAsync(WorkflowExecutionResourceRequest request, CancellationToken cancellationToken = default)
Reads the step attempts of an execution.
Parameters
request: The execution, profile and limits.cancellationToken: Cancels the operation.
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
request: The execution, profile and limits.cancellationToken: Cancels the operation.
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
request: The execution, profile and limits.cancellationToken: Cancels the operation.
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
request: The execution, profile and limits.cancellationToken: Cancels the operation.
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
request: The execution, profile and limits.cancellationToken: Cancels the operation.
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
request: The execution, profile and limits.cancellationToken: Cancels the operation.
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
request: The execution, profile and limits.cancellationToken: Cancels the operation.
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
request: The execution, profile and limits.cancellationToken: Cancels the operation.
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
request: The execution, profile and limits.cancellationToken: Cancels the operation.
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
request: The execution, profile and limits.cancellationToken: Cancels the operation.
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
request: The cursor, page size and profile.cancellationToken: Cancels the operation.
Returns
A page of executions.
Exceptions
ArgumentException: The profile is notSAFEorTECHNICAL.
RenderSvgAsync(WorkflowExecutionResourceRequest, CancellationToken) method
public Task<WorkflowExecutionResourceResponse> RenderSvgAsync(WorkflowExecutionResourceRequest request, CancellationToken cancellationToken = default)
Draws the execution graph as SVG.
Parameters
request: The execution, profile and limits.cancellationToken: Cancels the operation.
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
serviceProvider: Resolves the handlers.workflowRegistrationCatalog: The registered workflows.
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
serviceProvider: Resolves the handlers.workflowRegistrationCatalog: The registered workflows.
GetHandler(string, string) method
public IWorkflowExecutionHandler? GetHandler(string workflowName, string workflowVersion)
Finds the handler of a workflow version.
Parameters
workflowName: The workflow name.workflowVersion: The version.
Returns
The handler, or null.
WorkflowFunctionCatalogService class
public sealed class WorkflowFunctionCatalogService
Serves the function catalog.
Parameters
workflowFunctionCatalog: The functions.workflowModuleCatalog: The installed modules.
WorkflowFunctionCatalogService(IWorkflowFunctionCatalog, IWorkflowModuleCatalog) constructor
public WorkflowFunctionCatalogService(IWorkflowFunctionCatalog workflowFunctionCatalog, IWorkflowModuleCatalog workflowModuleCatalog)
Serves the function catalog.
Parameters
workflowFunctionCatalog: The functions.workflowModuleCatalog: The installed modules.
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
registrations: The registrations.
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
registrations: The registrations.
GetRegistration(string, string) method
public WorkflowRegistration? GetRegistration(string workflowName, string? workflowVersion = null)
Finds a registered workflow.
Parameters
workflowName: The workflow name.workflowVersion: The version; the latest when not set.
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
projectionRetentionStore: Applies retention to the projections.workflowRuntimeStateStore: The runtime states.
WorkflowRetentionService(IWorkflowProjectionRetentionStore, IWorkflowRuntimeStateStore) constructor
public WorkflowRetentionService(IWorkflowProjectionRetentionStore projectionRetentionStore, IWorkflowRuntimeStateStore workflowRuntimeStateStore)
Runs the instance retention: marks stale and purges projections and runtime states.
Parameters
projectionRetentionStore: Applies retention to the projections.workflowRuntimeStateStore: The runtime states.
RunAsync(DateTime?, WorkflowRetentionOverride, CancellationToken) method
public Task<WorkflowRetentionRunResult> RunAsync(DateTime? nowUtc = null, WorkflowRetentionOverride? retentionOverride = null, CancellationToken cancellationToken = default)
Runs retention once.
Parameters
nowUtc: The reference time, in UTC; now when not set.retentionOverride: Age thresholds that replace the configured ones for this run.cancellationToken: Cancels the operation.
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
roles: The roles.
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
workflowRoles: The workflow roles.taskRoles: The task roles.runtimeRoles: The roles computed at runtime.
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
request: The request.cancellationToken: Cancels the operation.
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
request: The request.cancellationToken: Cancels the operation.
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
request: The request.cancellationToken: Cancels the operation.
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
durableRequest: The durable start request.expectedExecutionVersion: The execution version the root was created at.cancellationToken: Cancels the operation.
Returns
true when the start ran; false when the execution already moved past that version.
Exceptions
WorkflowStartNotReadyException: The durable root does not exist yet.
GetInstanceAsync(WorkflowInstanceGetRequest, CancellationToken) method
public Task<WorkflowInstanceGetResponse> GetInstanceAsync(WorkflowInstanceGetRequest request, CancellationToken cancellationToken = default)
Reads one workflow instance.
Parameters
request: The request.cancellationToken: Cancels the operation.
Returns
The instance.
GetInstancesAsync(WorkflowInstancesGetRequest, CancellationToken) method
public Task<WorkflowInstancesGetResponse> GetInstancesAsync(WorkflowInstancesGetRequest request, CancellationToken cancellationToken = default)
Lists workflow instances.
Parameters
request: The request.cancellationToken: Cancels the operation.
Returns
A page of instances.
GetTaskAsync(WorkflowTaskGetRequest, CancellationToken) method
public Task<WorkflowTaskGetResponse> GetTaskAsync(WorkflowTaskGetRequest request, CancellationToken cancellationToken = default)
Reads one human task.
Parameters
request: The request.cancellationToken: Cancels the operation.
Returns
The task.
GetTasksAsync(WorkflowTasksGetRequest, CancellationToken) method
public Task<WorkflowTasksGetResponse> GetTasksAsync(WorkflowTasksGetRequest request, CancellationToken cancellationToken = default)
Lists human tasks.
Parameters
request: The request.cancellationToken: Cancels the operation.
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
request: The request.cancellationToken: Cancels the operation.
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
request: The request.cancellationToken: Cancels the operation.
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
signal: The signal.cancellationToken: Cancels the operation.
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
request: The request.cancellationToken: Cancels the operation.
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
signal: The signal.cancellationToken: Cancels the operation.
Returns
Whether the signal was applied.
Exceptions
WorkflowRuntimeStateConcurrencyException: The conflicts outlasted the attempts; the transport redelivers the signal.
WorkflowSignalDeadLetterService class
public sealed class WorkflowSignalDeadLetterService
Lists and replays dead-lettered signals.
Parameters
deadLetterStore: The dead letter store.
WorkflowSignalDeadLetterService(IWorkflowSignalDeadLetterStore) constructor
public WorkflowSignalDeadLetterService(IWorkflowSignalDeadLetterStore deadLetterStore)
Lists and replays dead-lettered signals.
Parameters
deadLetterStore: The dead letter store.
GetMessagesAsync(WorkflowSignalDeadLettersGetRequest, CancellationToken) method
public Task<WorkflowSignalDeadLettersGetResponse> GetMessagesAsync(WorkflowSignalDeadLettersGetRequest request, CancellationToken cancellationToken = default)
Lists the dead letters.
Parameters
request: The request.cancellationToken: Cancels the operation.
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
request: The request.cancellationToken: Cancels the operation.
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
consumerName: The consumer.envelope: The signal.deliveryCount: The delivery attempt.duration: How long it took.
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
consumerName: The consumer.envelope: The signal.deliveryCount: The delivery attempt.duration: How long it took.message: The error message.
RecordEmptyPoll(string) method
public void RecordEmptyPoll(string consumerName)
Counts a poll that found no signal.
Parameters
consumerName: The consumer.
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
consumerName: The consumer.envelope: The signal.deliveryCount: The delivery attempt.duration: How long it took.exception: The failure.
RecordProcessed(string, WorkflowSignalEnvelope, int, TimeSpan) method
public void RecordProcessed(string consumerName, WorkflowSignalEnvelope envelope, int deliveryCount, TimeSpan duration)
Counts a processed signal.
Parameters
consumerName: The consumer.envelope: The signal.deliveryCount: The delivery attempt.duration: How long it took.
WorkflowStudioDescriptor class
public sealed class WorkflowStudioDescriptor
Describes the workflow service to tools.
Parameters
options: The studio options.
WorkflowStudioDescriptor(IOptions<WorkflowStudioOptions>) constructor
public WorkflowStudioDescriptor(IOptions<WorkflowStudioOptions> options)
Describes the workflow service to tools.
Parameters
options: The studio options.
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
| Type | Kind | Description |
|---|---|---|
CanonicalBundleSourceConverter | class | Canonical workflow definition plus its rendering assets, packed as a single ZIP archive. |
CanonicalJsonSourceConverter | class | Pass-through converter for the engine’s native canonical JSON format. |
CanonicalYamlSourceConverter | class | Round-trips canonical workflow definitions through YAML. |
WorkflowSourceFormatRegistry | class | The 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
record: The stored definition.cancellationToken: Cancels the operation.
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
content: The content.cancellationToken: Cancels the operation.
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
record: The stored definition.cancellationToken: Cancels the operation.
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
content: The content.cancellationToken: Cancels the operation.
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
record: The stored definition.cancellationToken: Cancels the operation.
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
content: The content.cancellationToken: Cancels the operation.
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
converters: The registered converters.
WorkflowSourceFormatRegistry(IEnumerable<IWorkflowSourceFormatConverter>) constructor
public WorkflowSourceFormatRegistry(IEnumerable<IWorkflowSourceFormatConverter> converters)
The registry of the source format converters.
Parameters
converters: The registered converters.
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
formatId: The format id.
Returns
The converter.
Exceptions
InvalidOperationException: No converter has the format id.
TryGet(string) method
public IWorkflowSourceFormatConverter? TryGet(string formatId)
Finds a converter by format id, ignoring case.
Parameters
formatId: The format id.
Returns
The converter, or null.
StellaOps.Workflow.Engine.Signaling namespace
| Type | Kind | Description |
|---|---|---|
IWorkflowSignalCommandDispatcher | interface | Runs the start and resume commands that arrive as signals. |
NullWorkflowSignalBus | class | The signal bus of a host without signaling: every call raises NotSupportedException. |
NullWorkflowSignalClaimStore | class | A claim store that never has a signal to claim. |
NullWorkflowSignalDeadLetterStore | class | The dead letter store used when the backend registers none: every call raises NotSupportedException. |
NullWorkflowSignalDriver | class | The signal driver None: it sends no wake and has no signal to receive. |
NullWorkflowSignalStore | class | The signal store of a host without one: it logs a warning and stores nothing. |
NullWorkflowWakeOutbox | class | A wake outbox that stores nothing. |
NullWorkflowWakeOutboxReceiver | class | A wake outbox receiver that never has a notification. |
WorkflowSignalBusBridge | class | 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. |
WorkflowSignalCommandDispatcher | class | Runs signal commands through the workflow runtime service. |
WorkflowSignalEnvelopeSerializer | class | Serializes signal envelopes as JSON with the web defaults (camel-case names); payload keys compare ignoring case. |
WorkflowSignalProcessor | class | 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. |
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
envelope: The signal.cancellationToken: Cancels the operation.
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
request: The start request.cancellationToken: Cancels the operation.
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
envelope: The signal.cancellationToken: Cancels the operation.
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
envelope: The signal.cancellationToken: Cancels the operation.
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
consumerName: The consumer.cancellationToken: Cancels the operation.
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
consumerName: The consumer.cancellationToken: Cancels the operation.
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
request: The request.cancellationToken: Cancels the operation.
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
request: The request.cancellationToken: Cancels the operation.
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
notification: The available signal.cancellationToken: Cancels the operation.
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
consumerName: The consumer.cancellationToken: Cancels the operation.
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
logger: Receives the warnings.
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
logger: Receives the warnings.
PublishAsync(WorkflowSignalEnvelope, CancellationToken) method
public Task PublishAsync(WorkflowSignalEnvelope envelope, CancellationToken cancellationToken = default)
Stores a signal for delivery.
Parameters
envelope: The signal.cancellationToken: Cancels the operation.
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
envelope: The signal.cancellationToken: Cancels the operation.
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
notification: The notification.cancellationToken: Cancels the operation.
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
consumerName: The consumer.cancellationToken: Cancels the operation.
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
signalStore: Stores the signals.signalDriver: Wakes the consumers and hands out signals.wakeOutbox: The wake outbox, for theWakeOutboxdispatch mode.mutationScopeAccessor: The open change scope, for post-commit wakes.
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
signalStore: Stores the signals.signalDriver: Wakes the consumers and hands out signals.wakeOutbox: The wake outbox, for theWakeOutboxdispatch mode.mutationScopeAccessor: The open change scope, for post-commit wakes.
PublishAsync(WorkflowSignalEnvelope, CancellationToken) method
public Task PublishAsync(WorkflowSignalEnvelope envelope, CancellationToken cancellationToken = default)
Stores a signal for delivery.
Parameters
envelope: The signal.cancellationToken: Cancels the operation.
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
envelope: The signal.cancellationToken: Cancels the operation.
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
consumerName: The consumer.cancellationToken: Cancels the operation.
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
workflowRuntimeService: The runtime service.
WorkflowSignalCommandDispatcher(WorkflowRuntimeService) constructor
public WorkflowSignalCommandDispatcher(WorkflowRuntimeService workflowRuntimeService)
Runs signal commands through the workflow runtime service.
Parameters
workflowRuntimeService: The runtime service.
DispatchResumeWorkflowAsync(WorkflowSignalEnvelope, CancellationToken) method
public Task DispatchResumeWorkflowAsync(WorkflowSignalEnvelope envelope, CancellationToken cancellationToken = default)
Applies a signal to its instance.
Parameters
envelope: The signal.cancellationToken: Cancels the operation.
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
request: The start request.cancellationToken: Cancels the operation.
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
payload: The UTF-8 JSON.
Returns
The envelope.
Exceptions
InvalidOperationException: The JSON isnull.
Serialize(WorkflowSignalEnvelope) method
public byte[] Serialize(WorkflowSignalEnvelope envelope)
Serializes an envelope.
Parameters
envelope: The envelope.
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
commandDispatcher: Runs the resume and start commands.callerIdentity: Restores the caller a continuation signal carries.
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
commandDispatcher: Runs the resume and start commands.callerIdentity: Restores the caller a continuation signal carries.
ProcessAsync(WorkflowSignalEnvelope, CancellationToken) method
public Task ProcessAsync(WorkflowSignalEnvelope envelope, CancellationToken cancellationToken = default)
Applies a signal to its instance.
Parameters
envelope: The signal.cancellationToken: Cancels the operation.
Returns
A task that completes when the signal is applied.
