Sdílet prostřednictvím

integrace .NET AspireAzure Cosmos DB

  • Článek

zahrnuje:integrace hostování a integrace Client

Azure Cosmos DB je plně spravovaná databázová služba NoSQL pro moderní vývoj aplikací. Integrace .NET AspireAzure Cosmos DB umožňuje připojit se k existujícím instancím Cosmos DB nebo vytvářet nové instance z .NET pomocí emulátoru Azure Cosmos DB.

Integrace hostování

.NET .NET Aspire Azure Cosmos DB integrační modely hostování různých Cosmos DB prostředků jako následující typy:

Pokud chcete získat přístup k těmto typům a rozhraním API pro jejich vyjádření, přidejte 📦Aspire.Hosting.Azure.CosmosDB NuGet balíček v projektu hostitele aplikace .

dotnet add package Aspire.Hosting.Azure.CosmosDB

Pro další informace, viz dotnet add package nebo Správa závislostí balíčků v .NET aplikacích.

Přidejte prostředek AzureAzure Cosmos DB

V projektu hostitele aplikace zavolejte AddAzureCosmosDB, abyste přidali a vrátili tvůrce prostředků AzureAzure Cosmos DB.

var builder = DistributedApplication.CreateBuilder(args);

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

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

Když do hostitele aplikace přidáte AzureCosmosDBResource, zveřejní další užitečná rozhraní API pro přidání databází a kontejnerů. Jinými slovy, musíte přidat AzureCosmosDBResource před přidáním některého z dalších Cosmos DB prostředků.

Důležitý

Když voláte AddAzureCosmosDB, implicitně volá AddAzureProvisioning– což umožňuje dynamické generování Azure prostředků během spouštění aplikace. Aplikace musí nakonfigurovat příslušné předplatné a umístění. Pro více informací si přečtěte Místní zřizování: Konfigurace.

Vygenerované zřizování Bicep

Pokud s Bicep začínáte, jedná se o jazyk specifický pro doménu pro definování Azure prostředků. S .NET.NET Aspirenemusíte psát Bicep ručně; místo toho rozhraní pro zřizování API vytváří Bicep za vás. Když publikujete aplikaci, vygenerovaný soubor Bicep je součástí výstupu společně se souborem manifestu. Při přidání prostředku AzureAzure Cosmos DB se vygeneruje následující Bicep:


přepnout 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
}

Předcházející modul Bicep zřizuje účet AzureAzure Cosmos DB s následujícími výchozími hodnotami:

  • kind: Druh účtu Cosmos DB. Výchozí hodnota je GlobalDocumentDB.
  • consistencyPolicy: Zásady konzistence účtu Cosmos DB. Výchozí hodnota je Session.
  • locations: Umístění účtu Cosmos DB. Výchozí hodnota je umístění skupiny prostředků.

Kromě účtu Cosmos DB zřizuje také zdroj Azure Key Vault. Slouží k bezpečnému uložení připojovacího řetězce účtu Cosmos DB. Vygenerovaný Bicep je výchozím bodem a můžete ho přizpůsobit tak, aby splňoval vaše konkrétní požadavky.

Přizpůsobení infrastruktury zřizování

Všechny zdroje .NET AspireAzure jsou podtřídy typu AzureProvisioningResource. Tento typ umožňuje přizpůsobení vygenerovaného Bicep tím, že poskytuje plynulé API pro konfiguraci Azure zdrojů s API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Můžete například nakonfigurovat kind, consistencyPolicy, locationsatd. Následující příklad ukazuje, jak přizpůsobit prostředek 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");
    });

Předchozí kód:

Pro přizpůsobení prostředku AzureAzure Cosmos DB je k dispozici mnoho dalších možností konfigurace. Další informace najdete v tématu Azure.Provisioning.CosmosDB. Další informace naleznete v Azure. Přizpůsobení nastavení.

Připojení k existujícímu účtu AzureAzure Cosmos DB

Možná máte existující účet AzureAzure Cosmos DB, ke kterému se chcete připojit. Místo toho, abyste představovali nový prostředek AzureAzure Cosmos DB, můžete k hostiteli aplikace přidat připojovací řetězec. Pokud chcete přidat připojení k existujícímu účtu AzureAzure Cosmos DB, zavolejte metodu 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...

Poznámka

Připojovací řetězce se používají k reprezentaci široké škály informací o připojení, včetně databázových připojení, zprostředkovatelů zpráv, identifikátorů URI koncových bodů a dalších služeb. V .NET.NET Aspire terminologii se výraz "připojovací řetězec" používá k reprezentaci jakéhokoli druhu informací o připojení.

Připojovací řetězec se konfiguruje v konfiguraci hostitele aplikace, obvykle v části Tajné kódy uživatelův části ConnectionStrings. Hostitel aplikace vloží tento připojovací řetězec jako proměnnou prostředí do všech závislých prostředků, například:

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

Závislý prostředek má přístup k vloženému připojovacímu řetězci zavoláním metody GetConnectionString a předáním názvu připojení jako parametru, v tomto případě, "cosmos-db". Rozhraní API GetConnectionString je zkratka pro IConfiguration.GetSection("ConnectionStrings")[name].

Přidat prostředek databáze AzureAzure Cosmos DB

Pokud chcete přidat prostředek databáze AzureAzure Cosmos DB, zřetězte volání IResourceBuilder<AzureCosmosDBResource> do rozhraní API AddDatabase:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Při volání AddDatabasenakonfiguruje prostředky Cosmos DB tak, aby měly databázi s názvem db. Databáze se vytvoří v účtu Cosmos DB, který je reprezentován hodnotou AzureCosmosDBResource, kterou jste přidali dříve. Databáze je logický kontejner pro kolekce a uživatele. Další informace naleznete v tématu Databáze, kontejnery a položky v AzureAzure Cosmos DB.

Poznámka

Pokud k přidání databáze do prostředku AddDatabaseAzure používáte rozhraní API Azure Cosmos DB, databáze se ve skutečnosti nevytvořila v emulátoru. Toto rozhraní API je určeno k tomu, aby zahrnovalo databázi generovanou v Biceps na základě zřizovací infrastruktury.

Přidejte prostředek emulátoru AzureAzure Cosmos DB

Pokud chcete přidat prostředek emulátoru AzureAzure Cosmos DB, zřetězte volání IResourceBuilder<AzureCosmosDBResource> do rozhraní API RunAsEmulator:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Při volání RunAsEmulatornakonfiguruje prostředky Cosmos DB tak, aby se spouštěly místně pomocí emulátoru. Emulátor v tomto případě je AzureAzure Cosmos DB emulátor. Emulátor Azure Cosmos DB poskytuje bezplatné místní prostředí pro testování vašich Azure Cosmos DB aplikací a je to dokonalý doplněk k integraci .NET AspireAzure hostování. Emulátor není nainstalovaný, ale je přístupný pro .NET.NET Aspire jako kontejner. Když do hostitele aplikace přidáte kontejner, jak je znázorněno v předchozím příkladu s imagí mcr.microsoft.com/cosmosdb/emulator, vytvoří a spustí kontejner při spuštění hostitele aplikace. Další informace najdete v části životní cyklus prostředků kontejneru.

Konfigurace kontejneru emulátoru Cosmos DB

Pro prostředky kontejneru jsou k dispozici různé konfigurace, například můžete nakonfigurovat porty kontejneru, proměnné prostředí, životnostatd.

Konfigurace portu brány kontejneru emulátoru Cosmos DB

Ve výchozím nastavení kontejner emulátoru Cosmos DB při konfiguraci .NET Aspirezveřejňuje následující koncové body:

Koncový bod Kontejnerový přístav Port hostitele
https 8081 dynamický

Port, na který naslouchá, je ve výchozím nastavení dynamický. Když se kontejner spustí, port je mapován na náhodný port na hostitelském počítači. Pokud chcete nakonfigurovat port koncového bodu, zřetězte volání tvůrce prostředků kontejneru, který poskytuje metoda RunAsEmulator, jak je znázorněno v následujícím příkladu:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Předchozí kód nakonfiguruje existující Cosmos DB koncový bod kontejneru emulátoru https tak, aby naslouchal na portu 8081. Port kontejneru emulátoru Cosmos DB se mapuje na port hostitele, jak je znázorněno v následující tabulce:

Název koncového bodu Mapování portů (container:host)
https 8081:7777
Konfigurace kontejneru emulátoru Cosmos DB s trvalou životností

Pokud chcete nakonfigurovat kontejner emulátoru Cosmos DB s trvalou životností, zavolejte metodu WithLifetime v prostředku kontejneru emulátoru Cosmos DB a předejte 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...

Další informace najdete v tématu Životnost prostředků kontejneru.

Konfigurace kontejneru emulátoru Cosmos DB s datovým svazkem

Pokud chcete přidat datový svazek do prostředku emulátoru AzureAzure Cosmos DB, zavolejte metodu WithDataVolume prostředku emulátoru 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...

Datový svazek slouží k zachování dat emulátoru Cosmos DB mimo životní cyklus kontejneru. Datový svazek se připojí k cestě /tmp/cosmos/appdata v kontejneru emulátoru Cosmos DB a pokud není zadaný parametr name, vygeneruje se název. Emulátor má svou AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE proměnnou prostředí nastavenou na true. Další informace o datových svazcích a podrobnosti o tom, proč jsou preferovány před vazebnými připojeními, najdete v dokumentaci Docker: Svazky.

Konfigurace počtu oddílů kontejneru emulátoru Cosmos DB

Pokud chcete nakonfigurovat počet oddílů kontejneru emulátoru Cosmos DB, zavolejte metodu 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...

Předchozí kód nakonfiguruje kontejner emulátoru Cosmos DB tak, aby měl počet oddílů 100. Toto je zkratka pro nastavení proměnné prostředí AZURE_COSMOS_EMULATOR_PARTITION_COUNT.

Hostování kontrol stavu integrace

Integrace hostování Azure Cosmos DB automaticky přidá kontrolu stavu prostředku Cosmos DB. Kontrola stavu ověřuje, že Cosmos DB běží a že k němu lze navázat připojení.

Integrace hostování spoléhá na balíček NuGet AspNetCore.HealthChecks.CosmosDb.

Client integrace

Pokud chcete začít s integrací klienta .NET AspireAzure Cosmos DB, nainstalujte 📦Aspire.Microsoft.Azure.Cosmos NuGet package v projektu, který využívá klienta, tj. v projektu aplikace, která používá klienta Cosmos DB. Integrace klienta Cosmos DB registruje instanci CosmosClient, kterou můžete použít k interakci s Cosmos DB.

dotnet add package Aspire.Microsoft.Azure.Cosmos

Přidání klienta Cosmos DB

V souboru Program.cs projektu, který využívá klienta, zavolejte metodu rozšíření AddAzureCosmosClient na libovolném IHostApplicationBuilder a zaregistrujte CosmosClient pro použití prostřednictvím kontejneru injektáže závislostí. Metoda přebírá parametr názvu připojení.

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

Spropitné

Parametr connectionName se musí shodovat s názvem použitým při přidávání prostředku Cosmos DB do hostitelského projektu aplikace. Jinými slovy, když voláte AddAzureCosmosDB a zadáte název cosmos-db, tento název by měl být použit při volání AddAzureCosmosClient. Další informace najdete v tématu Přidání AzureAzure Cosmos DB prostředku.

Potom můžete načíst instanci CosmosClient pomocí injektování závislostí. Například, pokud chcete načíst připojení z ukázkové služby:

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

Další informace o injektáži závislostí najdete v tématu .NET injektáž závislostí.

Přidání klienta Cosmos DB s klíči

V situacích, kdy chcete zaregistrovat více instancí CosmosClient s různými názvy připojení. Pokud chcete zaregistrovat klíčované klienty Cosmos DB, zavolejte metodu AddKeyedAzureCosmosClient:

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

Důležitý

Při použití služeb s klíči se očekává, že váš prostředek Cosmos DB nakonfiguroval dvě pojmenované databáze, jednu pro mainDb a druhou pro loggingDb.

Potom můžete instance CosmosClient načíst pomocí injektování závislostí. Například, pokud chcete načíst připojení z ukázkové služby:

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

Další informace o klíčových službách najdete v tématu .NET injektáž závislostí: Služby s klíči.

Konfigurace

Integrace .NET AspireAzure Cosmos DB poskytuje několik možností konfigurace připojení na základě požadavků a konvencí projektu.

Použijte připojovací řetězec

Při použití připojovacího řetězce z oddílu konfigurace ConnectionStrings můžete při volání metody AddAzureCosmosClient zadat název připojovacího řetězce:

builder.AddAzureCosmosClient("cosmos-db");

Řetězec připojení se pak načte z oddílu konfigurace ConnectionStrings.

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

Další informace o formátování tohoto připojovacího řetězce naleznete v dokumentaci ConnectionString.

Použití zprostředkovatelů konfigurace

Integrace .NET AspireAzure Cosmos DB podporuje Microsoft.Extensions.Configuration. Načte MicrosoftAzureCosmosSettings z konfigurace pomocí klíče Aspire:Microsoft:Azure:Cosmos. Následující fragment kódu je příkladem souboru appsettings.json, který konfiguruje některé z možností:

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

Kompletní schéma integrace klienta Cosmos DBJSON viz Aspire. Microsoft.Azure. Cosmos/ConfigurationSchema.json.

Použití vložených delegátů

Můžete také předat delegáta Action<MicrosoftAzureCosmosSettings> configureSettings pro nastavení některých nebo všech možností přímo, například k zakázání trasování z kódu:

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

Můžete také nastavit Microsoft.Azure.Cosmos.CosmosClientOptions pomocí volitelného parametru Action<CosmosClientOptions> configureClientOptions metody AddAzureCosmosClient. Pokud chcete například nastavit příponu hlavičky uživatelského agenta CosmosClientOptions.ApplicationName pro všechny požadavky, které tento klient odesílá:

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

Client kontroly stavu integrace

Integrace .NET.NET Aspire ve výchozím nastavení umožňují kontroly stavu pro všechny služby. Další informace naleznete v tématu .NET.NET Aspire přehled integrací.

Integrace .NET AspireAzure Cosmos DB:

  • Přidá kontrolu stavu, když je MicrosoftAzureCosmosSettings.DisableTracingfalse, který se pokusí připojit k Cosmos DB.
  • Integruje se s koncovým bodem /health HTTP, který určuje, že všechny registrované kontroly stavu musí procházet, aby aplikace byla považována za připravenou přijímat provoz.

Pozorovatelnost a telemetrie

.NET .NET Aspire integrace automaticky nastaví konfigurace protokolování, trasování a metriky, které se někdy označují jako pilíře pozorovatelnosti. Další informace o pozorovatelnosti a telemetrii integrace najdete v přehledu integrace .NET.NET Aspire. V závislosti na zálohovací službě můžou některé integrace podporovat pouze některé z těchto funkcí. Například některé integrace podporují protokolování a trasování, ale ne metriky. Funkce telemetrie je také možné zakázat pomocí technik uvedených v části Konfigurace.

Protokolování

Integrace .NET AspireAzure Cosmos DB používá následující kategorie protokolů:

  • Azure-Cosmos-Operation-Request-Diagnostics

Kromě získání diagnostiky požadavků Azure Cosmos DB pro neúspěšné požadavky můžete nakonfigurovat prahové hodnoty latence, abyste zjistili, která úspěšná diagnostika požadavků Azure Cosmos DB se zaznamenají. Výchozí hodnoty jsou 100 ms pro operace bodu a 500 ms pro operace bez bodu.

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

Trasování

Integrace .NET AspireAzure Cosmos DB pomocí OpenTelemetryvygeneruje následující aktivity trasování:

  • Azure.Cosmos.Operation

Azure Azure Cosmos DB trasování je aktuálně ve verzi Preview, takže je nutné nastavit experimentální přepínač, aby se zajistilo, že se trasování vygeneruje.

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

Další informace najdete v tématu observabilita AzureAzure Cosmos DB SDK: Atributy trasování.

Metriky

Integrace .NET AspireAzure Cosmos DB v současné době nepodporuje metriky ve výchozím nastavení kvůli omezením sady Azure SDK.

Viz také