A modern, annotation-based SDK for building reliable distributed systems with NATS. Define your message consumers with simple attributes and let the framework handle the complexity.
NATS is a powerful messaging system that enables you to build sophisticated, fault-tolerant distributed systems that are location-transparent and globally distributed.
- Faster than HTTP - Binary protocol with lower overhead
- Fewer hops - Direct communication without load balancers or API gateways
- Globally distributed - Deploy applications worldwide without DNS or complex load balancing. Learn more about NATS super clusters
💡 Learn more: Check out this podcast from nats.fm for insights into NATS architecture.
Modern developers expect annotation-based definitions and dependency injection—the same developer experience you get with REST frameworks like ASP.NET Core. This SDK brings that same simplicity to NATS, so you can focus on your business logic instead of boilerplate.
- ✨ Annotation-based consumers - Define subscribers with simple attributes
- 🛡️ Built-in backpressure - Automatic handling of traffic spikes
- ⚖️ Flexible load balancing - Choose between broadcasting or load balancing strategies
- 🚀 JetStream support - Build temporally decoupled systems with persistent messaging
- 🔧 Dependency injection - Seamless integration with .NET's DI container
- ✅ Automatic message validation - Messages with a
Validate()method are automatically validated before processing. Invalid messages are never sent to your handlers. - 🪝 Consumer interceptors - Inspect, replace, or reject messages before handlers run
- 🧯 Consumer exception handlers - Map handler exceptions to a
NatsAckfor consistent JetStream ack/nak and Core request/reply responses, while still logging the original exception and recording the invocation as a failure
🎯 Building microservices? Check out our microservices-focused SDK built on top of
cloops.natsand makes building microservices a breeze!
Add the cloops.nats package to your .csproj file:
<PackageReference Include="cloops.nats" Version="*" />Run dotnet restore to install the package.
💡 Tip: Bring in your schema package for message governance. See more details in schema example
Broadcast Pattern (Kubernetes/Docker)
Ensure each pod/instance receives all messages by using runtime placeholders in the queue group name:
/// <summary>
/// Broadcast: Each pod gets a unique queue group, so all pods receive all messages
/// Supported placeholders: {POD_NAME}, {HOSTNAME}, {MACHINE_NAME}, {ENV:VAR_NAME}
/// </summary>
[NatsConsumer("test.broadcast", QueueGroupName = "pod-{POD_NAME}")]
public Task<NatsAck> BroadcastHandler(NatsMsg<string> msg, CancellationToken ct = default)
{
Console.WriteLine($"[Pod {Environment.GetEnvironmentVariable("POD_NAME")}] Received: {msg.Data}");
return Task.FromResult(new NatsAck(true));
}Load Balancing Pattern
Distribute messages across multiple instances using the same queue group:
[NatsConsumer("test.lb", QueueGroupName = "workers")]
public async Task<NatsAck> HandleMessage(NatsMsg<string> msg, CancellationToken ct = default)
{
Console.WriteLine($"Instance received: {msg.Data}");
await Task.Delay(100, ct).ConfigureAwait(false); // Simulate work
return new NatsAck(true);
}Runtime Placeholders
The SDK resolves placeholders dynamically:
{POD_NAME}→POD_NAMEenv var, falls back toHOSTNAMEor machine name{HOSTNAME}→HOSTNAMEenv var, falls back to machine name{MACHINE_NAME}→ Machine name{ENV:VAR_NAME}→ Any environment variable (e.g.,{ENV:MY_CUSTOM_VAR})
📝 Note:
QueueGroupNameis optional. If omitted, an empty string is used, which still enables load balancing. JetStream subscriptions are always load-balanced (no broadcast support).
- 📖 Examples - See real-world usage patterns
- 📚 Full Documentation - Detailed guides, setup instructions, and API reference
Contributions are welcome! Please feel free to submit a Pull Request.
This project is licensed under the MIT License - see the LICENSE file for details.