Class EventHubReceiver

Namespace

Microsoft.ServiceBus.Messaging

Assembly

Microsoft.ServiceBus.dll

A client class used in receive operations related to an Event Hub consumer group. Represents a logical receiver connection to a specific Event Hub partition within a consumer group.

public sealed class EventHubReceiver : ClientEntity

Inheritance

object

ClientEntity

EventHubReceiver

Inherited Members

ClientEntity.Abort()

ClientEntity.Close()

ClientEntity.CloseAsync()

ClientEntity.RetryPolicy

ClientEntity.IsClosed

object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Properties

Epoch

Gets the epoch value that is used to determine partition ownership during the receive operation.

public long? Epoch { get; }

Property Value

long?

Returns long.

EventHubPath

Gets the event hub path.

public string EventHubPath { get; }

Property Value

string

The event hub path.

Identifier

Gets the identifier of a receiver which was set during the creation of the receiver.

public string Identifier { get; }

Property Value

string

A string representing the identifier of a receiver. It will return null if the identifier is not set.

Name

Gets the name of the Event Hub.

public string Name { get; }

Property Value

string

The name of the Event Hub.

OffsetInclusive

Gets a value indicating whether StartingOffset is treated as an inclusive offset, meaning that the first event returned is the event that contains the starting offset. Normally, the first event returned is the event after the starting offset.

public bool OffsetInclusive { get; }

Property Value

bool

Returns bool.

PartitionId

Gets the partition ID for a logical partition of an Event Hub.

public string PartitionId { get; }

Property Value

string

The partition identifier.

PrefetchCount

Gets or sets the number of events that any receive operation will actively cache. By default, this value is inherited from EventHubConsumerGroup. The default value is 300.

public int PrefetchCount { get; set; }

Property Value

int

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

Remarks

Changes to this value will be used in next receive operation, however this does not affect the number of events already cached by the receiver. Setting this property to non-zero value will set PrefetchSizeInBytes to null. 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. the size might go over by at least one event data worth of size. Changes to this value will be used in next receive operation, however this does not affect the number of events already cached by the receiver. Setting this property 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.

ReceiverRuntimeMetricEnabled

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

public bool ReceiverRuntimeMetricEnabled { get; }

Property Value

bool

RuntimeInfo

Gets the approximate receiver runtime information for a logical partition of an Event Hub. To enable the setting, refer to ReceiverOptions and EnableReceiverRuntimeMetric

public ReceiverRuntimeInfo RuntimeInfo { get; }

Property Value

ReceiverRuntimeInfo

StartingDateTimeUtc

Gets the starting date and time in UTC format for this receiver. The Receive() method starts receiving the next event after this StartingDateTimeUtc value. If null, the receiver starts receiving events from the beginning of the Event Hubs event stream.

public DateTime? StartingDateTimeUtc { get; }

Property Value

DateTime?

The starting date and time in UTC.

Remarks

Service only uses this datetime as an approximation when delivering next event. Keep in mind that there can be clock skew between client time and service time, so user application should be designed to handle duplication in event delivery.

StartingOffset

Gets the starting offset for this receiver. The Receive() method starts receiving the next event after this offset value. If the value is null, the receiver starts receiving events from the beginning of the Event Hubs event stream.

public string StartingOffset { get; }

Property Value

string

The starting offset.

Remarks

This starting offset ties to one partition only, represented by PartitionId.

Methods

OnAbort()

protected override void OnAbort()

OnBeginClose(TimeSpan, AsyncCallback, object)

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

Parameters

timeout TimeSpan

callback AsyncCallback

state object

Returns

IAsyncResult

Returns IAsyncResult.

OnBeginOpen(TimeSpan, AsyncCallback, object)

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

Parameters

timeout TimeSpan

callback AsyncCallback

state object

Returns

IAsyncResult

Returns IAsyncResult.

OnClose(TimeSpan)

protected override void OnClose(TimeSpan timeout)

Parameters

timeout TimeSpan

OnEndClose(IAsyncResult)

protected override void OnEndClose(IAsyncResult result)

Parameters

result IAsyncResult

OnEndOpen(IAsyncResult)

protected override void OnEndOpen(IAsyncResult result)

Parameters

result IAsyncResult

OnOpen(TimeSpan)

protected override void OnOpen(TimeSpan timeout)

Parameters

timeout TimeSpan

Receive()

Receives Event Hubs event data.

public EventData Receive()

Returns

EventData

Returns the received EventData object, or null if no event data is available.

Exceptions

MessagingException

Thrown if the service encounters a transient error.

MessagingCommunicationException

Thrown if the client has a problem connecting to the service.

ServerBusyException

Thrown if the current namespace is placing too much load on the system.

ReceiverDisconnectedException

Thrown if another receiver with a higher Epoch value is connected as the current receiver to the same partition specified by PartitionId.

Receive(int)

Receives Event Hubs event data, up to the specified count.

public IEnumerable<EventData> Receive(int maxCount)

Parameters

maxCount int

The maximum amount of event data the user is willing to accept in one call.

Returns

IEnumerable<EventData>

Returns the received EventData collection. The collection is either empty if no event is returned within the specified time, or all events up to maxCount are returned.

Remarks

Service does not wait for maxCount events to be filled before returning to user. It returns as soon as there are any events available.

Exceptions

MessagingException

Thrown if the service encounters a transient error.

MessagingCommunicationException

Thrown if the client has a problem connecting to the service.

ServerBusyException

Thrown if the current namespace is placing too much load on the system.

ReceiverDisconnectedException

Thrown if another receiver with a higher Epoch value is connected as the current receiver to the same partition specified by PartitionId.

Receive(int, TimeSpan)

Receives Event Hubs event data, up to the specified count with the specified timeout value.

public IEnumerable<EventData> Receive(int maxCount, TimeSpan waitTime)

Parameters

maxCount int

The maximum amount of event data the user is willing to accept in one call.

waitTime TimeSpan

The maximum time the user is willing to wait for event data to arrive.

Returns

IEnumerable<EventData>

Returns the received EventData collection. The collection is either empty if no event is returned within the specified time, or all events up to maxCount are returned.

Remarks

waitTime is not a guaranteed wait time, as API will return data as soon as it is available. Also service does not wait for maxCount events to be filled before returning to user. it returns as soon as there are any events available.

Exceptions

MessagingException

Thrown if the service encounters a transient error.

MessagingCommunicationException

Thrown if the client has a problem connecting to the service.

ServerBusyException

Thrown if the current namespace is placing too much load on the system.

ReceiverDisconnectedException

Thrown if another receiver with a higher Epoch value is connected as the current receiver to the same partition specified by PartitionId.

Receive(TimeSpan)

Receives Event Hubs event data with the specified timeout value.

public EventData Receive(TimeSpan waitTime)

Parameters

waitTime TimeSpan

The maximum time the user is willing to wait for event data to arrive.

Returns

EventData

Returns the received EventData collection, or null if there is no event data available.

Remarks

waitTime is not a guaranteed wait time, as API will return data as soon as it is available.

Exceptions

MessagingException

Thrown if the service encounters a transient error.

MessagingCommunicationException

Thrown if the client has a problem connecting to the service.

ServerBusyException

Thrown if the current namespace is placing too much load on the system.

ReceiverDisconnectedException

Thrown if another receiver with a higher Epoch value is connected as the current receiver to the same partition specified by PartitionId.

ReceiveAsync()

Asynchronous version of Receive().

public Task<EventData> ReceiveAsync()

Returns

Task<EventData>

The task representing the asynchronous operation.

ReceiveAsync(int)

Asynchronous version of Receive(int).

public Task<IEnumerable<EventData>> ReceiveAsync(int maxCount)

Parameters

maxCount int

The maximum amount of event data the user is willing to accept in one call.

Returns

Task<IEnumerable<EventData>>

Returns Task<TResult>.

Remarks

Service does not wait for maxCount events to be filled before returning to user. It returns as soon as there are any events available.

ReceiveAsync(int, TimeSpan)

Asynchronous version of Receive(int, TimeSpan).

public Task<IEnumerable<EventData>> ReceiveAsync(int maxCount, TimeSpan waitTime)

Parameters

maxCount int

The maximum amount of event data the user is willing to accept in one call.

waitTime TimeSpan

The maximum time the user is willing to wait for event data to arrive.

Returns

Task<IEnumerable<EventData>>

Returns Task<TResult>.

Remarks

waitTime is not a guaranteed wait time, as API will return data as soon as it is available. Also service does not wait for maxCount events to be filled before returning to user. It returns as soon as there are any events available.

ReceiveAsync(TimeSpan)

Asynchronous version of Receive(TimeSpan).

public Task<EventData> ReceiveAsync(TimeSpan waitTime)

Parameters

waitTime TimeSpan

The maximum time the user is willing to wait for event data to arrive.

Returns

Task<EventData>

The task representing the asynchronous operation.

Remarks

waitTime is not a guaranteed wait time, as API will return data as soon as it is available.