Skip to content

Commit 885a5ba

Browse files
samtrionsamtrion
authored
docs: update README to provide comprehensive overview and usage instructions for NetEvolve Pulse (#4)
1 parent 837704a commit 885a5ba

1 file changed

Lines changed: 174 additions & 2 deletions

File tree

‎README.md‎

Lines changed: 174 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,174 @@
1-
# template-dotnet
2-
.NET template for repositories
1+
# NetEvolve Pulse
2+
3+
[![License](https://img.shields.io/github/license/dailydevops/pulse.svg)](LICENSE)
4+
[![Build Status](https://img.shields.io/github/actions/workflow/status/dailydevops/pulse/ci.yml?branch=main)](https://github.com/dailydevops/pulse/actions)
5+
[![Contributors](https://img.shields.io/github/contributors/dailydevops/pulse.svg)](https://github.com/dailydevops/pulse/graphs/contributors)
6+
7+
## Overview
8+
9+
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.
10+
11+
## Projects
12+
13+
### Core Libraries
14+
15+
- **NetEvolve.Pulse** — Mediator implementation with interceptor pipeline and DI integration ([src/NetEvolve.Pulse/README.md](src/NetEvolve.Pulse/README.md))
16+
- **NetEvolve.Pulse.Extensibility** — Contracts and abstractions for commands, queries, events, handlers, and configurators ([src/NetEvolve.Pulse.Extensibility/README.md](src/NetEvolve.Pulse.Extensibility/README.md))
17+
18+
### Tests
19+
20+
- **NetEvolve.Pulse.Tests.Unit** — Unit coverage for mediator behaviors ([tests/NetEvolve.Pulse.Tests.Unit](tests/NetEvolve.Pulse.Tests.Unit))
21+
- **NetEvolve.Pulse.Tests.Integration** — Integration scenarios and pipeline validation ([tests/NetEvolve.Pulse.Tests.Integration](tests/NetEvolve.Pulse.Tests.Integration))
22+
23+
## Features
24+
25+
- Typed CQRS mediator with single-handler enforcement for commands and queries, plus fan-out event dispatch
26+
- Interceptor pipeline for logging, metrics, tracing, validation, retries, and other cross-cutting concerns via `IMediatorConfigurator`
27+
- OpenTelemetry-friendly hooks through `AddActivityAndMetrics()` and TimeProvider-aware flows for deterministic testing and scheduling
28+
- Minimal DI setup with `services.AddPulse(...)`, scoped lifetimes, and opt-in configurators per application
29+
- Contracts in `NetEvolve.Pulse.Extensibility` for framework-agnostic use or deep integration with ASP.NET Core
30+
- Parallel event dispatch with cancellation support to keep handlers responsive under load
31+
- Built-in primitives like `Void` to simplify command semantics without return values
32+
33+
## Getting Started
34+
35+
### Prerequisites
36+
37+
- [.NET SDK 10.0](https://dotnet.microsoft.com/download) or higher (solution also targets .NET 8 and .NET 9)
38+
- [Git](https://git-scm.com/) for source control
39+
- [Visual Studio Code](https://code.visualstudio.com/) or [Visual Studio 2022](https://visualstudio.microsoft.com/) for development
40+
41+
### Installation
42+
43+
1. Clone the repository:
44+
45+
```bash
46+
git clone https://github.com/dailydevops/pulse.git
47+
cd pulse
48+
```
49+
50+
2. Restore dependencies:
51+
52+
```bash
53+
dotnet restore
54+
```
55+
56+
3. Build the solution:
57+
58+
```bash
59+
dotnet build
60+
```
61+
62+
4. Run tests to verify the setup:
63+
64+
```bash
65+
dotnet test
66+
```
67+
68+
### Quick Use
69+
70+
Install from NuGet and register the mediator:
71+
72+
```bash
73+
dotnet add package NetEvolve.Pulse
74+
```
75+
76+
```csharp
77+
using Microsoft.Extensions.DependencyInjection;
78+
using NetEvolve.Pulse;
79+
using NetEvolve.Pulse.Extensibility;
80+
81+
var services = new ServiceCollection();
82+
83+
services.AddPulse(config => config.AddActivityAndMetrics());
84+
services.AddScoped<ICommandHandler<CreateOrder, OrderCreated>, CreateOrderHandler>();
85+
86+
public record CreateOrder(string Sku) : ICommand<OrderCreated>;
87+
public record OrderCreated(Guid OrderId);
88+
89+
public sealed class CreateOrderHandler : ICommandHandler<CreateOrder, OrderCreated>
90+
{
91+
public Task<OrderCreated> HandleAsync(CreateOrder command, CancellationToken cancellationToken) =>
92+
Task.FromResult(new OrderCreated(Guid.NewGuid()));
93+
}
94+
```
95+
96+
### Configuration
97+
98+
- Configure environment variables and connection details as required by your host application when integrating Pulse.
99+
- Align logging and tracing setup with your OpenTelemetry configuration if using `AddActivityAndMetrics()`.
100+
- Add custom configurators (validation, caching, retries) through `IMediatorConfigurator` extension methods.
101+
102+
## Development
103+
104+
### Building
105+
106+
```bash
107+
dotnet build
108+
```
109+
110+
### Running Tests
111+
112+
```bash
113+
# Run all tests
114+
dotnet test
115+
116+
# Run a specific test project
117+
dotnet test tests/NetEvolve.Pulse.Tests.Unit
118+
```
119+
120+
### Code Formatting
121+
122+
- Use the repository analyzers and formatters configured in the solution. Run `dotnet format` if enabled in your environment.
123+
- Address diagnostics reported in `diagnostics-*.sarif` files generated by the solution analyzers.
124+
125+
### Project Structure
126+
127+
```
128+
src/ # Production libraries
129+
├── NetEvolve.Pulse
130+
└── NetEvolve.Pulse.Extensibility
131+
132+
tests/ # Test projects
133+
├── NetEvolve.Pulse.Tests.Unit
134+
└── NetEvolve.Pulse.Tests.Integration
135+
136+
templates/ # Documentation templates
137+
```
138+
139+
## Architecture
140+
141+
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.
142+
143+
## Contributing
144+
145+
Contributions are welcome. Review the [Contributing Guidelines](CONTRIBUTING.md) for workflows, coding standards, and pull request expectations. Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/).
146+
147+
## Code of Conduct
148+
149+
This project adheres to the [Code of Conduct](CODE_OF_CONDUCT.md). Please report unacceptable behavior through the channels defined there.
150+
151+
## Documentation
152+
153+
- [NetEvolve.Pulse project docs](src/NetEvolve.Pulse/README.md) for mediator usage
154+
- [NetEvolve.Pulse.Extensibility docs](src/NetEvolve.Pulse.Extensibility/README.md) for contract details
155+
- [Contributing Guidelines](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md)
156+
157+
## Versioning
158+
159+
This solution uses [GitVersion](https://gitversion.net/) for automated semantic versioning informed by [Conventional Commits](https://www.conventionalcommits.org/). Version numbers are derived from Git history during CI builds.
160+
161+
## Support
162+
163+
- File bugs or request features via [GitHub Issues](https://github.com/dailydevops/pulse/issues)
164+
- Review existing documentation in this repository before opening new issues
165+
- For security concerns, use private disclosure channels as described in the issue templates (if available)
166+
167+
## License
168+
169+
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
170+
171+
---
172+
173+
> [!NOTE]
174+
> **Made with ❤️ by the NetEvolve Team**

0 commit comments

Comments
 (0)