[Event Hubs] Assorted Minor Updates (Azure#23655)

# Summary

The focus of these changes is to:

  - Update change logs
  - Refine documentation around event handlers in the buffered producer
  - Adapt to changes in the `TestEnvironment` that altered behavior
  - Fix a corner case in the `AmqpConnectionScope` that could lead to timers not being properly disposed in some error scenarios.

Author: jsquire

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

@@ -2,15 +2,27 @@
 
 ## 5.7.0-beta.1 (Unreleased)
 
-### Features Added
+### Acknowledgments
 
-### Breaking Changes
+Thank you to our developer community members who helped to make the Event Hubs client libraries better with their contributions to this release:
 
-### Bugs Fixed
+- Andrey Shihov _([GitHub](https://github.com/andreyshihov))_
+
+### Changes
+
+#### Features Added
+
+#### Breaking Changes
+
+#### Bugs Fixed
 
 - Fixed an issue with refreshing authorization where redundant requests were made to acquire AAD tokens that were due to expire.  Refreshes will now coordinate to ensure a single AAD token acquisition.
 
-### Other Changes
+- Fixed an issue with authorization refresh where attempts may have been made to authorize a faulted link.  Links that fail to open are no longer be considered valid for authorization.
+
+#### Other Changes
+
+- Documentation has been enhanced to provide additional context for client library types, notably detailing non-obvious validations applied to parameters and options members.
 
 ## 5.6.0 (2021-08-10)
 

sdk/eventhub/Azure.Messaging.EventHubs.Shared/src/Testing/EventHubsTestEnvironment.cs

@@ -113,12 +113,6 @@ public sealed class EventHubsTestEnvironment : TestEnvironment
         ///
         public string SharedAccessKey => ParsedConnectionString.Value.SharedAccessKey;
 
-        /// <summary>
-        ///   The Azure Authority host to be used for authentication with the active cloud environment.
-        /// </summary>
-        ///
-        public new string AuthorityHostUrl => base.AuthorityHostUrl ?? "https://login.microsoftonline.com/";
-
         /// <summary>
         ///   The Azure Service Management endpoint to be used for management plane authentication with the active cloud environment.
         /// </summary>

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

@@ -2,16 +2,30 @@
 
 ## 5.7.0-beta.1 (Unreleased)
 
-### Features Added
+### Acknowledgments
+
+Thank you to our developer community members who helped to make the Event Hubs client libraries better with their contributions to this release:
+
+- Andrey Shihov _([GitHub](https://github.com/andreyshihov))_
+
+### Changes
+
+#### Features Added
 
-### Breaking Changes
+#### Breaking Changes
 
-### Bugs Fixed
+#### Bugs Fixed
 
 - Fixed an issue with refreshing authorization where redundant requests were made to acquire AAD tokens that were due to expire.  Refreshes will now coordinate to ensure a single AAD token acquisition.
 
+- Fixed an issue with authorization refresh where attempts may have been made to authorize a faulted link.  Links that fail to open are no longer be considered valid for authorization.
+
 ### Other Changes
 
+- A sample demonstrating the use of the `AzureEventSourceListener` from `Azure.Core` for common scenarios with the Event Hubs client library has been created.   _(A community contribution, courtesy of [andreyshihov](https://github.com/andreyshihov))_
+
+- Documentation has been enhanced to provide additional context for client library types, notably detailing non-obvious validations applied to parameters and options members.
+
 ## 5.6.0 (2021-08-10)
 
 ### Features Added

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

@@ -32,37 +32,39 @@ Tests in the Event Hubs client library are split into two categories:
 The Live tests read information from the following environment variables:
 
 - `EVENTHUB_RESOURCE_GROUP`  
- The name of the Azure resource group that contains the Event Hubs namespace
+  The name of the Azure resource group that contains the Event Hubs namespace
 
 - `EVENTHUB_SUBSCRIPTION_ID`  
- The identifier (GUID) of the Azure subscription to which the service principal belongs
+  The identifier (GUID) of the Azure subscription to which the service principal belongs
 
 - `EVENTHUB_TENANT_ID`  
- The identifier (GUID) of the Azure Active Directory tenant that contains the service principal
+  The identifier (GUID) of the Azure Active Directory tenant that contains the service principal
 
 - `EVENTHUB_CLIENT_ID`  
- The identifier (GUID) of the Azure Active Directory application that is associated with the service principal
+  The identifier (GUID) of the Azure Active Directory application that is associated with the service principal
 
 - `EVENTHUB_CLIENT_SECRET`  
- The client secret (password) of the Azure Active Directory application that is associated with the service principal
+  The client secret (password) of the Azure Active Directory application that is associated with the service principal
 
-- `EVENTHUB_PER_TEST_LIMIT_MINUTES`
-The maximum duration, in minutes, that a single test is permitted to run before it is considered at-risk for being hung.  If not provided, a default suitable for most local development environment runs is assumed.
+- `EVENTHUB_PER_TEST_LIMIT_MINUTES`  
+  The maximum duration, in minutes, that a single test is permitted to run before it is considered at-risk for being hung.  If not provided, a default suitable for most local development environment runs is assumed.
+
+- `AZURE_AUTHORITY_HOST` 
+  The URL of the Azure Authority to use for authenticating resource management operations.  For the Azure public cloud, this should be: https://login.microsoftonline.com/.  
+  
+  When testing in other cloud instances, the appropriate host will be needed.  See [National Clouds](https://docs.microsoft.com/azure/active-directory/develop/authentication-national-cloud) for more information.
 
 - `EVENTHUB_NAMESPACE_CONNECTION_STRING` _**(optional)**_  
   The connection string to an existing Event Hubs namespace to use for testing.  If specified, this namespace will be used as the basis for the test run, with Event Hub instances dynamically managed by the tests.  When the run is complete, the namespace will be left in the state that it was in before the test run took place.  If not specified, a new namespace will be dynamically created for the test run and removed at the end of the run.
 
 - `EVENTHUB_PROCESSOR_STORAGE_CONNECTION_STRING` _**(optional)**_  
   The connection string to an existing Blob Storage account to use for `EventProcessorClient` testing.  If specified, this account will be used as the basis for the test run, with container instances dynamically managed by the tests.  When the run is complete, the account will be left in the state that it was in before the test run took place.  If not specified, a new storage account will be dynamically created for the test run and removed at the end of the run.
-  
-- `AZURE_AUTHORITY_HOST` _**(optional)**_  
-  The name of the Azure Authority to use for authenticating resource management operations.  The default for this is appropriate for use with the Azure public cloud; when testing in other cloud instances, this may be needed.
-  
+ 
 - `SERVICE_MANAGEMENT_URL` _**(optional)**_  
-  The URL of the endpoint responsible for service management operations in Azure.  The default for this is appropriate for use with the Azure public cloud; when testing in other cloud instances, this may be needed.
+  The URL of the endpoint responsible for service management operations in Azure.  The default for this is appropriate for use with the Azure public cloud; when testing in other cloud instances, specifying this value may be needed.
 
 - `RESOURCE_MANAGER_URL` _**(optional)**_  
-  The URL of the endpoint responsible for resource management operations in Azure.  The default for this is appropriate for use with the Azure public cloud; when testing in other cloud instances, this may be needed.
+  The URL of the endpoint responsible for resource management operations in Azure.  The default for this is appropriate for use with the Azure public cloud; when testing in other cloud instances, specifying this value may be needed.
 
 To make setting up your environment easier, a [PowerShell script](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/eventhub/Azure.Messaging.EventHubs/assets/live-tests-azure-setup.ps1) is included in the repository and will create and/or configure the needed Azure resources.  To use this script, open a PowerShell instance and login to your Azure account using `Login-AzAccount`, then execute the script.  You will need to provide some information, after which the script will configure the Azure resources and then output the set of environment variables with the correct values for running tests.
 

sdk/eventhub/Azure.Messaging.EventHubs/samples/Sample10_AzureEventSourceListener.md

@@ -13,15 +13,13 @@ This example captures all Azure SDK logs from any client library in use, writing
 ```C# Snippet:EventHubs_Sample10_ConsoleListener
 var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
 var eventHubName = "<< NAME OF THE EVENT HUB >>";
+var producer = new EventHubProducerClient(connectionString, eventHubName);
 
 using AzureEventSourceListener consoleListener = AzureEventSourceListener.CreateConsoleLogger(EventLevel.LogAlways);
 
-EventHubProducerClient producer = new EventHubProducerClient(connectionString, eventHubName);
-
 try
 {
     using var eventBatch = await producer.CreateBatchAsync();
-
     var eventData = new EventData("This is an event body");
 
     if (!eventBatch.TryAdd(eventData))
@@ -42,15 +40,13 @@ Similar to the previous example, this snippet captures all logs, but writes them
 ```C# Snippet:EventHubs_Sample10_TraceListener
 var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
 var eventHubName = "<< NAME OF THE EVENT HUB >>";
+var producer = new EventHubProducerClient(connectionString, eventHubName);
 
 using AzureEventSourceListener traceListener = AzureEventSourceListener.CreateTraceLogger(EventLevel.LogAlways);
 
-EventHubProducerClient producer = new EventHubProducerClient(connectionString, eventHubName);
-
 try
 {
     using var eventBatch = await producer.CreateBatchAsync();
-
     var eventData = new EventData("This is an event body");
 
     if (!eventBatch.TryAdd(eventData))
@@ -75,6 +71,7 @@ More information about the `args` parameter for the callback can be found in the
 ```C# Snippet:EventHubs_Sample10_CustomListenerWithFilter
 var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
 var eventHubName = "<< NAME OF THE EVENT HUB >>";
+var producer = new EventHubProducerClient(connectionString, eventHubName);
 
 using AzureEventSourceListener customListener = new AzureEventSourceListener((args, message) =>
 {
@@ -95,19 +92,9 @@ using AzureEventSourceListener customListener = new AzureEventSourceListener((ar
     }
 }, EventLevel.LogAlways);
 
-EventHubsConnectionStringProperties connectionStringProperties = EventHubsConnectionStringProperties.Parse(connectionString);
-
-TokenCredential credential = new DefaultAzureCredential();
-
-var producer = new EventHubProducerClient(
-    connectionStringProperties.FullyQualifiedNamespace,
-    connectionStringProperties.EventHubName ?? eventHubName,
-    credential);
-
 try
 {
     using var eventBatch = await producer.CreateBatchAsync();
-
     var eventData = new EventData("This is an event body");
 
     if (!eventBatch.TryAdd(eventData))
@@ -128,8 +115,9 @@ For scenarios where capturing logs to `Trace` or `Console` outputs isn't ideal,
 ```C# Snippet:EventHubs_Sample10_CustomListenerWithFile
 var connectionString = "<< CONNECTION STRING FOR THE EVENT HUBS NAMESPACE >>";
 var eventHubName = "<< NAME OF THE EVENT HUB >>";
+var producer = new EventHubProducerClient(connectionString, eventHubName);
 
-using Stream stream = new FileStream("<< PATH TO THE FILE >>", FileMode.OpenOrCreate, FileAccess.Write); 
+using Stream stream = new FileStream("<< PATH TO THE FILE >>", FileMode.OpenOrCreate, FileAccess.Write);
 
 using StreamWriter streamWriter = new StreamWriter(stream)
 {
@@ -152,12 +140,9 @@ using AzureEventSourceListener customListener = new AzureEventSourceListener((ar
     }
 }, EventLevel.LogAlways);
 
-EventHubProducerClient producer = new EventHubProducerClient(connectionString, eventHubName);
-
 try
 {
     using var eventBatch = await producer.CreateBatchAsync();
-
     var eventData = new EventData("This is an event body");
 
     if (!eventBatch.TryAdd(eventData))