EventHubBufferedProducerClient Class

Reference

Definition

Namespace:: Azure.Messaging.EventHubs.Producer

Assembly:: Azure.Messaging.EventHubs.dll

Package:: Azure.Messaging.EventHubs v5.11.5

Package:: Azure.Messaging.EventHubs v5.12.0-beta.1

Source:: EventHubBufferedProducerClient.cs

Source:: EventHubBufferedProducerClient.cs

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

A client responsible for publishing instances of EventData to a specific Event Hub. Depending on the options specified when events are enqueued, they may be automatically assigned to a partition, grouped according to the specified partition key, or assigned a specifically requested partition.

The EventHubBufferedProducerClient does not publish immediately, instead using a deferred model where events are collected into a buffer so that they may be efficiently batched and published when the batch is full or the MaximumWaitTime has elapsed with no new events enqueued.

This model is intended to shift the burden of batch management from callers, at the cost of non-deterministic timing, for when events will be published. There are additional trade-offs to consider, as well:

If the application crashes, events in the buffer will not have been published. To prevent data loss, callers are encouraged to track publishing progress using the SendEventBatchSucceededAsync and SendEventBatchFailedAsync handlers.
Events specifying a partition key may be assigned a different partition than those using the same key with other producers.
In the unlikely event that a partition becomes temporarily unavailable, the EventHubBufferedProducerClient may take longer to recover than other producers.

In scenarios where it is important to have events published immediately with a deterministic outcome, ensure that partition keys are assigned to a partition consistent with other publishers, or where maximizing availability is a requirement, using the EventHubProducerClient is recommended.

public class EventHubBufferedProducerClient : IAsyncDisposable

type EventHubBufferedProducerClient = class
    interface IAsyncDisposable

Public Class EventHubBufferedProducerClient
Implements IAsyncDisposable

Inheritance: Object
EventHubBufferedProducerClient

Implements: IAsyncDisposable

Remarks

The EventHubBufferedProducerClient is safe to cache and use as a singleton for the lifetime of an application, which is the recommended approach. The producer is responsible for ensuring efficient network, CPU, and memory use. Calling either CloseAsync(Boolean, CancellationToken) or DisposeAsync() when no more events will be enqueued or as the application is shutting down is required so that the buffer can be flushed and resources cleaned up properly.

Constructors

EventHubBufferedProducerClient()	Used for mocking the producer for testing purposes.
EventHubBufferedProducerClient(EventHubConnection, EventHubBufferedProducerClientOptions)	Initializes a new instance of the EventHubBufferedProducerClient class.
EventHubBufferedProducerClient(String, EventHubBufferedProducerClientOptions)	Initializes a new instance of the EventHubBufferedProducerClient class.
EventHubBufferedProducerClient(String, String, AzureNamedKeyCredential, EventHubBufferedProducerClientOptions)	Initializes a new instance of the EventHubBufferedProducerClient class.
EventHubBufferedProducerClient(String, String, AzureSasCredential, EventHubBufferedProducerClientOptions)	Initializes a new instance of the EventHubBufferedProducerClient class.
EventHubBufferedProducerClient(String, String, EventHubBufferedProducerClientOptions)	Initializes a new instance of the EventHubBufferedProducerClient class.
EventHubBufferedProducerClient(String, String, TokenCredential, EventHubBufferedProducerClientOptions)	Initializes a new instance of the EventHubBufferedProducerClient class.
EventHubBufferedProducerClient(String, String)	Initializes a new instance of the EventHubBufferedProducerClient class.
EventHubBufferedProducerClient(String)	Initializes a new instance of the EventHubBufferedProducerClient class.

Properties

EventHubName	The name of the Event Hub that this producer is connected to, specific to the Event Hubs namespace that contains it.
FullyQualifiedNamespace	The fully qualified Event Hubs namespace that this producer is currently associated with, which will likely be similar to `{yournamespace}.servicebus.windows.net`.
Identifier	A unique name to identify the buffered producer.
IsClosed	Indicates whether or not this EventHubBufferedProducerClient has been closed.
IsPublishing	Indicates whether or not this EventHubBufferedProducerClient is currently active and publishing queued events.
TotalBufferedEventCount	The total number of events that are currently buffered and waiting to be published, across all partitions.

Methods

CloseAsync(Boolean, CancellationToken)	Closes the producer and performs the tasks needed to clean up all the resources used by the EventHubBufferedProducerClient.
DisposeAsync()	Closes the producer and performs the tasks needed to clean up all the resources used by the EventHubBufferedProducerClient.
EnqueueEventAsync(EventData, CancellationToken)	Enqueues an EventData into the buffer to be published to the Event Hub. If there is no capacity in the buffer when this method is invoked, it will wait for space to become available and ensure that the `eventData` has been enqueued. When this call returns, the `eventData` has been accepted into the buffer, but it may not have been published yet. Publishing will take place at a nondeterministic point in the future as the buffer is processed.
EnqueueEventAsync(EventData, EnqueueEventOptions, CancellationToken)	Enqueues an EventData into the buffer to be published to the Event Hub. If there is no capacity in the buffer when this method is invoked, it will wait for space to become available and ensure that the `eventData` has been enqueued. When this call returns, the `eventData` has been accepted into the buffer, but it may not have been published yet. Publishing will take place at a nondeterministic point in the future as the buffer is processed.
EnqueueEventsAsync(IEnumerable<EventData>, CancellationToken)	Enqueues a set of EventData into the buffer to be published to the Event Hub. If there is insufficient capacity in the buffer when this method is invoked, it will wait for space to become available and ensure that all `events` in the `events` set have been enqueued. When this call returns, the `events` have been accepted into the buffer, but it may not have been published yet. Publishing will take place at a nondeterministic point in the future as the buffer is processed.
EnqueueEventsAsync(IEnumerable<EventData>, EnqueueEventOptions, CancellationToken)	Enqueues a set of EventData into the buffer to be published to the Event Hub. If there is insufficient capacity in the buffer when this method is invoked, it will wait for space to become available and ensure that all `events` in the `events` set have been enqueued. When this call returns, the `events` have been accepted into the buffer, but it may not have been published yet. Publishing will take place at a nondeterministic point in the future as the buffer is processed.
FlushAsync(CancellationToken)	Attempts to publish all events in the buffer immediately. This may result in multiple batches being published, the outcome of each of which will be individually reported by the SendEventBatchSucceededAsync and SendEventBatchFailedAsync handlers. Upon completion of this method, the buffer will be empty.
GetBufferedEventCount(String)	The number of events that are buffered and waiting to be published for a given partition.
GetEventHubPropertiesAsync(CancellationToken)	Retrieves information about the Event Hub that the connection is associated with, including the number of partitions present and their identifiers.
GetPartitionIdsAsync(CancellationToken)	Retrieves the set of identifiers for the partitions of an Event Hub.
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.
ListPartitionIdsAsync(EventHubProducerClient, CancellationToken)	Queries for the identifiers of the Event Hub partitions.
OnSendFailedAsync(IReadOnlyList<EventData>, Exception, String, CancellationToken)	Responsible for raising the SendEventBatchFailedAsync event upon the failed publishing of a batch of events, after all eligible retries are exhausted.
OnSendSucceededAsync(IReadOnlyList<EventData>, String, CancellationToken)	Responsible for raising the SendEventBatchSucceededAsync event upon the successful publishing of a batch of events.

Events

SendEventBatchFailedAsync

Invoked for any batch of events that failed to be published to the Event Hub, this handler must be provided before events may be enqueued. If this producer was not configured with MaximumConcurrentSends and MaximumConcurrentSendsPerPartition both set to 1, the handler will be invoked concurrently.

It is safe to attempt resending the events by calling EnqueueEventAsync(EventData, EnqueueEventOptions, CancellationToken) or EnqueueEventsAsync(IEnumerable<EventData>, EnqueueEventOptions, CancellationToken) from within this handler. It is important to note that doing so will place them at the end of the buffer; the original order will not be maintained.

This handler will be awaited after failure to publish the batch; the publishing operation is not considered complete until the handler call returns. It is advised that no long-running operations be performed in the handler to avoid negatively impacting throughput.

It is not recommended to invoke CloseAsync(Boolean, CancellationToken) or DisposeAsync() from this handler; doing so may result in a deadlock scenario if those calls are awaited.

SendEventBatchSucceededAsync

Invoked after each batch of events has been successfully published to the Event Hub, this handler is optional and is intended to provide notifications for interested listeners. If this producer was configured with MaximumConcurrentSends or MaximumConcurrentSendsPerPartition set greater than 1, the handler will be invoked concurrently.

This handler will be awaited after publishing the batch; the publishing operation will not be considered complete until the handler call returns. It is advised that no long-running operations be performed in the handler to avoid negatively impacting throughput.

It is not recommended to invoke CloseAsync(Boolean, CancellationToken) or DisposeAsync() from this handler; doing so may result in a deadlock scenario if those calls are awaited.

Applies to

Share via