Sa.Utils.WorkQueue 0.20.0

dotnet add package Sa.Utils.WorkQueue --version 0.20.0
                    
NuGet\Install-Package Sa.Utils.WorkQueue -Version 0.20.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Sa.Utils.WorkQueue" Version="0.20.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Sa.Utils.WorkQueue" Version="0.20.0" />
                    
Directory.Packages.props
<PackageReference Include="Sa.Utils.WorkQueue" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Sa.Utils.WorkQueue --version 0.20.0
                    
#r "nuget: Sa.Utils.WorkQueue, 0.20.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Sa.Utils.WorkQueue@0.20.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Sa.Utils.WorkQueue&version=0.20.0
                    
Install as a Cake Addin
#tool nuget:?package=Sa.Utils.WorkQueue&version=0.20.0
                    
Install as a Cake Tool

Sa.Utils.WorkQueue

English | Русский

High-performance async task queue for .NET with bounded capacity, dynamic concurrency scaling, and a type-safe API.

Installation

dotnet add package Sa.Utils.WorkQueue

Contents

Features

Feature Description Details
Concurrency limiting Control the number of simultaneously executing tasks via ConcurrencyLimit Concurrency & Scaling
Dynamic scaling Change the limit at runtime: queue.ConcurrencyLimit = newLimit Concurrency & Scaling
Back-pressure BoundedChannel — Enqueue strategy when the buffer is full: Wait (default, blocks) • Skip (returns false) • Throw (SaWorkQueueFullException); plus non-blocking TryEnqueue and batch EnqueueMany Enqueue Strategies
Reader cancellation order Lifo • Fifo • RoundRobin • Random — choose which readers are cancelled when the limit is decreased Reader Cancellation Order
Cancel modes Hard (default) or Soft — how in-flight work is treated when readers are removed at runtime Reader Cancel Modes
DI integration AddSaWorkQueue<TInput> with an IWorkQueueBuilder (processor + callbacks) and settings bound from appsettings via Microsoft.Extensions.Options Quick Start
Safe shutdown ShutdownAsync, DisposeAsync — idempotent and thread-safe Important Notes
Error strategies Per-item fault handling: Continue, StopReader, or ShutdownQueue Error Strategies
Status callbacks Track item lifecycle: Running → Completed / Faulted / Cancelled / Aborted / Skipped Status Lifecycle
Pool observability PoolState names why a non-idle queue is not draining — paused on purpose, lost every reader, or stopped — which the published numbers cannot say Pool Observability
Emergency stop ForceCancelReaders / ForceCancelReadersAsync stop the reader pool without stopping the queue; the buffer is dropped unless the wait times out Important Notes

Quick Start

1️⃣ Implement your task processor

public sealed class OrderWork(ILogger<OrderWork> logger) : ISaWork<OrderInput>
{
    public async Task Execute(OrderInput input, CancellationToken ct)
    {
        logger.LogInformation("Processing order {OrderId}", input.OrderId);
        await ProcessOrderAsync(input, ct); // Your business logic
    }
}

2️⃣ Register with DI

builder.Services.AddSaWorkQueue<OrderInput>(
    configure: b => b
        .UseProcessor<OrderWork>()
        .WithReaderCancellationOrder(SaReaderCancellationOrder.RoundRobin)
        .WithStatusCallback((input, status, ex) =>
        {
            // logger.LogDebug("Order {Id} → {Status}", input.OrderId, status);
        })
        .FromConfiguration("WorkQueue"));

The serializable half (capacity, concurrency, strategies, timeouts) can live in appsettings — see Configuration from appsettings. The callback may also need services from the container — use the builder's Configure escape hatch:

b.Configure((sp, opts) =>
{
    var log = sp.GetRequiredService<ILogger<OrderWork>>();
    return opts.WithStatusCallback((input, status, _) =>
        log.LogInformation("Order {Id} → {Status}", input.OrderId, status));
})

3️⃣ Use via injection

public class OrderService(ISaWorkChannel<OrderInput> queue)
{
    // false only in Skip mode, when the buffer was full and the item was dropped
    public async Task<bool> SubmitAsync(OrderInput order, CancellationToken ct)
        => await queue.Enqueue(order, ct);

    public async Task WaitForCompletionAsync(CancellationToken ct)
        => await queue.WaitForIdleAsync(cancellationToken: ct);

    public bool IsIdle() => queue.IsIdle();
    public int Pending => queue.QueueTasks;
}

Configuration

All parameters are immutable record fields with fluent With* methods on SaWorkQueueOptions<TInput>:

SaWorkQueueOptions<TInput>.Create(processor)
    .WithConcurrencyLimit(int)                    // Concurrency limit (default: CPU count)
    .WithQueueCapacity(int)                       // Channel capacity (default: equals MaxConcurrency)
    .WithMaxConcurrency(int)                      // Absolute ceiling of readers (default: CPU count)
    .WithSingleWriter(bool)                       // Optimisation for single-writer scenarios
    .WithReaderCancellationOrder(enum)             // Lifo | Fifo | RoundRobin | Random
    .WithReaderCancelMode(enum)                   // Hard | Soft — in-flight work on reader removal
    .WithEnqueueStrategy(enum)                    // Wait | Skip | Throw — behaviour when the buffer is full
    .WithProducerCancellation(enum)               // Observe | Detached — keep or drop the producer's token after acceptance
    .WithStatusCallback(Action<TInput, SaWorkStatus, Exception?>)
    .WithHandleItemFaulted(Func<TInput, Exception, SaExecutionErrorStrategy>)
    .WithItemDisplayName(Func<TInput, string>)    // Custom display name for logging
    .WithShutdownTimeout(TimeSpan)                 // Max wait for readers on shutdown/force-cancel (default: 30s)
    .WithTimeProvider(TimeProvider)                // Clock for every bounded wait (default: System; tests only)

WithTimeProvider exists so that ShutdownTimeout can be exercised without sleeping through it — every wait in the queue is measured on this clock, so pointing it at a controllable one makes a 30-second timeout expire instantly. It governs waits only, never the processors, so a clock that jumps cannot corrupt a queue's state. Leave it alone in production code.

Creating options

// Via ISaWork<TInput> implementation
var opts = SaWorkQueueOptions<OrderInput>.Create(new OrderWork(logger));

// Via delegate (no class needed)
var opts = SaWorkQueueOptions<OrderInput>.Create(async (input, ct) => {
    await ProcessAsync(input, ct);
});

Configuration from appsettings (Microsoft.Extensions.Options)

The serializable half of the queue lives in SaWorkQueueSettings and goes through the standard options pipeline — bind a section with .FromConfiguration(...):

{
  "WorkQueue": {
    "ConcurrencyLimit": 4,
    "QueueCapacity": 100,
    "MaxConcurrency": 16,
    "SingleWriter": false,
    "EnqueueStrategy": "Wait",
    "ProducerCancellation": "Observe",
    "ReaderCancelMode": "Hard",
    "ReaderCancellationOrder": "RoundRobin",
    "ShutdownTimeout": "00:00:30"
  }
}
builder.Services.AddSaWorkQueue<OrderInput>(
    b => b
        .UseProcessor<OrderWork>()
        .FromConfiguration("WorkQueue"));

The same delegate also owns the settings pipeline — .Options(...) hands you the standard OptionsBuilder<SaWorkQueueSettings>, so there is one configuration channel for everything:

builder.Services.AddSaWorkQueue<OrderInput>(
    b => b
        .UseProcessor<OrderWork>()
        .WithQueueCapacity(64)                      // code default — config wins over it
        .FromConfiguration("WorkQueue")             // section binding — wins over code
        .Options(o => o                             // escape hatch — beats config
            .Configure(x => x.ConcurrencyLimit = 4)
            .Validate(x => x.QueueCapacity > 0, "QueueCapacity must be positive")));

Details worth knowing:

  • One named options instance per item type (typeof(TInput).FullName), so queues of different item types in one container bind from different sections and never see each other's values.
  • Precedence. The pipeline runs: builder With* code defaults → BindConfiguration → the builder's Options(...) actions → validation. The binder only overwrites keys the section contains, so configuration wins over code and everything the section does not mention keeps its code value; a Configure inside Options(...) (and the builder's queue-level Configure, which runs at resolve) beats configuration.
  • Validation. SaWorkQueueSettingsValidator (IValidateOptions, AOT-safe) checks the same rules the queue constructor enforces — QueueCapacity ≥ 1, ConcurrencyLimit ≥ 0, MaxConcurrency ≥ 0, positive ShutdownTimeout — and ValidateOnStart() turns a bad section into an OptionsValidationException at host start rather than deep in a run.
  • Snapshot. Settings are read once, when the queue is created; reloading configuration does not touch a running queue. ConcurrencyLimit remains mutable at runtime through the queue property.

Concurrency & Scaling

The queue runs up to ConcurrencyLimit readers concurrently (default: CPU count), never exceeding MaxConcurrency. The limit is mutable at runtime — readers are spawned or cancelled as needed, and queued items are not affected.

// Configure
var opts = SaWorkQueueOptions<OrderInput>.Create(processor)
    .WithConcurrencyLimit(4)      // readers to start with
    .WithMaxConcurrency(16)       // ceiling for runtime scaling
    .WithQueueCapacity(100);      // bounded buffer size
// Scale at runtime
queue.ConcurrencyLimit = 8;  // spawn more readers
queue.ConcurrencyLimit = 4;  // cancel readers (per the configured cancellation order)
queue.ConcurrencyLimit = 0;  // pause processing; set a positive value to resume

When a reader terminates on its own (error strategy StopReader, ForceCancelReaders), ConcurrencyLimit decreases accordingly — set it back to the target value to restore the pool.

A limit of 0 therefore does not say paused: it is also what a pool that lost every reader looks like. PoolState tells those apart.


Pool Observability

IsIdle() answers whether work is pending. It does not answer why nothing is coming for it, and neither does anything else the queue publishes. After ForceCancelReaders — or after every reader is lost to a StopReader fault — the cancelled readers give up their slots and ConcurrencyLimit drops to 0, which is exactly the number a deliberate pause leaves behind. Same limit, same IsEnabled, opposite situations: one is a decision, the other is a fault that needs acting on.

PoolState names the condition in one call:

State Meaning Response
Active Running, at least one reader live —
Paused ConcurrencyLimit was set to 0 on purpose Raise the limit when work should resume
NoReaders Enabled, not paused, no readers left Re-arm: set ConcurrencyLimit above 0. This is the one that means something is wrong
Stopped Shut down or disposed —
switch (queue.PoolState)
{
    case SaWorkPoolState.NoReaders:
        logger.LogError("work queue {Queue} lost every reader; re-arming", name);
        queue.ConcurrencyLimit = 4;          // the documented response
        break;

    case SaWorkPoolState.Paused:
        logger.LogInformation("work queue {Queue} is paused with {Pending} item(s) pending",
            name, queue.QueueTasks);
        break;
}

A stopped queue reports Stopped rather than Paused even if its limit was 0 when it stopped — there is no pool left to describe, and the shutdown is the reason nothing is happening, not the pause.

It is a snapshot, not a value that stays true: pausing a running queue or re-arming an empty one changes it on the next read. It is meant for a log line, a metric or a health check — all of which read it once and act.

WaitForIdleAsync does not work this out for itself: when it decides a pending queue will never drain, it reads PoolState and acts on that one value. So the state a caller polls, the warning it logs and the exception it throws are the same answer by construction rather than by three checks that have to be kept in agreement — and a stopped queue is waited on properly, since Stopped is neither of the two dead ends.


Reader Cancellation Order

Determines which readers to cancel when ConcurrencyLimit is decreased at runtime (default: Lifo).

var opts = SaWorkQueueOptions<OrderInput>.Create(processor)
    .WithReaderCancellationOrder(SaReaderCancellationOrder.RoundRobin);
Strategy Behaviour Best for
Lifo (default) Cancels the most recently created readers CPU-bound tasks, cache locality
Fifo Cancels the oldest readers Resource rotation, even lifetime distribution
RoundRobin Cyclic reader cancellation Stable workers, balanced load
Random Random reader cancellation Testing, avoiding patterns

Reader Cancel Modes

Controls how in-flight work is treated when readers are removed at runtime (limit decrease, or pause via ConcurrencyLimit = 0).

var opts = SaWorkQueueOptions<OrderInput>.Create(processor)
    .WithReaderCancelMode(SaReaderCancelMode.Soft);
Mode Behaviour Best for
Hard (default) The in-flight item is cancelled immediately (Cancelled) and dropped Fast stop, work that is cheap to interrupt
Soft The removed reader finishes its current item (Completed) before exiting; items still in the channel stay queued Expensive-to-interrupt work (I/O, third-party calls, long computations)

ForceCancelReaders / ForceCancelReadersAsync and Shutdown / ShutdownAsync always interrupt in-flight work regardless of the mode.


Enqueue Strategies

Enqueue returns ValueTask<bool> and behaves according to the configured SaEnqueueStrategy when the bounded buffer is full:

var opts = SaWorkQueueOptions<OrderInput>.Create(processor)
    .WithEnqueueStrategy(SaEnqueueStrategy.Wait);   // Wait | Skip | Throw
Strategy Behaviour when the buffer is full Best for
Wait (default) Blocks until space is available, then returns true Producers that should apply back-pressure
Skip Drops the item and returns false (not counted in QueueTasks; reported as Skipped) Fire-and-forget producers: metrics, telemetry, logs
Throw Throws SaWorkQueueFullException (carries QueueCapacity, QueuedCount, and the item's display name) Producers that must react explicitly to overload
var accepted = await queue.Enqueue(input, ct);
if (!accepted)
{
    // Skip mode: the buffer was full, the item was dropped (reported as Skipped)
}

// Free slots before the buffer is full (informational)
int free = queue.AvailableCapacity;

A stopped or disposed queue always throws (InvalidOperationException / ObjectDisposedException) regardless of the strategy. Since Enqueue is async, the exception is carried by the returned ValueTask — observe it with await.

TryEnqueue(input) is a non-blocking variant that never honors the strategy: it performs a single try-write — true when the item is accepted, false when the buffer is full (the item is dropped, not counted, and reported as Skipped). Use it on hot paths where the caller cannot block or await. A stopped or disposed queue still throws — synchronously this time.

EnqueueMany(inputs, ct) adds several items in a single call and returns the number accepted (ValueTask<int>). Each item honors the configured strategy: Wait blocks until space is available, so all items are eventually accepted; Skip drops the items that no longer fit, reporting each of them as Skipped; Throw throws SaWorkQueueFullException as soon as the buffer becomes full, carrying AcceptedCount and TotalCount. Items accepted before a Throw failure remain in the queue.

Producer cancellation

By default an accepted item keeps observing the token passed to Enqueue: cancelling it while the item is buffered or in flight reports Aborted and leaves the reader in the pool. That costs a linked CancellationTokenSource per item whenever the token is cancellable.

var opts = SaWorkQueueOptions<OrderInput>.Create(processor)
    .WithProducerCancellation(SaProducerCancellationMode.Detached);

Detached keeps the token only for the wait on buffer space. An already-cancelled token still rejects the call, and cancelling a producer parked in WriteAsync still unblocks it, but once accepted the item runs to a terminal status — the queue's own shutdown and force-cancel still cancel it. Use this when work must outlive the scope that produced it (for example, a request token handed to background processing). EnqueueMany checks the token before each item, so a cancellation observed mid-batch stops the batch after the preceding items were accepted.

SaProducerCancellationMode.Observe is the default, and the only mode in which producer cancellation can produce SaWorkStatus.Aborted. TryEnqueue carries no token at all and is therefore already detached.


Error Strategies

Controls what happens when ISaWork<TInput>.Execute throws.

var opts = SaWorkQueueOptions<OrderInput>.Create(processor)
    .WithHandleItemFaulted((input, ex) =>
        ex is OutOfMemoryException
            ? SaExecutionErrorStrategy.ShutdownQueue
            : SaExecutionErrorStrategy.Continue);
Strategy Behaviour
Continue Mark item as Faulted, continue processing remaining items
StopReader Mark item as Faulted, stop current reader (capacity decreases; restore via ConcurrencyLimit = X)
ShutdownQueue (default) Mark item as Faulted, trigger full queue shutdown

For fault-tolerant pipelines, override the default to Continue or StopReader.


Status Lifecycle

Each item flows through statuses communicated via the StatusChanged callback:

var opts = SaWorkQueueOptions<OrderInput>.Create(processor)
    .WithStatusCallback((input, status, ex) =>
    {
        // e.g. logger.LogDebug("Order {Id} → {Status}", input.OrderId, status);
    });
Status Meaning
Running Item is being processed
Completed Finished successfully
Faulted Unhandled error occurred
Cancelled Cancelled by system (shutdown, timeout)
Aborted Cancelled explicitly by caller's token
Skipped Not accepted because the buffer was full (Skip strategy, TryEnqueue, or EnqueueMany); the item was never processed

API — ISaWorkChannel<TInput>

Member Kind Description
Enqueue(input, ct) Method Add a task; returns false only in Skip mode when the buffer is full
TryEnqueue(input) Method Non-blocking enqueue; returns false when the buffer is full (strategy-independent)
EnqueueMany(inputs, ct) Method Batch enqueue; returns the number of items accepted (each item honors the configured strategy)
WaitForIdleAsync(failIfNoProgress, ct) Method Wait until all tasks complete. Returns immediately when a running queue is explicitly paused (ConcurrencyLimit = 0) or has no readers — in both states pending work can never drain. A stopped queue is waited on normally even if its limit was 0: the shutdown drains the buffer, and that drain is the thing being waited for. failIfNoProgress: true turns a no-progress state into InvalidOperationException instead of a silent return, carrying the message that matches the cause
ShutdownAsync() Method Cancellation shutdown: cancels all readers (in-flight work is interrupted, not finished), waits for readers bounded by ShutdownTimeout, drains the rest of the buffer as Faulted
Shutdown() Method Synchronous shutdown (blocks the calling thread)
ForceCancelReaders() Method Emergency stop of all readers (bounded wait)
ForceCancelReadersAsync(timeout, ct) Method Async emergency stop with optional timeout
IsIdle() Method true if no pending/active tasks
PoolState Property Active / Paused / NoReaders / Stopped — why a non-idle queue is not draining, which the limit cannot say
IsEnabled Property true while queue is active
QueueTasks Property Total tasks in progress + queued
ConcurrencyLimit Property Current parallelism limit (mutable)
MaxConcurrency Property Absolute ceiling
QueueCapacity Property Bounded channel capacity
AvailableCapacity Property Free slots in the buffer (informational)
ShutdownError Property Exception that triggered shutdown, if any

⚠️ Important Notes

  1. Lifecycle: registered as Singleton only. AddSaWorkQueue rejects Scoped/Transient with ArgumentOutOfRangeException — a scoped queue gives every resolution its own reader pool and its own copy of the buffer, which works right up until two scopes enqueue the same work.
  2. StatusChanged callback: invoked synchronously, on the reader's thread — and for a reader that finds work already waiting, that is the thread which set ConcurrencyLimit, not a pool thread. No queue lock is held while it runs, so a handler may use the queue from another thread and wait for it. What it must not do is wait for the reader that is calling it: that reader is blocked on the handler. Avoid long-running operations inside. Handler exceptions are logged but not propagated.
  3. Cancellation: each Enqueue accepts a CancellationToken. Items distinguish caller-initiated cancellation (Aborted) from system cancellation (Cancelled).
  4. Thread safety: all public members are thread-safe. Changing ConcurrencyLimit at runtime adjusts reader count without losing queued items.
  5. Idempotent shutdown: ShutdownAsync, Shutdown, Dispose, DisposeAsync are safe to call multiple times.
  6. ConcurrencyLimit = 0: pauses all processing (cancels all readers; in Soft mode the in-flight items are allowed to finish first). Restore a positive value to resume. While a running queue is paused with pending work, WaitForIdleAsync returns immediately (or throws InvalidOperationException with failIfNoProgress: true) — and a wait that was already parked is released when the pause happens, so arriving early is not a way to hang on a pool that no longer exists. The qualifier is load-bearing: a queue that was paused and then stopped reports Stopped, and the wait parks for the shutdown drain instead — that drain needs no reader, so a pause which is no longer the reason cannot be the answer. QueuePaused argues the point on its own: it tells the caller to raise ConcurrencyLimit, and on a stopped queue that assignment does nothing. Note an emergency loss of all readers (ForceCancelReaders, StopReader faults) is not a pause, but the wait returns early there as well — the empty pool cannot drain on its own; re-arm ConcurrencyLimit to restore readers. Either early return is logged as a warning, because it is not the same answer as "idle". On the producer side, Enqueue under the Wait strategy parks when the buffer is full — including while the queue is paused. Three things release it: a positive ConcurrencyLimit, a shutdown, and the caller's own CancellationToken. This is deliberate rather than a defect — parking is what bounds the producer, and refusing the item instead would turn a pause into data loss. Once the queue is stopped or disposed, assigning ConcurrencyLimit does nothing and the getter keeps reporting the limit the queue was stopped at — assigning 4 and reading back 4 would claim four readers that are never coming. Nothing is thrown: the assignment states an intent, and IsEnabled is the answer to "is there a pool to resize" for callers that need one to ask.
  7. ForceCancelReaders / ForceCancelReadersAsync: emergency stop — immediately cancels all reader tasks. The sync variant waits up to ShutdownTimeout (default 30s) for readers to terminate; the async variant accepts an optional TimeSpan? timeout. Items still in the buffer are dropped and reported as Faulted with a "readers were force-cancelled" reason (the queue itself stays active — the message must not claim a shutdown that did not happen). After calling, restore concurrency by setting ConcurrencyLimit = X to spawn replacement readers. The buffer is dropped only when the call actually stopped a reader. A paused queue (ConcurrencyLimit = 0), or one whose readers are already unwinding, has nothing to cancel — so it also has nothing to discard: the accepted items stay queued, QueueTasks keeps counting them, and a re-armed pool finishes them. An emergency stop is a statement about the pool, not permission to empty the queue. One exception: if ForceCancelReadersAsync is given a timeout and it elapses (or its ct is cancelled), the buffer is kept — nobody rejected those items, and a re-armed pool can still take them. A warning is logged, the exception is rethrown so the caller knows the wait expired, and IsIdle() stays false until the buffer is drained. A WaitForIdleAsync that gives up for this reason also logs a warning naming the cause — including a wait that was already parked when the timeout expired — so it never contradicts IsIdle().
  8. Processor sources: the processor comes from the builder — UseProcessor<TProcessor>() (registered in the container if absent), UseProcessor(instance) or WithProcess(delegate) — with a fallback to an ISaWork<TInput> you register by hand, so a bare AddSaWorkQueue<TInput>() also works. A queue with no processor at all fails the first resolve with an InvalidOperationException naming both options. Callbacks that need services from the container go through the builder's Configure((sp, opts) => ...) escape hatch, which runs at resolve — capture only singletons there: the queue is a singleton, so a captured scoped service would live forever.
  9. Enqueue return value: ValueTask<bool> — false only in Skip mode with a full buffer (the item is dropped and reported as Skipped via StatusChanged). A stopped/disposed queue always throws; the exception is carried by the ValueTask and surfaced by await.
  10. AvailableCapacity: informational only — free slots in the buffer. It does not affect IsIdle().
  11. Never from inside Execute: do not call Shutdown, ShutdownAsync, ForceCancelReaders, ForceCancelReadersAsync, or Dispose/DisposeAsync from within your ISaWork<TInput>.Execute implementation: the calling reader is one of the tasks those methods wait for, so the call blocks for the full ShutdownTimeout (30 s by default) before returning. Hand the work off to a background task instead (e.g. Task.Run).
  12. Options validation: the SaWorkQueueOptions<TInput> primary constructor is public, so its arguments bypass the With* guards; the SaWorkChannel<TInput> constructor re-validates and throws ArgumentOutOfRangeException before creating the channel — ConcurrencyLimit ≥ 0, QueueCapacity ≥ 1, MaxConcurrency ≥ 0, positive ShutdownTimeout, and the four strategy enums (EnqueueStrategy, ProducerCancellation, ReaderCancelMode, ReaderCancellationOrder) must be defined values: an undefined one would otherwise fall through to a default arm and quietly become Skip, Hard or Lifo. The same rules reach configuration earlier through SaWorkQueueSettingsValidator, which reports them as an OptionsValidationException — at host start (ValidateOnStart()) or on the first queue resolve — instead of an ArgumentOutOfRangeException. MaxConcurrency = 0 and null both mean "processor count" (the same thing WithMaxConcurrency(0) produces); a negative value has no meaning and is rejected. Assigning a negative ConcurrencyLimit after construction throws too — a silent clamp to 0 would produce a permanently paused queue that still reports IsEnabled == true. Only a positive value above MaxConcurrency is clamped, not rejected.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Sa.Utils.WorkQueue:

Package Downloads
Sa.Schedule

Execute jobs on a schedule

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.20.0 136 11/13/2026
0.18.0 147 11/3/2026
0.17.0 149 10/29/2026
0.16.0 146 10/14/2026
0.15.0 142 10/2/2026
0.12.0 217 7/28/2026
0.11.0 192 7/14/2026
0.10.0 192 7/2/2026
0.9.0 182 4/29/2026