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

Abierto Apto para principiantes
  • ¿Algo no está bien?
#2,130 0 comentarios 1 reacción 0 asignados Ver en GitHub

Los mantenedores suelen responder en 2 días

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
2/5
Tiempo estimado
1-3 horas
Aptitud para principiantes
85/100
Tipo de issue
Documentación
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
csharp, markdown
Área
documentation

Línea de trabajo

Lee la tabla de cambios incompatibles en src/frontend/src/content/docs/whats-new/aspire-13-3.mdx y la sección configureClientOptions de src/frontend/src/content/docs/integrations/cloud/azure/azure-cosmos-db/azure-cosmos-db-connect.mdx. Añade el cambio incompatible de Aspire 17.0 a la página «What's new» de la versión 17.0 cuando exista y considera añadir un ejemplo actualizado de callback a la página de integración. El trabajo estará terminado cuando el cambio, su impacto en la compatibilidad y la migración estén documentados con precisión.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.
Lenguaje dominante
MDX
Estrellas
202
Forks
99
Merge medio
2 d 10 h
PR fusionados (30 d)
97

Preparar el entorno

Abrir en Codespaces

Inicia el contenedor de desarrollo del proyecto en tu navegador, con tu propia cuenta de GitHub.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de microsoft/aspire.dev

Todos los issues de microsoft/aspire.dev

Issues similares

Más issues de Documentation

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.