EventProcessorClient Class
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Allows for consuming and processing events across all partitions of a given Event Hub within the scope of 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.
public class EventProcessorClient : Azure.Messaging.EventHubs.Primitives.EventProcessor<Azure.Messaging.EventHubs.Primitives.EventProcessorPartition>type EventProcessorClient = class
inherit EventProcessor<EventProcessorPartition>Public Class EventProcessorClient
Inherits EventProcessor(Of EventProcessorPartition)- Inheritance
Remarks
To enable coordination for sharing of partitions between EventProcessorClient 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 EventProcessorClient is safe to cache and use for the lifetime of an application, and that is best practice when the application processes events regularly or semi-regularly. The processor is responsible for ensuring efficient network, CPU, and memory use. Calling either StopProcessingAsync(CancellationToken) or StopProcessing(CancellationToken) when processing is complete or as the application is shutting down will ensure that network resources and other unmanaged objects are properly cleaned up.
Constructors
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. |
| 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 |
| EventHubName |
The name of the Event Hub that the processor is connected to, specific to the Event Hubs namespace that contains it. |
| EventHubProperties |
The properties associated with the Event Hub being read from. This value is updated in each load balancing cycle. (Inherited from EventProcessor<TPartition>) |
| FullyQualifiedNamespace |
The fully qualified Event Hubs namespace that the processor is associated with. This is likely
to be similar to |
| Identifier |
A unique name used to identify this event processor. |
| IsRunning |
Indicates whether or not this event processor is currently running. |
| RetryPolicy |
The active policy which governs retry attempts for the processor. (Inherited from EventProcessor<TPartition>) |
Methods
| ClaimOwnershipAsync(IEnumerable<EventProcessorPartitionOwnership>, CancellationToken) |
Attempts to claim ownership of the specified partitions for processing. This method is used by load balancing to allow event processor instances to distribute the responsibility for processing partitions for a given Event Hub and consumer group pairing amongst the active event processors. |
| CreateConnection() |
Creates an EventHubConnection to use for communicating with the Event Hubs service. |
| GetCheckpointAsync(String, CancellationToken) |
Returns a checkpoint for the Event Hub, consumer group, and partition ID associated with the event processor instance, so that processing for a given partition can be properly initialized. |
| ListOwnershipAsync(CancellationToken) |
Produces 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 when load balancing to allow the processor to discover other active collaborators and to make decisions about how to best balance work between them. |
| ListPartitionIdsAsync(EventHubConnection, CancellationToken) |
Queries for the identifiers of the Event Hub partitions. (Inherited from EventProcessor<TPartition>) |
| OnInitializingPartitionAsync(EventProcessorPartition, CancellationToken) |
Performs the tasks to initialize a partition, and its associated context, for event processing. |
| OnInitializingPartitionAsync(TPartition, CancellationToken) |
Performs the tasks to initialize a partition, and its associated context, for event processing. (Inherited from EventProcessor<TPartition>) |
| OnPartitionProcessingStoppedAsync(EventProcessorPartition, 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. |
| 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. (Inherited from EventProcessor<TPartition>) |
| OnProcessingErrorAsync(Exception, EventProcessorPartition, String, CancellationToken) |
Performs the tasks needed when an unexpected exception occurs within the operation of the event processor infrastructure. |
| OnProcessingErrorAsync(Exception, TPartition, String, CancellationToken) |
Performs the tasks needed when an unexpected exception occurs within the operation of the event processor infrastructure. (Inherited from EventProcessor<TPartition>) |
| OnProcessingEventBatchAsync(IEnumerable<EventData>, EventProcessorPartition, CancellationToken) |
Performs the tasks needed to process a batch of events for a given partition as they are read from the Event Hubs service. |
| 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. (Inherited from EventProcessor<TPartition>) |
| 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. (Inherited from EventProcessor<TPartition>) |
| StartProcessing(CancellationToken) |
Signals the EventProcessorClient to begin processing events. Should this method be called while the processor is running, no action is taken. |
| StartProcessingAsync(CancellationToken) |
Signals the EventProcessorClient to begin processing events. Should this method be called while the processor is running, no action is taken. |
| StopProcessing(CancellationToken) |
Signals the EventProcessorClient to stop processing events. Should this method be called while the processor is not running, no action is taken. |
| StopProcessingAsync(CancellationToken) |
Signals the EventProcessorClient to stop processing events. Should this method be called while the processor is not running, no action is taken. |
| 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. |
| UpdateCheckpointAsync(String, Int64, Nullable<Int64>, 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. |
| UpdateCheckpointAsync(String, Int64, Nullable<Int64>, 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. (Inherited from EventProcessor<TPartition>) |
| ValidateProcessingPreconditions(CancellationToken) |
Performs the tasks needed to validate basic configuration and permissions of the dependencies needed for the processor to function. |
Events
| PartitionClosingAsync |
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. 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. |
| PartitionInitializingAsync |
Performs the tasks to initialize a partition, and its associated context, for event processing. 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. |
| ProcessErrorAsync |
Performs the tasks needed when an unexpected exception occurs within the operation of the event processor infrastructure. Implementation is mandatory. This error handler is invoked when there is an exception observed within the EventProcessorClient itself; it is not invoked for exceptions in code that has been implemented to process events or other event handlers and extension points that execute developer code. The EventProcessorClient 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. |
| ProcessEventAsync |
Performs the tasks needed to process a batch of events for a given partition as they are read from the Event Hubs service. Implementation is mandatory. 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 handler; requesting to start or stop the processor may result in a deadlock scenario, especially if using the synchronous form of the call. |
