Interface ISaga
Defines the contract for event-driven choreography saga instances that manage long-running business processes through event reactions. This is the Process Coordinator pattern where services autonomously react to domain events.
public interface ISaga
- Extension Methods
Remarks
Pattern: Event-Driven Choreography (Process Coordinator)
Use When:
- Decentralized coordination across services (no central orchestrator)
- Services publish domain events autonomously
- Long-running processes (hours/days)
- Multiple bounded contexts participate
- Eventual consistency acceptable
Alternatives: For step-based orchestration with explicit compensation logic,
use ISaga{TSagaData} from the Excalibur.Saga.Abstractions package instead.
Examples: Order fulfillment workflows, user onboarding journeys, multi-tenant provisioning processes.
The saga pattern implements process management in distributed systems, handling both success and failure scenarios through compensating actions. Sagas maintain their own state and can span multiple bounded contexts or microservices.
See pattern selection guidance and architectural decisions documentation.
Properties
Id
Gets the unique identifier for this saga instance. This identifier is used for saga persistence, correlation, and lifecycle management.
Guid Id { get; }
Property Value
Remarks
The saga ID is typically assigned when the saga is first created and remains constant throughout the saga's execution. This identifier enables correlation of events with specific saga instances and supports saga persistence and recovery operations.
IsCompleted
Gets a value indicating whether this saga has completed its business process. Completed sagas should not process additional events and may be eligible for cleanup.
bool IsCompleted { get; }
Property Value
- bool
trueif the saga has completed successfully or has been terminated; otherwise,false.
Remarks
Saga completion can result from successful execution of all steps, explicit termination due to business rules, or failure handling that results in compensation completion. The saga coordinator uses this property to determine whether to route events to the saga.
Methods
HandleAsync(object, CancellationToken)
Asynchronously processes the specified event message, potentially advancing the saga's state and triggering additional actions or state transitions within the business process.
Task<SagaEventOutcome> HandleAsync(object eventMessage, CancellationToken cancellationToken)
Parameters
eventMessageobjectThe event message to process, which may trigger saga state changes.
cancellationTokenCancellationTokenToken to monitor for cancellation requests during event processing.
Returns
- Task<SagaEventOutcome>
A task that represents the asynchronous event handling operation.
Remarks
Event handling may result in state transitions, command dispatching, timer scheduling, or saga completion. Implementations should ensure idempotency where possible and handle duplicate event delivery gracefully. The method should update saga state and coordinate any necessary downstream actions based on the business process logic.
HandlesEvent(object)
Determines whether this saga instance can handle the specified event message. This method enables event filtering and routing to appropriate saga instances.
bool HandlesEvent(object eventMessage)
Parameters
eventMessageobjectThe event message to evaluate for handling compatibility.
Returns
- bool
trueif this saga can process the event; otherwise,false.
Remarks
Implementations should examine the event type, content, and current saga state to determine handling eligibility. This method supports saga event correlation and helps prevent incorrect event routing in complex orchestration scenarios.