integración .NET AspireAzure Cosmos DB

Incluye: Integración de alojamiento —&— Client integración

Azure Cosmos DB es un servicio de base de datos NoSQL totalmente administrado para el desarrollo de aplicaciones modernas. La integración de .NET AspireAzure Cosmos DB permite conectarse a instancias de Cosmos DB existentes o crear nuevas instancias desde .NET con el emulador de Azure Cosmos DB.

Si busca la integración Entity Framework Core, consulte .NET AspireCosmos DBEntity Framework Core integración.

Integración de hospedaje

El modelo de integración de hospedaje de .NET.NET AspireAzure Cosmos DB modela los diversos recursos Cosmos DB como los siguientes tipos:

• AzureCosmosDBResource: representa un recurso AzureAzure Cosmos DB.
• AzureCosmosDBContainerResource: representa un AzureAzure Cosmos DB recurso de contenedor.
• AzureCosmosDBDatabaseResource: representa un AzureAzure Cosmos DB recurso de base de datos.
• AzureCosmosDBEmulatorResource: representa un recurso del emulador de AzureAzure Cosmos DB.

Para acceder a estos tipos y API para expresarlos, añade el paquete 📦Aspire.Hosting.Azure.CosmosDB NuGet en el proyecto app host.

dotnet add package Aspire.Hosting.Azure.CosmosDB

<PackageReference Include="Aspire.Hosting.Azure.CosmosDB"
                  Version="*" />

Para obtener más información, consulte dotnet add package (Agregar paquete ) o Manage package dependencies in applications (Administrar dependencias de paquetes en .NET aplicaciones).

Agregar AzureAzure Cosmos DB recurso

En el proyecto host de su app, llama a AddAzureCosmosDB para añadir y devolver un compilador de recursos AzureAzure Cosmos DB.

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db");

// After adding all resources, run the app...

Al agregar un AzureCosmosDBResource al host de la aplicación, expone otras API útiles para agregar bases de datos y contenedores. Es decir, debe agregar un AzureCosmosDBResource antes de agregar cualquiera de los otros recursos Cosmos DB.

Bicep generado por el aprovisionamiento

Si no está familiarizado con Bicep, es un lenguaje específico del dominio para definir Azure recursos. Con .NET.NET Aspire, no es necesario escribir Bicep manualmente, sino que las API de aprovisionamiento generan Bicep automáticamente. Al publicar la aplicación, el Bicep generado se muestra junto con el archivo de manifiesto. Al agregar un recurso AzureAzure Cosmos DB, se genera el siguiente Bicep:

@description('The ___location for the resource(s) to be deployed.')
param ___location string = resourceGroup().___location

resource cosmos 'Microsoft.DocumentDB/databaseAccounts@2024-08-15' = {
  name: take('cosmos-${uniqueString(resourceGroup().id)}', 44)
  ___location: ___location
  properties: {
    locations: [
      {
        locationName: ___location
        failoverPriority: 0
      }
    ]
    consistencyPolicy: {
      defaultConsistencyLevel: 'Session'
    }
    databaseAccountOfferType: 'Standard'
    disableLocalAuth: true
  }
  kind: 'GlobalDocumentDB'
  tags: {
    'aspire-resource-name': 'cosmos'
  }
}

output connectionString string = cosmos.properties.documentEndpoint

output name string = cosmos.name

El Bicep anterior es un módulo que aprovisiona un recurso de cuenta AzureAzure Cosmos DB. Además, las asignaciones de roles se crean para el Azure recurso en un módulo independiente:

@description('The ___location for the resource(s) to be deployed.')
param ___location string = resourceGroup().___location

param cosmos_outputs_name string

param principalId string

resource cosmos 'Microsoft.DocumentDB/databaseAccounts@2024-08-15' existing = {
  name: cosmos_outputs_name
}

resource cosmos_roleDefinition 'Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions@2024-08-15' existing = {
  name: '00000000-0000-0000-0000-000000000002'
  parent: cosmos
}

resource cosmos_roleAssignment 'Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments@2024-08-15' = {
  name: guid(principalId, cosmos_roleDefinition.id, cosmos.id)
  properties: {
    principalId: principalId
    roleDefinitionId: cosmos_roleDefinition.id
    scope: cosmos.id
  }
  parent: cosmos
}

El Bicep generado es un punto de partida y se ve influido por los cambios en la infraestructura de aprovisionamiento en C#. Las personalizaciones realizadas directamente en el archivo Bicep se sobrescribirán, por lo que los cambios deben realizarse a través de las API de aprovisionamiento de C# para garantizar que se reflejen en los archivos generados.

Personalización de la infraestructura de aprovisionamiento

Todos los recursos .NET AspireAzure son subclases del tipo AzureProvisioningResource. Este tipo permite la personalización del Bicep generado proporcionando una API fluida para configurar los recursos Azure mediante la API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Por ejemplo, puede configurar el kind, consistencyPolicy, locations, etc. En el ejemplo siguiente se muestra cómo personalizar el recurso de AzureAzure Cosmos DB:

builder.AddAzureCosmosDB("cosmos-db")
    .ConfigureInfrastructure(infra =>
    {
        var cosmosDbAccount = infra.GetProvisionableResources()
                                   .OfType<CosmosDBAccount>()
                                   .Single();

        cosmosDbAccount.Kind = CosmosDBAccountKind.MongoDB;
        cosmosDbAccount.ConsistencyPolicy = new()
        {
            DefaultConsistencyLevel = DefaultConsistencyLevel.Strong,
        };
        cosmosDbAccount.Tags.Add("ExampleKey", "Example value");
    });

El código anterior:

• Encadena una llamada a la API ConfigureInfrastructure:
  • El parámetro infra es una instancia del tipo AzureResourceInfrastructure.
  • Los recursos aprovisionables se recuperan llamando al método GetProvisionableResources().
  • Se recupera el único CosmosDBAccount.
  • El CosmosDBAccount.ConsistencyPolicy se asigna a un DefaultConsistencyLevel.Strong.
  • Se agrega una etiqueta a la cuenta de Cosmos DB con una clave de ExampleKey y un valor de Example value.

Hay muchas más opciones de configuración disponibles para personalizar el recurso AzureAzure Cosmos DB. Para obtener más información, consulte Azure.Provisioning.CosmosDB. Para obtener más información, vea Azure. Personalización del aprovisionamiento.

Conexión a una cuenta de AzureAzure Cosmos DB existente

Es posible que tenga una cuenta de AzureAzure Cosmos DB existente a la que desea conectarse. Puede encadenar una llamada para anotar que su AzureCosmosDBResource es un recurso existente:

var builder = DistributedApplication.CreateBuilder(args);

var existingCosmosName = builder.AddParameter("existingCosmosName");
var existingCosmosResourceGroup = builder.AddParameter("existingCosmosResourceGroup");

var cosmos = builder.AddAzureCosmosDB("cosmos-db")
                    .AsExisting(existingCosmosName, existingCosmosResourceGroup);

builder.AddProject<Projects.WebApplication>("web")
       .WithReference(cosmos);

// After adding all resources, run the app...

Para obtener más información sobre cómo tratar los recursos de AzureAzure Cosmos DB como recursos existentes, consulte Uso de recursos de Azure existentes.

Añadir recursos de base de datos y contenedor AzureAzure Cosmos DB

.NET Aspire modela las relaciones de padre e hijo entre Azure Cosmos DB recursos. Por ejemplo, una AzureAzure Cosmos DB cuenta (AzureCosmosDBResource) puede tener varias bases de datos (AzureCosmosDBDatabaseResource) y cada base de datos puede tener varios contenedores (AzureCosmosDBContainerResource). Al agregar una base de datos o un recurso de contenedor, lo hace en un recurso primario.

Para agregar un recurso de base de datos de AzureAzure Cosmos DB, llame al método AddCosmosDatabase en una instancia de IResourceBuilder<AzureCosmosDBResource>:

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db");
var db = cosmos.AddCosmosDatabase("db");

// After adding all resources, run the app...

Al llamar a AddCosmosDatabase, agrega una base de datos denominada db a los recursos de Cosmos DB y devuelve el recurso de base de datos recién creado. La base de datos se crea en la cuenta de Cosmos DB que está representada por el AzureCosmosDBResource que has agregado anteriormente. La base de datos es un contenedor lógico para colecciones y usuarios.

Un contenedor de AzureAzure Cosmos DB es donde se almacenan los datos. Al crear un contenedor, debe proporcionar una clave de partición.

Para agregar un recurso de contenedor de AzureAzure Cosmos DB, llame al método AddContainer en una instancia de IResourceBuilder<AzureCosmosDBDatabaseResource>:

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db");
var db = cosmos.AddCosmosDatabase("db");
var container = db.AddContainer("entries", "/id");

// After adding all resources, run the app...

El contenedor se crea en la base de datos representada por el AzureCosmosDBDatabaseResource que agregó anteriormente. Para obtener más información, vea Bases de datos, contenedores y elementos en AzureAzure Cosmos DB.

Ejemplo de relación de recursos padre-hijo

Para comprender mejor la relación de elementos primarios y secundarios entre Azure Cosmos DB recursos, considere el ejemplo siguiente, que muestra cómo agregar un Azure Cosmos DB recurso junto con una base de datos y un contenedor:

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos");

var customers = cosmos.AddCosmosDatabase("customers");
var profiles = customers.AddContainer("profiles", "/id");

var orders = cosmos.AddCosmosDatabase("orders");
var details = orders.AddContainer("details", "/id");
var history = orders.AddContainer("history", "/id");

builder.AddProject<Projects.Api>("api")
       .WithReference(profiles)
       .WithReference(details)
       .WithReference(history);

builder.Build().Run();

El código anterior agrega un AzureAzure Cosmos DB recurso denominado cosmos con dos bases de datos: customers y orders. La customers base de datos tiene un único contenedor denominado profiles, mientras que la orders base de datos tiene dos contenedores: details y history. La clave de partición de cada contenedor es /id.

El siguiente diagrama ilustra la relación padre-hijo entre los recursos AzureAzure Cosmos DB:

Cuando el código host de su aplicación exprese las relaciones primarias-secundarias, el cliente podrá establecer enlaces profundos a estos recursos por su nombre. Por ejemplo, se puede hacer referencia a la customers base de datos por nombre en el proyecto cliente, registrando una Database instancia que se conecta a la customers base de datos. Lo mismo se aplica a los contenedores con nombre, por ejemplo, el details contenedor se puede hacer referencia por nombre en el proyecto cliente, registrando una Container instancia que se conecta al details contenedor.

Adición de un recurso del emulador de AzureAzure Cosmos DB

Para añadir un recurso emulador AzureAzure Cosmos DB, encadene una llamada en un IResourceBuilder<AzureCosmosDBResource> a la API RunAsEmulator:

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db")
                    .RunAsEmulator();

// After adding all resources, run the app...

Al llamar a RunAsEmulator, configura los recursos de Cosmos DB para que se ejecuten localmente mediante un emulador. En este caso, el emulador es el AzureAzure Cosmos DB Emulador. El emulador de Azure Cosmos DB proporciona un entorno local gratuito para probar las aplicaciones de Azure Cosmos DB y es un complemento perfecto para la integración de hospedaje .NET AspireAzure. El emulador no está instalado, sino que es accesible para .NET.NET Aspire como contenedor. Al agregar un contenedor al host de la aplicación, como se muestra en el ejemplo anterior con la imagen de mcr.microsoft.com/cosmosdb/emulator, crea e inicia el contenedor cuando se inicia el host de la aplicación. Para obtener más información, consulte el ciclo de vida de recursos de contenedor .

Configuración del contenedor del emulador de Cosmos DB

Hay varias configuraciones disponibles para los recursos de contenedor, por ejemplo, puede configurar los puertos del contenedor, las variables de entorno, su duración y mucho más.

Configurar el puerto de puerta de enlace del contenedor emulador Cosmos DB

De forma predeterminada, el contenedor del emulador de Cosmos DB cuando lo configura .NET Aspire, expone los siguientes puntos de conexión:

El puerto en el que está escuchando es dinámico de forma predeterminada. Cuando se inicia el contenedor, el puerto se asigna a un puerto aleatorio en el equipo host. Para configurar el puerto de punto de conexión, encadene llamadas en el generador de recursos de contenedor proporcionado por el método RunAsEmulator tal como se muestra en el ejemplo siguiente:

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db").RunAsEmulator(
                     emulator =>
                     {
                         emulator.WithGatewayPort(7777);
                     });

// After adding all resources, run the app...

El código anterior configura el punto de conexión Cosmos DB del contenedor del emulador https para que escuche en el puerto 8081. El puerto del contenedor del emulador de Cosmos DB se asigna al puerto host, como se muestra en la tabla siguiente:

Configurar contenedor emulador Cosmos DB con tiempo de vida persistente

Para configurar el contenedor del emulador de Cosmos DB con una vida útil persistente, llame al método WithLifetime en el recurso de contenedor del emulador de Cosmos DB y pase ContainerLifetime.Persistent:

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db").RunAsEmulator(
                     emulator =>
                     {
                         emulator.WithLifetime(ContainerLifetime.Persistent);
                     });

// After adding all resources, run the app...

Para más información, consulte Duración de los recursos del contenedor.

Configurar contenedor emulador Cosmos DB con volumen de datos

Para agregar un volumen de datos al recurso del emulador de AzureAzure Cosmos DB, llame al método WithDataVolume en el recurso del emulador de AzureAzure Cosmos DB:

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db").RunAsEmulator(
                     emulator =>
                     {
                         emulator.WithDataVolume();
                     });

// After adding all resources, run the app...

El volumen de datos se usa para conservar los datos del emulador de Cosmos DB fuera del ciclo de vida de su contenedor. El volumen de datos se monta en la ruta /tmp/cosmos/appdata en el contenedor emulador Cosmos DB y cuando no se proporciona un parámetro name, se genera el nombre. El emulador tiene su variable de entorno AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE establecida en true. Para obtener más información sobre los volúmenes de datos y detalles sobre por qué se prefieren sobre montajes de enlace, consulte Docker docs: Volúmenes.

Configurar la cantidad de particiones del contenedor del emulador Cosmos DB

Para configurar el recuento de particiones del contenedor del emulador de Cosmos DB, llame al método WithPartitionCount:

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db").RunAsEmulator(
                     emulator =>
                     {
                         emulator.WithPartitionCount(100); // Defaults to 25
                     });

// After adding all resources, run the app...

El código anterior configura el contenedor del emulador de Cosmos DB para tener un recuento de particiones de 100. Se trata de una abreviatura para establecer la variable de entorno AZURE_COSMOS_EMULATOR_PARTITION_COUNT.

Uso del emulador basado en Linux(versión preliminar)

La próxima generación del AzureAzure Cosmos DB emulador está basada completamente en Linux y está disponible como un contenedor Docker. Admite la ejecución en una amplia variedad de procesadores y sistemas operativos.

Para usar la versión preliminar del emulador de Cosmos DB, llame al método RunAsPreviewEmulator. Dado que esta característica está en versión preliminar, debe habilitar explícitamente la función de vista previa suprimiendo el diagnóstico experimental ASPIRECOSMOSDB001.

El emulador de vista previa también admite la exposición de un punto de conexión de "Data Explorer", que permite ver los datos almacenados en el emulador de Cosmos DB a través de una interfaz de usuario web. Para habilitar el Explorador de datos, llame al método WithDataExplorer.

#pragma warning disable ASPIRECOSMOSDB001

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db").RunAsPreviewEmulator(
                     emulator =>
                     {
                         emulator.WithDataExplorer();
                     });

// After adding all resources, run the app...

El código anterior configura el contenedor emulador basado en la Linuxvista previa Cosmos DB, con el punto de conexión Data Explorer, para utilizarlo en tiempo de ejecución.

Comprobaciones de salud de integración de hospedaje

La integración de hospedaje Azure Cosmos DB agrega automáticamente una comprobación de estado para el recurso Cosmos DB. La verificación de salud comprueba que el Cosmos DB está en funcionamiento y que se puede establecer una conexión con él.

La integración de hospedaje se basa en el 📦 paquete NuGet AspNetCore.HealthChecks.CosmosDb .

Integración con Client

Para empezar a trabajar con la integración del cliente .NET AspireAzure Cosmos DB, instale el paquete NuGet 📦Aspire.Microsoft.Azure.Cosmos en el proyecto que consume el cliente, es decir, el proyecto de la aplicación que usa el cliente Cosmos DB. La integración de cliente Cosmos DB registra una instancia de CosmosClient que puede usar para interactuar con Cosmos DB.

dotnet add package Aspire.Microsoft.Azure.Cosmos

<PackageReference Include="Aspire.Microsoft.Azure.Cosmos"
                  Version="*" />

Agregar cliente Cosmos DB

En el archivo Program.cs del proyecto que consume el cliente, llame al método de extensión AddAzureCosmosClient en cualquier IHostApplicationBuilder para registrar un CosmosClient para su uso a través del contenedor de inyección de dependencias. El método toma un parámetro de nombre de conexión.

builder.AddAzureCosmosClient(connectionName: "cosmos-db");

A continuación, puede recuperar la instancia CosmosClient usando la inyección de dependencias. Por ejemplo, para recuperar el cliente de un servicio de ejemplo:

public class ExampleService(CosmosClient client)
{
    // Use client...
}

Para obtener más información sobre la inserción de dependencias, consulte .NET Inserción de dependencias.

Adición de un cliente de Cosmos DB con clave

Puede haber situaciones en las que quiera registrar varias instancias de CosmosClient con nombres de conexión diferentes. Para registrar clientes de Cosmos DB con clave, llame al método AddKeyedAzureCosmosClient:

builder.AddKeyedAzureCosmosClient(name: "mainDb");
builder.AddKeyedAzureCosmosClient(name: "loggingDb");

Luego puede recuperar las instancias CosmosClient usando inyección de dependencias. Por ejemplo, para recuperar la conexión de un servicio de ejemplo:

public class ExampleService(
    [FromKeyedServices("mainDb")] CosmosClient mainDbClient,
    [FromKeyedServices("loggingDb")] CosmosClient loggingDbClient)
{
    // Use clients...
}

Para obtener más información sobre los servicios con claves, consulte .NET Inserción de dependencias: Servicios con claves.

Agregar AzureAzure Cosmos DB base de datos

En el host de la aplicación, el recurso de base de datos (AzureCosmosDBDatabaseResource) se puede agregar como un recurso secundario al elemento primario AzureCosmosDBResource. En su proyecto cliente-consumidor, puede vincular en profundidad el recurso de base de datos por nombre, registrando una instancia Database para su uso con inyección de dependencias. Por ejemplo, considere el código siguiente que llama a AddAzureCosmosDatabase en una IHostApplicationBuilder instancia:

builder.AddAzureCosmosDatabase(connectionName: "customers");

La AddAzureCosmosDatabase API devuelve una CosmosDatabaseBuilder instancia que puede usar para adjuntar varios contenedores en la misma conexión de base de datos. Todos los contenedores secundarios comparten la misma CosmosClient y conexión de base de datos e instancia CosmosClient. Esta estrategia es útil al asociar lo mismo CosmosClientOptions con varios contenedores.

Después de llamar a AddAzureCosmosDatabase, puede recuperar la instancia Database utilizando la inyección de dependencia. Por ejemplo, para recuperar la base de datos de un delegado en una MapGet llamada, tenga en cuenta el código siguiente:

app.MapGet("/api/customers", async (Database database) =>
{
    // Query data from database...
});

Agregar base de datos con AzureAzure Cosmos DB claves

También hay una AddKeyedAzureCosmosDatabase API que devuelve una CosmosDatabaseBuilder instancia que puede usar para adjuntar varios contenedores en la misma conexión de base de datos. método que permite registrar varias bases de datos con nombres de conexión diferentes. Por ejemplo, considere el código siguiente que llama a AddKeyedAzureCosmosDatabase en una IHostApplicationBuilder instancia:

var builder = WebApplication.CreateBuilder(args);

builder.AddKeyedAzureCosmosDatabase("customers");
builder.AddKeyedAzureCosmosDatabase("orders");

var app = builder.Build();

app.MapGet("/api/customers", async (
    [FromKeyedServices("customers")] Database database) =>
{
    // Get container from database and query data
});

app.MapPost("/api/orders", async (
    [FromKeyedServices("orders")] Database database,
    [FromBody] OrderRequest order) =>
{
    // Get container from database and query data
});

app.Run();

En el código de ejemplo anterior se muestra cómo registrar dos bases de datos: details y customers. Cada base de datos con nombre se puede usar para obtener sus contenedores correspondientes para consultar datos.

Agregar AzureAzure Cosmos DB contenedor

Al agregar un Cosmos DB recurso en el proyecto host de la aplicación, también puede agregar un Azure Cosmos DB recurso de contenedor. El recurso de contenedor se considera un recurso secundario en el elemento primario AzureCosmosDBDatabaseResource. En su proyecto cliente-consumidor, puede vincular en profundidad el recurso de contenedor por nombre, registrando una instancia Container para su uso con inyección de dependencias. Por ejemplo, considere el código siguiente que llama a AddAzureCosmosContainer en una IHostApplicationBuilder instancia:

builder.AddAzureCosmosContainer(connectionName: "details");

A continuación, puede recuperar la instancia Container usando la inyección de dependencias. Por ejemplo, para recuperar el contenedor de un delegado en una llamada MapGet, considere el siguiente código:

app.MapGet("/api/orders/{id:guid}", async (
    Container container, 
    [FromRoute] Guid id) =>
{
    // Query data from container...
});

Agregue un contenedor con clave AzureAzure Cosmos DB

También hay un AddKeyedAzureCosmosContainer método que permite registrar varios contenedores con nombres de conexión diferentes. Por ejemplo, considere el código siguiente que llama a AddKeyedAzureCosmosContainer en una IHostApplicationBuilder instancia:

var builder = WebApplication.CreateBuilder(args);

builder.AddKeyedAzureCosmosContainer("customers");

var app = builder.Build();

app.MapGet("/api/customers", async (
    [FromKeyedServices("customers")] Container container) =>
{
    // Query data from container...
});

app.Run();

Si tiene varios contenedores en la misma conexión de base de datos, puede usar la AddAzureCosmosDatabase API para adjuntar varios contenedores en la misma conexión de base de datos. Todos los contenedores secundarios comparten la misma CosmosClient y conexión a la base de datos. Esta estrategia es útil al asociar lo mismo CosmosClientOptions con varios contenedores. Considere el siguiente código alternativo para registrar varios contenedores en la misma conexión de base de datos:

var builder = WebApplication.CreateBuilder(args);

builder.AddAzureCosmosDatabase("customers", configureClientOptions: options =>
    {
        options.SerializerOptions = new CosmosSerializationOptions()
        {
            PropertyNamingPolicy = CosmosPropertyNamingPolicy.CamelCase
        };
    })
    .AddKeyedContainer(name: "profiles");

builder.AddAzureCosmosDatabase(connectionName: "orders")
       .AddKeyedContainer(name: "details")
       .AddKeyedContainer(name: "history");

var app = builder.Build();

app.MapGet("/api/customers", async (
    [FromKeyedServices("profiles")] Container container) =>
{
    // Query data from container
});

app.MapGet("/api/orders", async (
    [FromKeyedServices("details")] Container container,
    [FromKeyedServices("history")] Container container) =>
{
    // Query data from container
});

app.Run();

En el código de ejemplo anterior se muestra cómo registrar dos bases de datos customers y orders, cada una con sus propios contenedores. La customers base de datos tiene un único contenedor denominado profiles, mientras que la orders base de datos tiene dos contenedores denominados details y history. Cada contenedor se puede consultar individualmente mediante su clave respectiva.

Configuración

La integración de .NET AspireAzure Cosmos DB proporciona varias opciones para configurar la conexión en función de los requisitos y convenciones del proyecto.

Uso de una cadena de conexión

Al usar una cadena de conexión de la sección de configuración de ConnectionStrings, puede proporcionar el nombre de la cadena de conexión al llamar al método AddAzureCosmosClient:

builder.AddAzureCosmosClient("cosmos-db");

A continuación, la cadena de conexión se recupera de la sección de configuración de ConnectionStrings:

{
  "ConnectionStrings": {
    "cosmos-db": "AccountEndpoint=https://{account_name}.documents.azure.com:443/;AccountKey={account_key};"
  }
}

Para más información, consulte la documentación de ConnectionString.

Uso de proveedores de configuración

La integración de .NET AspireAzure Cosmos DB admite Microsoft.Extensions.Configuration. Carga el MicrosoftAzureCosmosSettings de configuración utilizando la clave Aspire:Microsoft:Azure:Cosmos. El fragmento de código siguiente es un ejemplo de un archivo appsettings.json que configura algunas de las opciones:

{
  "Aspire": {
    "Microsoft": {
      "Azure": {
        "Cosmos": {
          "DisableTracing": false,
        }
      }
    }
  }
}

Para el esquema completo de integración Cosmos DB de cliente JSON, consulte Aspire.Microsoft.Azure.Cosmos/ConfigurationSchema.json.

Utilice delegados en línea

También puede pasar el objeto delegado Action<MicrosoftAzureCosmosSettings> configureSettings para configurar algunas o todas las opciones directamente, por ejemplo, para deshabilitar el seguimiento desde el código:

builder.AddAzureCosmosClient(
    "cosmos-db",
    static settings => settings.DisableTracing = true);

También puede configurar el Microsoft.Azure.Cosmos.CosmosClientOptions mediante el parámetro opcional Action<CosmosClientOptions> configureClientOptions del método AddAzureCosmosClient. Por ejemplo para establecer el sufijo de cabecera CosmosClientOptions.ApplicationName de agente de usuario para todas las peticiones emitidas por este cliente:

builder.AddAzureCosmosClient(
    "cosmosConnectionName",
    configureClientOptions:
        clientOptions => clientOptions.ApplicationName = "myapp");

Client comprobaciones de estado de la integración

Actualmente, la integración de cliente de .NET AspireCosmos DB no implementa comprobaciones de estado, aunque esto puede cambiar en futuras versiones.

Observabilidad y telemetría

.NET.NET Aspire las integraciones configuran automáticamente las configuraciones de registro, seguimiento y métricas, que a veces se conocen como los pilares de la observabilidad. Para obtener más información sobre la observabilidad y la telemetría de integración, consulte .NET.NET Aspire La introducción a las integraciones. En función del servicio de respaldo, algunas integraciones solo pueden admitir algunas de estas características. Por ejemplo, algunas integraciones admiten el registro y el seguimiento, pero no las métricas. Las funciones de telemetría también se pueden deshabilitar mediante las técnicas presentadas en la sección de configuración .

Registro

La integración de .NET AspireAzure Cosmos DB usa las siguientes categorías de registro:

• Azure-Cosmos-Operation-Request-Diagnostics

Además de obtener diagnósticos de solicitudes con errores Azure Cosmos DB, puede configurar umbrales de latencia para determinar qué diagnósticos de solicitudes exitosas se registrarán Azure Cosmos DB. Los valores predeterminados son 100 ms para las operaciones de punto y 500 ms para las operaciones que no son de punto.

builder.AddAzureCosmosClient(
    "cosmosConnectionName",
    configureClientOptions:
        clientOptions => {
            clientOptions.CosmosClientTelemetryOptions = new()
            {
                CosmosThresholdOptions = new()
                {
                    PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(50),
                    NonPointOperationLatencyThreshold = TimeSpan.FromMilliseconds(300)
                }
            };
        });

Seguimiento

La integración de .NET AspireAzure Cosmos DB emitirá las siguientes actividades de seguimiento mediante OpenTelemetry:

• Azure.Cosmos.Operation

Azure Azure Cosmos DB rastreo está actualmente en vista previa, por lo que debe establecer el interruptor experimental para garantizar que se emitan trazas.

AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true);

Para más información, consulte AzureAzure Cosmos DB Observabilidad del SDK: Atributos de seguimiento.

Métricas

La integración de .NET AspireAzure Cosmos DB actualmente no admite métricas de forma predeterminada debido a limitaciones con el SDK de Azure.

Consulte también

• Azure Cosmos DB
• Repositorio de ejemplo que muestra las relaciones entre padres e hijos
• .NET AspireCosmos DBEntity Framework Core integración
• .NET.NET Aspire Introducción a las integraciones
• .NET AspireAzure Introducción a las integraciones
• .NET AspireGitHub Repo