.NET Aspire Cosmos DB Entity Framework Core samverkan

2025-06-18

Inkluderar:Värdintegrering ingår Värdintegrering &–& integrering ingår integration

Azure Cosmos DB är en fullständigt hanterad NoSQL-databastjänst för modern apputveckling. Med integreringen .NET AspireCosmos DBEntity Framework Core kan du ansluta till befintliga Cosmos DB-instanser eller skapa nya instanser från .NET med Azure Cosmos DB-emulatorn.

Hostingtjänstintegration

Värdtjänstintegrationen av .NET.NET AspireAzure Cosmos DB modellerar de olika Cosmos DB-resurserna som följande typer:

AzureCosmosDBResource: Representerar en AzureAzure Cosmos DB resurs.
AzureCosmosDBContainerResource: Representerar en AzureAzure Cosmos DB resurs för containrar.
AzureCosmosDBDatabaseResource: Är en resurs för AzureAzure Cosmos DB databasen.
AzureCosmosDBEmulatorResource: Representerar en emulatorsresurs för AzureAzure Cosmos DB.

Om du vill komma åt dessa typer och API:er för att uttrycka dem lägger du till 📦Aspire.Hosting.Azure.CosmosDB NuGet-paketet i appvärd-projektet.

.NET CLI
PaketReferens

dotnet add package Aspire.Hosting.Azure.CosmosDB

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

Mer information finns i dotnet add package eller Hantera paketberoenden i .NET applikationer.

Lägg till AzureAzure Cosmos DB resurs

I ditt appvärdprojekt anropar du AddAzureCosmosDB för att lägga till och returnera en AzureAzure Cosmos DB resursbyggare.

var builder = DistributedApplication.CreateBuilder(args);

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

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

När du lägger till en AzureCosmosDBResource i appens värd blir andra användbara API:er tillgängliga för att lägga till databaser och containrar. Med andra ord måste du lägga till en AzureCosmosDBResource innan du lägger till någon av de andra Cosmos DB resurserna.

Viktig

När du anropar AddAzureCosmosDBanropas implicit AddAzureProvisioning– vilket ger stöd för att generera Azure resurser dynamiskt under appstarten. Appen måste konfigurera lämplig prenumeration och plats. Mer information finns i Lokal tilldelning: Konfiguration.

Konfigurationsgenererad Bicep

Om du är ny på Bicep, är det ett domänspecifikt språk för att definiera Azure-resurser. Med .NET.NET Aspirebehöver du inte skriva Bicep för hand, i stället genererar etablerings-API:erna Bicep åt dig. När du publicerar din app skapas den genererade Bicep-filen och placeras tillsammans med manifestfilen. När du lägger till en AzureAzure Cosmos DB resurs genereras följande Bicep:

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

En tidigare nämnd Bicep är en modul som tillhandahåller en AzureAzure Cosmos DB kontoresurs. Dessutom skapas rolltilldelningar för resursen Azure i en separat modul:

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

Den genererade Bicep är en startpunkt och påverkas av ändringar i tillhandahållandeinfrastrukturen i C#. Anpassningar till Bicep-filen skrivs över direkt, så gör ändringar via C#-etablerings-API:erna för att säkerställa att de återspeglas i de genererade filerna.

Anpassa försörjningsinfrastruktur

Alla .NET AspireAzure resurser är underklasser av den AzureProvisioningResource typen. Den här typen möjliggör anpassning av den genererade Bicep genom att tillhandahålla ett flytande API för att konfigurera Azure resurser med hjälp av ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) API:et. Du kan till exempel konfigurera kind, consistencyPolicy, locationsoch mycket mer. I följande exempel visas hur du anpassar AzureAzure Cosmos DB resursen:

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

Föregående kod:

Kedjar ett anrop till ConfigureInfrastructure-API:et:
- Parametern infra är en instans av den AzureResourceInfrastructure typen.
- De tillgängliga resurserna hämtas genom att anropa metoden GetProvisionableResources().
- Den enda CosmosDBAccount hämtas.
- CosmosDBAccount.ConsistencyPolicy tilldelas till en DefaultConsistencyLevel.Strong.
- En tagg läggs till i Cosmos DB-kontot med nyckeln ExampleKey och värdet Example value.

Det finns många fler konfigurationsalternativ för att anpassa AzureAzure Cosmos DB resursen. Mer information finns i Azure.Provisioning.CosmosDB. För mer information, se Azure.Tillhandahållande-anpassning.

Ansluta till ett befintligt AzureAzure Cosmos DB konto

Du kan ha ett befintligt AzureAzure Cosmos DB konto som du vill ansluta till. Du kan kedja en anropning för att annotera att din AzureCosmosDBResource är en befintlig resurs:

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

Viktig

När du anropar RunAsExisting, PublishAsExisting, eller AsExisting-metoder för att arbeta med resurser som redan finns i din Azure-prenumeration, måste du lägga till vissa konfigurationsvärden i App Host för att säkerställa att .NET Aspire kan hitta dem. De nödvändiga konfigurationsvärdena är SubscriptionId, AllowResourceGroupCreation, ResourceGroup och Location. Om du inte anger dem visas "Konfiguration saknas"-fel på .NET.NET Aspire instrumentpanelen. Mer information om hur du anger dem finns i Konfiguration.

Mer information om hur du behandlar AzureAzure Cosmos DB resurser som befintliga resurser finns i Använd befintliga Azure resurser.

Anteckning

Alternativt, i stället för att representera en AzureAzure Cosmos DB resurs, kan du lägga till en anslutningssträng till appens värd. Den här metoden är svagt skriven och fungerar inte med rolltilldelningar eller infrastrukturanpassningar. För mer information, se Lägg till befintliga Azure resurser med anslutningssträngar.

Lägga till AzureAzure Cosmos DB databas- och containerresurser

.NET Aspire modellerar överordnade-underordnade relationer mellan Azure Cosmos DB resurser. Ett konto () kan till exempel AzureAzure Cosmos DB ha flera databaser (AzureCosmosDBResource) och varje databas kan ha flera containrar (AzureCosmosDBDatabaseResource).AzureCosmosDBContainerResource När du lägger till en databas- eller containerresurs gör du det på en överordnad resurs.

Om du vill lägga till en AzureAzure Cosmos DB databasresurs anropar du metoden AddCosmosDatabase på en IResourceBuilder<AzureCosmosDBResource>-instans:

var builder = DistributedApplication.CreateBuilder(args);

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

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

När du anropar AddCosmosDatabaselägger den till en databas med namnet db till dina Cosmos DB resurser och returnerar den nyligen skapade databasresursen. Databasen skapas i det Cosmos DB konto som representeras av AzureCosmosDBResource som du lade till tidigare. Databasen är en logisk container för samlingar och användare.

En AzureAzure Cosmos DB container är där data lagras. När du skapar en container måste du ange en partitionsnyckel.

Om du vill lägga till en AzureAzure Cosmos DB containerresurs anropar du metoden AddContainer på en IResourceBuilder<AzureCosmosDBDatabaseResource>-instans:

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

Containern skapas i databasen som representeras av AzureCosmosDBDatabaseResource som du lade till tidigare. Mer information finns i Databaser, containrar och objekt i AzureAzure Cosmos DB.

Exempel på föräldra-barn resursrelation

För att bättre förstå relationen mellan Azure Cosmos DB överordnade och underordnade resurser kan du titta på följande exempel, som visar hur du lägger till en Azure Cosmos DB resurs tillsammans med en databas och container:

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

Föregående kod lägger till en AzureAzure Cosmos DB resurs med namnet cosmos med två databaser: customers och orders. Databasen customers har en enda container med namnet profiles, medan databasen orders har två containrar: details och history. Partitionsnyckeln för varje container är /id.

Följande diagram illustrerar föräldra-barnrelationen mellan resurserna AzureAzure Cosmos DB.

När din appvärdkod uttrycker överordnade och underordnade relationer kan klienten djuplänka till dessa resurser via namnet. Till exempel kan databasen customers refereras till vid namn i klientprojektet, där en Database-instans registreras som ansluter till customers-databasen. Samma sak gäller för namngivna containrar, till exempel kan containern details refereras med namn i klientprojektet och registrera en Container instans som ansluter till containern details .

Lägg till AzureAzure Cosmos DB emulatorresurs

Om du vill lägga till en AzureAzure Cosmos DB-emulatorresurs kedjar du ett anrop på en IResourceBuilder<AzureCosmosDBResource> till API:t RunAsEmulator.

var builder = DistributedApplication.CreateBuilder(args);

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

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

När du anropar RunAsEmulatorkonfigureras dina Cosmos DB resurser att köras lokalt med hjälp av en emulator. Emulatorn i det här fallet är AzureAzure Cosmos DB emulatorn. Azure Cosmos DB-emulatorn ger en kostnadsfri lokal miljö för att testa dina Azure Cosmos DB-appar och den är en perfekt följeslagare till .NET AspireAzure hosting-integration. Emulatorn är inte installerad, i stället är den tillgänglig för .NET.NET Aspire som en container. När du lägger till en container i appvärden, som du ser i det föregående exemplet med mcr.microsoft.com/cosmosdb/emulator-bilden, skapas och startas containern när appvärden startar. Mer information finns i Livscykel för containerresurser.

Konfigurera Cosmos DB emulator container

Det finns olika konfigurationer tillgängliga för containerresurser, till exempel kan du konfigurera containerns portar, miljövariabler, det är livslängdmed mera.

Konfigurera gatewayporten för emulatorcontainern Cosmos DB

Som standard exponerar Cosmos DB emulatorcontainern när den konfigureras av .NET Aspireföljande slutpunkter:

Slutpunkt	Containerhamn	Värdport
`https`	8081	dynamisk

Porten som den lyssnar på är dynamisk som standard. När containern startar mappas porten till en slumpmässig port på värddatorn. För att konfigurera slutpunktsporten anropar kedjan containerresursverktyget som tillhandahålls av metoden RunAsEmulator enligt följande exempel:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Föregående kod konfigurerar Cosmos DB emulatorcontainerns befintliga https slutpunkt för att lyssna på port 8081. Cosmos DB-emulatorcontainerns port mappas till värdporten enligt följande tabell:

Slutpunktsnamn	Portmappning (`container:host`)
`https`	`8081:7777`

Konfigurera Cosmos DB emulatorcontainer med beständig livslängd

Om du vill konfigurera Cosmos DB-emulatorcontainern med en beständig livslängd anropar du WithLifetime-metoden på containerresursen Cosmos DB emulator och skickar ContainerLifetime.Persistent:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Mer information finns i containerresursens livslängd.

Konfigurera Cosmos DB emulatorcontainer med datavolym

Om du vill lägga till en datavolym i AzureAzure Cosmos DB-emulatorresursen anropar du metoden WithDataVolume på AzureAzure Cosmos DB-emulatorresursen:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Datavolymen används för att bevara Cosmos DB emulatordata utanför containerns livscykel. Datavolymen monteras på sökvägen /tmp/cosmos/appdata i emulatorcontainern Cosmos DB och när parametern name inte anges genereras namnet. Emulatorn har sin AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE miljövariabel inställd på true. För mer information om datavolymer och varför de föredras framför bind-mounts, se Docker dokumentation: Volymer.

Konfigurera Cosmos DB antal containerpartitioner för emulatorn

Om du vill konfigurera partitionsantalet för containern Cosmos DB emulator anropar du metoden WithPartitionCount:

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

Föregående kod konfigurerar Cosmos DB-emulatorcontainern till att ha ett partitionsantal på 100. Det här är en förkortning för att ange miljövariabeln AZURE_COSMOS_EMULATOR_PARTITION_COUNT.

Använda Linux-baserad emulator (förhandsversion)

nästa generation av AzureAzure Cosmos DB-emulatorn är helt Linux-baserad och är tillgänglig som en Docker container. Den stöder körning på en mängd olika processorer och operativsystem.

Om du vill använda förhandsversionen av Cosmos DB-emulatorn anropar du metoden RunAsPreviewEmulator. Eftersom den här funktionen är i förhandsversion måste du uttryckligen välja förhandsgranskningsfunktionen genom att utelämna ASPIRECOSMOSDB001 experimentell diagnostik.

Förhandsgranskningsemulatorn har också stöd för att exponera en slutpunkt för "Datautforskaren" som gör att du kan visa data som lagras i Cosmos DB-emulatorn via ett webbgränssnitt. Om du vill aktivera Datautforskaren anropar du metoden WithDataExplorer.

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

Föregående kod konfigurerar förhandsvisningscontainer för Linux-baserad emulator med Data Explorer-slutpunkt att användas vid körning.

Utför hälsokontroller för integration

Azure Cosmos DB värdintegrering lägger automatiskt till en hälsokontroll för den Cosmos DB resursen. Hälsokontrollen verifierar att Cosmos DB körs och att en anslutning kan upprättas till den.

Värdintegreringen förlitar sig på 📦 AspNetCore.HealthChecks.CosmosDb NuGet-paketet.

Client integration

Kom igång med .NET Aspire Microsoft Entity Framework CoreCosmos DB-integrering genom att installera 📦Aspire. Microsoft.EntityFrameworkCore.Cosmos NuGet-paket i det klientkrävande projektet, dvs. projektet för programmet som använder Microsoft Entity Framework CoreCosmos DB-klienten.

.NET CLI
PaketReferens

dotnet add package Aspire.Microsoft.EntityFrameworkCore.Cosmos

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

Lägg till Cosmos DB kontext

I Program.cs-filen för ditt klientprojekt anropar du utökningsmetoden AddCosmosDbContext för att registrera en System.Data.Entity.DbContext för användning via beroendeinjektionsbehållaren. Metoden tar en parameter för anslutningsnamn och en parameter för databasnamn.

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

Alternativt kan databasnamnet härledas från anslutningen när det finns en enda databas i anslutningssträngen. I det här fallet kan du utelämna parametern databasnamn:

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

Tips

Parametern connectionName måste överensstämma med namnet som används när man lägger till resursen Cosmos DB i appvärdprojektet. Med andra ord, när du anropar AddAzureCosmosDB och anger ett namn på cosmosdb ska samma namn användas när du anropar AddCosmosDbContext. Mer information finns i Lägg till AzureAzure Cosmos DB resurs.

Du kan sedan hämta DbContext-instansen med hjälp av beroendeinjektion. Om du till exempel vill hämta klienten från en tjänst:

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

Mer information om hur du använder Entity Framework Core med Azure Cosmos DBfinns i Exempel för Azure Cosmos DB för NoSQL SDK för .NET.

Konfiguration

Integreringen .NET Aspire Microsoft Entity Framework CoreCosmos DB innehåller flera alternativ för att konfigurera Azure Cosmos DB-anslutningen baserat på kraven och konventionerna i ditt projekt.

Använda en anslutningssträng

När du använder en anslutningssträng från ConnectionStrings konfigurationsavsnittet kan du ange namnet på anslutningssträngen när du anropar builder.AddCosmosDbContext:

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

Och sedan hämtas anslutningssträngen från ConnectionStrings-konfigurationsavsnittet:

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

Mer information finns i dokumentationen ConnectionString.

Använda konfigurationsprovidrar

Integrationen .NET Aspire mellan Microsoft Entity Framework CoreCosmos DB stöder Microsoft.Extensions.Configuration. Den läser in EntityFrameworkCoreCosmosSettings från konfigurationsfiler som appsettings.json. Exempel _appsettings.json som konfigurerar några av alternativen:

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

Det fullständiga Cosmos DB klientintegreringsschemat JSON finns i Aspire. Microsoft.EntityFrameworkCore.Cosmos/ConfigurationSchema.json.

Använd inline-delegater

Du kan också använda den delegerade Action<EntityFrameworkCoreCosmosSettings> configureSettings för att konfigurera vissa eller alla EntityFrameworkCoreCosmosSettings alternativ direkt, till exempel för att inaktivera spårning från koden.

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

Client hälsokontroller för integrering

.NET Aspire Microsoft Entity Framework CoreCosmos DB integrering implementerar för närvarande inte hälsokontroller, även om detta kan ändras i framtida versioner.

Observerbarhet och telemetri

.NET .NET Aspire integreringar konfigurerar automatiskt konfigurationer för loggning, spårning och mått, som ibland kallas grundpelarna för observerbarhet. Mer information om integreringsobservabilitet och telemetri finns i översikten över .NET.NET Aspire integreringar. Beroende på säkerhetskopieringstjänsten kanske vissa integreringar bara stöder vissa av dessa funktioner. Vissa integreringar stöder till exempel loggning och spårning, men inte mått. Telemetrifunktioner kan också inaktiveras med hjälp av de tekniker som visas i avsnittet Configuration.

Skogsavverkning

Integreringen .NET Aspire Microsoft Entity Framework CoreCosmos DB använder följande loggkategorier:

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

Spårning

Integreringen .NET Aspire Microsoft Entity Framework CoreCosmos DB genererar följande spårningsaktiviteter med hjälp av OpenTelemetry:

Azure.Cosmos.Operation
OpenTelemetry.Instrumentation.EntityFrameworkCore

Mätvärden

Integreringen .NET Aspire Microsoft Entity Framework CoreCosmos DB stöder för närvarande följande mått:

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