Introduction

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
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. 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
cts.Cancel();

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

Reference NATS.Net NuGet package in your project:

await using var nats = new NatsConnection();
var js = new NatsJSContext(nats);

// Create a stream to store the messages
await js.CreateStreamAsync(new StreamConfig(name: "orders", subjects: new[] { "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", data: $"order {i}");
    ack.EnsureSuccess();
}

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

await foreach (var jsMsg in consumer.ConsumeAsync<string>())
{
    Console.WriteLine($"Processed: {jsMsg.Data}");
    await jsMsg.AckAsync();

    // Process only 10 messages
    // (message order might be different in different scenarios)
    if (jsMsg.Data == "order 9")
    {
        break;
    }
}

Note

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.

Table of Contents

Introduction

Quick Start

Note

What's Next