[17.0] Document breaking change: Azure Cosmos DB `configureClientOptions` callback now receives `IServiceProvider`

Open Beginner friendly
#2,130 0 comments 1 reaction 0 assignees View on GitHub

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.

The change applies to all six methods on Microsoft.Extensions.Hosting.AspireMicrosoftAzureCosmosExtensions:

  • AddAzureCosmosClient and AddKeyedAzureCosmosClient
  • AddAzureCosmosContainer and AddKeyedAzureCosmosContainer
  • AddAzureCosmosDatabase and AddKeyedAzureCosmosDatabase
- 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 as configureClientOptions no longer compiles. Calls that don't pass configureClientOptions still compile.
  • Binary: assemblies compiled against 13.x that call any of these methods throw MissingMethodException at run time, even if they don't pass configureClientOptions.
  • Behavior: configureClientOptions now runs when the CosmosClient is first resolved from DI, not during registration, so an exception thrown by the callback surfaces at that point. Likewise, CosmosDatabaseBuilder.AddKeyedContainer no longer creates the CosmosClient during 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*.mdx on main yet; follow the table in aspire-13-3.mdx.
  • Consider adding a configureClientOptions example next to the inline delegates example in azure-cosmos-db-connect.mdx, which only shows configureSettings today. 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

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from microsoft/aspire.dev

All issues in microsoft/aspire.dev

Similar issues

More Documentation issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.