Dela via

.NET Aspire Cosmos DB Entity Framework Core integrering

  • Artikel

omfattar:Värdtjänstintegration och Client 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.

Värdintegrering

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

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.

dotnet add package Aspire.Hosting.Azure.CosmosDB

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 appvärden görs 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.

Genererad tillhandahållande av 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:


Växla 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
}

Föregående Bicep är en modul som etablerar ett AzureAzure Cosmos DB konto med följande standardvärden:

  • kind: Typen av Cosmos DB konto. Standardvärdet är GlobalDocumentDB.
  • consistencyPolicy: Konsekvensprincipen för Cosmos DB-kontot. Standardvärdet är Session.
  • locations: Platserna för Cosmos DB-kontot. Standardvärdet är resursgruppens plats.

Utöver kontot Cosmos DB etablerar det även resursen Azure Key Vault. Detta används för att lagra Cosmos DB-kontots anslutningssträng på ett säkert sätt. Den genererade Bicep är en startpunkt och kan anpassas för att uppfylla dina specifika krav.

Anpassa etableringsinfrastruktur

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

Det finns många fler konfigurationsalternativ för att anpassa AzureAzure Cosmos DB resursen. Mer information finns i Azure.Provisioning.CosmosDB. Mer information finns i Azure. Anpassning av tilldelning.

Ansluta till ett befintligt AzureAzure Cosmos DB konto

Du kan ha ett befintligt AzureAzure Cosmos DB konto som du vill ansluta till. I stället för att representera en ny AzureAzure Cosmos DB resurs kan du lägga till en anslutningssträng till appvärd. Om du vill lägga till en anslutning till ett befintligt AzureAzure Cosmos DB konto anropar du metoden AddConnectionString:

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

Not

Anslutningssträngar används för att representera ett brett spektrum av anslutningsinformation, inklusive databasanslutningar, meddelandeköer, slutpunkts-URI:er och andra tjänster. I .NET.NET Aspire nomenklatur används termen "anslutningssträng" för att representera alla typer av anslutningsinformation.

Anslutningssträngen konfigureras i appvärdens konfiguration, vanligtvis under Användarhemligheter, under avsnittet ConnectionStrings. Appvärden matar in den här anslutningssträngen som en miljövariabel i alla beroende resurser, till exempel:

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

Den beroende resursen kan komma åt den inmatade anslutningssträngen genom att anropa metoden GetConnectionString och skicka anslutningsnamnet som parameter, i det här fallet "cosmos-db". API:et GetConnectionString är en förkortning för IConfiguration.GetSection("ConnectionStrings")[name].

Lägga till AzureAzure Cosmos DB databasresurs

Om du vill lägga till en AzureAzure Cosmos DB databasresurs kedjar du ett anrop på en IResourceBuilder<AzureCosmosDBResource> till AddDatabase-API:et:

var builder = DistributedApplication.CreateBuilder(args);

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

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

När du anropar AddDatabasekonfigureras dina Cosmos DB resurser för att ha en databas med namnet db. 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. Mer information finns i Databaser, containrar och objekt i AzureAzure Cosmos DB.

Not

Om du använder AddDatabase-API:et för att lägga till en databas i en AzureAzure Cosmos DB resurs, skapas inte databasen i emulatorn om du kör emulatorn. Det här API:et är avsett att inkludera en databas i Bicep som genererats av försörjningsinfrastrukturen.

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. Mer information om datavolymer och information om varför de föredras framför bindningsmonteringar finns i Docker dokument: 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.

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

dotnet add package Aspire.Microsoft.EntityFrameworkCore.Cosmos

Lägg till Cosmos DB kontext

I den Program.cs filen för ditt klientanvändande projekt anropar du utökningsmetoden AddCosmosDbContext för att registrera en System.Data.Entity.DbContext för användning via beroendeinjektionskontainern. Metoden tar en parameter för anslutningsnamn.

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ända infogade ombud

Du kan också använda Action<EntityFrameworkCoreCosmosSettings> configureSettings delegat för att konfigurera vissa eller alla EntityFrameworkCoreCosmosSettings alternativ inline, till exempel för att inaktivera spårning i koden.

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

Client hälsokontroller för integrering

Som standard aktiverar .NET.NET Aspire integreringar hälsokontroller för alla tjänster. Mer information finns i översikten över .NET.NET Aspire integreringar.

.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

Se även