Command operations that invoke Screenplay abilities in Cratis Arc
A Screenplay model can say that a command’s operation phases call abilities of an external system. This page shows how an Arc command operation is written so that it runs those abilities inside the command request, and how Arc reads the operation back into a model.
The model side is documented in the Screenplay documentation: operations and invoking an ability. How an ability reaches an extension host is documented by Stage in ability invocations.
What the model says
Section titled “What the model says”produces operation ReserveOrderRevenue uses Ledger orderId OrderId = orderId amount Money = total execute invokes Ledger.ReserveRevenue orderId = orderId amount = amount compensate invokes Ledger.ReleaseRevenue orderId = orderIdThese invocations run in the command request through ICommandOperation. They are not durable messages, a failed one fails the command, and their compensation follows the commit disposition described in execution and recovery. Their results never feed the command’s events: operations run after the events are enrolled, and a decision must not depend on an answer from outside. Work that should happen after the command commits belongs in a reaction to the committed event.
Write the operation
Section titled “Write the operation”A system becomes one interface whose methods are its abilities. Mark it with ISystemAbilities and put the system’s name in the interface name: ILedger is the system Ledger.
public interface ILedger : ISystemAbilities{ Task ReserveRevenue(OrderId orderId, Money amount, CancellationToken cancellationToken);
Task ReleaseRevenue(OrderId orderId, CancellationToken cancellationToken);}The operation takes the interface as a parameter of Execute and Compensate, like any other operation dependency, and calls one ability per statement:
public record ReserveOrderRevenue(OrderId OrderId, Money Amount) : ICommandOperation{ public Task Execute(ILedger ledger, CancellationToken cancellationToken) => ledger.ReserveRevenue(OrderId, Amount, cancellationToken);
public Task Compensate(ILedger ledger, CancellationToken cancellationToken) => ledger.ReleaseRevenue(OrderId, cancellationToken);}Execution, ordering, the compensation budget and what happens when a commit is rejected are exactly those of every other operation. Nothing about abilities changes them.
Implement the collaborator
Section titled “Implement the collaborator”Derive the implementation from SystemAbilities. It names the system and hands each call to IAbilityInvoker:
public class LedgerAbilities(IAbilityInvoker invoker, ICommandContextAccessor contextAccessor) : SystemAbilities(invoker, contextAccessor), ILedger{ protected override string System => "Ledger";
public Task ReserveRevenue(OrderId orderId, Money amount, CancellationToken cancellationToken) => Invoke("ReserveRevenue", new Dictionary<string, object?> { ["orderId"] = orderId, ["amount"] = amount }, cancellationToken);
public Task ReleaseRevenue(OrderId orderId, CancellationToken cancellationToken) => Invoke("ReleaseRevenue", new Dictionary<string, object?> { ["orderId"] = orderId }, cancellationToken);}Register it as a scoped service. Invoke only works while an operation is executing or compensating and throws InvalidCommandOperation anywhere else.
The invoker is the seam to the extension host
Section titled “The invoker is the seam to the extension host”Arc ships no IAbilityInvoker. A host registers the one that hands the invocation to its extension host; Stage’s runtime does this with its ability backend. Each AbilityInvocation carries:
| Member | Meaning |
|---|---|
System, Ability |
The names declared in the model. |
Inputs |
The typed inputs by name. |
IdempotencyKey |
A key that is the same for the same call in the same command execution, never includes an attempt, and differs between Execute and Compensate, so repeating a call finds the same effect once. |
Causation |
The command, correlationId, operation and phase (execute or compensate) that caused the call. |
The invoker returns an AbilityInvocationResult. An outcome of failed, or an exception, fails the command with AbilityInvocationFailed and compensation follows the commit disposition. A declared business outcome other than failed is returned to the operation, which decides what it means.
The key is built from the command’s correlation identity. A client that retries a command as a new request gets a new correlation identity, so give the ability itself a natural idempotency of its own when the same business request can arrive twice.
Read the operation back into a model
Section titled “Read the operation back into a model”Arc’s Screenplay generator (Cratis/Arc#2887) reads an operation back into invokes when every statement of Execute and Compensate calls an ability of an ISystemAbilities parameter with values taken from the operation’s own inputs. It then declares each system with the abilities that are called, typing their inputs from the method parameters.
- An operation may call more than one system. The model’s
usesnames the first one and eachinvokesnames its own system; the compiler accepts this. - A phase that does anything else, such as logging, branching or a literal argument, leaves the operation in code and reports why. The model never says less than the code does.
- A trailing
Asyncon a method name is dropped from the ability name. - The effect class (
safe,idempotent, …) cannot be read from C#, so none is declared. Add it in the model.
Specify it
Section titled “Specify it”The collaborator is an ordinary interface, so a specification substitutes it. given Ledger.ReserveRevenue fails becomes a substitute whose method throws, and the command fails with the operation’s compensation running:
ledger.ReserveRevenue(Arg.Any<OrderId>(), Arg.Any<Money>(), Arg.Any<CancellationToken>()) .ThrowsAsync(new AbilityInvocationFailed("Ledger", "ReserveRevenue", "unavailable"));To check the invocation itself, register a recording IAbilityInvoker and assert on the AbilityInvocation it received: the system, the ability, the inputs and the causation. Use CommandScenario with the substitute registered to check order, compensation and the command outcome together, as described in testing command operations.