Udostępnij za pośrednictwem

integracja .NET AspireAzure Cosmos DB

  • Artykuł

obejmuje: integrację hostingu i integrację Client

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.

Integracja hostingu

.NET .NET Aspire Azure Cosmos DB hostowanie modeli integracji różnych zasobów Cosmos DB jako następujących typów:

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 or Manage package dependencies in .NET applications.

Dodawanie zasobu AzureAzure Cosmos DB

W projekcie hosta aplikacji wywołaj AddAzureCosmosDB, aby dodać i zwrócić AzureAzure Cosmos DB konstruktora 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 uwidacznia 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 AddAzureCosmosDBautomatycznie wywołuje AddAzureProvisioning— co dodaje obsługę dynamicznego generowania zasobów Azure w trakcie uruchamiania aplikacji. Aplikacja musi skonfigurować odpowiednią subskrypcję i lokalizację. Aby uzyskać więcej informacji, zobacz Lokalne przygotowanie: Konfiguracja.

Wygenerowane udostępnianie Bicep

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


przełącz AzureAzure Cosmos DB Bicep. 

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

param keyVaultName string

resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' existing = {
  name: keyVaultName
}

resource cosmos 'Microsoft.DocumentDB/databaseAccounts@2024-08-15' = {
  name: take('cosmos-${uniqueString(resourceGroup().id)}', 44)
  location: location
  properties: {
    locations: [
      {
        locationName: location
        failoverPriority: 0
      }
    ]
    consistencyPolicy: {
      defaultConsistencyLevel: 'Session'
    }
    databaseAccountOfferType: 'Standard'
  }
  kind: 'GlobalDocumentDB'
  tags: {
    'aspire-resource-name': 'cosmos'
  }
}

resource connectionString 'Microsoft.KeyVault/vaults/secrets@2023-07-01' = {
  name: 'connectionString'
  properties: {
    value: 'AccountEndpoint=${cosmos.properties.documentEndpoint};AccountKey=${cosmos.listKeys().primaryMasterKey}'
  }
  parent: keyVault
}

Powyższy Bicep to moduł, który dostarcza następujące wartości domyślne dla konta AzureAzure Cosmos DB.

  • kind: rodzaj konta Cosmos DB. Wartość domyślna to GlobalDocumentDB.
  • consistencyPolicy: polityka spójności konta Cosmos DB. Wartość domyślna to Session.
  • locations: lokalizacje konta Cosmos DB. Wartość domyślna to lokalizacja grupy zasobów.

Oprócz konta Cosmos DB, przygotowuje również zasób Azure Key Vault. Służy do bezpiecznego przechowywania parametrów połączenia konta Cosmos DB. Wygenerowany Bicep jest punktem wyjścia i można go dostosować, aby spełnić określone wymagania.

Dostosowywanie infrastruktury aprowizacji

Wszystkie zasoby .NET AspireAzure to podklasy typu AzureProvisioningResource. Ten typ umożliwia dostosowanie wygenerowanego elementu Bicep przez zapewnienie płynnego interfejsu API do konfigurowania zasobów Azure przy użyciu interfejsu 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. Konfigurowanie aprowizacji.

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. Zamiast reprezentować nowy zasób AzureAzure Cosmos DB, można dodać ciąg połączenia do hosta aplikacji. Aby dodać połączenie z istniejącym kontem AzureAzure Cosmos DB, wywołaj metodę AddConnectionString:

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

Notatka

Parametry połączenia służą do reprezentowania szerokiego zakresu informacji o połączeniu, w tym połączeń z bazą danych, brokerów komunikatów, identyfikatorów URI punktów końcowych i innych usług. W .NET.NET Aspire nomenklaturze termin "parametry połączenia" służy do reprezentowania wszelkich informacji o połączeniu.

Ciąg połączenia jest konfigurowany w konfiguracji hosta aplikacji, zazwyczaj w obszarze Tajne dane użytkownika, w sekcji ConnectionStrings. Host aplikacji wprowadza te parametry połączenia jako zmienną środowiskową do wszystkich zasobów zależnych, na przykład:

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

Zasób zależny może uzyskać dostęp do wstrzykiwanych parametrów połączenia, wywołując metodę GetConnectionString i przekazując nazwę połączenia jako parametr, w tym przypadku "cosmos-db". Interfejs API GetConnectionString jest skrócony dla IConfiguration.GetSection("ConnectionStrings")[name].

Dodawanie zasobu bazy danych AzureAzure Cosmos DB

Aby dodać zasób bazy danych AzureAzure Cosmos DB, połącz wywołanie IResourceBuilder<AzureCosmosDBResource> z interfejsem API AddDatabase:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Podczas wywoływania AddDatabaseprogram konfiguruje zasoby Cosmos DB tak, aby baza danych miała nazwę db. 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. Aby uzyskać więcej informacji, zobacz Bazy danych, kontenery i elementy w AzureAzure Cosmos DB.

Notatka

Jeśli używasz interfejsu API AddDatabase do dodawania bazy danych do zasobu AzureAzure Cosmos DB, jeśli używasz emulatora, baza danych nie jest w rzeczywistości tworzona w emulatorze. Ten interfejs API ma obejmować bazę danych w Bicep wygenerowaną przez infrastrukturę aprowizacji.

Dodawanie zasobu emulatora AzureAzure Cosmos DB

Aby dodać zasób emulatora AzureAzure Cosmos DB, połącz 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 żywotność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 hosta
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.

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 korzystającego z 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 zasobu AzureAzure Cosmos DB.

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

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

Aby uzyskać więcej informacji o wstrzykiwaniu zależności, zobacz .NET.

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 klucza 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 pobrać wystąpienia CosmosClient za pomocą wstrzykiwania zależności. 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 kluczy, zobacz .NET wstrzykiwanie zależności: usługi kluczy.

Konfiguracja

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

Używanie parametrów 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 na temat formatowania tych parametrów połączenia, zobacz dokumentację ConnectionString.

Korzystanie z dostawców konfiguracji

Integracja .NET AspireAzure Cosmos DB obsługuje Microsoft.Extensions.Configuration. Ładuje MicrosoftAzureCosmosSettings z konfiguracji przy użyciu 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 schemat integracji klienta Cosmos DBJSON, zobacz Aspire. Microsoft.Azure. Cosmos/ConfigurationSchema.json.

Użyj delegatów wbudowanych

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ń wysyłanych przez tego klienta:

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

Client kontrole stanu integracji

Domyślnie .NET.NET Aspire integracje umożliwiają sprawdzanie kondycji wszystkich usług. Aby uzyskać więcej informacji, zobacz omówienie integracji .NET.NET Aspire.

Integracja .NET AspireAzure Cosmos DB:

  • Dodaje kontrolę stanu, gdy MicrosoftAzureCosmosSettings.DisableTracing jest falsei próbuje nawiązać połączenie z Cosmos DB.
  • Integruje się z punktem końcowym /health HTTP, który określa, że wszystkie zarejestrowane kontrole stanu zdrowia muszą zostać zaliczone, aby aplikacja została uznana za gotową do akceptowania ruchu.

Obserwowanie i telemetria

.NET .NET Aspire integracje automatycznie konfigurują ustawienia rejestrowania, śledzenia i metryk, które są czasami nazywane filarami obserwowalności. Aby uzyskać więcej informacji na temat możliwości obserwacji integracji i telemetrii, zobacz omówienie integracji .NET.NET Aspire. 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 śledzenie jest obecnie w wersji zapoznawczej, dlatego należy ustawić przełącznik eksperymentalny, aby upewnić się, że ślady są emitowane.

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

Aby uzyskać więcej informacji, zobacz AzureAzure Cosmos DB SDK możliwości obserwowania: atrybuty śledzenia.

Metryki

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

Zobacz też