Class PartitionReceiver

Allows reading events from a specific partition of an Event Hub, and in the context of a specific consumer group, to be read with a greater level of control over communication with the Event Hubs service than is offered by other event consumers.

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

It is recommended that the EventProcessorClient or EventHubConsumerClient be used for reading and processing events for the majority of scenarios. The partition receiver is intended to enable scenarios with special needs which require more direct control.

The PartitionReceiver is safe to cache and use for the lifetime of an application, and which is the best practice when the application reads events regularly or semi-regularly. The receiver 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

PartitionReceiver()

Initializes a new instance of the PartitionReceiver class.

Declaration
protected PartitionReceiver ();

PartitionReceiver(String, String, EventPosition, EventHubConnection, PartitionReceiverOptions)

Initializes a new instance of the PartitionReceiver class.

Declaration
public PartitionReceiver (string consumerGroup, string partitionId, Azure.Messaging.EventHubs.Consumer.EventPosition eventPosition, Azure.Messaging.EventHubs.EventHubConnection connection, Azure.Messaging.EventHubs.Primitives.PartitionReceiverOptions options = null);
Parameters
System.String consumerGroup

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

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

The position within the partition where the client should begin reading events.
EventHubConnection connection

The EventHubConnection connection to use for communication with the Event Hubs service.
PartitionReceiverOptions options

A set of options to apply when configuring the client.

PartitionReceiver(String, String, EventPosition, String, PartitionReceiverOptions)

Initializes a new instance of the PartitionReceiver class.

Declaration
public PartitionReceiver (string consumerGroup, string partitionId, Azure.Messaging.EventHubs.Consumer.EventPosition eventPosition, string connectionString, Azure.Messaging.EventHubs.Primitives.PartitionReceiverOptions options = null);
Parameters
System.String consumerGroup

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

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

The position within the partition where the client should begin reading events.
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.
PartitionReceiverOptions options

A set of options to apply when configuring the client.
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.

PartitionReceiver(String, String, EventPosition, String, String, PartitionReceiverOptions)

Initializes a new instance of the PartitionReceiver class.

Declaration
public PartitionReceiver (string consumerGroup, string partitionId, Azure.Messaging.EventHubs.Consumer.EventPosition eventPosition, string connectionString, string eventHubName, Azure.Messaging.EventHubs.Primitives.PartitionReceiverOptions options = null);
Parameters
System.String consumerGroup

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

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

The position within the partition where the client should begin reading events.
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 client with.
PartitionReceiverOptions options

A set of options to apply when configuring the client.
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.

PartitionReceiver(String, String, EventPosition, String, String, AzureNamedKeyCredential, PartitionReceiverOptions)

Initializes a new instance of the PartitionReceiver class.

Declaration
public PartitionReceiver (string consumerGroup, string partitionId, Azure.Messaging.EventHubs.Consumer.EventPosition eventPosition, string fullyQualifiedNamespace, string eventHubName, Azure.AzureNamedKeyCredential credential, Azure.Messaging.EventHubs.Primitives.PartitionReceiverOptions options = null);
Parameters
System.String consumerGroup

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

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

The position within the partition where the client should begin reading events.
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 client with.
Azure.AzureNamedKeyCredential credential

The shared 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.
PartitionReceiverOptions options

A set of options to apply when configuring the client.

PartitionReceiver(String, String, EventPosition, String, String, AzureSasCredential, PartitionReceiverOptions)

Initializes a new instance of the PartitionReceiver class.

Declaration
public PartitionReceiver (string consumerGroup, string partitionId, Azure.Messaging.EventHubs.Consumer.EventPosition eventPosition, string fullyQualifiedNamespace, string eventHubName, Azure.AzureSasCredential credential, Azure.Messaging.EventHubs.Primitives.PartitionReceiverOptions options = null);
Parameters
System.String consumerGroup

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

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

The position within the partition where the client should begin reading events.
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 client with.
Azure.AzureSasCredential credential

The shared 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.
PartitionReceiverOptions options

A set of options to apply when configuring the client.

PartitionReceiver(String, String, EventPosition, String, String, TokenCredential, PartitionReceiverOptions)

Initializes a new instance of the PartitionReceiver class.

Declaration
public PartitionReceiver (string consumerGroup, string partitionId, Azure.Messaging.EventHubs.Consumer.EventPosition eventPosition, string fullyQualifiedNamespace, string eventHubName, Azure.Core.TokenCredential credential, Azure.Messaging.EventHubs.Primitives.PartitionReceiverOptions options = null);
Parameters
System.String consumerGroup

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

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

The position within the partition where the client should begin reading events.
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 client 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.
PartitionReceiverOptions options

A set of options to apply when configuring the client.

Properties

ConsumerGroup

The name of the consumer group that this client 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 client 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 client 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 receiver.

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

InitialPosition

The position within the partition where the client begins reading events.

Declaration
public Azure.Messaging.EventHubs.Consumer.EventPosition InitialPosition { get; }
Property Value
EventPosition

IsClosed

Indicates whether or not this PartitionReceiver has been closed.

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

true if the client is closed; otherwise, false.

PartitionId

The identifier of the Event Hub partition that this client is associated with. Events will be read only from this partition.

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

Methods

CloseAsync(CancellationToken)

Closes the client.

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

DisposeAsync()

Performs the task needed to clean up resources used by the PartitionReceiver, 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

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.

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.

GetPartitionPropertiesAsync(CancellationToken)

Retrieves information about the partition this client is associated to, 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 (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<PartitionProperties>

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

ReadLastEnqueuedEventProperties()

A set of information about the last enqueued event of the partition associated with this receiver, observed as events are received from the Event Hubs service. This is only available if the receiver was created with TrackLastEnqueuedEventProperties set. Otherwise, the properties will contain default values.

Declaration
public virtual Azure.Messaging.EventHubs.Consumer.LastEnqueuedEventProperties ReadLastEnqueuedEventProperties ();
Returns
LastEnqueuedEventProperties

The set of properties for the last event that was enqueued to the partition. If no events were read or tracking was not set, the properties will be returned with default values.
Remarks

When information about the partition's last enqueued event is being tracked, each event received from the Event Hubs

service will carry metadata about the partition that it otherwise would not. This results in a small amount of

additional network bandwidth consumption that is generally a favorable trade-off when considered

against periodically making requests for partition properties using an Event Hub client.

Exceptions
EventHubsException

Occurs when the Event Hubs client needed to read this information is no longer available.

ReceiveBatchAsync(Int32, CancellationToken)

Receives a batch of EventData from the Event Hub partition this client is associated with.

Declaration
[System.Diagnostics.DebuggerStepThrough]
public virtual System.Threading.Tasks.Task<System.Collections.Generic.IEnumerable<Azure.Messaging.EventHubs.EventData>> ReceiveBatchAsync (int maximumEventCount, System.Threading.CancellationToken cancellationToken = null);
Parameters
System.Int32 maximumEventCount

The maximum number of messages to receive in this batch.
System.Threading.CancellationToken cancellationToken

An optional System.Threading.CancellationToken instance to signal the request to cancel the operation.
Returns
System.Threading.Tasks.Task<System.Collections.Generic.IEnumerable<EventData>>

The batch of EventData from the Event Hub partition this client is associated with. If no events are present, an empty enumerable is returned.
Remarks

When events are available in the prefetch queue, they will be used to form the batch as quickly as possible without waiting for additional events from the Event Hubs service to try and meet the requested maximumEventCount. When no events are available in prefetch, the receiver will wait up to the duration specified by the TryTimeout in the active retry policy for events to be read from the service. Once any events are available, they will be used to form the batch immediately.

Exceptions
System.ArgumentOutOfRangeException

Occurs when the requested maximumEventCount is less than 1.
EventHubsException

Occurs when an PartitionReceiver 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.

ReceiveBatchAsync(Int32, TimeSpan, CancellationToken)

Receives a batch of EventData from the Event Hub partition this client is associated with.

Declaration
[System.Diagnostics.DebuggerStepThrough]
public virtual System.Threading.Tasks.Task<System.Collections.Generic.IEnumerable<Azure.Messaging.EventHubs.EventData>> ReceiveBatchAsync (int maximumEventCount, TimeSpan maximumWaitTime, System.Threading.CancellationToken cancellationToken = null);
Parameters
System.Int32 maximumEventCount

The maximum number of messages to receive in this batch.
System.TimeSpan maximumWaitTime

The maximum amount of time to wait for events to become available, if no events can be read from the prefetch queue.
System.Threading.CancellationToken cancellationToken

An optional System.Threading.CancellationToken instance to signal the request to cancel the operation.
Returns
System.Threading.Tasks.Task<System.Collections.Generic.IEnumerable<EventData>>

The batch of EventData from the Event Hub partition this client is associated with. If no events are present, an empty enumerable is returned.
Remarks

When events are available in the prefetch queue, they will be used to form the batch as quickly as possible without waiting for additional events from the Event Hubs service to try and meet the requested maximumEventCount. When no events are available in prefetch, the receiver will wait up to the maximumWaitTime for events to be read from the service. Once any events are available, they will be used to form the batch immediately.

Exceptions
System.ArgumentOutOfRangeException

Occurs when the requested maximumEventCount is less than 1.
EventHubsException

Occurs when an PartitionReceiver 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.

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.

See Also