Table of Contents

Interface IProgressDocumentHandler<TDocument>

Namespace
Excalibur.Dispatch.Delivery
Assembly
Excalibur.Dispatch.Abstractions.dll

Defines a handler that processes a document with progress reporting.

public interface IProgressDocumentHandler<in TDocument> where TDocument : IDispatchDocument

Type Parameters

TDocument

The type of document to process.

Extension Methods

Examples

public class PdfExportHandler : IProgressDocumentHandler<ExportDocument>
{
    public async Task HandleAsync(
        ExportDocument document,
        IProgress<DocumentProgress> progress,
        CancellationToken cancellationToken)
    {
        var pages = document.GetPages();
        var total = pages.Count;

        for (int i = 0; i < total; i++)
        {
            cancellationToken.ThrowIfCancellationRequested();

            await ProcessPageAsync(pages[i], cancellationToken)
                .ConfigureAwait(false);

            progress.Report(DocumentProgress.FromItems(
                itemsProcessed: i + 1,
                totalItems: total,
                currentPhase: $"Processing page {i + 1} of {total}"));
        }

        progress.Report(DocumentProgress.Completed(total, "Export complete"));
    }
}

Remarks

Implement this interface for long-running document operations where callers need visibility into processing progress. This is useful for operations that may take significant time and where users or monitoring systems need status updates. Common use cases include:

  • Large file processing: importing, exporting, or transforming large files
  • Multi-step transformations: operations with distinct processing phases
  • Batch operations: processing many items where progress can be tracked
  • Report generation: creating complex reports with multiple sections
  • Data migrations: moving or transforming data between systems

The contravariant in modifier on TDocument allows handlers to accept derived document types.

Progress is reported via the standard IProgress<T> pattern, allowing callers to choose how to handle progress updates (UI updates, logging, metrics, etc.). The DocumentProgress struct provides rich progress information including percentage, item counts, and phase descriptions.

Handlers are resolved from dependency injection and should be registered with scoped lifetime to maintain state within a single processing operation.

Methods

HandleAsync(TDocument, IProgress<DocumentProgress>, CancellationToken)

Handles the specified document with progress reporting.

Task HandleAsync(TDocument document, IProgress<DocumentProgress> progress, CancellationToken cancellationToken)

Parameters

document TDocument

The document to process.

progress IProgress<DocumentProgress>

The progress reporter for status updates.

cancellationToken CancellationToken

The cancellation token to observe throughout processing.

Returns

Task

A task that completes when the document has been fully processed.

Remarks

Implementations should report progress at regular intervals to provide meaningful feedback. Use FromItems(long, long, string?) for operations with known totals, or Indeterminate(long, string?) when the total is unknown.

Check cancellationToken periodically, especially before expensive operations, to ensure responsive cancellation. Use ConfigureAwait(false) on all await expressions when implementing in library code.

The progress parameter will never be null; callers that don't need progress can pass a no-op implementation.