ResearchCave.Messaging (1.1.44)
Installation
dotnet nuget add source --name ResearchCave --username your_username --password your_token http://git.researchcave.com/api/packages/ResearchCave/nuget/index.jsondotnet add package --source ResearchCave --version 1.1.44 ResearchCave.MessagingAbout this package
Wolverine and NATS messaging defaults for ResearchCave applications.
ResearchCave.Messaging
Shared Wolverine + NATS messaging defaults for ResearchCave microservices.
Install
Reference the package from your service project:
<PackageReference Include="ResearchCave.Messaging" Version="1.0.0" />
Or reference the project directly while developing locally.
Configure NATS
Add a Nats section to appsettings.json:
{
"Nats": {
"Url": "nats://researchcave:rc_is_nats@server:4222",
"QueueGroup": "sentient",
"EnableJetStream": true,
"StreamMaxAge": "30.00:00:00",
"TimeoutSeconds": 5
}
}
Recommended keys:
Url: NATS broker URL. Credentials may be included in the URL.Enabled: disables NATS transport when set tofalse.QueueGroup: stable consumer name. With JetStream, replicas sharing this value consume from the same durable cursor; different microservices must use different values.EnableJetStream: enables durable stream and consumer support.StreamMaxAge: how long missed events remain replayable; the default is 30 days.AutoListenToSubjectWildcard: opt-in catch-all listener for<SubjectPrefix>.>. Leave it disabled when registering explicit listeners to prevent duplicate message handling.TimeoutSeconds: timeout used by broker health checks and connection probes.HealthCheckEnabled: disables the NATS health check when set tofalse.
Service Names
You can point Nats:Url at any host name your environment can resolve. This works well with Docker Compose service names, Kubernetes service DNS, Consul DNS, or normal DNS:
{
"Nats": {
"Url": "nats://nats:4222",
"QueueGroup": "sentient",
"TimeoutSeconds": 5
}
}
ResearchCave.Messaging does not own service discovery. It passes the configured NATS URL to Wolverine. Keep service discovery, DNS, and deployment-specific name resolution in ResearchCave.ServiceDefaults or your hosting environment.
Register Messaging
In Program.cs:
using ResearchCave.Messaging.Extensions;
var builder = WebApplication.CreateBuilder(args);
builder.AddResearchCaveMessaging();
var app = builder.Build();
app.Run();
The extension configures:
- Wolverine
- NATS transport
- ResearchCave serialization defaults
- retry policy
- NATS broker health check
- optional durable inbox/outbox defaults
- optional durable local queues
- ResearchCave message subject helpers
Send Messages
Inject Wolverine's IMessageBus:
using Wolverine;
public sealed class OrdersService(IMessageBus bus)
{
public Task PublishAsync(OrderCreated message, CancellationToken cancellationToken)
=> bus.PublishAsync(message).AsTask();
}
Handle Messages
Create a handler class in your service:
public static class OrderCreatedHandler
{
public static Task Handle(OrderCreated message, CancellationToken cancellationToken)
{
// handle message
return Task.CompletedTask;
}
}
Message Naming
Use simple message types for cross-service contracts:
public sealed record OrderCreated(Guid OrderId, DateTimeOffset CreatedAt);
The library includes subject naming helpers:
using ResearchCave.Messaging.Conventions;
var subject = ResearchCaveMessageConventions.SubjectFor<OrderCreated>();
// researchcave.order.created
Advanced Overrides
The library owns sensible ResearchCave defaults for Wolverine, NATS, retry, serialization, and health checks. JetStream and durable queues are opt-in so the same service can use plain NATS for transient events and JetStream for durable endpoints.
Configure service-specific message topology in the Wolverine callback:
builder.AddResearchCaveMessaging(
options =>
{
options.SubjectPrefix = "researchcave";
options.StreamName = "RESEARCHCAVE";
},
wolverine =>
{
wolverine.PublishMessage<OrderCreated>()
.ToNatsSubject("researchcave.orders.created");
wolverine.ListenToNatsSubject("researchcave.orders.critical")
.UseJetStream("RESEARCHCAVE");
});
For most microservices, prefer the simple Nats config section and builder.AddResearchCaveMessaging().