Interface IProgressDocumentHandler<TDocument>
Defines a handler that processes a document with progress reporting.
public interface IProgressDocumentHandler<in TDocument> where TDocument : IDispatchDocument
Type Parameters
TDocumentThe 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
documentTDocumentThe document to process.
progressIProgress<DocumentProgress>The progress reporter for status updates.
cancellationTokenCancellationTokenThe 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.