Interface IStreamingDocumentHandler<TDocument, TOutput>
Defines a handler that produces a stream of outputs from a document.
public interface IStreamingDocumentHandler<in TDocument, out TOutput> where TDocument : IDispatchDocument
Type Parameters
TDocumentThe type of document to process.
TOutputThe 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
documentTDocumentThe document to process.
cancellationTokenCancellationTokenThe 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.