[17.0] Document breaking change: Azure Cosmos DB `configureClientOptions` callback now receives `IServiceProvider`
Maintainers usually reply within 2 days
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 85/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- csharp, markdown
- Domain
- documentation
Research direction
Read the Breaking changes table in src/frontend/src/content/docs/whats-new/aspire-13-3.mdx and the configureClientOptions section of src/frontend/src/content/docs/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-connect.mdx. Add the Aspire 17.0 breaking change to the 17.0 What's new page when it exists, and consider adding an updated callback example to the integration page. Done means the change, compatibility impact, and migration are documented accurately.
Written by the indexing model from the issue text.
Description
In Aspire 17.0, the configureClientOptions parameter in the stable Aspire.Microsoft.Azure.Cosmos client integration changed from Action<CosmosClientOptions>? to Action<IServiceProvider, CosmosClientOptions>?. The old signatures were removed rather than kept as overloads. This breaks both source and binary compatibility, so it should be listed in the 17.0 breaking changes.
- Code change: microsoft/aspire#19349 (partially addresses microsoft/aspire#667)
- Raised in the 17.0 API review: https://github.com/microsoft/aspire/pull/22185#discussion_r4552196618
- The change was held for 17.0 so it could ship as a breaking change: https://github.com/microsoft/aspire/pull/22185#discussion_r4553509110
The change applies to all six methods on Microsoft.Extensions.Hosting.AspireMicrosoftAzureCosmosExtensions:
AddAzureCosmosClientandAddKeyedAzureCosmosClientAddAzureCosmosContainerandAddKeyedAzureCosmosContainerAddAzureCosmosDatabaseandAddKeyedAzureCosmosDatabase
- Action<CosmosClientOptions>? configureClientOptions = null
+ Action<IServiceProvider, CosmosClientOptions>? configureClientOptions = null
Why it changed
The callback can now resolve services from DI while it configures the client. For example, it can add RequestHandler instances that have their own dependencies to CosmosClientOptions.CustomHandlers.
Impact
- Source: passing a single-parameter lambda, a method group, or an
Action<CosmosClientOptions>variable asconfigureClientOptionsno longer compiles. Calls that don't passconfigureClientOptionsstill compile. - Binary: assemblies compiled against 13.x that call any of these methods throw
MissingMethodExceptionat run time, even if they don't passconfigureClientOptions. - Behavior:
configureClientOptionsnow runs when theCosmosClientis first resolved from DI, not during registration, so an exception thrown by the callback surfaces at that point. Likewise,CosmosDatabaseBuilder.AddKeyedContainerno longer creates theCosmosClientduring registration, so missing connection information is reported when the container is first resolved.
Migration
Add an IServiceProvider parameter to the callback:
// Aspire 13.x
builder.AddAzureCosmosClient("cosmos", configureClientOptions: options =>
{
options.ApplicationName = "myapp";
});
// Aspire 17.0
builder.AddAzureCosmosClient("cosmos", configureClientOptions: (services, options) =>
{
options.ApplicationName = "myapp";
});
The new parameter can resolve services that the options need:
builder.Services.AddSingleton<MyRequestHandler>(); // MyRequestHandler derives from RequestHandler
builder.AddAzureCosmosClient("cosmos", configureClientOptions: (services, options) =>
{
options.CustomHandlers.Add(services.GetRequiredService<MyRequestHandler>());
});
Where to document
- Add a row to the ⚠️ Breaking changes table on the 17.0 What's new page. There's no
whats-new/aspire-17*.mdxonmainyet; follow the table in aspire-13-3.mdx. - Consider adding a
configureClientOptionsexample next to the inline delegates example in azure-cosmos-db-connect.mdx, which only showsconfigureSettingstoday. The package README has an updated example.
- Dominant language
- MDX
- Stars
- 202
- Forks
- 99
- Avg merge
- 3d 22h
- Merged PRs (30d)
- 138
Getting set up
Starts the project's dev container in your browser, under your own GitHub account.
- No Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from microsoft/aspire.dev
-
documentation
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
microsoft/aspire.dev#2184 ·
Maintainers usually reply within 2 days
-
documentation missing-conceptual-docs
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
microsoft/aspire.dev#2181 ·
Maintainers usually reply within 2 days
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
microsoft/aspire.dev#2131 ·
Maintainers usually reply within 2 days
-
Difficulty 1/5 1-3 hours Newbie friendliness 82/100
microsoft/aspire.dev#2129 ·
Maintainers usually reply within 2 days
-
Docs: note that Bun resources don't trust the dev cert via NODE_EXTRA_CA_CERTS (upstream Bun bug)Open
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
microsoft/aspire.dev#1802 · 3 comments ·
Maintainers usually reply within 2 days
All issues in microsoft/aspire.dev
Similar issues
-
content triage
Difficulty 1/5 Under an hour Newbie friendliness 88/100
Maintainers usually reply within 1 day
-
Link Checker ReportOpenautomated issue linkchecker report
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
QuantEcon/lecture-python.myst#1130 ·
Maintainers usually reply within 1 day
-
Enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
JSPrismarine/JSPrismarine#3214 ·
Maintainers usually reply within 1 day
-
feature request status/untriaged
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
karakeep-app/karakeep#3383 · 1 comment ·
Maintainers usually reply within 1 day
-
area-cli documentation triage:bot-seen triage:needs-human
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
microsoft/aspire#22344 · 2 comments ·
Maintainers usually reply within 1 day