From 53a9cb1ca8f14b9a07b48d95a59be50e0bfe7f2f Mon Sep 17 00:00:00 2001 From: Jesse Squire Date: Wed, 10 Jun 2020 11:15:07 -0400 Subject: [PATCH] [Event Hubs Client] Documentation Updates The focus of these changes is to refine some documentation to correct a missed update to `Azure.Identity` types and improve context around storage expectations when creating an `EventProcessorClient`. --- .../README.md | 2 +- .../src/EventProcessorClient.cs | 25 ++++++++----------- .../MigrationGuide.md | 2 +- .../Azure.Messaging.EventHubs/README.md | 2 +- 4 files changed, 13 insertions(+), 18 deletions(-) mode change 100755 => 100644 sdk/eventhub/Azure.Messaging.EventHubs.Processor/src/EventProcessorClient.cs diff --git a/sdk/eventhub/Azure.Messaging.EventHubs.Processor/README.md b/sdk/eventhub/Azure.Messaging.EventHubs.Processor/README.md index baf35538013c..d84219432815 100755 --- a/sdk/eventhub/Azure.Messaging.EventHubs.Processor/README.md +++ b/sdk/eventhub/Azure.Messaging.EventHubs.Processor/README.md @@ -190,7 +190,7 @@ string fullyQualifiedNamespace = "<< FULLY-QUALIFIED EVENT HUBS NAMESPACE (like string eventHubName = "<< NAME OF THE EVENT HUB >>"; string consumerGroup = "<< NAME OF THE EVENT HUB CONSUMER GROUP >>"; -TokenCredential credential = new DefaultAzureIdentity(); +TokenCredential credential = new DefaultAzureCredential(); BlobContainerClient storageClient = new BlobContainerClient(blobStorageUrl, credential); EventProcessorClient processor = new EventProcessorClient diff --git a/sdk/eventhub/Azure.Messaging.EventHubs.Processor/src/EventProcessorClient.cs b/sdk/eventhub/Azure.Messaging.EventHubs.Processor/src/EventProcessorClient.cs old mode 100755 new mode 100644 index 4b594524cca3..31d8768cc070 --- a/sdk/eventhub/Azure.Messaging.EventHubs.Processor/src/EventProcessorClient.cs +++ b/sdk/eventhub/Azure.Messaging.EventHubs.Processor/src/EventProcessorClient.cs @@ -2,18 +2,14 @@ // Licensed under the MIT License. using System; -using System.Collections.Concurrent; using System.Collections.Generic; using System.ComponentModel; -using System.Diagnostics; using System.Diagnostics.CodeAnalysis; using System.Globalization; -using System.Linq; using System.Runtime.ExceptionServices; using System.Threading; using System.Threading.Tasks; using Azure.Core; -using Azure.Core.Pipeline; using Azure.Messaging.EventHubs.Consumer; using Azure.Messaging.EventHubs.Core; using Azure.Messaging.EventHubs.Diagnostics; @@ -31,9 +27,8 @@ namespace Azure.Messaging.EventHubs     ///   allowing the processor to be resilient in the face of errors.     ///      /// -#pragma warning disable CA1001 // Types that own disposable fields should be disposable + [SuppressMessage("Usage", "CA1001:Types that own disposable fields should be disposable.", Justification = "Disposal is managed internally as part of the Stop operation.")] public class EventProcessorClient : EventProcessor -#pragma warning restore CA1001 // Types that own disposable fields should be disposable { /// The number of events to request as the maximum size for batches read from a partition. private const int ReadBatchSize = 15; @@ -265,13 +260,13 @@ public event Func ProcessErrorAsync /// Initializes a new instance of the class. /// /// - /// The client responsible for interaction with durable storage, responsible for persisting checkpoints and load-balancing state. + /// The client responsible for persisting checkpoints and processor state to durable storage. The associated container is expected to exist. /// The name of the consumer group this processor is associated with. Events are read in the context of this group. /// The connection string to use for connecting to the Event Hubs namespace; it is expected that the Event Hub name and the shared key properties are contained in this connection string. /// /// /// The container associated with the is expected to exist; the - /// does not assume the ability to manage the storage account and is safe to run without permission to manage the storage account. + /// does not assume the ability to manage the storage account and is safe to run with only read/write permission for blobs in the container. /// /// If the connection string is copied from the Event Hubs namespace, it will likely not contain the name of the desired Event Hub, /// which is needed. In this case, the name can be added manually by adding ";EntityPath=[[ EVENT HUB NAME ]]" to the end of the @@ -293,14 +288,14 @@ public EventProcessorClient(BlobContainerClient checkpointStore, /// Initializes a new instance of the class. /// /// - /// The client responsible for interaction with durable storage, responsible for persisting checkpoints and load-balancing state. + /// The client responsible for persisting checkpoints and processor state to durable storage. The associated container is expected to exist. /// The name of the consumer group this processor is associated with. Events are read in the context of this group. /// The connection string to use for connecting to the Event Hubs namespace; it is expected that the Event Hub name and the shared key properties are contained in this connection string. /// The set of options to use for this processor. /// /// /// The container associated with the is expected to exist; the - /// does not assume the ability to manage the storage account and is safe to run without permission to manage the storage account. + /// does not assume the ability to manage the storage account and is safe to run with only read/write permission for blobs in the container. /// /// If the connection string is copied from the Event Hubs namespace, it will likely not contain the name of the desired Event Hub, /// which is needed. In this case, the name can be added manually by adding ";EntityPath=[[ EVENT HUB NAME ]]" to the end of the @@ -323,14 +318,14 @@ public EventProcessorClient(BlobContainerClient checkpointStore, /// Initializes a new instance of the class. /// /// - /// The client responsible for interaction with durable storage, responsible for persisting checkpoints and load-balancing state. + /// The client responsible for persisting checkpoints and processor state to durable storage. The associated container is expected to exist. /// The name of the consumer group this processor is associated with. Events are read in the context of this group. /// The connection string to use for connecting to the Event Hubs namespace; it is expected that the shared key properties are contained in this connection string, but not the Event Hub name. /// The name of the specific Event Hub to associate the processor with. /// /// /// The container associated with the is expected to exist; the - /// does not assume the ability to manage the storage account and is safe to run without permission to manage the storage account. + /// does not assume the ability to manage the storage account and is safe to run with only read/write permission for blobs in the container. /// /// If the connection string is copied from the Event Hub itself, it will contain the name of the desired Event Hub, /// and can be used directly without passing the . The name of the Event Hub should be @@ -350,7 +345,7 @@ public EventProcessorClient(BlobContainerClient checkpointStore, /// Initializes a new instance of the class. /// /// - /// The client responsible for interaction with durable storage, responsible for persisting checkpoints and load-balancing state. + /// The client responsible for persisting checkpoints and processor state to durable storage. The associated container is expected to exist. /// The name of the consumer group this processor is associated with. Events are read in the context of this group. /// The connection string to use for connecting to the Event Hubs namespace; it is expected that the shared key properties are contained in this connection string, but not the Event Hub name. /// The name of the specific Event Hub to associate the processor with. @@ -358,7 +353,7 @@ public EventProcessorClient(BlobContainerClient checkpointStore, /// /// /// The container associated with the is expected to exist; the - /// does not assume the ability to manage the storage account and is safe to run without permission to manage the storage account. + /// does not assume the ability to manage the storage account and is safe to run with only read/write permission for blobs in the container. /// /// If the connection string is copied from the Event Hub itself, it will contain the name of the desired Event Hub, /// and can be used directly without passing the . The name of the Event Hub should be @@ -381,7 +376,7 @@ public EventProcessorClient(BlobContainerClient checkpointStore, /// Initializes a new instance of the class. /// /// - /// The client responsible for interaction with durable storage, responsible for persisting checkpoints and load-balancing state. + /// The client responsible for persisting checkpoints and processor state to durable storage. The associated container is expected to exist. /// The name of the consumer group this processor is associated with. Events are read in the context of this group. /// The fully qualified Event Hubs namespace to connect to. This is likely to be similar to {yournamespace}.servicebus.windows.net. /// The name of the specific Event Hub to associate the processor with. diff --git a/sdk/eventhub/Azure.Messaging.EventHubs/MigrationGuide.md b/sdk/eventhub/Azure.Messaging.EventHubs/MigrationGuide.md index bed49504020e..d4d9221ef5c1 100755 --- a/sdk/eventhub/Azure.Messaging.EventHubs/MigrationGuide.md +++ b/sdk/eventhub/Azure.Messaging.EventHubs/MigrationGuide.md @@ -76,7 +76,7 @@ In order to allow for a single focus and clear responsibility, the core function | In v4 | Equivalent in v5 | Sample | |------------------------------------------------|------------------------------------------------------------------|--------| | `EventHubClient.CreateFromConnectionString()` | `new EventHubProducerClient()` or `new EventHubConsumerClient()` | [Publish Events](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/eventhub/Azure.Messaging.EventHubs/samples/Sample03_PublishAnEventBatch.cs), [Read Events](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/eventhub/Azure.Messaging.EventHubs/samples/Sample05_ReadEvents.cs) | -| `EventHubClient.CreateWithAzureActiveDirectory()` or `EventHubClient.CreateWithManagedIdentity()` | `new EventHubProducerClient(..., TokenCredential)` or `new EventHubConsumerClient(..., TokenCredential)` | [Authenticate with client secret credential](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/eventhub/Azure.Messaging.EventHubs/samples/Sample11_AuthenticateWithClientSecretCredential.cs) +| `EventHubClient.CreateWithAzureActiveDirectory()` or `EventHubClient.CreateWithManagedIdentity()` | `new EventHubProducerClient(..., TokenCredential)` or `new EventHubConsumerClient(..., TokenCredential)` | [Authenticate with client secret credential](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/eventhub/Azure.Messaging.EventHubs/samples/Sample12_AuthenticateWithClientSecretCredential.cs) | `new EventProcessorHost()` | `new EventProcessorClient(BlobContainerClient, ...)` | [Basic Event Processing](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/eventhub/Azure.Messaging.EventHubs.Processor/samples/Sample03_BasicEventProcessing.cs) | ### Publish events diff --git a/sdk/eventhub/Azure.Messaging.EventHubs/README.md b/sdk/eventhub/Azure.Messaging.EventHubs/README.md index 253a1117f7ee..46e44f534c83 100755 --- a/sdk/eventhub/Azure.Messaging.EventHubs/README.md +++ b/sdk/eventhub/Azure.Messaging.EventHubs/README.md @@ -186,7 +186,7 @@ To make use of an Active Directory principal, one of the available identity toke var fullyQualifiedNamespace = "<< FULLY-QUALIFIED EVENT HUBS NAMESPACE (like something.servicebus.windows.net)>>" var eventHubName = "<< NAME OF THE EVENT HUB >>"; -TokenCredential credential = new DefaultAzureIdentity(); +TokenCredential credential = new DefaultAzureCredential(); await using (var producer = new EventHubProducerClient(fullyQualifiedNamespace, eventHubName, credential)) {