Nexus.Pipeline.Portal.Infrastructure.Sqlite 1.1.3

Nexus.Pipeline

Replace scattered if/else and service chains with a clean, observable pipeline — typed steps, structured errors, and automatic saga rollback for .NET 4.6.2 through .NET 10.

Nexus.Pipeline is a typed, in-process execution pipeline library for .NET. You register an ordered sequence of steps on a fluent builder, attach cross-cutting behaviors (logging, retry, timeout, transactions, OpenTelemetry metrics), and execute against a shared IExecutionContext that carries the request, the evolving response, and a per-step execution history. Every execution returns a PipelineResult<TResponse> — structured errors, no exception-based control flow. Supports inline lambda steps and DI-resolved class-based steps interchangeably. Targets .NET 4.6.2 through .NET 10, with AOT and trim compatibility on .NET 8+.

1. Why This Package Exists

Modern .NET applications often implement complex use cases—like checkout flows or user registration—by stuffing logic into massive service classes or MediatR handlers. This approach makes the code difficult to test, hard to observe, and incredibly challenging to roll back if a failure occurs halfway through. Nexus solves this by treating business processes as a pipeline of independent steps. This provides built-in observability, testability, and resilience, ensuring that execution flows are safe and manageable.

2. Key Features

• Core Pipeline Engine: Build and execute robust, strongly-typed pipelines.
• Dependency Injection: Seamlessly integrate with Microsoft.Extensions.DependencyInjection.
• Behaviors (Middleware): Intercept executions with telemetry, transactions, or retries.
• Compensation (Saga Pattern): Automatically roll back successful steps when a later step fails.
• Parallel Execution: Fan-out execution across multiple parallel step groups.
• Validation: Built-in, strongly-typed step validation.
• Portal & Resumability: Dedicated UI/API to visualize executions, debug failures, and resume stalled workflows exactly where they stopped.

3. Supported Frameworks

Nexus is designed for both modern, high-performance cloud workloads (with full AOT support) and legacy enterprise applications.

4. Ecosystem & Packages

Nexus is modular. You only install what you need:

• Nexus.Pipeline - Core engine and behaviors.
• Nexus.Pipeline.AspNetCore - ASP.NET Core integrations and result mappers.
• Nexus.Pipeline.Testing - Fluent assertions and fake contexts.
• Nexus.Pipeline.Portal - The standalone server and web UI for workflow monitoring.
• Nexus.Pipeline.Portal.Client - gRPC client to send pipeline state to the Portal.
• Nexus.Pipeline.Portal.Resume - Webhook handlers to resume stalled workflows.

5. Installation

You can install Nexus and its integrations via the .NET CLI:

dotnet add package Nexus.Pipeline
dotnet add package Nexus.Pipeline.AspNetCore
dotnet add package Nexus.Pipeline.Testing
dotnet add package Nexus.Pipeline.Portal
dotnet add package Nexus.Pipeline.Portal.Client
dotnet add package Nexus.Pipeline.Portal.Resume

6. Architecture Overview

Nexus uses a builder pattern to configure a sequence of steps, wraps them in a middleware pipeline (Behaviors), and executes them within a shared, typed ExecutionContext. The DependencyGraph handles topological sorting, while the CompensationEngine provides Saga-like rollback capabilities on failure.

flowchart LR
    Client --> Executor
    Executor --> Behaviors
    Behaviors --> Step1
    Step1 --> Step2
    Step2 --> Result
    Result --> Client

Read the detailed Architecture Overview

7. Core Concepts

Understanding Nexus starts with a few core concepts:

• PipelineBuilder / ExecutionWorkflow: The fluent API used to construct pipelines.
• ExecutionContext: The strongly-typed state container passed through all steps.
• IPipelineStep: The atomic unit of work containing business logic.
• IPipelineBehavior: Middleware that wraps step execution.
• PipelineResult: A Railway-Oriented response detailing success or failure.

8. Quick Start

The simplest way to use Nexus is to define a step and execute it using the pipeline builder.

public class RegisterUserRequest { public string Email { get; set; } = string.Empty; }
public class RegisterUserResponse { public string UserId { get; set; } = string.Empty; }

public class CreateUserStep : IPipelineStep<RegisterUserRequest, RegisterUserResponse>
{
    public string StepName => "CreateUser";
    public int Order => 10;

    public async Task<StepOutcome> ExecuteAsync(IExecutionContext<RegisterUserRequest, RegisterUserResponse> context, CancellationToken ct)
    {
        context.Response.UserId = Guid.NewGuid().ToString();
        return StepOutcome.Continue;
    }
}

// In Program.cs
var workflow = ExecutionWorkflow.Define<RegisterUserRequest, RegisterUserResponse>(resolver)
    .Step<CreateUserStep>()
    .Build();

var result = await workflow.ExecuteAsync(new RegisterUserRequest { Email = "test@example.com" });

See the First Project guide

9. Portal & Workflow Resumability

Nexus seamlessly integrates with the Nexus Portal—a dedicated UI and API for monitoring pipelines and recovering from failures. When a pipeline fails (e.g., an external API goes down), the exact request, response, and step history are serialized and pushed to the Portal. From the Portal UI, you can inspect the failure and click Resume.

Hosting the Portal UI/Server

Because the Portal is distributed as a NuGet package (Nexus.Pipeline.Portal), you can easily host it inside an ASP.NET Core application. It provides real-time SignalR dashboards, historical execution browsing, and remote resume triggers.

dotnet add package Nexus.Pipeline.Portal

In your Portal hosting application:

var builder = WebApplication.CreateBuilder(args);

// Add the Portal Server services and configure the database provider (Sqlite/SqlServer)
builder.Services.AddNexusPortalServer(options => 
{
    options.DatabaseProvider = "Sqlite";
    options.ConnectionStrings.DefaultConnection = "Data Source=nexus_portal.db";
});

var app = builder.Build();

// Map the UI and gRPC endpoints
app.UseNexusPortal();
app.Run();

Connecting Your Application to the Portal

In your worker service or API where your pipelines run:

1. Install Packages: Reference Nexus.Pipeline.Portal.Client and Nexus.Pipeline.Portal.Resume.
2. Configure DI:

   services.AddNexusPortal(options =>
   {
       options.PortalUrl = "http://nexus-portal:5200"; // Nexus Portal UI/API location
       options.Application = "OrderService";           // Your application name
       options.ActionBaseUrl = "http://my-service";    // Where the Portal sends resume webhooks
       options.OutboxType = NexusOutboxType.InMemory;  // Persistence outbox
   });
   

3. Handle Resume Webhooks: Implement INexusResumeHandler or inherit from NexusResumeHandlerBase<TReq, TRes> to receive the resume webhook from the Portal and re-trigger your pipeline with the original CorrelationId. The ResumePreparationBehavior automatically skips previously successful steps and resumes exactly where the failure occurred.

Read the full Portal Integration guide or Portal Architecture.

10. Complete Features Matrix

11. Examples

12. Documentation Map

• Getting Started: Installation | First Project | Configuration
• Architecture: Architecture Overview | Diagrams | Framework Support
• API Reference: Core API | Steps | IPipelineStep | ExecutionContext | PipelineResult | Behaviors | Errors

13. Best Practices

To get the most out of Nexus, keep steps small and focused on a single responsibility. Prefer using IPipelineBehavior for cross-cutting concerns (like logging or database transactions) instead of embedding them in individual steps. Always implement ICompensatableStep for operations that alter persistent state to ensure safety. For more details on designing flows, check the Architecture Overview.

14. Troubleshooting

If you encounter issues such as steps executing out of order, ensure you have correctly declared step dependencies using the explicit graph declarations or fluent builder. For missing dependency injection errors, verify that services.AddNexusPipeline() is called and all your steps are registered.

See the Error Handling documentation for more details.

15. Contributing

We welcome contributions! Please review the CONTRIBUTING.md guide before opening issues or submitting pull requests.

16. License

This project is licensed under the terms of the LICENSE.txt file in the repository root.