Class EventHubProducerClient

A client responsible for publishing EventData to a specific Event Hub, grouped together in batches. Depending on the options specified when sending, events may be automatically assigned an available partition or may request a specific partition.

The EventHubProducerClient publishes immediately, ensuring a deterministic outcome for each send operation, though requires that callers own the responsibility of building and managing batches.

In scenarios where it is not important to have events published immediately and where maximizing partition availability is not a requirement, it is recommended to consider using the EventHubBufferedProducerClient, which takes responsibility for building and managing batches to reduce the complexity of doing so in application code.

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

Allowing partition assignment is recommended when:

  • The sending of events needs to be highly available.
  • The event data should be evenly distributed among all available partitions.

If no partition is specified, the following rules are used for automatically selecting one:

  1. Distribute the events equally amongst all available partitions using a round-robin approach.
  2. If a partition becomes unavailable, the Event Hubs service will automatically detect it and forward the message to another available partition.

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

EventHubProducerClient()

Initializes a new instance of the EventHubProducerClient class.

Declaration
protected EventHubProducerClient ();

EventHubProducerClient(String)

Initializes a new instance of the EventHubProducerClient class.

Declaration
public EventHubProducerClient (string connectionString);
Parameters
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.

EventHubProducerClient(EventHubConnection, EventHubProducerClientOptions)

Initializes a new instance of the EventHubProducerClient class.

Declaration
public EventHubProducerClient (Azure.Messaging.EventHubs.EventHubConnection connection, Azure.Messaging.EventHubs.Producer.EventHubProducerClientOptions clientOptions = null);
Parameters
EventHubConnection connection

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

A set of options to apply when configuring the producer.

EventHubProducerClient(String, EventHubProducerClientOptions)

Initializes a new instance of the EventHubProducerClient class.

Declaration
public EventHubProducerClient (string connectionString, Azure.Messaging.EventHubs.Producer.EventHubProducerClientOptions clientOptions);
Parameters
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.
EventHubProducerClientOptions 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.

EventHubProducerClient(String, String)

Initializes a new instance of the EventHubProducerClient class.

Declaration
public EventHubProducerClient (string connectionString, string eventHubName);
Parameters
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 producer 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.

EventHubProducerClient(String, String, EventHubProducerClientOptions)

Initializes a new instance of the EventHubProducerClient class.

Declaration
public EventHubProducerClient (string connectionString, string eventHubName, Azure.Messaging.EventHubs.Producer.EventHubProducerClientOptions clientOptions);
Parameters
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 producer with.
EventHubProducerClientOptions clientOptions

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

EventHubProducerClient(String, String, AzureNamedKeyCredential, EventHubProducerClientOptions)

Initializes a new instance of the EventHubProducerClient class.

Declaration
public EventHubProducerClient (string fullyQualifiedNamespace, string eventHubName, Azure.AzureNamedKeyCredential credential, Azure.Messaging.EventHubs.Producer.EventHubProducerClientOptions clientOptions = null);
Parameters
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 producer 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.
EventHubProducerClientOptions clientOptions

A set of options to apply when configuring the producer.

EventHubProducerClient(String, String, AzureSasCredential, EventHubProducerClientOptions)

Initializes a new instance of the EventHubProducerClient class.

Declaration
public EventHubProducerClient (string fullyQualifiedNamespace, string eventHubName, Azure.AzureSasCredential credential, Azure.Messaging.EventHubs.Producer.EventHubProducerClientOptions clientOptions = null);
Parameters
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 producer 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.
EventHubProducerClientOptions clientOptions

A set of options to apply when configuring the producer.

EventHubProducerClient(String, String, TokenCredential, EventHubProducerClientOptions)

Initializes a new instance of the EventHubProducerClient class.

Declaration
public EventHubProducerClient (string fullyQualifiedNamespace, string eventHubName, Azure.Core.TokenCredential credential, Azure.Messaging.EventHubs.Producer.EventHubProducerClientOptions clientOptions = null);
Parameters
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 producer 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.
EventHubProducerClientOptions clientOptions

A set of options to apply when configuring the producer.

Properties

EventHubName

The name of the Event Hub that the producer 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 producer 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 producer.

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

IsClosed

Indicates whether or not this EventHubProducerClient 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 producer.

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.

CreateBatchAsync(CancellationToken)

Creates a size-constraint batch to which EventData may be added using a try-based pattern. If an event would exceed the maximum allowable size of the batch, the batch will not allow adding the event and signal that scenario using its return value.

Because events that would violate the size constraint cannot be added, publishing a batch will not trigger an exception when attempting to send the events to the Event Hubs service.

Declaration
[System.Diagnostics.DebuggerStepThrough]
public virtual System.Threading.Tasks.ValueTask<Azure.Messaging.EventHubs.Producer.EventDataBatch> CreateBatchAsync (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.ValueTask<EventDataBatch>

An EventDataBatch with the default batch options.
See Also

CreateBatchAsync(CreateBatchOptions, CancellationToken)

Creates a size-constraint batch to which EventData may be added using a try-based pattern. If an event would exceed the maximum allowable size of the batch, the batch will not allow adding the event and signal that scenario using its return value.

Because events that would violate the size constraint cannot be added, publishing a batch will not trigger an exception when attempting to send the events to the Event Hubs service.

Declaration
[System.Diagnostics.DebuggerStepThrough]
public virtual System.Threading.Tasks.ValueTask<Azure.Messaging.EventHubs.Producer.EventDataBatch> CreateBatchAsync (Azure.Messaging.EventHubs.Producer.CreateBatchOptions options, System.Threading.CancellationToken cancellationToken = null);
Parameters
CreateBatchOptions options

The set of options to consider when creating this batch.
System.Threading.CancellationToken cancellationToken

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

An EventDataBatch with the requested options.
Exceptions
System.InvalidOperationException

Occurs when both a partition identifier and partition key have been specified in the options.
See Also

DisposeAsync()

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

GetPartitionPublishingPropertiesAsync(String, CancellationToken)

A set of information about the state of publishing for a partition, as observed by the EventHubProducerClient. This data can always be read, but will only be populated with information relevant to the active features for the producer client.

Declaration
[System.ComponentModel.EditorBrowsable]
[System.Diagnostics.DebuggerStepThrough]
protected internal virtual System.Threading.Tasks.Task<Azure.Messaging.EventHubs.Producer.PartitionPublishingProperties> GetPartitionPublishingPropertiesAsync (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<PartitionPublishingProperties>

The set of information about the publishing state of the requested partition, within the context of this producer.
Remarks

The state of a partition is only understood by the EventHubProducerClient after events have been published to that partition; calling this method for a partition before events have been published to it will return an empty set of properties.

SendAsync(EventDataBatch, CancellationToken)

Sends a set of events to the associated Event Hub using a batched approach.

Declaration
[System.Diagnostics.DebuggerStepThrough]
public virtual System.Threading.Tasks.Task SendAsync (Azure.Messaging.EventHubs.Producer.EventDataBatch eventBatch, System.Threading.CancellationToken cancellationToken = null);
Parameters
EventDataBatch eventBatch

The set of event data to send. A batch may be created using CreateBatchAsync(CancellationToken).
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; if no exception is thrown when awaited, the Event Hubs service has acknowledge receipt and assumed responsibility for delivery of the batch.
Remarks

When published, the result is atomic; either all events that belong to the batch were successful or all

have failed. Partial success is not possible.

Exceptions
System.InvalidOperationException

Occurs when both a partition identifier and partition key have been specified by the batch.
See Also

SendAsync(IEnumerable<EventData>, CancellationToken)

Sends a set of events to the associated Event Hub as a single operation. To avoid the overhead associated with measuring and validating the size in the client, validation will be delegated to the Event Hubs service and is deferred until the operation is invoked. The call will fail if the size of the specified set of events exceeds the maximum allowable size of a single batch.

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

The set of event data to send.
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; if no exception is thrown when awaited, the Event Hubs service has acknowledged receipt and assumed responsibility for delivery of the set of events to its partition.
Remarks

When published, the result is atomic; either all events that belong to the set were successful or all

have failed. Partial success is not possible.

Exceptions
EventHubsException

Occurs when the set of events exceeds the maximum size allowed in a single batch, as determined by the Event Hubs service. The Reason will be set to MessageSizeExceeded in this case.
System.Runtime.Serialization.SerializationException

Occurs when one of the events in the eventBatch has a member in the Properties collection that is an unsupported type for serialization. See the Properties remarks for details.
See Also

SendAsync(IEnumerable<EventData>, SendEventOptions, CancellationToken)

Sends a set of events to the associated Event Hub as a single operation. To avoid the overhead associated with measuring and validating the size in the client, validation will be delegated to the Event Hubs service and is deferred until the operation is invoked. The call will fail if the size of the specified set of events exceeds the maximum allowable size of a single batch.

Declaration
[System.Diagnostics.DebuggerStepThrough]
public virtual System.Threading.Tasks.Task SendAsync (System.Collections.Generic.IEnumerable<Azure.Messaging.EventHubs.EventData> eventBatch, Azure.Messaging.EventHubs.Producer.SendEventOptions options, System.Threading.CancellationToken cancellationToken = null);
Parameters
System.Collections.Generic.IEnumerable<EventData> eventBatch

The set of event data to send.
SendEventOptions options

The set of options to consider when sending 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

A task to be resolved on when the operation has completed; if no exception is thrown when awaited, the Event Hubs service has acknowledged receipt and assumed responsibility for delivery of the set of events to its partition.
Remarks

When published, the result is atomic; either all events that belong to the set were successful or all

have failed. Partial success is not possible.

Exceptions
System.InvalidOperationException

Occurs when both a partition identifier and partition key have been specified in the options.
EventHubsException

Occurs when the set of events exceeds the maximum size allowed in a single batch, as determined by the Event Hubs service. The Reason will be set to MessageSizeExceeded in this case.
System.Runtime.Serialization.SerializationException

Occurs when one of the events in the eventBatch has a member in the Properties collection that is an unsupported type for serialization. See the Properties remarks for details.
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.

See Also