From 1fbd7e87a2a1729a46e76b5a35944b7b0edade15 Mon Sep 17 00:00:00 2001 From: Gabriele Santomaggio Date: Wed, 3 Jun 2026 11:23:45 +0200 Subject: [PATCH 1/2] update documentation Signed-off-by: Gabriele Santomaggio --- docs/Documentation/StreamSystemUsage.cs | 22 ++++++++++++++++++++++ docs/asciidoc/api.adoc | 13 ++----------- 2 files changed, 24 insertions(+), 11 deletions(-) diff --git a/docs/Documentation/StreamSystemUsage.cs b/docs/Documentation/StreamSystemUsage.cs index 628439bf..05c3afd6 100644 --- a/docs/Documentation/StreamSystemUsage.cs +++ b/docs/Documentation/StreamSystemUsage.cs @@ -153,6 +153,28 @@ private static async Task CreateAddressResolver() await streamSystem.Close().ConfigureAwait(false); } // end::create-address-resolver[] + + + // tag::create-dsn-address-resolver[] + private static async Task CreateDnsAddressResolver() + { + var dnsResolver = new DnsAddressResolver(new DnsEndPoint("rabbitmq-stream.my-cluster.local", 5552)); // <1> + + var streamSystem = await StreamSystem.Create( + new StreamSystemConfig() + { + UserName = "myuser", + Password = "mypassword", + AddressResolver = dnsResolver, // <2> + Endpoints = new List {dnsResolver.EndPoint} // <3> + } + ).ConfigureAwait(false); + + + await streamSystem.Close().ConfigureAwait(false); + } + // end::create-dns-address-resolver[] + // tag::stream-creation[] private static async Task CreateStream() diff --git a/docs/asciidoc/api.adoc b/docs/asciidoc/api.adoc index a8023f0f..c0dc5bbd 100644 --- a/docs/asciidoc/api.adoc +++ b/docs/asciidoc/api.adoc @@ -307,7 +307,7 @@ The blog post covers the https://blog.rabbitmq.com/posts/2021/07/connecting-to-s [[dns-address-resolver]] ====== Using DNS Round-Robin Instead of a Load Balancer -Starting from version 1.12 (https://github.com/rabbitmq/rabbitmq-stream-dotnet-client/pull/466[#466]), the client ships a built-in `DnsAddressResolver` that relies on DNS round-robin instead of a dedicated load balancer. +`DnsAddressResolver` relies on DNS round-robin instead of a dedicated load balancer. This is useful when the cluster nodes are exposed behind a single DNS name that resolves to multiple `A`/`AAAA` records (for example a Kubernetes headless service or a DNS-based service discovery setup). Instead of routing every connection through a load balancer, the client resolves the DNS name on each connection attempt and picks one of the returned IP addresses, distributing connections across the cluster nodes. @@ -315,16 +315,7 @@ This is useful when the cluster nodes are exposed behind a single DNS name that .Using the DNS address resolver [source,c#,indent=0] --------- -var dnsResolver = new DnsAddressResolver(new DnsEndPoint("rabbitmq-stream.my-cluster.local", 5552)); // <1> - -var streamSystem = await StreamSystem.Create( - new StreamSystemConfig - { - AddressResolver = dnsResolver, // <2> - Endpoints = new List { dnsResolver.EndPoint } // <3> - }).ConfigureAwait(false); --------- +include::{test-examples}/StreamSystemUsage.cs[tag=create-dsn-address-resolver] <1> Create the resolver with the `DnsEndPoint` (host and port) shared by all cluster nodes <2> Use the DNS resolver to resolve node addresses before each connection From 15904d049ecf6546df2431f4e34da232a81a82e4 Mon Sep 17 00:00:00 2001 From: Gabriele Santomaggio Date: Wed, 3 Jun 2026 11:41:56 +0200 Subject: [PATCH 2/2] update documentation Signed-off-by: Gabriele Santomaggio --- RabbitMQ.Stream.Client/IAddressResolver.cs | 5 +++++ RabbitMQ.Stream.Client/PublicAPI.Unshipped.txt | 1 + docs/asciidoc/api.adoc | 14 +++++++++++++- 3 files changed, 19 insertions(+), 1 deletion(-) diff --git a/RabbitMQ.Stream.Client/IAddressResolver.cs b/RabbitMQ.Stream.Client/IAddressResolver.cs index 29fb9bd1..27bf3f43 100644 --- a/RabbitMQ.Stream.Client/IAddressResolver.cs +++ b/RabbitMQ.Stream.Client/IAddressResolver.cs @@ -2,6 +2,7 @@ // 2.0, and the Mozilla Public License, version 2.0. // Copyright (c) 2017-2023 Broadcom. All Rights Reserved. The term "Broadcom" refers to Broadcom Inc. and/or its subsidiaries. +using System; using System.Net; using System.Threading.Tasks; @@ -10,5 +11,9 @@ namespace RabbitMQ.Stream.Client; public interface IAddressResolver { public bool Enabled { get; } + + [Obsolete("Deprecated. Use ResolveAsync instead.")] + public EndPoint Resolve(string address, int port); + public Task ResolveAsync(string address, int port); } diff --git a/RabbitMQ.Stream.Client/PublicAPI.Unshipped.txt b/RabbitMQ.Stream.Client/PublicAPI.Unshipped.txt index 5ac81bf6..9afdc158 100644 --- a/RabbitMQ.Stream.Client/PublicAPI.Unshipped.txt +++ b/RabbitMQ.Stream.Client/PublicAPI.Unshipped.txt @@ -179,6 +179,7 @@ RabbitMQ.Stream.Client.HashRoutingMurmurStrategy.Route(RabbitMQ.Stream.Client.Me RabbitMQ.Stream.Client.HeartBeatHandler.HeartBeatHandler(System.Func> sendHeartbeatFunc, System.Func> close, int heartbeat, Microsoft.Extensions.Logging.ILogger logger = null) -> void RabbitMQ.Stream.Client.IAddressResolver RabbitMQ.Stream.Client.IAddressResolver.Enabled.get -> bool +RabbitMQ.Stream.Client.IAddressResolver.Resolve(string address, int port) -> System.Net.EndPoint RabbitMQ.Stream.Client.IAddressResolver.ResolveAsync(string address, int port) -> System.Threading.Tasks.Task RabbitMQ.Stream.Client.IClient.ClientId.get -> string RabbitMQ.Stream.Client.IClient.ClientId.init -> void diff --git a/docs/asciidoc/api.adoc b/docs/asciidoc/api.adoc index c0dc5bbd..a228e347 100644 --- a/docs/asciidoc/api.adoc +++ b/docs/asciidoc/api.adoc @@ -323,7 +323,19 @@ include::{test-examples}/StreamSystemUsage.cs[tag=create-dsn-address-resolver] On every connection the resolver calls `ResolveAsync(...)`, which performs a DNS lookup of the configured host and returns one of the resolved IP addresses, achieving round-robin distribution across the nodes the DNS name points to. -NOTE: `DnsAddressResolver` ignores the per-node metadata hints returned by the broker, exactly like the custom load-balancer resolver above. The difference is that the node selection is driven by DNS resolution rather than by a load balancer. +NOTE: `DnsAddressResolver` ignores the per-node metadata hints returned by the broker, exactly like the custom load-balancer resolver above. +The difference is that the node selection is driven by DNS resolution rather than by a load balancer. + +You can use tour own implementation of `IAddressResolver` to implement custom address resolution strategies, +for example based on service discovery or other mechanisms. + +[NOTE] +.IAddressResolver Derepcation +==== +Starting from version 1.12.0 the `Resolve` field is deprecated. +Use `ResolveAsync` instead. +==== + ===== Managing Streams