Sipke Schoorstra 74fc891350

feat(core): let a container withdraw work it scheduled but must not run (#7967 )

A container that schedules a child and then decides the child must not run
had no way to withdraw it. `IActivityScheduler` exposed no removal operation,
and `CancelActivityAsync` no-opped on a context whose status was `Pending`,
so a container could tear a branch down and still have an activity from that
branch execute afterwards, side effects and all. Fixes #7943.

- `IActivityScheduler.RemoveWhere` removes work items and keeps the order the
  survivors would have been taken in; implemented in both the FIFO and LIFO
  schedulers.
- `CancelActivityAsync` (both the public extension and the internal one used
  when a container completes) cancels `Pending` contexts as well as running
  ones, and withdraws the work item that would have started the cancelled
  activity plus the items it had scheduled for children with no context yet.

Withdrawal is a real removal rather than a terminal status honoured at dequeue
time, because the scheduler is also read: `Flowchart.HasPendingWork` inspects
it to decide whether it may complete, and the work item list is extracted into
the persisted workflow state — a withdrawn-but-queued item would be persisted
and rehydrated with a fresh context after a suspend/resume.

`StateMachine` had hand-rolled the same operation to drop competing triggers by
clearing the scheduler and re-scheduling everything else; it now calls
`RemoveWhere`. `Elsa.Bpmn` no longer needs to refuse a teardown whose subtree
still has queued work, so `BpmnWorkTeardown` drops the `NotSupportedException`
and records the teardown reason on the torn-down activity's journal instead.

BREAKING: `IActivityScheduler` gains a member; external implementations must
add `RemoveWhere`.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

2026-08-20 23:29:46 +02:00

9 KiB

Raw Blame History

Workflow Core

Workflow core is the engine layer. It defines activities, execution contexts, scheduling primitives, inputs and outputs, variables, bookmarks, serialization, execution pipelines, flowchart behavior, and the core runner.

Start in src/modules/Elsa.Workflows.Core.

Feature Wiring

WorkflowsFeature registers the core services:

IActivityInvoker
IWorkflowRunner
IActivityTestRunner
IActivityVisitor
IWorkflowGraphBuilder
IWorkflowStateExtractor
IActivitySchedulerFactory
workflow and activity execution pipelines
activity registry, descriptor, factory, and lookup services
storage drivers
serializers
incident strategies
UI hint handlers
identity and hashing services

The feature also configures default workflow and activity pipelines. The umbrella ElsaFeature calls WithDefaultWorkflowExecutionPipeline() and WithDefaultActivityExecutionPipeline().

Activities

Core activity abstractions live in Abstractions:

Activity
Activity<T>
CodeActivity
WorkflowBase
Behavior
Trigger

Built-in activities live in Activities. Important families:

Primitive control: Sequence, If, Switch, For, ForEach, While, Parallel, Fork, Break, End, Finish, Complete, Fault.
Data and runtime helpers: SetVariable, SetName, Correlate, WriteLine, ReadLine.
Dynamic and missing activity handling: DynamicActivity, NotFoundActivity.
Flowchart: Activities/Flowchart.
State machine: Activities/StateMachine. Named states with trigger-driven transitions. See Activities And Authoring for the execution model.

Activities are described by IActivityDescriber and registered in IActivityRegistry. Workflow management adds activities to the available designer/API surface.

Execution Contexts And State

Core execution state lives under State and Models. Important concepts:

WorkflowState: serializable workflow execution state.
ActivityExecutionContextState: serializable activity execution context state.
ActivityWorkItemState: queued work item state.
WorkflowExecutionState: high-level status and state model.
ActivityIncident: fault or incident details.
WorkflowInput: input passed into a workflow run.
ActivityOutputs and ActivityOutputRecord: activity output capture.

Execution context extension tests live under test/unit/Elsa.Workflows.Core.UnitTests/Extensions/ActivityExecutionContextExtensions.

Inputs, Outputs, And Expressions

Inputs and outputs are modeled through:

Input<T> and Input
Output<T> and Output
InputDefinition
OutputDefinition
InputDescriptor
OutputDescriptor
Argument and ArgumentDefinition

Expression handling bridges core workflows with language providers through Expressions and the separate expression modules. DefaultActivityInputEvaluator evaluates inputs before activity execution.

Scheduling Inside A Workflow

Core scheduling is about which activity work item runs next. Key services:

Scheduling is reversible. A container that schedules a child and then decides the child must not run withdraws it by cancelling: CancelActivityAsync cancels contexts that are still Pending as well as running ones, and removes from the scheduler both the work item that would have started the cancelled activity and the work items it had scheduled for children that have no execution context yet. Withdrawal is a real removal (IActivityScheduler.RemoveWhere) rather than a flag honoured at dequeue time, because the scheduler is also read: Flowchart asks it whether the flowchart still has pending work, and the work item list is part of the persisted workflow state.

Runtime scheduling and external dispatch are separate and live in Elsa.Workflows.Runtime.

Bookmarks And Triggers

Core models define bookmark concepts:

The runtime persists and indexes bookmarks/triggers. Core activities create bookmarks and signals; runtime services decide how they are stored and resumed.

Flowchart Execution

Flowchart support is split between:

FlowchartFeature
Flowchart activities
flowchart extension methods in Activities/Flowchart/Extensions

Relevant ADRs:

Pipelines

Core has separate workflow and activity execution pipelines:

flowchart LR
    Runner["IWorkflowRunner"] --> WorkflowPipeline["IWorkflowExecutionPipeline"]
    WorkflowPipeline --> Scheduler["Activity scheduler"]
    Scheduler --> ActivityPipeline["IActivityExecutionPipeline"]
    ActivityPipeline --> Invoker["IActivityInvoker"]
    Invoker --> Activity["IActivity.ExecuteAsync"]

Pipeline extension methods live under Extensions and middleware under Middleware. Pipelines are configured by WorkflowsFeature.

Commit Strategies

Commit strategies determine persistence boundaries. Related files:

CommitStrategiesFeature
CommitStrategies
workflow sample configuration in Elsa.Server.Web/Program.cs

Runtime replaces the default no-op commit handler with an execution-cycle-aware handler so state changes are persisted at runtime boundaries.

Serialization

Core serializers live under Serialization, including:

JsonWorkflowStateSerializer
JsonPayloadSerializer
JsonActivitySerializer
ApiSerializer
SafeSerializer
StandardJsonSerializer

Custom constructor and additional converter configurators are registered by WorkflowsFeature.

Workflow JSON Type Identifiers

Workflow JSON type resolution uses the shared ISerializationTypeRegistry from Elsa.Common.Serialization, not expression type aliases. Register workflow-serializable payload types through SerializationTypeOptions; keep ExpressionOptions for expression/type metadata only.

New workflow JSON writes preferred aliases when a type is registered. Compatibility reads also accept explicitly registered legacy names, including selected CLR names from older persisted workflow JSON. Unknown CLR names are rejected rather than loaded dynamically. Polymorphic object reads also reject abstract, interface, open generic, and unsupported collection targets unless the resolver can map a known collection interface to a concrete collection type.

Public API payloads that expose workflow JSON type identifiers should emit values from ISerializationTypeRegistry. For example, incident strategy descriptors return the alias that workflow JSON accepts, while registered legacy CLR names remain readable during the compatibility window.

When To Change This Layer

Change workflow core only when you are changing engine semantics, activity contracts, execution state, serialization, core activity behavior, or flowchart behavior. If the change is about persisted definitions, API DTOs, background dispatch, or a module-specific transport, start in management, API, runtime, or the extension module instead.

9 KiB Raw Blame History