Table of Contents

Struct DocumentProgress

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

Represents progress information for a document processing operation.

public readonly record struct DocumentProgress : IEquatable<DocumentProgress>
Implements
Inherited Members
Extension Methods

Examples

// Report progress during document processing
progress.Report(new DocumentProgress(
    PercentComplete: 50.0,
    ItemsProcessed: 500,
    TotalItems: 1000,
    CurrentPhase: "Processing records"));

// Report indeterminate progress when total is unknown
progress.Report(new DocumentProgress(
    PercentComplete: -1,
    ItemsProcessed: 500,
    TotalItems: null,
    CurrentPhase: "Streaming data"));

Remarks

This record struct is designed for efficient progress reporting in high-throughput scenarios. As a readonly record struct, it avoids heap allocations when passed through IProgress<T>.

Progress information can be used to:

  • Display progress bars or percentage indicators to users
  • Log processing throughput for monitoring and diagnostics
  • Estimate remaining time based on items processed and total items
  • Provide status updates for long-running operations

Constructors

DocumentProgress(double, long, long?, string?)

Represents progress information for a document processing operation.

public DocumentProgress(double PercentComplete, long ItemsProcessed, long? TotalItems, string? CurrentPhase)

Parameters

PercentComplete double

The percentage of the operation that has been completed, from 0.0 to 100.0. A value of -1 indicates that progress is indeterminate.

ItemsProcessed long

The number of items or units of work that have been processed so far.

TotalItems long?

The total number of items to process, or null if the total is unknown. When null, consumers should display indeterminate progress indicators.

CurrentPhase string

A description of the current processing phase, or null if not applicable. Use this for multi-stage operations to indicate which stage is active.

Examples

// Report progress during document processing
progress.Report(new DocumentProgress(
    PercentComplete: 50.0,
    ItemsProcessed: 500,
    TotalItems: 1000,
    CurrentPhase: "Processing records"));

// Report indeterminate progress when total is unknown
progress.Report(new DocumentProgress(
    PercentComplete: -1,
    ItemsProcessed: 500,
    TotalItems: null,
    CurrentPhase: "Streaming data"));

Remarks

This record struct is designed for efficient progress reporting in high-throughput scenarios. As a readonly record struct, it avoids heap allocations when passed through IProgress<T>.

Progress information can be used to:

  • Display progress bars or percentage indicators to users
  • Log processing throughput for monitoring and diagnostics
  • Estimate remaining time based on items processed and total items
  • Provide status updates for long-running operations

Properties

CurrentPhase

A description of the current processing phase, or null if not applicable. Use this for multi-stage operations to indicate which stage is active.

public string? CurrentPhase { get; init; }

Property Value

string

ItemsProcessed

The number of items or units of work that have been processed so far.

public long ItemsProcessed { get; init; }

Property Value

long

PercentComplete

The percentage of the operation that has been completed, from 0.0 to 100.0. A value of -1 indicates that progress is indeterminate.

public double PercentComplete { get; init; }

Property Value

double

TotalItems

The total number of items to process, or null if the total is unknown. When null, consumers should display indeterminate progress indicators.

public long? TotalItems { get; init; }

Property Value

long?

Methods

Completed(long, string?)

Creates a progress instance representing a completed operation.

public static DocumentProgress Completed(long totalItems, string? finalPhase = null)

Parameters

totalItems long

The total number of items that were processed.

finalPhase string

Optional description of the final phase.

Returns

DocumentProgress

A DocumentProgress instance representing 100% completion.

FromItems(long, long, string?)

Creates a progress instance for a specific percentage.

public static DocumentProgress FromItems(long itemsProcessed, long totalItems, string? currentPhase = null)

Parameters

itemsProcessed long

The number of items processed.

totalItems long

The total number of items to process.

currentPhase string

Optional description of the current phase.

Returns

DocumentProgress

A DocumentProgress instance with calculated percentage.

Indeterminate(long, string?)

Creates a progress instance representing an indeterminate operation.

public static DocumentProgress Indeterminate(long itemsProcessed, string? currentPhase = null)

Parameters

itemsProcessed long

The number of items processed so far.

currentPhase string

Optional description of the current phase.

Returns

DocumentProgress

A DocumentProgress instance with indeterminate progress.