Silverback 5 Release Notes
5.9.0
Released on 2026-11-15
What's New
- Add
UseJsonSerializerContextto the JSON serializer and deserializer builders to use a System.Text.Json source-generated context (see Serializing the Produced Messages and Deserializing the Consumed Messages) Configurein the System.Text.Json and Newtonsoft.Json serializer and deserializer builders now applies to the previously configured options instead of replacing them- Filter the produced messages with a custom, asynchronous IOutboundMessageFilter, optionally resolved via DI (see Producing Messages)
- Filter the consumed messages per endpoint with a predicate or an IInboundMessageFilter, optionally resolved via DI: the filtered messages are skipped and committed (see Filtering)
- Support batch processing with MQTT 5 (see Batch Processing Consumed Messages)
- Support chunking with MQTT 5 (see Producing Chunked Messages)
- Add
ITestingHelper.Outboxto inspect, clear, wait for and process the outbox in the tests (see Testing with the Outbox) - Store a batch of messages published to the outbox without blocking a thread
- Annotate
IInboundEnvelope<TMessage>.IsTombstonefor the nullable reference types analysis: theMessageis known to be notnullafter checking that the envelope isn't a tombstone (see Consuming Tombstone Messages)
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
nullmessage, 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 anIObservable<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.Produceonce 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
IsTombstonefor 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 throughIInboundEnvelope<TMessage>, since configuring it throughIInboundEnvelopeorIBrokerEnvelopedoesn't apply to it - IOutboundMessageFilter is now asynchronous (
ShouldProduceAsyncreplacesShouldProduce): this doesn't affect the producer endpointFilterpredicates, since the endpoint builder didn't accept a custom implementation until now HandleMessageAsyncof Consumer<TIdentifier> returns aValueTask<ConsumerPipelineContext>instead of aValueTask(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
Initializedevent 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
WaitUntilAllMessagesAreConsumedAsyncandWaitUntilAllMessagesAreCommittedAsync - 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 (
afora/#) 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
DisposeOnExceptionsetting 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
Configureoverloads taking the Confluent configuration are now obsolete - Add
EnableSaslOauthbearerAssertionClaimJtiandDisableSaslOauthbearerAssertionClaimJtito 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
TargetInvocationExceptionwhen 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
StopAsyncfrom 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
GetAllMessagesand the in-memory MQTT brokerGetMessagesfrom 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
WaitUntilAllMessagesAreConsumedAsyncto wait for Kafka message processing independently of broker offset commits - Add
WaitUntilAllMessagesAreCommittedAsyncto the Kafka testing helper to explicitly wait for broker offset commits - Upgrade to Confluent.Kafka 2.16.0
Fixes
- Prevent
ObjectDisposedExceptionin 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
throwTimeoutExceptionargument inWaitUntilConnectedAsyncof 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
LockNamecolumn, as created byCreatePostgreSqlLocksTableAsync)
5.5.2
Released on 2026-09-10
Fixes
- Make IBrokerClientsConnector idempotent and safe to call concurrently
5.5.1
Released on 2026-08-26
Fixes
- Restore the NewtonsoftJsonMessageDeserializer<TMessage> stream position after deserialization for backward compatibility
5.5.0
Released on 2026-08-13
What's New
- Reduce NewtonsoftJsonMessageSerializer and NewtonsoftJsonMessageDeserializer<TMessage> allocations
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
- Upgrade to Confluent.Kafka 2.15.0
- Upgrade to MQTTnet 5.2.0
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
- Upgrade to Confluent.Kafka 2.14.0
Fixes
- Remove the
chunk-message-idheader, 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
- Add
WithKafkaTopicandWithMqttTopicextension methods for the InboundEnvelopeBuilder<TMessage> (see Testing) - Add IIntegrationPublisher as an alternative to the
WrapAndPublishextension methods on IPublisher (see Producing Messages)
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
- Add IApplicationPublisher as an alternative to the extension methods on IPublisher (see Using the Message Bus)
- Upgrade to Confluent.Kafka 2.13.2
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
- Clean up code and increase tests coverage
- Reduce allocations and improve performance in many places (see Performance)
- Register IPublisher as transient instead of scoped to allow injecting it into singleton services
- Add
CancellationTokensupport to the message bus (see Using the Message Bus) - Improve builders for error policies
- Support subscribers returning
ValueTask - Support exponential delay in
RetryErrorPolicy - Add new
AddHeaderandSetKafkaKeyoverloads in the producer endpoint configuration builders for easier and more readable configuration - Introduce typed endpoints registration using
Consume<TMessage>andProduce<TMessage>methods (replacingAddInboundandAddOutbound), making the nested configuration more readable and type-safe (see Producing Messages and Consuming Messages) - Automatically set the typed deserializer according to the message type when using
Consume<TMessage>to configure the endpoint (see Deserializing the Consumed Messages) - Automatically set the typed BinaryMessageDeserializer<TModel> according to the message type when using
Consume<TMessage>to configure the endpoint (see Deserializing the Consumed Messages) - Add full fluent API for Kafka and MQTT configuration (see Producing Messages and Consuming Messages)
- Rewrite storage implementation from scratch and introduce new Silverback.Storage.PostgreSql, Silverback.Storage.Sqlite, Silverback.Storage.EntityFramework and Silverback.Storage.Memory packages (see Storage Integration)
- Refactor transactional outbox adding support for transaction enlistment (even if not using Entity Framework) and improving performance (see Transactional Outbox)
- Improve outbox worker reliability
- Add message filtering in producer configuration (see Producing Messages)
- Improve and simplify tombstone handling (see Producing Tombstone Messages and Consuming Tombstone Messages)
- Add
IInboundEnvelopeextensions to get broker specific metadata such asGetKafkaOffset(),GetKafkaTimestamp(),GetMqttResponseTopic()andGetMqttCorrelationData() - Add
IOutboundEnvelopeextensions to set broker specific metadata such asSetKafkaKey(),SetMqttResponseTopic()andSetMqttCorrelationData() - Add
WrapAndPublishandWrapAndPublishAsyncmethods to IPublisher to allow envelope enrichment (setting headers, kafka key, etc.) and dynamic routing (see Producing Messages) - Add
WrapAndPublishBatchandWrapAndPublishBatchAsyncmethods to IPublisher with the same capabilities ofWrapAndPublishandWrapAndPublishAsync, supporting streaming, mapping, and efficient batching with Kafka (see Producing Messages) - Refactor and improve EntityFrameworkDomainEventsPublisher<TDbContext>
- Improve
ITestingHelperto allow waiting for specific topics to be consumed (see Testing) - Add InboundEnvelopeBuilder<TMessage> and OutboundEnvelopeBuilder<TMessage> to testing packages to help creating test envelopes (see Testing)
- Support Kafka cooperative sticky partition assignment strategy
- Implement transactional client-side offset storage (see Kafka Offset Storage)
- Support Kafka transactions (see Kafka Transactions)
- Add support for Confluent schema registry (Avro, Json, and Protobuf), including mock for in-memory testing
- Add
IgnoreNoMatchingSubscriberssetting to MQTT producer endpoints, to prevent throwing when no subscriber is consuming the produced message - Basic support for MQTT 5 request-response
- Add ConsumerNameFilterAttribute to filter the subscribers by consumer name (replaces KafkaGroupIdFilterAttribute and MqttClientIdFilterAttribute)
- Add new built-in (de-)serializers to support raw
string,Streamandbyte[](see Serializing the Produced Messages and Deserializing the Consumed Messages) - Improve Activity handling for sequences (batch processing, chunking, etc.)
- Upgrade to Confluent.Kafka 2.13.1
- Upgrade to MQTTnet 5.1.0
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.
ISilverbackBuildertoSilverbackBuilder) AddOutbound/AddInboundmethods have been replaced byAddKafkaClients/AddMqttClientsandProduce/ConsumemethodsConfiguremethod for Kafka clients replaced by configuration methods such asWithBootstrapServers,WithGroupId,WithClientId, etc.IBrokerCallbackandAdd*BrokerCallbackHandlermethods renamed toIBrokerClientCallbackandAdd*BrokerClientCallback- ... (many more changes)
- Split the
IMessageSerializerinterface 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, andIQueryPublisherwith equivalent extension methods on IPublisher (see Using the Message Bus)- Consequently removed the
UseModelconfiguration method
- Consequently removed the
- Removed the whole
IBrokerandIBrokerCollectionconstructs- They are superseded by the
IProducerCollectionandIConsumerCollectioninterfaces, as well as theIBrokerClientCollectionwhich grants access to all underlying broker clients
- They are superseded by the
- Changed some details in IProducer/IConsumer and their implementations
- A lot of methods have been changed to return a
ValueTaskinstead of aTask - Kafka key won't be set to a random
Guidanymore but will benullif not explicitly set - Some changes to the default settings:
- Increased default KafkaConsumerConfiguration.MaxDegreeOfParallelism to 100
- Increased default KafkaConsumerConfiguration.BackpressureLimit to 50
- The JSON deserializers don't use the
x-message-typeheader anymore by default, meaning that you have to explicitly activate the feature to deserialize polymorphic messages (see Deserializing the Consumed Messages) - Changed default NewtonsoftJsonMessageSerializer and NewtonsoftJsonMessageDeserializer<TMessage> typename handling to
TypeNameHandling.None, meaning that you need to explicitly set the type name handling strategy if you want to support polymorphic nested properties - Reverted default and null value handling in NewtonsoftJsonMessageSerializer to Newtonsoft.Json's default
- By default, the
MqttProducerwill not throw an exception anymore if no subscriber is consuming the produced message (can be configured to log a warning, or throw an exception)
- Several changes have been made to ITestingHelper, IKafkaTestingHelper, and IMqttTestingHelper
- Removed the
AddSubscribersmethods 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, andIQueryPublisherwith 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.