integrace .NET AspireCosmos DBEntity Framework Core

Článek
03/08/2025

zahrnuje: integraci hostování a Client integraci

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:

AzureCosmosDBResource: Představuje zdroj AzureAzure Cosmos DB.
AzureCosmosDBEmulatorResource: Představuje prostředek emulátoru AzureAzure Cosmos DB.

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

.NET rozhraní příkazového řádku
PackageReference

dotnet add package Aspire.Hosting.Azure.CosmosDB

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

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 vaší 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 doménově specifický jazyk pro definování Azure prostředků. S .NET.NET Aspire nemusíte psát Bicep ručně, místo toho za vás generují Bicep provisioning API. 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:

@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

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 přidá také aktuální aplikaci do role Data Contributor pro účet 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 pro zřizování zdrojů

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:

Zřetězí volání rozhraní API ConfigureInfrastructure:
- Parametr infra je instance typu AzureResourceInfrastructure.
- Zdroje určené k zajištění se načtou voláním metody GetProvisionableResources().
- Načte se jeden CosmosDBAccount.
- CosmosDBAccount.ConsistencyPolicy je přiřazen k DefaultConsistencyLevel.Strong.
- Značka se přidá do účtu Cosmos DB s klíčem ExampleKey a hodnotou Example value.

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 naleznete v AzurePř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. Namísto vytváření nového prostředku 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řidejte AzureAzure Cosmos DB prostředky databáze a kontejneru

Pokud chcete přidat prostředek databáze AzureAzure Cosmos DB, zavolejte metodu AddCosmosDatabase na instanci IResourceBuilder<AzureCosmosDBResource>.

var builder = DistributedApplication.CreateBuilder(args);

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

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

Při volání AddCosmosDatabasepřidá do prostředků db databázi s názvem Cosmos DB a vrátí nově vytvořený databázový prostředek. 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.

V kontejneru AzureAzure Cosmos DB jsou uložená data. Při vytváření kontejneru je potřeba zadat klíč oddílu.

Pokud chcete přidat prostředek kontejneru AzureAzure Cosmos DB, zavolejte metodu AddContainer na instanci 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...

Kontejner se vytvoří v databázi, která je reprezentovaná AzureCosmosDBDatabaseResource, kterou jste přidali dříve.

Další informace naleznete v tématu Databáze, kontejnery a položky v AzureAzure Cosmos DB.

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

Chcete-li přidat prostředek emulátoru AzureAzure Cosmos DB, zřetězte volání IResourceBuilder<AzureCosmosDBResource> k 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 Emulator. 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 části životní cyklus zdrojů 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	Hostitelský port
`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 Životní cyklus prostředků kontejneru.

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

Použijte emulátor založený na Linux(náhled)

Nástupce emulátoru AzureAzure Cosmos DB je plně založen na Linux a je k dispozici jako kontejner Docker. Podporuje spouštění na široké škále procesorů a operačních systémů.

Pokud chcete použít verzi Preview emulátoru Cosmos DB, zavolejte metodu RunAsPreviewEmulator. Vzhledem k tomu, že je tato funkce ve verzi Preview, musíte explicitně povolit tuto verzi potlačením experimentální diagnostiky ASPIRECOSMOSDB001.

Emulátor verze Preview také podporuje zpřístupnění koncového bodu „Průzkumník dat“, který umožňuje zobrazit data uložená v emulátoru Cosmos DB prostřednictvím webovým uživatelským rozhraním. Chcete-li povolit Průzkumníka dat, zavolejte metodu 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...

Předchozí kód konfiguruje kontejner emulátoru na bázi Linux s koncovým bodem Průzkumníka dat, který bude použit při běhu.

Hostování kontrol stavu integrace

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

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

Client integrace

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.

.NET rozhraní příkazového řádku
PackageReference

dotnet add package Aspire.Microsoft.EntityFrameworkCore.Cosmos

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

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", "databaseName");

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í injekce závislostí. 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 konfiguračního oddílu 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 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 vygeneruje následující aktivity tracová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

Sdílet prostřednictvím