Table of Contents


NATS.Net is a .NET client for the open source Connective Technology for Adaptive Edge & Distributed Systems - NATS! It's build on top of the modern .NET platform, taking advantage of all the high performance features and asynchronous programming model.

NATS.Net, just like NATS, is open source as is this documentation. Please let us know if you have updates or suggestions for these docs. You can also create a Pull Request in GitHub using the Edit this page link on each page.

Quick Start

You can download the latest nats-server for your platform and run it without any arguments.

$ nats-server

nats-server will listen on its default TCP port 4222. By default nats-server will not support persistence and only provide the foundational messaging features also called Core NATS. You can also enable JetStream by passing the -js flag to nats-server and enable persistence and other advanced features.

If you prefer using containers, you can also run the latest NATS server image using Docker:

$ docker run nats

Here are some quick examples to get you started with NATS.Net:

Core NATS is the basic messaging functionality. Messages can be published to a subject and received by one or more subscribers listening to the same subject only when they are running. There is no persistence and messages are not stored anywhere.

Start NATS server with default options:

$ nats-server

Reference NATS.Net NuGet package in your project:

await using var nats = new NatsConnection();

var cts = new CancellationTokenSource();

var subscription = Task.Run(async () =>
    await foreach (var msg in nats.SubscribeAsync<string>(subject: "foo").WithCancellation(cts.Token))
        Console.WriteLine($"Received: {msg.Data}");

// Give subscription time to start
await Task.Delay(1000);

for (var i = 0; i < 10; i++)
    await nats.PublishAsync(subject: "foo", data: $"Hello, World! {i}");

// Give subscription time to receive messages
await Task.Delay(1000);

// Unsubscribe

await subscription;

Every NatsConnection instance is a TCP connection to a NATS server. Typically an application will only need one connection and many subscriptions and publishers would share that same connection. Connections are relatively heavyweight and expensive to create while subscriptions and publishers are lightweight internal NATS protocol handlers. NATS.Net should be able to handle large numbers of subscriptions and publishers per connection.

Now you should be able to run NATS server on your machine and use the above code samples to see the basics of NATS messaging and persistence.

What's Next

Core NATS is the base set of functionalities and qualities of service offered by a NATS service infrastructure.

JetStream is the distributed persistence system built-in to the same NATS server binary.

Key/Value Store is the built-in distributed persistent associative arrays built on top of JetStream.

Object Store is the built-in distributed persistent objects of arbitrary size built on top of JetStream.

Services is the services protocol built on top of core NATS enabling discovery and monitoring of services you develop.