QsMessaging

What this project does

QsMessaging helps .NET applications exchange data asynchronously through a consistent API. Instead of writing transport-specific plumbing for every service, you register the library once, implement typed handlers, and send messages through IQsMessaging.

The project is designed for distributed systems that need clean contracts, background processing, and a straightforward path to scale multiple consumer instances.

The goal is practical messaging for real projects: keep contracts strongly typed, register handlers through dependency injection, and switch transports without rewriting business logic.

Where to find the code

The source code, examples, tests, and release metadata live in the GitHub repository:

https://github.com/Pavlo-0/QsMessaging

Additional reference material is available in the project wiki.

Core capabilities

The library focuses on the messaging patterns most teams need first for .NET services and worker processes.

Typed messages

Send strongly typed contracts between services instead of manual queue payload management.

Events

Broadcast event contracts so each running instance can react independently when needed.

Request / response

Send a request and await a typed response with correlation handled by the library.

Dependency injection

Handlers are discovered and registered in DI, so constructor injection works naturally.

Horizontal scaling

Run multiple consumer instances so the workload can be shared across services.

Error interception

Configure handler retries before custom consumer error handlers take over logging, alerting, or dead-letter flows.

Why teams use QsMessaging

One API for multiple transports instead of transport-specific application code.
Clear typed contracts for commands, integration messages, domain events, and responses.
Low-friction integration with hosted services, worker services, and ASP.NET Core applications.
Repository examples and integration tests that show the expected runtime behavior.

Quick start

dotnet add package QsMessaging

builder.Services.AddQsMessaging(options =>
{
    options.Transport = QsMessagingTransport.RabbitMQ;
    options.HandlerResilience.MaxRetryAttempts = 1;
    options.HandlerResilience.Delay = TimeSpan.FromSeconds(1);
    options.Resilience.MaxRetryAttempts = 3;
    options.Resilience.Delay = TimeSpan.FromSeconds(1);
});

await host.UseQsMessaging();

The package is published on NuGet and the repository contains example applications for messages, events, and request/response flows.

Supported transports

RabbitMQ

RabbitMQ is the default transport and the most mature path in the project. It uses a conventional host, username, password, and port configuration and is ready for local development or hosted deployments. Ordinary message publishing uses publisher confirms and return tracking so unroutable messages can be retried and reported.

Azure Service Bus

Azure Service Bus support is available behind the same public API, but it is still marked as early preview in the project documentation. The goal is transport flexibility without changing handler code, though some features may still evolve. Send retry starts only when Azure Service Bus reports a missing destination during send.

Developer experience

builder.Services.AddQsMessaging(options =>
{
    options.Transport = QsMessagingTransport.RabbitMQ;
});

await host.UseQsMessaging();

After registration, applications work with IQsMessaging for sending messages and requests, while handlers stay focused on domain logic instead of transport wiring.

Messaging patterns supported by the project

QsMessaging is built around common service-to-service communication patterns used in modern .NET systems.

Queue-based processing

Use messages for work items that should be processed by one consumer instance at a time.

Fan-out events

Publish typed events so multiple handlers or service instances can react independently.

Request and reply

Send typed requests and await typed responses without hand-building correlation plumbing.

How the library is organized

The repository includes code for the library, usage samples, and automated verification.

01

Main library

The QsMessaging project contains the public API, transport implementations, shared services, and registration code.

02

Examples

The Examples folder demonstrates message/event consumers and request/response communication between sample applications.

03

Tests

There are unit tests plus integration scenarios, including a dedicated Azure Service Bus integration test area.

04

Documentation surface

The GitHub repository, wiki, NuGet package, and this Pages site work together as the public documentation entry points.

Operational notes

Handlers are registered as transient services.
Message sends are not preceded by queue or subscription existence checks.
Missing or unroutable receiver send failures use Polly retry settings before a warning is logged.
User handlers are retried with HandlerResilience before consumer error handlers are called.
Azure Service Bus normal messages use a 14 day TTL; events use a 60 second TTL.
There is no built-in dead-letter orchestration yet.
Request/response uses correlation identifiers and a default timeout.
Transport-specific entity names are generated automatically by the library.

When QsMessaging fits well

Microservices that want a quick messaging integration path.
Background workers that need queue or topic communication.
Teams that want one programming model across multiple transports.
Projects that benefit from examples, tests, and packaged NuGet distribution.

Project links

Use the repository for source code and issues, NuGet for package consumption, the wiki for extended documentation, and this page as a searchable project overview.

GitHub repository NuGet package Project wiki