Udostępnij za pośrednictwem

integracja .NET AspireCosmos DBEntity Framework Core

  • Artykuł

obejmuje:integrację hostingu oraz Client integrację.

Azure Cosmos DB to w pełni zarządzana usługa bazy danych NoSQL na potrzeby nowoczesnego tworzenia aplikacji. Integracja .NET AspireCosmos DBEntity Framework Core 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 modelowanie integracji hostingu różnych zasobów Cosmos DB jako następujące typy:

Aby uzyskać dostęp do tych typów i interfejsów API do ich wyrażania, dodaj pakiet NuGet 📦Aspire.Hosting.Azure.CosmosDB w projekcie 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 aplikacjach .NET.

Dodawanie zasobu AzureAzure Cosmos DB

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

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 dowolnych innych zasobów Cosmos DB.

Ważny

Gdy wywołasz AddAzureCosmosDB, niejawnie wywołuje AddAzureProvisioning, co dodaje to obsługę dynamicznego generowania zasobów Azure podczas uruchamiania aplikacji. Aplikacja musi skonfigurować odpowiednią subskrypcję i lokalizację. Aby uzyskać więcej informacji, zobacz Lokalne udostępnianie: Konfiguracja.

Wygenerowany skrypt aprowizacji Bicep

Jeśli dopiero zaczynasz przygodę z Bicep , jest to język specyficzny dla domeny do definiowania zasobów Azure. W przypadku .NET.NET Aspirenie musisz pisać Bicep ręcznie, zamiast tego interfejsy API aprowizacji generują Bicep. 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 aprowizuje konto AzureAzure Cosmos DB z następującymi wartościami domyślnymi:

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

Oprócz konta Cosmos DB udostępnia 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łniał określone wymagania.

Dostosowywanie infrastruktury aprowizacji

Wszystkie zasoby .NET AspireAzure to podklasy typu AzureProvisioningResource. Ten typ umożliwia dostosowanie wygenerowanej struktury Bicep poprzez dostarczenie płynnego interfejsu API do ustawiania zasobów Azure przy użyciu interfejsu API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Można na przykład skonfigurować kind, consistencyPolicy, locationsi inne. 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 konfiguracji.

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ć łańcuch 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 ramach Wpisy tajne 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ótem 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 dodałeś wcześniej. Baza danych jest kontenerem logicznym dla kolekcji i użytkowników. Więcej informacji znajdziesz w 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, generowaną przez infrastrukturę zarządzania.

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, czas życiai 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, łańcuch wywołań konstruktora zasobów kontenera dostarczonego 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. Wolumin danych jest instalowany w ścieżce /tmp/cosmos/appdata w kontenerze emulatora Cosmos DB, a gdy nie podano parametru name, zostanie wygenerowana 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 zamiast montowania powiązanego, 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.

Kontrole kondycji integracji w hostingu

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

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

integracja Client

Aby rozpocząć pracę z integracją .NET Aspire Microsoft Entity Framework CoreCosmos DB, zainstaluj 📦Aspirepakiet NuGet Microsoft.EntityFrameworkCore.Cosmos w projekcie używającym klienta, tj. w projekcie aplikacji wykorzystującej klienta Microsoft Entity Framework CoreCosmos DB.

dotnet add package Aspire.Microsoft.EntityFrameworkCore.Cosmos

Dodaj kontekst Cosmos DB

W pliku Program.cs projektu korzystającego z klienta wywołaj metodę rozszerzenia AddCosmosDbContext, aby zarejestrować System.Data.Entity.DbContext do użycia za pośrednictwem kontenera wstrzykiwania zależności. Metoda przyjmuje parametr nazwy połączenia.

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

Napiwek

Parametr connectionName musi być zgodny z nazwą używaną podczas dodawania zasobu Cosmos DB w projekcie hosta aplikacji. Innymi słowy, kiedy wywołujesz AddAzureCosmosDB i podajesz nazwę cosmosdb, tej samej nazwy powinieneś użyć podczas wywoływania AddCosmosDbContext. Aby uzyskać więcej informacji, zobacz Dodaj zasób AzureAzure Cosmos DB.

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

public class ExampleService(MyDbContext context)
{
    // Use context...
}

Aby uzyskać więcej informacji na temat używania Entity Framework Core z Azure Cosmos DB, zobacz przykłady dla Azure Cosmos DB dla NoSQL SDK dla .NET.

Konfiguracja

Integracja .NET Aspire Microsoft Entity Framework CoreCosmos DB oferuje wiele opcji konfiguracji połączenia Azure Cosmos DB zgodnie z wymaganiami i konwencjami Twojego projektu.

Używanie parametrów połączenia

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

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

Następnie parametry połączenia zostaną pobrane z sekcji konfiguracji ConnectionStrings:

{
  "ConnectionStrings": {
    "CosmosConnection": "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 Aspire Microsoft Entity Framework CoreCosmos DB obsługuje Microsoft.Extensions.Configuration. Ładuje EntityFrameworkCoreCosmosSettings z plików konfiguracji, takich jak appsettings.json. Przykład _appsettings.json, który konfiguruje niektóre opcje:

{
  "Aspire": {
    "Microsoft": {
      "EntityFrameworkCore": {
        "Cosmos": {
          "DisableTracing": true
        }
      }
    }
  }
}

Aby uzyskać pełny schemat integracji klienta Cosmos DBJSON, sprawdź Aspire.Microsoft.EntityFrameworkCore.Cosmos/ConfigurationSchema.json.

Używanie delegatów wbudowanych

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

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

Client kontrola stanu integracji

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

Integracja .NET Aspire Microsoft Entity Framework CoreCosmos DB obecnie nie implementuje sprawdzania stanu, ale to może się zmienić w przyszłych wersjach.

Obserwowanie i telemetria

.NET .NET Aspire integracje automatycznie ustawiają konfiguracje 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 .

Wyrąb

Integracja .NET Aspire Microsoft Entity Framework CoreCosmos DB używa następujących kategorii logów:

  • Azure-Cosmos-Operation-Request-Diagnostics
  • Microsoft.EntityFrameworkCore.ChangeTracking
  • Microsoft.EntityFrameworkCore.Database.Command
  • Microsoft.EntityFrameworkCore.Infrastructure
  • Microsoft.EntityFrameworkCore.Query

Śledzenie

Integracja .NET Aspire Microsoft Entity Framework CoreCosmos DB będzie emitować następujące czynności śledzące przy użyciu OpenTelemetry:

  • Azure.Cosmos.Operation
  • OpenTelemetry.Instrumentation.EntityFrameworkCore

Wskaźniki

Integracja .NET Aspire Microsoft Entity Framework CoreCosmos DB obecnie obsługuje następujące metryki:

  • Microsoft.EntityFrameworkCore
    • ec_Microsoft_EntityFrameworkCore_active_db_contexts
    • ec_Microsoft_EntityFrameworkCore_total_queries
    • ec_Microsoft_EntityFrameworkCore_queries_per_second
    • ec_Microsoft_EntityFrameworkCore_total_save_changes
    • ec_Microsoft_EntityFrameworkCore_save_changes_per_second
    • ec_Microsoft_EntityFrameworkCore_compiled_query_cache_hit_rate
    • ec_Microsoft_Entity_total_execution_strategy_operation_failures
    • ec_Microsoft_E_execution_strategy_operation_failures_per_second
    • ec_Microsoft_EntityFramew_total_optimistic_concurrency_failures
    • ec_Microsoft_EntityF_optimistic_concurrency_failures_per_second

Zobacz też