Class EventHubConsumerClient

A client responsible for reading EventData from a specific Event Hub as a member of a specific consumer group.

A consumer may be exclusive, which asserts ownership over associated partitions for the consumer group to ensure that only one consumer from that group is reading the from the partition. These exclusive consumers are sometimes referred to as "Epoch Consumers."

A consumer may also be non-exclusive, allowing multiple consumers from the same consumer group to be actively reading events from a given partition. These non-exclusive consumers are sometimes referred to as "Non-Epoch Consumers."

Inheritance
System.Object
EventHubConsumerClient
Namespace: System.Dynamic.ExpandoObject
Assembly: Azure.Messaging.EventHubs.dll
Syntax
public class EventHubConsumerClient : IAsyncDisposable
Remarks

The EventHubConsumerClient is safe to cache and use for the lifetime of an application, which is the best practice when the application reads events regularly or semi-regularly. The consumer is responsible for ensuring efficient network, CPU, and memory use. Calling either CloseAsync(CancellationToken) or DisposeAsync() as the application is shutting down will ensure that network resources and other unmanaged objects are properly cleaned up.

Constructors

EventHubConsumerClient()

Initializes a new instance of the EventHubConsumerClient class.

Declaration
protected EventHubConsumerClient ();

EventHubConsumerClient(String, String)

Initializes a new instance of the EventHubConsumerClient class.

Declaration
public EventHubConsumerClient (string consumerGroup, string connectionString);
Parameters
System.String consumerGroup

The name of the consumer group this consumer is associated with. Events are read in the context of this group.
System.String 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.
Remarks

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

connection string. For example, ";EntityPath=telemetry-hub".

If you have defined a shared access policy directly on the Event Hub itself, then copying the connection string from that

Event Hub will result in a connection string that contains the name.

EventHubConsumerClient(String, EventHubConnection, EventHubConsumerClientOptions)

Initializes a new instance of the EventHubConsumerClient class.

Declaration
public EventHubConsumerClient (string consumerGroup, Azure.Messaging.EventHubs.EventHubConnection connection, Azure.Messaging.EventHubs.Consumer.EventHubConsumerClientOptions clientOptions = null);
Parameters
System.String consumerGroup

The name of the consumer group this consumer is associated with. Events are read in the context of this group.
EventHubConnection connection

The EventHubConnection connection to use for communication with the Event Hubs service.
EventHubConsumerClientOptions clientOptions

A set of options to apply when configuring the consumer.

EventHubConsumerClient(String, String, EventHubConsumerClientOptions)

Initializes a new instance of the EventHubConsumerClient class.

Declaration
public EventHubConsumerClient (string consumerGroup, string connectionString, Azure.Messaging.EventHubs.Consumer.EventHubConsumerClientOptions clientOptions);
Parameters
System.String consumerGroup

The name of the consumer group this consumer is associated with. Events are read in the context of this group.
System.String 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.
EventHubConsumerClientOptions clientOptions

The set of options to use for this consumer.
Remarks

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

connection string. For example, ";EntityPath=telemetry-hub".

If you have defined a shared access policy directly on the Event Hub itself, then copying the connection string from that

Event Hub will result in a connection string that contains the name.

EventHubConsumerClient(String, String, String)

Initializes a new instance of the EventHubConsumerClient class.

Declaration
public EventHubConsumerClient (string consumerGroup, string connectionString, string eventHubName);
Parameters
System.String consumerGroup

The name of the consumer group this consumer is associated with. Events are read in the context of this group.
System.String 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.
System.String eventHubName

The name of the specific Event Hub to associate the consumer with.
Remarks

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 eventHubName. The name of the Event Hub should be passed only once, either as part of the connection string or separately.

EventHubConsumerClient(String, String, String, EventHubConsumerClientOptions)

Initializes a new instance of the EventHubConsumerClient class.

Declaration
public EventHubConsumerClient (string consumerGroup, string connectionString, string eventHubName, Azure.Messaging.EventHubs.Consumer.EventHubConsumerClientOptions clientOptions);
Parameters
System.String consumerGroup

The name of the consumer group this consumer is associated with. Events are read in the context of this group.
System.String 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.
System.String eventHubName

The name of the specific Event Hub to associate the consumer with.
EventHubConsumerClientOptions clientOptions

A set of options to apply when configuring the consumer.
Remarks

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 eventHubName. The name of the Event Hub should be passed only once, either as part of the connection string or separately.

EventHubConsumerClient(String, String, String, AzureNamedKeyCredential, EventHubConsumerClientOptions)

Initializes a new instance of the EventHubConsumerClient class.

Declaration
public EventHubConsumerClient (string consumerGroup, string fullyQualifiedNamespace, string eventHubName, Azure.AzureNamedKeyCredential credential, Azure.Messaging.EventHubs.Consumer.EventHubConsumerClientOptions clientOptions = null);
Parameters
System.String consumerGroup

The name of the consumer group this consumer is associated with. Events are read in the context of this group.
System.String fullyQualifiedNamespace

The fully qualified Event Hubs namespace to connect to. This is likely to be similar to {yournamespace}.servicebus.windows.net.
System.String eventHubName

The name of the specific Event Hub to associate the consumer with.
Azure.AzureNamedKeyCredential credential

The shared access key credential to use for authorization. Access controls may be specified by the Event Hubs namespace or the requested Event Hub, depending on Azure configuration.
EventHubConsumerClientOptions clientOptions

A set of options to apply when configuring the consumer.

EventHubConsumerClient(String, String, String, AzureSasCredential, EventHubConsumerClientOptions)

Initializes a new instance of the EventHubConsumerClient class.

Declaration
public EventHubConsumerClient (string consumerGroup, string fullyQualifiedNamespace, string eventHubName, Azure.AzureSasCredential credential, Azure.Messaging.EventHubs.Consumer.EventHubConsumerClientOptions clientOptions = null);
Parameters
System.String consumerGroup

The name of the consumer group this consumer is associated with. Events are read in the context of this group.
System.String fullyQualifiedNamespace

The fully qualified Event Hubs namespace to connect to. This is likely to be similar to {yournamespace}.servicebus.windows.net.
System.String eventHubName

The name of the specific Event Hub to associate the consumer with.
Azure.AzureSasCredential credential

The shared access signature credential to use for authorization. Access controls may be specified by the Event Hubs namespace or the requested Event Hub, depending on Azure configuration.
EventHubConsumerClientOptions clientOptions

A set of options to apply when configuring the consumer.

EventHubConsumerClient(String, String, String, TokenCredential, EventHubConsumerClientOptions)

Initializes a new instance of the EventHubConsumerClient class.

Declaration
public EventHubConsumerClient (string consumerGroup, string fullyQualifiedNamespace, string eventHubName, Azure.Core.TokenCredential credential, Azure.Messaging.EventHubs.Consumer.EventHubConsumerClientOptions clientOptions = null);
Parameters
System.String consumerGroup

The name of the consumer group this consumer is associated with. Events are read in the context of this group.
System.String fullyQualifiedNamespace

The fully qualified Event Hubs namespace to connect to. This is likely to be similar to {yournamespace}.servicebus.windows.net.
System.String eventHubName

The name of the specific Event Hub to associate the consumer with.
Azure.Core.TokenCredential credential

The Azure managed identity credential to use for authorization. Access controls may be specified by the Event Hubs namespace or the requested Event Hub, depending on Azure configuration.
EventHubConsumerClientOptions clientOptions

A set of options to apply when configuring the consumer.

Fields

DefaultConsumerGroupName

The name of the default consumer group in the Event Hubs service.

Declaration
public const string DefaultConsumerGroupName;
Field Value
System.String

Properties

ConsumerGroup

The name of the consumer group that this consumer is associated with. Events will be read only in the context of this group.

Declaration
public string ConsumerGroup { get; }
Property Value
System.String

EventHubName

The name of the Event Hub that the consumer is connected to, specific to the Event Hubs namespace that contains it.

Declaration
public string EventHubName { get; }
Property Value
System.String

FullyQualifiedNamespace

The fully qualified Event Hubs namespace that the consumer is associated with. This is likely to be similar to {yournamespace}.servicebus.windows.net.

Declaration
public string FullyQualifiedNamespace { get; }
Property Value
System.String

Identifier

A unique name used to identify this consumer.

Declaration
public string Identifier { get; }
Property Value
System.String

IsClosed

Indicates whether or not this EventHubConsumerClient has been closed.

Declaration
public bool IsClosed { get; protected set; }
Property Value
System.Boolean

true if the client is closed; otherwise, false.

Methods

CloseAsync(CancellationToken)

Closes the consumer.

Declaration
[System.Diagnostics.DebuggerStepThrough]
public virtual System.Threading.Tasks.Task CloseAsync (System.Threading.CancellationToken cancellationToken = null);
Parameters
System.Threading.CancellationToken cancellationToken

An optional System.Threading.CancellationToken instance to signal the request to cancel the operation.
Returns
System.Threading.Tasks.Task

A task to be resolved on when the operation has completed.

DisposeAsync()

Performs the task needed to clean up resources used by the EventHubConsumerClient, including ensuring that the client itself has been closed.

Declaration
[System.Diagnostics.DebuggerStepThrough]
public virtual System.Threading.Tasks.ValueTask DisposeAsync ();
Returns
System.Threading.Tasks.ValueTask

A task to be resolved on when the operation has completed.

Equals(Object)

Determines whether the specified System.Object is equal to this instance.

Declaration
[System.ComponentModel.EditorBrowsable]
public override bool Equals (object obj);
Parameters
System.Object obj

The System.Object to compare with this instance.
Returns
System.Boolean

true if the specified System.Object is equal to this instance; otherwise, false.

GetEventHubPropertiesAsync(CancellationToken)

Retrieves information about the Event Hub that the connection is associated with, including the number of partitions present and their identifiers.

Declaration
[System.Diagnostics.DebuggerStepThrough]
public virtual System.Threading.Tasks.Task<Azure.Messaging.EventHubs.EventHubProperties> GetEventHubPropertiesAsync (System.Threading.CancellationToken cancellationToken = null);
Parameters
System.Threading.CancellationToken cancellationToken

An optional System.Threading.CancellationToken instance to signal the request to cancel the operation.
Returns
System.Threading.Tasks.Task<EventHubProperties>

The set of information for the Event Hub that this client is associated with.

GetHashCode()

Returns a hash code for this instance.

Declaration
[System.ComponentModel.EditorBrowsable]
public override int GetHashCode ();
Returns
System.Int32

A hash code for this instance, suitable for use in hashing algorithms and data structures like a hash table.

GetPartitionIdsAsync(CancellationToken)

Retrieves the set of identifiers for the partitions of an Event Hub.

Declaration
[System.Diagnostics.DebuggerStepThrough]
public virtual System.Threading.Tasks.Task<string[]> GetPartitionIdsAsync (System.Threading.CancellationToken cancellationToken = null);
Parameters
System.Threading.CancellationToken cancellationToken

An optional System.Threading.CancellationToken instance to signal the request to cancel the operation.
Returns
System.Threading.Tasks.Task<System.String[]>

The set of identifiers for the partitions within the Event Hub that this client is associated with.
Remarks

This method is synonymous with invoking GetEventHubPropertiesAsync(CancellationToken) and reading the PartitionIds property that is returned. It is offered as a convenience for quick access to the set of partition identifiers for the associated Event Hub. No new or extended information is presented.

GetPartitionPropertiesAsync(String, CancellationToken)

Retrieves information about a specific partition for an Event Hub, including elements that describe the available events in the partition event stream.

Declaration
[System.Diagnostics.DebuggerStepThrough]
public virtual System.Threading.Tasks.Task<Azure.Messaging.EventHubs.PartitionProperties> GetPartitionPropertiesAsync (string partitionId, System.Threading.CancellationToken cancellationToken = null);
Parameters
System.String partitionId

The unique identifier of a partition associated with the Event Hub.
System.Threading.CancellationToken cancellationToken

An optional System.Threading.CancellationToken instance to signal the request to cancel the operation.
Returns
System.Threading.Tasks.Task<PartitionProperties>

The set of information for the requested partition under the Event Hub this client is associated with.

ReadEventsAsync(CancellationToken)

Reads events from all partitions of the event hub as an asynchronous enumerable, allowing events to be iterated as they become available on the partition, waiting as necessary should there be no events available.

This enumerator may block for an indeterminate amount of time for an await if events are not available on the partition, requiring cancellation via the cancellationToken to be requested in order to return control. It is recommended to set the MaximumWaitTime for scenarios where a more deterministic maximum waiting period is desired.

Declaration
public virtual System.Collections.Generic.IAsyncEnumerable<Azure.Messaging.EventHubs.Consumer.PartitionEvent> ReadEventsAsync (System.Threading.CancellationToken cancellationToken = null);
Parameters
System.Threading.CancellationToken cancellationToken

An optional System.Threading.CancellationToken instance to signal the request to cancel the operation.
Returns
System.Collections.Generic.IAsyncEnumerable<PartitionEvent>

An System.Collections.Generic.IAsyncEnumerable to be used for iterating over events in the partition.
Remarks

This method is not recommended for production use; the EventProcessorClient should be used for reading events from all partitions in a production scenario, as it offers a much more robust experience with higher throughput.

It is important to note that this method does not guarantee fairness amongst the partitions during iteration; each of the partitions compete to publish events to be read by the enumerator. Depending on service communication, there may be a clustering of events per partition and/or there may be a noticeable bias for a given partition or subset of partitions.

Each reader of events is presented with an independent iterator; if there are multiple readers, each receive their own copy of an event to process, rather than competing for them.

Exceptions
EventHubsException

Occurs when an EventHubConsumerClient is unable to read from the Event Hub due to another reader having asserted exclusive ownership. In this case, the EventHubsException.FailureReason will be set to ConsumerDisconnected.
See Also

ReadEventsAsync(ReadEventOptions, CancellationToken)

Reads events from all partitions of the event hub as an asynchronous enumerable, allowing events to be iterated as they become available on the partition, waiting as necessary should there be no events available.

This enumerator may block for an indeterminate amount of time for an await if events are not available on the partition, requiring cancellation via the cancellationToken to be requested in order to return control. It is recommended to set the MaximumWaitTime for scenarios where a more deterministic maximum waiting period is desired.

Declaration
public virtual System.Collections.Generic.IAsyncEnumerable<Azure.Messaging.EventHubs.Consumer.PartitionEvent> ReadEventsAsync (Azure.Messaging.EventHubs.Consumer.ReadEventOptions readOptions, System.Threading.CancellationToken cancellationToken = null);
Parameters
ReadEventOptions readOptions

The set of options to use for configuring read behavior; if not specified the defaults will be used.
System.Threading.CancellationToken cancellationToken

An optional System.Threading.CancellationToken instance to signal the request to cancel the operation.
Returns
System.Collections.Generic.IAsyncEnumerable<PartitionEvent>

An System.Collections.Generic.IAsyncEnumerable to be used for iterating over events in the partition.
Remarks

This method is not recommended for production use; the EventProcessorClient should be used for reading events from all partitions in a production scenario, as it offers a much more robust experience with higher throughput.

It is important to note that this method does not guarantee fairness amongst the partitions during iteration; each of the partitions compete to publish events to be read by the enumerator. Depending on service communication, there may be a clustering of events per partition and/or there may be a noticeable bias for a given partition or subset of partitions.

Each reader of events is presented with an independent iterator; if there are multiple readers, each receive their own copy of an event to process, rather than competing for them.

Exceptions
EventHubsException

Occurs when an EventHubConsumerClient is unable to read from the Event Hub due to another reader having asserted exclusive ownership. In this case, the EventHubsException.FailureReason will be set to ConsumerDisconnected.
See Also

ReadEventsAsync(Boolean, ReadEventOptions, CancellationToken)

Reads events from all partitions of the event hub as an asynchronous enumerable, allowing events to be iterated as they become available on the partition, waiting as necessary should there be no events available.

This enumerator may block for an indeterminate amount of time for an await if events are not available on the partition, requiring cancellation via the cancellationToken to be requested in order to return control. It is recommended to set the MaximumWaitTime for scenarios where a more deterministic maximum waiting period is desired.

Declaration
[System.Runtime.CompilerServices.AsyncIteratorStateMachine(typeof(Azure.Messaging.EventHubs.Consumer.EventHubConsumerClient/<ReadEventsAsync>d__46))]
public virtual System.Collections.Generic.IAsyncEnumerable<Azure.Messaging.EventHubs.Consumer.PartitionEvent> ReadEventsAsync (bool startReadingAtEarliestEvent, Azure.Messaging.EventHubs.Consumer.ReadEventOptions readOptions = null, System.Threading.CancellationToken cancellationToken = null);
Parameters
System.Boolean startReadingAtEarliestEvent

true to begin reading at the first events available in each partition; otherwise, reading will begin at the end of each partition seeing only new events as they are published.
ReadEventOptions readOptions

The set of options to use for configuring read behavior; if not specified the defaults will be used.
System.Threading.CancellationToken cancellationToken

An optional System.Threading.CancellationToken instance to signal the request to cancel the operation.
Returns
System.Collections.Generic.IAsyncEnumerable<PartitionEvent>

An System.Collections.Generic.IAsyncEnumerable to be used for iterating over events in the partition.
Remarks

This method is not recommended for production use; the EventProcessorClient should be used for reading events from all partitions in a production scenario, as it offers a much more robust experience with higher throughput.

It is important to note that this method does not guarantee fairness amongst the partitions during iteration; each of the partitions competes to publish events to be read by the enumerator. Depending on service communication, there may be a clustering of events per partition and/or there may be a noticeable bias for a given partition or subset of partitions.

Each reader of events is presented with an independent iterator; if there are multiple readers, each receive their own copy of an event to process, rather than competing for them.

Exceptions
EventHubsException

Occurs when an EventHubConsumerClient is unable to read from the Event Hub due to another reader having asserted exclusive ownership. In this case, the EventHubsException.FailureReason will be set to ConsumerDisconnected.
See Also

ReadEventsFromPartitionAsync(String, EventPosition, CancellationToken)

Reads events from the requested partition as an asynchronous enumerable, allowing events to be iterated as they become available on the partition, waiting as necessary should there be no events available.

This enumerator may block for an indeterminate amount of time for an await if events are not available on the partition, requiring cancellation via the cancellationToken to be requested in order to return control. It is recommended to call the overload which accepts a set of options for configuring read behavior for scenarios where a more deterministic maximum waiting period is desired.

Declaration
public virtual System.Collections.Generic.IAsyncEnumerable<Azure.Messaging.EventHubs.Consumer.PartitionEvent> ReadEventsFromPartitionAsync (string partitionId, Azure.Messaging.EventHubs.Consumer.EventPosition startingPosition, System.Threading.CancellationToken cancellationToken = null);
Parameters
System.String partitionId

The identifier of the Event Hub partition from which events will be received.
EventPosition startingPosition

The position within the partition where the consumer should begin reading events.
System.Threading.CancellationToken cancellationToken

An optional System.Threading.CancellationToken instance to signal the request to cancel the operation.
Returns
System.Collections.Generic.IAsyncEnumerable<PartitionEvent>

An System.Collections.Generic.IAsyncEnumerable to be used for iterating over events in the partition.
Remarks

Each reader of events is presented with an independent iterator; if there are multiple readers, each receive their own copy of an event to

process, rather than competing for them.

Exceptions
EventHubsException

Occurs when an EventHubConsumerClient is unable to read from the requested Event Hub partition due to another reader having asserted exclusive ownership. In this case, the EventHubsException.FailureReason will be set to ConsumerDisconnected.
See Also

ReadEventsFromPartitionAsync(String, EventPosition, ReadEventOptions, CancellationToken)

Reads events from the requested partition as an asynchronous enumerable, allowing events to be iterated as they become available on the partition, waiting as necessary should there be no events available.

This enumerator may block for an indeterminate amount of time for an await if events are not available on the partition, requiring cancellation via the cancellationToken to be requested in order to return control. It is recommended to set the MaximumWaitTime for scenarios where a more deterministic maximum waiting period is desired.

Declaration
[System.Runtime.CompilerServices.AsyncIteratorStateMachine(typeof(Azure.Messaging.EventHubs.Consumer.EventHubConsumerClient/<ReadEventsFromPartitionAsync>d__43))]
public virtual System.Collections.Generic.IAsyncEnumerable<Azure.Messaging.EventHubs.Consumer.PartitionEvent> ReadEventsFromPartitionAsync (string partitionId, Azure.Messaging.EventHubs.Consumer.EventPosition startingPosition, Azure.Messaging.EventHubs.Consumer.ReadEventOptions readOptions, System.Threading.CancellationToken cancellationToken = null);
Parameters
System.String partitionId

The identifier of the Event Hub partition from which events will be received.
EventPosition startingPosition

The position within the partition where the consumer should begin reading events.
ReadEventOptions readOptions

The set of options to use for configuring read behavior; if not specified the defaults will be used.
System.Threading.CancellationToken cancellationToken

An optional System.Threading.CancellationToken instance to signal the request to cancel the operation.
Returns
System.Collections.Generic.IAsyncEnumerable<PartitionEvent>

An System.Collections.Generic.IAsyncEnumerable to be used for iterating over events in the partition.
Remarks

Each reader of events is presented with an independent iterator; if there are multiple readers, each receive their own copy of an event to

process, rather than competing for them.

Exceptions
EventHubsException

Occurs when an EventHubConsumerClient is unable to read from the requested Event Hub partition due to another reader having asserted exclusive ownership. In this case, the EventHubsException.FailureReason will be set to ConsumerDisconnected.
See Also

ToString()

Converts the instance to string representation.

Declaration
[System.ComponentModel.EditorBrowsable]
public override string ToString ();
Returns
System.String

A System.String that represents this instance.