Table of Contents

Interface IStreamingDocumentHandler<TDocument, TOutput>

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

Defines a handler that produces a stream of outputs from a document.

public interface IStreamingDocumentHandler<in TDocument, out TOutput> where TDocument : IDispatchDocument

Type Parameters

TDocument

The type of document to process.

TOutput

The type of output items produced by the handler.

Extension Methods

Examples

public class CsvRowHandler : IStreamingDocumentHandler<CsvDocument, DataRow>
{
    public async IAsyncEnumerable<DataRow> HandleAsync(
        CsvDocument document,
        [EnumeratorCancellation] CancellationToken cancellationToken)
    {
        await foreach (var line in document.ReadLinesAsync(cancellationToken))
        {
            cancellationToken.ThrowIfCancellationRequested();
            yield return ParseRow(line);
        }
    }
}

Remarks

Implement this interface for document-to-stream transformations where a single document produces multiple output items. This enables memory-efficient processing of large documents without loading entire result sets into memory. Common use cases include:

  • CSV/JSON parsing: splitting files into individual records
  • Document splitting: breaking large documents into pages or sections
  • Entity extraction: extracting multiple entities from unstructured text
  • Report generation: streaming report rows to output
  • PDF processing: extracting pages or images from documents

The covariant out modifier on TOutput enables returning streams of derived types where base types are expected. The contravariant in modifier on TDocument allows handlers to accept derived document types.

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

Methods

HandleAsync(TDocument, CancellationToken)

Handles the specified document and produces a stream of outputs asynchronously.

IAsyncEnumerable<out TOutput> HandleAsync(TDocument document, CancellationToken cancellationToken)

Parameters

document TDocument

The document to process.

cancellationToken CancellationToken

The cancellation token to observe throughout streaming.

Returns

IAsyncEnumerable<TOutput>

An asynchronous stream of output items.

Remarks

Implementations should use yield return to produce items incrementally rather than building collections in memory. Apply the [EnumeratorCancellation] attribute to the cancellation token parameter when implementing this method.

Check cancellationToken periodically and between yield operations to ensure responsive cancellation. Use ConfigureAwait(false) on all await expressions when implementing in library code.