.NET Aspire Azure Cosmos DB-Integration

Artikel
03/05/2025

umfasst: Hostingintegration und Client Integration

Azure Cosmos DB ist ein vollständig verwalteter NoSQL-Datenbankdienst für die moderne App-Entwicklung. Mit der .NET AspireAzure Cosmos DB-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 Hosting-Integrationsmodelle modellieren die verschiedenen Cosmos DB Ressourcen als die folgenden Typen:

AzureCosmosDBResource: Stellt eine AzureAzure Cosmos DB Ressource dar.
AzureCosmosDBEmulatorResource: Stellt eine AzureAzure Cosmos DB Emulatorressource dar.

Um auf diese Typen und die APIs, um sie auszudrücken, zuzugreifen, fügen Sie das NuGet-Paket 📦Aspire.Hosting.Azure.CosmosDB im App-Host-Projekt hinzu.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.CosmosDB

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

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

Eine Ressource AzureAzure Cosmos DB hinzufügen

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 ein AzureCosmosDBResource hinzufügen, werden dadurch weitere nützliche APIs zum Hinzufügen von Datenbanken und Containern verfügbar. 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, ruft es implizit AddAzureProvisioning auf, wodurch Azure-Ressourcen beim Start der App dynamisch generiert werden. Die App muss das entsprechende Abonnement und den entsprechenden Standort konfigurieren. Weitere Informationen finden Sie unter lokale Bereitstellung: Konfiguration.

Generierte Bereitstellung 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 selbst schreiben, sondern die Bereitstellungs-APIs generieren Bicep für Sie. Wenn Sie Ihre App veröffentlichen, wird das generierte Bicep zusammen mit der Manifestdatei ausgegeben. Wenn Sie eine AzureAzure Cosmos DB Ressource hinzufügen, wird die folgende Bicep generiert:

@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

Das vorliegende Bicep 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 Ort der Ressourcengruppe.

Zusätzlich zum Cosmos DB-Konto fügt es auch die aktuelle Anwendung zur Rolle Data Contributor für das Cosmos DB-Konto hinzu. Der generierte Bicep ist ein Ausgangspunkt und kann individuell 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, indem er eine Fluent-API bereitstellt, mit der die Azure-Ressourcen mithilfe der ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>)-API konfiguriert werden können. Sie können z. B. die kind, consistencyPolicy, locationsund 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 an die ConfigureInfrastructure-API.
- Der infra-Parameter ist eine Instanz des typs AzureResourceInfrastructure.
- Die bereitstellbaren Ressourcen werden durch Aufrufen der GetProvisionableResources()-Methode abgerufen.
- Die CosmosDBAccount wird einzeln abgerufen.
- Der CosmosDBAccount.ConsistencyPolicy wird einem DefaultConsistencyLevel.Strongzugewiesen.
- Dem Cosmos DB Konto wird ein Tag 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. Anstatt eine neue AzureAzure Cosmos DB-Ressource darzustellen, können Sie dem App-Host eine Verbindungszeichenfolge hinzufügen. Rufen Sie zum Hinzufügen einer Verbindung zu einem vorhandenen AzureAzure Cosmos DB Konto 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 "Connection-String" verwendet, um jede Art von Verbindungsinformationen darzustellen.

Die Verbindungszeichenfolge wird in der Konfiguration des App-Hosts konfiguriert, in der Regel unter Benutzergeheimnisse, unter dem 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 eine Abkürzung für IConfiguration.GetSection("ConnectionStrings")[name].

Hinzufügen AzureAzure Cosmos DB Datenbank- und Containerressourcen

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");
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 das von Ihnen zuvor 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");
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.

Hinzufügen der 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 mit einem Emulator 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 stattdessen als Container für .NET.NET Aspire zugänglich. 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 Lebenszyklus von Containerressourcen.

Konfigurieren Cosmos DB Emulator-Container

Es stehen verschiedene Konfigurationen für Containerressourcen zur Verfügung. Beispielsweise können Sie die Ports und Umgebungsvariablen des Containers, seine Lebensdauerund vieles mehr konfigurieren.

Konfigurieren Sie den Gateway-Port des Cosmos DB-Emulator-Containers

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 vorhergehende Code konfiguriert den vorhandenen Cosmos DB-Endpunkt des https Emulator-Containers, 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 des Cosmos DB-Emulatorcontainers mit dauerhaftem Lebenszyklus

Zum Konfigurieren des Cosmos DB Emulator-Containers mit einer persistenten Lebensdauer rufen Sie die Methode WithLifetime für die Cosmos DB-Emulator-Containerressource 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...

Unter Lebensdauer von Containerressourcen finden Sie weitere Informationen.

Konfigurieren Sie den Cosmos DB-Emulatorcontainer mit Datenvolumen

Um der AzureAzure Cosmos DB Emulatorressource ein Datenvolume 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 /tmp/cosmos/appdata-Pfad im Container des Cosmos DB-Emulators bereitgestellt und wenn kein name-Parameter angegeben wird, wird ein Name generiert. Der Emulator hat seine AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE Umgebungsvariable auf truefestgelegt. Weitere Informationen zu Datenvolumen und Details, warum diese gegenüber Bind-Mounts bevorzugt werden, finden Sie in der Docker Dokumentation: Volumes.

Konfigurieren der Partitionsanzahl des Emulator-Containers 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 zum Festlegen der umgebungsvariablen 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 vorangehende Code konfiguriert den auf Linuxbasierenden Vorschaucontainer und den Cosmos DB-Emulatorcontainer so, dass er den Daten-Explorer-Endpunkt zur Laufzeit verwendet.

Durchführung von Integritätsprüfungen für Integrationen

Die Azure Cosmos DB Hostingintegration fügt automatisch eine Integritätsprüfung für die Cosmos DB Ressource hinzu. Die Gesundheitsprüfung stellt sicher, dass die Cosmos DB läuft und eine Verbindung dazu hergestellt werden kann.

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

Client Integration

Um mit der .NET AspireAzure Cosmos DB-Clientintegration zu beginnen, installieren Sie das 📦Aspire.Microsoft.Azure.Cosmos.-NuGet-Paket im Projekt, das den Cosmos DB-Client verwendet, also das Projekt für die Anwendung, die den Client nutzt. Die Cosmos DB Clientintegration registriert eine CosmosClient Instanz, die Sie für die Interaktion mit Cosmos DBverwenden können.

.NET CLI
PackageReference

dotnet add package Aspire.Microsoft.Azure.Cosmos

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

Client Cosmos DB hinzufügen

In der Program.cs Datei Ihres Projekts, das den Client verwendet, rufen Sie die AddAzureCosmosClient Erweiterungsmethode bei jedem IHostApplicationBuilder auf, um eine CosmosClient für die Verwendung über den Dependency-Injection-Container zu registrieren. Die Methode verwendet einen Verbindungsnamenparameter.

builder.AddAzureCosmosClient(connectionName: "cosmos-db");

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 den Namen cosmos-db angeben, sollte dieser Name beim Aufrufen von AddAzureCosmosClientverwendet werden. Weitere Informationen finden Sie unter Hinzufügen AzureAzure Cosmos DB Ressource.

Anschließend können Sie die CosmosClient-Instanz mithilfe der Dependency Injection abrufen. So rufen Sie beispielsweise die Verbindung aus einem Beispieldienst ab:

public class ExampleService(CosmosClient client)
{
    // Use client...
}

Weitere Informationen zur Abhängigkeitsinjektion finden Sie unter .NET Abhängigkeitsinjektion.

Einen zugeordneten Cosmos DB-Client hinzufügen

Es kann Situationen geben, in denen Sie mehrere CosmosClient Instanzen mit unterschiedlichen Verbindungsnamen registrieren möchten. Um Clients mit dem Schlüssel Cosmos DB zu registrieren, rufen Sie die Methode AddKeyedAzureCosmosClient auf:

builder.AddKeyedAzureCosmosClient(name: "mainDb");
builder.AddKeyedAzureCosmosClient(name: "loggingDb");

Wichtig

Bei der Verwendung von schlüsselbasierten Diensten wird erwartet, dass Ihre Cosmos DB Ressource zwei benannte Datenbanken konfiguriert hat, eine für die mainDb und eine für die loggingDb.

Anschließend können Sie die CosmosClient Instanzen mithilfe der Abhängigkeitseinfügung abrufen. So rufen Sie beispielsweise die Verbindung aus einem Beispieldienst ab:

public class ExampleService(
    [FromKeyedServices("mainDb")] CosmosClient mainDbClient,
    [FromKeyedServices("loggingDb")] CosmosClient loggingDbClient)
{
    // Use clients...
}

Weitere Informationen zu schlüsselbasierten Diensten finden Sie unter .NET Abhängigkeitsinjektion: schlüsselbasierte Dienste.

Konfiguration

Die .NET AspireAzure Cosmos DB-Integration bietet mehrere Optionen zum Konfigurieren der Verbindung basierend auf den Anforderungen und Konventionen Ihres Projekts.

Verwenden Sie eine Verbindungszeichenfolge

Wenn Sie eine Verbindungszeichenfolge aus dem Konfigurationsabschnitt ConnectionStrings verwenden, können Sie beim Aufrufen der AddAzureCosmosClient-Methode den Namen der Verbindungszeichenfolge angeben:

builder.AddAzureCosmosClient("cosmos-db");

Aus dem Konfigurationsabschnitt ConnectionStrings wird anschließend die Verbindungszeichenfolge abgerufen.

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

Weitere Informationen zum Formatieren dieser Verbindungszeichenfolge finden Sie in der ConnectionString-Dokumentation.

Konfigurationsanbieter verwenden

Die .NET AspireAzure Cosmos DB-Integration unterstützt Microsoft.Extensions.Configuration. Sie lädt die MicrosoftAzureCosmosSettings mithilfe des Aspire:Microsoft:Azure:Cosmos Schlüssels aus der Konfiguration. Der folgende Codeausschnitt ist ein Beispiel für eine appsettings.json Datei, die einige der Optionen konfiguriert:

{
  "Aspire": {
    "Microsoft": {
      "Azure": {
        "Cosmos": {
          "DisableTracing": false,
        }
      }
    }
  }
}

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

Inline-Delegaten verwenden

Sie können auch den Action<MicrosoftAzureCosmosSettings> configureSettings Delegat übergeben, um einige oder alle Optionen inline einzurichten, z. B. das Tracing im Code zu deaktivieren.

builder.AddAzureCosmosClient(
    "cosmos-db",
    static settings => settings.DisableTracing = true);

Sie können die Microsoft.Azure.Cosmos.CosmosClientOptions auch mithilfe des optionalen Parameters Action<CosmosClientOptions> configureClientOptions der AddAzureCosmosClient-Methode einrichten. Wenn Sie beispielsweise das Benutzer-Agent-Headersuffix CosmosClientOptions.ApplicationName für alle Anforderungen, die von diesem Client ausgegeben werden, festlegen möchten:

builder.AddAzureCosmosClient(
    "cosmosConnectionName",
    configureClientOptions:
        clientOptions => clientOptions.ApplicationName = "myapp");

Client Integrations-Gesundheitschecks

Die .NET AspireCosmos DB Kundenintegration implementiert derzeit keine Gesundheitsprüfungen, dies kann sich jedoch in zukünftigen Versionen ändern.

Observability und Telemetrie

.NET .NET Aspire-Integrationen richten automatisch Protokollierungs-, Ablaufverfolgungs- und Metrikkonfigurationen ein, die manchmal als die Säulen der Beobachtbarkeitbezeichnet werden. Weitere Informationen zur Integrations-Observability und Telemetrie finden Sie unter .NET.NET Aspire Integrationsübersicht. Abhängig vom unterstützenden Dienst unterstützen einige Integrationen möglicherweise nur einige dieser Funktionen. 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 dargestellt sind.

Protokollierung

Die .NET AspireAzure Cosmos DB-Integration verwendet die folgenden Protokollkategorien:

Azure-Cosmos-Operation-Request-Diagnostics

Zusätzlich zum Abrufen von Azure Cosmos DB Anforderungsdiagnosen für fehlerhafte Anforderungen können Sie Latenzschwellenwerte konfigurieren, um zu bestimmen, welche der erfolgreichen Azure Cosmos DB Anforderungsdiagnosen protokolliert werden. Die Standardwerte sind 100 ms für Punktvorgänge und 500 ms für Vorgänge ohne Punkt.

builder.AddAzureCosmosClient(
    "cosmosConnectionName",
    configureClientOptions:
        clientOptions => {
            clientOptions.CosmosClientTelemetryOptions = new()
            {
                CosmosThresholdOptions = new()
                {
                    PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(50),
                    NonPointOperationLatencyThreshold = TimeSpan.FromMilliseconds(300)
                }
            };
        });

Nachverfolgung

Die .NET AspireAzure Cosmos DB Integration gibt die folgenden Tracing-Aktivitäten mithilfe von OpenTelemetry aus.

Azure.Cosmos.Operation

Azure Azure Cosmos DB Ablaufverfolgung befindet sich derzeit in der Preview-Phase, daher müssen Sie den Experimentiermodus aktivieren, um die Ausgabe von Ablaufverfolgungen zu gewährleisten.

AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true);

Weitere Informationen finden Sie unter AzureAzure Cosmos DB SDK-Observability: Trace-Attribute.

Metriken

Die .NET AspireAzure Cosmos DB-Integration unterstützt derzeit Metriken aufgrund von Einschränkungen mit dem Azure SDK nicht standardmäßig.

Siehe auch

Azure Cosmos DB
.NET Aspire Cosmos DB Entity Framework Core Integration
Übersicht über .NET.NET Aspire Integrationen
Übersicht über .NET AspireAzure Integrationen
.NET Aspire GitHub Repo

Freigeben über