Class ReadEventOptions
The set of options that can be specified to configure behavior when reading events from an EventHubConsumerClient.
Inheritance
Namespace: System.Dynamic.ExpandoObject
Assembly: Azure.Messaging.EventHubs.dll
Syntax
public class ReadEventOptionsConstructors
ReadEventOptions()
Declaration
public ReadEventOptions ();Properties
CacheEventCount
The maximum number of events that will be read from the Event Hubs service and held in a local memory cache when reading is active and events are being emitted to an enumerator for processing.
Declaration
public int CacheEventCount { get; set; }Property Value
|
System.Int32
The CacheEventCount 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. |
Remarks
The size of this cache 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, using a larger CacheEventCount and 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, using a smaller size CacheEventCount and 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 CacheEventCount to allow for efficient buffering of service operations.
Exceptions
|
System.ArgumentOutOfRangeException
Occurs when the requested count is less than 1. |
MaximumWaitTime
The maximum amount of time to wait to for an event to be available when reading before reading an empty event.
Declaration
public Nullable<TimeSpan> MaximumWaitTime { get; set; }Property Value
|
System.Nullable<System.TimeSpan>
If specified, should there be no events available before this waiting period expires, an empty event will be returned, allowing control to return to the reader that was waiting. If |
Exceptions
|
System.ArgumentOutOfRangeException
Occurs when the requested wait time is negative. |
OwnerLevel
When populated, the owner level indicates that a reading is intended to be performed exclusively for events in the requested partition and for the associated consumer group. To do so, reading will attempt to assert ownership over the partition; in the case where more than one exclusive reader in the consumer group attempts to assert ownership for the same partition, the one having a larger OwnerLevel value will "win".
When an exclusive reader is used, other readers which are non-exclusive or which have a lower owner level will either not be allowed to be created, if they already exist, will encounter an exception during the next attempted operation.
Declaration
public Nullable<long> OwnerLevel { get; set; }Property Value
|
System.Nullable<System.Int64>
The relative priority to associate with an exclusive reader; for a non-exclusive reader, this value should be |
Exceptions
|
EventHubsException
Occurs when the owner level is set and the EventHubConsumerClient is unable to read from the requested Event Hub partition due to being denied ownership. In this case, the EventHubsException.FailureReason will be set to ConsumerDisconnected. |
See Also
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. |
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, using a larger CacheEventCount and 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, using a smaller size CacheEventCount and 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 CacheEventCount 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 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. |
Exceptions
|
System.ArgumentOutOfRangeException
Occurs when the requested size is negative. |
TrackLastEnqueuedEventProperties
Indicates whether or not the reader should request information on the last enqueued event on the partition associated with a given event, and track that information as events are read.
Declaration
public bool TrackLastEnqueuedEventProperties { get; set; }Property Value
|
System.Boolean
|
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
|
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. |