Class EventHubClient

Namespace

Microsoft.ServiceBus.Messaging

Assembly

Microsoft.ServiceBus.dll

An anchor class used to send and receive events to and from an Event Hub.

public abstract class EventHubClient : ClientEntity

Inheritance

object

ClientEntity

EventHubClient

Inherited Members

ClientEntity.Abort()

ClientEntity.Close()

ClientEntity.CloseAsync()

ClientEntity.Fault()

ClientEntity.OnOpen(TimeSpan)

ClientEntity.ThrowIfClosed()

ClientEntity.ThrowIfDisposed()

ClientEntity.ThrowIfDisposedOrNotOpen()

ClientEntity.ThrowIfFaulted()

ClientEntity.ThrowIfDisposedOrImmutable()

ClientEntity.OnOpened()

ClientEntity.OnClosed()

ClientEntity.OnFaulted()

ClientEntity.RetryPolicy

ClientEntity.IsClosed

ClientEntity.ThisLock

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Properties

DisableEntityLevelPerformanceCounters

Gets or sets a value to indicate if entity level perf counters should be collected in memory. Note that this only affect entity level counters, and namespace level counters are always collected.

public bool DisableEntityLevelPerformanceCounters { get; set; }

Property Value

bool

Remarks

By default this is set to false - meaning by default we do collect entity level perf counters. Setting this value will not affect existing collected counters, and will only stop counters from new entity being collected.

Path

Gets the path of the Event Hub.

public string Path { get; }

Property Value

string

The path of the Event Hub.

PrefetchCount

Gets or sets the number of events that any receive operation will actively cache. By default, this value is inherited from MessagingFactory if the current instance is created from the factory method. Otherwise, the default value is 10,000.

public int PrefetchCount { get; set; }

Property Value

int

The number of messages that the message receiver can simultaneously request.

Remarks

Note that setting the count too low will affect the effective performance of the Event Hub receive call.

Exceptions

ArgumentOutOfRangeException

Thrown if the value is less than the minimum required value of 10.

PrefetchSizeInBytes

Gets or sets the maximum size (in bytes) in total that any receive operation will actively cache. The size of each event data is determined by the SerializedSizeInBytes property.

public long? PrefetchSizeInBytes { get; set; }

Property Value

long?

Returns long.

Remarks

The size limit is not an absolute limit, and can go over by as much as (PrefetchSizeInBytes/256kBytes) number of event worth of bytes. Any EventHubConsumerGroup created from this instance will inherit this value by default. Changes to this value will not be propagated to already created consumer group, but will be used by new EventHubConsumerGroup created after the change. Also setting this value to non-null value will set PrefetchCount to zero. Note that setting the size too low will affect the effective performance of the Event Hub receive call.

Exceptions

ArgumentOutOfRangeException

Thrown when the size value is less than the minimum required value of 260K bytes.

Methods

Create(string)

Creates a new instance of the EventHubClient instance, using a connection string from the application configuration settings.

public static EventHubClient Create(string path)

Parameters

path string

The path to the Event Hub.

Returns

EventHubClient

The newly created Event Hub client object.

Remarks

This method will attempt to retrieve the connection string information from either app.config, or web.config files. User must supply the connection string using the "AppSettings" section of the configuration. The format of the section is as follows:

        <pre><code class="lang-csharp"></code></pre>

CreateBatch()

Creates a batch where event data objects can be added for later SendBatch or SendBatchAsync call.

public EventDataBatch CreateBatch()

Returns

EventDataBatch

Returns EventDataBatch.

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.

public static EventHubClient CreateFromConnectionString(string connectionString)

Parameters

connectionString string

The connection string to use.

Returns

EventHubClient

The newly created EventHubClient object.

Examples

Sample showing how to populate the EntityPath in connectionString

var connectionStringBuilder = new ServiceBusConnectionStringBuilder(connectionString);
connectionStringBuilder.EntityPath = eventHubDescription.Path;
                                                                         var eventHubClient = EventHubClient.CreateFromConnectionString(connectionStringBuilder.ToString());</code></pre>

Remarks

The connection can be obtained either from the Azure portal, or created from a ServiceBusConnectionStringBuilder instance.

Exceptions

ArgumentException

Thrown when the format of the connectionString parameter is incorrect.

ArgumentException

Thrown when the format of the parameter connectionString is incorrect.

CreateFromConnectionString(string, string)

Creates a new instance of the Event Hubs client using the specified connection string. Use this overload only when the connection string does not use the EntityPath property.

public static EventHubClient CreateFromConnectionString(string connectionString, string path)

Parameters

connectionString string

The connection string to be used.

path string

The path to the Event Hub.

Returns

EventHubClient

The newly created EventHubClient object.

Remarks

The connection can be obtained either from the Azure portal, or created from a ServiceBusConnectionStringBuilder instance.

Exceptions

ArgumentException

Thrown when the format of the parameters is incorrect.

CreatePartitionedSender(string)

Creates an Event Hubs sender for the specified Event Hubs partition.

public EventHubSender CreatePartitionedSender(string partitionId)

Parameters

partitionId string

The ID of the partition.

Returns

EventHubSender

Returns the EventHubSender object.

CreatePartitionedSenderAsync(string)

Asynchronous version of CreatePartitionedSender(string).

public Task<EventHubSender> CreatePartitionedSenderAsync(string partitionId)

Parameters

partitionId string

The ID of the partition.

Returns

Task<EventHubSender>

Returns Task<TResult>.

CreateSender(string)

Creates an Event Hubs sender for the specified publisher.

public EventHubSender CreateSender(string publisher)

Parameters

publisher string

The publisher identifier.

Returns

EventHubSender

Returns EventHubSender.

CreateSenderAsync()

Creates the Event Hubs sender. This method is for internal use, and not meant to be called from user code.

protected abstract Task<MessageSender> CreateSenderAsync()

Returns

Task<MessageSender>

The task representing the asynchronous operation.

CreateSenderAsync(string)

Asynchronous version of CreateSender(string).

public Task<EventHubSender> CreateSenderAsync(string publisher)

Parameters

publisher string

The publisher identifier.

Returns

Task<EventHubSender>

Returns Task<TResult>.

GetConsumerGroup(string)

Returns the consumer group with the specified name, for the receive operation of event data.

public EventHubConsumerGroup GetConsumerGroup(string groupName)

Parameters

groupName string

The name of the group.

Returns

EventHubConsumerGroup

A EventHubConsumerGroup instance, corresponding to the consumer group.

GetDefaultConsumerGroup()

Returns the default consumer group, for the receive operation of event data.

public EventHubConsumerGroup GetDefaultConsumerGroup()

Returns

EventHubConsumerGroup

The default EventHubConsumerGroup.

Remarks

Default ConsumerGroup cannot perform checkpoint operations. To perform checkpoint operations, user should create a explicit ConsumerGroup

GetPartitionRuntimeInformation(string)

Retrieves runtime information for the specified partition of the Event Hub.

public virtual PartitionRuntimeInformation GetPartitionRuntimeInformation(string partitionId)

Parameters

partitionId string

The partition ID.

Returns

PartitionRuntimeInformation

Returns PartitionRuntimeInformation.

GetPartitionRuntimeInformationAsync(string)

Asynchronous version of GetPartitionRuntimeInformation(string).

public virtual Task<PartitionRuntimeInformation> GetPartitionRuntimeInformationAsync(string partitionId)

Parameters

partitionId string

The partition ID.

Returns

Task<PartitionRuntimeInformation>

Returns Task<TResult>.

GetRuntimeInformation()

Retrieves Event Hubs runtime information, which is required for creating EventHubSender or EventHubReceiver objects.

public virtual EventHubRuntimeInformation GetRuntimeInformation()

Returns

EventHubRuntimeInformation

Returns EventHubRuntimeInformation.

GetRuntimeInformationAsync()

Asynchronous version of GetRuntimeInformation().

public virtual Task<EventHubRuntimeInformation> GetRuntimeInformationAsync()

Returns

Task<EventHubRuntimeInformation>

Returns Task<TResult>.

OnAbort()

Executes the abort action.

protected override void OnAbort()

OnBeginClose(TimeSpan, AsyncCallback, object)

Executes the begin close action.

protected override IAsyncResult OnBeginClose(TimeSpan timeout, AsyncCallback callback, object state)

Parameters

timeout TimeSpan

The wait time before the operation times out.

callback AsyncCallback

An AsyncCallback delegate that references the method to invoke when the operation is complete.

state object

A user-defined object that contains information about the receive operation. This object is passed to the EndClose delegate when the operation is complete.

Returns

IAsyncResult

An IAsyncResult that references the asynchronous Close operation.

OnBeginOpen(TimeSpan, AsyncCallback, object)

Executes the begin open action.

protected override IAsyncResult OnBeginOpen(TimeSpan timeout, AsyncCallback callback, object state)

Parameters

timeout TimeSpan

The wait time before the operation times out.

callback AsyncCallback

An AsyncCallback delegate that references the method to invoke when the operation is complete.

state object

A user-defined object that contains information about the receive operation. This object is passed to the EndOpen delegate when the operation is complete.

Returns

IAsyncResult

An IAsyncResult that references the asynchronous Open operation.

OnClose(TimeSpan)

Executes the close action.

protected override void OnClose(TimeSpan timeout)

Parameters

timeout TimeSpan

The wait time before the operation times out.

OnEndClose(IAsyncResult)

Executes the end close action.

protected override void OnEndClose(IAsyncResult result)

Parameters

result IAsyncResult

An IAsyncResult that references the asynchronous Close operation.

OnEndOpen(IAsyncResult)

Executes the end open action.

protected override void OnEndOpen(IAsyncResult result)

Parameters

result IAsyncResult

An IAsyncResult that references the asynchronous Open operation.

Send(EventData)

Sends event data to an Event Hub.

public void Send(EventData data)

Parameters

data EventData

The event data.

Remarks

Any EventData instance send using this method must have the PartitionKey set.

SendAsync(EventData)

Asynchronously sends event data to an Event Hub.

public Task SendAsync(EventData data)

Parameters

data EventData

The EventData to send.

Returns

Task

The task representing the asynchronous operation.

Remarks

Any EventData instance send using this method must have the PartitionKey set.

SendBatch(IEnumerable<EventData>)

Sends a batch of event data.

public void SendBatch(IEnumerable<EventData> eventDataList)

Parameters

eventDataList IEnumerable<EventData>

An IEnumerable object containing event data instances.

Remarks

User should make sure the total serialized size of eventDataList should be under the size limit of one event data transmission, which is 256k by default. Also note that there will be some overhead to form the batch.

Exceptions

MessageSizeExceededException

Thrown if the total serialized size of eventDataList exceeds the allowed size limit for one event transmission (256k by default).

SendBatchAsync(IEnumerable<EventData>)

Asynchronously sends a batch of event data.

public Task SendBatchAsync(IEnumerable<EventData> eventDataList)

Parameters

eventDataList IEnumerable<EventData>

An IEnumerable object containing event data instances.

Returns

Task

Returns Task.

Remarks

User should make sure the total serialized size of eventDataList should be under the size limit of one event data transmission, which is 256k by default. Also note that there will be some overhead to form the batch.

Exceptions

MessageSizeExceededException

Thrown if the total serialized size of eventDataList exceeds the allowed size limit for one event transmission (256k by default).