Aspire Azure Cosmos DB integrering

Inkluderar:Värdintegrering ingår Värdintegrering &–& integrering ingår integration

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

Om du letar efter Entity Framework Core-integrationen, se AspireCosmos DBEntity Framework Core-integrationen.

Värdintegrering

Värdtjänstintegrering AspireAzure Cosmos DB modellerar de olika Cosmos DB resurserna som följande typer:

• AzureCosmosDBResource: Representerar en AzureAzure Cosmos DB resurs.
• AzureCosmosDBContainerResource: Representerar en resurs för AzureAzure Cosmos DB container.
• AzureCosmosDBDatabaseResource: Företräder en AzureAzure Cosmos DB databasresurs.
• AzureCosmosDBEmulatorResource: Representerar en resurs för AzureAzure Cosmos DB-emulator.

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

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 ditt AppHost-projekt 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 AppHost 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.

Ansluta till ett befintligt AzureAzure Cosmos DB konto

Du kan ha ett befintligt AzureAzure Cosmos DB konto som du vill ansluta till. Du kan kedja en anropning för att annotera att din AzureCosmosDBResource är en befintlig resurs:

var builder = DistributedApplication.CreateBuilder(args);

var existingCosmosName = builder.AddParameter("existingCosmosName");
var existingCosmosResourceGroup = builder.AddParameter("existingCosmosResourceGroup");

var cosmos = builder.AddAzureCosmosDB("cosmos-db")
                    .AsExisting(existingCosmosName, existingCosmosResourceGroup);

builder.AddProject<Projects.WebApplication>("web")
       .WithReference(cosmos);

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

Mer information om hur du behandlar AzureAzure Cosmos DB resurser som befintliga resurser finns i Använd befintliga Azure resurser.

Lägga till AzureAzure Cosmos DB databas- och containerresurser

Aspire modellerar överordnade-underordnade relationer mellan Azure Cosmos DB resurser. Ett konto () kan till exempel AzureAzure Cosmos DB ha flera databaser (AzureCosmosDBResource) och varje databas kan ha flera containrar (AzureCosmosDBDatabaseResource).AzureCosmosDBContainerResource När du lägger till en databas- eller containerresurs gör du det på en överordnad resurs.

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");
var 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");
var container = 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.

Exempel på förälder-barn resursrelation

För att bättre förstå relationen mellan Azure Cosmos DB överordnade och underordnade resurser kan du titta på följande exempel, som visar hur du lägger till en Azure Cosmos DB resurs tillsammans med en databas och container:

var builder = DistributedApplication.CreateBuilder(args);

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

var customers = cosmos.AddCosmosDatabase("customers");
var profiles = customers.AddContainer("profiles", "/id");

var orders = cosmos.AddCosmosDatabase("orders");
var details = orders.AddContainer("details", "/id");
var history = orders.AddContainer("history", "/id");

builder.AddProject<Projects.Api>("api")
       .WithReference(profiles)
       .WithReference(details)
       .WithReference(history);

builder.Build().Run();

Föregående kod lägger till en AzureAzure Cosmos DB resurs med namnet cosmos med två databaser: customers och orders. Databasen customers har en enda container med namnet profiles, medan databasen orders har två containrar: details och history. Partitionsnyckeln för varje container är /id.

Följande diagram illustrerar föräldra-barnrelationen mellan resurserna AzureAzure Cosmos DB.

När din AppHost-kod uttrycker överordnade och underordnade relationer kan klienten djuplänka till dessa resurser med namn. Till exempel kan databasen customers refereras till vid namn i klientprojektet, där en Database-instans registreras som ansluter till customers-databasen. Samma sak gäller för namngivna containrar, till exempel kan containern details refereras med namn i klientprojektet och registrera en Container instans som ansluter till containern details .

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 AspireAzure värdintegration. Emulatorn är inte installerad, i stället är den tillgänglig i form av en container Aspire. När du lägger till en container i AppHost, som du ser i föregående exempel med avbildningen mcr.microsoft.com/cosmosdb/emulator , skapas och startas containern när AppHost 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 Aspireföljande slutpunkter:

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:

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.

Konfigurationsgenererad Bicep

Om du är ny till Bicepär det ett domänspecifikt språk för att definiera Azure-resurser. Med 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

resource cosmos 'Microsoft.DocumentDB/databaseAccounts@2024-08-15' = {
  name: take('cosmos-${uniqueString(resourceGroup().id)}', 44)
  location: location
  properties: {
    locations: [
      {
        locationName: location
        failoverPriority: 0
      }
    ]
    capabilities: [
      {
        name: 'EnableServerless'
      }
    ]
    consistencyPolicy: {
      defaultConsistencyLevel: 'Session'
    }
    databaseAccountOfferType: 'Standard'
    disableLocalAuth: true
  }
  kind: 'GlobalDocumentDB'
  tags: {
    'aspire-resource-name': 'cosmos'
  }
}

output connectionString string = cosmos.properties.documentEndpoint

output name string = cosmos.name

Föregående Bicep är en modul som ställer in en AzureAzure Cosmos DB kontoresurs. Dessutom skapas rolltilldelningar för resursen Azure i en separat modul:

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

param cosmos_outputs_name string

param principalId string

resource cosmos 'Microsoft.DocumentDB/databaseAccounts@2024-08-15' existing = {
  name: cosmos_outputs_name
}

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
}

Den genererade Bicep är en startpunkt och påverkas av ändringar i tillhandahållandeinfrastrukturen i C#. Anpassningar till Bicep-filen skrivs över direkt, så gör ändringar via C#-etablerings-API:erna för att säkerställa att de återspeglas i de genererade filerna.

Anpassa infrastruktur för tillhandahållande

Alla 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:

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

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 integration

Kom igång med 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

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

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

Du kan sedan hämta CosmosClient-instansen med hjälp av beroendeinjektion. Om du till exempel vill hämta klienten 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");

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.

Lägg till AzureAzure Cosmos DB databas

I AppHost kan databasresursen (AzureCosmosDBDatabaseResource) läggas till som en underordnad resurs till den överordnade AzureCosmosDBResource. I ditt klientkrävande projekt kan du djuplänka till databasresursen efter namn och registrera en Database instans för användning med beroendeinmatning. Tänk till exempel på följande kod som anropar AddAzureCosmosDatabase på en IHostApplicationBuilder instans:

builder.AddAzureCosmosDatabase(connectionName: "customers");

API:et AddAzureCosmosDatabase returnerar en CosmosDatabaseBuilder instans som du kan använda för att koppla flera containrar under samma databasanslutning. Alla underordnade containrar delar samma CosmosClient, databasanslutning och CosmosClient-instans. Den här strategin är användbar när du associerar samma CosmosClientOptions sak med flera containrar.

När du har anropat AddAzureCosmosDatabase, kan du hämta instansen Database med hjälp av beroendeinjektion. Om du till exempel vill hämta databasen från ett ombud i ett MapGet anrop bör du överväga följande kod:

app.MapGet("/api/customers", async (Database database) =>
{
    // Query data from database...
});

Lägg till nyckeldatabas AzureAzure Cosmos DB

Det finns också ett AddKeyedAzureCosmosDatabase API som returnerar en CosmosDatabaseBuilder instans som du kan använda för att koppla flera containrar under samma databasanslutning. metod som gör att du kan registrera flera databaser med olika anslutningsnamn. Tänk till exempel på följande kod som anropar AddKeyedAzureCosmosDatabase på en IHostApplicationBuilder instans:

var builder = WebApplication.CreateBuilder(args);

builder.AddKeyedAzureCosmosDatabase("customers");
builder.AddKeyedAzureCosmosDatabase("orders");

var app = builder.Build();

app.MapGet("/api/customers", async (
    [FromKeyedServices("customers")] Database database) =>
{
    // Get container from database and query data
});

app.MapPost("/api/orders", async (
    [FromKeyedServices("orders")] Database database,
    [FromBody] OrderRequest order) =>
{
    // Get container from database and query data
});

app.Run();

Föregående exempelkod visar hur du registrerar två databaser details och customers. Varje namngiven databas kan användas för att hämta motsvarande containrar för att fråga efter data.

Lägg till AzureAzure Cosmos DB container

När du lägger till en Cosmos DB resurs i AppHost-projektet kan du även lägga till en Azure Cosmos DB containerresurs. Containerresursen betraktas som en underordnad resurs till den överordnade AzureCosmosDBDatabaseResource. I ditt klientkrävande projekt kan du djuplänka till containerresursen efter namn och registrera en Container instans för användning med beroendeinmatning. Tänk till exempel på följande kod som anropar AddAzureCosmosContainer på en IHostApplicationBuilder instans:

builder.AddAzureCosmosContainer(connectionName: "details");

Du kan sedan hämta Container-instansen med hjälp av beroendeinjektion. Om du till exempel vill hämta containern från ett ombud i ett MapGet anrop bör du överväga följande kod:

app.MapGet("/api/orders/{id:guid}", async (
    Container container, 
    [FromRoute] Guid id) =>
{
    // Query data from container...
});

Lägg till nyckelcontainer AzureAzure Cosmos DB

Det finns också en AddKeyedAzureCosmosContainer metod som gör att du kan registrera flera containrar med olika anslutningsnamn. Tänk till exempel på följande kod som anropar AddKeyedAzureCosmosContainer på en IHostApplicationBuilder instans:

var builder = WebApplication.CreateBuilder(args);

builder.AddKeyedAzureCosmosContainer("customers");

var app = builder.Build();

app.MapGet("/api/customers", async (
    [FromKeyedServices("customers")] Container container) =>
{
    // Query data from container...
});

app.Run();

Om du har flera containrar under samma databasanslutning kan du använda API:et AddAzureCosmosDatabase för att koppla flera containrar under samma databasanslutning. Alla barncontainrar delar samma CosmosClient och databasanslutning. Den här strategin är användbar när du associerar samma CosmosClientOptions sak med flera containrar. Överväg följande alternativa kod för att registrera flera containrar under samma databasanslutning:

var builder = WebApplication.CreateBuilder(args);

builder.AddAzureCosmosDatabase("customers", configureClientOptions: options =>
    {
        options.SerializerOptions = new CosmosSerializationOptions()
        {
            PropertyNamingPolicy = CosmosPropertyNamingPolicy.CamelCase
        };
    })
    .AddKeyedContainer(name: "profiles");

builder.AddAzureCosmosDatabase(connectionName: "orders")
       .AddKeyedContainer(name: "details")
       .AddKeyedContainer(name: "history");

var app = builder.Build();

app.MapGet("/api/customers", async (
    [FromKeyedServices("profiles")] Container container) =>
{
    // Query data from container
});

app.MapGet("/api/orders", async (
    [FromKeyedServices("details")] Container container,
    [FromKeyedServices("history")] Container container) =>
{
    // Query data from container
});

app.Run();

Föregående exempelkod visar hur du registrerar två databaser, customers och orders, var och en med sina egna containrar. Databasen customers har en enda container med namnet profiles, medan orders databasen har två containrar med namnet details och history. Varje container kan frågas individuellt med hjälp av sin respektive nyckel.

Konfiguration

Den 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 finns i dokumentationen ConnectionString.

Använda konfigurationsprovidrar

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 namngiven konfiguration

Integreringen AspireAzure Cosmos DB stöder namngiven konfiguration, vilket gör att du kan konfigurera flera instanser av samma resurstyp med olika inställningar. Den namngivna konfigurationen använder anslutningsnamnet som en nyckel under huvudkonfigurationsavsnittet.

{
  "Aspire": {
    "Microsoft": {
      "Azure": {
        "Cosmos": {
          "cosmos1": {
            "AccountEndpoint": "https://myaccount1.documents.azure.com:443/",
            "DisableTracing": false
          },
          "cosmos2": {
            "AccountEndpoint": "https://myaccount2.documents.azure.com:443/",
            "DisableTracing": true
          }
        }
      }
    }
  }
}

I det här exemplet kan anslutningsnamnen cosmos1 och cosmos2 användas när du anropar AddAzureCosmosClient:

builder.AddAzureCosmosClient("cosmos1");
builder.AddAzureCosmosClient("cosmos2");

Den namngivna konfigurationen har företräde framför konfigurationen på den översta nivån. Om båda anges åsidosätter inställningarna från den namngivna konfigurationen inställningarna på den översta nivån.

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 AspireCosmos DB klientintegration implementerar för närvarande inte hälsokontroller, dock kan detta ändras i framtida versioner.

Observerbarhet och telemetri

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 Aspire översikten över 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

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

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 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
• Exempelarkiv som visar överordnade-underordnade relationer
• Aspire Cosmos DB Entity Framework Core integration
• Aspire översikt över integreringar
• översikt över AspireAzure integreringar
• Aspire GitHub Repo