NATS .NET v2.5.1

Patch fix release.

What's Changed

• Update docs using the simple client by @mtmk in #655
  Added NatsOpts to NatsClient constructor. (Note that documentation update is for the repo GitHub pages docs site.)

Full Changelog: v2.5.0...v2.5.1

NATS .NET v2.5.0

We're happy to announce a new release of NATS .NET version 2.5.0 with new NatsClient extensions. With this release we are completing the features required for a simplified client initialization for ease of use especially for newcomers.

New Features

• Add JetStream NATS Client Extensions by @mtmk in #598
• Add other client extensions by @mtmk in #637

New extensions to INatsClient enables context creation easily.

using NATS.Net;

await using var nc = new NatsClient();

// Serializer does the expected thing with all types
await nc.PublishAsync("x.int", 100);
await nc.PublishAsync("x.string", "Hello, World!");
await nc.PublishAsync("x.bytes", new byte[] { 65, 66, 67 });
await nc.PublishAsync("x.json", new MyData(30, "bar"));

// ...and now you can create the contexts from the client
var js = nc.CreateJetStreamContext();
var kv = nc.CreateKeyValueStoreContext();
var obj = nc.CreateObjectStoreContext();
var svc = nc.CreateServicesContext();

Contexts are also refactored to accept interfaces rather than implementations (see breaking changes below)

• Added Domain support for stream mirroring and sourcing and KV full support for the same. by @darkwatchuk in #631

With this addition you can now setup your KV stores with mirroring support. We still have a bit more work to do with #642 to add domains.

Fixes

• Run core tests on Windows and test run stability by @mtmk in #464
• Adds type-forwarders NET 5.0+ by @VaticanUK in #641
• Add placement configuration to key-value and object store by @mtmk in #650

Security

• Bump System.Text.Json from 8.0.4 to 8.0.5 in /src/NATS.Client.Core by @dependabot in #649

Breaking Changes

Contexts now take interfaces instead of implementations. This helps us with creating various extensions as well as making it easier to unit test application code:

- public NatsJSContext(NatsConnection connection)
+ public NatsJSContext(INatsConnection connection)

- public NatsKVContext(NatsJSContext context)
+ public NatsKVContext(INatsJSContext context)

- public NatsObjContext(NatsJSContext context)
+ public NatsObjContext(INatsJSContext context)

- public NatsSvcContext(NatsConnection nats)
+ public NatsSvcContext(INatsConnection nats)

Code should compile without any issues but we're probably braking binary compatibility and you might want to refactor your code if you were working around the fact these constructors were not using interfaces.

New Contributors

• @VaticanUK made their first contribution in #641

Thank You

A big thank you to our contributors.

Happy coding ❤️

Full Changelog: v2.4.0...v2.5.0

NATS .NET v2.4.0

We are excited to announce the release of NATS .NET v2.4.0! This version brings a host of new features, enhancements, and bug fixes to improve your experience with the NATS .NET client.

New Features

New Simplified NatsClient API (Experimental)

• Add NATS client implementation by @mtmk in #589
• Simplified NATS client by @mtmk in #607

We've introduced a new, simplified NATS client implementation that makes initialization easier with common defaults, like JSON serialization for ad hoc types—great for newcomers!

Note that this new API is experimental at this stage and we will be implementing JetStream, KV, ObjectStore and Services extensions in the next minor release 2.5.x.

// Simpler initialization
await using var client = new NatsClient("nats://localhost:4222");

// Already setup with most common serialization scenarios
await client.PublishAsync("x.int", 100);
await client.PublishAsync("x.string", "Hello, World!");
await client.PublishAsync("x.bytes", new byte[] { 65, 66, 67 });
await client.PublishAsync("x.json", new MyData(30, "bar"));

Please note that this new interface is added alongside the existing INatsConnection interface, and existing applications are not affected by it.

WebSocket Improvements

• NatsOpts.ConfigureWebSocketOpts callback handler by @wolfman42 in #605
• Nats web socket opts improvements by @Ivandemidov00 in #623

This change allows setting an authorization header and a callback for more connection setup options for WebSocket connections. Unfortunately because of browser restrictions not all the options (e.g. setting headers) won't work for WebAssembly projects. Thank you @wolfman42 for the idea, @Ivandemidov00 for options enhancement and also thanks to @caleblloyd for his help in shaping the API.

Nuid Public Type

• Make NuidWriter public by @Madgvox in #618

The Nuid class generates unique identifiers that can be used to ensure uniqueness in distributed systems. With this change we opened up this internal API for applications to use in their scenarios as well. Thank you @Madgvox for the idea and the implementation and thanks to @jasper-d for verifying the implementation and the API making sure it makes sense for the .NET ecosystem.

var id = Nuid.NewNuid();

Dependency Injection Improvements

• ServiceProvider callback for NATS DI configuration; by @william-liebert in #619

This change adds IServiceProvider overloads to configuration methods, to enable resolution-time configuration. Thank you @william-liebert for the implementation.

services.AddNatsClient(builder => builder.ConfigureOptions((provider, opts) => {
    var configurator = provider.GetRequiredService<MyOptsConfigurator>();
    return configurator.Configure(opts);
}));

Fixes

• Extensive logging for reconnect debugging by @mtmk in #593
• Add default timeout to initial commands by @mtmk in #594
• Fix various disposable issues by @Bykiev in #625
• Fixed consume pending message calculation by @mtmk in #626

Documentation

• Add clear next step navigation to API index doc by @johnweldon in #592
• Update docs by @mtmk in #595

Breaking Changes

There are breaking changes that might affect your applications, but most should be caught by the compiler as you build, if any. We don't expect many applications to be affected. However, there maybe some behavioral changes you might want to keep an eye on and test especially around the JetStream consume method. Again, we do not expect many applications affected by these changes.

Changes to INatsConnection interface and the New INatsClient Interface

INatsConnection now extends the new INatsClient interface, with commonly used methods moved into the new interface. With this change, you should not normally see any effects in your code, as the INatsConnection interface still implements the exact same members so it is not actually a breaking change. However, it's something to be aware of. The idea is that if you start implementing your application using INatsClient you should be able to swap it out with INatsConnection if you see the need to use more specialized members.

public interface INatsConnection : INatsClient { /* ...on top of INatsClient also implements more specialized members */ }
public interface INatsClient : IAsyncDisposable { /* implements most common members e.g. Publish and Subscribe... */ }

Changes to Log Messages

If you are monitoring log messages there are a few minimal changes that might affect your monitoring configuration.

- Trace "Connection {Name} is closed. Will cleanup and reconnect"
+ Debug "Connection {Name} is closed. Will cleanup and reconnect [{ReconnectCount}]"

- Information "Try to invoke OnConnectingAsync before connect to NATS"
+ Information "Try to invoke OnConnectingAsync before connect to NATS [{ReconnectCount}]"

- Information "Tried to connect NATS {Url}"
+ Information "Tried to connect NATS {Url} [{ReconnectCount}]"

- Information "Connection succeeded {Name}, NATS {Url}"
+ Information "Connection succeeded {Name}, NATS {Url} [{ReconnectCount}]"

- Error "Retry loop stopped and connection state is invalid"
+ Error "Retry loop stopped and connection state is invalid [{ReconnectCount}]"

JetStream Changes to Consume Pending Message Calculation

We had a back pressure handling issue with ConsumeAsync() method in JetStream consumers. If you are using that method and relying on how many messages are consumed and how fast or tweaked options for max-messages, bytes or thresholds please test you applications to make sure you are happy with the behaviour. We don't expect any issues but there maybe some cases that needs attention. Let us know if you have any questions about this.

For more details please check PR 626 and relevant discussions.

Thank You

A huge thank you to our amazing community and all the contributors for their invaluable support. We hope these updates enhance your experience with NATS .NET and make your development process smoother. Happy coding ❤️

New Contributors

• @johnweldon made their first contribution in #592
• @wolfman42 made their first contribution in #605
• @Madgvox made their first contribution in #618
• @Bykiev made their first contribution in #625
• @william-liebert made their first contribution in #619

Full Changelog: v2.3.3...v2.4.0

NATS .NET v2.3.3

This is a minor bug fix and improvements of NATS .NET release v2.3.3. Please check the notes below about minor breaking changes.

What's Changed

• Use string.Create when building a new inbox string by @jasper-d in #551
• Add logging enhancements and improve error handling by @mtmk in #570
• KV never set duplicate window by @scottf in #577
• Obj store empty list fixed by @Ivandemidov00 in #578
• Fetch idle timeout default fix by @mtmk in #582

Breaking Changes

• Base64 Encoding simplification + optimization by @to11mtm in #549:
  JetStream model NATS.Client.JetStream.Models.StoredMessage class' Data property type changed from string to ReadOnlyMemory<byte>. This is a Base64 encoded field which now is taken case of by System.Text.Json library to be serialized as binary data. KV and Object store implementations are updated to use this more efficient version of the property so if you're only using these high level APIs you won't need to do any changes. Otherwise you will have to update your code to use the new type and in most cases compiler should catch the code that needs updating.

• Resolved issue of ObjStore GetInfo MTime returning 0 by @darkwatchuk in #567:
  Another change to the same NATS.Client.JetStream.Models.StoredMessage class. Time property is changed from string to DataTimeOffset making it easier to deal with. Again, if you're not using the model directly you should not need any changes otherwise you'd need to update your code where compiler should catch the required change for you.

• Handle various protocol errors and socket exceptions by @mtmk in #584:
  This is a log level change, so you might want to update your monitoring setup if you're watching this particular log entry for NATS.Client.Core.Commands.CommandWriter logger. We demoted socket errors (which are expected during reconnect) to a warning and changed the message slightly. Please see #584 for the exact details.

New Contributors

• @ronnieoverby made their first contribution in #576

Full Changelog: v2.3.2...v2.3.3

Nuget Package

dotnet add package NATS.Net --version 2.3.3

NATS .NET v2.3.3-preview.1

Bug fix and improvements release.

Breaking

There is one breaking change to StoredMessage.Data type in #549

What's Changed

• Use string.Create when building a new inbox string by @jasper-d in #551
• Base64 Encoding simplification + optimization by @to11mtm in #549
• Add logging enhancements and improve error handling by @mtmk in #570 (this also fixes a service API bug around error reporting)

Full Changelog: v2.3.2...v2.3.3-preview.1

Nuget Package

dotnet add package NATS.Net --version 2.3.3-preview.1

NATS .NET v2.3.2

This is a small bugfix release.

What's Changed

• Bump System.Text.Json from 8.0.3 to 8.0.4 in /src/NATS.Client.Core by @dependabot in #559
• Remove timeout from readerTask in CommandWriter by @mtmk in #554

Full Changelog: v2.3.1...v2.3.2

Nuget Package

dotnet add package NATS.Net --version 2.3.2

NATS .NET v2.3.1

This release of NATS .NET version 2.3.1 addresses several bug fixes, primarily improving Unity builds, and introduces a few new features.

What's Changed

• Fixed version number sent to server and changed lang to .NET from C#.… by @darkwatchuk in #541
• netstandard Nullable ref fix in #542
• Add KV Filtering of keys by @darkwatchuk in #545
• Remove unnecessary comment and configuration modification in #537
• Full coverage kv management methods by @Ivandemidov00 in #535
• Fix il2cpp error in #548

Full Changelog: v2.3.0...v2.3.1

Nuget Package

dotnet add package NATS.Net --version 2.3.1

NATS .NET v2.3.0

🎉 Big News: .NET Standard Support for NATS .NET in Release 2.3.0! 🎉

We're thrilled to announce the latest update for NATS .NET, version 2.3.0, now with .NET Standard 2.0 and 2.1 support! This means you can seamlessly integrate it with both .NET Framework and Unity. 🚀

👉 Let us know how it goes and share your feedback!

Features

• Support for .NET Standard 2.0 and 2.1 #513
• Add TLS options for netstandard #524
• NETStandard TLS Parity by @caleblloyd in #527
• JetStream Concurrent Publish #532

Full Changelog: v2.2.3...v2.3.0

Thanks

We would like to thank our amazing community, especially @caleblloyd, @to11mtm, @rickdotnet, @galvesribeiro, @stebet, and @teo-tsirpanis for their invaluable contributions, reviews, and support in making .NET Standard support happen. ❤️

Nuget Package

dotnet add package NATS.Net --version 2.3.0

NATS .NET v2.3.0-preview.1

This is our first release with .NET Standard support. We worked very hard to avoid any changes for .NET 6.0 and .NET 8.0 targets, although there are a few minor nonfunctional changes. Please test your applications targeting .NET 6 and .NET 8 thoroughly and report any issues you find.

With this release, we now support .NET Standard 2.0 and 2.1, allowing you to use it in runtimes like .NET Framework and Unity. We utilized .NET Standard 2.1 APIs as much as possible to provide the best performance and compatibility that the target platforms offer.

TLS API Differences for .NET Standard

The underlying .NET TLS options differ significantly between .NET Standard and .NET 6 and 8, so we had to reflect those changes in our TLS options. If your application uses TLS, you will need to adapt to the different APIs for .NET Standard targets. Please reach out if you have any questions, and check the platform tests to see examples of how these different APIs can be used.

What's Changed

• Support for .NET Standard 2.0 and 2.1 by @mtmk in #513
• Add TLS options for netstandard by @mtmk in #524

Full Changelog: v2.2.3...v2.3.0-preview.1

Nuget Package

dotnet add package NATS.Net --version 2.3.0-preview.1

NATS .NET v2.2.3

We're happy to introduce NAT .NET v2.2.3! This update brings a few new features, a crucial fix for subscription object lifetime, and a minor adjustment that primarily affects the key-value store.

Features

• Add overload for empty requests by @mtmk in #502
• Add ResumeAtRevision support to KV Watcher by @niklasfp in #491

Fixes

• Keep sub alive when reading channel by @caleblloyd in #506
• Prefer sub channel ReadAllAsync and remove SubAnchor by @caleblloyd in #507
• Direct Message Header May Contain Multiple Subjects by @Ivandemidov00 in #512

Full Changelog: v2.2.2...v2.2.3

Nuget Package

dotnet add package NATS.Net --version 2.2.3

Getting Started with NATS .NET

Check out the introduction to using NATS .NET and NATS server for a quick start.