Class EventHubOptions

Namespace

Microsoft.Azure.WebJobs.EventHubs

Assembly

Microsoft.Azure.WebJobs.Extensions.EventHubs.dll

public class EventHubOptions : IOptionsFormatter

Inheritance

object

EventHubOptions

Implements

IOptionsFormatter

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Constructors

EventHubOptions()

public EventHubOptions()

Properties

BatchCheckpointFrequency

Gets or sets the number of batches to process before creating an EventHub cursor checkpoint. Default 1.

public int BatchCheckpointFrequency { get; set; }

Property Value

int

Remarks

If EnableCheckpointing is set to false, this value is ignored.

ClientRetryOptions

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.

public EventHubsRetryOptions ClientRetryOptions { get; set; }

Property Value

EventHubsRetryOptions

CustomEndpointAddress

The address to use for establishing a connection to the Event Hubs service, allowing network requests to be routed through any application gateways or other paths needed for the host environment.

public Uri CustomEndpointAddress { get; set; }

Property Value

Uri

This address will override the default endpoint of the Event Hubs namespace when making the network request to the service. The default endpoint specified in a connection string or by a fully qualified namespace will still be needed to negotiate the connection with the Event Hubs service.

EnableCheckpointing

Gets or sets a value indicating whether the trigger will create checkpoints as events are being processed. The default value is true.

public bool EnableCheckpointing { get; set; }

Property Value

bool

true if checkpoints will be written; otherwise, false.

Remarks

This value takes precedence over BatchCheckpointFrequency, which will be ignored if this property is set to false.

InitialOffsetOptions

Gets the initial offset options to apply when processing. This only applies when no checkpoint information is available.

public InitialOffsetOptions InitialOffsetOptions { get; }

Property Value

InitialOffsetOptions

LoadBalancingUpdateInterval

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

public TimeSpan LoadBalancingUpdateInterval { get; set; }

Property Value

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

ArgumentOutOfRangeException

Occurs when the requested interval is negative.

MaxEventBatchSize

Gets or sets the maximum number of events delivered in a batch. This setting applies only to functions that receive multiple events. Default 100.

public int MaxEventBatchSize { get; set; }

Property Value

int

MaxWaitTime

Gets or sets the maximum time that the trigger should wait to fill a batch before invoking the function. This is only considered when MinEventBatchSize is set to larger than 1 and is otherwise unused. If less than MinEventBatchSize events were available before the wait time elapses, the function will be invoked with a partial batch. Default is 60 seconds. The longest allowed wait time is 10 minutes.

public TimeSpan MaxWaitTime { get; set; }

Property Value

TimeSpan

Remarks

This interval is not a strict guarantee for the exact timing on which the function will be invoked. There is a small margin of error due to timer precision. When scaling takes place, the first invocation with a partial batch may take place more quickly or may take up to twice the configured MaxWaitTime.

MinEventBatchSize

Gets or sets the minimum number of events desired for a batch. This setting applies only to functions that receive multiple events. This value must be less than MaxEventBatchSize and is used in conjunction with MaxWaitTime. Default 1.

public int MinEventBatchSize { get; set; }

Property Value

int

Remarks

The minimum size is not a strict guarantee, as a partial batch will be dispatched if a full batch cannot be prepared before the MaxWaitTime has elapsed. Partial batches are also likely for the first invocation of the function after scaling takes place.

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.

public TimeSpan PartitionOwnershipExpirationInterval { get; set; }

Property Value

TimeSpan

The default ownership interval is 2 minutes.

Remarks

As a general guideline, it is advised that this value be greater than the configured Azure.Messaging.EventHubs.Primitives.EventProcessorOptions.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

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.

public int PrefetchCount { get; set; }

Property Value

int

The Azure.Messaging.EventHubs.Primitives.EventProcessorOptions.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 Azure.Messaging.EventHubs.Primitives.EventProcessorOptions.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 Azure.Messaging.EventHubs.Primitives.EventProcessorOptions.PrefetchCount may help manage resource use without incurring a non-trivial cost to throughput.

Regardless of the values, it is generally recommended that the Azure.Messaging.EventHubs.Primitives.EventProcessorOptions.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

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.

public long? PrefetchSizeInBytes { get; set; }

Property Value

long?

When set to null, the option is considered disabled; otherwise, it will be considered enabled and take precedence over any value specified for the Azure.Messaging.EventHubs.Primitives.EventProcessorOptions.PrefetchCountThe Azure.Messaging.EventHubs.Primitives.EventProcessorOptions.PrefetchSizeInBytes is an advanced control that developers can use to help tune performance in some scenarios; it is recommended to prefer using the Azure.Messaging.EventHubs.Primitives.EventProcessorOptions.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 Azure.Messaging.EventHubs.Primitives.EventProcessorOptions.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

ArgumentOutOfRangeException

Occurs when the requested size is negative.

TargetUnprocessedEventThreshold

Get or sets the target number of unprocessed events per worker for Event Hub-triggered functions. This is used in target-based scaling to override the default scaling threshold inferred from the MaxEventBatchSize option.

If TargetUnprocessedEventThreshold is set, the total unprocessed event count will be divided by this value to determine the number of worker instances, which will then be rounded up to a worker instance count that creates a balanced partition distribution.

public int? TargetUnprocessedEventThreshold { get; set; }

Property Value

int?

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.

public bool TrackLastEnqueuedEventProperties { get; set; }

Property Value

bool

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.

TransportType

The type of protocol and transport that will be used for communicating with the Event Hubs service.

public EventHubsTransportType TransportType { get; set; }

Property Value

EventHubsTransportType

WebProxy

The proxy to use for communication over web sockets.

public IWebProxy WebProxy { get; set; }

Property Value

IWebProxy

Remarks

A proxy cannot be used for communication over TCP; if web sockets are not in use, specifying a proxy is an invalid option.