Repository navigation
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: Add IServiceProvider support to Cosmos DB extensions aspire#19349 (partially addresses CosmosDB Components should allow for CosmosClientOptions to be configured via IConfiguration aspire#667)
- Raised in the 17.0 API review: [Automated] Update API Surface Area (release/17.0) aspire#22185 (comment)
- The change was held for 17.0 so it could ship as a breaking change: [Automated] Update API Surface Area (release/17.0) aspire#22185 (comment)
The change applies to all six methods on Microsoft.Extensions.Hosting.AspireMicrosoftAzureCosmosExtensions:
AddAzureCosmosClientandAddKeyedAzureCosmosClientAddAzureCosmosContainerandAddKeyedAzureCosmosContainerAddAzureCosmosDatabaseandAddKeyedAzureCosmosDatabase
- Action<CosmosClientOptions>? configureClientOptions = null
+ Action<IServiceProvider, CosmosClientOptions>? configureClientOptions = nullWhy 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 nowhats-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.
Activity
Address open 17.0 milestone doc issues
Fill remaining Aspire 17.0 doc gaps and add 17.0 dashboard captures (#…
IEvangelist commentedon Nov 17, 2026
Addressed in #2188 (merged into release/17.0).