integratie van AspireCosmos DBEntity Framework Core

Inclusief: —&— Client integratie

Azure Cosmos DB is een volledig beheerde NoSQL-databaseservice voor het ontwikkelen van moderne apps. Met de 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 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 database 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 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- en kindrelatie tussen Azure Cosmos DB resources, bekijkt u het volgende voorbeeld, 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 ziet u de ouder-kind relatie tussen de AzureAzure Cosmos DB bronnen:

Een diagram dat de ouder-kindrelaties van AzureAzure Cosmos DB resources afbeeldt.

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.

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 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 voor de Cosmos DB-emulatorcontainergateway 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. 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:

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.

Provisioning-gegenereerde Bicep

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

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 aanpassen

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

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

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 parameter voor de verbindingsnaam en een databasenaamparameter.

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

De databasenaam kan ook worden afgeleid van de verbinding wanneer er één database in de verbindingsreeks staat. In dit geval kunt u de parameter voor de databasenaam weglaten:

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

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 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 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 het volledige Cosmos DB clientintegratieschema JSON in 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 Aspire Microsoft Entity Framework CoreCosmos DB 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 integratie van 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 Aspire Microsoft Entity Framework CoreCosmos DB verzendt de volgende traceringsactiviteiten met behulp van OpenTelemetry:

• Azure.Cosmos.Operation
• OpenTelemetry.Instrumentation.EntityFrameworkCore

Statistieken

De 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

Zie ook

• Azure Azure Cosmos DB documenten
• Aspire Integraties
• Aspire GitHub Repo