LightPath.Cargo
3.1.8
See the version list below for details.
dotnet add package LightPath.Cargo --version 3.1.8
NuGet\Install-Package LightPath.Cargo -Version 3.1.8
<PackageReference Include="LightPath.Cargo" Version="3.1.8" />
<PackageVersion Include="LightPath.Cargo" Version="3.1.8" />
<PackageReference Include="LightPath.Cargo" />
paket add LightPath.Cargo --version 3.1.8
#r "nuget: LightPath.Cargo, 3.1.8"
#:package LightPath.Cargo@3.1.8
#addin nuget:?package=LightPath.Cargo&version=3.1.8
#tool nuget:?package=LightPath.Cargo&version=3.1.8
Cargo
A lightweight Chain of Responsibility pipeline library for .NET.
Why Would I Use This?
You have a series of steps that process or transform data — validation, enrichment, persistence, notification — and you want each step to be:
- Isolated — each step is its own class with a single responsibility
- Composable — mix, match, and reorder steps without touching their internals
- Testable — test each step independently
- Flexible — support sync and async work, error handling, retries, and early termination
Cargo gives you this with minimal ceremony. Define your steps as stations, wire them into a bus, and go.
Common use cases:
- Request processing pipelines
- Validation chains
- ETL / data transformation
- Workflow orchestration
- Multi-step form processing
Installation
dotnet add package LightPath.Cargo
Quick Start
Define a content model (the data that flows through the pipeline):
public class OrderContext
{
public string CustomerId { get; set; }
public decimal Total { get; set; }
public bool IsValid { get; set; }
public bool IsProcessed { get; set; }
}
Create stations (each step in the pipeline):
public class ValidateOrder : Station<OrderContext>
{
public override Station.Action Process()
{
Package.Contents.IsValid = Package.Contents.Total > 0
&& !string.IsNullOrEmpty(Package.Contents.CustomerId);
return Package.Contents.IsValid
? Station.Action.Next()
: Station.Action.Abort("Invalid order");
}
}
public class ProcessOrder : Station<OrderContext>
{
public override Station.Action Process()
{
Package.Contents.IsProcessed = true;
return Station.Action.Next();
}
}
Wire them up and run:
var context = new OrderContext { CustomerId = "C-123", Total = 49.99m };
var result = Bus.New<OrderContext>()
.WithStation<ValidateOrder>()
.WithStation<ProcessOrder>()
.Go(context);
// context.IsValid == true
// context.IsProcessed == true
Features
- Sync and async stations —
Station<T>for synchronous work,StationAsync<T>for async/IO-bound work - Mixed pipelines — freely interleave sync and async stations in the same pipeline
- Services — register and inject dependencies into stations
- Error handling — abort on error (default) or continue with error state
- Station repeat — stations can repeat themselves until a condition is met, with an optional delay and a per-station limit
- Final station — a station that always runs, even after an abort
- Observers — receive a callback as each station starts and finishes, with iteration and elapsed time
- Cancellation — pass a
CancellationTokentoGoAsync(), accessible viaPackage.CancellationToken. Optionally treat cancellation as a graceful abort instead of an exception. - Tracing — built-in trace messages for pipeline execution
- Result tracking — inspect results from each station via
Package.Results - Broad compatibility — targets
netstandard2.0(runs on .NET Framework 4.6.1+, .NET Core 2.0+, and .NET 5/6/7/8+)
Core Concepts
Package — wraps your content model and carries it through the pipeline. Holds results, services, trace messages, and error state.
Station — a single step in the pipeline. Receives the package, does its work, and returns an action: Next(), Abort(), or Repeat().
Bus — builds and executes the pipeline. You register stations, services, and configuration, then call Go() or GoAsync().
Examples
Async Stations
public class FetchCustomerData : StationAsync<OrderContext>
{
public override async Task<Station.Action> ProcessAsync()
{
var service = GetService<ICustomerApi>();
var customer = await service.GetCustomerAsync(Package.Contents.CustomerId);
Package.Contents.CustomerName = customer.Name;
return Station.Action.Next();
}
}
var result = await Bus.New<OrderContext>()
.WithService<ICustomerApi>(customerApi)
.WithStation<ValidateOrder>()
.WithStation<FetchCustomerData>()
.WithStation<ProcessOrder>()
.GoAsync(context);
Async stations run with the caller's synchronization context. Cargo uses ConfigureAwait(false) internally, but station authors control their own awaits — standard .NET async guidance applies.
Services
Register dependencies and access them from any station:
var bus = Bus.New<OrderContext>()
.WithService<ICustomerApi>(customerApi)
.WithService<ILogger>(logger)
.WithStation<FetchCustomerData>();
// Inside a station:
var api = GetService<ICustomerApi>();
var logger = GetService<ILogger>();
// Or safely:
if (TryGetService<ILogger>(out var logger))
{
logger.Log("Processing order");
}
Error Handling
By default, an exception in a station aborts the pipeline:
var bus = Bus.New<OrderContext>()
.WithStation<RiskyStation>()
.WithStation<NextStation>()
.WithFinalStation<CleanupStation>();
// If RiskyStation throws, NextStation is skipped, CleanupStation runs.
To continue after errors:
var bus = Bus.New<OrderContext>()
.WithNoAbortOnError()
.WithStation<RiskyStation>()
.WithStation<NextStation>();
// If RiskyStation throws, NextStation still runs.
// Check Package.IsErrored or LastResult.WasFailure to inspect error state.
A station constructor that throws is handled the same way as a Process() that throws: the station records a failed result and the pipeline follows the abort-on-error setting, so the final station still runs.
Registration is validated up front. WithStation<T>() and WithFinalStation<T>() throw ArgumentException when the type does not derive from Station<T>/StationAsync<T> for the bus's content type, is abstract, or has no public parameterless constructor. WithStations(params Type[]) skips a type that is not a station at all, but still throws for a station that is abstract, open generic, has no parameterless constructor, or has the wrong content type.
Station Repeat
A station can repeat itself until a condition is met:
public class RetryableStation : Station<OrderContext>
{
public override Station.Action Process()
{
Package.Contents.Attempts++;
if (Package.Contents.Attempts < 3)
return Station.Action.Repeat();
return Station.Action.Next();
}
}
Set a repeat limit to prevent infinite loops (default is 100). When the limit is reached, the station records a failed result with an OverflowException and the pipeline follows the abort-on-error setting:
var bus = Bus.New<OrderContext>()
.WithStationRepeatLimit(10)
.WithStation<RetryableStation>();
A station can set its own limit by overriding RepeatLimit. The override replaces the bus-wide value for that station only; returning null keeps the bus-wide value. It is read from a new instance on every run, after Package is set, so it can depend on the content:
public class PollStation : Station<OrderContext>
{
protected override int? RepeatLimit => Package.Contents.MaxPolls;
public override Station.Action Process() { ... }
}
To wait before the next attempt, add a delay to the repeat action. The bus waits (honoring the cancellation token) and then runs the station again. The delay is ignored on Next and Abort. A delay also works under the synchronous Go(), which blocks the calling thread for the delay; the rest of the run then continues on a thread-pool thread, not the calling thread:
return Station.Action.Repeat("Not ready").WithDelay(TimeSpan.FromSeconds(5));
Cancellation during the delay is handled like cancellation between stations: by default OperationCanceledException is thrown; with WithAbortOnCancel() an abort result is recorded and the final station runs. The final station runs once after cancellation; if it returns Repeat, the repeat is recorded as the abort result instead of running again.
Observing Stations
To react as each station starts and finishes — for live progress output, logging, or timing — register an observer:
public class ConsoleObserver : IStationObserver
{
public void Starting(Type station, int iteration)
=> Console.WriteLine($"{station.Name} (attempt {iteration})");
public void Finished(Station.Result result)
=> Console.WriteLine($" {(result.WasSuccess ? "ok" : "failed")} in {result.Elapsed.TotalMilliseconds:F0} ms");
}
var bus = Bus.New<OrderContext>()
.WithStationObserver(new ConsoleObserver())
.WithStation<FetchStation>()
.WithStation<DeployStation>();
Starting fires before each run; iteration starts at 1 and counts repeats of the same station. Finished fires after each result is recorded, including the abort result that WithAbortOnCancel() records for a cancelled station (for which Starting does not fire, and whose Elapsed is zero). Starting also fires for the attempt that exceeds the repeat limit; that attempt records the OverflowException result without running Process(). Every Station.Result carries Iteration and Elapsed; Elapsed is measured from after Starting returns and includes station construction.
The observer runs outside the station's error handling. An exception thrown by the observer escapes Go()/GoAsync() unchanged; it is never recorded as a station failure.
Cancellation
var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
var result = await Bus.New<OrderContext>()
.WithStation<SlowStation>()
.GoAsync(context, cts.Token);
// Inside a station, access the token:
// Package.CancellationToken
Cancellation is checked between stations. By default, a cancelled token throws OperationCanceledException and skips all remaining stations, including the final station.
To treat cancellation as a graceful abort instead (record an abort result, run the final station, return normally):
var bus = Bus.New<OrderContext>()
.WithAbortOnCancel()
.WithStation<SlowStation>()
.WithFinalStation<CleanupStation>();
await bus.GoAsync(context, cts.Token);
// No exception thrown — inspect the package state instead:
if (bus.Package.IsAborted) { /* handle the graceful cancellation */ }
Abort with Messages
return Station.Action.Abort("Payment declined");
// Later:
bus.Package.AbortMessage // "Payment declined"
bus.Package.IsAborted // true
API Reference
Bus
| Method | Description |
|---|---|
Bus.New<T>() |
Create a new bus |
.WithStation<TStation>() |
Add a station to the pipeline |
.WithStations(params Type[]) |
Add multiple stations by type |
.WithFinalStation<TStation>() |
Set a station that runs after abort or error |
.WithService<T>(T service) |
Register a typed service |
.WithServices(strategy, params object[]) |
Register multiple services |
.WithAbortOnError() |
Abort pipeline on station error (default) |
.WithNoAbortOnError() |
Continue pipeline on station error |
.WithAbortOnCancel() |
Treat cancellation as a graceful abort instead of throwing |
.WithNoAbortOnCancel() |
Throw on cancellation (default) |
.WithStationRepeatLimit(int) |
Set max repeat iterations (default: 100) |
.WithStationObserver(IStationObserver) |
Receive a callback as each station starts and finishes |
.Go(content, callback?) |
Execute the pipeline synchronously |
.GoAsync(content, token?, callback?) |
Execute the pipeline asynchronously |
Station.Action
| Method | Description |
|---|---|
Next() |
Proceed to the next station |
Next(string) |
Proceed with a message |
Next(Exception) |
Proceed with an exception |
Abort() |
Abort the pipeline |
Abort(string) |
Abort with a message |
Abort(Exception) |
Abort with an exception |
Repeat() |
Repeat the current station |
Repeat(string) |
Repeat with a message |
Repeat(Exception) |
Repeat with an exception |
.WithMessage(string) |
Attach a message to any action |
.WithException(Exception) |
Attach an exception to any action |
.WithDelay(TimeSpan) |
Wait before the repeat runs the station again; zero to int.MaxValue milliseconds, otherwise ArgumentOutOfRangeException |
ActionType / ActionMessage / ActionException / Delay |
Read back what was attached |
Station.Result
| Member | Description |
|---|---|
Station |
The station type that produced the result |
WasSuccess / WasFailure |
Whether the station completed or threw |
IsAborting / IsRepeating |
Whether the returned action was Abort or Repeat |
ActionMessage / ActionException |
The message or exception attached to the action |
ActionDelay |
The delay attached to a Repeat action |
Exception |
The exception that failed the station, if any |
Iteration |
1 for a first run, higher on each repeat of the same station |
Elapsed |
Wall-clock time for the run, including construction; zero for a cancellation abort result |
Station Members
| Member | Description |
|---|---|
Package |
The current package |
Package.Contents |
The content model |
Package.CancellationToken |
The cancellation token (async pipelines) |
IsErrored |
Whether any station has errored |
LastResult |
The result from the previous station |
PackageResults |
All station results so far |
RepeatLimit |
Override to set this station's repeat limit; null (default) uses the bus-wide limit. A station member of the same name that is not an override hides it and is ignored by the bus |
Messages |
Trace messages |
GetService<T>() |
Get a registered service |
HasService<T>() |
Check if a service is registered |
TryGetService<T>(out T) |
Safely get a service |
Trace(string) |
Add a trace message |
Target Frameworks
The library targets netstandard2.0, so it runs on any compatible runtime, including:
- .NET Framework 4.6.1+
- .NET Core 2.0+
- .NET 5, 6, 7, 8 and later
Releasing
Every merge to master publishes a new version of LightPath.Cargo to nuget.org. There is no manual publish step and no local tool to run.
The workflow in .github/workflows/publish.yml runs on each push to master:
- Nerdbank.GitVersioning computes the version from
version.jsonand the commit height. The major and minor parts come from theversionfield inversion.json; the patch part increments with each commit. Only builds frommasterget a clean version number. Builds from other branches get a-g<sha>prerelease suffix and are never published. - The solution is built in Release configuration and the tests run on net8.0.
dotnet packproduces the.nupkgfile.NuGet/loginexchanges the workflow's GitHub OIDC token for a short-lived nuget.org key. This is NuGet Trusted Publishing. The repo holds no NuGet API key, and nothing expires.dotnet nuget pushuploads the package. A version that already exists on nuget.org is skipped instead of failing.- A GitHub Release is created for the version, which also creates the git tag.
The Trusted Publishing policy is managed on nuget.org under the account that owns the package. It is bound to the GitHub repository owner, the repository name, the workflow file name, and the package ID. Renaming the repository or the workflow file, or adding a GitHub environment: to the publish job, stops the push until the policy is updated to match.
To change the major or minor version, edit the version field in version.json in the same pull request as the change that needs it.
License
MIT - LightPath Solutions, LLC
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. 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. |
| .NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
| .NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
| .NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
| MonoAndroid | monoandroid was computed. |
| MonoMac | monomac was computed. |
| MonoTouch | monotouch was computed. |
| Tizen | tizen40 was computed. tizen60 was computed. |
| Xamarin.iOS | xamarinios was computed. |
| Xamarin.Mac | xamarinmac was computed. |
| Xamarin.TVOS | xamarintvos was computed. |
| Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- No dependencies.
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 3.1.10 | 107 | 10/27/2026 |
| 3.1.8 | 96 | 10/27/2026 |
| 3.1.6 | 92 | 10/27/2026 |
| 3.1.5 | 124 | 10/27/2026 |
| 3.1.3 | 102 | 10/27/2026 |
| 3.0.13 | 309 | 7/8/2026 |
| 3.0.11 | 154 | 7/8/2026 |
| 3.0.6 | 355 | 3/20/2026 |
| 2.0.4.7 | 575 | 6/2/2025 |
| 2.0.4.6 | 279 | 5/3/2025 |
| 2.0.4.4 | 373 | 2/19/2025 |
| 2.0.4.3 | 291 | 2/19/2025 |
| 2.0.4.2 | 293 | 2/18/2025 |
| 2.0.4.1 | 276 | 2/14/2025 |
| 2.0.3.6 | 2,977 | 1/7/2024 |
| 2.0.3.5 | 319 | 1/7/2024 |
| 2.0.3.4 | 312 | 1/7/2024 |
| 2.0.3.3 | 325 | 1/7/2024 |
| 2.0.3.2 | 308 | 1/7/2024 |
| 2.0.3.1 | 4,190 | 9/29/2022 |