Table of Contents

Silverback 5 Release Notes

5.9.0

Released on 2026-11-15

What's New

Fixes

  • Take the serializer options into account when comparing JsonMessageSerializer and JsonMessageDeserializer<TMessage> instances
  • Take the serializer settings into account when comparing NewtonsoftJsonMessageSerializer and NewtonsoftJsonMessageDeserializer<TMessage> instances
  • Stabilize the consumption with AllowStreaming, especially the error handling and the shutdown (see Streaming)
  • Prevent the consumer from stalling when one of several subscribers stops enumerating a stream
  • Prevent the consumer from stalling when one of several batch or stream subscribers is canceled
  • Stabilize the batch processing, which could lose messages, process them twice or commit them unprocessed when a batch failed or was retried, or the consumer stopped
  • Prevent the consumer from stalling when a batch subscriber stops enumerating while the batch is completed by its max wait time
  • Prevent a batch completed by its max wait time from committing a message that no subscriber received (e.g. because they canceled the enumeration)
  • Prevent a message from being processed twice when a batch with multiple subscribers is completed by its max wait time
  • Prevent a batch or stream subscriber from receiving a null message, or from seeing a normal end, when the consumer stops or the batch or stream fails
  • Prevent the thread pool starvation, which could stall the consumer (e.g. exceeding the Kafka max.poll.interval.ms), when many batches or streams are consumed at once by subscribers enumerating them synchronously (IEnumerable<T>, IMessageStreamEnumerable<T>) or subscribing to an IObservable<T> (see Subscribing to Batches)
  • Complete the batches when their max wait time elapses and discard the incomplete chunked messages when their timeout elapses, instead of up to a second later
  • Allow multiple endpoints in a Kafka consumer processing all partitions together (see Parallelism)
  • Fix the Kafka consumer not leaving the group when disconnecting with the cooperative sticky partition assignment strategy and auto-commit, which delayed the reassignment of its partitions until the session timeout
  • Prevent a static Kafka consumer (group.instance.id) from leaving the group, and triggering a rebalance, when disconnecting
  • Redeliver the unacknowledged QoS 1 and 2 messages when a mocked MQTT persistent session is resumed
  • Keep the MQTT consumer reconnecting when a QoS 2 acknowledgment fails because of a lost connection
  • Prevent the broker from dropping a message of a shared subscription routed to an MQTT client while it disconnects (observed with EMQX, see Shared Subscriptions)
  • Fix publishing a collection of messages hanging when the producer endpoint's filter skips one of them
  • Fix publishing a collection of chunked messages, which could complete before all chunks were produced, silently skip some of the messages or miss some errors
  • Invoke the callbacks passed to IProducer.Produce once per message, also when the message is filtered out or split into chunks
  • Prevent the code following the publishing of a collection of messages from running on the broker client's thread, which could stall or deadlock the producer
  • Throw instead of hanging when publishing a batch of messages to the outbox fails or is canceled
  • Prevent the outbox worker from producing messages twice when a stored message targets an unknown endpoint
  • Apply the outbox worker retry delay to every failure to produce the stored messages, instead of retrying some of them in a tight loop (see Retries and Message Order)
  • Fix the outbox worker stopping for good after many consecutive failures, when an exponential retry delay with a maximum delay is configured
  • Delay the first retry of the retry error policy and of the outbox worker by the initial delay, as documented

Breaking Changes

  • The batch max wait time is measured from the first message of the batch, as documented, instead of restarting with each message: this is a fix, but review the max wait time if you tuned it around the previous behavior (see Batch Processing Consumed Messages)
  • IInboundEnvelope<TMessage> redeclares IsTombstone for the nullable analysis: the actual envelopes are not affected, but the custom implementations, usually test doubles, must implement it and the substitutes (e.g. NSubstitute or Moq) must configure the property through IInboundEnvelope<TMessage>, since configuring it through IInboundEnvelope or IBrokerEnvelope doesn't apply to it
  • IOutboundMessageFilter is now asynchronous (ShouldProduceAsync replaces ShouldProduce): this doesn't affect the producer endpoint Filter predicates, since the endpoint builder didn't accept a custom implementation until now
  • HandleMessageAsync of Consumer<TIdentifier> returns a ValueTask<ConsumerPipelineContext> instead of a ValueTask (relevant only for custom broker integrations)

5.8.0

Released on 2026-11-08

What's New

  • Improve the parallel invocation of the subscribers and the broker clients
  • Reduce logger allocations, especially for disabled logs
  • Get a Kafka admin client for a configured producer, consumer or endpoint through the IConfluentAdminClientFactory (see Kafka Admin Client) [#139]
  • Subscribe the Kafka consumer endpoints to the topics matching a regular expression (see Kafka Subscription and Partition Assignment)
  • Support topic creation and full metadata in the mocked Kafka admin client

Fixes

  • Apply the error policies when the consumer commit fails
  • Disconnect the broker client when an Initialized event handler fails
  • Fix message routing when a message is published before the broker clients are initialized [#280]
  • Prevent the Kafka consumer commit from failing during the client initialization
  • Prevent the Kafka consumer shutdown from failing or hanging during a partition assignment
  • Consume the partitions assigned to a Kafka consumer while it's stopping, once it's restarted
  • Skip the Silverback log when a Kafka log or error callback returns true
  • Prevent a fatal error when a message is retried while using the Kafka client side offset store
  • Fix the first produce failing when a Kafka transactional producer endpoint has a friendly name
  • Revoke the partitions of a mocked Kafka consumer leaving the group
  • Wait for all the topics of the Kafka endpoints with multiple topics or a static partition in WaitUntilAllMessagesAreConsumedAsync and WaitUntilAllMessagesAreCommittedAsync
  • Prevent MQTT consumers from hanging when an error policy handles a failed QoS 2 acknowledgement
  • Apply the configured timeout to the MQTT connection attempts [#278]
  • Keep the configured name for the Kafka and MQTT producers with a single endpoint, instead of appending an index
  • Report the MQTT consumer as connected only after its topics are subscribed
  • Route the parent level of an MQTT multi-level wildcard filter (a for a/#) and stop routing the $ topics to the filters starting with a wildcard
  • Validate the MQTT topic filters and shared subscriptions, and reject the same topic subscribed more than once through shared subscriptions
  • Log an error when the MQTT broker rejects a subscription, and don't report the consumer as connected if all its topics are rejected
  • Distribute the messages of the mocked MQTT shared subscriptions round-robin among the connected clients, with a copy per shared subscription, and fix their unsubscribe
  • Prevent the mocked MQTT broker from failing when publishing while a client connects or disconnects
  • Wait for the topics matched by the MQTT consumer endpoint filters in WaitUntilAllMessagesAreConsumedAsync
  • Prevent the mocked MQTT pending messages count from getting stuck when a message is handled before being counted
  • Fix the event name of IntegrationLogEvents.EndpointBuilderError

5.7.1

Released on 2026-11-05

Fixes

  • Recreate the Kafka producer after a fatal error, the DisposeOnException setting is now obsolete and ignored

5.7.0

Released on 2026-11-02

What's New

  • Configure the Avro, JSON and Protobuf schema registry serializers and deserializers through dedicated builders (e.g. KafkaJsonSerializerConfigurationBuilder), consistently with the other Kafka settings; the Configure overloads taking the Confluent configuration are now obsolete
  • Add EnableSaslOauthbearerAssertionClaimJti and DisableSaslOauthbearerAssertionClaimJti to the Kafka client configuration builders, consistently with the other boolean settings
  • Execute custom code when an error policy is about to be applied (see Error Handling Policies)

Fixes

  • Mark the parent of the consume activity as remote when the trace context is restored from the message headers [#267]
  • Start the produce activity when the outbox worker produces the stored messages, continuing the trace stored in the message headers
  • Set the message id, partition and Kafka key tags on the produce activity
  • Rethrow the original exception instead of wrapping it into a TargetInvocationException when a synchronous subscriber throws [#177]
  • Prevent the asynchronous broker client callbacks from failing when a scoped callback or one of its dependencies only implements IAsyncDisposable
  • Prevent a deadlock when a sequence (e.g. a batch) is aborted while it is being completed or disposed
  • Prevent adding to, completing or aborting a sequence (e.g. a batch) from hanging when it is disposed concurrently
  • Commit the last processed message and keep consuming when a batch subscriber stops enumerating before the end of the batch
  • Prevent a batch from hanging when its timeout elapses while the subscriber stops enumerating
  • Prevent the consumer from looping endlessly when a chunked message in a batch isn't fully read
  • Prevent the consumer stop from failing or completing too early when a new sequence (e.g. a batch) starts while stopping
  • Prevent the consumer from processing one more buffered message while stopping or disconnecting
  • Roll back instead of applying the error policies when the consumer stop cancels the processing (see Error Handling Policies)
  • Prevent the consumer StopAsync from hanging when the processing it waits for stops or reconnects the consumer (e.g. through the error policies)
  • Prevent a reconnect (e.g. the Kafka auto recovery) from restarting a consumer that is stopped or being stopped
  • Prevent the broker clients from connecting or disconnecting twice when concurrent calls overlap (e.g. the shutdown racing a reconnect)
  • Prevent Kafka consumers from skipping the messages already fetched but not yet processed when stopped and restarted
  • Prevent a Kafka partition from staying paused when the consumer is stopped and restarted, or the partition is revoked and assigned again, while rolling it back
  • Keep consuming when a Kafka consumer is restarted right after a non-blocking stop
  • Prevent a Kafka partition assignment or rollback racing the consumer stop from treating the stopped consumer as still started
  • Prevent a possible native crash when offsets are stored or committed while the Kafka consumer is being disconnected
  • Prevent MQTT consumers from leaving the message being read or retried unprocessed when stopped and restarted
  • Prevent MQTT consumers from resuming consuming when stopped again before a pending restart is completed
  • Report the MQTT consumer as connected again (instead of stopped) when it is restarted while the client is still connected
  • Prevent a misleading MQTT connection error warning from being logged when the client is disconnected during a connection attempt
  • Allow tombstone messages (null body) to be stored in the Sqlite, PostgreSQL and Entity Framework outbox
  • Prevent the in-memory Kafka topic GetAllMessages and the in-memory MQTT broker GetMessages from failing when messages are produced concurrently
  • Prevent an exception in a partitions revoked callback from interrupting the rebalance of the other consumers in the mocked Kafka
Important

The [Required] attribute has been removed from Content. When using the Entity Framework outbox, add a migration to drop the NOT NULL constraint from the Content column, otherwise storing a tombstone will still fail.

5.6.0

Released on 2026-10-29

What's New

  • Allow WaitUntilAllMessagesAreConsumedAsync to wait for Kafka message processing independently of broker offset commits
  • Add WaitUntilAllMessagesAreCommittedAsync to the Kafka testing helper to explicitly wait for broker offset commits
  • Upgrade to Confluent.Kafka 2.16.0

Fixes

  • Prevent ObjectDisposedException in IBrokerClientsConnector when application shutdown calls overlap
  • Fix a race condition that could cause Kafka consumers to stall and exceed the maximum poll interval after a rebalance
  • Fix race conditions that could cause message loss or interrupt consumption when a Kafka rebalance or reconnect overlaps with rollback or batch completion
  • Prevent Kafka consumers processing partitions together from stalling or skipping messages after a partial cooperative rebalance
  • Prevent out-of-order processing and message loss when Kafka consumers stop with full message buffers
  • Prevent out-of-order processing and message loss when Kafka consumers retry messages while polling
  • Prevent Kafka consumers from polling concurrently and stalling when restarted before a non-blocking stop completes
  • Prevent Kafka consumers from stalling when restarted while a non-blocking stop is still processing the buffered messages
  • Log failed Kafka offset commits consistently
  • Prevent assignment errors and consumption waits failing or returning too early during mocked Kafka rebalances
  • Prevent a deadlock in the mocked Kafka when consumers disconnect during a rebalance
  • Honor the timeout and the throwTimeoutException argument in WaitUntilConnectedAsync of the ITestingHelper
  • Prevent MQTT consumers from stalling after reconnecting or hanging during disconnect with full message buffers
  • Fix uneven distribution of MQTT messages across parallel processing channels
  • Allow pending MQTT messages to finish publishing during shutdown and prevent publishing calls from hanging after disconnect
  • Prevent canceled MQTT publishing calls from stalling subsequent messages and application shutdown
  • Prevent MQTT publishing and application shutdown from hanging when a message is produced synchronously right after an asynchronous produce completes
  • Prevent MQTT consumers from stalling or stopping permanently after an unexpected connection loss
  • Respect the configured MQTT backpressure limit when buffering messages for processing
  • Preserve MQTT sessions across reconnects when persistence is requested without an explicit expiration
  • Apply shared MQTT client settings in the order they are configured
  • Prevent the DistributedBackgroundService from logging an error when the distributed lock acquisition is canceled during shutdown [#272]
  • Fix the event names of the lock related CoreLogEvents
  • Prevent the EntityFrameworkLock from causing duplicate key errors when multiple instances start at the same time and ensure the lock is acquired atomically regardless of the database provider [#272]
  • Allow the PostgreSqlTableLock to take over expired locks (e.g. left by a crashed instance), prevent duplicate key errors when multiple instances acquire it at the same time and detect when the lock is lost (requires a primary key or unique constraint on the LockName column, as created by CreatePostgreSqlLocksTableAsync)

5.5.2

Released on 2026-09-10

Fixes

5.5.1

Released on 2026-08-26

Fixes

5.5.0

Released on 2026-08-13

What's New

Fixes

  • Prevent lazy message stream pushes from hanging when the provider is completed or aborted before the stream is created

5.4.2

Released on 2026-08-04

Fixes

  • Correctly route tombstones and regular messages to their respective subscribers regardless of which message is consumed first

5.4.1

Released on 2026-07-29

Fixes

  • Prevent a race condition that could cause the BatchSequence constructor to throw an ObjectDisposedException

5.4.0

Released on 2026-07-28

What's New

Fixes

  • Optimize the shutdown process by stopping consumers in parallel
  • Correctly handle subscriber tasks completion
  • Resolve rebalance race condition in the mocked Kafka consumer

5.3.3

Released on 2026-06-01

Fixes

  • Ensure the batch sequences are completed before disconnecting (a further step in preventing the producer not connected exception during shutdown)

5.3.2

Released on 2026-06-01

Fixes

  • Prevent deadlock in the disconnect process

5.3.1

Released on 2026-05-25

Fixes

  • Prevent null messages (tombstones) from being forwarded to regular subscribers (subscribing the message type)
  • Postpone disconnect to the application stopped lifecycle event to prevent potential issues with the Kafka producer when the application is shutting down

5.3.0

Released on 2026-04-26

What's New

Fixes

  • Remove the chunk-message-id header, which was added by mistake in v5 and introduced an unintended break

5.2.2

Released on 2026-04-24

Fixes

  • Handle some potential race conditions in the batch completion and timeout handling

5.2.1

Released on 2026-03-25

Fixes

  • Fix a potential deadlock in the batch sequence completion

5.2.0

Released on 2026-03-23

What's New

Fixes

  • Ensure that the Kafka AdminClient is initialized with a clean configuration to prevent warnings from being logged
  • Fix a race condition potentially preventing the batch sequence from completing successfully when the timeout is reached

5.1.0

Released on 2026-03-04

What's New

Fixes

  • Correctly bind the error handler to the Kafka producer to prevent uncontrolled logging to stderr

5.0.0

Released on 2026-02-22

Silverback 5.0.0 is the most significant update in the library’s history, built on years of user feedback and real-world experience. This release is more than just an upgrade, it’s a complete refactoring that enhances flexibility, performance, and maintainability while laying a strong foundation for future innovations.

Highlights

  • An improved configuration API that makes it easier to set up Silverback exactly the way you want, with a more intuitive and consistent syntax. The new fluent API is designed to be more readable and straightforward and to give you more control over the Kafka and MQTT clients that are used under the hood.
services.AddSilverback()
    .WithConnectionToMessageBroker(options => options.AddKafka())
    .AddKafkaClients(clients => clients
        .WithBootstrapServers("PLAINTEXT://localhost:9092")
        .AddProducer(producer => producer
            .Produce<MyMessage>(endpoint => endpoint
                .ProduceTo("my-topic"))
            .Produce<MyMessage2>(endpoint => endpoint
                .ProduceTo("my-topic-2")))
        .AddConsumer(consumer => consumer
            .WithGroupId("consumer1")
            .AutoResetOffsetToEarliest()
            .Consume<MyMessage3>(endpoint => endpoint
                .ConsumeFrom("my-topic-3")
                .OnError(policy => policy.Retry(3).ThenSkip()))
            .Consume<MyMessage4>(endpoint => endpoint
                .ConsumeFrom("my-topic-4")
                .EnableBatchProcessing(100, TimeSpan.FromSeconds(5))
                .OnError(policy => policy.Skip()))));
  • The new WrapAndPublish and WrapAndPublishAsync methods allow you to enrich the message envelope with headers, Kafka keys, and other metadata before publishing it.
publisher.WrapAndPublish(
    new MyMessage { Content = "Hello, Silverback!" },
    envelope => envelope
        .AddHeader("custom-header", "custom-value")
        .SetKafkaKey("my-key"));
  • WrapAndPublishBatch and WrapAndPublishBatchAsync methods extend the WrapAndPublish functionality to support streaming, mapping, and efficient batching with Kafka.
await publisher.WrapAndPublishBatchAsync(
    entities,
    entity => new MyMessage { Id = entity.Id },
    envelope => envelope
        .AddHeader("custom-header", "custom-value")
        .SetKafkaKey("my-key"));
  • The message bus (IPublisher) has been improved on many levels
    • is now registered as transient instead of scoped, allowing you to inject it into singleton services
    • IEventPublisher, ICommandPublisher, and IQueryPublisher have been replaced by extension methods on IPublisher, so you don't need multiple dependencies anymore
    • supports CancellationToken
    • supports ValueTask return types
    • more performance and reduced allocations
  • Many new features to leverage the power of Kafka and MQTT
    • Kafka transactions
    • Confluent schema registry support
    • Kafka consumer cooperative sticky partition assignment strategy
    • MQTT 5 request-response
  • Redesigned and improved storage packages
    • native support for PostgreSQL and SQLite (more to come in the future), as well as Entity Framework
    • rethought and rewritten outbox
    • client-side offset storage for Kafka

In the following sections, you'll find a more detailed and canonical list of improvements, new features, and breaking changes.

What's New

Breaking Changes

This release includes many breaking changes, as the library underwent a significant refactoring. The following list might be incomplete but should give you an overview of the most important changes:

  • Refactored the configuration model and related fluent API, refer to the updated Guides and Samples to see what it looks like in the new version
    • Many types, properties, and methods have been renamed or modified to improve readability, consistency, and ergonomics
    • Reorganized the configuration namespaces, some extension methods might have been moved to a different namespace, thus requiring a different using.
    • Changed the endpoint models and most of the configuration models to records with init-only properties
    • Building the endpoints directly is still supported, but the strongly recommended preferred way is to use the fluent API; therefore, from now on the documentation will only show that approach
    • Removed all builders interfaces and exposed the actual classes directly (e.g. ISilverbackBuilder to SilverbackBuilder)
    • AddOutbound/AddInbound methods have been replaced by AddKafkaClients/AddMqttClients and Produce/Consume methods
    • Configure method for Kafka clients replaced by configuration methods such as WithBootstrapServers, WithGroupId, WithClientId, etc.
    • IBrokerCallback and Add*BrokerCallbackHandler methods renamed to IBrokerClientCallback and Add*BrokerClientCallback
    • ... (many more changes)
  • Split the IMessageSerializer interface into IMessageSerializer and IMessageDeserializer
  • Outbox and all storage-dependent features have been rewritten from scratch, look at the Guides for more details about the new implementation
    • Important: the new Entity Framework based outbox works slightly differently than the previous one, and you might need to explicitly begin a transaction
  • Exactly once guard has been replaced by the client side offset storage (see Kafka Offset Storage)
  • Replaced IEventPublisher, ICommandPublisher, and IQueryPublisher with equivalent extension methods on IPublisher (see Using the Message Bus)
    • Consequently removed the UseModel configuration method
  • Removed the whole IBroker and IBrokerCollection constructs
    • They are superseded by the IProducerCollection and IConsumerCollection interfaces, as well as the IBrokerClientCollection which grants access to all underlying broker clients
  • Changed some details in IProducer/IConsumer and their implementations
  • A lot of methods have been changed to return a ValueTask instead of a Task
  • Kafka key won't be set to a random Guid anymore but will be null if not explicitly set
  • Some changes to the default settings:
  • Several changes have been made to ITestingHelper, IKafkaTestingHelper, and IMqttTestingHelper
  • Removed the AddSubscribers methods allowing to register subscribers via a base type or interface
  • ... (many more changes)

Migration Guide

Tip

A step-by-step migration guide with before/after examples is available in Migrating from v4 to v5.

The migration from Silverback 4.x.x to 5.x.x is a significant step and requires some effort. The following list is not exhaustive and might not cover all the breaking changes but should give you a good idea of the basic steps:

  • Ensure your application targets .NET 10 as starting with v5 Silverback only supports the latest LTS release
  • Upgrade all Silverback.* NuGet packages to 5.x.x
  • Some namespace usings will need to be adjusted (e.g.,Silverback.Messaging.Configuration → Silverback.Configuration)
  • Migrate the endpoints configuration to the new broker clients configuration (an example of the new fluent API can be found in the Highlights section above)
  • Replace usage of IEventPublisher, ICommandPublisher, and IQueryPublisher with the related extension methods on the basic IPublisher or the consolidated IApplicationPublisher (introduced in v5.1.0) if you prefer a more testable approach (see also Using the Message Bus)
  • If using the outbox, adjust the DbContext / database schema and review transaction handling: you might need to explicitly begin a transaction and enlist it in the publisher to keep application changes and outbox messages atomic (see also Transactional Outbox)

Deprecation Notice

The support for RabbitMQ has been dropped in this release and the Silverback.Integration.RabbitMQ package has been deprecated. See Deprecation notice: packages to be deprecated in Silverback v5.