Integration von .NET Aspire Cosmos DB Entity Framework Core

2025-06-28

Enthält: Hosting-Integration —&— 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.
AzureCosmosDBContainerResource: Stellt eine AzureAzure Cosmos DB Containerressource dar.
AzureCosmosDBDatabaseResource: Stellt eine AzureAzure Cosmos DB Datenbankressource 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 AddAzureCosmosDB aufrufen, wird impliziert AddAzureProvisioning aufgerufen, wodurch während des Starts der App Azure-Ressourcen dynamisch generiert werden. Die App muss das entsprechende Abonnement und den entsprechenden Standort konfigurieren. Weitere Informationen finden Sie unter lokale Bereitstellung: Konfiguration.

Durch Bereitstellung generierte Bicep-Datei

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 das generierte Bicep-Modul zusammen mit der Manifestdatei ausgegeben. Wenn Sie eine AzureAzure Cosmos DB Ressource hinzufügen, wird das folgende Bicep generiert:

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

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

output connectionString string = cosmos.properties.documentEndpoint

output name string = cosmos.name

Der obige Bicep-Code ist ein Modul, das eine AzureAzure Cosmos DB-Kontoressource bereitstellt. Darüber hinaus werden Rollenzuweisungen für die Azure Ressource in einem separaten Modul erstellt:

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param cosmos_outputs_name string

param principalId string

resource cosmos 'Microsoft.DocumentDB/databaseAccounts@2024-08-15' existing = {
  name: cosmos_outputs_name
}

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
}

Das generierte Bicep ist ein Einstiegspunkt und wird durch Änderungen an der Bereitstellungsinfrastruktur in C# beeinflusst. Direkte Anpassungen an der Bicep-Datei werden überschrieben. Nehmen Sie daher Änderungen über die C#-Bereitstellungs-APIs vor, damit sie in den generierten Dateien reflektiert werden.

Anpassen der Bereitstellungsinfrastruktur

Alle .NET AspireAzure Ressourcen sind Unterklassen des AzureProvisioningResource Typs. Dieser Typ ermöglicht die Anpassung des generierten Bicep, indem eine Fluent-API bereitgestellt wird, die es ermöglicht, die Azure-Ressourcen mithilfe der ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>)-API zu konfigurieren. 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.
- Der einzelne CosmosDBAccount wird abgerufen.
- CosmosDBAccount.ConsistencyPolicy wird DefaultConsistencyLevel.Strong zugewiesen.
- Ein Tag wird dem Cosmos DB-Konto mit dem Schlüssel ExampleKey und dem Wert Example value hinzugefü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. Sie können einen Aufruf verketten, um anzumerken, dass Ihr AzureCosmosDBResource eine vorhandene Ressource ist.

var builder = DistributedApplication.CreateBuilder(args);

var existingCosmosName = builder.AddParameter("existingCosmosName");
var existingCosmosResourceGroup = builder.AddParameter("existingCosmosResourceGroup");

var cosmos = builder.AddAzureCosmosDB("cosmos-db")
                    .AsExisting(existingCosmosName, existingCosmosResourceGroup);

builder.AddProject<Projects.WebApplication>("web")
       .WithReference(cosmos);

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

Weitere Informationen zum Behandeln von AzureAzure Cosmos DB Ressourcen als vorhandene Ressourcen finden Sie unter Verwenden vorhandener Azure Ressourcen.

Anmerkung

Anstatt eine AzureAzure Cosmos DB-Ressource zu repräsentieren, können Sie auch eine Verbindungszeichenfolge zum Host der App hinzufügen. Dieser Ansatz ist schwach typiert und funktioniert nicht mit Rollenzuweisungen oder Infrastrukturanpassungen. Weitere Informationen finden Sie unter Hinzufügen vorhandener Azure Ressourcen mit Verbindungszeichenfolgen.

Hinzufügen AzureAzure Cosmos DB Datenbank- und Containerressourcen

.NET Aspire modelliert Eltern-Kind-Beziehungen zwischen Azure Cosmos DB Ressourcen. Ein Konto (Azure) kann z. BAzure Cosmos DBAzureCosmosDBResource. mehrere Datenbanken haben (AzureCosmosDBDatabaseResource), und jede Datenbank kann mehrere Container (AzureCosmosDBContainerResource) aufweisen. Wenn Sie eine Datenbank- oder Containerressource hinzufügen, gehen Sie dazu in einer übergeordneten Ressource vor.

Um eine AzureAzure Cosmos DB-Datenbankressource hinzuzufügen, rufen Sie die AddCosmosDatabase-Methode für eine IResourceBuilder<AzureCosmosDBResource> Instanz auf:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Wenn Sie AddCosmosDatabaseaufrufen, wird Ihrer Ressourcengruppe db eine neue Datenbank mit dem Namen Cosmos DB hinzugefügt, und die neu erstellte Datenbankressource wird zurückgegeben. Die Datenbank wird in dem Cosmos DB-Konto erstellt, das durch die zuvor von Ihnen hinzugefügte AzureCosmosDBResource dargestellt wird. Die Datenbank ist ein logischer Container für Sammlungen und Benutzer.

Ein AzureAzure Cosmos DB Container ist der Ort, an dem Daten gespeichert werden. Beim Erstellen eines Containers müssen Sie einen Partitionsschlüssel angeben.

Um eine AzureAzure Cosmos DB Containerressource hinzuzufügen, rufen Sie die AddContainer-Methode für eine IResourceBuilder<AzureCosmosDBDatabaseResource> Instanz auf:

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db");
var db = cosmos.AddCosmosDatabase("db");
var container = db.AddContainer("entries", "/id");

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

Der Container wird in der Datenbank erstellt, die durch die zuvor hinzugefügte AzureCosmosDBDatabaseResource dargestellt wird. Weitere Informationen finden Sie unter Datenbanken, Container und Elemente in AzureAzure Cosmos DB.

Beispiel für die Beziehung zwischen Eltern-Kind-Ressourcen

Um die Eltern-Kind-Beziehung zwischen Azure Cosmos DB Ressourcen besser zu verstehen, betrachten Sie das folgende Beispiel, das das Hinzufügen einer Azure Cosmos DB Ressource sowie einer Datenbank und eines Containers veranschaulicht.

var builder = DistributedApplication.CreateBuilder(args);

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

var customers = cosmos.AddCosmosDatabase("customers");
var profiles = customers.AddContainer("profiles", "/id");

var orders = cosmos.AddCosmosDatabase("orders");
var details = orders.AddContainer("details", "/id");
var history = orders.AddContainer("history", "/id");

builder.AddProject<Projects.Api>("api")
       .WithReference(profiles)
       .WithReference(details)
       .WithReference(history);

builder.Build().Run();

Der vorausgehende Code fügt eine Ressource namens Azure mit zwei Datenbanken hinzu: Azure Cosmos DB und cosmos. Die customers Datenbank hat einen einzelnen Container mit dem Namen profiles, während die orders Datenbank über zwei Container verfügt: details und history. Der Partitionsschlüssel für jeden Container lautet /id.

Das folgende Diagramm veranschaulicht die Eltern-Kind-Beziehung zwischen den AzureAzure Cosmos DB Ressourcen.

Wenn Ihr App-Hostcode Beziehungen zwischen übergeordneten und untergeordneten Elementen ausdrückt, kann der Client einen Deep-Link zu diesen Ressourcen anhand des Namens herstellen. Auf die customers Datenbank kann z. B. anhand des Namens im Clientprojekt verwiesen werden, wobei eine Database Instanz registriert wird, die eine Verbindung mit der customers Datenbank herstellt. Das gleiche gilt für benannte Container, z. B. kann auf den details Container anhand des Namens im Clientprojekt verwiesen werden, wobei eine Container Instanz registriert wird, die eine Verbindung mit dem details Container herstellt.

Hinzufügen AzureAzure Cosmos DB Emulator-Ressource

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.

Cosmos DB-Emulatorcontainer mit Datenvolumen konfigurieren

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.

Verwenden Sie den Linux-basierten Emulator (Vorschau)

Die nächste Generation des AzureAzure Cosmos DB Emulators ist vollständig Linux-basiert und als Docker Container verfügbar. Er unterstützt die Ausführung auf einer Vielzahl von Prozessoren und Betriebssystemen.

Rufen Sie die Cosmos DB-Methode auf, um die Vorschauversion des RunAsPreviewEmulator Emulators zu verwenden. Da sich dieses Feature in der Vorschauversion befindet, müssen Sie sich explizit für die Vorschaufunktion entscheiden, indem Sie die experimentelle Diagnose ASPIRECOSMOSDB001 deaktivieren.

Der Vorschauemulator unterstützt auch das Verfügbarmachen eines "Daten-Explorer"-Endpunkts, mit dem Sie die im Cosmos DB Emulator gespeicherten Daten über eine Web-UI anzeigen können. Rufen Sie zum Aktivieren des Daten-Explorers die WithDataExplorer-Methode auf.

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

Der obige Code konfiguriert den auf Linux basierenden Cosmos DB-Emulator-Vorschaucontainer so, dass er den Daten-Explorer-Endpunkt zur Laufzeit verwendet.

Durchführung von Integrations-Gesundheitsprüfungen

Die Azure Cosmos DB Hosting-Integration fügt automatisch eine Gesundheitsprüfung für die Cosmos DB Ressource hinzu. Die Integritätsprüfung stellt sicher, dass die Cosmos DB läuft und eine Verbindung zu ihr 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 Projekts, das den Client nutzt, rufen Sie die AddCosmosDbContext-Erweiterungsmethode auf, um ein System.Data.Entity.DbContext zur Verwendung über den Abhängigkeitsinjektionscontainer zu registrieren. Die Methode verwendet einen Verbindungsnamenparameter und einen Datenbanknamenparameter.

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

Alternativ kann der Datenbankname von der Verbindung abgeleitet werden, wenn eine einzelne Datenbank in der Verbindungszeichenfolge vorhanden ist. In diesem Fall können Sie den Datenbanknamenparameter weglassen:

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

Tipp

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

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

Inline-Delegaten verwenden

Sie können auch den Action<EntityFrameworkCoreCosmosSettings> configureSettings-Delegaten übergeben, um einige oder alle EntityFrameworkCoreCosmosSettings-Optionen inline einzurichten, beispielsweise um die Ablaufverfolgung im Code zu deaktivieren:

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

Client-Integritätsprüfungen

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.

Einblick und Telemetrie

.NET.NET Aspire Integrationen richten automatisch Protokollierungs-, Tracing- und Metrikkonfigurationen ein, die manchmal als die Säulen der Observabilitybezeichnet werden. Weitere Informationen zum Einblick in Integrationen und zur Telemetrie finden Sie in der .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

Ablaufverfolgung

Die .NET Aspire Microsoft Entity Framework CoreCosmos DB-Integration gibt die folgenden Ablaufverfolgungsaktivitäten mithilfe von OpenTelemetry 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