Azure.Messaging.EventHubs

Bugs Fixed

• Fixed a bug which caused the placeholder value used to represent missing offsets in v5.11.3 - v5.11.6 to not be properly detected and incorrectly used as a valid offset when reading from a partition.

Acknowledgments

Thank you to our developer community members who helped to make the Event Hubs client libraries better with their contributions to this release:

• tovyhnal (GitHub)

Features Added

• Support for the Event Hubs geographic data replication feature has been enabled. Checking for whether or not this feature is enabled for your namespace can be done by querying for Event Hub properties using EventHubProducerClient or EventHubConsumerClient and referencing the the IsGeoReplicationEnabled property of the result.

  As part of this feature, the type of offset-related data has been changed from long to string to align with changes to the Event Hubs service API. To preserve backwards compatibility, the existing offset-related members have not been changed, and new members with names similar to OffsetString and string-based parameters for method overloads have been introduced.

  The long-based offset members will continue to work for Event Hubs namespaces that do not have GeoDR replication enabled, but are discouraged for use and have been marked as obsolete.

  Obsoleted properties:

  • EventData.Offset
  • LastEnqueuedEventProperties.Offset
  • PartitionProperties.LastEnqueuedOffset

  Obsoleted method overloads:

  • EventPosition.FromOffset
  • EventHubsModelFactory.EventData
  • BlobCheckpointStore.UpdateCheckpointAsync
  • EventProcessorClient.UpdateCheckpointAsync

Bugs Fixed

• Querying runtime data and other management operations will now correctly guards against the race condition where an AMQP link is in the process of closing as the operation attempts to use it. These errors will now properly be classified as retriable as they are for producer and consumer operations.

• Fixed an obscure edge case in the EventHubBufferedProducer client where an unlikely race condition when flushing/enqueuing events concurrently with disposing the producer could cause a semaphore to be released inappropriately. This error superseded the TaskCanceledException that should have been surfaced.

Other Changes

• Enhanced retry logic to consider additional cases for web socket-based failures. In many cases, a WebSocketException is triggered which wraps a SocketException with the details for the specific network conditions. Retry decisions are now based on the internal exception, if present, to ensure retries are correctly applied.

• Added annotations to make the package compatible with trimming and native AOT compilation.

• Added Event Hub name to processor load balancing logs for additional context. (A community contribution, courtesy of tovyhnal)

• Updated the Microsoft.Azure.Amqp dependency to 2.6.9, which contains several bug fixes. (see: commits)

Bugs Fixed

• Fixed an obscure edge case in the EventHubBufferedProducer client where an obscure race condition when flushing/enqueuing events concurrently with disposing the producer could cause a semaphore to be released inappropriately. This error superseded the TaskCanceledException that should have been surfaced.

Other Changes

• Bump Azure.Core.Amqp dependency to 1.3.1, which includes a fix to serialization of binary application properties.

Bugs Fixed

• Fixed an error that prevented relative URIs from being used with application properties in the EventData.Properties collection.

• Fixed an error with ETW logs which caused structured arguments for Id 105 (Event Processor position determined) to be out-of-order with the message format. This also caused the date to render incorrectly for some captures.

Other Changes

• The client will now refresh the maximum message size each time a new AMQP link is opened; this is necessary for large message support, where the maximum message size for entities can be reconfigured and adjusted on the fly. Because the client had cached the value, it would not be aware of the change and would enforce the wrong size for batch creation.

• The PluggableCheckpointStoreEventProcessor will now emit a diagnostic span when a checkpoint is created/updated. While this span is not defined by the Open Telemetry specification, this change aligns diagnostic spans with those emitted by EventProcessorClient.

• Adjusted the options used by EventProcessor<TPartition> and descendants during startup validation to reduce the amount of data transferred and minimize impact on the outgoing events metric.

Bugs Fixed

• Fixed an error that caused connection strings using host names without a scheme to fail parsing and be considered invalid.

Other Changes

• Removed the restriction that endpoints used with the development emulator had to resolve to a localhost variant.

• Updated the Microsoft.Azure.Amqp dependency to 2.6.7, which contains several bug fixes, including for an internal NullReferenceException that would sometimes impact creating new links. (see: #258)

Features Added

• It is now possible for processors extending EventProcessor<T> to disable the batch-level tracing emitted when processing events. This is intended to allow derived processors dispatching single events or partial batches to emit their own trace information that more accurately correlates to the set of events being processed. Previously all events in a batch were tracked under a single span regardless of how they were dispatched for processing.

Bugs Fixed

• Fixed a warning for "too many parameters" that was written to logs when the processor attempted to log load balancing messages due to improper ETW attribute use.

Other Changes

• It is now possible to set byte[] values as application properties in the EventData.Properties collection.

Other Changes

• Updated the Microsoft.Azure.Amqp dependency to 2.6.5, which includes several bug fixes. A notable fix addresses an obscure race condition when a cancellation token is signaled while service operations are being invoked concurrently which caused those operations to hang.

Features Added

• Added a CheckpointPosition struct to Azure.Messaging.EventHubs.Processor to use when updating a checkpoint. The specified position indicates that an event processor should begin reading from the next event. Added new UpdateCheckpointAsync overloads to CheckpointStore, PluggableCheckpointStoreEventProcessor<TPartition and EventProcessor<TPartition> that accept the CheckpointPosition struct instead of individual values for offset and sequence number.

Breaking Changes

• The type of several existing values in the EventData.SystemProperties collection have been changed so that they are properly represented as .NET string types. Previously, the underlying AMQP types were unintentionally returned, forcing callers to call ToString() to read the value.

  This is a behavioral breaking change that will impacts only those callers who were explicitly casting system property values to AmqpAddress or AmqpMessageId before calling ToString(). The affected system properties are:

  • MessageId
  • CorrelationId
  • To
  • ReplyTo

• The base implementations of both UpdateCheckpointAsync method overloads in PluggableCheckpointStoreEventProcessor<TPartition> and EventProcessor<TPartition> now choose sequence number over offset when writing a checkpoint and both values are provided. Previously, writing a checkpoint prioritized offset over sequence number. There is no behavioral change for those using the official checkpoint store implementations.

Bugs Fixed

• Load balancing is no longer blocked when event processing for a lost partition does not honor the cancellation token. Previously, long-running processing could cause delays in load balancing that resulted in ownership not being renewed for all partitions.

• Adjusted retries to consider an unreachable host address as terminal. Previously, all socket-based errors were considered transient and would be retried.

• Fixed a race condition that could lead to a synchronization primitive being double-released if IsRunning was called concurrently while starting or stopping an event processor.

• Fixed an issue with event processor validation where an exception for quota exceeded may inappropriately be surfaced when starting the processor.

• In the rare case that an event processor's load balancing and health monitoring task cannot recover from an error, it will now properly surrender ownership when processing stops.

• Reduced the timeout for transient service failures when starting the buffered producer. This fixed an issue where the buffered producer appeared to hang for an extended period of time when starting if it had issues querying Event Hub metadata for the first time.

• Fixed the logic used to set the TimeToLive value of the AmqpMessageHeader for received messages to be based on the difference of the AbsoluteExpiryTime and CreationTime properties of the AmqpMessageProperties.

Other Changes

• Updated the Microsoft.Azure.Amqp dependency to 2.6.4, which enables support for TLS 1.3.

• Removed the custom sizes for the AMQP sending and receiving buffers, allowing the optimized defaults of the host platform to be used. This offers non-trivial performance increase on Linux-based platforms and a minor improvement on macOS. Windows performance remains unchanged as the default and custom buffer sizes are equivalent.

• Improved efficiency of partition management during load balancing, reducing the number of operations performed and deferring waiting for lost partitions until the processor is stopped or the partition is reclaimed. Allocations were also non-trivially reduced.

• Improved the approach used by the processor to manage the background tasks for partition processing and load balancing. These tasks are now marked as long-running and have improved error recovery.

• Initialization of the load balancing task is now performed in the background and will no longer cause delays when starting the processor.

• Loosened validation for the fully qualified namespace name passed to client constructors. A URI is now also accepted as a valid format. This is intended to improve the experience when using the management library, CLI, Bicep, or ARM template to create the namespace, as they return only an endpoint for the namespace. Previously, callers were responsible for parsing the endpoint and extracting the host name for use with the clients.

• In the rare case that an event processor's load balancing and health monitoring task cannot recover from an error, the processor now signals the error handler with a wrapped exception that makes clear that processing will terminate. Previously, the source exception was surfaced to the error handler and the impact was not clear.

• The "Event Receive Completed" log now includes the maximum batch size and wait time that were used for the operation.

• A new log has been added to capture the end-to-end performance of the cycle to read and process events for a partition owned by an event processor type. This is emitted as a verbose ETW event with the Id 129 and is highly recommended to capture when troubleshooting processor scenarios.

Breaking Changes

• Change ActivitySource name used to report message activity from Azure.Messaging.EventHubs.EventHubs to Azure.Messaging.EventHubs.Message and message Activity name from EventHubs.Message to Message.
• Updated tracing attributes names to conform to OpenTelemetry semantic conventions version 1.23.0.

Bugs Fixed

• Fixed a parameter type mismatch in ETW #7 (ReceiveComplete) which caused the duration argument of the operation to be interpreted as a Unicode string and fail to render properly in the formatted message.

Other Changes

• When an Event Hub is disabled, it will now be detected and result in a terminal EventHubsException with its reason set to FailureReason.ResourceNotFound.

Bugs Fixed

• When using the EventHubBufferedProducerClient, events are now instrumented when EnqueueEventAsync or EnqueueEventsAsync is called, rather than when the event is published. This ensures that the instrumentation is accurate when the event is published, regardless of whether the event is published immediately or buffered for a period of time.

Other Changes

• Several improvements to logging have been made to capture additional context and fix typos. Most notable among them is the inclusion of starting and ending sequence numbers when events are read from Event Hubs and dispatched for processing by event processor types.

• The reference for the AMQP transport library, Microsoft.Azure.Amqp, has been bumped to 2.6.3. This fixes an issue with timeout duration calculations during link creation and includes several efficiency improvements.

Other Changes

• The reference for the AMQP transport library, Microsoft.Azure.Amqp, has been bumped to 2.6.2. This resolves a potential issue opening TLS connections on .NET 6+.

• It is now possible to create an EventData instance from an AmqpAnnotatedMessage.

Bugs Fixed

• Removed the 30 second cap applied when opening AMQP links; this allows developers to fully control the timeout for service operations by tuning the TryTimeout as appropriate for the application.

Breaking Changes

• If diagnostic tracing is enabled, diagnostic tracing information is retained on EventData instances when they are added to an EventDataBatch. This matches the existing behavior when sending events using the SendEventsAsync method that takes an IEnumerable<EventData>.

Bugs Fixed

• Changed the approach that the event processor uses to validate permissions on startup to ensure that it does not interrupt other processors already running by temporarily asserting ownership of a partition.

Other Changes

• Enhanced the log emitted when an event processor begins reading from a partition to report whether the offset chosen was based on a checkpoint or default value.

Other Changes

• Upgrading dependency on Azure.Core library.

Features Added

• ActivitySource activities that are used when using the experimental OpenTelemetry support will include the az.schema_url tag indicating the OpenTelemetry schema version. They will also include the messaging attribute specified here.

Bugs Fixed

• Corrected log message issue causing formatting to fail when developer code for processing events leaks an exception. This obscured the warning that was intended to be emitted to the error handler.

Other Changes

• Calling ToString on an EventHubsException now includes details of any inner exception.

Acknowledgments

Thank you to our developer community members who helped to make the Event Hubs client libraries better with their contributions to this release:

• Jason Gilbertson (GitHub)

Bugs Fixed

• Corrected an indexing issue with the log event source, causing an exception to surface when the buffered producer completed its idle state.

Bugs Fixed

• Telemetry will now use a parent activity instead of links when the event processor is configured to use a eventBatchMaximumCount of 1.

• The reference for the AMQP transport library, Microsoft.Azure.Amqp, has been bumped to 2.5.12. This resolves a rare race condition encountered when creating an AMQP link that could cause the link to hang.

Other Changes

• Adjusted the frequency that a warning logged when the processor owns more partitions than a basic heuristic believes is ideal. Warnings will no longer log on each load balancing cycle, only when the number of partitions owned changes.

• Added timing information to logs for AMQP publish and read operations.

Acknowledgments

Thank you to our developer community members who helped to make the Event Hubs client libraries better with their contributions to this release:

• Daniel Marbach (GitHub)
• Anshul Mathur (GitHub)

Other Changes

• Added additional heuristics for the EventProcessor<T> configuration to help discover issues that can impact processor performance and stability; these validations will produce warnings at processor start-up should potential concerns be found.

• Exception messages have been updated to include a link to the Event Hubs troubleshooting guide.

• Miscellaneous performance improvements by reducing memory allocations. (A community contribution, courtesy of danielmarbach)

Acknowledgments

Thank you to our developer community members who helped to make the Event Hubs client libraries better with their contributions to this release:

• Daniel Marbach (GitHub)

Bugs Fixed

• Fixed a regression with the EventHubProducerClient overloads of SendAsync which accept an enumerable of events. When specifying a partition key, it was ignored when sending. As a result, the Event Hub applied round-robin partition assignment, spreading events across partitions rather than grouping them in a single partition.

Other Changes

• Reduced memory allocations when converting messages into the underlying AMQP primitives. (A community contribution, courtesy of danielmarbach)

Acknowledgments

Thank you to our developer community members who helped to make the Event Hubs client libraries better with their contributions to this release:

• Chad Vidovcich (GitHub)

Features Added

• The event processor error handler will now raise warning when an unhandled exception propagated from the event processing handler causing partition processing to fault and restart.

Bugs Fixed

• Fixed an issue with the EventHubBufferedProducerClient where it was not properly identifying when buffers were empty and should enter an idle state; this caused the background task that manages publishing to spin and consume an unreasonable amount of resources.

• Fixed an issue with event processor startup validation where an invalid consumer group was not properly detected.

Other Changes

• Samples now each have a table of contents to help discover and navigate to the topics discussed for a scenario. (A community contribution, courtesy of chadvidovcich)

• Enhanced API documentation for the EventData properties collection, detailing the types supported by AMQP serialization.

Acknowledgments

Thank you to our developer community members who helped to make the Event Hubs client libraries better with their contributions to this release:

• Daniel Marbach (GitHub)

Features Added

• The EventHubBufferedProducerClient is being introduced, intended to allow for efficient publishing of events without having to explicitly manage batches in the application. More information can be found in its design document. (Thanks to danielmarbach for his contributions to the implementation)

• An additional base class for event processors, PluggableCheckpointStoreEventProcessor<T>, has been added to simplify creating customized event processors and integrate with concrete CheckpointStore implementations.

• An abstract CheckpointStore is now available for use with the PluggableCheckpointStoreEventProcessor<T> to simplify creating customized event processors and allow reusing existing checkpoint store implementations.

• Support for cancellation tokens has been improved for AMQP operations, enabling earlier detection of cancellation requests without needing to wait for the configured timeout to elapse.

• Added FullyQualifiedNamespace, EventHubName, and ConsumerGroup to the partition context associated with events read by the EventHubConsumerClient.

Other Changes

• Based on a new series of profiling and testing in real-world application scenarios, the default values for EventProcessor<T> load balancing have been updated to provide better performance and stability. The default load balancing interval was changed from 10 seconds to 30 seconds. The default ownership expiration interval was changed from 30 seconds to 2 minutes. The default load balancing strategy has been changed from balanced to greedy.

• Added additional heuristics for the EventProcessor<T> load balancing cycle to help discover issues that can impact processor performance and stability; these validations will produce warnings should potential concerns be found.

• EventProcessor<T> will now log a verbose message indicating what event position was chosen to read from when initializing a partition.

• Removed allocations from Event Source logging by introducing WriteEvent overloads to handle cases that would otherwise result in boxing to object[] via params array. (A community contribution, courtesy of danielmarbach)

• Removed LINQ from the AmqpMessageConverter in favor of direct looping. (Based on a community contribution, courtesy of danielmarbach)

• Changed the internal batch AsEnumerable<T> to AsList<T> in order to avoid casting costs and have Count available to right-size transform collections. (Based on a community contribution, courtesy of danielmarbach)

• Moved to using the two item overload when creating a linked token source to avoid allocating an unnecessary array. (Based on a community contribution, courtesy of danielmarbach)

• Attempts to retrieve AMQP objects will first try synchronously before calling GetOrCreateAsync, to avoid an asynchronous call unless necessary.

• Improved documentation for EventPosition to be more explicit about defaults for inclusivity.

• EventPosition now exposes its ToString method for code completion, making it more discoverable.

• Minor updates to the class hierarchy of EventData to improve integration with Azure Schema Registry.

• EventData now allows the EventBody to be set after construction and supports an empty constructor.

Bugs Fixed

• Dependencies have been updated to resolve an error when creating EventSource instances when used with Xamarin.

Acknowledgments

Thank you to our developer community members who helped to make the Event Hubs client libraries better with their contributions to this release:

• Andrey Shihov (GitHub)
• John Call (GitHub)

Bugs Fixed

• Fixed an issue with refreshing authorization where redundant requests were made to acquire AAD tokens that were due to expire. Refreshes will now coordinate to ensure a single AAD token acquisition.

• Fixed an issue with authorization refresh where attempts may have been made to authorize a faulted link. Links that fail to open are no longer be considered valid for authorization.

Features Added

• Each Event Hubs client type now offers an option to set an Identifier. The identifier is informational and is associated with the AMQP links used, allowing the service to provide additional context in error messages and the SDK logs to provide an additional point of correlation.

Other Changes

• Added the ability to adjust the connection idle timeout using the EventHubConnectionOptions available within the options for each client type.

Acknowledgments

Thank you to our developer community members who helped to make the Event Hubs client libraries better with their contributions to this release:

• Daniel Marbach (GitHub)

Changes

Features Added

• The EventData type offers a curated set of the information available for messages using the AMQP protocol. While this results in a simpler and more easily understood API surface for an event, it limits interoperability with other message brokers. To support heterogeneous environments or those with specialized needs, the full AMQP message is now available using the GetRawAmqpMessage method. (Based on a community prototype contribution, courtesy of danielmarbach)

• EventData now supports construction using a string to specify the event body; this will be represented as a set of UTF-8 encoded bytes for transport.

• EventData has been extended to include properties for applications to assign a MessageId, ContentType, and CorrelationId as well-known members rather than embedding them in the Properties dictionary. It is important to note that these properties are intended for application use and are not recognized by the Event Hubs service.

• When stopping, the EventProcessor<TPartition> will now attempt to force-close the connection to the Event Hubs service to abort in-process read operations blocked on their timeout. This should significantly help reduce the amount of time the processor takes to stop in many scenarios. (Based on a community prototype contribution, courtesy of danielmarbach)

• When the EventProcessor<TPartition> detects a partition being stolen outside of a load balancing cycle, it will immediately surrender ownership rather than waiting for a load balancing cycle to confirm the ownership change. This will help reduce event duplication from overlapping ownership of processors.

• The EventProcessor<TPartition> now exposes the ListPartitionIdsAsync method, allowing custom processors to control the set of partitions known to the processor. This can be used to reduce complexity when a custom processor is directly assigned a set of partitions to process rather than using load balancing to control ownership.

• The ConnectionOptions available when creating client types now support registering a callback delegate for participating in the validation of SSL certificates when connections are established. This delegate may override the built-in validation and allow or deny certificates based on application-specific logic.

• The ConnectionOptions available when creating client types now support setting a custom size for the send and receive buffers of the transport.

• Additional verbose logging has been added to allow monitoring of lower-level AMQP operations such as creating links, terminal exceptions that fault a link without an active operation, and when the service force-closes links.

Key Bugs Fixed

• The EventProcessor<TPartition> will now properly respect another another consumer stealing ownership of a partition when the service forcibly terminates the active link in the background. Previously, the client did not observe the error directly and attempted to recover the faulted link which reasserted ownership and caused the partition to "bounce" between owners until a load balancing cycle completed.

• The EventProcessor<TPartition> will now be less aggressive when considering whether or not to steal a partition, doing so only when it will correct an imbalance and preferring the status quo when the overall distribution would not change. This will help reduce event duplication due to partitions moving between owners.

• The EventHubConsumerClient and PartitionReceiver will now properly surface an exception when another another consumer stealing ownership of a partition when the service forcibly terminates the active link in the background. Previously, the client did not observe the error directly and did not make callers attempted to recover the faulted link which reasserted ownership and caused the partition to "bounce" between owners until a load balancing cycle completed.

• The retry policy used by clients will no longer overflow the TimeSpan maximum when using an Exponential strategy with a large number of retries and long delay set.

Changes

Features Added

• EventProcessor<TPartition> will now perform validation of core configuration and permissions at startup, in order to attempt to detect unrecoverable problems more deterministically. Validation is non-blocking and will not delay claiming of partitions. One important note is that validation should be considered point-in-time and best effort; it is not meant to replace monitoring of error handler activity.

• Partition initialization for EventProcessor<TPartition> has been moved to a background operation. This will allow partitions to be more efficiently managed and speed up ownership claims, especially when using the LoadBalancingStrategy.Greedy configuration or when the processor is recovering from some error conditions.

Key Bugs Fixed

• Dependencies have been updated to resolve security warnings for CVE-2021-26701. (The Event Hubs client library does not make use of the vulnerable components, directly or indirectly)

• Event Hubs client types will now consider some additional exception types as transient when they occur in the context of opening an AMQP connection or link; this allows the client to attempt recovery by discarding the faulted connection and attempting to create a new one.

• Event Hubs client types will now react more deterministically when a shared connection was closed while still in use. Previously, the exception surfaced varied based on internal state. Now, an EventHubsException with FailureReason.ClientClosed and an appropriate message will be thrown.

• EventProcessor<TPartition> will no longer inappropriately determine that it should attempt to steal partitions from itself or when the load is balanced but there is an uneven ownership distribution. Previously, stealing was attempted but no candidates were found, leading to log spam but no interruption in processing.

Acknowledgments

Thank you to our developer community members who helped to make the Event Hubs client libraries better with their contributions to this release:

• Daniel Marbach (GitHub)

Changes

Features Added

• The Event Hubs clients now support shared key and shared access signature authentication using the AzureNamedKeyCredential and AzureSasCredential types in addition to the connection string. Use of the credential allows the shared key or SAS to be updated without the need to create a new Event Hubs client.

• The Properties collection used by EventData is now lazily allocated, avoiding memory bloat when not used.

• The SystemProperties collection used by EventData will not use a shared empty set for events that have not been read from the Event Hubs service, reducing memory allocation.

• Multiple enhancements were made to the transport paths for publishing and reading events to reduce memory allocations and increase performance. (A community contribution, courtesy of danielmarbach)

Key Bugs Fixed

• The AMQP library used for transport has been updated, fixing several issues including a potential unobserved ObjectDisposedException that could cause the host process to crash. (see: release notes)

Changes

Key Bugs Fixed

• Fixed an issue where long-lived credentials (more than 49 days) were overflowing refresh timer limits and being rejected.

• Added detection and recovery for a race condition that occurred when the Event Hubs service closed a connection or link after the client had validated its state and was performing an operation; this will now be properly retried with a fresh connection/link.

• Extended retry scenarios to include generic I/O exceptions, as they are typically transient network failures.

• Extended retry scenarios to include authorization failures, as the Event Hubs services do not differentiate between authentication and authorization, callers cannot reason about whether an Unauthorized return from an operation indicates that the call will never succeed or may trigger a credential renewal that may allow success.

Changes

Features Added

• Connection strings can now be parsed into their key/value pairs using the EventHubsConnectionStringProperties class.

• The body of an event has been moved to the EventData.EventBody property and makes use of the new BinaryData type. To preserve backwards compatibility, the existing EventData.Body property has been preserved with the current semantics.

• It is now possible to specify a custom endpoint to use for establishing the connection to the Event Hubs service in the EventHubConnectionOptions used by each of the clients.

• Errors occurring in the Event Hubs service or active transport are now preserved in full and propagated as an inner exception; this will provide deeper context for diagnosing and troubleshooting exceptions.

• The EventHubsModelFactory has been introduced to provide a single point for creation of Event Hubs model types to assist with mocking and testing.

• Documentation used for auto-completion via Intellisense and other tools has been enhanced in many areas, addressing gaps and commonly asked questions.

Key Bugs Fixed

• Upgraded the Microsoft.Azure.Amqp library to resolve crashes occurring in .NET 5.

• The EventHubsException.ToString result will now properly follow the format of other .NET exception output.

• Signaling the cancellation token will no longer cause the SendAsync method of the EventHubProducerClient to ignore the result of the service operation if publishing has already completed.

• The calculation for authorization token expiration has been fixed, resulting in fewer token refreshes and network requests.

Acknowledgments

Thank you to our developer community members who helped to make the Event Hubs client libraries better with their contributions to this release:

• Daniel Marbach (GitHub)

Changes

Key Bugs Fixed

• The underlying AMQP library has been enhanced for more efficient resource usage; this will result in a noticeable reduction in memory use in common consuming scenarios. (A community contribution, courtesy of danielmarbach)

• All clients will now perform an eager validation of connection strings upon creation. Previously, validation was performed just before a service operation in some scenarios which made debugging difficult.

• An additional level of resilience was added to some corner case scenarios where establishing an AMQP link failed with what may be a transient issue.

• Fixed an issue where failure to create an AMQP link would lead to an AMQP session not being explicitly closed, causing connections to the Event Hubs service to remain open until a garbage collection pass was performed.

Features Added

• The EventProcessor<TPartition> now supports a configurable strategy for load balancing, allowing control over whether it claims ownership of partitions in a balanced manner (default) or more aggressively. The strategy may be set in the EventProcessorOptions when creating the processor. More details about strategies can be found in the associated documentation.

• The EventHubConsumerClient pipeline for reading events from a single partition was reworked to improve efficiency and make use of the new configuration options for PrefetchCount and CacheEventCount.

• The ReadEventOptions used with the EventHubConsumerClient now support setting a PrefetchCount and CacheEventCount for performance tuning. More details about each can be found in the associated documentation.

• Logging for the core send and receive operations against the Event Hubs service can now be correlated by an OperationId in the logs and detail the number of retries attempted for the operation.

• Connection strings for each of the clients now supports a SharedAccessSignature token, allowing a pre-generated SAS to be used for authorization.

Acknowledgments

Thank you to our developer community members who helped to make the Event Hubs client libraries better with their contributions to this release:

• Alberto De Natale (GitHub)
• Daniel Marbach (GitHub)

Changes

General availability of preview features

• The set of features from v5.1.0-preview.1 are now generally available. This includes the EventProcessor<TPartition> and PartitionReceiver types which focus on advanced application scenarios which require greater low-level control.

Publishing events

• A set of events may now be published without an explicit batch; a batched approach will be used when communicating with the Event Hubs service, with an implicit batch created on the sender's behalf.

Bug fixes and foundation

• The transport producers used for sending events to a specific partition are now managed by a pool with sliding expiration to enable more efficient resource use and cleanup. (A community contribution, courtesy of albertodenatale)

• Timing operations have been refactored to make use of a more efficient approach with fewer allocations. (A community contribution, courtesy of danielmarbach)

• Fixed a bug with EventDataBatch; it is now thread-safe.

• Minor enhancements to reduce allocations and improve efficiency

Acknowledgements

Thank you to our developer community members who helped to make the Event Hubs client libraries better with their contributions to this release:

• Alberto De Natale (GitHub)

Changes

General

• A migration guide is now available for those moving from the 4.x version of the Microsoft.Azure.EventHubs libraries to the 5.0.1 version under the Azure.Messaging.EventHubs namespace.

• A bug was fixed that would intermittently cause a failure that caused retries to abort, potentially preventing recovery from transient failures.

• Several minor performance and efficiency improvements have been implemented.

Organization and naming

• Namespaces have been reorganized to align types to their functional area, reducing the number of types in the root namespace and offering better context for where a type is used. Cross-functional types have been left in the root while specialized types were moved to the Producer, Consumer, or Processor namespaces.

• The hierarchy of custom exceptions has been flattened, with only the EventHubsException remaining. The well-known failure scenarios that had previously been represented as stand-alone types are now exposed by a new Reason property to allow for applying exception filtering and other logic where inspecting the text of an exception message wouldn't be ideal.

Code | Docs

Support: Active

Event Grid Namespaces

Azure.Messaging.EventGrid.Namespaces