Poznámka
Přístup k této stránce vyžaduje autorizaci. Můžete se zkusit přihlásit nebo změnit adresáře.
Přístup k této stránce vyžaduje autorizaci. Můžete zkusit změnit adresáře.
Azure Cosmos DB je plně spravovaná databázová služba NoSQL pro moderní vývoj aplikací. Integrace .NET AspireCosmos DBEntity Framework Core umožňuje připojit se k existujícím instancím Cosmos DB nebo vytvářet nové instance z .NET pomocí emulátoru Azure Cosmos DB.
Integrace hostování
.NET .NET Aspire Azure Cosmos DB integrační hostovací modely modelují různé zdroje Cosmos DB jako následující typy:
- AzureCosmosDBResource: Představuje zdroj AzureAzure Cosmos DB.
- AzureCosmosDBContainerResource: Představuje AzureAzure Cosmos DB zdroj kontejneru.
- AzureCosmosDBDatabaseResource: Představuje AzureAzure Cosmos DB databázový prostředek.
- AzureCosmosDBEmulatorResource: Představuje prostředek emulátoru AzureAzure Cosmos DB.
Pokud chcete získat přístup k těmto typům a rozhraním API pro jejich vyjádření, přidejte balíček NuGet 📦Aspire.Hosting.Azure.CosmosDB do projektu hostování aplikace.
dotnet add package Aspire.Hosting.Azure.CosmosDB
Další informace najdete v tématu dotnet add package nebo Správa závislostí balíčků v .NET aplikacích.
Přidejte prostředek AzureAzure Cosmos DB
V projektu hostitele vaší aplikace zavolejte AddAzureCosmosDB, abyste přidali a vrátili tvůrce prostředků AzureAzure Cosmos DB.
var builder = DistributedApplication.CreateBuilder(args);
var cosmos = builder.AddAzureCosmosDB("cosmos-db");
// After adding all resources, run the app...
Když do hostitele aplikace přidáte AzureCosmosDBResource, zveřejní další užitečná rozhraní API pro přidání databází a kontejnerů. Jinými slovy, musíte přidat AzureCosmosDBResource
před přidáním některého z dalších Cosmos DB zdrojů.
Důležitý
Při volání AddAzureCosmosDBse automaticky volá AddAzureProvisioning– což dynamicky přidává podporu pro generování prostředků Azure při startu aplikace. Aplikace musí nakonfigurovat příslušné předplatné a umístění. Pro získání více informací nahlédněte do části Místní zřizování: Konfigurace.
Vygenerovaný Bicep pro zřizování
Pokud s Bicep začínáte, jedná se o doménově specifický jazyk pro definování Azure prostředků. S .NET.NET Aspire nemusíte psát Bicep ručně, místo toho za vás generují Bicep provisioning API. Když publikujete svou aplikaci, vygenerovaný Bicep je zahrnut společně se souborem manifestu. Když přidáte prostředek AzureAzure Cosmos DB, vygeneruje se následující 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
Předchozí Bicep je modul, který zřizuje prostředek účtu AzureAzure Cosmos DB. Dále jsou přiřazení rolí vytvořena pro prostředek Azure v samostatném modulu.
@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
}
Vygenerovaný Bicep je výchozím bodem a je ovlivněný změnami infrastruktury zřizování v C#. Přímé úpravy souboru Bicep budou přepsány, proto provádějte změny prostřednictvím C# provisioning rozhraní API, aby se zajistilo, že se promítnou do vygenerovaných souborů.
Přizpůsobení infrastruktury pro zřizování zdrojů
Všechny prostředky .NET AspireAzure jsou podtřídy typu AzureProvisioningResource. Tento typ umožňuje přizpůsobení vygenerovaného Bicepu poskytnutím fluentního API pro konfiguraci prostředků Azure pomocí API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Můžete například nakonfigurovat kind
, consistencyPolicy
, locations
atd. Následující příklad ukazuje, jak přizpůsobit prostředek AzureAzure Cosmos DB:
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");
});
Předchozí kód:
- Zřetězení volání na rozhraní API ConfigureInfrastructure:
- Parametr
infra
je instance typu AzureResourceInfrastructure. - Zdroje určené k zajištění se načtou voláním metody GetProvisionableResources().
- Je získán jeden CosmosDBAccount.
- CosmosDBAccount.ConsistencyPolicy je přiřazen k DefaultConsistencyLevel.Strong.
- Značka se přidá do účtu Cosmos DB s klíčem
ExampleKey
a hodnotouExample value
.
- Parametr
Pro přizpůsobení prostředku AzureAzure Cosmos DB je k dispozici mnoho dalších možností konfigurace. Další informace najdete v tématu Azure.Provisioning.CosmosDB. Další informace naleznete v AzurePřizpůsobení zřizování.
Připojení k existujícímu účtu AzureAzure Cosmos DB
Možná máte existující účet AzureAzure Cosmos DB, ke kterému se chcete připojit. Můžete řetězit volání, abyste označili, že AzureCosmosDBResource je existující prostředek:
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...
Důležitý
Když zavoláte metody RunAsExisting
, PublishAsExisting
nebo AsExisting
pro práci s prostředky, které již máte ve svém předplatném Azure, musíte do aplikačního hostitele přidat určité konfigurační hodnoty, aby je .NET Aspire mohl najít. Mezi nezbytné hodnoty konfigurace patří SubscriptionId, AllowResourceGroupCreation, ResourceGroup a Location. Pokud je nenastavíte, zobrazí se na řídicím panelu .NET.NET Aspire chyby 'Chybějící konfigurace'. Další informace o tom, jak je nastavit, najdete v tématu Konfigurace.
Další informace o zacházení s prostředky jako s existujícími AzureAzure Cosmos DB prostředky najdete v tématu Použití existujících Azure prostředků.
Poznámka
Alternativně namísto zobrazování zdroje AzureAzure Cosmos DB můžete k hostiteli aplikace přidat připojovací řetězec. Tento přístup je slabě napsaný a nefunguje s přiřazeními rolí ani vlastními nastaveními infrastruktury. Další informace najdete v části Přidat existující prostředky s připojovacími řetězciAzure.
Přidejte AzureAzure Cosmos DB prostředky databáze a kontejneru
Modely .NET Aspire vztahů mezi nadřazenými a podřízenými Azure Cosmos DB zdroji. Například AzureAzure Cosmos DB účet (AzureCosmosDBResource) může mít více databází (AzureCosmosDBDatabaseResource) a každá databáze může mít více kontejnerů (AzureCosmosDBContainerResource). Když přidáte databázi nebo kontejnerový prostředek, uděláte to na nadřazeném prostředku.
Pokud chcete přidat prostředek databáze AzureAzure Cosmos DB, zavolejte metodu AddCosmosDatabase na instanci IResourceBuilder<AzureCosmosDBResource>
.
var builder = DistributedApplication.CreateBuilder(args);
var cosmos = builder.AddAzureCosmosDB("cosmos-db");
var db = cosmos.AddCosmosDatabase("db");
// After adding all resources, run the app...
Při volání AddCosmosDatabase
přidá do prostředků db
databázi s názvem Cosmos DB a vrátí nově vytvořený databázový prostředek. Databáze se vytvoří v účtu Cosmos DB, který je reprezentován AzureCosmosDBResource
, přidaným dříve. Databáze je logický kontejner pro kolekce a uživatele.
V kontejneru AzureAzure Cosmos DB jsou uložená data. Při vytváření kontejneru musíte zadat klíč oddílu.
Pokud chcete přidat prostředek kontejneru AzureAzure Cosmos DB, zavolejte metodu AddContainer na instanci IResourceBuilder<AzureCosmosDBDatabaseResource>
.
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...
Kontejner se vytvoří v databázi, která je reprezentovaná AzureCosmosDBDatabaseResource
, kterou jste přidali dříve. Další informace naleznete v tématu Databáze, kontejnery a položky v AzureAzure Cosmos DB.
Příklad vztahu prostředků rodič-dítě
Pokud chcete lépe porozumět vztahu nadřazenosti a podřízenosti mezi Azure Cosmos DB prostředky, zvažte následující příklad, který ukazuje přidání Azure Cosmos DB prostředku spolu s databází a kontejnerem:
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();
Předchozí kód přidá AzureAzure Cosmos DB prostředek s názvem cosmos
se dvěma databázemi: customers
a orders
. Databáze customers
má jeden kontejner s názvem profiles
, zatímco orders
databáze má dva kontejnery: details
a history
. Klíč partice pro každý kontejner je /id
.
Následující diagram znázorňuje vztah rodič-dítě mezi prostředky Azure a Azure Cosmos DB:
Když kód hostitele aplikace vyjadřuje vztahy nadřazenosti a podřízenosti, klient může pomocí názvu napřímo propojit tyto prostředky. Na databázi customers
lze například odkazovat jako názvem v klientském projektu a zaregistrovat instanci Database, která se připojuje k databázi customers
. Totéž platí pro pojmenované kontejnery, například kontejner details
může být odkazován názvem v klientském projektu, přičemž registruje instanci Container, která se připojuje ke kontejneru details
.
Přidejte prostředek emulátoru AzureAzure Cosmos DB
Chcete-li přidat prostředek emulátoru AzureAzure Cosmos DB, zřetězte volání IResourceBuilder<AzureCosmosDBResource>
k rozhraní API RunAsEmulator:
var builder = DistributedApplication.CreateBuilder(args);
var cosmos = builder.AddAzureCosmosDB("cosmos-db")
.RunAsEmulator();
// After adding all resources, run the app...
Při volání RunAsEmulator
nakonfiguruje prostředky Cosmos DB tak, aby se spouštěly místně pomocí emulátoru. V tomto případě je emulátor AzureAzure Cosmos DB Emulator. Emulátor Azure Cosmos DB poskytuje bezplatné místní prostředí pro testování vašich Azure Cosmos DB aplikací a je to dokonalý doplněk k integraci .NET AspireAzure hostování. Emulátor není nainstalovaný, ale je přístupný pro .NET.NET Aspire jako kontejner. Když do hostitele aplikace přidáte kontejner, jak je znázorněno v předchozím příkladu s imagí mcr.microsoft.com/cosmosdb/emulator
, vytvoří a spustí kontejner při spuštění hostitele aplikace. Další informace najdete v části životní cyklus zdrojů kontejneru.
Konfigurace kontejneru emulátoru Cosmos DB
Pro prostředky kontejneru jsou k dispozici různé konfigurace, například můžete nakonfigurovat porty kontejneru, proměnné prostředí, životnostatd.
Konfigurace portu brány kontejneru emulátoru Cosmos DB
Ve výchozím nastavení kontejner emulátoru Cosmos DB při konfiguraci .NET Aspirezveřejňuje následující koncové body:
Koncový bod | Kontejnerový přístav | Hostitelský port |
---|---|---|
https |
8081 | dynamický |
Port, na který naslouchá, je ve výchozím nastavení dynamický. Při spuštění kontejneru se port mapuje na náhodně vybraný port na hostitelském počítači. Pokud chcete nakonfigurovat port koncového bodu, propojte volání na tvůrce zdrojů kontejneru, který poskytuje metoda RunAsEmulator
, jak je znázorněno v následujícím příkladu:
var builder = DistributedApplication.CreateBuilder(args);
var cosmos = builder.AddAzureCosmosDB("cosmos-db").RunAsEmulator(
emulator =>
{
emulator.WithGatewayPort(7777);
});
// After adding all resources, run the app...
Kód uvedený výše nakonfiguruje kontejner emulátoru Cosmos DB tak, aby jeho existující koncový bod https
naslouchal na portu 8081
. Port kontejneru emulátoru Cosmos DB se mapuje na port hostitele, jak je znázorněno v následující tabulce:
Název koncového bodu | Mapování portů (container:host ) |
---|---|
https |
8081:7777 |
Konfigurace kontejneru emulátoru Cosmos DB s trvalou životností
Pokud chcete nakonfigurovat kontejner emulátoru Cosmos DB s trvalou životností, zavolejte metodu WithLifetime v prostředku kontejneru emulátoru Cosmos DB a předejte 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...
Další informace najdete v části Životní cyklus prostředků kontejneru.
Nakonfigurujte kontejner emulátoru Cosmos DB s datovým svazkem
Pokud chcete přidat datový svazek do prostředku emulátoru AzureAzure Cosmos DB, zavolejte metodu WithDataVolume prostředku emulátoru AzureAzure Cosmos DB:
var builder = DistributedApplication.CreateBuilder(args);
var cosmos = builder.AddAzureCosmosDB("cosmos-db").RunAsEmulator(
emulator =>
{
emulator.WithDataVolume();
});
// After adding all resources, run the app...
Datový svazek slouží k zachování dat emulátoru Cosmos DB mimo životní cyklus kontejneru. Datový svazek se připojí k cestě /tmp/cosmos/appdata
v kontejneru emulátoru Cosmos DB a pokud není zadaný parametr name
, vygeneruje se název. Emulátor má svou AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE
proměnnou prostředí nastavenou na true
. Další informace o datových svazcích a podrobnosti o tom, proč jsou upřednostňovány před připojovacími body, najdete v dokumentaci Docker: Svazky.
Konfigurace počtu oddílů kontejneru emulátoru Cosmos DB
Pokud chcete nakonfigurovat počet oddílů kontejneru emulátoru Cosmos DB, zavolejte metodu 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...
Předchozí kód nakonfiguruje kontejner emulátoru Cosmos DB tak, aby měl počet oddílů 100
. Toto je zkratka pro nastavení proměnné prostředí AZURE_COSMOS_EMULATOR_PARTITION_COUNT
.
Použijte emulátor založený na Linux(náhled)
Azure Podporuje spouštění na široké škále procesorů a operačních systémů.
Pokud chcete použít verzi Preview emulátoru Cosmos DB, zavolejte metodu RunAsPreviewEmulator. Vzhledem k tomu, že je tato funkce ve verzi Preview, musíte explicitně povolit tuto verzi potlačením experimentální diagnostiky ASPIRECOSMOSDB001
.
Emulátor verze Preview také podporuje zpřístupnění koncového bodu „Průzkumník dat“, který umožňuje zobrazit data uložená v emulátoru Cosmos DB prostřednictvím webovým uživatelským rozhraním. Chcete-li povolit Průzkumníka dat, zavolejte metodu 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...
Předchozí kód konfiguruje kontejner emulátoru na bázi Linux s koncovým bodem Průzkumníka dat, který bude použit při běhu.
Hostování kontrol stavu integrace
Integrace hostování Azure Cosmos DB automaticky přidá kontrolu stavu prostředku Cosmos DB. Kontrola funkčnosti ověřuje, že je Cosmos DB spuštěn a lze se k němu připojit.
Integrace hostování spoléhá na 📦 NuGet balíček AspNetCore.HealthChecks.CosmosDb.
Client integrace
Pokud chcete začít s integrací .NET Aspire Microsoft Entity Framework CoreCosmos DB, nainstalujte 📦Aspire.Microsoft.EntityFrameworkCore.Cosmos balíček NuGet v projektu klienta, tj. v projektu pro aplikaci, která využívá klienta Microsoft Entity Framework CoreCosmos DB.
dotnet add package Aspire.Microsoft.EntityFrameworkCore.Cosmos
Přidejte kontext Cosmos DB
Ve souboru Program.cs ve vašem projektu používajícím klienta zavolejte rozšiřující metodu AddCosmosDbContext, která zaregistruje System.Data.Entity.DbContext k použití přes kontejner pro injektování závislostí. Metoda přebírá parametr názvu připojení a parametr názvu databáze.
builder.AddCosmosDbContext<MyDbContext>("cosmosdb", "databaseName");
Případně je možné název databáze odvodit z připojení, pokud je v připojovacím řetězci jedna databáze. V tomto případě můžete vynechat parametr názvu databáze:
builder.AddCosmosDbContext<MyDbContext>("cosmosdb");
Návod
Parametr connectionName
se musí shodovat s názvem použitým při přidávání prostředku Cosmos DB do hostitelského projektu aplikace. Jinými slovy, když voláte AddAzureCosmosDB
a zadáte název cosmosdb
, stejné jméno by mělo být použito při volání AddCosmosDbContext
. Další informace najdete v tématu Přidání AzureAzure Cosmos DB prostředků.
Potom můžete načíst instanci DbContext pomocí injekce závislostí. Například načíst klienta ze služby:
public class ExampleService(MyDbContext context)
{
// Use context...
}
Další informace o použití Entity Framework Core s Azure Cosmos DBnaleznete v tématu Příklady pro Azure Cosmos DB pro sadu NoSQL SDK pro .NET.
Konfigurace
Integrace .NET Aspire Microsoft Entity Framework CoreCosmos DB poskytuje několik možností konfigurace připojení Azure Cosmos DB na základě požadavků a konvencí projektu.
Použijte připojovací řetězec
Při použití připojovacího řetězce z oddílu konfigurace ConnectionStrings
můžete při volání builder.AddCosmosDbContext
zadat název připojovacího řetězce:
builder.AddCosmosDbContext<MyDbContext>("CosmosConnection");
A potom se připojovací řetězec načte z konfiguračního oddílu ConnectionStrings
.
{
"ConnectionStrings": {
"CosmosConnection": "AccountEndpoint=https://{account_name}.documents.azure.com:443/;AccountKey={account_key};"
}
}
Další informace naleznete v dokumentaci ConnectionString.
Použití zprostředkovatelů konfigurace
Integrace .NET Aspire společnosti Microsoft Entity Framework CoreCosmos DB podporuje Microsoft.Extensions.Configuration. Načte EntityFrameworkCoreCosmosSettings z konfiguračních souborů, jako je appsettings.json. Příklad _appsettings.json, který konfiguruje některé z možností:
{
"Aspire": {
"Microsoft": {
"EntityFrameworkCore": {
"Cosmos": {
"DisableTracing": true
}
}
}
}
}
Kompletní schéma integrace klienta Cosmos DBJSON najdete v tématu Aspire.Microsoft.EntityFrameworkCore.Cosmos/ConfigurationSchema.json.
Použití vložených delegátů
Můžete také předat delegáta Action<EntityFrameworkCoreCosmosSettings> configureSettings
a nastavit některé nebo všechny možnosti EntityFrameworkCoreCosmosSettings přímo, například zakázat sledování z kódu.
builder.AddCosmosDbContext<MyDbContext>(
"cosmosdb",
settings => settings.DisableTracing = true);
Client kontroly stavu integrace
Integrace .NET Aspire Microsoft Entity Framework CoreCosmos DB v současné době neimplementuje kontroly stavu, i když se to může v budoucích verzích změnit.
Pozorovatelnost a telemetrie
.NET .NET Aspire integrace automaticky nastaví konfigurace pro protokolování, trasování a metriky, které se někdy označují jako pilíře pozorovatelnosti. Další informace o pozorovatelnosti a telemetrii integrace najdete v přehledu integrace .NET.NET Aspire. V závislosti na zálohovací službě můžou některé integrace podporovat pouze některé z těchto funkcí. Například některé integrace podporují protokolování a trasování, ale ne metriky. Funkce telemetrie je také možné zakázat pomocí technik uvedených v části Konfigurace.
Protokolování
Integrace .NET Aspire Microsoft Entity Framework CoreCosmos DB používá následující kategorie protokolů:
Azure-Cosmos-Operation-Request-Diagnostics
Microsoft.EntityFrameworkCore.ChangeTracking
Microsoft.EntityFrameworkCore.Database.Command
Microsoft.EntityFrameworkCore.Infrastructure
Microsoft.EntityFrameworkCore.Query
Trasování
Integrace .NET Aspire Microsoft Entity Framework CoreCosmos DB vygeneruje následující aktivity tracování pomocí OpenTelemetry:
Azure.Cosmos.Operation
OpenTelemetry.Instrumentation.EntityFrameworkCore
Metriky
Integrace .NET Aspire Microsoft Entity Framework CoreCosmos DB v současné době podporuje následující metriky:
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