.NET Aspire Azure Cosmos DB integrering

Artikel
01/09/2025

omfattar:Hostingintegration och Client integration

Azure Cosmos DB är en fullständigt hanterad NoSQL-databastjänst för modern apputveckling. Med .NET AspireAzure Cosmos DB integrering kan du ansluta till befintliga Cosmos DB-instanser eller skapa nya instanser från .NET med Azure Cosmos DB-emulatorn.

Värdintegrering

.NET .NET Aspire Azure Cosmos DB värdintegrering modellerar de olika Cosmos DB-resurserna som följande typer:

AzureCosmosDBResource: Representerar en AzureAzure Cosmos DB resurs.
AzureCosmosDBEmulatorResource: Representerar en AzureAzure Cosmos DB-emulatorresurs.

Om du vill komma åt dessa typer och API:er för att uttrycka dem, lägger du till 📦Aspire.Hosting.Azure.CosmosDB NuGet-paketet i appvärd-projektet.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.CosmosDB

<PackageReference Include="Aspire.Hosting.Azure.CosmosDB"
                  Version="*" />

Mer information finns i dotnet add package eller Hantera paketberoenden i .NET applikationer.

Lägg till AzureAzure Cosmos DB resurs

I värdprojekt för appen anropar du AddAzureCosmosDB för att lägga till och returnera en resursbyggare för AzureAzure Cosmos DB.

var builder = DistributedApplication.CreateBuilder(args);

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

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

När du lägger till en AzureCosmosDBResource till appvärden exponeras andra användbara API:er för att lägga till databaser och containrar. Med andra ord måste du lägga till en AzureCosmosDBResource innan du lägger till någon av de andra Cosmos DB resurserna.

Viktig

När du anropar AddAzureCosmosDBanropas implicit AddAzureProvisioning– vilket ger stöd för att generera Azure resurser dynamiskt under appstarten. Appen måste konfigurera lämplig prenumeration och plats. För mer information, se Lokal etablering: Konfiguration.

Genererad provisionering av Bicep

Om du är ny till Bicepär det ett domänspecifikt språk för att definiera Azure-resurser. Med .NET.NET Aspirebehöver du inte skriva Bicep för hand, i stället genererar etablerings-API:erna Bicep åt dig. När du publicerar din app genereras Bicep-filen tillsammans med manifestfilen. När du lägger till en AzureAzure Cosmos DB resurs genereras följande Bicep:

Växla 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
}

Föregående Bicep är en modul som etablerar ett AzureAzure Cosmos DB konto med följande standardvärden:

kind: Typen av Cosmos DB konto. Standardvärdet är GlobalDocumentDB.
consistencyPolicy: Konsekvensprincipen för Cosmos DB-kontot. Standardvärdet är Session.
locations: Platserna för Cosmos DB-kontot. Standardvärdet är resursgruppens plats.

Utöver det Cosmos DB-kontot tillhandahåller det även en Azure Key Vault-resurs. Detta används för att lagra Cosmos DB-kontots anslutningssträng på ett säkert sätt. Den genererade Bicep är en startpunkt och kan anpassas för att uppfylla dina specifika krav.

Anpassa försörjningsinfrastruktur

Alla .NET AspireAzure resurser är underklasser av den AzureProvisioningResource typen. Den här typen möjliggör anpassning av den genererade Bicep genom att tillhandahålla ett fluent API för att konfigurera Azure-resurser genom att använda ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>)-API:et. Du kan till exempel konfigurera kind, consistencyPolicy, locationsoch mycket mer. I följande exempel visas hur du anpassar AzureAzure Cosmos DB resursen:

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

Föregående kod:

Kedjar ett anrop till ConfigureInfrastructure-API:et:
- Parametern infra är en instans av den AzureResourceInfrastructure typen.
- De provisionerbara resurserna hämtas genom att anropa metoden GetProvisionableResources().
- Den enda CosmosDBAccount hämtas.
- CosmosDBAccount.ConsistencyPolicy tilldelas till en DefaultConsistencyLevel.Strong.
- En tagg läggs till i Cosmos DB-kontot med nyckeln ExampleKey och värdet Example value.

Det finns många fler konfigurationsalternativ för att anpassa AzureAzure Cosmos DB resursen. Mer information finns i Azure.Provisioning.CosmosDB. Mer information finns i Azure. Anpassning av provisionering.

Ansluta till ett befintligt AzureAzure Cosmos DB konto

Du kan ha ett befintligt AzureAzure Cosmos DB konto som du vill ansluta till. I stället för att representera en ny AzureAzure Cosmos DB resurs kan du lägga till en anslutningssträng till appens värd. Om du vill lägga till en anslutning till ett befintligt AzureAzure Cosmos DB konto anropar du metoden 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...

Notera

Anslutningssträngar används för att representera ett brett spektrum av anslutningsinformation, inklusive databasanslutningar, meddelandeköer, slutpunkts-URI:er och andra tjänster. I .NET.NET Aspire nomenklatur används termen "anslutningssträng" för att representera alla typer av anslutningsinformation.

Anslutningssträngen konfigureras i appvärdens konfiguration, vanligtvis under Användarhemligheter, under avsnittet ConnectionStrings. Appvärden matar in den här anslutningssträngen som en miljövariabel i alla beroende resurser, till exempel:

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

Den beroende resursen kan komma åt den inmatade anslutningssträngen genom att anropa metoden GetConnectionString och skicka anslutningsnamnet som parameter, i det här fallet "cosmos-db". API:et GetConnectionString är en förkortning för IConfiguration.GetSection("ConnectionStrings")[name].

Lägga till AzureAzure Cosmos DB databasresurs

Om du vill lägga till en AzureAzure Cosmos DB databasresurs kedjar du ett anrop på en IResourceBuilder<AzureCosmosDBResource> till AddDatabase-API:et:

var builder = DistributedApplication.CreateBuilder(args);

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

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

När du anropar AddDatabasekonfigureras dina Cosmos DB resurser för att ha en databas med namnet db. Databasen skapas i det Cosmos DB konto som representeras av AzureCosmosDBResource som du lade till tidigare. Databasen är en logisk container för samlingar och användare. Mer information finns i Databaser, containrar och objekt i AzureAzure Cosmos DB.

Notera

Om du använder AddDatabase-API:et för att lägga till en databas i en AzureAzure Cosmos DB resurs, skapas inte databasen i emulatorn om du kör emulatorn. Det här API:et är avsett att inkludera en databas i Bicep som genereras av etableringsinfrastrukturen.

Lägg till AzureAzure Cosmos DB emulatorresurs

Om du vill lägga till en AzureAzure Cosmos DB emulatorresurs kedjar du ett anrop på en IResourceBuilder<AzureCosmosDBResource> till RunAsEmulator-API:et:

var builder = DistributedApplication.CreateBuilder(args);

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

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

När du anropar RunAsEmulatorkonfigureras dina Cosmos DB resurser att köras lokalt med hjälp av en emulator. Emulatorn i det här fallet är AzureAzure Cosmos DB emulatorn. Azure Cosmos DB-Emulatorn ger en kostnadsfri lokal miljö för att testa dina Azure Cosmos DB-applikationer och den är en perfekt följeslagare till .NET AspireAzure värdintegration. Emulatorn är inte installerad, i stället är den tillgänglig för .NET.NET Aspire som en container. När du lägger till en container i appvärden, som visas i föregående exemplet med mcr.microsoft.com/cosmosdb/emulator-bilden, skapas och startas containern när appvärden startar. Mer information finns i Livscykel för containerresurser.

Konfigurera Cosmos DB emulator-container

Det finns olika konfigurationer tillgängliga för containerresurser, till exempel kan du konfigurera containerns portar, miljövariabler, det är livslängdmed mera.

Konfigurera gateway-port för Cosmos DB containern för emulatorn

Som standard exponerar Cosmos DB emulatorcontainern när den konfigureras av .NET Aspireföljande slutpunkter:

Slutpunkt	Containerhamn	Värdport
`https`	8081	dynamisk

Porten som den lyssnar på är dynamisk som standard. När containern startar mappas porten till en slumpmässig port på värddatorn. För att konfigurera slutpunktsporten anropar kedjan containerresursverktyget som tillhandahålls av metoden RunAsEmulator enligt följande exempel:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Föregående kod konfigurerar Cosmos DB emulatorcontainerns befintliga https slutpunkt för att lyssna på port 8081. Cosmos DB-emulatorcontainerns port mappas till värdporten enligt följande tabell:

Slutpunktsnamn	Portmappning (`container:host`)
`https`	`8081:7777`

Konfigurera Cosmos DB emulatorcontainer med beständig livslängd

Om du vill konfigurera Cosmos DB-emulatorcontainern med en beständig livslängd anropar du WithLifetime-metoden på containerresursen Cosmos DB emulator och skickar 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...

För mer information, se Containerresursens livslängd.

Konfigurera Cosmos DB emulatorcontainer med datavolym

Om du vill lägga till en datavolym i AzureAzure Cosmos DB-emulatorresursen anropar du metoden WithDataVolume på AzureAzure Cosmos DB-emulatorresursen:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Datavolymen används för att bevara Cosmos DB emulatordata utanför containerns livscykel. Datavolymen monteras på /tmp/cosmos/appdata-sökvägen i Cosmos DB-emulatorns container, och när en name-parameter inte anges, genereras namnet. Emulatorn har sin AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE miljövariabel inställd på true. Mer information om datavolymer och information om varför de föredras framför bindningsmonteringar finns i Docker dokument: Volymer.

Konfigurera Cosmos DB antal containerpartitioner för emulatorn

Om du vill konfigurera partitionsantalet för containern Cosmos DB emulator anropar du metoden 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...

Föregående kod konfigurerar Cosmos DB-emulatorcontainern till att ha ett partitionsantal på 100. Det här är en förkortning för att ange miljövariabeln AZURE_COSMOS_EMULATOR_PARTITION_COUNT.

Genomför hälsokontroller för integrationsvärd

Azure Cosmos DB värdintegrering lägger automatiskt till en hälsokontroll för den Cosmos DB resursen. Hälsokontrollen verifierar att Cosmos DB är igång och att en anslutning kan upprättas till denna enhet.

Värdintegrering förlitar sig på 📦 AspNetCore.HealthChecks.CosmosDb NuGet-paketet.

Client integrering

Kom igång med .NET AspireAzure Cosmos DB-klientintegrering genom att installera 📦Aspire. Microsoft.Azure. Cosmos NuGet-paket i det klientkrävande projektet, dvs. projektet för det program som använder Cosmos DB-klienten. Cosmos DB-klientintegrering registrerar en CosmosClient instans som du kan använda för att interagera med Cosmos DB.

.NET CLI
PackageReference

dotnet add package Aspire.Microsoft.Azure.Cosmos

<PackageReference Include="Aspire.Microsoft.Azure.Cosmos"
                  Version="*" />

Lägg till Cosmos DB klient

I den Program.cs filen för ditt klientkrävande projekt anropar du AddAzureCosmosClient-tilläggsmetoden på alla IHostApplicationBuilder för att registrera en CosmosClient för användning via containern för beroendeinmatning. Metoden tar en parameter för anslutningsnamn.

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

Tips

Parametern connectionName måste matcha namnet som används när du lägger till Cosmos DB resursen i appvärdprojektet. Med andra ord, när du anropar AddAzureCosmosDB och anger ett namn på cosmos-db ska samma namn användas när du anropar AddAzureCosmosClient. Mer information finns i Lägg till AzureAzure Cosmos DB resurs.

Du kan sedan hämta CosmosClient-instansen med hjälp av beroendeinjektion. Om du till exempel vill hämta anslutningen från en exempeltjänst:

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

Mer information om beroendeinmatning finns i .NET beroendeinmatning.

Lägg till nyckelade Cosmos DB klient

Det kan finnas situationer där du vill registrera flera CosmosClient instanser med olika anslutningsnamn. Om du vill registrera nyckelade Cosmos DB klienter anropar du metoden AddKeyedAzureCosmosClient:

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

Viktig

När du använder nyckelade tjänster förväntas din Cosmos DB resurs ha konfigurerat två namngivna databaser, en för mainDb och en för loggingDb.

Sedan kan du hämta CosmosClient-instanser med hjälp av beroendeinjektion. Om du till exempel vill hämta anslutningen från en exempeltjänst:

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

Mer information om nyckelade tjänster finns i .NET beroendeinjektion: Nyckelade tjänster.

Konfiguration

Den .NET AspireAzure Cosmos DB integreringen innehåller flera alternativ för att konfigurera anslutningen baserat på kraven och konventionerna i ditt projekt.

Använda en anslutningssträng

När du använder en anslutningssträng från ConnectionStrings-konfigurationsavsnittet kan du ange namnet på anslutningssträngen när du anropar metoden AddAzureCosmosClient:

builder.AddAzureCosmosClient("cosmos-db");

Sedan hämtas anslutningssträngen från ConnectionStrings-konfigurationsavsnittet:

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

Mer information om hur du formaterar den här anslutningssträngen finns i dokumentationen om ConnectionString.

Använda konfigurationsprovidrar

.NET Aspire Azure Cosmos DB-integreringen stöder Microsoft.Extensions.Configuration. Den läser in MicrosoftAzureCosmosSettings från konfigurationen med hjälp av Aspire:Microsoft:Azure:Cosmos-nyckeln. Följande kodfragment är ett exempel på en appsettings.json fil som konfigurerar några av alternativen:

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

För det kompletta klientintegreringsschemat Cosmos DBJSON, se Aspire. Microsoft.Azure. Cosmos/ConfigurationSchema.json.

Använda inline-delegater

Du kan också skicka delegeringen Action<MicrosoftAzureCosmosSettings> configureSettings för att konfigurera vissa eller alla alternativ direkt, till exempel för att inaktivera spårning från kod:

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

Du kan också konfigurera Microsoft.Azure.Cosmos.CosmosClientOptions med hjälp av den valfria Action<CosmosClientOptions> configureClientOptions parametern för metoden AddAzureCosmosClient. Om du till exempel vill sätta CosmosClientOptions.ApplicationName-suffixet för 'user-agent'-huvudet för alla förfrågningar som görs av den här klienten:

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

Client hälsokontroller för integrering

Som standard aktiverar .NET.NET Aspire integreringar hälsokontroller för alla tjänster. Mer information finns i översikten över .NET.NET Aspire integreringar.

Integreringen av .NET AspireAzure Cosmos DB:

Lägger till hälsokontrollen när MicrosoftAzureCosmosSettings.DisableTracing är false, vilket innebär ett försök att ansluta till Cosmos DB.
Integrerar med /health HTTP-slutpunkt, som anger att alla registrerade hälsokontroller måste godkännas för att appen ska anses vara redo att acceptera trafik.

Observerbarhet och telemetri

.NET .NET Aspire integreringar konfigurerar automatiskt konfigurationer för loggning, spårning och mått, som ibland kallas grundpelarna för observerbarhet. Mer information om integreringsobservabilitet och telemetri finns i översikten över .NET.NET Aspire integreringar. Beroende på säkerhetskopieringstjänsten kanske vissa integreringar bara stöder vissa av dessa funktioner. Vissa integreringar stöder till exempel loggning och spårning, men inte mått. Telemetrifunktioner kan också inaktiveras med hjälp av de tekniker som visas i avsnittet Configuration.

Skogsavverkning

.NET Aspire Azure Cosmos DB-integreringen använder följande loggkategorier:

Azure-Cosmos-Operation-Request-Diagnostics

Förutom att få Azure Cosmos DB begärandediagnostik för misslyckade begäranden kan du konfigurera tröskelvärden för svarstid för att avgöra vilken lyckad Azure Cosmos DB begärandediagnostik som ska loggas. Standardvärdena är 100 ms för punktåtgärder och 500 ms för åtgärder som inte är punktåtgärder.

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

Spårning

.NET Aspire Azure Cosmos DB-integreringen genererar följande spårningsaktiviteter med hjälp av OpenTelemetry:

Azure.Cosmos.Operation

Azure Azure Cosmos DB spårning är för närvarande i en förhandsversion, så du måste ange den experimentella inställningen för att säkerställa att spårningar genereras.

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

För mer information, se AzureAzure Cosmos DB SDK-produktens observerbarhet: spårningsattribut.

Mått

Den .NET AspireAzure Cosmos DB integreringen stöder för närvarande inte mått som standard på grund av begränsningar med Azure SDK.

Se även

Azure Cosmos DB
översikt över .NET.NET Aspire integreringar
översikt över .NET AspireAzure integreringar
.NET Aspire GitHub lagringsplats

Dela via