integración de .NET AspireAzure Cosmos DB

Artículo
03/05/2025

incluye: integración de hospedaje de e integración de Client

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.

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.
AzureCosmosDBEmulatorResource: representa un recurso del emulador de AzureAzure Cosmos DB.

Para acceder a estos tipos y API para expresarlos, agregue el paquete NuGet 📦Aspire.Hosting.Azure.CosmosDB en el proyecto host de la aplicación .

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.CosmosDB

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

Para obtener más información, consulte dotnet add package o Administrar dependencias de paquetes en aplicaciones .NET.

Agregar AzureAzure Cosmos DB recurso

En el proyecto anfitrión de tu aplicación, llama a AddAzureCosmosDB para añadir y devolver un generador de recursos para 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.

Importante

Al llamar a AddAzureCosmosDB, llama implícitamente a AddAzureProvisioning, lo que agrega compatibilidad para generar recursos de Azure dinámicamente durante el inicio de la aplicación. La aplicación debe configurar la suscripción y la ubicación adecuadas. Para obtener más información, consulte aprovisionamiento local: Configuración.

Bicep de aprovisionamiento generado

Si eres nuevo en Bicep, es un lenguaje específico de dominio para definir recursos Azure. Con .NET.NET Aspire, no es necesario escribir Bicep manualmente, sino que las API de aprovisionamiento generan Bicep automáticamente. Al publicar tu aplicación, el Bicep generado se muestra junto al 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

param principalType string

param principalId string

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'
  }
}

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
}

output connectionString string = cosmos.properties.documentEndpoint

Bicep anterior es un módulo que aprovisiona una cuenta de AzureAzure Cosmos DB con los siguientes valores predeterminados:

kind: El tipo de Cosmos DB cuenta. El valor predeterminado es GlobalDocumentDB.
consistencyPolicy: La política de coherencia de la cuenta Cosmos DB. El valor predeterminado es Session.
locations: Las ubicaciones de la cuenta Cosmos DB. El valor predeterminado es la ubicación del grupo de recursos.

Además de la cuenta Cosmos DB, también añade la aplicación actual al rol Data Contributor para la cuenta Cosmos DB. El Bicep generado es un punto de partida y se puede personalizar para adaptar a tus necesidades específicas.

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 de Azure mediante la API de 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 elemento ú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. En lugar de representar un nuevo recurso de AzureAzure Cosmos DB, puede agregar una cadena de conexión al host de la aplicación. Para agregar una conexión a una cuenta de AzureAzure Cosmos DB existente, llame al método AddConnectionString:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Nota

Las cadenas de conexión se usan para representar una amplia gama de información de conexión, incluidas las conexiones de base de datos, los agentes de mensajes, los URI de punto de conexión y otros servicios. En .NET.NET Aspire nomenclatura, el término "cadena de conexión" se usa para representar cualquier tipo de información de conexión.

La cadena de conexión se configura en la configuración del host de la aplicación, normalmente en secretos de usuario, en la sección ConnectionStrings. El host de la aplicación inserta esta cadena de conexión como una variable de entorno en todos los recursos dependientes, por ejemplo:

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

El recurso dependiente puede acceder a la cadena de conexión insertada llamando al método GetConnectionString y pasando el nombre de conexión como parámetro, en este caso "cosmos-db". La API de GetConnectionString es una abreviatura de IConfiguration.GetSection("ConnectionStrings")[name].

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

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");
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");
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, consulte Bases de datos, contenedores y elementos de AzureAzure Cosmos DB.

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

Para agregar un recurso del emulador de AzureAzure Cosmos DB, haga una llamada encadenada desde un IResourceBuilder<AzureCosmosDBResource> a la API de 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 más.

Configuración del puerto de puerta de enlace de contenedor del emulador de Cosmos DB

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

Punto final	Puerto de contenedor	Puerto de servidor
`https`	8081	dinámico

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 existente de Cosmos DB en el contenedor del emulador de 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:

Nombre del punto de conexión	Asignación de puertos (`container:host`)
`https`	`8081:7777`

Configura el contenedor del emulador de Cosmos DB con vida útil 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 obtener más información, consulte duración del recurso del contenedor.

Configura el contenedor del emulador Cosmos DB con un 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 de acceso /tmp/cosmos/appdata en el contenedor emulador Cosmos DB y, cuando no se proporciona un parámetro name, el nombre se genera automáticamente. 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 los detalles sobre por qué se prefieren sobre los montajes enlazados, consulte la documentación Docker: 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 nueva generación del emulador de AzureAzure Cosmos DB está completamente basada en Linuxy disponible como un contenedor de 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 del emulador de vista previa basado en Linux y en Cosmos DB, con el punto de conexión de Data Explorer, para su uso en tiempo de ejecución.

Comprobaciones de estado 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 Client

Para comenzar con la integración del cliente .NET AspireAzure Cosmos DB, instale el paquete NuGet 📦Aspire.Microsoft.Azure.Cosmos en el proyecto que utiliza 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.

.NET CLI
PackageReference

dotnet add package Aspire.Microsoft.Azure.Cosmos

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

Agregar cliente Cosmos DB

En el archivo Program.cs de su proyecto cliente, utilice el método de extensión AddAzureCosmosClient en un IHostApplicationBuilder para registrar un CosmosClient para su uso mediante el contenedor de inyección de dependencias. El método toma un parámetro de nombre de conexión.

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

Propina

El parámetro connectionName debe coincidir con el nombre usado al agregar el recurso Cosmos DB en el proyecto host de la aplicación. Es decir, cuando se llama a AddAzureCosmosDB y se proporciona un nombre de cosmos-db ese mismo nombre se debe usar al llamar a AddAzureCosmosClient. Para obtener más información, consulte Agregar AzureAzure Cosmos DB recurso.

A continuación, puede recuperar la instancia CosmosClient usando la inyección de dependencias. Por ejemplo, para recuperar la conexión 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");

Importante

Cuando se usan servicios con claves, se espera que el recurso de Cosmos DB configure dos bases de datos con nombre, una para el mainDb y otra para la loggingDb.

A continuación, puede recuperar las instancias de CosmosClient mediante la 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.

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 obtener más información sobre cómo dar formato a esta cadena de conexió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 desde la configuración usando 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 obtener el esquema de integración completo del cliente Cosmos DBJSON, consulte Aspire. Microsoft.Azure. Cosmos/ConfigurationSchema.json.

Usa 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 del encabezado de agente de usuario CosmosClientOptions.ApplicationName para todas las solicitudes emitidas por este cliente:

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

Client verificaciones de estado de las integraciones

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 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 de integración y la telemetría, consulte información general sobre las integraciones de .NET.NET Aspire. 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 características de telemetría también se pueden deshabilitar mediante las técnicas presentadas en la sección 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

El rastreo de AzureAzure Cosmos DB se encuentra actualmente en versión preliminar, por lo que debe activar la opción experimental para asegurarse de que se emitan rastros.

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

Para obtener más información, consulte AzureAzure Cosmos DBObservabilidad del SDK: Atributos de trazas.

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
.NET Aspire Cosmos DB Entity Framework Core integración
visión general de las integraciones de .NET.NET Aspire
visión general de las integraciones de .NET AspireAzure
.NET Aspire GitHub repositorio

Compartir a través de