ND.FW.PipelineOrchestrator 1.0.2

ND.FW.PipelineOrchestrator

Staged, ordered pipeline execution for Novacis Digital services, with built-in distributed tracing via ND.FW.Observability (INDTracerService). Cross-cutting span/trace instrumentation is handled by the framework, so application code doesn't need to write any bespoke tracing logic around its stages.

What it does

• Executes a set of IPipelineStage<TPayload> implementations in Order.
• Two context-propagation modes between stages:
  • SharedContext (default) — every stage's Output is merged into context.Extensions, accumulating across the whole run.
  • DerivedContext — each stage's first output value becomes context.Current, feeding forward into the next stage.
• Wraps the whole run in a root trace span, and each stage in a child span, automatically tagging duration, outcome, and error details.
• Emits System.Diagnostics.DiagnosticListener events (Pipeline.Start, Stage.Enter, Stage.Success, Stage.Failed, Stage.Exception, Stage.Cancelled, Pipeline.Completed, Pipeline.Failed) for anyone listening in-process, independent of the tracer.
• Stops on the first stage failure or unhandled exception — no partial/best-effort continuation past a failed stage.

What it does not do

• It doesn't retry stages. If a stage needs retry semantics, build that into the stage implementation itself.
• It doesn't validate that stage Order values are unique or contiguous — stages just run in ascending Order.
• Tracing is a no-op if no IPipelineTracer is supplied (all tracer calls are null-conditional), so the package works standalone without ND.FW.Observability wired up at runtime — but the package reference itself is required at compile time.

Install

dotnet add package ND.FW.PipelineOrchestrator

Usage

using PipelineOrchestrator.Abstractions;
using PipelineOrchestrator.Contracts;
using PipelineOrchestrator.Core;

// 1. Implement your stages
public sealed class ValidateStage : IPipelineStage<OrderPayload>
{
    public string StageName => "Validate";
    public int Order => 0;
    public bool IsEnabled => true;

    public Task<StageResult> ExecuteAsync(PipelineContext<OrderPayload> context, CancellationToken ct)
    {
        var isValid = context.Payload.Total > 0;

        return Task.FromResult(new StageResult
        {
            Success = isValid,
            StageName = StageName,
            ErrorCode = isValid ? null : "INVALID_ORDER",
            Outcome = isValid ? StageOutcome.Continue : StageOutcome.Stop
        });
    }
}

// 2. Wire up the pipeline (tracer is optional — pass null to run untraced)
var pipeline = new Pipeline<OrderPayload>(
    stages: new IPipelineStage<OrderPayload>[] { new ValidateStage(), /* ... */ },
    tracer: pipelineTracer); // IPipelineTracer, backed by ND.FW.Observability's INDTracerService

// 3. Execute
var context = new PipelineContext<OrderPayload> { Payload = order };
var result = await pipeline.Execute(context, PipelineExecutionMode.SharedContext, ct);

if (!result.Success)
{
    // result.FailedStage, result.ErrorCode, result.StageResults are populated
}

Tracing setup

PipelineTracer wraps an INDTracerService (from ND.FW.Observability) and implements IPipelineTracer:

IPipelineTracer tracer = new PipelineTracer(ndTracerService);

If you don't need tracing, omit the tracer argument (or pass null) — Pipeline<TPayload> treats it as optional and skips all span creation.

Execution modes

Dependencies

• ND.FW.Observability (0.0.8) — required at compile time for INDTracerService; must already be published to the GitLab Package Registry before this package is restored (see publish order below).
• Microsoft.Extensions.Logging / Microsoft.Extensions.Logging.Console

ND.FW.Observability must be published before this package can restore in CI.

Versioning

Package version is set at pack time and is not hardcoded in source:

dotnet pack /p:Version=$VERSION

License

Internal Novacis Digital package. Not for external distribution.