Class EventHubConsumerGroup

Namespace

Microsoft.ServiceBus.Messaging

Assembly

Microsoft.ServiceBus.dll

Represents the consumer group within an Event Hub. This class creates receivers for a specific consumer group within an Event Hub. This can be the default consumer group or another user-created consumer group.

public sealed class EventHubConsumerGroup : ClientEntity

Inheritance

object

ClientEntity

EventHubConsumerGroup

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()

Fields

DefaultGroupName

Specifies the default name of the consumer group, which is $Default. You cannot delete or update the default consumer group.

public const string DefaultGroupName = "$Default"

Field Value

string

StartOfStream

A constant that denotes the start of a stream. You can use this field as an offset argument during receiver creation.

public const string StartOfStream = "-1"

Field Value

string

Properties

EventHubPath

Gets the event hub path.

public string EventHubPath { get; }

Property Value

string

The event hub path

GroupName

Gets the name of the consumer group.

public string GroupName { get; }

Property Value

string

The name of the consumer group.

PrefetchCount

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

public int PrefetchCount { get; set; }

Property Value

int

The number of events that the receiver can cache.

Exceptions

ArgumentOutOfRangeException

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

PrefetchSizeInBytes

public long? PrefetchSizeInBytes { get; set; }

Property Value

long?

Methods

CreateReceiver(string)

Creates a new Event Hubs receiver in the specified partition. You can use the created receiver to receive events for one Event Hubs partition, specified by partitionId.

public EventHubReceiver CreateReceiver(string partitionId)

Parameters

partitionId string

The ID of the partition.

Returns

EventHubReceiver

Returns the EventHubReceiver object that is tied to the given Event Hubs partition.

Exceptions

MessagingException

Thrown if the service encounters a transient error.

MessagingCommunicationException

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

ArgumentOutOfRangeException

Thrown if partitionId is not within the expected range, as determined by the PartitionCount property.

System.ServiceModel.QuotaExceededException

Thrown if the number of receivers currently connected to the partition specified by partitionId has exceeded the maximum allowed quota set by the service.

ReceiverDisconnectedException

Thrown if there is currently a receiver connected to the partition as specified by partitionId, with an epoch specified.

CreateReceiver(string, DateTime)

Creates a new Event Hubs receiver in the specified partition, starting at the specified date and time. You can use the created receiver to receive events for one Event Hubs partition, specified by partitionId.

public EventHubReceiver CreateReceiver(string partitionId, DateTime startingDateTimeUtc)

Parameters

partitionId string

The ID of the partition.

startingDateTimeUtc DateTime

The starting UTC time for receiving messages.

Returns

EventHubReceiver

Returns the EventHubReceiver.

Exceptions

MessagingException

Thrown if the service encounters a transient error.

MessagingCommunicationException

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

ArgumentOutOfRangeException

Thrown if partitionId is not within the expected range, as determined by the PartitionCount property.

System.ServiceModel.QuotaExceededException

Thrown if the number of receivers currently connected to the partition specified by partitionId has exceeded the maximum allowed quota set by the service.

ReceiverDisconnectedException

Thrown if there is currently a receiver connected to the partition as specified by partitionId, with an epoch specified.

CreateReceiver(string, DateTime, long)

Creates a new Event Hubs receiver in the specified partition, starting at the specified date and time. You can use the created receiver to receive events for one Event Hubs partition, specified by partitionId.

public EventHubReceiver CreateReceiver(string partitionId, DateTime startingDateTimeUtc, long epoch)

Parameters

partitionId string

The ID of the partition.

startingDateTimeUtc DateTime

The starting UTC time for receiving messages.

epoch long

The epoch value. The service uses this value to enforce partition/lease ownership.

Returns

EventHubReceiver

Returns the EventHubReceiver.

Exceptions

MessagingException

Thrown if the service encounters a transient error.

MessagingCommunicationException

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

ArgumentOutOfRangeException

Thrown if partitionId is not within the expected range, as determined by the PartitionCount property.

CreateReceiver(string, long)

Creates a new Event Hubs receiver in the specified partition, and the specified epoch value. You can use the created receiver to receive events for one Event Hubs partition, specified by partitionId.

public EventHubReceiver CreateReceiver(string partitionId, long epoch)

Parameters

partitionId string

The ID of the partition.

epoch long

The epoch value. The service uses this value to enforce partition/lease ownership.

Returns

EventHubReceiver

Returns the EventHubReceiver.

Exceptions

MessagingException

Thrown if the service encounters a transient error.

MessagingCommunicationException

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

ArgumentOutOfRangeException

Thrown if partitionId is not within the expected range, as determined by the PartitionCount property.

CreateReceiver(string, string)

Creates a new Event Hubs receiver in the specified partition, at the specified starting offset. You can use the created receiver to receive events for one Event Hubs partition, specified by partitionId.

public EventHubReceiver CreateReceiver(string partitionId, string startingOffset)

Parameters

partitionId string

The ID of the partition.

startingOffset string

The starting offset at which to start receiving messages.

Returns

EventHubReceiver

Returns the EventHubReceiver.

Exceptions

ArgumentOutOfRangeException

Thrown if partitionId is not within the expected range, as determined by the PartitionCount property.

System.ServiceModel.QuotaExceededException

Thrown if the number of receivers currently connected to the partition specified by partitionId has exceeded the maximum allowed quota set by the service.

ReceiverDisconnectedException

Thrown if there is currently a receiver connected to the partition as specified by partitionId, with an epoch specified.

CreateReceiver(string, string, bool)

Creates a new Event Hubs receiver in the specified partition, at the specified starting offset. You can use the created receiver to receive events for one Event Hubs partition, specified by partitionId.

public EventHubReceiver CreateReceiver(string partitionId, string startingOffset, bool offsetInclusive)

Parameters

partitionId string

The ID of the partition.

startingOffset string

The starting offset at which to start receiving messages.

offsetInclusive bool

A Boolean value that indicates 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.

Returns

EventHubReceiver

Returns EventHubReceiver.

CreateReceiver(string, string, bool, long)

Creates a new Event Hubs receiver in the specified partition, at the specified starting offset. You can use the created receiver to receive events for one Event Hubs partition, specified by partitionId.

public EventHubReceiver CreateReceiver(string partitionId, string startingOffset, bool offsetInclusive, long epoch)

Parameters

partitionId string

The ID of the partition.

startingOffset string

The starting offset at which to start receiving messages.

offsetInclusive bool

A Boolean value that indicates 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.

epoch long

The epoch value. The service uses this value to enforce partition/lease ownership.

Returns

EventHubReceiver

Returns EventHubReceiver.

CreateReceiver(string, string, long)

Creates a new Event Hubs receiver in the specified partition, at the specified starting offset.

public EventHubReceiver CreateReceiver(string partitionId, string startingOffset, long epoch)

Parameters

partitionId string

The ID of the partition.

startingOffset string

The starting offset at which to start receiving messages. To specify the start of the stream, see StartOfStream.

epoch long

The epoch value. The service uses this value to enforce partition/lease ownership.

Returns

EventHubReceiver

Returns the EventHubReceiver.

Exceptions

MessagingException

Thrown if the service encounters a transient error.

MessagingCommunicationException

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

ArgumentOutOfRangeException

Thrown if partitionId is not within the expected range, as determined by the PartitionCount property.

CreateReceiverAsync(string)

Asynchronous version of CreateReceiver(string).

public Task<EventHubReceiver> CreateReceiverAsync(string partitionId)

Parameters

partitionId string

The ID of the partition.

Returns

Task<EventHubReceiver>

Returns Task<TResult>.

CreateReceiverAsync(string, DateTime)

Asynchronous version of CreateReceiver(string, DateTime).

public Task<EventHubReceiver> CreateReceiverAsync(string partitionId, DateTime startingDateTimeUtc)

Parameters

partitionId string

The ID of the partition.

startingDateTimeUtc DateTime

The starting UTC time for receiving messages.

Returns

Task<EventHubReceiver>

Returns Task<TResult>.

CreateReceiverAsync(string, DateTime, long)

Asynchronous version of CreateReceiver(string, DateTime, long).

public Task<EventHubReceiver> CreateReceiverAsync(string partitionId, DateTime startingDateTimeUtc, long epoch)

Parameters

partitionId string

The ID of the partition.

startingDateTimeUtc DateTime

The starting UTC time for receiving messages.

epoch long

The epoch value. The service uses this value to enforce partition/lease ownership.

Returns

Task<EventHubReceiver>

Returns Task<TResult>.

CreateReceiverAsync(string, long)

Asynchronous version of CreateReceiver(string, long).

public Task<EventHubReceiver> CreateReceiverAsync(string partitionId, long epoch)

Parameters

partitionId string

The ID of the partition.

epoch long

The epoch value. The service uses this value to enforce partition/lease ownership.

Returns

Task<EventHubReceiver>

Returns Task<TResult>.

CreateReceiverAsync(string, string)

Asynchronous version of CreateReceiver(string, string).

public Task<EventHubReceiver> CreateReceiverAsync(string partitionId, string startingOffset)

Parameters

partitionId string

The ID of the partition.

startingOffset string

The starting offset at which to start receiving messages.

Returns

Task<EventHubReceiver>

Returns Task<TResult>.

CreateReceiverAsync(string, string, bool)

Asynchronous version of CreateReceiver(string, string, bool).

public Task<EventHubReceiver> CreateReceiverAsync(string partitionId, string startingOffset, bool offsetInclusive)

Parameters

partitionId string

The ID of the partition.

startingOffset string

The starting offset at which to start receiving messages.

offsetInclusive bool

A Boolean value that indicates 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.

Returns

Task<EventHubReceiver>

Returns Task<TResult>.

CreateReceiverAsync(string, string, bool, long)

Asynchronous version of CreateReceiver(string, string, bool, long).

public Task<EventHubReceiver> CreateReceiverAsync(string partitionId, string startingOffset, bool offsetInclusive, long epoch)

Parameters

partitionId string

The ID of the partition.

startingOffset string

The starting offset at which to start receiving messages.

offsetInclusive bool

A Boolean value that indicates 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.

epoch long

The epoch value. The service uses this value to enforce partition/lease ownership.

Returns

Task<EventHubReceiver>

Returns Task<TResult>.

CreateReceiverAsync(string, string, long)

Asynchronous version of CreateReceiver(string, string, long).

public Task<EventHubReceiver> CreateReceiverAsync(string partitionId, string startingOffset, long epoch)

Parameters

partitionId string

The ID of the partition.

startingOffset string

The starting offset at which to start receiving messages. To specify the start of the stream, see StartOfStream.

epoch long

The epoch value. The service uses this value to enforce partition/lease ownership.

Returns

Task<EventHubReceiver>

Returns Task<TResult>.

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

RegisterProcessorAsync<T>(Lease, ICheckpointManager)

Asynchronous version of RegisterProcessor<T>(Lease, ICheckpointManager).

public Task RegisterProcessorAsync<T>(Lease lease, ICheckpointManager checkpointManager) where T : IEventProcessor

Parameters

lease Lease

Partition information.

checkpointManager ICheckpointManager

Checkpoints the offset for the specified partition when CheckpointAsync() is called.

Returns

Task

A task instance that represents the asynchronous operation.

Type Parameters

T

Implementation of IEventProcessor.

RegisterProcessorAsync<T>(Lease, ICheckpointManager, EventProcessorOptions)

Asynchronous version of RegisterProcessor<T>(Lease, ICheckpointManager, EventProcessorOptions).

public Task RegisterProcessorAsync<T>(Lease lease, ICheckpointManager checkpointManager, EventProcessorOptions processorOptions) where T : IEventProcessor

Parameters

lease Lease

Partition information.

checkpointManager ICheckpointManager

Checkpoints the offset for the specified partition when CheckpointAsync() is called.

processorOptions EventProcessorOptions

An EventProcessorOptions object.

Returns

Task

Returns Task.

Type Parameters

T

Implementation of IEventProcessor.

RegisterProcessorFactory(Lease, ICheckpointManager, IEventProcessorFactory)

Registers the IEventProcessorFactory object used to create an instance of IEventProcessor in order to start consuming events for the partition specified by PartitionId, starting from Offset. Use this overload to create an event processor that checkpoints the message offset using a custom implementation of ICheckpointManager.

public void RegisterProcessorFactory(Lease lease, ICheckpointManager checkpointManager, IEventProcessorFactory eventProcessorFactory)

Parameters

lease Lease

Partition information.

checkpointManager ICheckpointManager

Checkpoints the offset for the specified partition when CheckpointAsync() is called.

eventProcessorFactory IEventProcessorFactory

Factory to create an instance of IEventProcessor.

RegisterProcessorFactory(Lease, ICheckpointManager, IEventProcessorFactory, EventProcessorOptions)

Registers the IEventProcessorFactory object used to create an instance of IEventProcessor in order to start consuming events for the partition specified by PartitionId, starting from Offset. Use this overload to create an event processor that checkpoints the message offset using a custom implementation of ICheckpointManager.

public void RegisterProcessorFactory(Lease lease, ICheckpointManager checkpointManager, IEventProcessorFactory eventProcessorFactory, EventProcessorOptions processorOptions)

Parameters

lease Lease

Partition information.

checkpointManager ICheckpointManager

Checkpoints the offset for the specified partition when CheckpointAsync() is called.

eventProcessorFactory IEventProcessorFactory

Factory to create an instance of IEventProcessor.

processorOptions EventProcessorOptions

An EventProcessorOptions object.

RegisterProcessorFactoryAsync(Lease, ICheckpointManager, IEventProcessorFactory)

Asynchronous version of RegisterProcessorFactory(Lease, ICheckpointManager, IEventProcessorFactory).

public Task RegisterProcessorFactoryAsync(Lease lease, ICheckpointManager checkpointManager, IEventProcessorFactory eventProcessorFactory)

Parameters

lease Lease

Partition information.

checkpointManager ICheckpointManager

Checkpoints the offset for the specified partition when CheckpointAsync() is called.

eventProcessorFactory IEventProcessorFactory

Factory to create an instance of IEventProcessor.

Returns

Task

A task instance that represents the asynchronous operation.

RegisterProcessorFactoryAsync(Lease, ICheckpointManager, IEventProcessorFactory, EventProcessorOptions)

Asynchronous version of RegisterProcessorFactory(Lease, ICheckpointManager, IEventProcessorFactory, EventProcessorOptions).

public Task RegisterProcessorFactoryAsync(Lease lease, ICheckpointManager checkpointManager, IEventProcessorFactory eventProcessorFactory, EventProcessorOptions processorOptions)

Parameters

lease Lease

Partition information.

checkpointManager ICheckpointManager

Checkpoints the offset for the specified partition when CheckpointAsync() is called.

eventProcessorFactory IEventProcessorFactory

Factory to create an instance of IEventProcessor.

processorOptions EventProcessorOptions

An EventProcessorOptions object.

Returns

Task

Returns Task.

RegisterProcessor<T>(Lease, ICheckpointManager)

Registers an implementation of IEventProcessor in order to start consuming events from Event Hubs for the specified PartitionId starting from Offset. Use this overload to create an event processor that checkpoints the message offset using a custom implementation of ICheckpointManager.

public void RegisterProcessor<T>(Lease lease, ICheckpointManager checkpointManager) where T : IEventProcessor

Parameters

lease Lease

Partition information.

checkpointManager ICheckpointManager

Checkpoints the offset for the specified partition when CheckpointAsync() is called.

Type Parameters

T

Implementation of IEventProcessor.

RegisterProcessor<T>(Lease, ICheckpointManager, EventProcessorOptions)

Registers an implementation of IEventProcessor in order to start consuming events from Event Hubs for the specified PartitionId starting from Offset. Use this overload to create an event processor that checkpoints the message offset using a custom implementation of ICheckpointManager.

public void RegisterProcessor<T>(Lease lease, ICheckpointManager checkpointManager, EventProcessorOptions processorOptions) where T : IEventProcessor

Parameters

lease Lease

Partition information.

checkpointManager ICheckpointManager

Checkpoints the offset for the specified partition when CheckpointAsync() is called.

processorOptions EventProcessorOptions

An EventProcessorOptions object.

Type Parameters

T

Implementation of IEventProcessor.

UnregisterProcessor(Lease, CloseReason)

Unregisters IEventProcessor for the partition specified by PartitionId. This results in CloseAsync(PartitionContext, CloseReason) being called on the underlying event processor.

public void UnregisterProcessor(Lease lease, CloseReason reason)

Parameters

lease Lease

Partition information.

reason CloseReason

Reason for which UnregisterProcessor(Lease, CloseReason) was called.

UnregisterProcessorAsync(Lease, CloseReason)

Asynchronous version of UnregisterProcessor(Lease, CloseReason).

public Task UnregisterProcessorAsync(Lease lease, CloseReason reason)

Parameters

lease Lease

Partition information.

reason CloseReason

Reason that UnregisterProcessorAsync(Lease, CloseReason) was called.

Returns

Task

A task instance that represents the asynchronous operation.