Table of Contents

Interface ISaga

Namespace
Excalibur.Dispatch.Messaging
Assembly
Excalibur.Dispatch.Abstractions.dll

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

Guid

A Guid that uniquely identifies this saga instance across its entire lifecycle.

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

true if 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

eventMessage object

The event message to process, which may trigger saga state changes.

cancellationToken CancellationToken

Token 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

eventMessage object

The event message to evaluate for handling compatibility.

Returns

bool

true if 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.