Skip to content

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

Closed

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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions