Freigeben über

Integration von .NET AspireAzure Cosmos DB

Enthält:Hosting-Integration inbegriffen Hosting-Integration —&— Client Integration inbegriffenClient 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.

Wenn Sie sich für die Integration von Entity Framework Core interessieren, siehe .NET AspireCosmos DBIntegration von Entity Framework Core.

Hosting-Integration

Die .NET.NET AspireAzure Cosmos DB Hosting-Integrationsmodelle modellieren die verschiedenen Cosmos DB Ressourcen als die folgenden Typen:

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

dotnet add package Aspire.Hosting.Azure.CosmosDB

Weitere Informationen finden Sie unter dotnet add package oder Verwalten 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, 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 noch nicht mit Bicep arbeiten, 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-Modul zusammen mit der Manifestdatei ausgegeben. Wenn Sie eine AzureAzure Cosmos DB-Ressource hinzufügen, wird der folgende Bicep-Code 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 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:

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

Wichtig

Wenn Sie die Methoden RunAsExisting, PublishAsExisting oder AsExisting aufrufen, um mit Ressourcen zu arbeiten, die bereits in Ihrem Azure-Abonnement vorhanden sind, müssen Sie bestimmte Konfigurationswerte zu Ihrem App-Host hinzufügen, damit .NET Aspire diese finden kann. Zu den erforderlichen Konfigurationswerten gehören SubscriptionId, AllowResourceGroupCreation, ResourceGroup und Location. Wenn Sie sie nicht festlegen, werden Fehler "Fehlende Konfiguration" auf dem .NET.NET Aspire Dashboard angezeigt. Weitere Informationen zum Festlegen dieser Informationen finden Sie unter "Konfiguration".

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 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");
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 eine Beziehung zwischen über- und untergeordneten Ressourcen

Um die Beziehung zwischen übergeordneten und untergeordneten Azure Cosmos DB Ressourcen besser zu verstehen, betrachten Sie das folgende Beispiel, das das Hinzufügen einer Azure Cosmos DB Ressource zusammen mit einer Datenbank und einem Container 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 vorangehende 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.

Ein Diagramm, das die Beziehungen zwischen über- und untergeordneten AzureAzure Cosmos DB-Ressourcen darstellt.

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.

Azure Azure Cosmos DB-Emulator-Ressource hinzufügen

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. Informationen über den Lebenszyklus von Containerressourcen finden Sie unter Containerressourcenlebenszyklus.

Cosmos DB-Emulatorcontainer konfigurieren

Es stehen verschiedene Konfigurationen für Containerressourcen zur Verfügung, z. B. können Sie die Ports, Umgebungsvariablen, Lebensdauer und 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...

Weitere Informationen finden Sie unter Lebensdauer von Container-Ressourcen.

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 Datenvolumes und Details dazu, warum sie 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 obige Code konfiguriert den auf Linux basierenden Cosmos DB-Emulator-Vorschaucontainer so, dass er den Daten-Explorer-Endpunkt zur Laufzeit verwendet.

Integritätsprüfungen der Hosting-Integration

Die Azure Cosmos DB Hostingintegration fügt automatisch eine Integritätsprü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 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.

dotnet add package Aspire.Microsoft.Azure.Cosmos

Client Cosmos DB hinzufügen

Rufen Sie in der Program.cs-Datei Ihres Projekts, das den Client verwendet, die AddAzureCosmosClient-Erweiterungsmethode für jeden IHostApplicationBuilder auf, um einen 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 "Ressource hinzufügenAzureAzure Cosmos DB".

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

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

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

Schlüsselbasierten 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ängigkeitseinfügung: Schlüsseldienste.

Datenbank hinzufügen AzureAzure Cosmos DB

Im App-Host kann die Datenbankressource (AzureCosmosDBDatabaseResource) als untergeordnete Ressource zum übergeordneten Element AzureCosmosDBResourcehinzugefügt werden. In Ihrem kundenorientierten Projekt können Sie einen Deep-Link zu der Datenbankressource anhand des Namens herstellen und eine Database Instanz für die Verwendung mit Dependency Injection registrieren. Betrachten Sie beispielsweise den folgenden Code, der AddAzureCosmosDatabase auf einer IHostApplicationBuilder-Instanz aufruft:

builder.AddAzureCosmosDatabase(connectionName: "customers");

Die AddAzureCosmosDatabase API gibt eine CosmosDatabaseBuilder Instanz zurück, mit der Sie mehrere Container unter derselben Datenbankverbindung anfügen können. Alle untergeordneten Container verwenden dieselbe CosmosClient- und Datenbankverbindung und CosmosClient-Instanz. Diese Strategie ist nützlich, wenn Sie dasselbe CosmosClientOptions mit mehreren Containern verknüpfen.

Nach dem Aufrufen von AddAzureCosmosDatabase können Sie die Database-Instanz mithilfe der Abhängigkeitsinjektion abrufen. Um die Datenbank beispielsweise von einem Delegaten in einem Aufruf MapGet abzurufen, sehen Sie sich den folgenden Code an:

app.MapGet("/api/customers", async (Database database) =>
{
    // Query data from database...
});

Hinzufügen einer schlüsselbasierten Datenbank AzureAzure Cosmos DB

Es gibt auch eine AddKeyedAzureCosmosDatabase API, die eine CosmosDatabaseBuilder Instanz zurückgibt, mit der Sie mehrere Container unter derselben Datenbankverbindung anfügen können. -Methode, mit der Sie mehrere Datenbanken mit unterschiedlichen Verbindungsnamen registrieren können. Betrachten Sie beispielsweise den folgenden Code, der AddKeyedAzureCosmosDatabase auf einer IHostApplicationBuilder-Instanz aufruft:

var builder = WebApplication.CreateBuilder(args);

builder.AddKeyedAzureCosmosDatabase("customers");
builder.AddKeyedAzureCosmosDatabase("orders");

var app = builder.Build();

app.MapGet("/api/customers", async (
    [FromKeyedServices("customers")] Database database) =>
{
    // Get container from database and query data
});

app.MapPost("/api/orders", async (
    [FromKeyedServices("orders")] Database database,
    [FromBody] OrderRequest order) =>
{
    // Get container from database and query data
});

app.Run();

Im vorangehenden Beispielcode wird veranschaulicht, wie zwei Datenbanken, details und customers, registriert werden. Jede benannte Datenbank kann verwendet werden, um die entsprechenden Container abzurufen, um Daten abzufragen.

Container hinzufügen AzureAzure Cosmos DB

Wenn Sie eine Cosmos DB Ressource im App-Hostprojekt hinzufügen, können Sie auch eine Azure Cosmos DB Containerressource hinzufügen. Die Containerressource wird als untergeordnete Ressource für die übergeordnete AzureCosmosDBDatabaseResource betrachtet. In Ihrem Projekt, das den Client verwendet, können Sie einen Deep-Link zur Containerressource anhand des Namens herstellen und eine Container-Instanz für die Verwendung mit Dependency Injection registrieren. Betrachten Sie beispielsweise den folgenden Code, der AddAzureCosmosContainer auf einer IHostApplicationBuilder-Instanz aufruft:

builder.AddAzureCosmosContainer(connectionName: "details");

Anschließend können Sie die Container-Instanz mithilfe der Dependency Injection abrufen. Um beispielsweise den Container aus einem Delegaten in einem MapGet-Aufruf abzurufen, betrachten Sie den folgenden Code:

app.MapGet("/api/orders/{id:guid}", async (
    Container container, 
    [FromRoute] Guid id) =>
{
    // Query data from container...
});

Azure Azure Cosmos DB-Container mit Schlüsseln hinzufügen

Es gibt auch eine AddKeyedAzureCosmosContainer Methode, mit der Sie mehrere Container mit unterschiedlichen Verbindungsnamen registrieren können. Betrachten Sie beispielsweise den folgenden Code, der AddKeyedAzureCosmosContainer auf einer IHostApplicationBuilder-Instanz aufruft:

var builder = WebApplication.CreateBuilder(args);

builder.AddKeyedAzureCosmosContainer("customers");

var app = builder.Build();

app.MapGet("/api/customers", async (
    [FromKeyedServices("customers")] Container container) =>
{
    // Query data from container...
});

app.Run();

Wenn Sie über mehrere Container unter derselben Datenbankverbindung verfügen, können Sie die AddAzureCosmosDatabase API verwenden, um mehrere Container unter derselben Datenbankverbindung anzufügen. Alle untergeordneten Container verwenden dieselbe CosmosClient- und Datenbankverbindung. Diese Strategie ist nützlich, wenn Sie dasselbe CosmosClientOptions mit mehreren Containern verknüpfen. Betrachten Sie den folgenden alternativen Code, um mehrere Container unter derselben Datenbankverbindung zu registrieren:

var builder = WebApplication.CreateBuilder(args);

builder.AddAzureCosmosDatabase("customers", configureClientOptions: options =>
    {
        options.SerializerOptions = new CosmosSerializationOptions()
        {
            PropertyNamingPolicy = CosmosPropertyNamingPolicy.CamelCase
        };
    })
    .AddKeyedContainer(name: "profiles");

builder.AddAzureCosmosDatabase(connectionName: "orders")
       .AddKeyedContainer(name: "details")
       .AddKeyedContainer(name: "history");

var app = builder.Build();

app.MapGet("/api/customers", async (
    [FromKeyedServices("profiles")] Container container) =>
{
    // Query data from container
});

app.MapGet("/api/orders", async (
    [FromKeyedServices("details")] Container container,
    [FromKeyedServices("history")] Container container) =>
{
    // Query data from container
});

app.Run();

Im vorangehenden Beispielcode wird veranschaulicht, wie zwei Datenbanken registriert werden, customers und ordersjede mit ihren eigenen Containern. Die customers Datenbank hat einen einzelnen Container mit dem Namen profiles, während die orders Datenbank zwei Container mit dem Namen details und history. Jeder Container kann einzeln mit dem jeweiligen Schlüssel abgefragt werden.

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 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-Schema der JSON-Clientintegration finden Sie unter Aspire.Microsoft.Azure.Cosmos/ConfigurationSchema.json

Inline-Delegaten verwenden

Sie können auch den Action<MicrosoftAzureCosmosSettings> configureSettings-Delegaten übergeben, um einige oder alle Optionen inline einzurichten, beispielsweise um die Ablaufverfolgung 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. Beispielsweise legen Sie das Benutzer-Agent-Headersuffix CosmosClientOptions.ApplicationName für alle Anforderungen, die von diesem Client ausgegeben werden, wie folgt fest:

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.

Beobachtbarkeit und Telemetrie

.NET .NET Aspire Integrationen richten automatisch Protokollierungs-, Ablaufverfolgungs- und Metrikkonfigurationen ein, die manchmal als Säulen der Observability bezeichnet werden. Weitere Informationen zum Einblick in Integrationen und zur Telemetrie finden Sie in der .NET.NET AspireÜbersicht über Integrationen. 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. Telemetriefeatures können auch mithilfe der im Abschnitt "Konfiguration " dargestellten Techniken deaktiviert werden.

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

Ablaufverfolgung

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

  • Azure.Cosmos.Operation

Die Ablaufverfolgung der AzureAzure Cosmos DB befindet sich derzeit in der Vorschauphase, 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