Condividi tramite

integrazione .NET AspireAzure Cosmos DB

  • Articolo

Include: integrazione dell'hosting e integrazione di Client

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:

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

dotnet add package Aspire.Hosting.Azure.CosmosDB

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, consultare Approvisionnement locale: Configurazione.

Bicep di distribuzione 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 pubblichi la tua app, il Bicep generato viene fornito insieme al file manifesto. Quando si aggiunge una risorsa AzureAzure Cosmos DB, viene generato il seguente 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

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

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

Oltre all'account Cosmos DB, l'applicazione corrente viene aggiunta al ruolo Data Contributor per l'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:

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].

Aggiungere AzureAzure Cosmos DB risorse di database e contenitori

Per aggiungere una risorsa di database AzureAzure Cosmos DB, chiamare il metodo AddCosmosDatabase in un'istanza di IResourceBuilder<AzureCosmosDBResource>:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Quando si chiama AddCosmosDatabase, aggiunge un database denominato db alle risorse Cosmos DB e restituisce la risorsa di database appena creata. 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.

Un contenitore AzureAzure Cosmos DB è la posizione in cui vengono archiviati i dati. Quando si crea un contenitore, è necessario specificare una chiave di partizione.

Per aggiungere una risorsa contenitore AzureAzure Cosmos DB, chiamare il metodo AddContainer in un'istanza di 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...

Il contenitore viene creato nel database rappresentato dal AzureCosmosDBDatabaseResource aggiunto in precedenza.

Per altre informazioni, vedere Database, contenitori ed elementi in AzureAzure Cosmos DB.

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 è il AzureAzure Cosmos DB Emulatore. 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 dell'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 Cosmos DB esistente del contenitore dell'emulatore di https 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 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 di 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 "bind mounts", consultare la documentazione: VolumiDocker.

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.

Usare l'emulatore basato su Linux(anteprima)

La nuova generazione dell'emulatore AzureAzure Cosmos DB è interamente basata su Linuxed è disponibile come contenitore Docker. Supporta l'esecuzione su un'ampia gamma di processori e sistemi operativi.

Per usare la versione di anteprima dell'emulatore Cosmos DB, chiamare il metodo RunAsPreviewEmulator. Poiché questa funzionalità è in anteprima, è necessario acconsentire esplicitamente alla funzionalità di anteprima eliminando la diagnostica sperimentale ASPIRECOSMOSDB001.

L'emulatore di anteprima supporta anche l'esposizione di un endpoint "Esplora dati" che consente di visualizzare i dati archiviati nell'emulatore di Cosmos DB tramite un'interfaccia utente Web. Per abilitare Esplora dati, chiamare il metodo 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...

Il codice precedente configura il contenitore dell'emulatore basato su LinuxCosmos DB, con l'endpoint Data Explorer, da usare in fase di esecuzione.

Verifica dello stato di integrazione dell'hosting

L'integrazione dell'hosting Azure Cosmos DB aggiunge automaticamente una verifica dello stato di salute 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 utilizzare l'integrazione del client .NET AspireAzure Cosmos DB, installare il pacchetto NuGet 📦Aspire.Microsoft.Azure.Cosmos nel progetto client-consumer, cioè il progetto relativo all'applicazione che utilizza il client Cosmos DB. L'integrazione client Cosmos DB registra un'istanza di CosmosClient che è possibile usare per interagire con Cosmos DB.

dotnet add package Aspire.Microsoft.Azure.Cosmos

Aggiungere Cosmos DB client

Nel file Program.cs del progetto che usa il client, chiamare il metodo di estensione AddAzureCosmosClient su qualsiasi IHostApplicationBuilder per registrare un CosmosClient da usare tramite il contenitore di iniezione 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 di 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 un cliente con chiave Cosmos DB

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 dependency injection. 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 ulteriori informazioni sui servizi con chiave, vedere .NET iniezione di 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 fornitori di configurazione

L'integrazione .NET AspireAzure Cosmos DB supporta Microsoft.Extensions.Configuration. Carica il MicrosoftAzureCosmosSettings dalla configurazione utilizzando la chiave 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 di integrazione del client Cosmos DBJSON, vedere Aspire.Microsoft.Azure.Cosmos/ConfigurationSchema.json.

Usare delegati in linea

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 CosmosClientOptions.ApplicationName dell'intestazione dell'utente-agente per tutte le richieste effettuate da questo client:

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

Client verifiche di integrità dell'integrazione

L'integrazione client .NET AspireCosmos DB attualmente non implementa i controlli di integrità, anche se questo potrebbe cambiare nelle versioni future.

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)
                }
            };
        });

Tracciamento

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