Nabs.Launchpad.Core.Activities 10.0.229

Nabs.Launchpad.Core.Activities

Nabs.Launchpad.Core.Activities gives you a composable workflow pipeline for multi-step business operations with validation and DI-friendly execution.

Installation

dotnet add package Nabs.Launchpad.Core.Activities

The Problem

Without a workflow abstraction, teams often ship brittle process code:

// 1) Silent ordering bugs
await ValidateAsync();
await SaveAsync();
await EnrichAsync(); // should run before SaveAsync

// 2) Repeated validation boilerplate
var validator = new OrderValidator();
var result = await validator.ValidateAsync(model);
if (!result.IsValid) throw new Exception("Invalid");

// 3) Hidden dependency resolution from static/service-locator calls
var gateway = ServiceLocator.Get<IPaymentGateway>();

Features

• Step-based orchestration with synchronous and asynchronous steps
• Validator steps using FluentValidation
• Shared activity state via ActivityContext<TState>
• Factory-based creation with ActivityFactory

Usage

public sealed class OrderState : IActivityState
{
    public int OrderId { get; set; }
    public bool Validated { get; set; }
}

public sealed class ValidateOrderStep : ActivityStep<OrderState>
{
    public override void Run(ActivityContext<OrderState> context)
    {
        context.State.Validated = context.State.OrderId > 0;
    }
}

public sealed class OrderActivity : Activity<OrderState>
{
    protected override void RegisterSteps()
    {
        AddActivityStep<ValidateOrderStep>();
    }
}

var factory = new ActivityFactory(options => options.ServiceProvider = services);
var activity = factory.Create<OrderActivity>();
await activity.ProcessAsync(state => state.OrderId = 42);

Configuration

Set the service provider when creating the ActivityFactory so step constructors can resolve dependencies.

Project Structure

• Activity* - workflow runtime and context primitives
• IActivity* - workflow contracts
• ActivityFactory / ActivityOptions - construction and DI integration

License

Copyright (c) Net Advantage Business Solutions.

Properties

IsCompleted

public bool IsCompleted { get; protected set; }

Indicates whether the step has completed execution.

Methods

Run (Abstract)

public abstract void Run(ActivityContext<TActivityState> context)

Execute the step logic. Set IsCompleted = true when done.

Reset

public virtual void Reset()

Resets the step to its initial state. Override to add custom reset logic.

ActivityStepAsync<TActivityState>

Properties

IsCompleted

public bool IsCompleted { get; protected set; }

Indicates whether the step has completed execution.

Methods

RunAsync (Abstract)

public abstract Task RunAsync(ActivityContext<TActivityState> context)

Execute the asynchronous step logic. Set IsCompleted = true when done.

Reset

public virtual void Reset()

Resets the step to its initial state. Override to add custom reset logic.

ActivityContext<TActivityState>

Properties

State

public TActivityState State { get; set; }

The current workflow state.

ValidationResult

public ValidationResult? ValidationResult { get; set; }

Validation results from validator steps, if any.

Options

public ActivityOptions Options { get; }

Global activity options containing the service provider.

ActivityFactory

Constructor

public ActivityFactory(Action<ActivityOptions> configure)

Creates a factory with the specified configuration.

Methods

Create<TActivity>

public TActivity Create<TActivity>() where TActivity : IActivity, new()

Creates an instance of the specified activity type.

ActivityOptions

Properties

ServiceProvider

public IServiceProvider ServiceProvider { get; set; }

Service provider used for dependency injection in activity steps.

Architecture and Design Patterns

Step Registration and Immutability

Steps must be registered in the RegisterSteps() method during construction. After construction, the step list becomes immutable, ensuring workflow consistency and thread safety.

Dependency Injection

Activity steps can declare constructor dependencies that are automatically resolved from the configured service provider. This enables proper separation of concerns and testability.

Validation Integration

FluentValidation validators can be added as steps. If validation fails, workflow execution stops and validation results are available in Context.ValidationResult.

State Management

State flows through all steps via the ActivityContext. Steps can read and modify state, enabling communication between steps.

Error Handling

Activities throw ActivityStepExecutionException when a step fails to execute. The exception wraps the underlying exception and provides context about which step failed.

try
{
    await activity.ProcessAsync(state => { /* setup */ });
}
catch (ActivityStepExecutionException ex)
{
    Console.WriteLine($"Step failed: {ex.Message}");
    Console.WriteLine($"Inner exception: {ex.InnerException?.Message}");
}

Best Practices

1. Keep Steps Focused: Each step should have a single, well-defined responsibility
2. Use Validation Steps: Add validator steps early in the workflow to fail fast
3. Manage State Carefully: State is shared across all steps; document state contracts
4. Set IsCompleted: Always set IsCompleted = true in your step implementation when done
5. Use Dependency Injection: Declare step dependencies in constructors rather than using service locator pattern
6. Handle Cancellation: Long-running steps should periodically check the cancellation token
7. Immutable Registration: Register all steps in RegisterSteps() method only

Testing

The library includes comprehensive unit tests demonstrating various usage patterns:

• Synchronous activity execution
• Asynchronous activity execution
• Validation step integration with FluentValidation
• HTTP client activity steps with dependency injection
• Function-based steps
• Bad dependency injection scenarios

Testing Your Activities

[Fact]
public async Task OrderProcessing_ValidOrder_Success()
{
    // Arrange
    var services = new ServiceCollection();
    services.AddScoped<IPaymentService, MockPaymentService>();
    var factory = new ActivityFactory(options => {
        options.ServiceProvider = services.BuildServiceProvider();
    });
    
    var activity = factory.Create<OrderProcessingActivity>();
    
    // Act
    await activity.ProcessAsync(state => {
        state.OrderId = 1;
        state.Amount = 100m;
    });
    
    // Assert
    activity.Context.State.IsProcessed.Should().BeTrue();
    activity.Context.ValidationResult?.IsValid.Should().BeTrue();
}

Dependencies

• Ardalis.Result: For result pattern implementation and error handling
• Ardalis.Result.FluentValidation: Integration layer between Ardalis.Result and FluentValidation
• FluentValidation: For validation step support and rule-based validation
• Microsoft.EntityFrameworkCore: For data access scenarios in activity steps
• Microsoft.Extensions.Http: For HTTP client integration in activity steps

Target Framework

• .NET 10