[Messaging] Minor updates for April 2025 release (Azure#49169)

* [Messaging] Minor updates for April 2025 release

The focus of these changes is to make a small set
of minor updates to the Azure Messaging libraries.
Included are:

- Clarifying the load balancing behavior of the
Event Hubs processor's load balancing strategies.

- Enhancing the retry policies for better support
in web socket scenarios.  It was observed that the
relevant failure information in many scenarios was
embedded in an inner `WebSocketException` and
wrapped by `WebSocketException`.  Going forward,
retry decisions will be made based on the inner
exception, if present.

- Added an option for a remote certificate validation
callback to the `ServiceBusClientOptions` in order
to allow applications to control validation behavior
and to align with the existing option in Event Hubs.

* Reverting copy/paste error

* Restoring accidental deletion

* Fixing test mocks

* Regenerating Event Hubs API

* Fixing missed Clone for the callback.

Author: jsquire

sdk/eventhub/Azure.Messaging.EventHubs.Processor/CHANGELOG.md

@@ -8,11 +8,12 @@
 
 ### Bugs Fixed
 
-- UpdateCheckpointAsync in the 'EventProcessorClient` was not awaiting the Checkpoint Stores 'UpdateCheckpointAsync' method.
-By not awaiting we were starting the OTel span and closing it almost immediately. The catch would've been ignored as well.
+- Fixed behavior in the `UpdateCheckpointAsync` method of `EventProcessorClient` to properly await the call to the checkpoint store.  Previously, this was not awaited, causing the OTel span to open and close almost immediately and skip reporting any errors observed.
 
 ### Other Changes
 
+- Enhanced retry logic to consider additional cases for web socket-based failures.  In many cases, a `WebSocketException` is triggered which wraps a `SocketException` with the details for the specific network conditions.  Retry decisions are now based on the internal exception, if present, to ensure retries are correctly applied.
+
 ## 5.12.0-beta.2 (2025-02-11)
 
 ### Acknowledgments

sdk/eventhub/Azure.Messaging.EventHubs.Shared/src/Core/BasicRetryPolicy.cs

@@ -5,6 +5,7 @@
 using System.Globalization;
 using System.IO;
 using System.Net.Sockets;
+using System.Net.WebSockets;
 using System.Threading;
 using System.Threading.Tasks;
 using Azure.Core;
@@ -140,14 +141,16 @@ public BasicRetryPolicy(EventHubsRetryOptions retryOptions)
         ///
         private static bool ShouldRetryException(Exception exception)
         {
-            if ((exception is TaskCanceledException) || (exception is OperationCanceledException))
-            {
-                exception = exception?.InnerException;
-            }
-            else if (exception is AggregateException aggregateEx)
+            // Transform the exception into a more relevant type, if possible.
+
+            exception = exception switch
             {
-                exception = aggregateEx?.Flatten().InnerException;
-            }
+                TaskCanceledException => exception?.InnerException,
+                OperationCanceledException => exception?.InnerException,
+                WebSocketException => exception?.InnerException ?? exception,
+                AggregateException aggregateEx => aggregateEx?.Flatten().InnerException,
+                _ => exception
+            };
 
             switch (exception)
             {

sdk/eventhub/Azure.Messaging.EventHubs.Shared/tests/RetryPolicies/BasicRetryPolicyTests.cs

@@ -5,6 +5,7 @@
 using System.Collections.Generic;
 using System.IO;
 using System.Net.Sockets;
+using System.Net.WebSockets;
 using System.Threading.Tasks;
 using Azure.Messaging.EventHubs.Core;
 using Moq;
@@ -31,6 +32,9 @@ public static IEnumerable<object[]> RetriableExceptionTestCases()
             yield return new object[] { new IOException() };
             yield return new object[] { new UnauthorizedAccessException() };
 
+            // WebSocketException should use the inner exception as the decision point.
+            yield return new object[] { new WebSocketException("dummy", new EventHubsException(true, null)) };
+
             // Task/Operation Canceled should use the inner exception as the decision point.
 
             yield return new object[] { new TaskCanceledException("dummy", new EventHubsException(true, null)) };
@@ -63,6 +67,9 @@ public static IEnumerable<object[]> NonRetriableExceptionTestCases()
             yield return new object[] { new SocketException((int)SocketError.HostNotFound) };
             yield return new object[] { new SocketException((int)SocketError.HostUnreachable) };
 
+            // WebSocketException should use the inner exception as the decision point.
+            yield return new object[] { new WebSocketException("dummy", new EventHubsException(false, null)) };
+
             // Task/Operation Canceled should use the inner exception as the decision point.
 
             yield return new object[] { new TaskCanceledException("dummy", new EventHubsException(false, null)) };
@@ -96,7 +103,7 @@ public static IEnumerable<object[]> NonRetriableExceptionTestCases()
         [TestCase(2)]
         [TestCase(10)]
         [TestCase(100)]
-        public void CalulateTryTimeoutRespectsOptions(int attemptCount)
+        public void CalculateTryTimeoutRespectsOptions(int attemptCount)
         {
             var timeout = TimeSpan.FromSeconds(5);
             var options = new EventHubsRetryOptions { TryTimeout = timeout };
@@ -255,7 +262,7 @@ public void CalculateRetryDelayRespectsThrottleInterval()
         /// </summary>
         ///
         [Test]
-        public void CalculateRetryDelayDoesNotTrottleGeneralExceptions()
+        public void CalculateRetryDelayDoesNotThrottleGeneralExceptions()
         {
             var delaySeconds = 1;
             var exception = new EventHubsException(true, "dummy", EventHubsException.FailureReason.GeneralError);

sdk/eventhub/Azure.Messaging.EventHubs/CHANGELOG.md

@@ -10,6 +10,8 @@
 
 ### Other Changes
 
+- Enhanced retry logic to consider additional cases for web socket-based failures.  In many cases, a `WebSocketException` is triggered which wraps a `SocketException` with the details for the specific network conditions.  Retry decisions are now based on the internal exception, if present, to ensure retries are correctly applied.
+
 ## 5.12.0-beta.2 (2025-02-11)
 
 ### Acknowledgments

sdk/eventhub/Azure.Messaging.EventHubs/api/Azure.Messaging.EventHubs.net8.0.cs

@@ -818,13 +818,11 @@ public static partial class EventHubClientBuilderExtensions
         public static Azure.Core.Extensions.IAzureClientBuilder<Azure.Messaging.EventHubs.Consumer.EventHubConsumerClient, Azure.Messaging.EventHubs.Consumer.EventHubConsumerClientOptions> AddEventHubConsumerClient<TBuilder>(this TBuilder builder, string consumerGroup, string connectionString) where TBuilder : Azure.Core.Extensions.IAzureClientFactoryBuilder { throw null; }
         public static Azure.Core.Extensions.IAzureClientBuilder<Azure.Messaging.EventHubs.Consumer.EventHubConsumerClient, Azure.Messaging.EventHubs.Consumer.EventHubConsumerClientOptions> AddEventHubConsumerClient<TBuilder>(this TBuilder builder, string consumerGroup, string connectionString, string eventHubName) where TBuilder : Azure.Core.Extensions.IAzureClientFactoryBuilder { throw null; }
         [System.Diagnostics.CodeAnalysis.RequiresDynamicCodeAttribute("Binding strongly typed objects to configuration values requires generating dynamic code at runtime, for example instantiating generic types. Use the Configuration Binder Source Generator (EnableConfigurationBindingGenerator=true) instead.")]
-        [System.Diagnostics.CodeAnalysis.RequiresUnreferencedCodeAttribute("Binding strongly typed objects to configuration values is not supported with trimming. Use the Configuration Binder Source Generator (EnableConfigurationBindingGenerator=true) instead.")]
         public static Azure.Core.Extensions.IAzureClientBuilder<Azure.Messaging.EventHubs.Consumer.EventHubConsumerClient, Azure.Messaging.EventHubs.Consumer.EventHubConsumerClientOptions> AddEventHubConsumerClient<TBuilder, TConfiguration>(this TBuilder builder, TConfiguration configuration) where TBuilder : Azure.Core.Extensions.IAzureClientFactoryBuilderWithConfiguration<TConfiguration> { throw null; }
         public static Azure.Core.Extensions.IAzureClientBuilder<Azure.Messaging.EventHubs.Producer.EventHubProducerClient, Azure.Messaging.EventHubs.Producer.EventHubProducerClientOptions> AddEventHubProducerClientWithNamespace<TBuilder>(this TBuilder builder, string fullyQualifiedNamespace, string eventHubName) where TBuilder : Azure.Core.Extensions.IAzureClientFactoryBuilderWithCredential { throw null; }
         public static Azure.Core.Extensions.IAzureClientBuilder<Azure.Messaging.EventHubs.Producer.EventHubProducerClient, Azure.Messaging.EventHubs.Producer.EventHubProducerClientOptions> AddEventHubProducerClient<TBuilder>(this TBuilder builder, string connectionString) where TBuilder : Azure.Core.Extensions.IAzureClientFactoryBuilder { throw null; }
         public static Azure.Core.Extensions.IAzureClientBuilder<Azure.Messaging.EventHubs.Producer.EventHubProducerClient, Azure.Messaging.EventHubs.Producer.EventHubProducerClientOptions> AddEventHubProducerClient<TBuilder>(this TBuilder builder, string connectionString, string eventHubName) where TBuilder : Azure.Core.Extensions.IAzureClientFactoryBuilder { throw null; }
         [System.Diagnostics.CodeAnalysis.RequiresDynamicCodeAttribute("Binding strongly typed objects to configuration values requires generating dynamic code at runtime, for example instantiating generic types. Use the Configuration Binder Source Generator (EnableConfigurationBindingGenerator=true) instead.")]
-        [System.Diagnostics.CodeAnalysis.RequiresUnreferencedCodeAttribute("Binding strongly typed objects to configuration values is not supported with trimming. Use the Configuration Binder Source Generator (EnableConfigurationBindingGenerator=true) instead.")]
         public static Azure.Core.Extensions.IAzureClientBuilder<Azure.Messaging.EventHubs.Producer.EventHubProducerClient, Azure.Messaging.EventHubs.Producer.EventHubProducerClientOptions> AddEventHubProducerClient<TBuilder, TConfiguration>(this TBuilder builder, TConfiguration configuration) where TBuilder : Azure.Core.Extensions.IAzureClientFactoryBuilderWithConfiguration<TConfiguration> { throw null; }
     }
 }

sdk/eventhub/Azure.Messaging.EventHubs/src/Processor/LoadBalancingStrategy.cs

@@ -12,29 +12,36 @@ namespace Azure.Messaging.EventHubs.Processor
     public enum LoadBalancingStrategy
     {
         /// <summary>
-        ///   An event processor will take a measured approach to requesting
-        ///   partition ownership when balancing work with other processors, slowly
-        ///   claiming partitions until a stabilized distribution is achieved.
+        ///   An event processor will take a slow approach to requesting
+        ///   partition ownership when balancing work with other processors, waiting
+        ///   until a load balancing cycle is schedule to run, claiming 1 partition
+        ///   per cycle until a stabilized distribution is achieved.
         ///
-        ///   <para>When using this strategy, it may take longer for all partitions of
+        ///   <para>When using this strategy, it will be considerably longer for all partitions of
         ///   an Event Hub to be owned by a processor when processing first starts, the
-        ///   number of active processors changes, or when partitions are scaled.  The
-        ///   Balanced strategy will reduce contention for a partition, ensuring that once
-        ///   it is claimed, processing will be more likely to be steady and consistent.</para>
+        ///   number of active processors changes, or when partitions are scaled.</para>
+        ///
+        ///   <para>The Balanced strategy is generally not recommended, as it does not provide
+        ///   any tangible benefits unless the load balancing interval is set below 10 seconds,
+        ///   which is strongly discouraged.  The Balanced strategy mainly exists to ensure backwards
+        ///   compatibility with earlier library versions.</para>
         /// </summary>
         ///
         Balanced,
 
         /// <summary>
         ///   An event processor will attempt to claim ownership of its fair share of
-        ///   partitions aggressively when balancing work with other processors.
+        ///   partitions consistently, claiming 1 partition at a time until work is balanced
+        ///   between all active processors.
+        ///
+        ///   <para>When using this strategy, load balancing cycles run without delay until
+        ///   ownership is evenly distributed, ensuring that partitions are processed more quickly
+        ///   when processing first starts, the number of active processors changes, or
+        ///   when partitions are scaled.</para>
         ///
-        ///   <para>When using this strategy, all partitions of an Event Hub will be claimed
-        ///   quickly when processing first starts, the number of active processors changes, or
-        ///   when partitions are scaled.  The Greedy strategy is likely to cause competition for
-        ///   ownership of a given partition, causing it to see sporadic processing and some amount of
-        ///   duplicate events until balance has been reached and work is distributed equally among the
-        ///   active processors.</para>
+        ///   <para>The Greedy strategy will not cause additional competition for township of a given
+        ///   when compared to other strategies, as it allows claims from other processors to safely
+        ///   interleave.  Greedy is the recommended default strategy for processors.</para>
         /// </summary>
         ///
         Greedy

sdk/servicebus/Azure.Messaging.ServiceBus/CHANGELOG.md

@@ -4,6 +4,8 @@
 
 ### Features Added
 
+- `ServiceBusClientOptions` now supports registering a callback delegate for participating in the validation of SSL certificates when connections are established.  This delegate may override the built-in validation and allow or deny certificates based on application-specific logic.
+
 ### Breaking Changes
 
 ### Bugs Fixed
@@ -12,6 +14,8 @@
 
 - Added jitter to the lock renewal timer to reduce the likelihood of lock renewal collisions when using the `ServiceBusProcessor` or the `ServiceBusSessionProcessor`.
 
+- Enhanced retry logic to consider additional cases for web socket-based failures.  In many cases, a `WebSocketException` is triggered which wraps a `SocketException` with the details for the specific network conditions.  Retry decisions are now based on the internal exception, if present, to ensure retries are correctly applied.
+
 ## 7.18.4 (2025-02-11)
 
 ### Bugs Fixed

sdk/servicebus/Azure.Messaging.ServiceBus/api/Azure.Messaging.ServiceBus.net8.0.cs

@@ -134,6 +134,7 @@ public ServiceBusClient(string connectionString, Azure.Messaging.ServiceBus.Serv
     public partial class ServiceBusClientOptions
     {
         public ServiceBusClientOptions() { }
+        public System.Net.Security.RemoteCertificateValidationCallback CertificateValidationCallback { get { throw null; } set { } }
         public System.TimeSpan ConnectionIdleTimeout { get { throw null; } set { } }
         public System.Uri CustomEndpointAddress { get { throw null; } set { } }
         public bool EnableCrossEntityTransactions { get { throw null; } set { } }

sdk/servicebus/Azure.Messaging.ServiceBus/api/Azure.Messaging.ServiceBus.netstandard2.0.cs

@@ -134,6 +134,7 @@ public ServiceBusClient(string connectionString, Azure.Messaging.ServiceBus.Serv
     public partial class ServiceBusClientOptions
     {
         public ServiceBusClientOptions() { }
+        public System.Net.Security.RemoteCertificateValidationCallback CertificateValidationCallback { get { throw null; } set { } }
         public System.TimeSpan ConnectionIdleTimeout { get { throw null; } set { } }
         public System.Uri CustomEndpointAddress { get { throw null; } set { } }
         public bool EnableCrossEntityTransactions { get { throw null; } set { } }

sdk/servicebus/Azure.Messaging.ServiceBus/samples/Sample13_AdvancedConfiguration.md

@@ -35,6 +35,39 @@ var options = new ServiceBusClientOptions
 ServiceBusClient client = new(fullyQualifiedNamespace, new DefaultAzureCredential(), options);
 ```
 
+### Influencing SSL certificate validation
+
+For some environments using a proxy or custom gateway for routing traffic to Service Bus, a certificate not trusted by the root certificate authorities may be issued. This can often be a self-signed certificate from the gateway or one issued by a company's internal certificate authority.
+
+By default, these certificates are not trusted by the Service Bus client library and the connection will be refused. To enable these scenarios, a [RemoteCertificateValidationCallback](https://learn.microsoft.com/dotnet/api/system.net.security.remotecertificatevalidationcallback) can be registered to provide custom validation logic for remote certificates. This allows an application to override the default trust decision and assert responsibility for accepting or rejecting the certificate.
+
+```C# Snippet:ServiceBusConfigureRemoteCertificateValidationCallback
+string fullyQualifiedNamespace = "<fully_qualified_namespace>";
+DefaultAzureCredential credential = new();
+
+static bool ValidateServerCertificate(
+      object sender,
+      X509Certificate certificate,
+      X509Chain chain,
+      SslPolicyErrors sslPolicyErrors)
+{
+    if ((sslPolicyErrors == SslPolicyErrors.None)
+        || (certificate.Issuer == "My Company CA"))
+    {
+        return true;
+    }
+
+    // Do not allow communication with unauthorized servers.
+
+    return false;
+}
+
+ServiceBusClient client = new(fullyQualifiedNamespace, credential, new ServiceBusClientOptions
+{
+    CertificateValidationCallback = ValidateServerCertificate
+});
+```
+
 ## Customizing the retry options
 
 The retry options are used to configure the retry policy for all operations when communicating with the service. The default values are shown below, but they can be customized to fit your scenario.