.NET Aspire-Cosmos DB-Entity Framework Core-Integration

Artikel
01/09/2025

umfasst:Hosting-Integration und Client-Integration

Azure Cosmos DB ist ein vollständig verwalteter NoSQL-Datenbankdienst für die moderne App-Entwicklung. Mit der .NET AspireCosmos DBEntity Framework Core-Integration können Sie eine Verbindung mit vorhandenen Cosmos DB Instanzen herstellen oder neue Instanzen aus .NET mit dem Azure Cosmos DB Emulator erstellen.

Hosting-Integration

Die .NET.NET AspireAzure Cosmos DB Host-Integrationsmodelle modellieren die verschiedenen Cosmos DB Ressourcen als folgende Typen:

AzureCosmosDBResource: Stellt eine AzureAzure Cosmos DB Ressource dar.
AzureCosmosDBEmulatorResource: Stellt eine AzureAzure Cosmos DB Emulator-Ressource dar.

Um auf diese Typen und APIs zuzugreifen, fügen Sie das NuGet-Paket 📦Aspire.Hosting.Azure.CosmosDB zum App-Host Projekt hinzu.

.NET CLI
PaketReferenz

dotnet add package Aspire.Hosting.Azure.CosmosDB

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

Weitere Informationen finden Sie unter dotnet add package oder Verwalten von Paketabhängigkeiten in .NET-Anwendungen.

Hinzufügen der Ressource AzureAzure Cosmos DB

Rufen Sie in Ihrem App-Hostprojekt AddAzureCosmosDB auf, um einen AzureAzure Cosmos DB Ressourcen-Generator hinzuzufügen und zurückzugeben.

var builder = DistributedApplication.CreateBuilder(args);

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

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

Wenn Sie dem App-Host eine AzureCosmosDBResource hinzufügen, werden andere nützliche APIs zum Hinzufügen von Datenbanken und Containern verfügbar gemacht. Mit anderen Worten, Sie müssen eine AzureCosmosDBResource hinzufügen, bevor Sie eine der anderen Cosmos DB-Ressourcen hinzufügen.

Wichtig

Wenn Sie AddAzureCosmosDBaufrufen, wird implizit AddAzureProvisioningaufgerufen, wodurch Azure Ressourcen während des Anwendungsstarts dynamisch generiert werden. Die App muss das entsprechende Abonnement und den entsprechenden Standort konfigurieren. Weitere Informationen finden Sie unter lokale Bereitstellung: Konfiguration.

Generiertes Bereitstellungs-Bicep

Wenn Sie neu bei Bicepsind, handelt es sich um eine domänenspezifische Sprache zum Definieren von Azure Ressourcen. Mit .NET.NET Aspiremüssen Sie Bicep nicht manuell schreiben, sondern die Bereitstellungs-APIs generieren Bicep für Sie. Wenn Sie Ihre App veröffentlichen, wird Bicep zusammen mit der Manifestdatei ausgegeben. Wenn Sie eine AzureAzure Cosmos DB Ressource hinzufügen, wird das folgende Bicep generiert:

Umschalten 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
}

Das vorherige Bicep-Modul ist ein Modul, das ein AzureAzure Cosmos DB Konto mit den folgenden Standardwerten bereitstellt:

kind: Die Art des Cosmos DB Kontos. Der Standardwert ist GlobalDocumentDB.
consistencyPolicy: Die Konsistenzrichtlinie des Cosmos DB Kontos. Der Standardwert ist Session.
locations: Die Standorte für das Cosmos DB Konto. Die Standardeinstellung ist der Speicherort der Ressourcengruppe.

Zusätzlich zum Cosmos DB-Konto stellt das System auch eine Azure Key Vault-Ressource bereit. Dies dient dazu, die Verbindungszeichenfolge des Cosmos DB-Kontos sicher zu speichern. Das generierte Bicep-Modul ist ein Ausgangspunkt und kann an Ihre spezifischen Anforderungen angepasst werden.

Anpassen der Bereitstellungsinfrastruktur

Alle .NET AspireAzure Ressourcen sind Unterklassen des AzureProvisioningResource Typs. Dieser Typ ermöglicht die Anpassung der generierten Bicep durch Bereitstellen einer Fluent-API zum Konfigurieren der Azure-Ressourcen mithilfe der ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>)-API. Sie können z. B. die kind, consistencyPolicy, locationsund vieles mehr konfigurieren. Im folgenden Beispiel wird veranschaulicht, wie die AzureAzure Cosmos DB Ressource angepasst wird:

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

Der vorangehende Code:

Verkettet einen Aufruf der ConfigureInfrastructure-API:
- Der infra-Parameter ist eine Instanz des typs AzureResourceInfrastructure.
- Die bereitstellbaren Ressourcen werden durch Aufrufen der GetProvisionableResources()-Methode abgerufen.
- Die einzelne CosmosDBAccount wird abgerufen.
- Der CosmosDBAccount.ConsistencyPolicy wird einem DefaultConsistencyLevel.Strongzugewiesen.
- Dem Cosmos DB Konto wird ein Tag mit einem Schlüssel von ExampleKey und einem Wert von Example valuehinzugefügt.

Es stehen viele weitere Konfigurationsoptionen zum Anpassen der AzureAzure Cosmos DB Ressource zur Verfügung. Weitere Informationen finden Sie unter Azure.Provisioning.CosmosDB. Weitere Informationen finden Sie unter Azure. Bereitstellungsanpassung.

Verbinden mit einem vorhandenen AzureAzure Cosmos DB-Konto

Möglicherweise verfügen Sie über ein vorhandenes AzureAzure Cosmos DB Konto, mit dem Sie eine Verbindung herstellen möchten. Anstatt eine neue Ressource AzureAzure Cosmos DB zu repräsentieren, können Sie dem App-Host eine Verbindungszeichenfolge hinzufügen. Um eine Verbindung zu einem vorhandenen AzureAzure Cosmos DB Konto hinzuzufügen, rufen Sie die AddConnectionString-Methode auf.

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

Anmerkung

Verbindungszeichenfolgen werden verwendet, um eine vielzahl von Verbindungsinformationen darzustellen, einschließlich Datenbankverbindungen, Nachrichtenbroker, Endpunkt-URIs und anderen Diensten. In .NET.NET Aspire Nomenklatur wird der Begriff "Verbindungszeichenfolge" verwendet, um jede Art von Verbindungsinformationen darzustellen.

Die Verbindungszeichenfolge ist in der Konfiguration des App-Hosts definiert, typischerweise unter Benutzergeheimnisse, im Abschnitt ConnectionStrings. Der App-Host fügt diese Verbindungszeichenfolge als Umgebungsvariable in alle abhängigen Ressourcen ein, z. B.:

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

Die abhängige Ressource kann auf die eingefügte Verbindungszeichenfolge zugreifen, indem sie die GetConnectionString Methode aufruft und den Verbindungsnamen als Parameter übergibt, in diesem Fall "cosmos-db". Die GetConnectionString-API ist kurz für IConfiguration.GetSection("ConnectionStrings")[name].

Datenbankressource AzureAzure Cosmos DB hinzufügen

Um eine AzureAzure Cosmos DB-Datenbankressource hinzuzufügen, verketten Sie einen Aufruf eines IResourceBuilder<AzureCosmosDBResource> der AddDatabase-API:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Wenn Sie AddDatabaseaufrufen, werden die Cosmos DB-Ressourcen so konfiguriert, dass eine Datenbank mit dem Namen dberstellt wird. Die Datenbank wird im Konto Cosmos DB erstellt, das durch AzureCosmosDBResource dargestellt wird, die Sie zuvor hinzugefügt haben. Die Datenbank ist ein logischer Container für Sammlungen und Benutzer. Weitere Informationen finden Sie unter Datenbanken, Container und Elemente in AzureAzure Cosmos DB.

Anmerkung

Wenn Sie die AddDatabase-API verwenden, um eine Datenbank zu einer AzureAzure Cosmos DB-Ressource hinzuzufügen, und dabei den Emulator ausführen, wird die Datenbank tatsächlich nicht im Emulator erstellt. Diese API soll eine Datenbank in die durch die Bereitstellungsinfrastruktur generierte Bicep einschließen.

Hinzufügen AzureAzure Cosmos DB Emulatorressource

Um eine AzureAzure Cosmos DB Emulatorressource hinzuzufügen, verketten Sie einen Aufruf eines IResourceBuilder<AzureCosmosDBResource> an die RunAsEmulator-API:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Wenn Sie RunAsEmulatoraufrufen, werden Ihre Cosmos DB-Ressourcen so konfiguriert, dass sie lokal mithilfe eines Emulators ausgeführt werden. Der Emulator in diesem Fall ist der AzureAzure Cosmos DB Emulator. Der Azure Cosmos DB Emulator bietet eine kostenlose lokale Umgebung zum Testen Ihrer Azure Cosmos DB-Apps und ist ein perfekter Begleiter für die .NET AspireAzure Hostingintegration. Der Emulator ist nicht installiert, sondern steht .NET.NET Aspire als Container zur Verfügung. Wenn Sie dem App-Host einen Container hinzufügen, wie im vorherigen Beispiel mit dem mcr.microsoft.com/cosmosdb/emulator Image gezeigt, wird der Container erstellt und gestartet, wenn der App-Host gestartet wird. Weitere Informationen finden Sie unter Container-Ressourcenlebenszyklus.

Konfigurieren des Cosmos DB-Emulatorcontainers

Es stehen verschiedene Konfigurationen für Container-Ressourcen zur Verfügung. Zum Beispiel können Sie die Ports und Umgebungsvariablen des Containers sowie seine Lebensdauerund vieles mehr konfigurieren.

Konfigurieren Sie den Containergateway-Port des Cosmos DB-Emulators

Standardmäßig macht der Cosmos DB Emulatorcontainer, wenn er von .NET Aspirekonfiguriert wird, die folgenden Endpunkte verfügbar:

Endpunkt	Containerhafen	Hostport
`https`	8081	dynamisch

Der Port, auf dem es lauscht, ist standardmäßig dynamisch. Wenn der Container gestartet wird, wird der Port einem zufälligen Port auf dem Hostcomputer zugeordnet. Um den Endpunktport zu konfigurieren, führen Sie Kettenaufrufe für den Containerressourcen-Generator aus, der von der RunAsEmulator-Methode bereitgestellt wird, wie im folgenden Beispiel gezeigt:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Der vorangehende Code konfiguriert den vorhandenen Endpunkt Cosmos DB des Emulatorcontainers https, um auf Port 8081zu lauschen. Der Port des Cosmos DB Emulatorcontainers wird dem Hostport zugeordnet, wie in der folgenden Tabelle dargestellt:

Endpunktname	Portzuordnung (`container:host`)
`https`	`8081:7777`

Konfigurieren Sie den Cosmos DB-Emulatorcontainer mit dauerhafter Laufzeit

Zum Konfigurieren des Cosmos DB-Emulatorcontainers mit einer permanenten Lebensdauer, rufen Sie die WithLifetime-Methode für die Cosmos DB-Emulatorcontainerressource auf, und übergeben Sie 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...

Weitere Informationen finden Sie unter Lebensdauer von Container-Ressourcen.

Konfigurieren Sie den Emulator-Container Cosmos DB mit einem Daten-Volume.

Um der AzureAzure Cosmos DB-Emulatorressource ein Datenvolumen hinzuzufügen, rufen Sie die WithDataVolume-Methode für die AzureAzure Cosmos DB-Emulatorressource auf.

var builder = DistributedApplication.CreateBuilder(args);

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

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

Das Datenvolume wird verwendet, um die Cosmos DB Emulatordaten außerhalb des Lebenszyklus des Containers zu speichern. Das Datenvolumen wird im Pfad /tmp/cosmos/appdata im Container des Cosmos DB-Emulators bereitgestellt und wenn kein name-Parameter angegeben wird, wird der Name generiert. Der Emulator hat seine AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE Umgebungsvariable auf truefestgelegt. Weitere Informationen zu Datenvolumes und Details dazu, warum sie gegenüber Bind-Mounts bevorzugt werden, finden Sie in der Docker Dokumentation: Volumes.

Konfigurieren Sie die Anzahl der Partitionen des Container-Emulators Cosmos DB

Rufen Sie zum Konfigurieren der Partitionsanzahl des Cosmos DB Emulatorcontainers die WithPartitionCount-Methode auf:

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

Im vorherigen Code wird der Cosmos DB-Emulatorcontainer so konfiguriert, dass er eine Partitionsanzahl von 100hat. Dies ist eine Kurzform für das Festlegen der Umgebungsvariable AZURE_COSMOS_EMULATOR_PARTITION_COUNT.

Hosten von Integritätsprüfungen für Integration

Die Azure Cosmos DB Hosting-Integration fügt automatisch eine Gesundheitsprüfung für die Cosmos DB Ressource hinzu. Die Gesundheitsprüfung überprüft, ob die Cosmos DB ausgeführt wird und ob eine Verbindung hergestellt werden kann.

Die Hostingintegration basiert auf dem 📦 AspNetCore.HealthChecks.CosmosDb NuGet-Paket.

Client Integration

Um mit der .NET Aspire Microsoft Entity Framework CoreCosmos DB Integration zu beginnen, installieren Sie das 📦Aspire.Microsoft.EntityFrameworkCore.Cosmos NuGet-Paket im clientnutzenden Projekt, also das Projekt der Anwendung, die den Microsoft Entity Framework CoreCosmos DB-Client verwendet.

.NET CLI
PaketReferenz

dotnet add package Aspire.Microsoft.EntityFrameworkCore.Cosmos

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

Hinzufügen des Cosmos DB-Kontextes

In der Program.cs-Datei Ihres clientnutzenden Projekts rufen Sie die AddCosmosDbContext-Erweiterungsmethode auf, um ein System.Data.Entity.DbContext zur Verwendung über den Dependency-Injection-Container zu registrieren. Die Methode verwendet einen Verbindungsnamenparameter.

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

Trinkgeld

Der parameter connectionName muss mit dem Namen übereinstimmen, der beim Hinzufügen der Cosmos DB-Ressource im App-Hostprojekt verwendet wird. Anders ausgedrückt: Wenn Sie AddAzureCosmosDB aufrufen und einen Namen von cosmosdb angeben, dann sollte derselbe Name verwendet werden, wenn Sie AddCosmosDbContextaufrufen. Weitere Informationen finden Sie unter Hinzufügen AzureAzure Cosmos DB Ressource.

Anschließend können Sie die DbContext Instanz mithilfe der Abhängigkeitseinfügung abrufen. Um beispielsweise den Client von einem Dienst abzurufen:

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

Weitere Informationen zur Verwendung von Entity Framework Core mit Azure Cosmos DBfinden Sie in den Beispielen für Azure Cosmos DB des NoSQL SDK für .NET.

Konfiguration

Die .NET Aspire Microsoft-Entity Framework Core-Cosmos DB-Integration bietet mehrere Optionen zum Konfigurieren der Azure Cosmos DB Verbindung, die an die Anforderungen und Konventionen Ihres Projekts angepasst sind.

Verwenden Sie eine Verbindungszeichenfolge

Wenn Sie eine Verbindungszeichenfolge aus dem Konfigurationsabschnitt ConnectionStrings verwenden, können Sie beim Aufrufen von builder.AddCosmosDbContextden Namen der Verbindungszeichenfolge angeben:

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

Anschließend wird die Verbindungszeichenfolge aus dem Konfigurationsabschnitt ConnectionStrings abgerufen:

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

Weitere Informationen finden Sie in der ConnectionString-Dokumentation.

Verwenden von Konfigurationsanbietern

Die .NET Aspire Microsoft Entity Framework CoreCosmos DB Integration unterstützt Microsoft.Extensions.Configuration. Es lädt die EntityFrameworkCoreCosmosSettings aus Konfigurationsdateien wie appsettings.json. Beispiel _appsettings.json, das einige der Optionen konfiguriert:

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

Die vollständige Cosmos DB Clientintegration des JSON-Schema finden Sie unter Aspire. Microsoft.EntityFrameworkCore.Cosmos/ConfigurationSchema.json.

Verwenden von Inlinedelegaten

Sie können auch den Action<EntityFrameworkCoreCosmosSettings> configureSettings Delegat übergeben, um einige oder alle EntityFrameworkCoreCosmosSettings Optionen inline einzurichten, z. B. um die Ablaufverfolgung aus Code zu deaktivieren:

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

Client Integrations-Gesundheitsprüfungen

Standardmäßig ermöglichen die .NET-.NET Aspire-Integrationen Integritätsprüfungen für alle Dienste. Weitere Informationen finden Sie unter .NET.NET Aspire Integrationsübersicht.

Die .NET Aspire Microsoft Entity Framework CoreCosmos DB-Integration führt derzeit keine Gesundheitsprüfungen durch, obwohl sich dies in zukünftigen Versionen ändern könnte.

Observability und Telemetrie

.NET .NET Aspire Integrationen richten automatisch Protokollierungs-, Tracing- und Metrikkonfigurationen ein, die manchmal als die Säulen der Observabilitybezeichnet werden. Weitere Informationen zur Integrationsobservability und Telemetrie finden Sie unter .NET.NET Aspire Übersicht über Integrationen. Abhängig vom Unterstützungsdienst könnten einige Integrationen nur bestimmte dieser Funktionen unterstützen. Beispielsweise unterstützen einige Integrationen Protokollierung und Ablaufverfolgung, aber keine Metriken. Telemetrie-Features können auch mithilfe der Techniken deaktiviert werden, die im Abschnitt Configuration beschrieben werden.

Protokollierung

Die .NET Aspire Microsoft Entity Framework CoreCosmos DB Integration verwendet die folgenden Protokollkategorien:

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

Nachverfolgung

Die .NET Aspire Microsoft Entity Framework CoreCosmos DB-Integration gibt mithilfe von OpenTelemetrydie folgenden Protokollierungsaktivitäten aus:

Azure.Cosmos.Operation
OpenTelemetry.Instrumentation.EntityFrameworkCore

Metriken

Die .NET Aspire Microsoft Entity Framework CoreCosmos DB -Integration unterstützt derzeit die folgenden Metriken:

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

Freigeben über