Dela via


.NET Aspire Azure Cosmos DB integrering

omfattar: Hosting-integration och Client integrering

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:

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

dotnet add package Aspire.Hosting.Azure.CosmosDB

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

Lägg till AzureAzure Cosmos DB resurs

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

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 i appens värd 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:

@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

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.

Förutom Cosmos DB-kontot lägger det också till det aktuella programmet i Data Contributor-rollen för Cosmos DB-kontot. Den genererade Bicep är en startpunkt och kan anpassas för att uppfylla dina specifika krav.

Anpassa infrastruktur för tillhandahållande

Alla .NET AspireAzure resurser är underklasser av den AzureProvisioningResource typen. Den här typen möjliggör anpassning av den genererade Bicep genom att erbjuda ett flytande API för att konfigurera Azure-resurser med hjälp av 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:

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 databas- och containerresurser

Om du vill lägga till en AzureAzure Cosmos DB databasresurs anropar du metoden AddCosmosDatabase på en IResourceBuilder<AzureCosmosDBResource>-instans:

var builder = DistributedApplication.CreateBuilder(args);

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

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

När du anropar AddCosmosDatabaselägger den till en databas med namnet db till dina Cosmos DB resurser och returnerar den nyligen skapade databasresursen. 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.

En AzureAzure Cosmos DB container är där data lagras. När du skapar en container måste du ange en partitionsnyckel.

Om du vill lägga till en AzureAzure Cosmos DB containerresurs anropar du metoden AddContainer på en IResourceBuilder<AzureCosmosDBDatabaseResource>-instans:

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

Containern skapas i databasen som representeras av AzureCosmosDBDatabaseResource som du lade till tidigare.

Mer information finns i Databaser, containrar och objekt i AzureAzure Cosmos DB.

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 Hostport
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 vid sökvägen /tmp/cosmos/appdata i emulatorcontainern Cosmos DB och om parametern name inte anges genereras namnet. Emulatorn har sin AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE miljövariabel inställd på true. Mer information om datavolymer och om varför de föredras framför bind-montering 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.

Använda Linux-baserad emulator (förhandsversion)

nästa generation av AzureAzure Cosmos DB-emulatorn är helt Linux-baserad och är tillgänglig som en Docker container. Den stöder körning på en mängd olika processorer och operativsystem.

Om du vill använda förhandsversionen av Cosmos DB-emulatorn anropar du metoden RunAsPreviewEmulator. Eftersom den här funktionen är i förhandsversion måste du uttryckligen välja förhandsgranskningsfunktionen genom att utelämna ASPIRECOSMOSDB001 experimentell diagnostik.

Förhandsgranskningsemulatorn har också stöd för att exponera en slutpunkt för "Datautforskaren" som gör att du kan visa data som lagras i Cosmos DB-emulatorn via ett webbgränssnitt. Om du vill aktivera Datautforskaren anropar du metoden 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...

Den föregående koden konfigurerar den Linux-baserade förhandsgransknings-emulatorcontainern, med datautforskarens slutpunkt, för användning vid körning.

Hälsokontroller för värdintegration

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ärdintegreringen förlitar sig på NuGet-paketet 📦 AspNetCore.HealthChecks.CosmosDb.

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.

dotnet add package Aspire.Microsoft.Azure.Cosmos

Lägg till Cosmos DB klient

I Program.cs-filen för ditt klientkonsumerande projekt anropar du AddAzureCosmosClient-tilläggsmetoden på valfri IHostApplicationBuilder för att registrera en CosmosClient för användning via beroendeinjektionscontainern. 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 klient med nyckel Cosmos DB

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 med beroendeinjektion hämta CosmosClient-instanser. 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änd 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

Den .NET AspireCosmos DB klientintegration implementerar för närvarande inte hälsokontroller, dock kan detta ändras i framtida versioner.

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