integratie van .NET AspireCosmos DBEntity Framework Core

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

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 ingericht. 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 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 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 middelen worden opgehaald door middel van het aanroepen van de GetProvisionableResources() methode.
- 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. Aanpassinginrichten.

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.

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 de installatiekopie 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, koppelt u aanroepen van 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 gegevensvolumes en details waarom ze worden geprefereerd boven bindingskoppelingen, zie Docker documenten: 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.

Gezondheidscontroles voor hostingintegratie

De Azure Cosmos DB hostingintegratie voegt automatisch een statuscontrole toe voor de Cosmos DB resource. De statuscontrole 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 van Client

Installeer de 📦Aspireom aan de slag te gaan met de .NET Aspire Microsoft Entity Framework CoreCosmos DB-integratie. Microsoft.EntityFrameworkCore.Cosmos NuGet-pakket in het clientgebruikte project, bijvoorbeeld het project voor de toepassing die gebruikmaakt van de Microsoft Entity Framework CoreCosmos DB-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");

Fooi

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 DBde 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 Aspirevoor het volledige Cosmos DB clientintegratieschema JSON. 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

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

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