Class EventProcessorOptions

The set of options that can be specified when creating an EventProcessor<TPartition> to configure its behavior.

Inheritance
System.Object
EventProcessorOptions
Namespace: System.Dynamic.ExpandoObject
Assembly: Azure.Messaging.EventHubs.dll
Syntax
public class EventProcessorOptions

Constructors

EventProcessorOptions()

Declaration
public EventProcessorOptions ();

Properties

ConnectionOptions

The options used for configuring the connection to the Event Hubs service.

Declaration
public Azure.Messaging.EventHubs.EventHubConnectionOptions ConnectionOptions { get; set; }
Property Value
EventHubConnectionOptions

DefaultStartingPosition

The position within a partition where the event processor should begin reading events when no checkpoint can be found.

Declaration
public Azure.Messaging.EventHubs.Consumer.EventPosition DefaultStartingPosition { get; set; }
Property Value
EventPosition

Remarks

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 those values be returned by the ListCheckpointsAsync(CancellationToken) method as if they were previously saved checkpoints.

The default starting position is Earliest.

See Also

Identifier

A unique name used to identify the event processor. If null or empty, a GUID will be used as the identifier.

Declaration
public string Identifier { get; set; }
Property Value
System.String

If not specified, a random unique identifier will be generated.
Remarks

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.

LoadBalancingStrategy

The strategy that an event processor will use to make decisions about partition ownership when performing load balancing to share work with other event processors.

Declaration
public Azure.Messaging.EventHubs.Processor.LoadBalancingStrategy LoadBalancingStrategy { get; set; }
Property Value
LoadBalancingStrategy

The default strategy is Greedy.
See Also

LoadBalancingUpdateInterval

The desired amount of time to allow between load balancing verification attempts.

Declaration
public TimeSpan LoadBalancingUpdateInterval { get; set; }
Property Value
System.TimeSpan

The default load balancing interval is 30 seconds.
Remarks

Because load balancing holds less priority than processing events, this interval

should be considered the minimum time that will elapse between verification attempts; operations

with higher priority may cause a delay longer than this interval for load balancing.

Exceptions
System.ArgumentOutOfRangeException

Occurs when the requested interval is negative.

MaximumWaitTime

The maximum amount of time to wait for events to become available from a given partition before emitting an empty batch of events.

Declaration
public Nullable<TimeSpan> MaximumWaitTime { get; set; }
Property Value
System.Nullable<System.TimeSpan>

If null, the processor will wait indefinitely for a batch of events to become available and will not dispatch them to be processed while waiting; otherwise, a batch will always be emitted within this interval, whether or not it is empty.

The default wait time is null.
Exceptions
System.ArgumentOutOfRangeException

Occurs when the requested wait time is negative.

PartitionOwnershipExpirationInterval

The desired amount of time to consider a partition owned by a specific event processor instance before the ownership is considered stale and the partition becomes eligible to be requested by another event processor that wishes to assume responsibility for processing it.

Declaration
public TimeSpan PartitionOwnershipExpirationInterval { get; set; }
Property Value
System.TimeSpan

The default ownership interval is 2 minutes.
Remarks

As a general guideline, it is advised that this value be greater than the configured LoadBalancingUpdateInterval by at least a factor of two. It is recommended that this be a factor of three or more, unless there are application scenarios that require more aggressive ownership expiration.

Exceptions
System.ArgumentOutOfRangeException

Occurs when the requested interval is negative.

PrefetchCount

The number of events that will be eagerly requested from the Event Hubs service and queued locally without regard to whether a read operation is currently active, intended to help maximize throughput by allowing events to be read from from a local cache rather than waiting on a service request.

Declaration
public int PrefetchCount { get; set; }
Property Value
System.Int32

The PrefetchCount is a control that developers can use to help tune performance for the specific needs of an application, given its expected size of events, throughput needs, and expected scenarios for using Event Hubs.

The default prefetch count is 300.
Remarks

The size of the prefetch count has an influence on the efficiency of reading events from the Event Hubs service. The larger the size of the cache, the more efficiently service operations can be buffered in the background to improve throughput. This comes at the cost of additional memory use and potentially increases network I/O.

For scenarios where the size of events is small and many events are flowing through the system, requesting more events in a batch and using a higher PrefetchCount may help improve throughput. For scenarios where the size of events is larger or when processing of events is expected to be a heavier and slower operation, requesting fewer events in a batch and using a smaller PrefetchCount may help manage resource use without incurring a non-trivial cost to throughput.

Regardless of the values, it is generally recommended that the PrefetchCount be at least 2-3 times as large as the number of events in a batch to allow for efficient buffering of service operations.

Exceptions
System.ArgumentOutOfRangeException

Occurs when the requested count is negative.

PrefetchSizeInBytes

The desired number of bytes to attempt to eagerly request from the Event Hubs service and queued locally without regard to whether a read operation is currently active, intended to help maximize throughput by allowing events to be read from from a local cache rather than waiting on a service request.

Declaration
public Nullable<long> PrefetchSizeInBytes { get; set; }
Property Value
System.Nullable<System.Int64>

When set to null, the option is considered disabled; otherwise, it will be considered enabled and take precedence over any value specified for the PrefetchCountThe PrefetchSizeInBytes is an advanced control that developers can use to help tune performance in some scenarios; it is recommended to prefer using the PrefetchCount over this option where possible for more accurate control and more predictable throughput.

This size should be considered a statement of intent rather than a guaranteed limit; the local cache may be larger or smaller than the number of bytes specified, and will always contain at least one event when the PrefetchSizeInBytes is specified. A heuristic is used to predict the average event size to use for size calculations, which should be expected to fluctuate as traffic passes through the system. Consequently, the resulting resource use will fluctuate as well.

This option is disabled by default with the value set to null.
Exceptions
System.ArgumentOutOfRangeException

Occurs when the requested size is negative.

RetryOptions

The set of options to use for determining whether a failed operation should be retried and, if so, the amount of time to wait between retry attempts. These options also control the amount of time allowed for receiving event batches and other interactions with the Event Hubs service.

Declaration
public Azure.Messaging.EventHubs.EventHubsRetryOptions RetryOptions { get; set; }
Property Value
EventHubsRetryOptions

TrackLastEnqueuedEventProperties

Indicates whether or not the processor should request information on the last enqueued event on the partition associated with a given event, and track that information as events are received.

Declaration
public bool TrackLastEnqueuedEventProperties { get; set; }
Property Value
System.Boolean

true if information about a partition's last event should be requested and tracked; otherwise, false. The default value is true.
Remarks

When information about a 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 one of the Event Hub clients.

Methods

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.

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.

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.