NetEvolve Pulse

Overview

NetEvolve Pulse delivers a high-performance CQRS mediator with an interceptor-enabled pipeline for commands, queries, and events. It targets .NET services that need predictable dispatching, strong typing, and first-class observability. The solution is designed for APIs, background workers, and modular libraries that require clean message handling with minimal ceremony.

Projects

Core Libraries

• NetEvolve.Pulse — Mediator implementation with interceptor pipeline and DI integration (src/NetEvolve.Pulse/README.md)
• NetEvolve.Pulse.Extensibility — Contracts and abstractions for commands, queries, events, handlers, and configurators (src/NetEvolve.Pulse.Extensibility/README.md)

Tests

• NetEvolve.Pulse.Tests.Unit — Unit coverage for mediator behaviors (tests/NetEvolve.Pulse.Tests.Unit)
• NetEvolve.Pulse.Tests.Integration — Integration scenarios and pipeline validation (tests/NetEvolve.Pulse.Tests.Integration)

Features

• Typed CQRS mediator with single-handler enforcement for commands and queries, plus fan-out event dispatch
• Interceptor pipeline for logging, metrics, tracing, validation, retries, and other cross-cutting concerns via IMediatorConfigurator
• OpenTelemetry-friendly hooks through AddActivityAndMetrics() and TimeProvider-aware flows for deterministic testing and scheduling
• Minimal DI setup with services.AddPulse(...), scoped lifetimes, and opt-in configurators per application
• Contracts in NetEvolve.Pulse.Extensibility for framework-agnostic use or deep integration with ASP.NET Core
• Parallel event dispatch with cancellation support to keep handlers responsive under load
• Built-in primitives like Void to simplify command semantics without return values

Getting Started

Prerequisites

• .NET SDK 10.0 or higher (solution also targets .NET 8 and .NET 9)
• Git for source control
• Visual Studio Code or Visual Studio 2022 for development

Installation

1. Clone the repository:

   git clone https://github.com/dailydevops/pulse.git
   cd pulse

2. Restore dependencies:

   dotnet restore

3. Build the solution:

   dotnet build

4. Run tests to verify the setup:

   dotnet test

Quick Use

Install from NuGet and register the mediator:

dotnet add package NetEvolve.Pulse

using Microsoft.Extensions.DependencyInjection;
using NetEvolve.Pulse;
using NetEvolve.Pulse.Extensibility;

var services = new ServiceCollection();

services.AddPulse(config => config.AddActivityAndMetrics());
services.AddScoped<ICommandHandler<CreateOrder, OrderCreated>, CreateOrderHandler>();

public record CreateOrder(string Sku) : ICommand<OrderCreated>;
public record OrderCreated(Guid OrderId);

public sealed class CreateOrderHandler : ICommandHandler<CreateOrder, OrderCreated>
{
    public Task<OrderCreated> HandleAsync(CreateOrder command, CancellationToken cancellationToken) =>
        Task.FromResult(new OrderCreated(Guid.NewGuid()));
}

Configuration

• Configure environment variables and connection details as required by your host application when integrating Pulse.
• Align logging and tracing setup with your OpenTelemetry configuration if using AddActivityAndMetrics().
• Add custom configurators (validation, caching, retries) through IMediatorConfigurator extension methods.

Development

Building

dotnet build

Running Tests

# Run all tests
dotnet test

# Run a specific test project
dotnet test tests/NetEvolve.Pulse.Tests.Unit

Code Formatting

• Use the repository analyzers and formatters configured in the solution. Run dotnet format if enabled in your environment.
• Address diagnostics reported in diagnostics-*.sarif files generated by the solution analyzers.

Project Structure

src/                 # Production libraries
├── NetEvolve.Pulse
└── NetEvolve.Pulse.Extensibility

tests/               # Test projects
├── NetEvolve.Pulse.Tests.Unit
└── NetEvolve.Pulse.Tests.Integration

templates/           # Documentation templates

Architecture

Pulse centers on a mediator that routes commands, queries, and events through an interceptor pipeline. Handlers run with scoped lifetimes to ensure safe resolution of dependencies per request. Interceptors can enrich context, add validation, or emit telemetry before and after handler execution. Parallel event dispatch keeps fan-out responsive while honoring cancellation tokens.

Contributing

Contributions are welcome. Review the Contributing Guidelines for workflows, coding standards, and pull request expectations. Commit messages follow Conventional Commits.

Code of Conduct

This project adheres to the Code of Conduct. Please report unacceptable behavior through the channels defined there.

Documentation

• NetEvolve.Pulse project docs for mediator usage
• NetEvolve.Pulse.Extensibility docs for contract details
• Contributing Guidelines and Code of Conduct

Versioning

This solution uses GitVersion for automated semantic versioning informed by Conventional Commits. Version numbers are derived from Git history during CI builds.

Support

• File bugs or request features via GitHub Issues
• Review existing documentation in this repository before opening new issues
• For security concerns, use private disclosure channels as described in the issue templates (if available)

License

This project is licensed under the MIT License. See the LICENSE file for details.

---

Note

Made with ❤️ by the NetEvolve Team