From 3d4822975d2292fe1ee8288e0faee911c18041ec Mon Sep 17 00:00:00 2001 From: Warwick Schroeder Date: Mon, 6 Oct 2025 11:33:35 +0800 Subject: [PATCH 1/6] Add details for cosmosdb optin flag EnableContainerFromMessageExtractor --- persistence/cosmosdb/defaultcontainer.include.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/persistence/cosmosdb/defaultcontainer.include.md b/persistence/cosmosdb/defaultcontainer.include.md index 94b8b1c2889..342c6cf2916 100644 --- a/persistence/cosmosdb/defaultcontainer.include.md +++ b/persistence/cosmosdb/defaultcontainer.include.md @@ -3,6 +3,13 @@ The container that is used by default for all incoming messages is specified via snippet: CosmosDBDefaultContainer #if-version [3, ) +**Added in version 3.2.1:** An opt-in flag `EnableContainerFromMessageExtractor` has been introduced to enable the below behavior added in `v3.2.0` in a non-breaking way, particularily if a default container and a message container extractor is used. If this flag is not used, the default behavior will be that the message container extractor will not overwrite the default container. This flag will become redundant in `v4.0.0` resulting in the correct default behavior introduced in `v3.2.0`, and be removed in `v5.0.0`. + +```csharp +config.UsePersistence() + .EnableContainerFromMessageExtractor(); +``` + **Added in version 3.2.0:** If the container information is being extracted during runtime from a message instance (header or message body), the default container specified will be overwritten by the last extractor in the pipeline. For example, if a [Header Extractor](/persistence/cosmosdb/transactions.md#specifying-the-container-to-use-for-the-transaction-using-message-header-values) (physical stage) and a [Message Extractor](/persistence/cosmosdb/transactions.md#specifying-the-container-to-use-for-the-transaction-using-the-message-contents) (logical stage) are both configured, then the container information within the Message Extractor would be used. > [!NOTE] From f2482622de229445cf0e9357030305af9e9c50ef Mon Sep 17 00:00:00 2001 From: Warwick Schroeder Date: Mon, 6 Oct 2025 11:54:42 +0800 Subject: [PATCH 2/6] Update wording. --- persistence/cosmosdb/defaultcontainer.include.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/persistence/cosmosdb/defaultcontainer.include.md b/persistence/cosmosdb/defaultcontainer.include.md index 342c6cf2916..166d8d7a95f 100644 --- a/persistence/cosmosdb/defaultcontainer.include.md +++ b/persistence/cosmosdb/defaultcontainer.include.md @@ -3,17 +3,17 @@ The container that is used by default for all incoming messages is specified via snippet: CosmosDBDefaultContainer #if-version [3, ) -**Added in version 3.2.1:** An opt-in flag `EnableContainerFromMessageExtractor` has been introduced to enable the below behavior added in `v3.2.0` in a non-breaking way, particularily if a default container and a message container extractor is used. If this flag is not used, the default behavior will be that the message container extractor will not overwrite the default container. This flag will become redundant in `v4.0.0` resulting in the correct default behavior introduced in `v3.2.0`, and be removed in `v5.0.0`. +**Added in version 3.2.1:** By default, message container extractors cannot override the configured default container. To allow extractors to override the default container, enable the `EnableContainerFromMessageExtractor` flag: ```csharp config.UsePersistence() .EnableContainerFromMessageExtractor(); ``` -**Added in version 3.2.0:** If the container information is being extracted during runtime from a message instance (header or message body), the default container specified will be overwritten by the last extractor in the pipeline. For example, if a [Header Extractor](/persistence/cosmosdb/transactions.md#specifying-the-container-to-use-for-the-transaction-using-message-header-values) (physical stage) and a [Message Extractor](/persistence/cosmosdb/transactions.md#specifying-the-container-to-use-for-the-transaction-using-the-message-contents) (logical stage) are both configured, then the container information within the Message Extractor would be used. +When this flag is enabled and multiple extractors are configured, the last extractor in the pipeline determines the final container. For example, if both a [Header Extractor](/persistence/cosmosdb/transactions.md#specifying-the-container-to-use-for-the-transaction-using-message-header-values) (physical stage) and a [Message Extractor](/persistence/cosmosdb/transactions.md#specifying-the-container-to-use-for-the-transaction-using-the-message-contents) (logical stage) are configured, the Message Extractor takes precedence. > [!NOTE] -> **Added in version 3.2.0:** The exception to the above is if the extractor fails to pull container information from the message (logical), then the container information in the header (physical) will be used. If this also fails, the configured default container will be used as a fallback. If there is no default container configured, an exception will be thrown. +> **Added in version 3.2.1:** If an extractor fails to retrieve container information, the system falls back to the next available source in this order: Message Extractor → Header Extractor → configured default container. If no default container is configured and all extractors fail, an exception is thrown. #end-if When installers are enabled, this (default) container will be created if it doesn't exist. To opt-out of creating the default container, either disable the installers or use `DisableContainerCreation()`: From fe2d1830eff832fcb35fe916b71258a145b2cab7 Mon Sep 17 00:00:00 2001 From: Warwick Schroeder Date: Tue, 7 Oct 2025 13:00:30 +0800 Subject: [PATCH 3/6] Update version numbers for cosmos 3.2.1 --- persistence/cosmosdb/defaultcontainer.include.md | 8 +++++++- .../index_outboxstorageformat_CosmosDB_[3,3].partial.md | 2 +- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/persistence/cosmosdb/defaultcontainer.include.md b/persistence/cosmosdb/defaultcontainer.include.md index 166d8d7a95f..51d9665b402 100644 --- a/persistence/cosmosdb/defaultcontainer.include.md +++ b/persistence/cosmosdb/defaultcontainer.include.md @@ -3,6 +3,9 @@ The container that is used by default for all incoming messages is specified via snippet: CosmosDBDefaultContainer #if-version [3, ) + +--- + **Added in version 3.2.1:** By default, message container extractors cannot override the configured default container. To allow extractors to override the default container, enable the `EnableContainerFromMessageExtractor` flag: ```csharp @@ -13,7 +16,10 @@ config.UsePersistence() When this flag is enabled and multiple extractors are configured, the last extractor in the pipeline determines the final container. For example, if both a [Header Extractor](/persistence/cosmosdb/transactions.md#specifying-the-container-to-use-for-the-transaction-using-message-header-values) (physical stage) and a [Message Extractor](/persistence/cosmosdb/transactions.md#specifying-the-container-to-use-for-the-transaction-using-the-message-contents) (logical stage) are configured, the Message Extractor takes precedence. > [!NOTE] -> **Added in version 3.2.1:** If an extractor fails to retrieve container information, the system falls back to the next available source in this order: Message Extractor → Header Extractor → configured default container. If no default container is configured and all extractors fail, an exception is thrown. +> If an extractor fails to retrieve container information, the system falls back to the next available source in this order: Message Extractor → Header Extractor → configured default container. If no default container is configured and all extractors fail, an exception is thrown. + +--- + #end-if When installers are enabled, this (default) container will be created if it doesn't exist. To opt-out of creating the default container, either disable the installers or use `DisableContainerCreation()`: diff --git a/persistence/cosmosdb/index_outboxstorageformat_CosmosDB_[3,3].partial.md b/persistence/cosmosdb/index_outboxstorageformat_CosmosDB_[3,3].partial.md index 488666c9f34..27334946db6 100644 --- a/persistence/cosmosdb/index_outboxstorageformat_CosmosDB_[3,3].partial.md +++ b/persistence/cosmosdb/index_outboxstorageformat_CosmosDB_[3,3].partial.md @@ -1,4 +1,4 @@ -#### Version 3.2 and up +#### Version 3.2.1 and up A default [synthetic partition key](https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/synthetic-partition-keys) will be used for all incoming messages, in the format `{endpointName}-{messageId}`, if not explicitly [overwritten](/persistence/cosmosdb/transactions.md#specifying-the-partitionkey-to-use-for-the-transaction) at runtime. From 7df0588c4e0eb401bfc301dbffdf2220dc1ccd86 Mon Sep 17 00:00:00 2001 From: Warwick Schroeder Date: Tue, 7 Oct 2025 13:48:11 +0800 Subject: [PATCH 4/6] remove the cosmos 3.1 to 3.2 upgrade guide menu item --- menu/menu.yaml | 2 -- 1 file changed, 2 deletions(-) diff --git a/menu/menu.yaml b/menu/menu.yaml index 41a5069b7d5..d80892a50cc 100644 --- a/menu/menu.yaml +++ b/menu/menu.yaml @@ -1141,8 +1141,6 @@ Articles: - Url: persistence/upgrades/cosmosdb-1to2 Title: Version 1 to 2 - - Url: persistence/upgrades/cosmosdb-3.1to3.2 - Title: Version 3.1 to 3.2 - Title: DynamoDB Articles: - Url: persistence/upgrades/dynamodb-2to3 From 3c0b5d0ce412d297220a3957e3f133d212d7486d Mon Sep 17 00:00:00 2001 From: Warwick Schroeder Date: Mon, 13 Oct 2025 09:49:59 +0800 Subject: [PATCH 5/6] Add upgrade warning for Default Container migration --- persistence/cosmosdb/defaultcontainer.include.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/persistence/cosmosdb/defaultcontainer.include.md b/persistence/cosmosdb/defaultcontainer.include.md index 51d9665b402..3e5122cf3c6 100644 --- a/persistence/cosmosdb/defaultcontainer.include.md +++ b/persistence/cosmosdb/defaultcontainer.include.md @@ -18,6 +18,8 @@ When this flag is enabled and multiple extractors are configured, the last extra > [!NOTE] > If an extractor fails to retrieve container information, the system falls back to the next available source in this order: Message Extractor → Header Extractor → configured default container. If no default container is configured and all extractors fail, an exception is thrown. +> [!WARNING] +> **For users upgrading from version 3.1 or older:** Enabling this flag may require you to migrate data from the Default Container to the container configured in the message extractor. This action prevents message duplication. --- #end-if From 4cf28c5eca296e62d600ddde413901cecf5db130 Mon Sep 17 00:00:00 2001 From: Warwick Schroeder Date: Mon, 13 Oct 2025 09:53:30 +0800 Subject: [PATCH 6/6] Fix capitalization in warning note for upgrades --- persistence/cosmosdb/defaultcontainer.include.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/persistence/cosmosdb/defaultcontainer.include.md b/persistence/cosmosdb/defaultcontainer.include.md index 3e5122cf3c6..a2a98d6d66e 100644 --- a/persistence/cosmosdb/defaultcontainer.include.md +++ b/persistence/cosmosdb/defaultcontainer.include.md @@ -19,7 +19,7 @@ When this flag is enabled and multiple extractors are configured, the last extra > If an extractor fails to retrieve container information, the system falls back to the next available source in this order: Message Extractor → Header Extractor → configured default container. If no default container is configured and all extractors fail, an exception is thrown. > [!WARNING] -> **For users upgrading from version 3.1 or older:** Enabling this flag may require you to migrate data from the Default Container to the container configured in the message extractor. This action prevents message duplication. +> **For users upgrading from version 3.1 or older:** Enabling this flag may require you to migrate data from the default container to the container configured in the message extractor. This action prevents message duplication. --- #end-if