integrazione di .NET AspireeAzure Cosmos DB

Articolo
01/09/2025

includere:Integrazione dell'hosting e Client Integrazione

Azure Cosmos DB è un servizio di database NoSQL completamente gestito per lo sviluppo di app moderne. L'integrazione .NET AspireAzure Cosmos DB consente di connettersi alle istanze di Cosmos DB esistenti o di creare nuove istanze da .NET con l'emulatore di Azure Cosmos DB.

Integrazione dell'hosting

Il .NET.NET AspireAzure Cosmos DB che ospita l'integrazione modella le varie risorse Cosmos DB come i tipi seguenti:

AzureCosmosDBResource: rappresenta una risorsa di AzureAzure Cosmos DB.
AzureCosmosDBEmulatorResource: rappresenta una risorsa emulatore di AzureAzure Cosmos DB.

Per accedere a questi tipi e alle API per esprimerli, aggiungere il pacchetto NuGet 📦Aspire.Hosting.Azure.CosmosDB nel progetto host dell'app .

.NET interfaccia a riga di comando
PackageReference

dotnet add package Aspire.Hosting.Azure.CosmosDB

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

Per ulteriori informazioni, vedere dotnet add package o Gestire le dipendenze dei pacchetti nelle applicazioni .NET.

Aggiungere risorsa AzureAzure Cosmos DB

Nel progetto host della tua app, chiama AddAzureCosmosDB per aggiungere e restituire un generatore di risorse AzureAzure Cosmos DB.

var builder = DistributedApplication.CreateBuilder(args);

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

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

Quando si aggiunge un AzureCosmosDBResource all'host dell'app, espone altre API utili per aggiungere database e contenitori. In altre parole, è necessario aggiungere AzureCosmosDBResource prima di aggiungere qualunque altra risorsa Cosmos DB.

Importante

Quando si chiama AddAzureCosmosDB, si attiva implicitamente AddAzureProvisioning, che aggiunge il supporto per la generazione dinamica di risorse Azure durante l'avvio dell'app. L'app deve configurare la sottoscrizione e la posizione appropriate. Per ulteriori informazioni, vedere Configurazione locale: Provisioning .

Bicep di provisioning generato

Se sei nuovo a Bicep, si tratta di un linguaggio specifico del dominio per la definizione delle risorse Azure. Con .NET.NET Aspirenon è necessario scrivere Bicep a mano, perché le API di provisioning generano Bicep per te automaticamente. Quando si pubblica l'app, il Bicep generato viene generato insieme al file manifesto. Quando si aggiunge una risorsa AzureAzure Cosmos DB, viene generato il seguente Bicep:

Attiva/Disattiva AzureAzure Cosmos DB Bicep.

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

param keyVaultName string

resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' existing = {
  name: keyVaultName
}

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'
  }
  kind: 'GlobalDocumentDB'
  tags: {
    'aspire-resource-name': 'cosmos'
  }
}

resource connectionString 'Microsoft.KeyVault/vaults/secrets@2023-07-01' = {
  name: 'connectionString'
  properties: {
    value: 'AccountEndpoint=${cosmos.properties.documentEndpoint};AccountKey=${cosmos.listKeys().primaryMasterKey}'
  }
  parent: keyVault
}

Il Bicep precedente è un modulo che fornisce un account AzureAzure Cosmos DB con le seguenti impostazioni predefinite:

kind: tipo di account Cosmos DB. Il valore predefinito è GlobalDocumentDB.
consistencyPolicy: politica di coerenza dell'account Cosmos DB. Il valore predefinito è Session.
locations: i percorsi per l'account Cosmos DB. Il valore predefinito è la posizione del gruppo di risorse.

Oltre all'account Cosmos DB, fornisce anche una risorsa Azure Key Vault. Viene usato per archiviare in modo sicuro la stringa di connessione dell'account Cosmos DB. Il Bicep generato è un punto di partenza e può essere personalizzato per soddisfare i requisiti specifici.

Personalizzare l'infrastruttura di provisioning

Tutte le risorse .NET AspireAzure sono sottoclassi del tipo di AzureProvisioningResource. Questo tipo consente la personalizzazione del Bicep generato fornendo un'API fluente per configurare le risorse Azure, utilizzando l'API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Ad esempio, è possibile configurare il kind, consistencyPolicy, locationse altro ancora. L'esempio seguente illustra come personalizzare la risorsa 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");
    });

Il codice precedente:

Concatena una chiamata all'API ConfigureInfrastructure:
- Il parametro infra è un'istanza del tipo AzureResourceInfrastructure.
- Le risorse provisionabili vengono recuperate chiamando il metodo GetProvisionableResources().
- Viene recuperato il singolo CosmosDBAccount.
- Il CosmosDBAccount.ConsistencyPolicy viene assegnato a un DefaultConsistencyLevel.Strong.
- Un tag viene aggiunto all'account Cosmos DB con una chiave di ExampleKey e un valore di Example value.

Sono disponibili molte altre opzioni di configurazione per personalizzare la risorsa AzureAzure Cosmos DB. Per altre informazioni, vedere Azure.Provisioning.CosmosDB. Per altre informazioni, vedere Azure. Personalizzazione del provisioning.

Connettersi a un account AzureAzure Cosmos DB esistente

Potresti avere un account AzureAzure Cosmos DB esistente a cui collegarti. Anziché rappresentare una nuova risorsa AzureAzure Cosmos DB, è possibile aggiungere una stringa di connessione all'host dell'app. Per aggiungere una connessione a un account esistente di AzureAzure Cosmos DB, utilizzare il metodo 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

Le stringhe di connessione vengono usate per rappresentare un'ampia gamma di informazioni di connessione, tra cui connessioni di database, broker di messaggi, URI degli endpoint e altri servizi. Nella nomenclatura .NET.NET Aspire, il termine "stringa di connessione" si usa per indicare qualsiasi tipo di informazioni di connessione.

La stringa di connessione viene configurata nella configurazione dell'host dell'app, in genere in segreti utente, nella sezione ConnectionStrings. L'host dell'app inserisce questa stringa di connessione come variabile di ambiente in tutte le risorse dipendenti, ad esempio:

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

La risorsa dipendente può accedere alla stringa di connessione inserita chiamando il metodo GetConnectionString e passando il nome della connessione come parametro, in questo caso "cosmos-db". L'API GetConnectionString è un'abbreviazione di IConfiguration.GetSection("ConnectionStrings")[name].

Aggiungi AzureAzure Cosmos DB risorsa di database

Per aggiungere una risorsa di database AzureAzure Cosmos DB, concatenare una chiamata a un IResourceBuilder<AzureCosmosDBResource> all'API AddDatabase:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Quando chiami AddDatabase, configura le risorse Cosmos DB per avere un database chiamato db. Il database viene creato nell'account Cosmos DB, che è rappresentato dal AzureCosmosDBResource che hai aggiunto in precedenza. Il database è un contenitore logico per raccolte e utenti. Per altre informazioni, vedere Database, contenitori ed elementi in AzureAzure Cosmos DB.

Nota

Quando si usa l'API AddDatabase per aggiungere un database a una risorsa AzureAzure Cosmos DB, se si esegue l'emulatore, il database non viene effettivamente creato nell'emulatore. Questa API è progettata per includere un database nel Bicep generato dall'infrastruttura di provisioning.

Aggiungere una risorsa emulatore AzureAzure Cosmos DB

Per aggiungere una risorsa dell'emulatore AzureAzure Cosmos DB, concatenare una chiamata a un IResourceBuilder<AzureCosmosDBResource> all'API RunAsEmulator:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Quando si chiama RunAsEmulator, configura le risorse Cosmos DB per l'esecuzione in locale tramite un emulatore. L'emulatore in questo caso è l'Emulatore AzureAzure Cosmos DB. L'emulatore Azure Cosmos DB offre un ambiente locale gratuito per testare le app Azure Cosmos DB ed è un perfetto compagno all'integrazione dell'hosting .NET AspireAzure. L'emulatore non è installato, ma è accessibile per .NET.NET Aspire come contenitore. Quando si aggiunge un contenitore all'host dell'applicazione, come mostrato nell'esempio precedente con l'immagine mcr.microsoft.com/cosmosdb/emulator, il contenitore viene creato e avviato all'avvio dell'host dell'applicazione. Per ulteriori informazioni, vedere il ciclo di vita delle risorse del contenitore.

Configurare il contenitore dell'emulatore Cosmos DB

Sono disponibili varie configurazioni per le risorse del contenitore, ad esempio è possibile configurare le porte del contenitore, le variabili di ambiente, la durata e altro ancora.

Configurare la porta del gateway del contenitore emulatore Cosmos DB

Per impostazione predefinita, il contenitore dell'emulatore Cosmos DB quando configurato da .NET Aspireespone gli endpoint seguenti:

Punto di Accesso	Porta contenitore	Porta host
`https`	8081	dinamico

La porta su cui è in ascolto è dinamica per impostazione predefinita. All'avvio del contenitore, la porta viene mappata a una porta casuale sulla macchina host. Per configurare la porta dell'endpoint, concatenare le chiamate al generatore di risorse del contenitore fornito dal metodo RunAsEmulator, come illustrato nell'esempio seguente:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Il codice precedente configura l'endpoint https esistente del contenitore dell'emulatore di Cosmos DB per l'ascolto sulla porta 8081. La porta del contenitore dell'emulatore Cosmos DB viene mappata alla porta host, come illustrato nella tabella seguente:

Nome del punto finale	Mappatura delle porte (`container:host`)
`https`	`8081:7777`

Configurare il contenitore dell'emulatore Cosmos DB con una durata a vita permanente

Per configurare il contenitore dell'emulatore Cosmos DB con una durata permanente, chiamare il metodo WithLifetime nella risorsa contenitore dell'emulatore Cosmos DB e passare 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...

Per ulteriori informazioni, vedere durata delle risorse del contenitore.

Configurare il contenitore emulatore Cosmos DB con volume dati

Per aggiungere un volume di dati alla risorsa dell'emulatore AzureAzure Cosmos DB, chiamare il metodo WithDataVolume nella risorsa dell'emulatore 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...

Il volume di dati viene usato per rendere persistenti i dati dell'emulatore Cosmos DB al di fuori del ciclo di vita del contenitore. Il volume di dati viene montato nel percorso /tmp/cosmos/appdata nel contenitore dell'emulatore Cosmos DB e quando non viene specificato un parametro name, viene generato il nome. L'emulatore ha la variabile di ambiente AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE impostata su true. Per ulteriori informazioni sui volumi di dati e sui motivi per cui sono preferiti rispetto ai montaggi di bind, consultare la documentazione: Volumi.

Configurare il numero di partizioni del contenitore dell'emulatore Cosmos DB

Per configurare il numero di partizioni del contenitore dell'emulatore Cosmos DB, chiamare il metodo 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...

Il codice precedente configura il contenitore dell'emulatore Cosmos DB in modo che abbia un numero di partizioni di 100. Si tratta di una sintassi abbreviata per impostare la variabile di ambiente AZURE_COSMOS_EMULATOR_PARTITION_COUNT.

Verifica dello stato di integrazione dell'hosting

L'integrazione dell'hosting Azure Cosmos DB aggiunge automaticamente un controllo integrità per la risorsa Cosmos DB. Il controllo di integrità verifica che il Cosmos DB sia in esecuzione e che sia possibile stabilire una connessione.

L'integrazione dell'hosting si basa sul pacchetto NuGet 📦 AspNetCore.HealthChecks.CosmosDb.

integrazione Client

Per iniziare a usare l'integrazione di .NET AspireAzure Cosmos DBclient, installare il 📦Aspire.Microsoft.Azure.Cosmos pacchetto NuGet nel progetto client-consuming, ovvero il progetto per l'applicazione che usa il Cosmos DBclient. L'integrazione Cosmos DBclient registra un'istanza di CosmosClient che è possibile usare per interagire con Cosmos DB.

.NET interfaccia a riga di comando
PackageReference

dotnet add package Aspire.Microsoft.Azure.Cosmos

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

Aggiungere Cosmos DBclient

Nel file Program.cs del progetto che consuma client, chiama il metodo di estensione AddAzureCosmosClient su qualsiasi IHostApplicationBuilder per registrare un CosmosClient da usare tramite il contenitore per l'inserimento delle dipendenze. Il metodo accetta un parametro del nome di connessione.

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

Suggerimento

Il parametro connectionName deve corrispondere al nome usato quando si aggiunge la risorsa Cosmos DB nel progetto host dell'app. In altre parole, quando si chiama AddAzureCosmosDB e si specifica un nome di cosmos-db lo stesso nome deve essere usato quando si chiama AddAzureCosmosClient. Per altre informazioni, vedere Aggiungere AzureAzure Cosmos DB risorsa.

È quindi possibile recuperare l'istanza di CosmosClient usando l'iniezione delle dipendenze. Ad esempio, per recuperare la connessione da un servizio di esempio:

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

Per altre informazioni sull'inserimento delle dipendenze, vedere .NET 'inserimento delle dipendenze.

Aggiungere Cosmos DBclient con chiave

In alcuni casi potrebbe essere necessario registrare più istanze di CosmosClient con nomi di connessione diversi. Per registrare i client Cosmos DB con chiave, chiamare il metodo AddKeyedAzureCosmosClient:

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

Importante

Quando si usano i servizi con chiave, è previsto che la risorsa Cosmos DB sia configurata con due database denominati, uno per il mainDb e uno per l'loggingDb.

È quindi possibile recuperare le istanze di CosmosClient mediante l'iniezione delle dipendenze. Ad esempio, per recuperare la connessione da un servizio di esempio:

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

Per altre informazioni sui servizi con chiave, vedere .NET inserimento delle dipendenze: Servizi con chiave.

Configurazione

L'integrazione .NET AspireAzure Cosmos DB offre più opzioni per configurare la connessione in base ai requisiti e alle convenzioni del progetto.

Usare una stringa di connessione

Quando si usa una stringa di connessione dalla sezione di configurazione ConnectionStrings, è possibile specificare il nome della stringa di connessione quando si chiama il metodo AddAzureCosmosClient:

builder.AddAzureCosmosClient("cosmos-db");

La stringa di connessione viene quindi recuperata dalla sezione di configurazione ConnectionStrings:

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

Per altre informazioni su come formattare questa stringa di connessione, vedere la documentazione di ConnectionString.

Usare i provider di configurazione

L'integrazione .NET AspireAzure Cosmos DB supporta Microsoft.Extensions.Configuration. Carica il MicrosoftAzureCosmosSettings dalla configurazione usando la chiave di Aspire:Microsoft:Azure:Cosmos. Il frammento di codice seguente è un esempio di un file appsettings.json che configura alcune delle opzioni:

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

Per lo schema completo Cosmos DBclient di integrazione JSON, vedere Aspire. Microsoft.Azure. Cosmos/ConfigurationSchema.json.

Usare delegati inline

Puoi anche passare il delegato Action<MicrosoftAzureCosmosSettings> configureSettings per configurare alcune o tutte le opzioni in linea, ad esempio per disabilitare il tracciamento dal codice:

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

È anche possibile configurare il Microsoft.Azure.Cosmos.CosmosClientOptions usando il parametro facoltativo Action<CosmosClientOptions> configureClientOptions del metodo AddAzureCosmosClient. Ad esempio, per impostare il suffisso dell'intestazione CosmosClientOptions.ApplicationName user-agent per tutte le richieste emesse da questo client:

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

Client verifiche di integrità dell'integrazione

Per impostazione predefinita, le integrazioni .NET.NET Aspire, abilitano i controlli di integrità per tutti i servizi. Per altre informazioni, vedere panoramica delle integrazioni .NET.NET Aspire.

Integrazione .NET AspireAzure Cosmos DB:

Aggiunge il controllo di integrità quando MicrosoftAzureCosmosSettings.DisableTracing è false, che tenta di connettersi al Cosmos DB.
Si integra con l'endpoint HTTP /health, che specifica che tutti i controlli di integrità registrati devono essere passati affinché l'app sia considerata pronta per accettare il traffico.

Osservabilità e telemetria

.NET .NET Aspire le integrazioni configurano automaticamente la registrazione, il tracciamento e le metriche, talvolta noti come i pilastri dell'osservabilità. Per altre informazioni sull'osservabilità e la telemetria dell'integrazione, vedere panoramica delle integrazioni .NET.NET Aspire. A seconda del servizio di backup, alcune integrazioni possono supportare solo alcune di queste funzionalità. Ad esempio, alcune integrazioni supportano la registrazione e la traccia, ma non le metriche. Le funzionalità di telemetria possono essere disabilitate anche usando le tecniche presentate nella sezione Configurazione .

Registrazione

L'integrazione .NET AspireAzure Cosmos DB usa le categorie di log seguenti:

Azure-Cosmos-Operation-Request-Diagnostics

Oltre a ottenere la diagnostica delle richieste Azure Cosmos DB per le richieste non riuscite, è possibile configurare le soglie di latenza per determinare quale diagnostica delle richieste riuscite Azure Cosmos DB verrà registrata correttamente. I valori predefiniti sono 100 ms per le operazioni punto e 500 ms per le operazioni non di punto.

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

Tracciatura

L'integrazione .NET AspireAzure Cosmos DB genererà le attività di traccia seguenti usando OpenTelemetry:

Azure.Cosmos.Operation

Il tracciamento AzureAzure Cosmos DB è attualmente in anteprima, pertanto è necessario impostare l'interruttore sperimentale per assicurarsi che le tracce vengano emesse.

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

Per altre informazioni, vedere AzureAzure Cosmos DB SDK osservabilità: attributi di traccia.

Metriche

L'integrazione .NET AspireAzure Cosmos DB attualmente non supporta le metriche per impostazione predefinita a causa di limitazioni con Azure SDK.

Vedere anche

Azure Cosmos DB
Panoramica integrazioni .NET.NET Aspire
Panoramica integrazioni .NET AspireAzure
.NET Aspire GitHub repository

Condividi tramite