integratie van .NET AspireAzure Cosmos DB

Artikel
01/09/2025

omvat:hostingintegratie en Client integratie

Azure Cosmos DB is een volledig beheerde NoSQL-databaseservice voor het ontwikkelen van moderne apps. Met de .NET 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.

Hostingintegratie

De .NET.NET AspireAzure Cosmos DB hostintegratiemodellen modelleren de verschillende Cosmos DB resources als de volgende typen:

AzureCosmosDBResource: vertegenwoordigt een AzureAzure Cosmos DB resource.
AzureCosmosDBEmulatorResource: vertegenwoordigt een AzureAzure Cosmos DB emulatorresource.

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

.NET CLI
PackageReference

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 app-hostproject AddAzureCosmosDB aan om een AzureAzure Cosmos DB resource builder 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 AzureCosmosDBResource toevoegt aan de app-host, 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.

Belangrijk

Wanneer u AddAzureCosmosDBaanroept, wordt impliciet AddAzureProvisioningaangeroepen. Hiermee wordt ondersteuning toegevoegd voor het dynamisch genereren van Azure resources tijdens het opstarten van de app. De app moet het juiste abonnement en de juiste locatie configureren. Zie Lokale inrichting: Configuratievoor meer informatie.

Gegenereerde voorziening Bicep

Als u nieuw bent bij Bicep, dan is dit een domeinspecifieke taal voor het definiëren van Azure-resources. Met .NET.NET Aspirehoeft u bicep niet handmatig te schrijven, in plaats daarvan genereren de inrichtings-API's Bicep voor u. 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:

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

De voorgaande Bicep is een module waarmee een AzureAzure Cosmos DB-account wordt ingesteld met de volgende standaardwaarden:

kind: het type Cosmos DB account. De standaardwaarde is GlobalDocumentDB.
consistencyPolicy: het consistentiebeleid van het Cosmos DB-account. De standaardwaarde is Session.
locations: De locaties voor het Cosmos DB-account. De standaardwaarde is de locatie van de resourcegroep.

Naast het Cosmos DB-account wordt ook een Azure Key Vault-bron voorzien. Dit wordt gebruikt om de verbindingsreeks van het Cosmos DB-account veilig op te slaan. De gegenereerde Bicep is een uitgangspunt en kan worden aangepast aan uw specifieke vereisten.

Voorzieningsinfrastructuur personaliseren

Alle .NET 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.
- De enkele 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.

Verbinding maken met een bestaand AzureAzure Cosmos DB-account

Mogelijk hebt u een bestaand AzureAzure Cosmos DB-account waarmee u verbinding wilt maken. In plaats van een nieuwe AzureAzure Cosmos DB resource weer te geven, kunt u een verbindingsreeks toevoegen aan de app-host. Als u een verbinding wilt toevoegen aan een bestaand AzureAzure Cosmos DB-account, roept u de methode AddConnectionString aan:

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

Notitie

Verbindingsreeksen worden gebruikt om een breed scala aan verbindingsgegevens weer te geven, waaronder databaseverbindingen, berichtbrokers, eindpunt-URI's en andere services. In .NET.NET Aspire nomenclatuur wordt de term "verbindingsreeks" gebruikt om alle soorten verbindingsgegevens weer te geven.

De verbindingsreeks is geconfigureerd in de configuratie van de app-host, meestal onder gebruikersgeheimen, onder de sectie ConnectionStrings. De app-host injecteert deze verbindingsreeks als een omgevingsvariabele in alle afhankelijke resources, bijvoorbeeld:

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

De afhankelijke resource heeft toegang tot de geïnjecteerde verbindingsreeks door de methode GetConnectionString aan te roepen en de verbindingsnaam door te geven als de parameter, in dit geval "cosmos-db". De GetConnectionString-API is een afkorting voor IConfiguration.GetSection("ConnectionStrings")[name].

Azure Azure Cosmos DB database resource toevoegen

Als u een AzureAzure Cosmos DB-databaseresource wilt toevoegen, koppelt u een aanroep van een IResourceBuilder<AzureCosmosDBResource> aan de AddDatabase-API:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Wanneer u AddDatabaseaanroept, worden uw Cosmos DB resources geconfigureerd voor een database met de naam db. 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. Zie Databases, containers en items in AzureAzure Cosmos DBvoor meer informatie.

Notitie

Wanneer u de AddDatabase-API gebruikt om een database toe te voegen aan een AzureAzure Cosmos DB resource, wordt de database niet daadwerkelijk in de emulator gemaakt als u de emulator uitvoert. Deze API is bedoeld om een database op te nemen in de Bicep gegenereerde door de inrichtingsinfrastructuur.

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 .NET AspireAzure hostingintegratie. De emulator is niet geïnstalleerd, maar is toegankelijk voor .NET.NET Aspire als container. Wanneer u een container toevoegt aan de app-host, zoals wordt weergegeven in het vorige voorbeeld met de installatiekopie mcr.microsoft.com/cosmosdb/emulator, wordt de container gemaakt en gestart wanneer de app-host 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.

Poort voor Cosmos DB-emulatorcontainergateway configureren

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

Eindpunt	Containerpoort	host-poort
`https`	8081	dynamisch

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:

Eindpuntnaam	Poorttoewijzing (`container:host`)
`https`	`8081:7777`

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.

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.

integratie van Client

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

.NET CLI
PackageReference

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

Tip

De parameter connectionName moet overeenkomen met de naam die wordt gebruikt bij het toevoegen van de Cosmos DB resource in het app-hostproject. Met andere woorden, wanneer u AddAzureCosmosDB aanroept en een naam opgeeft van cosmos-db diezelfde naam moet worden gebruikt bij het aanroepen van AddAzureCosmosClient. Zie AzureAzure Cosmos DB resource toevoegenvoor meer informatie.

Vervolgens kunt u het CosmosClient exemplaar ophalen met behulp van afhankelijkheidsinjectie. Als u bijvoorbeeld de verbinding 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");

Belangrijk

Wanneer u sleutelservices gebruikt, wordt verwacht dat uw Cosmos DB resource twee benoemde databases heeft geconfigureerd, één voor de mainDb en één voor de 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 sleutelservices, zie .NET afhankelijkheidsinjectie: Keyed services.

Configuratie

De .NET 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-documentatie voor meer informatie over het opmaken van deze verbindingsreeks.

Configuratieproviders gebruiken

De .NET AspireAzure Cosmos DB-integratie ondersteunt Microsoft.Extensions.Configuration. Het laadt de MicrosoftAzureCosmosSettings vanuit de configuratie met behulp 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 Aspirevoor het volledige Cosmos DB clientintegratieschema JSON. Microsoft.Azure. Cosmos/ConfigurationSchema.json.

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

statuscontroles voor Client integratie

Standaard stellen .NET.NET Aspire-integraties gezondheidscontroles voor alle services in. Zie .NET.NET Aspire overzicht van integratiesvoor meer informatie.

De .NET AspireAzure Cosmos DB-integratie:

Voegt de gezondheidscontrole toe wanneer MicrosoftAzureCosmosSettings.DisableTracingfalseis, wat probeert verbinding te maken met de Cosmos DB.
Integreert met het /health HTTP-eindpunt, waarbij alle geregistreerde statuscontroles moeten slagen zodat de app als gereed wordt beschouwd voor het accepteren van verkeer.

Waarneembaarheid en telemetrie

.NET .NET Aspire integraties stellen automatisch de configuraties voor logging, tracing en metrieken in, die ook wel bekend staan als de pijlers van waarneembaarheid. Zie .NET.NET Aspire overzicht van integratieintegratiesvoor meer informatie over de waarneembaarheid en telemetrie van integraties. 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 .NET 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)
                }
            };
        });

Tracering

De .NET 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 .NET AspireAzure Cosmos DB-integratie biedt momenteel geen ondersteuning voor metrische gegevens vanwege beperkingen met de Azure SDK.

Zie ook

Azure Cosmos DB
overzicht van .NET.NET Aspire integraties
overzicht van .NET AspireAzure integraties
.NET Aspire GitHub opslagplaats

Delen via