Class EventProcessor<TPartition>

Provides a base for creating a custom processor which consumes events across all partitions of a given Event Hub for a specific consumer group. The processor is capable of collaborating with other instances for the same Event Hub and consumer group pairing to share work by using a common storage platform to communicate. Fault tolerance is also built-in, allowing the processor to be resilient in the face of errors.

Inheritance

System.Object

EventProcessor<TPartition>

PluggableCheckpointStoreEventProcessor<TPartition>

Namespace: System.Dynamic.ExpandoObject

Assembly: Azure.Messaging.EventHubs.dll

Syntax

public abstract class EventProcessor<TPartition> where TPartition : EventProcessorPartitionnew()

Type Parameters

TPartition The context of the partition for which an operation is being performed.

Remarks

To enable coordination for sharing of partitions between EventProcessor<TPartition> instances, they will assert exclusive read access to partitions for the consumer group. No other readers should be active in the consumer group other than processors intending to collaborate. Non-exclusive readers will be denied access; exclusive readers, including processors using a different storage locations, will interfere with the processor's operation and performance.

The EventProcessor<TPartition> is safe to cache and use for the lifetime of an application, which is the recommended approach. The processor is responsible for ensuring efficient network, CPU, and memory use. Calling either StopProcessingAsync(CancellationToken) or StopProcessing(CancellationToken) when all processing is complete or as the application is shutting down will ensure that network resources and other unmanaged objects are properly cleaned up.

Constructors

EventProcessor<TPartition>()

Initializes a new instance of the EventProcessor<TPartition> class.

Declaration

protected EventProcessor ();

EventProcessor<TPartition>(Int32, String, String, EventProcessorOptions)

Initializes a new instance of the EventProcessor<TPartition> class.

Declaration

protected EventProcessor (int eventBatchMaximumCount, string consumerGroup, string connectionString, Azure.Messaging.EventHubs.Primitives.EventProcessorOptions options = null);

Parameters

System.Int32 eventBatchMaximumCount The desired number of events to include in a batch to be processed. This size is the maximum count in a batch; the actual count may be smaller, depending on whether events are available in the Event Hub.

System.String consumerGroup The name of the consumer group this processor is associated with. The processor will assert exclusive read access to partitions for this group.

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.

EventProcessorOptions options The set of options to use for the processor.

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.

Exceptions

System.ArgumentOutOfRangeException Occurs when the requested eventBatchMaximumCount is less than 1.

EventProcessor<TPartition>(Int32, String, String, String, EventProcessorOptions)

Initializes a new instance of the EventProcessor<TPartition> class.

Declaration

protected EventProcessor (int eventBatchMaximumCount, string consumerGroup, string connectionString, string eventHubName, Azure.Messaging.EventHubs.Primitives.EventProcessorOptions options = null);

Parameters

System.Int32 eventBatchMaximumCount The desired number of events to include in a batch to be processed. This size is the maximum count in a batch; the actual count may be smaller, depending on whether events are available in the Event Hub.

System.String consumerGroup The name of the consumer group this processor is associated with. The processor will assert exclusive read access to partitions for this group.

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 processor with.

EventProcessorOptions options The set of options to use for the processor.

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.

Exceptions

System.ArgumentOutOfRangeException Occurs when the requested eventBatchMaximumCount is less than 1.

EventProcessor<TPartition>(Int32, String, String, String, AzureNamedKeyCredential, EventProcessorOptions)

Initializes a new instance of the EventProcessor<TPartition> class.

Declaration

protected EventProcessor (int eventBatchMaximumCount, string consumerGroup, string fullyQualifiedNamespace, string eventHubName, Azure.AzureNamedKeyCredential credential, Azure.Messaging.EventHubs.Primitives.EventProcessorOptions options = null);

Parameters

System.Int32 eventBatchMaximumCount The desired number of events to include in a batch to be processed. This size is the maximum count in a batch; the actual count may be smaller, depending on whether events are available in the Event Hub.

System.String consumerGroup The name of the consumer group this processor is associated with. The processor will assert exclusive read access to partitions for this group.

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 processor 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.

EventProcessorOptions options The set of options to use for the processor.

Exceptions

System.ArgumentOutOfRangeException Occurs when the requested eventBatchMaximumCount is less than 1.

EventProcessor<TPartition>(Int32, String, String, String, AzureSasCredential, EventProcessorOptions)

Initializes a new instance of the EventProcessor<TPartition> class.

Declaration

protected EventProcessor (int eventBatchMaximumCount, string consumerGroup, string fullyQualifiedNamespace, string eventHubName, Azure.AzureSasCredential credential, Azure.Messaging.EventHubs.Primitives.EventProcessorOptions options = null);

Parameters

System.Int32 eventBatchMaximumCount The desired number of events to include in a batch to be processed. This size is the maximum count in a batch; the actual count may be smaller, depending on whether events are available in the Event Hub.

System.String consumerGroup The name of the consumer group this processor is associated with. The processor will assert exclusive read access to partitions for this group.

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 processor with.

Azure.AzureSasCredential credential The shared 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.

EventProcessorOptions options The set of options to use for the processor.

Exceptions

System.ArgumentOutOfRangeException Occurs when the requested eventBatchMaximumCount is less than 1.

EventProcessor<TPartition>(Int32, String, String, String, TokenCredential, EventProcessorOptions)

Initializes a new instance of the EventProcessor<TPartition> class.

Declaration

protected EventProcessor (int eventBatchMaximumCount, string consumerGroup, string fullyQualifiedNamespace, string eventHubName, Azure.Core.TokenCredential credential, Azure.Messaging.EventHubs.Primitives.EventProcessorOptions options = null);

Parameters

System.Int32 eventBatchMaximumCount The desired number of events to include in a batch to be processed. This size is the maximum count in a batch; the actual count may be smaller, depending on whether events are available in the Event Hub.

System.String consumerGroup The name of the consumer group this processor is associated with. The processor will assert exclusive read access to partitions for this group.

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 processor 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.

EventProcessorOptions options The set of options to use for the processor.

Exceptions

System.ArgumentOutOfRangeException Occurs when the requested eventBatchMaximumCount is less than 1.

Properties

ConsumerGroup

The name of the consumer group this event processor is associated with. Events will be read only in the context of this group.

Declaration

public string ConsumerGroup { get; }

Property Value

System.String

EnableBatchTracing

Indicates whether or not this event processor should instrument batch event processing calls with distributed tracing. Implementations that instrument event processing themselves should set this to false.

Declaration

protected bool EnableBatchTracing { get; set; }

Property Value

System.Boolean

EventHubName

The name of the Event Hub that the processor is connected to, specific to the Event Hubs namespace that contains it.

Declaration

public string EventHubName { get; }

Property Value

System.String

EventHubProperties

The properties associated with the Event Hub being read from. This value is updated in each load balancing cycle.

Declaration

protected Azure.Messaging.EventHubs.EventHubProperties EventHubProperties { get; }

Property Value

EventHubProperties

FullyQualifiedNamespace

The fully qualified Event Hubs namespace that the processor 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 event processor.

Declaration

public string Identifier { get; }

Property Value

System.String

Remarks

The identifier can be set using the Identifier property on the EventProcessorOptions passed when constructing the processor. If not specified, a random identifier will be generated.

It is recommended that you set a stable unique identifier for processor instances, as this allows the processor to recover partition ownership when an application or host instance is restarted. It also aids readability in Azure SDK logs and allows for more easily correlating logs to a specific processor instance.

IsRunning

Indicates whether or not this event processor is currently running.

Declaration

public bool IsRunning { get; protected set; }

Property Value

System.Boolean

RetryPolicy

The active policy which governs retry attempts for the processor.

Declaration

protected Azure.Messaging.EventHubs.EventHubsRetryPolicy RetryPolicy { get; }

Property Value

EventHubsRetryPolicy

Methods

ClaimOwnershipAsync(IEnumerable<EventProcessorPartitionOwnership>, CancellationToken)

Attempts to claim ownership of the specified partitions for processing. This operation is used by load balancing to enable distributing the responsibility for processing partitions for an Event Hub and consumer group pairing amongst the active event processors.

Declaration

protected abstract System.Threading.Tasks.Task<System.Collections.Generic.IEnumerable<Azure.Messaging.EventHubs.Primitives.EventProcessorPartitionOwnership>> ClaimOwnershipAsync (System.Collections.Generic.IEnumerable<Azure.Messaging.EventHubs.Primitives.EventProcessorPartitionOwnership> desiredOwnership, System.Threading.CancellationToken cancellationToken);

Parameters

System.Collections.Generic.IEnumerable<EventProcessorPartitionOwnership> desiredOwnership The set of partition ownership desired by the event processor instance; this is the set of partitions that it will attempt to request responsibility for processing.

System.Threading.CancellationToken cancellationToken A System.Threading.CancellationToken instance to signal the request to cancel the processing. This is most likely to occur when the processor is shutting down.

Returns

System.Threading.Tasks.Task<System.Collections.Generic.IEnumerable<EventProcessorPartitionOwnership>> The set of ownership records for the partitions that were successfully claimed; this is expected to be the desiredOwnership or a subset of those partitions.

CreateConnection()

Creates an EventHubConnection to use for communicating with the Event Hubs service.

Declaration

protected internal virtual Azure.Messaging.EventHubs.EventHubConnection CreateConnection ();

Returns

EventHubConnection The requested EventHubConnection.

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.

GetCheckpointAsync(String, CancellationToken)

Returns a checkpoint for the Event Hub, consumer group, and identifier of the partition associated with the event processor instance, so that processing for a given partition can be properly initialized. The default implementation calls the ListCheckpointsAsync(CancellationToken) and filters results by PartitionId. It's recommended that this method is overridden in EventProcessor<TPartition> implementations to achieve an optimal performance.

Declaration

[System.Diagnostics.DebuggerStepThrough]
protected virtual System.Threading.Tasks.Task<Azure.Messaging.EventHubs.Primitives.EventProcessorCheckpoint> GetCheckpointAsync (string partitionId, System.Threading.CancellationToken cancellationToken);

Parameters

System.String partitionId The identifier of the partition for which to retrieve the checkpoint.

System.Threading.CancellationToken cancellationToken A System.Threading.CancellationToken instance to signal the request to cancel the processing. This is most likely to occur when the processor is shutting down.

Returns

System.Threading.Tasks.Task<EventProcessorCheckpoint> The checkpoint for the processor to take into account when initializing partition.

Remarks

Should a partition not have a corresponding checkpoint, the DefaultStartingPosition will be used to initialize the partition for processing.

In the event that a custom starting point is desired for a single partition, or each partition should start at a unique place, it is recommended that this method express that intent by returning checkpoints for those partitions with the desired custom starting location set.

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.

ListCheckpointsAsync(CancellationToken)

Produces a list of the available checkpoints for the Event Hub and consumer group associated with the event processor instance, so that processing for a given set of partitions can be properly initialized. It's recommended that GetCheckpointAsync(String, CancellationToken) is implemented instead of overriding ListCheckpointsAsync(CancellationToken) for better performance and efficiency.

Declaration

[System.ComponentModel.EditorBrowsable]
protected virtual System.Threading.Tasks.Task<System.Collections.Generic.IEnumerable<Azure.Messaging.EventHubs.Primitives.EventProcessorCheckpoint>> ListCheckpointsAsync (System.Threading.CancellationToken cancellationToken);

Parameters

System.Threading.CancellationToken cancellationToken A System.Threading.CancellationToken instance to signal the request to cancel the processing. This is most likely to occur when the processor is shutting down.

Returns

System.Threading.Tasks.Task<System.Collections.Generic.IEnumerable<EventProcessorCheckpoint>> The set of checkpoints for the processor to take into account when initializing partitions.

Remarks

This method exists to preserve backwards compatibility; it is highly recommended that GetCheckpointAsync(String, CancellationToken) be overridden and implemented instead to improve efficiency.

ListOwnershipAsync(CancellationToken)

Requests a list of the ownership assignments for partitions between each of the cooperating event processor instances for a given Event Hub and consumer group pairing. This method is used during load balancing to allow the processor to discover other active collaborators and to make decisions about how to best balance work between them.

Declaration

protected abstract System.Threading.Tasks.Task<System.Collections.Generic.IEnumerable<Azure.Messaging.EventHubs.Primitives.EventProcessorPartitionOwnership>> ListOwnershipAsync (System.Threading.CancellationToken cancellationToken);

Parameters

System.Threading.CancellationToken cancellationToken A System.Threading.CancellationToken instance to signal the request to cancel the processing. This is most likely to occur when the processor is shutting down.

Returns

System.Threading.Tasks.Task<System.Collections.Generic.IEnumerable<EventProcessorPartitionOwnership>> The set of ownership data to take into account when making load balancing decisions.

ListPartitionIdsAsync(EventHubConnection, CancellationToken)

Queries for the identifiers of the Event Hub partitions.

Declaration

protected virtual System.Threading.Tasks.Task<string[]> ListPartitionIdsAsync (Azure.Messaging.EventHubs.EventHubConnection connection, System.Threading.CancellationToken cancellationToken);

Parameters

EventHubConnection connection The active connection to the Event Hubs service.

System.Threading.CancellationToken cancellationToken A System.Threading.CancellationToken instance to signal the request to cancel the query.

Returns

System.Threading.Tasks.Task<System.String[]> The set of identifiers for the Event Hub partitions.

OnInitializingPartitionAsync(TPartition, CancellationToken)

Performs the tasks to initialize a partition, and its associated context, for event processing.

Declaration

protected virtual System.Threading.Tasks.Task OnInitializingPartitionAsync (TPartition partition, System.Threading.CancellationToken cancellationToken);

Parameters

partition The context of the partition being initialized. Only the well-known members of the EventProcessorPartition will be populated. If a custom context is being used, the implementor of this method is responsible for initializing custom members.

System.Threading.CancellationToken cancellationToken A System.Threading.CancellationToken instance to signal the request to cancel the initialization. This is most likely to occur if the partition is claimed by another event processor instance or the processor is shutting down.

Returns

System.Threading.Tasks.Task

Remarks

It is not recommended that the state of the processor be managed directly from within this method; requesting to start or stop the processor may result in

a deadlock scenario, especially if using the synchronous form of the call.

This method will be invoked concurrently, limited to one call per partition. The processor will await each invocation before beginning to process

the associated partition.

The processor will wait indefinitely for execution of the handler to complete. It is recommended for implementations to avoid

long-running operations, as they will delay processing for the associated partition.

OnPartitionProcessingStoppedAsync(TPartition, ProcessingStoppedReason, CancellationToken)

Performs the tasks needed when processing for a partition is being stopped. This commonly occurs when the partition is claimed by another event processor instance or when the current event processor instance is shutting down.

Declaration

protected virtual System.Threading.Tasks.Task OnPartitionProcessingStoppedAsync (TPartition partition, Azure.Messaging.EventHubs.Processor.ProcessingStoppedReason reason, System.Threading.CancellationToken cancellationToken);

Parameters

partition The context of the partition for which processing is being stopped.

ProcessingStoppedReason reason The reason that processing is being stopped for the partition.

System.Threading.CancellationToken cancellationToken A System.Threading.CancellationToken instance to signal the request to cancel the processing. This is not expected to signal under normal circumstances and will only occur if the processor encounters an unrecoverable error.

Returns

System.Threading.Tasks.Task

Remarks

It is not recommended that the state of the processor be managed directly from within this method; requesting to start or stop the processor may result in

a deadlock scenario, especially if using the synchronous form of the call.

This method will be invoked concurrently, as each close is independent. No time limit is imposed on an invocation; it is safe for implementations

to perform long-running operations and retries as needed. This handler has no influence on processing for the associated partition and offers no

guarantee that execution will complete before processing for the partition is restarted or migrates to a new host.

OnProcessingErrorAsync(Exception, TPartition, String, CancellationToken)

Performs the tasks needed when an unexpected exception occurs within the operation of the event processor infrastructure.

Declaration

protected abstract System.Threading.Tasks.Task OnProcessingErrorAsync (Exception exception, TPartition partition, string operationDescription, System.Threading.CancellationToken cancellationToken);

Parameters

System.Exception exception The exception that occurred during operation of the event processor.

partition The context of the partition associated with the error, if any; otherwise, null. This may only be initialized for members of EventProcessorPartition, depending on the point at which the error occurred.

System.String operationDescription A short textual description of the operation during which the exception occurred; intended to be informational only.

System.Threading.CancellationToken cancellationToken A System.Threading.CancellationToken instance to signal the request to cancel the processing. This is most likely to occur when the processor is shutting down.

Returns

System.Threading.Tasks.Task

Remarks

This error handler is invoked when there is an exception observed within the event processor itself; it is not invoked for exceptions in code that has been implemented to process events or other overrides and extension points that are not critical to the processor's operation. The event processor will make every effort to recover from exceptions and continue processing. Should an exception that cannot be recovered from be encountered, the processor will attempt to forfeit ownership of all partitions that it was processing so that work may be redistributed.

The exceptions surfaced to this method may be fatal or non-fatal; because the processor may not be able to accurately predict whether an exception was fatal or whether its state was corrupted, this method has responsibility for making the determination as to whether processing should be terminated or restarted. If desired, this can be done safely by calling StopProcessingAsync(CancellationToken) and/or StartProcessingAsync(CancellationToken).

It is recommended that, for production scenarios, the decision be made by considering observations made by this error handler, the method invoked when initializing processing for a partition, and the method invoked when processing for a partition is stopped. Many developers will also include data from their monitoring platforms in this decision as well.

As with event processing, should an exception occur in the code for the error handler, the event processor will allow it to bubble and will not attempt to handle it in any way. Developers are strongly encouraged to take exception scenarios into account and guard against them using try/catch blocks and other means as appropriate.

This method will be invoked concurrently and is not awaited by the processor, as each error is independent. No time limit is imposed on an invocation; it is safe for implementations to perform long-running operations and retries as needed.

OnProcessingEventBatchAsync(IEnumerable<EventData>, TPartition, CancellationToken)

Performs the tasks needed to process a batch of events for a given partition as they are read from the Event Hubs service.

Declaration

protected abstract System.Threading.Tasks.Task OnProcessingEventBatchAsync (System.Collections.Generic.IEnumerable<Azure.Messaging.EventHubs.EventData> events, TPartition partition, System.Threading.CancellationToken cancellationToken);

Parameters

System.Collections.Generic.IEnumerable<EventData> events The batch of events to be processed.

partition The context of the partition from which the events were read.

System.Threading.CancellationToken cancellationToken A System.Threading.CancellationToken instance to signal the request to cancel the processing. This is most likely to occur when the processor is shutting down.

Returns

System.Threading.Tasks.Task

Remarks

The number of events in the events batch may vary, with the batch containing between zero and maximum batch size that was specified when the processor was created. The actual number of events in a batch depends on the number events available in the processor's prefetch queue at the time when a read takes place.

When at least one event is available in the prefetch queue, they will be used to form the batch as close to the requested maximum batch size as possible without waiting for additional events from the Event Hub partition to be read. When no events are available in prefetch the processor will wait until at least one event is available or the requested MaximumWaitTime has elapsed, after which the batch will be dispatched for processing.

If MaximumWaitTime is null, the processor will continue trying to read from the Event Hub partition until a batch with at least one event could be formed and will not dispatch any empty batches to this method.

This method will be invoked concurrently, limited to one call per partition. The processor will await each invocation to ensure that the events from the same partition are processed in the order that they were read from the partition. No time limit is imposed on an invocation of this handler; the processor will wait indefinitely for execution to complete before dispatching another event for the associated partition. It is safe for implementations to perform long-running operations, retries, delays, and dead-lettering activities.

Should an exception occur within the code for this method, the event processor will allow it to propagate up the stack without attempting to handle it in any way. On most hosts, this will fault the task responsible for partition processing, causing it to be restarted from the last checkpoint. On some hosts, it may crash the process. Developers are strongly encouraged to take all exception scenarios into account and guard against them using try/catch blocks and other means as appropriate.

It is not recommended that the state of the processor be managed directly from within this method; requesting to start or stop the processor may result in a deadlock scenario, especially if using the synchronous form of the call.

ReadLastEnqueuedEventProperties(String)

A set of information about the last enqueued event of a partition, as observed by the associated EventHubs client associated with this context as events are received from the Event Hubs service. This is only available if the consumer was created with TrackLastEnqueuedEventProperties set.

Declaration

protected virtual Azure.Messaging.EventHubs.Consumer.LastEnqueuedEventProperties ReadLastEnqueuedEventProperties (string partitionId);

Parameters

System.String partitionId The identifier of the Event Hub partition to read the properties from.

Returns

LastEnqueuedEventProperties The set of properties for the last event that was enqueued to the partition.

Remarks

When information about the partition's last enqueued event is being tracked, each event received from the Event Hubs

service will carry metadata about the partition that it otherwise would not. This results in a small amount of

additional network bandwidth consumption that is generally a favorable trade-off when considered

against periodically making requests for partition properties using an Event Hub client.

Exceptions

System.InvalidOperationException Occurs when this method is invoked without TrackLastEnqueuedEventProperties set or when the processor is not running.

StartProcessing(CancellationToken)

Signals the EventProcessor<TPartition> to begin processing events. Should this method be called while the processor is running, no action is taken.

Declaration

public virtual void StartProcessing (System.Threading.CancellationToken cancellationToken = null);

Parameters

System.Threading.CancellationToken cancellationToken A System.Threading.CancellationToken instance to signal the request to cancel the start operation. This won't affect the EventProcessor<TPartition> once it starts running.

Exceptions

System.AggregateException As the processor starts, it will attempt to detect configuration and permissions errors that would prevent it from being able to recover without intervention. For example, an incorrect connection string or the inability to query the Event Hub would be detected. These exceptions will be packaged as an System.AggregateException, and will cause StartProcessing(CancellationToken) to fail.

StartProcessingAsync(CancellationToken)

Signals the EventProcessor<TPartition> to begin processing events. Should this method be called while the processor is running, no action is taken.

Declaration

[System.Diagnostics.DebuggerStepThrough]
public virtual System.Threading.Tasks.Task StartProcessingAsync (System.Threading.CancellationToken cancellationToken = null);

Parameters

System.Threading.CancellationToken cancellationToken A System.Threading.CancellationToken instance to signal the request to cancel the start operation. This won't affect the EventProcessor<TPartition> once it starts running.

Returns

System.Threading.Tasks.Task

Exceptions

System.AggregateException As the processor starts, it will attempt to detect configuration and permissions errors that would prevent it from being able to recover without intervention. For example, an incorrect connection string or the inability to query the Event Hub would be detected. These exceptions will be packaged as an System.AggregateException, and will cause StartProcessingAsync(CancellationToken) to fail.

StopProcessing(CancellationToken)

Signals the EventProcessor<TPartition> to stop processing events. Should this method be called while the processor is not running, no action is taken.

Declaration

public virtual void StopProcessing (System.Threading.CancellationToken cancellationToken = null);

Parameters

System.Threading.CancellationToken cancellationToken A System.Threading.CancellationToken instance to signal the request to cancel the stop operation. If the operation is successfully canceled, the EventProcessor<TPartition> will keep running.

Remarks

When stopping, the processor will update the ownership of partitions that it was responsible for processing and clean up network resources used for communication with the Event Hubs service. As a result, this method will perform network I/O and may need to wait for partition reads that were active to complete.

Due to service calls and network latency, an invocation of this method may take slightly longer than the specified MaximumWaitTime or if the wait time was not configured, the duration of the TryTimeout of the configured retry policy.

StopProcessingAsync(CancellationToken)

Signals the EventProcessor<TPartition> to stop processing events. Should this method be called while the processor is not running, no action is taken.

Declaration

[System.Diagnostics.DebuggerStepThrough]
public virtual System.Threading.Tasks.Task StopProcessingAsync (System.Threading.CancellationToken cancellationToken = null);

Parameters

System.Threading.CancellationToken cancellationToken A System.Threading.CancellationToken instance to signal the request to cancel the stop operation. If the operation is successfully canceled, the EventProcessor<TPartition> will keep running.

Returns

System.Threading.Tasks.Task

Remarks

When stopping, the processor will update the ownership of partitions that it was responsible for processing and clean up network resources used for communication with the Event Hubs service. As a result, this method will perform network I/O and may need to wait for partition reads that were active to complete.

Due to service calls and network latency, an invocation of this method may take slightly longer than the specified MaximumWaitTime or if the wait time was not configured, the duration of the TryTimeout of the configured retry policy.

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.

UpdateCheckpointAsync(String, CheckpointPosition, CancellationToken)

Creates or updates a checkpoint for a specific partition, identifying a position in the partition's event stream that an event processor should begin reading from.

Declaration

protected virtual System.Threading.Tasks.Task UpdateCheckpointAsync (string partitionId, Azure.Messaging.EventHubs.Processor.CheckpointPosition startingPosition, System.Threading.CancellationToken cancellationToken);

Parameters

System.String partitionId The identifier of the partition the checkpoint is for.

CheckpointPosition startingPosition The starting position to associate with the checkpoint, indicating that a processor should begin reading from the next event in the stream.

System.Threading.CancellationToken cancellationToken A System.Threading.CancellationToken instance to signal a request to cancel the operation.

Returns

System.Threading.Tasks.Task

UpdateCheckpointAsync(String, Int64, Nullable<Int64>, CancellationToken)

Obsolete.

Creates or updates a checkpoint for a specific partition, identifying a position in the partition's event stream that an event processor should begin reading from.

Declaration

[System.ComponentModel.EditorBrowsable]
[System.Obsolete("The Event Hubs service does not guarantee a numeric offset for all resource configurations.  Checkpoints created from a numeric offset may not work in all cases going forward. Please use a string-based offset via the overload accepting 'CheckpointPosition' instead.", false)]
protected virtual System.Threading.Tasks.Task UpdateCheckpointAsync (string partitionId, long offset, Nullable<long> sequenceNumber, System.Threading.CancellationToken cancellationToken);

Parameters

System.String partitionId The identifier of the partition the checkpoint is for.

System.Int64 offset The offset to associate with the checkpoint, intended as informational metadata. This will only be used for positioning if there is no value provided for sequenceNumber.

System.Nullable<System.Int64> sequenceNumber The sequence number to associate with the checkpoint, indicating that a processor should begin reading from the next event in the stream.

System.Threading.CancellationToken cancellationToken A System.Threading.CancellationToken instance to signal a request to cancel the operation.

Returns

System.Threading.Tasks.Task

Remarks

This method is obsolete and should no longer be used. Please use UpdateCheckpointAsync(String, CheckpointPosition, CancellationToken) instead.

ValidateProcessingPreconditions(CancellationToken)

Performs the tasks needed to validate basic configuration and permissions of the dependencies needed for the processor to function.

Declaration

[System.Diagnostics.DebuggerStepThrough]
protected internal virtual System.Threading.Tasks.Task ValidateProcessingPreconditions (System.Threading.CancellationToken cancellationToken);

Parameters

System.Threading.CancellationToken cancellationToken A System.Threading.CancellationToken instance to signal the request to cancel the validation.

Returns

System.Threading.Tasks.Task

Exceptions

System.AggregateException Any validation failures will result in an aggregate exception.