NATS .NET

NATS.Net is designed to work across multiple .NET platforms. While the API surface is consistent, some features vary based on the capabilities of the target framework.

Supported target frameworks include:

• netstandard2.0: Compatible with .NET Framework 4.6.1+, .NET Core 2.0+, Mono, Xamarin, and Unity.
• netstandard2.1: Compatible with .NET Core 3.0+.
• net8.0: .NET 8.
• net10.0: .NET 10.

JetStream is a built-in distributed persistence system for NATS that provides temporal decoupling between publishers and subscribers. Unlike Core NATS, where subscribers only receive messages published while they are actively connected, JetStream uses Streams to capture and store messages, allowing clients to 'replay' or consume messages at any time.

To use JetStream, you must enable it on your NATS server using the -js flag.

# Run nats-server with JetStream enabled
nats-server -js

# Or using Docker
docker run nats -js

A JetStream Context is the primary entry point for managing JetStream in NATS.NET. It is responsible for creating, configuring, and controlling streams, and it also provides methods to manage consumers directly without needing to reference a stream first. You create a context using an existing NATS connection.

// Create a JetStream context using an existing NATS connection
var js = connection.CreateJetStreamContext();

The ServerError event provides an args.Kind property, which is a NatsServerErrorKind enum value parsed from the raw error text. If the parser does not recognize the error, it defaults to NatsServerErrorKind.Unknown. For errors not covered by the enum, you should match against the raw string in args.Error.

connection.ServerError += (args) => 
{
    switch (args.Kind)
    {
        case NatsServerErrorKind.PermissionsViolation:
            // Handle permission denial
            break;
        case NatsServerErrorKind.AuthorizationViolation:
            // Handle authorization failure
            break;
        // ... other cases
        default:
            // Handle unknown or unmapped errors using args.Error
            break;
    }
};

In the NATS .NET demo, the receiver listens to the subject hello.my_room.>.

The > character is a wildcard that matches any subject starting with hello.my_room.. For example, a sender publishing to hello.my_room.chat or hello.my_room.updates will both be received by the subscriber.

JetStream relies on two primary abstractions:

1. Streams: These are message stores. A stream captures messages published to specific NATS subjects (which can include wildcards like orders.>). Streams define how messages are retained (duration, size, interest).
2. Consumers: A consumer is a stateful view of a stream. It acts as an interface for clients to consume a subset of messages. Consumers are stored on the NATS server, which tracks which messages have been delivered and acknowledged, removing the need for clients to manage state manually.

The Object Store is a client-side construct used to store and retrieve large objects (of any size) using a key-based system. It uses JetStream as the underlying persistence engine. While similar to the Key-Value Store, Object Store is specifically designed for handling large data like files by chunking them under the hood.

To use Object Store, the NATS server must be running with JetStream enabled using the -js flag.

JetStream supports idempotent message writes by ignoring duplicate messages based on a unique Message ID.

Note that the Message ID is not part of the message payload itself; instead, it must be passed as metadata within the message headers. When the server receives a message with a header ID it has already processed for that stream, it will ignore the duplicate.

You can configure TLS client authentication using the NatsTlsOpts.ConfigureClientAuthentication property. The type used for this configuration depends on your target framework:

• For netstandard2.0: The library uses a polyfill type NATS.Client.Core.SslClientAuthenticationOptions. This polyfill supports a subset of properties:
  • TargetHost
  • EnabledSslProtocols
  • ClientCertificates
  • CertificateRevocationCheckMode
  • RemoteCertificateValidationCallback
  • LocalCertificateSelectionCallback
• For netstandard2.1, net8.0, or net10.0: The library uses the standard BCL type System.Net.Security.SslClientAuthenticationOptions.

If your application requires the full range of SslClientAuthenticationOptions features, target netstandard2.1 or higher.