integratie van .NET AspireCosmos DBEntity Framework Core

Artikel
03/08/2025

Omvat: Hostingintegratie en Client-integratie

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

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 in 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 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 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 je nieuw bent bij Bicep-, is dit een domeinspecifieke taal voor het definiëren van Azure bronnen. 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 uitgegeven 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

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

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 voegt het ook de huidige toepassing toe aan de Data Contributor-rol voor het Cosmos DB-account. 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 aanpassen

Alle .NET AspireAzure resources zijn subklassen van het AzureProvisioningResource type. Met dit type kunt u de gegenereerde Bicep aanpassen door een fluent API te bieden, waarmee u de Azure resources configureert 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 middelen worden opgehaald door middel van het aanroepen van de GetProvisionableResources() methode.
- Een 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. Voor meer informatie, zie Azure.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 en containerbronnen toevoegen

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

Voeg resource toe 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 getoond in het vorige voorbeeld met het beeld mcr.microsoft.com/cosmosdb/emulator, wordt de container aangemaakt en gestart bij het opstarten van de app-host. 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 voor de Cosmos DB-emulatorcontainergateway configureren

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

Eindpunt	Containerpoort	Hostpoort
`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. Als u de eindpuntpoort wilt configureren, koppel aanroepen naar de containerresourcebouwer die wordt geleverd door de RunAsEmulator methode, zoals wordt 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. Voor meer informatie over datavolumes en details waarom ze de voorkeur genieten boven bind mounts, raadpleeg de Docker documentatie: Volumes.

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

Met de voorgaande code wordt de container van de Cosmos DB emulator geconfigureerd om een partitieaantal van 100te hebben. 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.

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 in werking is en of er een verbinding tot stand kan worden gebracht.

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

integratie Client

Om aan de slag te gaan met de .NET Aspire Microsoft Entity Framework CoreCosmos DB-integratie, installeer het 📦 in het client-gebruikend project, d.w.z. het project voor de toepassing die gebruikmaakt van de Microsoft Aspire-client.

.NET CLI
PackageReference

dotnet add package Aspire.Microsoft.EntityFrameworkCore.Cosmos

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

Cosmos DB context toevoegen

Roep in het Program.cs bestand van het clientgebruikte project de AddCosmosDbContext extensiemethode aan om een System.Data.Entity.DbContext te registreren voor gebruik via de container voor afhankelijkheidsinjectie. De methode gebruikt een verbindingsnaamparameter.

builder.AddCosmosDbContext<MyDbContext>("cosmosdb", "databaseName");

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 cosmosdb diezelfde naam moet worden gebruikt bij het aanroepen van AddCosmosDbContext. Voor meer informatie, zie AzureAzure Cosmos DB bron toevoegen.

Vervolgens kunt u het DbContext exemplaar ophalen met behulp van afhankelijkheidsinjectie. Bijvoorbeeld om de client op te halen uit een service:

public class ExampleService(MyDbContext context)
{
    // Use context...
}

Zie voor meer informatie over het gebruik van Entity Framework Core met Azure Cosmos DB de Voorbeelden voor Azure Cosmos DB voor NoSQL SDK voor .NET.

Configuratie

De .NET Aspire Integratie van Microsoft Entity Framework CoreCosmos DB biedt meerdere opties voor het configureren van de Azure Cosmos DB 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 builder.AddCosmosDbContext:

builder.AddCosmosDbContext<MyDbContext>("CosmosConnection");

Vervolgens wordt de verbindingsreeks opgehaald uit de sectie ConnectionStrings configuratie:

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

Zie de ConnectionString-documentatievoor meer informatie.

Configuratieproviders gebruiken

De integratie van .NET Aspire Microsoft Entity Framework CoreCosmos DB ondersteunt Microsoft.Extensions.Configuration. Het laadt de EntityFrameworkCoreCosmosSettings uit configuratiebestanden zoals appsettings.json. Voorbeeld _appsettings.json waarmee een aantal van de opties wordt geconfigureerd:

{
  "Aspire": {
    "Microsoft": {
      "EntityFrameworkCore": {
        "Cosmos": {
          "DisableTracing": true
        }
      }
    }
  }
}

Zie Cosmos DBvoor het volledige JSON clientintegratieschema Aspire. Microsoft.EntityFrameworkCore.Cosmos/ConfigurationSchema.json.

Inline delegates gebruiken

U kunt ook de Action<EntityFrameworkCoreCosmosSettings> configureSettings delegate doorgeven om sommige of alle EntityFrameworkCoreCosmosSettings opties inline in te stellen, bijvoorbeeld om het traceren vanuit de code uit te schakelen.

builder.AddCosmosDbContext<MyDbContext>(
    "cosmosdb",
    settings => settings.DisableTracing = true);

gezondheidscontroles voor Client-integratie

De integratie van .NET Aspire Microsoft Entity Framework CoreCosmos DB implementeert momenteel geen statuscontroles, maar dit kan in toekomstige releases veranderen.

Waarneembaarheid en telemetrie

.NET .NET Aspire integraties stellen automatisch de configuraties in voor logging, tracing en metrics, die soms ook wel bekend staan als de pijlers van observability. 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.

Logboekregistratie

De integratie van .NET Aspire Microsoft Entity Framework CoreCosmos DB maakt gebruik van de volgende logboekcategorieën:

Azure-Cosmos-Operation-Request-Diagnostics
Microsoft.EntityFrameworkCore.ChangeTracking
Microsoft.EntityFrameworkCore.Database.Command
Microsoft.EntityFrameworkCore.Infrastructure
Microsoft.EntityFrameworkCore.Query

Opvolging

De integratie van .NET Aspire Microsoft Entity Framework CoreCosmos DB verzendt de volgende traceringsactiviteiten met behulp van OpenTelemetry:

Azure.Cosmos.Operation
OpenTelemetry.Instrumentation.EntityFrameworkCore

Statistieken

De .NET Aspire Integratie van Microsoft Entity Framework CoreCosmos DB ondersteunt momenteel de volgende metrische gegevens:

Microsoft.EntityFrameworkCore
- ec_Microsoft_EntityFrameworkCore_active_db_contexts
- ec_Microsoft_EntityFrameworkCore_total_queries
- ec_Microsoft_EntityFrameworkCore_queries_per_second
- ec_Microsoft_EntityFrameworkCore_total_save_changes
- ec_Microsoft_EntityFrameworkCore_save_changes_per_second
- ec_Microsoft_EntityFrameworkCore_compiled_query_cache_hit_rate
- ec_Microsoft_Entity_total_execution_strategy_operation_failures
- ec_Microsoft_E_execution_strategy_operation_failures_per_second
- ec_Microsoft_EntityFramew_total_optimistic_concurrency_failures
- ec_Microsoft_EntityF_optimistic_concurrency_failures_per_second

Delen via