Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/devlooped/merq
Internal application architecture via command and event messages
https://github.com/devlooped/merq
dotnet smart-nuget
Last synced: 13 days ago
JSON representation
Internal application architecture via command and event messages
- Host: GitHub
- URL: https://github.com/devlooped/merq
- Owner: devlooped
- License: mit
- Created: 2022-07-16T04:57:23.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-06-13T12:18:52.000Z (5 months ago)
- Last Synced: 2024-06-13T14:51:10.738Z (5 months ago)
- Topics: dotnet, smart-nuget
- Language: C#
- Homepage: https://clarius.org/Merq
- Size: 1.35 MB
- Stars: 23
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: readme.md
- Changelog: changelog.md
- License: license.txt
Awesome Lists containing this project
README
 Merq
================
[](https://www.nuget.org/packages/Merq)
[](https://www.nuget.org/packages/Merq)
[](https://github.com/devlooped/Merq/blob/main/license.txt)
> **Mercury:** messenger of the Roman gods
> *Mercury* > *Merq-ry* > **Merq**
**Merq** brings the [Message Bus](https://docs.microsoft.com/en-us/previous-versions/msp-n-p/ff647328(v=pandp.10)) pattern together with
a [command-oriented interface](https://www.martinfowler.com/bliki/CommandOrientedInterface.html) for an
extensible and decoupled in-process application architecture.
These patterns are well established in microservices and service oriented
architectures, but their benefits can be applied to apps too, especially
extensible ones where multiple teams can contribute extensions which
are composed at run-time.
The resulting improved decoupling between components makes it easier to evolve
them independently, while improving discoverability of available commands and
events. You can see this approach applied in the real world in
[VSCode commands](https://code.visualstudio.com/api/extension-guides/command)
and various events such as [window events](https://code.visualstudio.com/api/references/vscode-api#window).
Clearly, in the case of VSCode, everything is in-process, but the benefits of
a clean and predictable API are pretty obvious.
*Merq* provides the same capabilities for .NET apps.
## Events
Events can be any type, there is no restriction or interfaces you must implement.
Nowadays, [C# record types](https://docs.microsoft.com/en-us/dotnet/csharp/fundamentals/types/records)
are a perfect fit for event data types. An example event could be a one-liner such as:
```csharp
public record ItemShipped(string Id, DateTimeOffset Date);
```
The events-based API surface on the message bus is simple enough:
```csharp
public interface IMessageBus
{
void Notify(TEvent e);
IObservable Observe();
}
```
By relying on `IObservable`, *Merq* integrates seamlessly with
more powerful event-driven handling via [System.Reactive](http://nuget.org/packages/system.reactive)
or the more lightweight [RxFree](https://www.nuget.org/packages/RxFree).
Subscribing to events with either of those packages is trivial:
```csharp
IDisposable subscription;
// constructor may use DI to get the dependency
public CustomerViewModel(IMessageBus bus)
{
subscription = bus.Observe().Subscribe(OnItemShipped);
}
void OnItemShipped(ItemShipped e) => // Refresh item status
public void Dispose() => subscription.Dispose();
```
In addition to event producers just invoking `Notify`, they can also be
implemented as `IObservable` directly, which is useful when the
producer is itself an observable sequence.
Both features integrate seamlessly and leverage all the power of
[Reactive Extensions](https://github.com/dotnet/reactive).
## Commands
Commands can also be any type, and C# records make for concise definitions:
```csharp
record CancelOrder(string OrderId) : IAsyncCommand;
```
Unlike events, command messages need to signal the invocation style they require
for execution:
| Scenario | Interface | Invocation |
| --- | --- | --- |
| void synchronous command | `ICommand` | `IMessageBus.Execute(command)` |
| value-returning synchronous command | `ICommand` | `var result = await IMessageBus.Execute(command)` |
| void asynchronous command | `IAsyncCommand` | `await IMessageBus.ExecuteAsync(command)` |
| value-returning asynchronous command | `IAsyncCommand` | `var result = await IMessageBus.ExecuteAsync(command)` |
| async stream command | `IStreamCommand` | `await foreach(var item in IMessageBus.ExecuteStream(command))` |
The sample command shown before can be executed using the following code:
```csharp
// perhaps a method invoked when a user
// clicks/taps a Cancel button next to an order
async Task OnCancel(string orderId)
{
await bus.ExecuteAsync(new CancelOrder(orderId), CancellationToken.None);
// refresh UI for new state.
}
```
An example of a synchronous command could be:
```csharp
// Command declaration
record SignOut() : ICommand;
// Command invocation
void OnSignOut() => bus.Execute(new SignOut());
// or alternatively, for void commands that have no additional data:
void OnSignOut() => bus.Execute();
```
The marker interfaces on the command messages drive the compiler to only allow
the right invocation style on the message bus, as defined by the command author:
```csharp
public interface IMessageBus
{
// sync void
void Execute(ICommand command);
// sync value-returning
TResult Execute(ICommand command);
// async void
Task ExecuteAsync(IAsyncCommand command, CancellationToken cancellation);
// async value-returning
Task ExecuteAsync(IAsyncCommand command, CancellationToken cancellation);
// async stream
IAsyncEnumerable ExecuteStream(IStreamCommand command, CancellationToken cancellation);
}
```
For example, to create a value-returning async command that retrieves some
value, you would have:
```csharp
record FindDocuments(string Filter) : IAsyncCommand>;
class FindDocumentsHandler : IAsyncCommandHandler>
{
public bool CanExecute(FindDocument command) => !string.IsNullOrEmpty(command.Filter);
public Task> ExecuteAsync(FindDocument command, CancellationToken cancellation)
=> // evaluate command.Filter across all documents and return matches
}
```
In order to execute such command, the only execute method the compiler will allow
is:
```csharp
IEnumerable files = await bus.ExecuteAsync(new FindDocuments("*.json"));
```
If the consumer tries to use `Execute`, the compiler will complain that the
command does not implement `ICommand`, which is the synchronous version
of the marker interface.
While these marker interfaces on the command messages might seem unnecessary,
they are actually quite important. They solve a key problem that execution
abstractions face: whether a command execution is synchronous or asynchronous
(as well as void or value-returning) should *not* be abstracted away since
otherwise you can end up in two common anti-patterns (i.e. [async guidelines for ASP.NET](https://github.com/davidfowl/AspNetCoreDiagnosticScenarios/blob/master/AsyncGuidance.md)),
known as [sync over async](https://devblogs.microsoft.com/pfxteam/should-i-expose-synchronous-wrappers-for-asynchronous-methods/) and
[async over sync](https://devblogs.microsoft.com/pfxteam/should-i-expose-asynchronous-wrappers-for-synchronous-methods/).
Likewise, mistakes cannot be made when implementing the handler, since the
handler interfaces define constraints on what the commands must implement:
```csharp
// sync
public interface ICommandHandler : ... where TCommand : ICommand;
public interface ICommandHandler : ... where TCommand : ICommand;
// async
public interface IAsyncCommandHandler : ... where TCommand : IAsyncCommand;
public interface IAsyncCommandHandler : ... where TCommand : IAsyncCommand
// async stream
public interface IStreamCommandHandler: ... where TCommand : IStreamCommand
```
This design choice also makes it impossible to end up executing a command
implementation improperly.
In addition to execution, the `IMessageBus` also provides a mechanism to determine
if a command has a registered handler at all via the `CanHandle` method as well
as a validation mechanism via `CanExecute`, as shown above in the `FindDocumentsHandler` example.
Commands can notify new events, and event observers/subscribers can in turn
execute commands.
### Async Streams
For .NET6+ apps, *Merq* also supports [async streams](https://learn.microsoft.com/en-us/dotnet/csharp/asynchronous-programming/generate-consume-asynchronous-stream)
as a command invocation style. This is useful for scenarios where the command
execution produces a potentially large number of results, and the consumer
wants to process them as they are produced, rather than waiting for the entire
sequence to be produced.
For example, the filter documents command above could be implemented as an
async stream command instead:
```csharp
record FindDocuments(string Filter) : IStreamCommand;
class FindDocumentsHandler : IStreamCommandHandler
{
public bool CanExecute(FindDocument command) => !string.IsNullOrEmpty(command.Filter);
public async IAsyncEnumerable ExecuteAsync(FindDocument command, [EnumeratorCancellation] CancellationToken cancellation)
{
await foreach (var file in FindFilesAsync(command.Filter, cancellation))
yield return file;
}
}
```
In order to execute such command, the only execute method the compiler will allow
is:
```csharp
await foreach (var file in bus.ExecuteStream(new FindDocuments("*.json")))
Console.WriteLine(file);
```
## Analyzers and Code Fixes
Beyond the compiler complaining, *Merq* also provides a set of analyzers and
code fixes to learn the patterns and avoid common mistakes. For example, if you
created a simple record to use as a command, such as:
```csharp
public record Echo(string Message);
```
And then tried to implement a command handler for it:
```csharp
public class EchoHandler : ICommandHandler
{
}
```
the compiler would immediately complain about various contraints and interfaces
that aren't satisfied due to the requirements on the `Echo` type itself. For
a seasoned *Merq* developer, this is a no-brainer, but for new developers,
it can be a bit puzzling:
A code fix is provided to automatically implement the required interfaces
in this case:
Likewise, if a consumer attempted to invoke the above `Echo` command asynchronously
(known as the [async over sync anti-pattern](https://devblogs.microsoft.com/pfxteam/should-i-expose-asynchronous-wrappers-for-synchronous-methods/)),
they would get a somewhat unintuitive compiler error:
But the second error is more helpful, since it points to the actual problem,
and a code fix can be applied to resolve it:
The same analyzers and code fixes are provided for the opposite anti-pattern,
known as [sync over async](https://devblogs.microsoft.com/pfxteam/should-i-expose-synchronous-wrappers-for-asynchronous-methods/),
where a synchronous command is executed asynchronously.
## Message Bus
The default implementation lives in a separate package [Merq.Core](https://www.nuget.org/packages/Merq.Core)
so that application components can take a dependency on just the interfaces.
[](https://www.nuget.org/packages/Merq.Core)
[](https://www.nuget.org/packages/Merq.Core)
The default implementation of the message bus interface `IMessageBus` has
no external dependencies and can be instantiated via the `MessageBus` constructor
directly.
The bus locates command handlers and event producers via the passed-in
`IServiceProvider` instance in the constructor:
```csharp
var bus = new MessageBus(serviceProvider);
// execute a command
bus.Execute(new MyCommand());
// observe an event from the bus
bus.Observe().Subscribe(e => Console.WriteLine(e.Message));
```
When using [dependency injection for .NET](https://learn.microsoft.com/en-us/dotnet/core/extensions/dependency-injection),
the [Merq.DependencyInjection](https://www.nuget.org/packages/Merq.DependencyInjection) package
provides a simple mechanism for registering the message bus:
```csharp
var builder = WebApplication.CreateBuilder(args);
...
builder.Services.AddMessageBus();
```
All command handlers and event producers need to be registered with the
services collection as usual, using the main interface for the component,
such as `ICommandHandler` and `IObservable`.
> NOTE: *Merq* makes no assumptions about the lifetime of the registered
> components, so it's up to the consumer to register them with the desired
> lifetime.
To drastically simplify registration of handlers and producers, we
recommend the [Devlooped.Extensions.DependencyInjection.Attributed](https://www.nuget.org/packages/Devlooped.Extensions.DependencyInjection.Attributed/).
package, which provides a simple attribute-based mechanism for automatically
emitting at compile-time the required service registrations for all types
marked with the provided `[Service]` attribute, which also allows setting the
component lifetime, such as `[Service(ServiceLifetime.Transient)]` (default
lifetime is `ServiceLifetime.Singleton` for this source generator-based
package).
This allows to simply mark all command handlers and event producers as
`[Service]` and then register them all with a single line of code:
```csharp
builder.Services.AddServices();
```
### Telemetry and Monitoring
The core implementation of the `IMessageBus` is instrumented with `ActivitySource` and
`Metric`, providing out of the box support for [Open Telemetry](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/distributed-tracing-instrumentation-walkthroughs)-based monitoring, as well
as via [dotnet trace](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/dotnet-trace)
and [dotnet counters](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/dotnet-counters).
To export telemetry using [Open Telemetry](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/distributed-tracing-instrumentation-walkthroughs),
for example:
```csharp
using var tracer = Sdk
.CreateTracerProviderBuilder()
.SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("ConsoleApp"))
.AddSource(source.Name)
.AddSource("Merq")
.AddConsoleExporter()
.AddZipkinExporter()
.AddAzureMonitorTraceExporter(o => o.ConnectionString = config["AppInsights"])
.Build();
```
Collecting traces via [dotnet-trace](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/dotnet-trace):
```shell
dotnet trace collect --name [PROCESS_NAME] --providers="Microsoft-Diagnostics-DiagnosticSource:::FilterAndPayloadSpecs=[AS]Merq,System.Diagnostics.Metrics:::Metrics=Merq"
```
Monitoring metrics via [dotnet-counters](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/dotnet-counters):
```shell
dotnet counters monitor --process-id [PROCESS_ID] --counters Merq
```
Example rendering from the included sample console app:
## Duck Typing Support
Being able to loosely couple both events (and their consumers) and command execution (from their
command handler implementations) is a key feature of Merq. To take this decoupling to the extreme,
Merq allows a similar capability as allowed by the TypeScript/JavaScript in VSCode: you can just
copy/paste an event/command definition as *source* into your assembly, and perform the regular
operations with it (like `Observe` an event and `Execute` a command), in a "duck typing" manner.
As long as the types' full name match, the conversion will happen automatically. Since this
functionality isn't required in many scenarios, and since there are a myriad ways to implement
such an object mapping functionality, the `Merq.Core` package only provides the hooks to enable
this, but does not provide any built-in implementation for it. In other words, no duck typing
is performed by default.
The [Merq.AutoMapper](https://www.nuget.org/packages/Merq.AutoMapper) package provides one such
implementation, based on the excelent [AutoMapper](https://automapper.org/) library. It can be
registered with the DI container as follows:
```csharp
builder.Services.AddMessageBus();
// register all services, including handlers and producers
builder.Services.AddServices();
```
# Dogfooding
[](https://pkg.kzu.dev/index.json)
[](https://github.com/devlooped/Merq/actions)
We also produce CI packages from branches and pull requests so you can dogfood builds as quickly as they are produced.
The CI feed is `https://pkg.kzu.dev/index.json`.
The versioning scheme for packages is:
- PR builds: *42.42.42-pr*`[NUMBER]`
- Branch builds: *42.42.42-*`[BRANCH]`.`[COMMITS]`
# Sponsors
[](https://github.com/clarius)
[](https://github.com/KirillOsenkov)
[](https://github.com/MFB-Technologies-Inc)
[](https://github.com/decriptor)
[](https://github.com/torutek-gh)
[](https://github.com/drivenet)
[](https://github.com/dgnaegi)
[](https://github.com/AshleyMedway)
[](https://github.com/Keflon)
[](https://github.com/tbolon)
[](https://github.com/kfrancis)
[](https://github.com/twenzel)
[](https://github.com/Giorgi)
[](https://github.com/MikeCodesDotNET)
[](https://github.com/dansiegel)
[](https://github.com/rbnswartz)
[](https://github.com/jfoshee)
[](https://github.com/Mrxx99)
[](https://github.com/eajhnsn1)
[](https://github.com/mackayn)
[](https://github.com/certifytheweb)
[](https://github.com/IxTechnologies)
[](https://github.com/davidjenni)
[](https://github.com/Jonathan-Hickey)
[](https://github.com/okyrylchuk)
[](https://github.com/akunzai)
[](https://github.com/jakobt)
[](https://github.com/seanalexander)
[](https://github.com/tinohager)
[](https://github.com/ploeh)
[](https://github.com/angelobelchior)
[](https://github.com/KenBonny)
[](https://github.com/SimonCropp)
[](https://github.com/agileworks-eu)
[](https://github.com/sorahex)
[](https://github.com/arsdragonfly)
[](https://github.com/vezel-dev)
[](https://github.com/sponsors/devlooped)
[Learn more about GitHub Sponsors](https://github.com/sponsors)