title | description | ms.topic | ms.date |
---|---|---|---|
.NET Aspire Microsoft Entity Framework Core Cosmos DB component |
This article describes the .NET Aspire Microsoft Entity Framework Core Cosmos DB component features and capabilities. |
how-to |
07/17/2024 |
In this article, you learn how to use the .NET Aspire Microsoft Entity Framework Core Cosmos DB component. The Aspire.Microsoft.EntityFrameworkCore.Cosmos
library is used to register a xref:System.Data.Entity.DbContext?displayProperty=fullName as a singleton in the DI container for connecting to Azure Cosmos DB. It also enables corresponding health checks, logging and telemetry.
To get started with the .NET Aspire Microsoft Entity Framework Core Cosmos DB component, install the Aspire.Microsoft.EntityFrameworkCore.Cosmos NuGet package in the consuming client project.
dotnet add package Aspire.Microsoft.EntityFrameworkCore.Cosmos
<PackageReference Include="Aspire.Microsoft.EntityFrameworkCore.Cosmos"
Version="[SelectVersion]" />
For more information, see dotnet add package or Manage package dependencies in .NET applications.
In the :::no-loc text="Program.cs"::: file of your component-consuming project, call the xref:Microsoft.Extensions.Hosting.AspireAzureEFCoreCosmosExtensions.AddCosmosDbContext%2A extension to register a xref:System.Data.Entity.DbContext?displayProperty=fullName for use via the dependency injection container.
builder.AddCosmosDbContext<MyDbContext>("cosmosdb");
You can then retrieve the xref:Microsoft.EntityFrameworkCore.DbContext instance using dependency injection. For example, to retrieve the client from a service:
public class ExampleService(MyDbContext context)
{
// Use context...
}
For more information on using Entity Framework Core with Azure Cosmos DB, see the Examples for Azure Cosmos DB for NoSQL SDK for .NET.
To add Azure Cosmos DB hosting support to your xref:Aspire.Hosting.IDistributedApplicationBuilder, install the Aspire.Hosting.Azure.CosmosDB NuGet package in the app host project.
dotnet add package Aspire.Hosting.Azure.CosmosDB
<PackageReference Include="Aspire.Hosting.Azure.CosmosDB"
Version="[SelectVersion]" />
In your app host project, register the .NET Aspire Microsoft Entity Framework Core Cosmos DB component and consume the service using the following methods:
var builder = DistributedApplication.CreateBuilder(args);
var cosmos = builder.AddAzureCosmosDB("cosmos");
var cosmosdb = cosmos.AddDatabase("cosmosdb");
var exampleProject = builder.AddProject<Projects.ExampleProject>()
.WithReference(cosmosdb);
Tip
To use the Azure Cosmos DB emulator, chain a call to the xref:Aspire.Hosting.AzureCosmosExtensions.AddAzureCosmosDB%2A method.
cosmosdb.RunAsEmulator();
The .NET Aspire Microsoft Entity Framework Core Cosmos DB component provides multiple options to configure the Azure Cosmos DB connection based on the requirements and conventions of your project.
When using a connection string from the ConnectionStrings
configuration section, you can provide the name of the connection string when calling builder.AddCosmosDbContext
:
builder.AddCosmosDbContext<MyDbContext>("CosmosConnection");
And then the connection string will be retrieved from the ConnectionStrings
configuration section:
{
"ConnectionStrings": {
"CosmosConnection": "AccountEndpoint=https://{account_name}.documents.azure.com:443/;AccountKey={account_key};"
}
}
For more information, see the ConnectionString documentation.
The .NET Aspire Microsoft Entity Framework Core Cosmos DB component supports xref:Microsoft.Extensions.Configuration?displayProperty=fullName. It loads the <xref:Aspire.Microsoft.EntityFrameworkCore.Cosmos.EntityFrameworkCoreCosmosSettings > from :::no-loc text="appsettings.json"::: or other configuration files using Aspire:Microsoft:EntityFrameworkCore:Cosmos
key. Example :::no-loc text="appsettings.json"::: that configures some of the options:
{
"Aspire": {
"Microsoft": {
"EntityFrameworkCore": {
"Cosmos": {
"DisableTracing": true
}
}
}
}
}
You can also pass the Action<EntityFrameworkCoreCosmosSettings> configureSettings
delegate to set up some or all the xref:Aspire.Microsoft.EntityFrameworkCore.Cosmos.EntityFrameworkCoreCosmosSettings options inline, for example to disable tracing from code:
builder.AddCosmosDbContext<MyDbContext>(
"cosmosdb",
settings => settings.DisableTracing = true);
[!INCLUDE component-health-checks]
The .NET Aspire Microsoft Entity Framework Core Cosmos DB component currently doesn't implement health checks, though this may change in future releases.
[!INCLUDE component-observability-and-telemetry]
The .NET Aspire Microsoft Entity Framework Core Cosmos DB component uses the following log categories:
- Azure-Cosmos-Operation-Request-Diagnostics
- Microsoft.EntityFrameworkCore.ChangeTracking
- Microsoft.EntityFrameworkCore.Database.Command
- Microsoft.EntityFrameworkCore.Infrastructure
- Microsoft.EntityFrameworkCore.Query
The .NET Aspire Microsoft Entity Framework Core Cosmos DB component will emit the following tracing activities using OpenTelemetry:
- Azure.Cosmos.Operation
- OpenTelemetry.Instrumentation.EntityFrameworkCore
The .NET Aspire Microsoft Entity Framework Core Cosmos DB component currently supports the following metrics:
- 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