Skip to content

Commit

Permalink
[Event Hubs Client] Documentation Updates (Azure#12690)
Browse files Browse the repository at this point in the history 
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`.
  • Loading branch information
@jsquire
jsquire authored Jun 10, 2020
1 parent c938cdd commit 7505a33
Show file tree
Hide file tree
Showing 4 changed files with 13 additions and 18 deletions.
2 changes: 1 addition & 1 deletion sdk/eventhub/Azure.Messaging.EventHubs.Processor/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
25 changes: 10 additions & 15 deletions sdk/eventhub/Azure.Messaging.EventHubs.Processor/src/EventProcessorClient.cs
100755 → 100644
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -31,9 +27,8 @@ namespace Azure.Messaging.EventHubs
    ///   allowing the processor to be resilient in the face of errors.
    /// </summary>
    ///
#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<EventProcessorPartition>
#pragma warning restore CA1001 // Types that own disposable fields should be disposable
{
/// <summary>The number of events to request as the maximum size for batches read from a partition.</summary>
private const int ReadBatchSize = 15;
Expand Down Expand Up @@ -265,13 +260,13 @@ public event Func<ProcessErrorEventArgs, Task> ProcessErrorAsync
/// Initializes a new instance of the <see cref="EventProcessorClient"/> class.
/// </summary>
///
/// <param name="checkpointStore">The client responsible for interaction with durable storage, responsible for persisting checkpoints and load-balancing state.</param>
/// <param name="checkpointStore">The client responsible for persisting checkpoints and processor state to durable storage. The associated container is expected to exist.</param>
/// <param name="consumerGroup">The name of the consumer group this processor is associated with. Events are read in the context of this group.</param>
/// <param name="connectionString">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.</param>
///
/// <remarks>
/// <para>The container associated with the <paramref name="checkpointStore" /> is expected to exist; the <see cref="EventProcessorClient" />
/// does not assume the ability to manage the storage account and is safe to run without permission to manage the storage account.</para>
/// 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.</para>
///
/// <para>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
Expand All @@ -293,14 +288,14 @@ public EventProcessorClient(BlobContainerClient checkpointStore,
/// Initializes a new instance of the <see cref="EventProcessorClient"/> class.
/// </summary>
///
/// <param name="checkpointStore">The client responsible for interaction with durable storage, responsible for persisting checkpoints and load-balancing state.</param>
/// <param name="checkpointStore">The client responsible for persisting checkpoints and processor state to durable storage. The associated container is expected to exist.</param>
/// <param name="consumerGroup">The name of the consumer group this processor is associated with. Events are read in the context of this group.</param>
/// <param name="connectionString">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.</param>
/// <param name="clientOptions">The set of options to use for this processor.</param>
///
/// <remarks>
/// <para>The container associated with the <paramref name="checkpointStore" /> is expected to exist; the <see cref="EventProcessorClient" />
/// does not assume the ability to manage the storage account and is safe to run without permission to manage the storage account.</para>
/// 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.</para>
///
/// <para>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
Expand All @@ -323,14 +318,14 @@ public EventProcessorClient(BlobContainerClient checkpointStore,
/// Initializes a new instance of the <see cref="EventProcessorClient"/> class.
/// </summary>
///
/// <param name="checkpointStore">The client responsible for interaction with durable storage, responsible for persisting checkpoints and load-balancing state.</param>
/// <param name="checkpointStore">The client responsible for persisting checkpoints and processor state to durable storage. The associated container is expected to exist.</param>
/// <param name="consumerGroup">The name of the consumer group this processor is associated with. Events are read in the context of this group.</param>
/// <param name="connectionString">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.</param>
/// <param name="eventHubName">The name of the specific Event Hub to associate the processor with.</param>
///
/// <remarks>
/// <para>The container associated with the <paramref name="checkpointStore" /> is expected to exist; the <see cref="EventProcessorClient" />
/// does not assume the ability to manage the storage account and is safe to run without permission to manage the storage account.</para>
/// 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.</para>
///
/// <para>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 <paramref name="eventHubName" />. The name of the Event Hub should be
Expand All @@ -350,15 +345,15 @@ public EventProcessorClient(BlobContainerClient checkpointStore,
/// Initializes a new instance of the <see cref="EventProcessorClient"/> class.
/// </summary>
///
/// <param name="checkpointStore">The client responsible for interaction with durable storage, responsible for persisting checkpoints and load-balancing state.</param>
/// <param name="checkpointStore">The client responsible for persisting checkpoints and processor state to durable storage. The associated container is expected to exist.</param>
/// <param name="consumerGroup">The name of the consumer group this processor is associated with. Events are read in the context of this group.</param>
/// <param name="connectionString">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.</param>
/// <param name="eventHubName">The name of the specific Event Hub to associate the processor with.</param>
/// <param name="clientOptions">The set of options to use for this processor.</param>
///
/// <remarks>
/// <para>The container associated with the <paramref name="checkpointStore" /> is expected to exist; the <see cref="EventProcessorClient" />
/// does not assume the ability to manage the storage account and is safe to run without permission to manage the storage account.</para>
/// 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.</para>
///
/// <para>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 <paramref name="eventHubName" />. The name of the Event Hub should be
Expand All @@ -381,7 +376,7 @@ public EventProcessorClient(BlobContainerClient checkpointStore,
/// Initializes a new instance of the <see cref="EventProcessorClient"/> class.
/// </summary>
///
/// <param name="checkpointStore">The client responsible for interaction with durable storage, responsible for persisting checkpoints and load-balancing state.</param>
/// <param name="checkpointStore">The client responsible for persisting checkpoints and processor state to durable storage. The associated container is expected to exist.</param>
/// <param name="consumerGroup">The name of the consumer group this processor is associated with. Events are read in the context of this group.</param>
/// <param name="fullyQualifiedNamespace">The fully qualified Event Hubs namespace to connect to. This is likely to be similar to <c>{yournamespace}.servicebus.windows.net</c>.</param>
/// <param name="eventHubName">The name of the specific Event Hub to associate the processor with.</param>
Expand Down
2 changes: 1 addition & 1 deletion sdk/eventhub/Azure.Messaging.EventHubs/MigrationGuide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion sdk/eventhub/Azure.Messaging.EventHubs/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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))
{
Expand Down

0 comments on commit 7505a33

Please sign in to comment.