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
- 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
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