integratie AspireAzure Cosmos DB

Inclusief: —&— Client integratie

Azure Cosmos DB is een volledig beheerde NoSQL-databaseservice voor het ontwikkelen van moderne apps. Met de AspireAzure Cosmos DB-integratie kunt u verbinding maken met bestaande Cosmos DB exemplaren of nieuwe exemplaren maken vanuit .NET met de Azure Cosmos DB emulator.

Als u op zoek bent naar de Entity Framework Core integratie, raadpleegt u de AspireCosmos DBEntity Framework Core integratie.

Hostingintegratie

De AspireAzure Cosmos DB hosting-integratie modelleert de verschillende Cosmos DB resources als de volgende typen:

• AzureCosmosDBResource: vertegenwoordigt een AzureAzure Cosmos DB resource.
• AzureCosmosDBContainerResource: Vertegenwoordigt een AzureAzure Cosmos DB containerresource.
• AzureCosmosDBDatabaseResource: Vertegenwoordigt een AzureAzure Cosmos DB databasebron.
• AzureCosmosDBEmulatorResource: vertegenwoordigt een AzureAzure Cosmos DB emulator resource.

Als u toegang wilt krijgen tot deze typen en API's om ze uit te drukken, voegt u de 📦Aspire. Hosting.Azure. CosmosDB NuGet-pakket in het AppHost-project .

dotnet add package Aspire.Hosting.Azure.CosmosDB

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

Zie dotnet pakket toevoegen of Pakketafhankelijkheden beheren in .NET toepassingenvoor meer informatie.

Azure Azure Cosmos DB-resource toevoegen

Roep in uw AppHost-project AddAzureCosmosDB aan om een AzureAzure Cosmos DB resourcebouwer toe te voegen en te retourneren.

var builder = DistributedApplication.CreateBuilder(args);

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

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

Wanneer u een app AzureCosmosDBResource toevoegt aan de AppHost, worden er andere nuttige API's weergegeven om databases en containers toe te voegen. Met andere woorden, u moet een AzureCosmosDBResource toevoegen voordat u een van de andere Cosmos DB resources toevoegt.

Verbinding maken met een bestaand AzureAzure Cosmos DB-account

Mogelijk hebt u een bestaand AzureAzure Cosmos DB-account waarmee u verbinding wilt maken. U kunt een aanroep aaneenschakelen om aan te geven dat uw AzureCosmosDBResource een bestaande resource is.

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

Zie Azurevoor meer informatie over het behandelen van Azure Cosmos DBAzure bronnen als bestaande.

Azure Azure Cosmos DB-database en containerbronnen toevoegen

Aspire modellen ouder-kind-relaties tussen Azure Cosmos DB resources. Een account () kan bijvoorbeeld AzureAzure Cosmos DB meerdere databases (AzureCosmosDBResourceAzureCosmosDBDatabaseResource) hebben en elke database kan meerdere containers (AzureCosmosDBContainerResource) hebben. Wanneer u een database of containerresource toevoegt, doet u dit op een bovenliggende resource.

Als u een AzureAzure Cosmos DB databaseresource wilt toevoegen, roept u de AddCosmosDatabase methode aan op een IResourceBuilder<AzureCosmosDBResource> exemplaar:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Wanneer u AddCosmosDatabaseaanroept, wordt er een database met de naam db aan uw Cosmos DB resources toegevoegd en wordt de zojuist gemaakte databaseresource geretourneerd. De database wordt gemaakt in het Cosmos DB-account dat wordt vertegenwoordigd door de AzureCosmosDBResource die u eerder hebt toegevoegd. De database is een logische container voor verzamelingen en gebruikers.

Een AzureAzure Cosmos DB-container is waar gegevens worden opgeslagen. Wanneer u een container maakt, moet u een partitiesleutel opgeven.

Als u een AzureAzure Cosmos DB containerresource wilt toevoegen, roept u de AddContainer methode aan op een IResourceBuilder<AzureCosmosDBDatabaseResource>-exemplaar:

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

De container wordt gemaakt in de database die wordt vertegenwoordigd door de AzureCosmosDBDatabaseResource die u eerder hebt toegevoegd. Zie Databases, containers en items in AzureAzure Cosmos DBvoor meer informatie.

Voorbeeld van ouder-kind-resourcerelatie

Als u meer inzicht wilt krijgen in de ouder-kindrelatie tussen Azure Cosmos DB resources, kunt u het volgende voorbeeld bekijken, waarin het toevoegen van een Azure Cosmos DB resource samen met een database en container wordt gedemonstreerd.

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

Met de voorgaande code wordt een AzureAzure Cosmos DB resource met de naam cosmos met twee databases toegevoegd: customers en orders. De customers database heeft één container met de naam profiles, terwijl de orders database twee containers heeft: details en history. De partitiesleutel voor elke container is /id.

In het volgende diagram wordt de ouder-kindrelatie tussen de AzureAzure Cosmos DB resources geïllustreerd.

AzureAzure Cosmos DB resource parent child relationships.

Wanneer uw AppHost-code relaties tussen bovenliggende en onderliggende elementen weergeeft, kan de client een dieptekoppeling naar deze resources maken op naam. Er kan bijvoorbeeld naar de customers database worden verwezen op naam in het clientproject, waarbij een Database exemplaar wordt geregistreerd dat verbinding maakt met de customers database. Hetzelfde geldt voor benoemde containers, bijvoorbeeld de details container kan worden verwezen op naam in het clientproject, waarbij een Container exemplaar wordt geregistreerd dat verbinding maakt met de details container.

Resource toevoegen voor AzureAzure Cosmos DB emulator

Als u een AzureAzure Cosmos DB emulatorresource wilt toevoegen, koppelt u een aanroep op een IResourceBuilder<AzureCosmosDBResource> aan de RunAsEmulator-API:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Wanneer u RunAsEmulatoraanroept, worden uw Cosmos DB resources geconfigureerd om lokaal te worden uitgevoerd met behulp van een emulator. De emulator is in dit geval de AzureAzure Cosmos DB Emulator. De Azure Cosmos DB Emulator biedt een gratis lokale omgeving voor het testen van uw Azure Cosmos DB-apps en het is een perfecte aanvulling op de AspireAzure hostingintegratie. De emulator is niet geïnstalleerd, maar wel toegankelijk als container voor Aspire. Wanneer u een container aan de AppHost toevoegt, zoals wordt weergegeven in het vorige voorbeeld met de mcr.microsoft.com/cosmosdb/emulator installatiekopieën, wordt de container gemaakt en gestart wanneer de AppHost wordt gestart. Zie levenscyclus van containerresourcesvoor meer informatie.

Container voor Cosmos DB emulator configureren

Er zijn verschillende configuraties beschikbaar voor containerresources. U kunt bijvoorbeeld de poorten van de container, omgevingsvariabelen, de levensduuren meer configureren.

De poort van de Cosmos DB-emulatorcontainer-gateway configureren

Standaard bevat de Cosmos DB emulatorcontainer wanneer deze is geconfigureerd door Aspire, de volgende eindpunten:

De poort waarop wordt geluisterd, is standaard dynamisch. Wanneer de container wordt gestart, wordt de poort toegewezen aan een willekeurige poort op de hostcomputer. Om de endpointpoort te configureren, koppelt u aanroepen op de containerresourcebouwer die wordt geleverd door de RunAsEmulator-methode, zoals weergegeven in het volgende voorbeeld:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Met de voorgaande code wordt het bestaande Cosmos DB-eindpunt van de https emulatorcontainer geconfigureerd om te luisteren op poort 8081. De poort van de Cosmos DB emulatorcontainer wordt toegewezen aan de hostpoort, zoals wordt weergegeven in de volgende tabel:

Cosmos DB emulatorcontainer met permanente levensduur configureren

Als u de container van de Cosmos DB emulator met een permanente levensduur wilt configureren, roept u de WithLifetime methode aan op de containerresource van de Cosmos DB emulator en geeft u ContainerLifetime.Persistentdoor:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Zie Levensduur van containerresourcesvoor meer informatie.

Cosmos DB emulatorcontainer configureren met gegevensvolume

Als u een gegevensvolume wilt toevoegen aan de resource van de AzureAzure Cosmos DB emulator, roept u de WithDataVolume methode aan op de resource van de AzureAzure Cosmos DB emulator:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Het gegevensvolume wordt gebruikt om de Cosmos DB emulatorgegevens buiten de levenscyclus van de container te behouden. Het gegevensvolume wordt gekoppeld aan het /tmp/cosmos/appdata pad in de container van de Cosmos DB emulator en wanneer er geen name parameter wordt opgegeven, wordt de naam gegenereerd. De emulator heeft de AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE omgevingsvariabele ingesteld op true. Zie de documenten Docker: Volumesvoor meer informatie over gegevensvolumes en waarom deze de voorkeur hebben boven bindingskoppelingen.

Aantal containerpartities voor Cosmos DB emulator configureren

Als u het aantal partities van de container Cosmos DB emulator wilt configureren, roept u de methode WithPartitionCount aan:

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

De voorgaande code configureert de container van de Cosmos DB-emulator op een partitieaantal van 100. Dit is een afkorting voor het instellen van de AZURE_COSMOS_EMULATOR_PARTITION_COUNT omgevingsvariabele.

Op Linuxgebaseerde emulator gebruiken (preview)

De volgende generatie van de AzureAzure Cosmos DB-emulator is volledig Linuxgebaseerd en is beschikbaar als een Docker-container. Het ondersteunt uitvoering op een groot aantal processors en besturingssystemen.

Als u de preview-versie van de Cosmos DB emulator wilt gebruiken, roept u de methode RunAsPreviewEmulator aan. Omdat deze functie in preview is, moet u zich expliciet aanmelden voor de preview-functie door de ASPIRECOSMOSDB001 experimentele diagnose te onderdrukken.

De preview-emulator biedt ook ondersteuning voor het beschikbaar maken van een Data Explorer-eindpunt, waarmee u de gegevens kunt bekijken die zijn opgeslagen in de Cosmos DB emulator via een webgebruikersinterface. Als u Data Explorer wilt inschakelen, roept u de methode WithDataExplorer aan.

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

Met de voorgaande code wordt de op Linuxgebaseerde preview-container Cosmos DB emulator geconfigureerd, met het Data Explorer-eindpunt, dat tijdens runtime moet worden gebruikt.

Provisioning-gegenereerde Bicep

Als u nieuw bent bij Bicep, dan is dit een domeinspecifieke taal voor het definiëren van Azure-resources. Met Aspire hoeft u Bicep niet handmatig te schrijven, omdat de voorzienings-API's Bicep voor u genereren. Wanneer u uw app publiceert, wordt de gegenereerde Bicep weergegeven naast het manifestbestand. Wanneer u een AzureAzure Cosmos DB resource toevoegt, wordt de volgende Bicep gegenereerd:

@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

De voorafgaande Bicep-module is een module die een AzureAzure Cosmos DB accountresource inricht. Daarnaast worden roltoewijzingen gemaakt voor de Azure resource in een afzonderlijke module:

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

De gegenereerde Bicep is een beginpunt en wordt beïnvloed door wijzigingen aan de voorzieningsinfrastructuur in C#. Aanpassingen aan het Bicep-bestand zullen direct overschreven worden, dus breng wijzigingen aan via de C#-inrichtings-API's zodat ze weerspiegeld worden in de gegenereerde bestanden.

Voorzieningsinfrastructuur personaliseren

Alle AspireAzure resources zijn subklassen van het AzureProvisioningResource type. Met dit type kunt u de gegenereerde Bicep aanpassen door een vloeiende API te bieden om de Azure-resources te configureren, met behulp van de ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>)-API. U kunt bijvoorbeeld de kind, consistencyPolicy, locationsen meer configureren. In het volgende voorbeeld ziet u hoe u de AzureAzure Cosmos DB-resource aanpast:

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

De voorgaande code:

• Koppelt een aanroep naar de ConfigureInfrastructure-API:
  • De parameter infra is een exemplaar van het AzureResourceInfrastructure type.
  • De voorzienbare bronnen worden opgehaald door de GetProvisionableResources() Methode aan te roepen.
  • Het enige exemplaar CosmosDBAccount wordt opgehaald.
  • De CosmosDBAccount.ConsistencyPolicy is toegewezen aan een DefaultConsistencyLevel.Strong.
  • Er wordt een tag toegevoegd aan het Cosmos DB-account met een sleutel van ExampleKey en een waarde van Example value.

Er zijn nog veel meer configuratieopties beschikbaar om de AzureAzure Cosmos DB resource aan te passen. Zie Azure.Provisioning.CosmosDBvoor meer informatie. Zie Azurevoor meer informatie. Aanpassing van voorzieningen.

Gezondheidscontroles voor hostingintegratie

De Azure Cosmos DB hostingintegratie voegt automatisch een statuscontrole toe voor de Cosmos DB resource. De gezondheidscontrole verifieert of de Cosmos DB actief is en of er een verbinding tot stand kan worden gebracht.

De hostingintegratie is afhankelijk van het 📦 AspNetCore.HealthChecks.CosmosDb NuGet-pakket.

Client integratie

Installeer het Aspire NuGet-pakket in het client-consumerend project, dat wil zeggen het project voor de toepassing die gebruikmaakt van de Azure Cosmos DB-client, om aan de slag te gaan met de 📦Aspire clientintegratie. De Cosmos DB-clientintegratie registreert een CosmosClient exemplaar dat u kunt gebruiken om met Cosmos DBte communiceren.

dotnet add package Aspire.Microsoft.Azure.Cosmos

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

Cosmos DB-client toevoegen

Roep in het Program.cs bestand van het clientgebruikte project de AddAzureCosmosClient-extensiemethode aan op een IHostApplicationBuilder om een CosmosClient te registreren voor gebruik via de container voor afhankelijkheidsinjectie. De methode gebruikt een verbindingsnaamparameter.

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

Vervolgens kunt u het CosmosClient exemplaar ophalen met behulp van afhankelijkheidsinjectie. Als u bijvoorbeeld de client wilt ophalen uit een voorbeeldservice:

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

Voor meer informatie over afhankelijkheidsinjectie, zie .NET afhankelijkheidsinjectie.

Keyed Cosmos DB-client toevoegen

Er kunnen situaties zijn waarin u meerdere CosmosClient exemplaren met verschillende verbindingsnamen wilt registreren. Als u keyed Cosmos DB-clients wilt registreren, roept u de methode AddKeyedAzureCosmosClient aan:

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

Vervolgens kunt u de CosmosClient-exemplaren ophalen met behulp van dependency injection. Als u bijvoorbeeld de verbinding wilt ophalen uit een voorbeeldservice:

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

Voor meer informatie over gesleutelde services, zie .NET afhankelijkheidsinjectie: Gesleutelde services.

Database toevoegen AzureAzure Cosmos DB

In de AppHost kan de databaseresource (AzureCosmosDBDatabaseResource) worden toegevoegd als een onderliggende resource aan het bovenliggende AzureCosmosDBResourceitem. In uw clientverbruikende project kunt u een dieptekoppeling maken naar de databaseresource op naam, waarbij u een Database exemplaar registreert voor gebruik met afhankelijkheidsinjectie. Denk bijvoorbeeld aan de volgende code die AddAzureCosmosDatabase aanroept op een IHostApplicationBuilder exemplaar:

builder.AddAzureCosmosDatabase(connectionName: "customers");

De AddAzureCosmosDatabase API retourneert een CosmosDatabaseBuilder exemplaar dat u kunt gebruiken om meerdere containers onder dezelfde databaseverbinding te koppelen. Alle onderliggende containers delen dezelfde CosmosClient, databaseverbinding en CosmosClient-instantie. Deze strategie is handig bij het koppelen van hetzelfde CosmosClientOptions aan meerdere containers.

Na het aanroepen van AddAzureCosmosDatabase kunt u vervolgens het Database exemplaar ophalen met behulp van dependency-injectie. Als u bijvoorbeeld de database wilt ophalen van een gemachtigde in een MapGet aanroep, moet u rekening houden met de volgende code:

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

Voeg een gesleutelde AzureAzure Cosmos DB database toe

Er is ook een AddKeyedAzureCosmosDatabase API die een CosmosDatabaseBuilder exemplaar retourneert dat u kunt gebruiken om meerdere containers onder dezelfde databaseverbinding te koppelen. methode waarmee u meerdere databases met verschillende verbindingsnamen kunt registreren. Denk bijvoorbeeld aan de volgende code die AddKeyedAzureCosmosDatabase aanroept op een IHostApplicationBuilder exemplaar:

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

De voorgaande voorbeeldcode laat zien hoe u twee databases registreert en detailscustomers. Elke benoemde database kan worden gebruikt om de bijbehorende containers op te halen om query's uit te voeren op gegevens.

Container toevoegen AzureAzure Cosmos DB

Wanneer u een Cosmos DB resource toevoegt in het AppHost-project, kunt u ook een Azure Cosmos DB containerresource toevoegen. De containerresource wordt beschouwd als een onderliggende resource voor het bovenliggende AzureCosmosDBDatabaseResourceitem. In uw clientverbruikende project kunt u een dieptekoppeling maken naar de containerresource op naam, waarbij u een Container exemplaar registreert voor gebruik met afhankelijkheidsinjectie. Denk bijvoorbeeld aan de volgende code die AddAzureCosmosContainer aanroept op een IHostApplicationBuilder exemplaar:

builder.AddAzureCosmosContainer(connectionName: "details");

Vervolgens kunt u het Container exemplaar ophalen met behulp van afhankelijkheidsinjectie. Als u bijvoorbeeld de container wilt ophalen van een gemachtigde in een MapGet aanroep, moet u rekening houden met de volgende code:

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

Sleutelcontainer AzureAzure Cosmos DB toevoegen

Er is ook een AddKeyedAzureCosmosContainer methode waarmee u meerdere containers met verschillende verbindingsnamen kunt registreren. Denk bijvoorbeeld aan de volgende code die AddKeyedAzureCosmosContainer aanroept op een IHostApplicationBuilder exemplaar:

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

Als u meerdere containers onder dezelfde databaseverbinding hebt, kunt u de AddAzureCosmosDatabase API gebruiken om meerdere containers onder dezelfde databaseverbinding te koppelen. Alle kindcontainers delen dezelfde CosmosClient en databaseverbinding. Deze strategie is handig bij het koppelen van hetzelfde CosmosClientOptions aan meerdere containers. Overweeg de volgende alternatieve code om meerdere containers te registreren onder dezelfde databaseverbinding:

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

In de voorgaande voorbeeldcode ziet u hoe u twee databases customers registreert en orderselk met hun eigen containers. De customers database heeft één container met de naam profiles, terwijl de database twee containers heeft met de orders naam details en history. Elke container kan afzonderlijk worden opgevraagd met behulp van de bijbehorende sleutel.

Configuratie

De AspireAzure Cosmos DB-integratie biedt meerdere opties voor het configureren van de verbinding op basis van de vereisten en conventies van uw project.

Een verbindingsreeks gebruiken

Wanneer u een verbindingsreeks uit de sectie ConnectionStrings configuratie gebruikt, kunt u de naam van de verbindingsreeks opgeven bij het aanroepen van de AddAzureCosmosClient methode:

builder.AddAzureCosmosClient("cosmos-db");

Vervolgens wordt de verbindingsreeks opgehaald uit de ConnectionStrings configuratiesectie:

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

Zie de ConnectionString-documentatievoor meer informatie.

Configuratieproviders gebruiken

De AspireAzure Cosmos DB-integratie ondersteunt Microsoft.Extensions.Configuration. Het laadt de MicrosoftAzureCosmosSettings uit de configuratie door gebruik te maken van de Aspire:Microsoft:Azure:Cosmos-sleutel. Het volgende codefragment is een voorbeeld van een appsettings.json-bestand waarmee een aantal van de opties wordt geconfigureerd:

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

Zie voor het volledige Cosmos DB clientintegratieschema JSON, Aspire.Microsoft.Azure.Cosmos/ConfigurationSchema.json.

Benoemde configuratie gebruiken

De AspireAzure Cosmos DB integratie ondersteunt benoemde configuratie, waarmee u meerdere exemplaren van hetzelfde resourcetype met verschillende instellingen kunt configureren. De benoemde configuratie maakt gebruik van de verbindingsnaam als een sleutel in het hoofdgedeelte van de configuratie.

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

In dit voorbeeld kunnen de cosmos1 en cosmos2 verbindingsnamen worden gebruikt wanneer AddAzureCosmosClient wordt aangeroepen:

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

Benoemde configuratie heeft voorrang op de configuratie op het hoogste niveau. Als beide zijn opgegeven, overschrijven de instellingen van de benoemde configuratie de instellingen op het hoogste niveau.

Inline delegates gebruiken

U kunt ook de Action<MicrosoftAzureCosmosSettings> configureSettings delegate doorgeven om enkele of alle opties inline in te stellen, bijvoorbeeld om tracering vanuit de code uit te schakelen.

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

U kunt de Microsoft.Azure.Cosmos.CosmosClientOptions ook instellen met behulp van de optionele parameter Action<CosmosClientOptions> configureClientOptions van de methode AddAzureCosmosClient. Als u bijvoorbeeld het achtervoegsel van de CosmosClientOptions.ApplicationName user-agent header wilt instellen voor alle verzoeken die door deze client worden gedaan:

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

integratie-gezondheidscontroles Client

De AspireCosmos DB-clientintegratie implementeert momenteel geen statuscontroles, maar dit kan in toekomstige releases veranderen.

Waarneembaarheid en telemetrie

Aspire Integraties stellen automatisch configuraties voor logboekregistratie, tracering en metrische gegevens in, die ook wel de pijlers van waarneembaarheid worden genoemd. Zie het overzicht van integratieobserveerbaarheid en telemetrie voor meer informatie over integratieobserveerbaarheid en telemetrieAspire. Afhankelijk van de back-upservice ondersteunen sommige integraties mogelijk slechts enkele van deze functies. Sommige integraties ondersteunen bijvoorbeeld logboekregistratie en tracering, maar geen metrische gegevens. Telemetriefuncties kunnen ook worden uitgeschakeld met behulp van de technieken die worden weergegeven in de sectie Configuratie.

Loggen

De AspireAzure Cosmos DB-integratie maakt gebruik van de volgende logboekcategorieën:

• Azure-Cosmos-Operation-Request-Diagnostics

Naast het ophalen van Azure Cosmos DB aanvraagdiagnose voor mislukte aanvragen, kunt u latentiedrempels configureren om te bepalen welke geslaagde Azure Cosmos DB aanvraagdiagnose wordt geregistreerd. De standaardwaarden zijn 100 ms voor puntbewerkingen en 500 ms voor niet-puntbewerkingen.

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

Traceren

De AspireAzure Cosmos DB-integratie verzendt de volgende traceringsactiviteiten met behulp van OpenTelemetry:

• Azure.Cosmos.Operation

Op dit moment is AzureAzure Cosmos DB tracering in de preview-fase, dus moet u de experimentele schakelaar instellen om ervoor te zorgen dat sporen worden verzonden.

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

Zie AzureAzure Cosmos DB SDK waarneembaarheid: Traceerkenmerkenvoor meer informatie.

Statistieken

De AspireAzure Cosmos DB-integratie biedt momenteel geen ondersteuning voor metrische gegevens vanwege beperkingen met de Azure SDK.

Zie ook

• Azure Cosmos DB
• Voorbeeldrepository met ouder-kindrelaties
• Aspire Cosmos DB Entity Framework Core integratie
• Aspire overzicht van integraties
• overzicht van AspireAzure integraties
• Aspire GitHub repository