Skip to content

NATS .NET v2.4.0

Compare
Choose a tag to compare
@mtmk mtmk released this 17 Sep 20:10
· 25 commits to main since this release
5fb5a92

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)

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

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

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

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

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

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