Sdílet prostřednictvím

integrace .NET AspireCosmos DBEntity Framework Core

  • Článek

zahrnuje:integrace hostování a Client integrace

Azure Cosmos DB je plně spravovaná databázová služba NoSQL pro moderní vývoj aplikací. Integrace .NET AspireCosmos DBEntity Framework Core umožňuje připojit se k existujícím instancím Cosmos DB nebo vytvářet nové instance z .NET pomocí emulátoru Azure Cosmos DB.

Integrace hostování

.NET .NET Aspire Azure Cosmos DB integrační hostovací modely modelují různé zdroje Cosmos DB jako následující typy:

Pokud chcete získat přístup k těmto typům a rozhraním API pro jejich vyjádření, přidejte 📦Aspire.Hosting.Azure.CosmosDB balíček NuGet v projektu hostování aplikace .

dotnet add package Aspire.Hosting.Azure.CosmosDB

Další informace najdete v tématu dotnet add package nebo Správa závislostí balíčků v .NET aplikacích.

Přidejte prostředek AzureAzure Cosmos DB

V projektu hostitele aplikace zavolejte AddAzureCosmosDB, abyste přidali a vrátili tvůrce prostředků AzureAzure Cosmos DB.

var builder = DistributedApplication.CreateBuilder(args);

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

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

Když do hostitele aplikace přidáte AzureCosmosDBResource, zveřejní další užitečná rozhraní API pro přidání databází a kontejnerů. Jinými slovy, musíte přidat AzureCosmosDBResource před přidáním některého z dalších Cosmos DB zdrojů.

Důležitý

Při volání AddAzureCosmosDBse automaticky volá AddAzureProvisioning– což dynamicky přidává podporu pro generování prostředků Azure při startu aplikace. Aplikace musí nakonfigurovat příslušné předplatné a umístění. Pro získání více informací nahlédněte do části Místní zřizování: Konfigurace.

Vygenerované zřizování Bicep

Pokud s Bicep začínáte, jedná se o jazyk specifický pro doménu pro definování Azure prostředků. Se .NET.NET Aspirenemusíte psát Bicep ručně, místo toho provisioning API generuje Bicep za vás. Když publikujete svou aplikaci, vygenerovaný Bicep je zahrnut společně se souborem manifestu. Když přidáte prostředek AzureAzure Cosmos DB, vygeneruje se následující Bicep:


přepnout 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
}

Předchozí modul Bicep zřizuje účet AzureAzure Cosmos DB s následujícími výchozími nastaveními:

  • kind: Druh účtu Cosmos DB. Výchozí hodnota je GlobalDocumentDB.
  • consistencyPolicy: Zásady konzistence účtu Cosmos DB. Výchozí hodnota je Session.
  • locations: Umístění účtu Cosmos DB. Výchozí hodnota je umístění skupiny prostředků.

Kromě účtu Cosmos DB poskytne také prostředek Azure Key Vault. Slouží k bezpečnému uložení připojovacího řetězce účtu Cosmos DB. Vygenerovaný Bicep je výchozím bodem a můžete ho přizpůsobit tak, aby splňoval vaše konkrétní požadavky.

Přizpůsobení infrastruktury zřizování

Všechny prostředky .NET AspireAzure jsou podtřídy typu AzureProvisioningResource. Tento typ umožňuje přizpůsobení vygenerovaného Bicepu poskytnutím fluentního API pro konfiguraci prostředků Azure pomocí API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Můžete například nakonfigurovat kind, consistencyPolicy, locationsatd. Následující příklad ukazuje, jak přizpůsobit prostředek 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");
    });

Předchozí kód:

Pro přizpůsobení prostředku AzureAzure Cosmos DB je k dispozici mnoho dalších možností konfigurace. Další informace najdete v tématu Azure.Provisioning.CosmosDB. Další informace najdete v tématu Azure. Přizpůsobení zřizování.

Připojení k existujícímu účtu AzureAzure Cosmos DB

Možná máte existující účet AzureAzure Cosmos DB, ke kterému se chcete připojit. Místo toho, abyste představovali nový prostředek AzureAzure Cosmos DB, můžete k hostiteli aplikace přidat připojovací řetězec. Pokud chcete přidat připojení k existujícímu účtu AzureAzure Cosmos DB, zavolejte metodu 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...

Poznámka

Připojovací řetězce se používají k reprezentaci široké škály informací o připojení, včetně databázových připojení, zprostředkovatelů zpráv, identifikátorů URI koncových bodů a dalších služeb. V .NET.NET Aspire terminologii se výraz "připojovací řetězec" používá k reprezentaci jakéhokoli druhu informací o připojení.

Připojovací řetězec se konfiguruje v konfiguraci hostitele aplikace, obvykle v části Tajné kódy uživatelův části ConnectionStrings. Hostitel aplikace vloží tento připojovací řetězec jako proměnnou prostředí do všech závislých prostředků, například:

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

Závislý prostředek má přístup k tomuto vloženému připojovacímu řetězci voláním metody GetConnectionString a předáním názvu připojení jako parametru, v tomto případě "cosmos-db". Rozhraní API GetConnectionString je zkratka pro IConfiguration.GetSection("ConnectionStrings")[name].

Přidání prostředku databáze AzureAzure Cosmos DB

Pokud chcete přidat prostředek databáze AzureAzure Cosmos DB, spojte volání na IResourceBuilder<AzureCosmosDBResource> s rozhraním API AddDatabase.

var builder = DistributedApplication.CreateBuilder(args);

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

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

Při volání AddDatabasenakonfiguruje prostředky Cosmos DB tak, aby měly databázi s názvem db. Databáze se vytvoří v účtu Cosmos DB, který je reprezentován AzureCosmosDBResource, přidaným dříve. Databáze je logický kontejner pro kolekce a uživatele. Další informace naleznete v tématu Databáze, kontejnery a položky v AzureAzure Cosmos DB.

Poznámka

Pokud k přidání databáze do prostředku AddDatabaseAzure používáte rozhraní API Azure Cosmos DB, databáze se ve skutečnosti nevytvořila v emulátoru. Toto rozhraní API je určeno k zahrnutí databáze do Bicep generovaného zřizovací infrastrukturou.

Přidejte prostředek emulátoru AzureAzure Cosmos DB

Pokud chcete přidat prostředek emulátoru AzureAzure Cosmos DB, zřetězte volání IResourceBuilder<AzureCosmosDBResource> do rozhraní API RunAsEmulator:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Při volání RunAsEmulatornakonfiguruje prostředky Cosmos DB tak, aby se spouštěly místně pomocí emulátoru. V tomto případě je emulátor AzureAzure Cosmos DB emulátor. Emulátor Azure Cosmos DB poskytuje bezplatné místní prostředí pro testování vašich Azure Cosmos DB aplikací a je to dokonalý doplněk k integraci .NET AspireAzure hostování. Emulátor není nainstalovaný, ale je přístupný pro .NET.NET Aspire jako kontejner. Když do hostitele aplikace přidáte kontejner, jak je znázorněno v předchozím příkladu s imagí mcr.microsoft.com/cosmosdb/emulator, vytvoří a spustí kontejner při spuštění hostitele aplikace. Další informace najdete v tématu životní cyklus prostředků kontejneru.

Konfigurace kontejneru emulátoru Cosmos DB

Pro prostředky kontejneru jsou k dispozici různé konfigurace, například můžete nakonfigurovat porty kontejneru, proměnné prostředí, životnostatd.

Konfigurace portu brány kontejneru emulátoru Cosmos DB

Ve výchozím nastavení kontejner emulátoru Cosmos DB při konfiguraci .NET Aspirezveřejňuje následující koncové body:

Koncový bod Kontejnerový přístav Port hostitele
https 8081 dynamický

Port, na který naslouchá, je ve výchozím nastavení dynamický. Při spuštění kontejneru se port mapuje na náhodný port na hostitelském počítači. Pokud chcete nakonfigurovat port koncového bodu, zřetězte volání tvůrce prostředků kontejneru, který poskytuje metoda RunAsEmulator, jak je znázorněno v následujícím příkladu:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Kód uvedený výše nakonfiguruje kontejner emulátoru Cosmos DB tak, aby jeho existující koncový bod https naslouchal na portu 8081. Port kontejneru emulátoru Cosmos DB se mapuje na port hostitele, jak je znázorněno v následující tabulce:

Název koncového bodu Mapování portů (container:host)
https 8081:7777
Konfigurace kontejneru emulátoru Cosmos DB s trvalou životností

Pokud chcete nakonfigurovat kontejner emulátoru Cosmos DB s trvalou životností, zavolejte metodu WithLifetime v prostředku kontejneru emulátoru Cosmos DB a předejte 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...

Další informace najdete v části Doba života prostředků kontejneru.

Konfigurujte kontejner emulátoru Cosmos DB s datovým svazkem

Pokud chcete přidat datový svazek do prostředku emulátoru AzureAzure Cosmos DB, zavolejte metodu WithDataVolume prostředku emulátoru 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...

Datový svazek slouží k zachování dat emulátoru Cosmos DB mimo životní cyklus kontejneru. Datový svazek se připojí k cestě /tmp/cosmos/appdata v kontejneru emulátoru Cosmos DB a pokud není zadaný parametr name, vygeneruje se název. Emulátor má svou AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE proměnnou prostředí nastavenou na true. Další informace o datových svazcích a podrobnosti o tom, proč jsou upřednostňovány před připojovacími body, najdete v dokumentaci Docker: Svazky.

Konfigurace počtu oddílů kontejneru emulátoru Cosmos DB

Pokud chcete nakonfigurovat počet oddílů kontejneru emulátoru Cosmos DB, zavolejte metodu 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...

Předchozí kód nakonfiguruje kontejner emulátoru Cosmos DB tak, aby měl počet oddílů 100. Toto je zkratka pro nastavení proměnné prostředí AZURE_COSMOS_EMULATOR_PARTITION_COUNT.

Hostování kontrol stavu integrace

Integrace hostování Azure Cosmos DB automaticky přidá kontrolu stavu prostředku Cosmos DB. Kontrola stavu ověřuje, že je Cosmos DB spuštěn a že se k němu lze připojit.

Integrace hostování spoléhá na 📦 NuGet balíček AspNetCore.HealthChecks.CosmosDb.

integrace Client

Pokud chcete začít s integrací .NET Aspire Microsoft Entity Framework CoreCosmos DB, nainstalujte 📦Aspire.Microsoft.EntityFrameworkCore.Cosmos balíček NuGet v projektu klienta, tj. v projektu pro aplikaci, která využívá klienta Microsoft Entity Framework CoreCosmos DB.

dotnet add package Aspire.Microsoft.EntityFrameworkCore.Cosmos

Přidejte kontext Cosmos DB

V souboru Program.cs projektu, který využívá klienta, zavolejte metodu rozšíření AddCosmosDbContext, která zaregistruje System.Data.Entity.DbContext pro použití prostřednictvím kontejneru injektáže závislostí. Metoda přebírá parametr názvu připojení.

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

Spropitné

Parametr connectionName se musí shodovat s názvem použitým při přidávání prostředku Cosmos DB do hostitelského projektu aplikace. Jinými slovy, když voláte AddAzureCosmosDB a zadáte název cosmosdb, stejné jméno by mělo být použito při volání AddCosmosDbContext. Další informace najdete v tématu Přidání AzureAzure Cosmos DB prostředků.

Potom můžete načíst instanci DbContext pomocí injektáže závislostí. Pokud chcete například načíst klienta ze služby:

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

Další informace o použití Entity Framework Core s Azure Cosmos DBnaleznete v tématu Příklady pro Azure Cosmos DB pro sadu NoSQL SDK pro .NET.

Konfigurace

Integrace .NET Aspire Microsoft Entity Framework CoreCosmos DB poskytuje několik možností konfigurace připojení Azure Cosmos DB na základě požadavků a konvencí projektu.

Použijte připojovací řetězec

Při použití připojovacího řetězce z oddílu konfigurace ConnectionStrings můžete při volání builder.AddCosmosDbContextzadat název připojovacího řetězce:

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

A potom se připojovací řetězec načte z oddílu konfigurace ConnectionStrings.

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

Další informace naleznete v dokumentaci ConnectionString.

Použití zprostředkovatelů konfigurace

Integrace .NET Aspire Microsoft Entity Framework CoreCosmos DB podporuje Microsoft.Extensions.Configuration. Načte EntityFrameworkCoreCosmosSettings z konfiguračních souborů, jako je appsettings.json. Příklad _appsettings.json, který konfiguruje některé z možností:

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

Kompletní schéma integrace klienta Cosmos DBJSON najdete v tématu Aspire.Microsoft.EntityFrameworkCore.Cosmos/ConfigurationSchema.json.

Použití vložených delegátů

Můžete také předat delegáta Action<EntityFrameworkCoreCosmosSettings> configureSettings a nastavit některé nebo všechny možnosti EntityFrameworkCoreCosmosSettings přímo, například zakázat sledování z kódu.

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

Client kontroly stavu integrace

Integrace .NET.NET Aspire ve výchozím nastavení umožňují kontroly stavu pro všechny služby. Pro více informací viz .NET.NET Aspire přehled integrací.

Integrace .NET Aspire Microsoft Entity Framework CoreCosmos DB v současné době neimplementuje kontroly stavu, i když se to může v budoucích verzích změnit.

Pozorovatelnost a telemetrie

.NET .NET Aspire integrace automaticky nastaví konfigurace pro protokolování, trasování a metriky, které se někdy označují jako pilíře pozorovatelnosti. Další informace o pozorovatelnosti a telemetrii integrace najdete v přehledu integrace .NET.NET Aspire. V závislosti na zálohovací službě můžou některé integrace podporovat pouze některé z těchto funkcí. Například některé integrace podporují protokolování a trasování, ale ne metriky. Funkce telemetrie je také možné zakázat pomocí technik uvedených v části Konfigurace.

Protokolování

Integrace .NET Aspire Microsoft Entity Framework CoreCosmos DB používá následující kategorie protokolů:

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

Trasování

Integrace .NET Aspire Microsoft Entity Framework CoreCosmos DB bude generovat následující aktivity trasování pomocí OpenTelemetry:

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

Metriky

Integrace .NET Aspire Microsoft Entity Framework CoreCosmos DB v současné době podporuje následující metriky:

  • 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

Viz také