Introduction

NATS .NET is a .NET client for the open source NATS messaging system. It's built on top of the modern .NET platform, taking advantage of 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.

Note

Don't confuse NuGet packages! NATS .NET package on NuGet is called NATS.Net. There is another package called NATS.Client which is the older version of the client library and will be deprecated eventually.

Tip

NATS .NET now supports .NET Standard 2.0 and 2.1 along with .NET 6.0 and 8.0, which means you can also use it with .NET Framework 4.6.2+ and Unity 2018.1+.

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 or Podman, for example:

$ docker run nats

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

Core NATS
JetStream

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. Messages are not stored anywhere.

Start NATS server with default options:

$ nats-server

$ docker run nats

Reference NATS.Net NuGet package in your project:

await using var nc = new NatsClient();

// We will use a cancellation token to stop the subscription
using var cts = new CancellationTokenSource();

var subscription = Task.Run(async () =>
{
    await foreach (var msg in nc.SubscribeAsync<string>(subject: "greet.*", cancellationToken: cts.Token))
    {
        Console.WriteLine($"Received: {msg.Subject}: {msg.Data}");
    }
});

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

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

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

// Unsubscribe
await cts.CancelAsync();

await subscription;

JetStream is the distributed persistence system built-in to the same NATS server binary. Messages published to JetStream are stored on the NATS JetStream server and can be retrieved by consumers any time after publishing.

Start NATS server with JetStream enabled:

$ nats-server -js

$ docker run nats -js

Reference NATS.Net NuGet package in your project:

await using var nc = new NatsClient();
var js = nc.CreateJetStreamContext();

// Create a stream to store the messages those subjects start with "orders."
await js.CreateStreamAsync(new StreamConfig(name: "ORDERS", subjects: ["orders.>"]));

for (var i = 0; i < 10; i++)
{
    // Publish a message to the stream. The message will be stored in the stream
    // because the published subject matches one of the the stream's subjects.
    var ack = await js.PublishAsync(subject: $"orders.new.{i}", data: $"order {i}");

    // Ensure the message is stored in the stream.
    // Returned ack makes the JetStream publish different from the core publish.
    ack.EnsureSuccess();
}

// Create a consumer to receive the messages
var consumer = await js.CreateOrUpdateConsumerAsync("ORDERS", new ConsumerConfig("order_processor"));

// We will use a cancellation token to stop the consume loop
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(3));

await foreach (var jsMsg in consumer.ConsumeAsync<string>(cancellationToken: cts.Token))
{
    Console.WriteLine($"Processed: {jsMsg.Subject}: {jsMsg.Data} ({jsMsg.Metadata?.Sequence.Stream}/{jsMsg.Metadata?.NumPending})");

    // Acknowledge the message is processed and the consumer can move to the next message
    await jsMsg.AckAsync(cancellationToken: cts.Token);
}

Now you should be able to run the 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 Service Protocol built on top of core NATS enabling discovery and monitoring of services you develop.

Table of Contents

Introduction

Note

Tip

Quick Start

What's Next