EventHubClient Class

  • Reference

Definition

Namespace:
Microsoft.Azure.EventHubs
Assembly:
Microsoft.Azure.EventHubs.dll
Package:
Microsoft.Azure.EventHubs v4.3.2
Source:
EventHubClient.cs

Anchor class - all EventHub client operations start here. See CreateFromConnectionString(String)

public abstract class EventHubClient : Microsoft.Azure.EventHubs.ClientEntity
type EventHubClient = class
    inherit ClientEntity
Public MustInherit Class EventHubClient
Inherits ClientEntity
Inheritance
Object
ClientEntity
EventHubClient

Properties

ClientId

Gets the client ID.

(Inherited from ClientEntity)
EnableReceiverRuntimeMetric

Gets or sets a value indicating whether the runtime metric of a receiver is enabled.
EventHubName

Gets the name of the EventHub.
IsClosed

Returns a boolean representing whether client object is closed or not.

(Inherited from ClientEntity)
RegisteredPlugins

Gets a list of currently registered plugins for this Client.

(Inherited from ClientEntity)
RetryPolicy

Gets the RetryPolicy for the ClientEntity.

(Inherited from ClientEntity)
WebProxy

Gets or sets the web proxy. A proxy is applicable only when transport type is set to AmqpWebSockets. If not set, systemwide proxy settings will be honored.

Methods

Close()

Closes the ClientEntity.

(Inherited from ClientEntity)
CloseAsync()

Closes and releases resources associated with EventHubClient.
Create(EventHubsConnectionStringBuilder)

Creates a new instance of the Event Hubs client using the specified connection string builder.
CreateBatch()

Creates a batch where event data objects can be added for later SendAsync call.
CreateBatch(BatchOptions)

Creates a batch where event data objects can be added for later SendAsync call.
CreateEpochReceiver(String, String, EventPosition, Int64, ReceiverOptions)

Create a Epoch based EventHub receiver with given EventPosition. The receiver is created for a specific EventHub Partition from the specific consumer group.

It is important to pay attention to the following when creating epoch based receiver:

- Ownership enforcement: Once you created an epoch based receiver, you cannot create a non-epoch receiver to the same consumerGroup-Partition combo until all receivers to the combo are closed.

- Ownership stealing: If a receiver with higher epoch value is created for a consumerGroup-Partition combo, any older epoch receiver to that combo will be force closed.

- Any receiver closed due to lost of ownership to a consumerGroup-Partition combo will get ReceiverDisconnectedException for all operations from that receiver.
CreateFromConnectionString(String)

Creates a new instance of the Event Hubs client using the specified connection string. You can populate the EntityPath property with the name of the Event Hub.
CreatePartitionSender(String)

Create a PartitionSender which can publish EventData's directly to a specific EventHub partition (sender type iii. in the below list).

There are 3 patterns/ways to send to EventHubs:

i. SendAsync(EventData) or SendAsync(IEnumerable<EventData>)

ii. SendAsync(EventData, String) or SendAsync(IEnumerable<EventData>, String)

iii. SendAsync(EventData) or SendAsync(IEnumerable<EventData>)
CreateReceiver(String, String, EventPosition, ReceiverOptions)

Create the EventHub receiver with given EventPosition. The receiver is created for a specific EventHub Partition from the specific consumer group.
CreateWithAzureActiveDirectory(Uri, String, AzureActiveDirectoryTokenProvider+AuthenticationCallback, String, Nullable<TimeSpan>, TransportType)

Creates a new instance of the EventHubClient by using Azure Active Directory authentication.
CreateWithManagedIdentity(Uri, String, Nullable<TimeSpan>, TransportType)

Creates a new instance of the EventHubClient by using Azure Managed Identity authentication.
CreateWithTokenProvider(Uri, String, ITokenProvider, Nullable<TimeSpan>, TransportType)

Creates a new instance of the Event Hubs client using the specified endpoint, entity path, and token provider.
GetPartitionRuntimeInformationAsync(String)

Retrieves runtime information for the specified partition of the Event Hub.
GetRuntimeInformationAsync()

Retrieves EventHub runtime information
OnCloseAsync()
OnCreateReceiver(String, String, EventPosition, Nullable<Int64>, ReceiverOptions)
OnGetPartitionRuntimeInformationAsync(String)
OnGetRuntimeInformationAsync()
OnRetryPolicyUpdate()

Handle retry policy updates here.
RegisterPlugin(EventHubsPlugin)

Registers a EventHubsPlugin to be used with this client.

(Inherited from ClientEntity)
SendAsync(EventData, String)

Sends an 'EventData with a partitionKey to EventHub. All EventData's with a partitionKey are guaranteed to land on the same partition. This send pattern emphasize data correlation over general availability and latency.

There are 3 ways to send to EventHubs, each exposed as a method (along with its batched overload):

i. SendAsync(EventData) or SendAsync(IEnumerable<EventData>)

ii. SendAsync(EventData, String) or SendAsync(IEnumerable<EventData>, String)

iii. SendAsync(EventData) or SendAsync(IEnumerable<EventData>)

Use this type of send if:

a) There is a need for correlation of events based on Sender instance; The sender can generate a UniqueId and set it as partitionKey - which on the received Message can be used for correlation

b) The client wants to take control of distribution of data across partitions.

Multiple PartitionKeys could be mapped to one Partition. EventHubs service uses a proprietary Hash algorithm to map the PartitionKey to a PartitionId. Using this type of send (Sending using a specific partitionKey) could sometimes result in partitions which are not evenly distributed.
SendAsync(EventData)

Send EventData to EventHub. The sent EventData will land on any arbitrarily chosen EventHubs partition.

There are 3 ways to send to EventHubs, each exposed as a method (along with its sendBatch overload):

i. SendAsync(EventData) or SendAsync(IEnumerable<EventData>)

ii. SendAsync(EventData, String) or SendAsync(IEnumerable<EventData>, String)

iii. SendAsync(EventData) or SendAsync(IEnumerable<EventData>)

Use this method to send if:

a) the SendAsync(EventData) operation should be highly available and

b) the data needs to be evenly distributed among all partitions; exception being, when a subset of partitions are unavailable

SendAsync(EventData) sends the EventData to a Service Gateway, which in-turn will forward the EventData to one of the EventHub's partitions. Here's the message forwarding algorithm:

i. Forward the EventDatas to EventHub partitions, by equally distributing the data among all partitions (ex: Round-robin the EventDatas to all EventHub partitions)

ii. If one of the EventHub partitions is unavailable for a moment, the Service Gateway will automatically detect it and forward the message to another available partition - making the send operation highly-available.
SendAsync(EventDataBatch)

Send a batch of EventData in EventDataBatch.
SendAsync(IEnumerable<EventData>, String)

Send a 'batch of EventData with the same partitionKey' to EventHub. All EventData's with a partitionKey are guaranteed to land on the same partition. Multiple PartitionKey's will be mapped to one Partition.

There are 3 ways to send to EventHubs, to understand this particular type of send refer to the overload SendAsync(EventData, String), which is the same type of send and is used to send single EventData.

Sending a batch of EventData's is useful in the following cases:

i. Efficient send - sending a batch of EventData maximizes the overall throughput by optimally using the number of sessions created to EventHubs service.

ii. Sending multiple events in One Transaction. This is the reason why all events sent in a batch needs to have same partitionKey (so that they are sent to one partition only).
SendAsync(IEnumerable<EventData>)

Send a batch of EventData to EventHub. The sent EventData will land on any arbitrarily chosen EventHub partition. This is the most recommended way to send to EventHub.

There are 3 ways to send to EventHubs, to understand this particular type of send refer to the overload SendAsync(EventData), which is used to send single EventData. Use this overload if you need to send a batch of EventData.

Sending a batch of EventData's is useful in the following cases:

i. Efficient send - sending a batch of EventData maximizes the overall throughput by optimally using the number of sessions created to EventHub's service.

ii. Send multiple EventData's in a Transaction. To acheieve ACID properties, the Gateway Service will forward all EventData's in the batch to a single EventHub partition.
ThrowIfClosed()

Throws an exception if client object is already closed.

(Inherited from ClientEntity)
UnregisterPlugin(String)

Unregisters a EventHubsPlugin.

(Inherited from ClientEntity)

Applies to