Sdílet prostřednictvím

integrace .NET AspireAzure Cosmos DB

  • Článek

zahrnuje: integraci hostování a Client integraci

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í

Integrační modely hostingu popisují různé prostředky 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 balíček NuGet do 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řidat zdroj AzureAzure Cosmos DB

V projektu hostitele aplikace zavolejte AddAzureCosmosDB ke přidání a vrácení generátoru 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é nastavení Bicep

Pokud začínáte s Bicep, je to doménově specifický jazyk k 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:

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

param principalType string

param principalId string

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

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
}

output connectionString string = cosmos.properties.documentEndpoint

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 lokace skupiny prostředků.

Kromě účtu Cosmos DB přidá také aktuální aplikaci do role Data Contributor pro účet 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 poskytováním plynulého API pro konfiguraci Azure zdrojů pomocí 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 vytváření nového prostředku AzureAzure Cosmos DB můžete k hostiteli aplikace přidat řetězec připojení. 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 injektuje tento připojovací řetězec jako proměnnou prostředí například do všech závislých prostředků:

{
    "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". API rozhraní GetConnectionString je zkratka pro IConfiguration.GetSection("ConnectionStrings")[name].

Přidejte AzureAzure Cosmos DB prostředky databáze a kontejneru

Pokud chcete přidat prostředek databáze AzureAzure Cosmos DB, zavolejte metodu AddCosmosDatabase na instanci IResourceBuilder<AzureCosmosDBResource>.

var builder = DistributedApplication.CreateBuilder(args);

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

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

Při volání AddCosmosDatabasepřidá do prostředků db databázi s názvem Cosmos DB a vrátí nově vytvořený databázový prostředek. 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.

V kontejneru AzureAzure Cosmos DB jsou uložená data. Při vytváření kontejneru je potřeba zadat klíč oddílu.

Pokud chcete přidat prostředek kontejneru AzureAzure Cosmos DB, zavolejte metodu AddContainer na instanci IResourceBuilder<AzureCosmosDBDatabaseResource>.

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db");
var db = cosmos.AddCosmosDatabase("db");
db.AddContainer("entries", "/id");

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

Kontejner se vytvoří v databázi, která je reprezentovaná AzureCosmosDBDatabaseResource, kterou jste přidali dříve.

Další informace naleznete v tématu Databáze, kontejnery a položky v AzureAzure Cosmos DB.

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 naleznete v části životní cyklus kontejnerových prostředků.

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 Životnosti kontejneru.

Nakonfigurujte kontejner 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č se upřednostňují před svazky připojenými pomocí mount, 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.

Použijte emulátor založený na Linux(náhled)

Další generace emulátoru AzureAzure Cosmos DB je zcela na bázi Linux a je k dispozici jako kontejner Docker. Podporuje spouštění na široké škále procesorů a operačních systémů.

Pokud chcete použít verzi Preview emulátoru Cosmos DB, zavolejte metodu RunAsPreviewEmulator. Vzhledem k tomu, že je tato funkce ve verzi Preview, musíte explicitně povolit tuto verzi potlačením experimentální diagnostiky ASPIRECOSMOSDB001.

Emulátor verze Preview také podporuje zpřístupnění koncového bodu „Průzkumník dat“, který umožňuje zobrazit data uložená v emulátoru Cosmos DB prostřednictvím webovým uživatelským rozhraním. Chcete-li povolit Průzkumníka dat, zavolejte metodu 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...

Předchozí kód nakonfiguruje kontejner emulátoru Linux-založeného náhledu Cosmos DB s koncovým bodem „Průzkumníka dat“ pro použití během běhu programu.

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řidat klienta Cosmos DB s přiřazeným klíčem.

Mohou nastat situace, 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,
        }
      }
    }
  }
}

Pro úplné schéma integrace klienta viz Cosmos DBJSONAspire.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 klienta .NET AspireCosmos DB v současné době neimplementuje kontroly stavu, i když se to může v budoucích verzích změnit.

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

Pro více informací se podívejte na AzureAzure Cosmos DB pozorovatelnost SDK: Atributy trasování.

Ukazatele

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é