Pipeline Validation

Prerequisites: Defining Pipelines

NPipeline validates your pipeline graph when you call Build(). Validation catches structural errors - disconnected nodes, type mismatches, cycles - before execution begins.

Validation Modes

Control validation behavior with WithValidationMode:

// Default: throw PipelineValidationException on errors
builder.WithValidationMode(GraphValidationMode.Error);

// Log warnings but allow execution
builder.WithValidationMode(GraphValidationMode.Warn);

// Skip validation entirely (not recommended)
builder.WithValidationMode(GraphValidationMode.Off);

Built-In Rules

Core Rules (Always Run)

Rule	Stops Build	What It Checks
UniqueNodeNameRule	Yes	No duplicate node names
DuplicateNodeIdRule	Yes	No duplicate node IDs
EdgeReferenceRule	Yes	All edges reference existing nodes
SourceAndReachabilityRule	No	At least one source; all nodes reachable
UnconsumedOutputRule	No	Every non-sink node's output is consumed downstream
JoinInputsRule	No	Every join has both its left and right inputs connected
CycleDetectionRule	No	Graph is a DAG (no cycles)
ResilienceOptionsRule	No	Item retry, node restart and circuit breakers are set only on transforms; node restart uses a resumable strategy

Extended Rules (Opt-Out)

Extended rules add configuration and best-practice checks:

Rule	What It Checks
MissingSinkRule	At least one sink node exists
SelfLoopRule	No edges from a node to itself
DuplicateEdgeRule	No duplicate edges between same node pair
TypeCompatibilityRule	Output type is assignable to downstream input type
ParallelConfigurationRule	Parallel nodes have bounded queues and reasonable DOP

Disable extended rules if needed:

builder.WithoutExtendedValidation();

Pre-Build Validation

Validate without building:

PipelineValidationResult result = builder.Validate();

if (!result.IsValid)
{
    foreach (var error in result.Errors)
        Console.WriteLine($"Error: {error}");
    foreach (var warning in result.Warnings)
        Console.WriteLine($"Warning: {warning}");
}

Check if a specific connection is valid:

if (builder.CanConnect(source, target, out string? reason))
    builder.Connect(source, target);
else
    Console.WriteLine($"Cannot connect: {reason}");

Safe Build with TryBuild

TryBuild returns false instead of throwing on validation failures:

if (builder.TryBuild(out var pipeline, out var validationResult))
{
    await runner.RunAsync(pipeline);
}
else
{
    foreach (var issue in validationResult.Issues)
        Console.WriteLine($"[{issue.Severity}] {issue.Message}");
}

Custom Validation Rules

Add project-specific rules by implementing IGraphRule:

public class RequireNamingConventionRule : IGraphRule
{
    public string Name => "Naming Convention";
    public bool StopOnError => false;

    public IEnumerable<ValidationIssue> Evaluate(GraphValidationContext context)
    {
        foreach (var node in context.Graph.Nodes)
        {
            if (!node.Name.Contains('-'))
            {
                yield return new ValidationIssue(
                    ValidationSeverity.Warning,
                    $"Node '{node.Name}' should use kebab-case naming",
                    "Convention");
            }
        }
    }
}

builder.WithValidationRule(new RequireNamingConventionRule());

Pipeline Visualization

Inspect the pipeline graph structure:

// Generate a Mermaid diagram
string mermaid = builder.ToMermaidDiagram();
Console.WriteLine(mermaid);

// Text description of the graph
string description = builder.Describe();

💡 Tip: Roslyn analyzers (NP9xxx) provide additional compile-time checks beyond graph validation. See Analyzer Rules for the full catalog.

Next Steps

• Defining Pipelines - the builder API
• Error Handling - resilience configuration validation
• Parallel Execution - parallel configuration validation