Condividi tramite

integrazione di .NET AspireCosmos DBEntity Framework Core

  • Articolo

includono:integrazione dell'hosting e integrazioneClient

Azure Cosmos DB è un servizio di database NoSQL completamente gestito per lo sviluppo di app moderne. L'integrazione .NET AspireCosmos DBEntity Framework Core 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 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 dell'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 un AzureCosmosDBResource prima di aggiungere qualsiasi altra risorsa Cosmos DB.

Importante

Quando chiami AddAzureCosmosDB, chiama implicitamente AddAzureProvisioning, che aggiunge il supporto per la generazione dinamica delle risorse Azure durante l'avvio dell'app. L'app deve configurare l'abbonamento e la posizione appropriati. Per ulteriori informazioni, vedere Configurazione locale: Configurazione.

Bicep di provisioning generato

Se non hai familiarità con Bicep, si tratta di un linguaggio del dominio specifico per la definizione delle risorse Azure. Con .NET.NET Aspirenon è necessario scrivere Bicep a mano, ma le API di provisioning generano Bicep automaticamente. Quando pubblichi la tua app, il Bicep generato viene fornito insieme al file di manifesto. Quando si aggiunge una risorsa AzureAzure Cosmos DB, viene generato il Bicep seguente:


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: 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, esegue anche il provisioning di 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 permette la personalizzazione del Bicep generato fornendo un'API fluente per configurare le risorse Azure usando 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 ulteriori informazioni, consulta Azure. Personalizzazione del provisioning.

Accedi a un account AzureAzure Cosmos DB esistente

Potresti avere un account AzureAzure Cosmos DB esistente a cui desideri connetterti. Anziché rappresentare una nuova risorsa AzureAzure Cosmos DB, è possibile aggiungere una stringa di connessione all'host dell'app. Per aggiungere un collegamento a un account di AzureAzure Cosmos DB esistente, chiamare 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 endpoint e altri servizi. Nella nomenclatura .NET.NET Aspire, il termine "stringa di connessione" viene usata per rappresentare 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 è una forma abbreviata di IConfiguration.GetSection("ConnectionStrings")[name].

Aggiungere la risorsa di database AzureAzure Cosmos DB

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 si chiama AddDatabase, configura le risorse Cosmos DB per avere un database denominato db. Il database viene creato nell'account Cosmos DB 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 la 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 container all'host dell'applicazione, come illustrato nell'esempio precedente con l'immagine mcr.microsoft.com/cosmosdb/emulator, viene creato e avviato il container all'avvio dell'host dell'applicazione. Per altre informazioni, vedere 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.

Configura la porta del gateway per il contenitore dell'emulatore Cosmos DB

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

Punto terminale 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 random sulla macchina host. Per configurare la porta dell'endpoint, effettuare chiamate concatenate utilizzando il costruttore 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 https per ascoltare sulla porta 8081. La porta del contenitore dell'emulatore Cosmos DB viene mappata alla porta host, come illustrato nella tabella seguente:

Nome endpoint Mappatura delle porte (container:host)
https 8081:7777
Configurare il contenitore dell'emulatore Cosmos DB con 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 dei contenitori.

Configurare il contenitore dell'emulatore Cosmos DB con un 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, se un parametro name non viene fornito, il nome viene generato. 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, consulta la documentazione Docker: 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.

Hosting dei controlli di integrità dell'integrazione

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 usare l'integrazione di Microsoft Entity Framework CoreCosmos DB.NET Aspire, installare il 📦Aspire.Microsoft.EntityFrameworkCore.Cosmos pacchetto NuGet nel progetto cliente utilizzatore, ovvero il progetto per l'applicazione che usa il client Microsoft Entity Framework CoreCosmos DB.

dotnet add package Aspire.Microsoft.EntityFrameworkCore.Cosmos

Aggiungere Cosmos DB contesto

Nel file Program.cs del progetto che usa il client chiamare il metodo di estensione AddCosmosDbContext per registrare un System.Data.Entity.DbContext da usare tramite il contenitore di inserimento delle dipendenze. Il metodo accetta un parametro del nome di connessione.

builder.AddCosmosDbContext<MyDbContext>("cosmosdb");

Mancia

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 cosmosdb lo stesso nome deve essere usato quando si chiama AddCosmosDbContext. Per altre informazioni, vedere Aggiungere AzureAzure Cosmos DB risorsa.

È quindi possibile recuperare l'istanza di DbContext usando l'iniezione delle dipendenze. Ad esempio, per recuperare il client da un servizio:

public class ExampleService(MyDbContext context)
{
    // Use context...
}

Per ulteriori informazioni sull'uso di Entity Framework Core con Azure Cosmos DB, vedere gli esempi di per Azure Cosmos DB nel SDK NoSQL per .NET.

Configurazione

L'integrazione .NET Aspire di Microsoft Entity Framework CoreCosmos DB offre più opzioni per configurare la connessione Azure Cosmos DB 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 builder.AddCosmosDbContext:

builder.AddCosmosDbContext<MyDbContext>("CosmosConnection");

La stringa di connessione verrà quindi recuperata dalla sezione di configurazione ConnectionStrings:

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

Per ulteriori informazioni, consultare la documentazione ConnectionString.

Usare i fornitori di configurazione

L'integrazione di Microsoft .NET AspireEntity Framework CoreCosmos DB supporta Microsoft.Extensions.Configuration. Carica il EntityFrameworkCoreCosmosSettings dai file di configurazione, ad esempio appsettings.json. Esempio _appsettings.json che configura alcune delle opzioni:

{
  "Aspire": {
    "Microsoft": {
      "EntityFrameworkCore": {
        "Cosmos": {
          "DisableTracing": true
        }
      }
    }
  }
}

Per lo schema Cosmos DB di integrazione del client JSON completo, consultare Aspire.Microsoft.EntityFrameworkCore.Cosmos/ConfigurationSchema.json.

Usare delegati inline

È anche possibile passare il delegato Action<EntityFrameworkCoreCosmosSettings> configureSettings per configurare alcune o tutte le opzioni EntityFrameworkCoreCosmosSettings direttamente in linea, ad esempio per disabilitare il monitoraggio dal codice:

builder.AddCosmosDbContext<MyDbContext>(
    "cosmosdb",
    settings => settings.DisableTracing = true);

Client controlli 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.

L'integrazione .NET Aspire Microsoft Entity Framework CoreCosmos DB attualmente non implementa i controlli della salute, anche se questo potrebbe variare nelle versioni future.

Osservabilità e telemetria

.NET .NET Aspire le integrazioni configurano automaticamente le impostazioni di registrazione, tracciamento e metriche, talvolta note 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 di .NET Aspire Microsoft Entity Framework CoreCosmos DB usa le categorie di log seguenti:

  • Azure-Cosmos-Operation-Request-Diagnostics
  • Microsoft.EntityFrameworkCore.ChangeTracking
  • Microsoft.EntityFrameworkCore.Database.Command
  • Microsoft.EntityFrameworkCore.Infrastructure
  • Microsoft.EntityFrameworkCore.Query

Tracciamento

L'integrazione di Microsoft .NET AspireEntity Framework CoreCosmos DB genererà le attività di traccia seguenti usando OpenTelemetry:

  • Azure.Cosmos.Operation
  • OpenTelemetry.Instrumentation.EntityFrameworkCore

Metriche

L'integrazione .NET Aspire Microsoft Entity Framework CoreCosmos DB supporta attualmente le metriche seguenti:

  • Microsoft.EntityFrameworkCore
    • ec_Microsoft_EntityFrameworkCore_active_db_contexts
    • ec_Microsoft_EntityFrameworkCore_total_queries
    • ec_Microsoft_EntityFrameworkCore_queries_per_second
    • ec_Microsoft_EntityFrameworkCore_total_save_changes
    • ec_Microsoft_EntityFrameworkCore_save_changes_per_second
    • ec_Microsoft_EntityFrameworkCore_compiled_query_cache_hit_rate
    • ec_Microsoft_Entity_total_execution_strategy_operation_failures
    • ec_Microsoft_E_execution_strategy_operation_failures_per_second
    • ec_Microsoft_EntityFramew_total_optimistic_concurrency_failures
    • ec_Microsoft_EntityF_optimistic_concurrency_failures_per_second

Vedere anche