Udostępnij za pośrednictwem

integracja .NET AspireAzure Cosmos DB

Obejmuje:integracja hostingu obejmuje integrację hostingu — Client integracja dołączonaClient

Azure Cosmos DB to w pełni zarządzana usługa bazy danych NoSQL na potrzeby nowoczesnego tworzenia aplikacji. Integracja .NET AspireAzure Cosmos DB umożliwia łączenie się z istniejącymi wystąpieniami Cosmos DB lub tworzenie nowych wystąpień z .NET za pomocą emulatora Azure Cosmos DB.

Jeśli szukasz Entity Framework Core integracji, zobacz .NET AspireCosmos DBEntity Framework Core integrację.

Integracja hostingu

Model integracji hostingu .NET.NET AspireAzure Cosmos DB przedstawia różne zasoby Cosmos DB jako następujące typy:

Aby uzyskać dostęp do tych typów i powiązanych z nimi interfejsów API, dodaj pakiet NuGet 📦Aspire.Hosting.Azure.CosmosDB do projektu hosta aplikacji .

dotnet add package Aspire.Hosting.Azure.CosmosDB

Aby uzyskać więcej informacji, zobacz dotnet add package lub Zarządzanie zależnościami pakietów w .NET aplikacjach.

Dodawanie zasobu AzureAzure Cosmos DB

W projekcie hosta aplikacji wywołaj AddAzureCosmosDB, aby dodać i zwrócić AzureAzure Cosmos DB twórcę zasobów.

var builder = DistributedApplication.CreateBuilder(args);

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

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

Po dodaniu AzureCosmosDBResource do hosta aplikacji, udostępnia on inne przydatne interfejsy API do dodawania baz danych i kontenerów. Innymi słowy, należy dodać AzureCosmosDBResource przed dodaniem jakiegokolwiek innego Cosmos DB zasobu.

Ważny

Podczas wywoływania AddAzureCosmosDB, automatycznie wywołuje AddAzureProvisioning, co dodaje wsparcie dla dynamicznego generowania zasobów Azure podczas uruchamiania aplikacji. Aplikacja musi skonfigurować odpowiednią subskrypcję i lokalizację. Aby uzyskać więcej informacji, zobacz Local provisioning: Configuration (Aprowizowanie lokalne: konfiguracja).

Bicep wygenerowany przez prowizjonowanie

Jeśli dopiero zaczynasz korzystać z aplikacji Bicep, jest to język specyficzny dla domeny do definiowania Azure zasobów. W przypadku .NET.NET Aspirenie musisz pisać Bicep ręcznie, ponieważ interfejsy API do aprowizacji generują Bicep za Ciebie. Podczas publikowania aplikacji wygenerowany Bicep zostaje wyświetlony wraz z plikiem manifestu. Po dodaniu zasobu AzureAzure Cosmos DB zostanie wygenerowany następujący kod Bicep:

@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

Powyższy Bicep jest modułem, który tworzy AzureAzure Cosmos DB zasób konta. Ponadto w osobnym module tworzone są przypisania ról dla zasobu Azure.

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

Wygenerowany Bicep jest punktem wyjścia i ma wpływ na zmiany w infrastrukturze aprowizacji w języku C#. Modyfikacje pliku Bicep, które zostaną wprowadzone bezpośrednio, będą nadpisane. Dlatego należy wprowadzać je za pośrednictwem interfejsów API aprowizowania w języku C#, aby zapewnić, że zostaną odzwierciedlone w wygenerowanych plikach.

Dostosowywanie infrastruktury aprowizacji

Wszystkie zasoby .NET AspireAzure to podklasy typu AzureProvisioningResource. Ten typ umożliwia dostosowanie wygenerowanego kodu Bicep poprzez zapewnienie płynnego interfejsu API do konfigurowania zasobów Azure przy użyciu API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Można na przykład skonfigurować kind, consistencyPolicy, locationsi więcej. W poniższym przykładzie pokazano, jak dostosować zasób AzureAzure Cosmos DB:

builder.AddAzureCosmosDB("cosmos-db")
    .ConfigureInfrastructure(infra =>
    {
        var cosmosDbAccount = infra.GetProvisionableResources()
                                   .OfType<CosmosDBAccount>()
                                   .Single();

        cosmosDbAccount.Kind = CosmosDBAccountKind.MongoDB;
        cosmosDbAccount.ConsistencyPolicy = new()
        {
            DefaultConsistencyLevel = DefaultConsistencyLevel.Strong,
        };
        cosmosDbAccount.Tags.Add("ExampleKey", "Example value");
    });

Powyższy kod:

Dostępnych jest wiele opcji konfiguracji umożliwiających dostosowanie zasobu AzureAzure Cosmos DB. Aby uzyskać więcej informacji, zobacz Azure.Provisioning.CosmosDB. Aby uzyskać więcej informacji, zobacz Azure. Dostosowywanie provisioningu.

Nawiązywanie połączenia z istniejącym kontem AzureAzure Cosmos DB

Być może masz istniejące konto AzureAzure Cosmos DB, z którym chcesz nawiązać połączenie. Możesz łańcuchować wywołanie, aby wskazać, że AzureCosmosDBResource jest istniejącym zasobem:

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

Aby uzyskać więcej informacji na temat traktowania AzureAzure Cosmos DB zasobów jako istniejących zasobów, zobacz Korzystanie z istniejących Azure zasobów.

Notatka

Alternatywnie, zamiast reprezentować AzureAzure Cosmos DB zasób, można dodać łańcuch połączenia do hosta aplikacji. Takie podejście jest słabo typizowane i nie działa z przypisaniami ról ani dostosowaniami infrastruktury. Aby uzyskać więcej informacji, zobacz Dodaj istniejące zasoby Azure z parametrami połączenia.

Dodawanie AzureAzure Cosmos DB zasobów bazy danych i kontenerów

.NET Aspire modele relacje nadrzędno-podrzędne między Azure Cosmos DB zasobami. Na przykład AzureAzure Cosmos DB konto (AzureCosmosDBResource) może mieć wiele baz danych (AzureCosmosDBDatabaseResource), a każda baza danych może mieć wiele kontenerów (AzureCosmosDBContainerResource). Podczas dodawania bazy danych lub zasobu kontenera należy to zrobić w zasobie nadrzędnym.

Aby dodać zasób bazy danych AzureAzure Cosmos DB, wywołaj metodę AddCosmosDatabase w wystąpieniu IResourceBuilder<AzureCosmosDBResource>:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Podczas wywoływania AddCosmosDatabaseprogram dodaje bazę danych o nazwie db do zasobów Cosmos DB i zwraca nowo utworzony zasób bazy danych. Baza danych jest tworzona na koncie Cosmos DB, które jest reprezentowane przez AzureCosmosDBResource, który został dodany wcześniej. Baza danych jest kontenerem logicznym dla kolekcji i użytkowników.

Kontener AzureAzure Cosmos DB to miejsce przechowywania danych. Podczas tworzenia kontenera należy podać klucz partycji.

Aby dodać zasób kontenera AzureAzure Cosmos DB, wywołaj metodę AddContainer w wystąpieniu IResourceBuilder<AzureCosmosDBDatabaseResource>:

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

Kontener jest tworzony w bazie danych, którą reprezentuje wcześniej dodany AzureCosmosDBDatabaseResource. Aby uzyskać więcej informacji, zobacz Bazy danych, kontenery i elementy w AzureAzure Cosmos DB.

Przykład relacji zasobu nadrzędnego i podrzędnego

Aby lepiej zrozumieć relację nadrzędny-podrzędny między Azure Cosmos DB zasobami, rozważmy następujący przykład, który pokazuje dodawanie Azure Cosmos DB zasobu wraz z bazą danych i kontenerem:

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

Powyższy kod dodaje AzureAzure Cosmos DB zasób o nazwie cosmos z dwoma bazami danych: customers i orders. Baza customers danych ma jeden kontener o nazwie profiles, a orders baza danych ma dwa kontenery: details i history. Klucz partycji dla każdego kontenera to /id.

Na poniższym diagramie przedstawiono relację nadrzędności-podrzędności między zasobami Azure a Azure Cosmos DB.

Diagram przedstawiający relacje nadrzędno-podrzędne zasobów AzureAzure Cosmos DB.

Gdy kod hosta aplikacji wyraża relacje nadrzędny-podrzędny, klient może tworzyć bezpośrednie łącza do tych zasobów według nazwy. Na przykład można odwoływać się do bazy danych customers według nazwy w projekcie klienta, rejestrując wystąpienie Database łączące się z bazą danych customers. To samo dotyczy nazwanych kontenerów, na przykład można odwoływać się do kontenera details według nazwy w projekcie klienta, rejestrując instancję Container, która łączy się z kontenerem details.

Dodawanie zasobu emulatora AzureAzure Cosmos DB

Aby dodać zasób emulatora AzureAzure Cosmos DB, zlinkuj wywołanie IResourceBuilder<AzureCosmosDBResource> z interfejsem API RunAsEmulator.

var builder = DistributedApplication.CreateBuilder(args);

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

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

Podczas wywoływania RunAsEmulatorprogram konfiguruje zasoby Cosmos DB do uruchamiania lokalnego przy użyciu emulatora. Emulator w tym przypadku to AzureAzure Cosmos DB Emulator. Emulator Azure Cosmos DB zapewnia bezpłatne środowisko lokalne do testowania aplikacji Azure Cosmos DB i jest doskonałym towarzyszem integracji .NET AspireAzure hostingu. Emulator nie jest zainstalowany, a zamiast tego jest dostępny do .NET.NET Aspire jako kontener. Po dodaniu kontenera do hosta aplikacji, jak pokazano w poprzednim przykładzie z obrazem mcr.microsoft.com/cosmosdb/emulator, tworzy i uruchamia kontener po uruchomieniu hosta aplikacji. Aby uzyskać więcej informacji, zobacz Cykl życia zasobów kontenera.

Konfigurowanie kontenera emulatora Cosmos DB

Istnieją różne konfiguracje dostępne dla zasobów kontenera, na przykład można skonfigurować porty kontenera, zmienne środowiskowe, jego okres istnienia i nie tylko.

Konfigurowanie portu bramy kontenera emulatora Cosmos DB

Domyślnie kontener emulatora Cosmos DB skonfigurowany przez .NET Aspireuwidacznia następujące punkty końcowe:

Punkt końcowy Port kontenerowy Port główny
https 8081 dynamiczny

Port, na który nasłuchuje, jest domyślnie dynamiczny. Po uruchomieniu kontenera port jest mapowany na losowy port na maszynie hosta. Aby skonfigurować port punktu końcowego, użyj sekwencji wywołań na budowniczym zasobów kontenera dostarczonym przez metodę RunAsEmulator, jak pokazano w poniższym przykładzie:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Powyższy kod konfiguruje istniejący punkt końcowy Cosmos DB kontenera emulatora https do nasłuchiwania na porcie 8081. Port kontenera emulatora Cosmos DB jest mapowany na port hosta, jak pokazano w poniższej tabeli:

Nazwa punktu końcowego Mapowanie portów (container:host)
https 8081:7777
Konfigurowanie kontenera emulatora Cosmos DB z trwałym okresem istnienia

Aby skonfigurować kontener emulatora Cosmos DB z trwałym okresem istnienia, wywołaj metodę WithLifetime w zasobie kontenera emulatora Cosmos DB i przekaż 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...

Aby uzyskać więcej informacji, zobacz Okres istnienia zasobu kontenera.

Konfigurowanie kontenera emulatora Cosmos DB za pomocą woluminu danych

Aby dodać wolumin danych do zasobu emulatora AzureAzure Cosmos DB, wywołaj metodę WithDataVolume w zasobie emulatora AzureAzure Cosmos DB:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Wolumin danych służy do utrwalania danych emulatora Cosmos DB poza cyklem życia kontenera. Wolumen danych jest zamontowany na ścieżce /tmp/cosmos/appdata w kontenerze emulatora Cosmos DB, a gdy nie podano parametru name, generowana jest nazwa. Emulator ma zmienną środowiskową AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE ustawioną na true. Aby uzyskać więcej informacji na temat wolumenów danych i szczegółów na temat tego, dlaczego są preferowane nad podmontowaniami wiążącymi, zobacz dokumentację Docker: Wolumeny.

Konfigurowanie liczby partycji kontenera emulatora Cosmos DB

Aby skonfigurować liczbę partycji kontenera emulatora Cosmos DB, wywołaj metodę WithPartitionCount:

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db").RunAsEmulator(
                     emulator =>
                     {
                         emulator.WithPartitionCount(100); // Defaults to 25
                     });

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

Powyższy kod konfiguruje kontener emulatora Cosmos DB tak, aby miał liczbę partycji 100. Jest to skrót do ustawiania zmiennej środowiskowej AZURE_COSMOS_EMULATOR_PARTITION_COUNT.

Korzystanie z emulatora opartego na Linux(wersja zapoznawcza)

Następna generacja emulatora AzureAzure Cosmos DB jest w pełni oparta na Linux i dostępna jako Docker kontener. Obsługuje on uruchamianie na wielu różnych procesorach i systemach operacyjnych.

Aby użyć wersji zapoznawczej emulatora Cosmos DB, wywołaj metodę RunAsPreviewEmulator. Ponieważ ta funkcja jest dostępna w wersji zapoznawczej, musisz jawnie wyrazić zgodę na jej użycie, pomijając eksperymentalną diagnostykę ASPIRECOSMOSDB001.

Emulator wersji zapoznawczej obsługuje również uwidacznianie punktu końcowego "Eksplorator danych", który umożliwia wyświetlanie danych przechowywanych w emulatorze Cosmos DB za pośrednictwem internetowego interfejsu użytkownika. Aby włączyć Eksplorator danych, wywołaj metodę WithDataExplorer.

#pragma warning disable ASPIRECOSMOSDB001

var builder = DistributedApplication.CreateBuilder(args);

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

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

Powyższy kod konfiguruje podglądowy kontener emulatora oparty na Linux, z punktem końcowym eksploratora danych Cosmos DB, do użycia podczas działania.

Sprawdzanie stanu integracji hostingu

Integracja hostowania Azure Cosmos DB automatycznie dodaje kontrolę kondycji zasobu Cosmos DB. Kontrola stanu sprawdza, czy Cosmos DB jest uruchomione i czy można nawiązać z nim połączenie.

Integracja hostingu opiera się na pakiecie NuGet AspNetCore.HealthChecks.CosmosDb.📦

Client integracja

Aby rozpocząć pracę z integracją klienta .NET AspireAzure Cosmos DB, zainstaluj pakiet NuGet 📦Aspire.Microsoft.Azure.Cosmos w projekcie aplikacji korzystającej z klienta Cosmos DB. Integracja klienta Cosmos DB rejestruje wystąpienie CosmosClient, którego można użyć do interakcji z Cosmos DB.

dotnet add package Aspire.Microsoft.Azure.Cosmos

Dodaj klienta Cosmos DB

W pliku Program.cs projektu wykorzystującego klienta, wywołaj metodę rozszerzenia AddAzureCosmosClient na dowolnym IHostApplicationBuilder, aby zarejestrować CosmosClient do użycia za pośrednictwem kontenera wstrzykiwania zależności. Metoda przyjmuje parametr nazwy połączenia.

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

Napiwek

Parametr connectionName musi być zgodny z nazwą używaną podczas dodawania zasobu Cosmos DB w projekcie hosta aplikacji. Innymi słowy, podczas wywoływania AddAzureCosmosDB, podając nazwę cosmos-db, tej samej nazwy należy użyć podczas wywoływania AddAzureCosmosClient. Aby uzyskać więcej informacji, zobacz Dodawanie AzureAzure Cosmos DB zasobu.

Następnie za pomocą wstrzykiwania zależności można uzyskać instancję CosmosClient. Na przykład aby pobrać klienta z przykładowej usługi:

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

Aby uzyskać więcej informacji o wstrzykiwaniu zależności, odwiedź stronę .NETwstrzykiwanie zależności.

Dodaj klienta Cosmos DB z kluczem

Mogą wystąpić sytuacje, w których chcesz zarejestrować wiele wystąpień CosmosClient z różnymi nazwami połączeń. Aby zarejestrować klientów powiązanych z kluczem Cosmos DB, wywołaj metodę AddKeyedAzureCosmosClient.

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

Ważny

W przypadku korzystania z usług opierających się na kluczach oczekuje się, że zasób Cosmos DB skonfigurował dwie nazwane bazy danych, jedną dla mainDb i drugą dla loggingDb.

Następnie można za pomocą wstrzykiwania zależności uzyskać wystąpienia CosmosClient. Aby na przykład pobrać połączenie z przykładowej usługi:

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

Aby uzyskać więcej informacji na temat usług opartych na kluczach, zobacz .NET wstrzykiwanie zależności: usługi oparte na kluczach.

Dodawanie AzureAzure Cosmos DB bazy danych

Na hoście aplikacji zasób bazy danych (AzureCosmosDBDatabaseResource) można dodać jako podrzędny zasób do elementu nadrzędnego AzureCosmosDBResource. W projekcie używającym klienta możesz tworzyć bezpośrednie połączenie z zasobem bazy danych według nazwy, rejestrując instancję Database do użycia z iniekcją zależności. Rozważmy na przykład następujący kod, który wywołuje AddAzureCosmosDatabase na instancji IHostApplicationBuilder.

builder.AddAzureCosmosDatabase(connectionName: "customers");

Interfejs AddAzureCosmosDatabase API zwraca instancję CosmosDatabaseBuilder, którą można wykorzystać do obsługi wielu kontenerów przez to samo połączenie z bazą danych. Wszystkie kontenery podrzędne współużytkuje to samo CosmosClient oraz instancję CosmosClient bazy danych. Ta strategia jest przydatna podczas kojarzenia tego samego CosmosClientOptions z wieloma kontenerami.

Po wywołaniu metody AddAzureCosmosDatabase można następnie pobrać wystąpienie Database przy użyciu wstrzykiwania zależności. Aby na przykład pobrać bazę danych z delegata w wywołaniu funkcji MapGet, należy rozważyć następujący kod:

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

Dodanie bazy danych indeksowanej według kluczy AzureAzure Cosmos DB

Istnieje również AddKeyedAzureCosmosDatabase interfejs API, który zwraca CosmosDatabaseBuilder wystąpienie, którego można użyć do dołączania wielu kontenerów pod tym samym połączeniem z bazą danych. metoda umożliwiająca zarejestrowanie wielu baz danych przy użyciu różnych nazw połączeń. Rozważmy na przykład następujący kod, który wywołuje AddKeyedAzureCosmosDatabase na instancji IHostApplicationBuilder.

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

Powyższy przykładowy kod pokazuje, jak zarejestrować dwie bazy danych details i customers. Każda nazwana baza danych może być użyta do uzyskania odpowiednich kontenerów w celu przeprowadzania zapytań o dane.

Dodawanie AzureAzure Cosmos DB kontenera

Po dodaniu Cosmos DB zasobu w projekcie hosta aplikacji możesz również dodać zasób kontenera Azure Cosmos DB . Zasób kontenera jest traktowany jako zasób podrzędny dla nadrzędnego zasobu AzureCosmosDBDatabaseResource. W projekcie korzystającym z klienta możesz połączyć się z zasobem kontenera według nazwy, rejestrując instancję Container do użycia w mechanizmie wstrzykiwania zależności. Rozważmy na przykład następujący kod, który wywołuje AddAzureCosmosContainer na instancji IHostApplicationBuilder.

builder.AddAzureCosmosContainer(connectionName: "details");

Następnie za pomocą wstrzykiwania zależności można uzyskać instancję Container. Aby pobrać na przykład kontener z delegata w wywołaniu MapGet, należy wziąć pod uwagę następujący kod:

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

Dodawanie kontenera z kluczem AzureAzure Cosmos DB

Istnieje również AddKeyedAzureCosmosContainer metoda, która umożliwia zarejestrowanie wielu kontenerów przy użyciu różnych nazw połączeń. Rozważmy na przykład następujący kod, który wywołuje AddKeyedAzureCosmosContainer na instancji IHostApplicationBuilder.

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

Jeśli masz wiele kontenerów w ramach tego samego połączenia z bazą danych, możesz użyć interfejsu AddAzureCosmosDatabase API, aby dołączyć wiele kontenerów w ramach tego samego połączenia z bazą danych. Wszystkie kontenery podrzędne współużytkują to samo CosmosClient i połączenie z bazą danych. Ta strategia jest przydatna podczas kojarzenia tego samego CosmosClientOptions z wieloma kontenerami. Rozważmy następujący alternatywny kod, aby zarejestrować wiele kontenerów w ramach tego samego połączenia bazy danych:

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

Powyższy przykładowy kod pokazuje, jak zarejestrować dwie bazy danych, customers i orders, z których każda ma własne kontenery. Baza customers danych ma jeden kontener o nazwie profiles, a orders baza danych ma dwa kontenery o nazwie details i history. Każdy kontener można zapytać indywidualnie przy użyciu odpowiedniego klucza.

Konfiguracja

Integracja .NET AspireAzure Cosmos DB udostępnia wiele opcji konfigurowania połączenia na podstawie wymagań i konwencji projektu.

Użyj łańcucha połączenia

W przypadku używania parametrów połączenia z sekcji konfiguracji ConnectionStrings podczas wywoływania metody AddAzureCosmosClient można podać nazwę parametrów połączenia:

builder.AddAzureCosmosClient("cosmos-db");

Następnie parametry połączenia są pobierane z sekcji konfiguracji ConnectionStrings:

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

Aby uzyskać więcej informacji, zobacz dokumentację ConnectionString.

Korzystanie z dostawców konfiguracji

Integracja .NET AspireAzure Cosmos DB obsługuje Microsoft.Extensions.Configuration. Ładuje MicrosoftAzureCosmosSettings z konfiguracji, używając klucza Aspire:Microsoft:Azure:Cosmos. Poniższy fragment kodu to przykład pliku appsettings.json, który konfiguruje niektóre opcje:

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

Aby uzyskać pełny Cosmos DB schemat integracji klienta JSON, zobacz Aspire.Microsoft.Azure.Cosmos/ConfigurationSchema.json.

Użyj delegatów liniowych

Możesz również przekazać delegata Action<MicrosoftAzureCosmosSettings> configureSettings, aby skonfigurować niektóre lub wszystkie opcje bezpośrednio w kodzie, na przykład w celu wyłączenia śledzenia:

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

Można również skonfigurować Microsoft.Azure.Cosmos.CosmosClientOptions przy użyciu opcjonalnego parametru Action<CosmosClientOptions> configureClientOptions metody AddAzureCosmosClient. Aby na przykład ustawić sufiks nagłówka CosmosClientOptions.ApplicationName user-agent dla wszystkich żądań wydawanych przez tego klienta:

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

Client kontrole stanu integracji

Integracja klienta .NET AspireCosmos DB obecnie nie implementuje kontroli stanu zdrowia, ale może to ulec zmianie w przyszłych wersjach.

Obserwowanie i telemetria

.NET .NET Aspire integracje automatycznie konfigurują konfiguracje rejestrowania, śledzenia i metryk, które są czasami nazywane filarami obserwacji. Aby uzyskać więcej informacji na temat możliwości obserwacji integracji i telemetrii, zobacz .NET.NET Aspire Omówienie integracji. W zależności od usługi pomocniczej niektóre integracje mogą obsługiwać tylko niektóre z tych funkcji. Na przykład niektóre integracje obsługują rejestrowanie i śledzenie, ale nie metryki. Funkcje telemetrii można również wyłączyć przy użyciu technik przedstawionych w sekcji konfiguracji .

Logowanie

Integracja .NET AspireAzure Cosmos DB używa następujących kategorii dzienników:

  • Azure-Cosmos-Operation-Request-Diagnostics

Poza uzyskaniem diagnostyki Azure Cosmos DB dla żądań zakończonych niepowodzeniem, można skonfigurować progi opóźnienia, aby określić, które diagnostyki dotyczące pomyślnych żądań Azure Cosmos DB zostaną zarejestrowane. Wartości domyślne to 100 ms dla operacji punktów i 500 ms dla operacji innych niż punkt.

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

Śledzenie

Integracja .NET AspireAzure Cosmos DB spowoduje emitowanie następujących działań śledzenia przy użyciu OpenTelemetry:

  • Azure.Cosmos.Operation

Azure Azure Cosmos DB funkcja śledzenia jest obecnie w wersji zapoznawczej, dlatego należy ustawić przełącznik eksperymentalny, aby zapewnić emisję śladów.

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

Aby uzyskać więcej informacji, zobacz AzureAzure Cosmos DB Obserwowalność SDK: atrybuty śledzenia.

Metryki

Integracja .NET AspireAzure Cosmos DB obecnie nie obsługuje metryk domyślnie z powodu ograniczeń SDK Azure.

Zobacz też