Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

✅ Merge main into live #2366

Merged
merged 2 commits into from
Jan 9, 2025
Merged

✅ Merge main into live #2366

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7be334e
Orleans integration article rewrite (#2355)
alistairmatthews Jan 8, 2025
2f33d71
Rewrite of the Azure Cosmos DB articles (#2324)
IEvangelist Jan 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
131 changes: 55 additions & 76 deletions docs/database/azure-cosmos-db-entity-framework-integration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,27 @@
---
title: .NET Aspire Microsoft Entity Framework Core Cosmos DB integration
description: This article describes the .NET Aspire Microsoft Entity Framework Core Cosmos DB integration features and capabilities.
ms.topic: how-to
ms.date: 08/12/2024
title: .NET Aspire Cosmos DB Entity Framework Core integration
description: Learn how to install and configure the .NET Aspire Cosmos DB Entity Framework Core integration to connect to existing Cosmos DB instances or create new instances from .NET with the Azure Cosmos DB emulator.
ms.date: 12/18/2024
uid: dotnet/aspire/azure-cosmos-db-entity-framework-integration
---

# .NET Aspire Microsoft Entity Framework Core Cosmos DB integration
# .NET Aspire Cosmos DB Entity Framework Core integration

In this article, you learn how to use the .NET Aspire Microsoft Entity Framework Core Cosmos DB integration. 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.
[!INCLUDE [includes-hosting-and-client](../includes/includes-hosting-and-client.md)]

## Get started
[Azure Cosmos DB](https://azure.microsoft.com/services/cosmos-db/) is a fully managed NoSQL database service for modern app development. The .NET Aspire Cosmos DB Entity Framework Core integration enables you to connect to existing Cosmos DB instances or create new instances from .NET with the Azure Cosmos DB emulator.

## Hosting integration

[!INCLUDE [cosmos-app-host](includes/cosmos-app-host.md)]

### Hosting integration health checks

The Azure Cosmos DB hosting integration automatically adds a health check for the Cosmos DB resource. The health check verifies that the Cosmos DB is running and that a connection can be established to it.

The hosting integration relies on the [📦 AspNetCore.HealthChecks.CosmosDb](https://www.nuget.org/packages/AspNetCore.HealthChecks.CosmosDb) NuGet package.

## Client integration

To get started with the .NET Aspire Microsoft Entity Framework Core Cosmos DB integration, install the [📦 Aspire.Microsoft.EntityFrameworkCore.Cosmos](https://www.nuget.org/packages/Aspire.Microsoft.EntityFrameworkCore.Cosmos) NuGet package in the client-consuming project, i.e., the project for the application that uses the Microsoft Entity Framework Core Cosmos DB client.

Expand All @@ -28,16 +40,17 @@ dotnet add package Aspire.Microsoft.EntityFrameworkCore.Cosmos

---

For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-package) or [Manage package dependencies in .NET applications](/dotnet/core/tools/dependencies).

## Example usage
### Add Cosmos DB context

In the _:::no-loc text="Program.cs":::_ file of your client-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.
In the :::no-loc text="Program.cs"::: file of your client-consuming project, call the <xref:Microsoft.Extensions.Hosting.AspireAzureEFCoreCosmosExtensions.AddCosmosDbContext%2A> extension method to register a <xref:System.Data.Entity.DbContext?displayProperty=fullName> for use via the dependency injection container. The method takes a connection name parameter.

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

> [!TIP]
> The `connectionName` parameter must match the name used when adding the Cosmos DB resource in the app host project. In other words, when you call `AddAzureCosmosDB` and provide a name of `cosmosdb` that same name should be used when calling `AddCosmosDbContext`. For more information, see [Add Azure Cosmos DB resource](#add-azure-cosmos-db-resource).

You can then retrieve the <xref:Microsoft.EntityFrameworkCore.DbContext> instance using dependency injection. For example, to retrieve the client from a service:

```csharp
Expand All @@ -49,49 +62,11 @@ public class ExampleService(MyDbContext 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](/ef/core/providers/cosmos/?tabs=dotnet-core-cli).

## App host usage

To add Azure Cosmos DB hosting support to your <xref:Aspire.Hosting.IDistributedApplicationBuilder>, install the [📦 Aspire.Hosting.Azure.CosmosDB](https://www.nuget.org/packages/Aspire.Hosting.Azure.CosmosDB) NuGet package in the [app host](xref:dotnet/aspire/app-host) project.

### [.NET CLI](#tab/dotnet-cli)

```dotnetcli
dotnet add package Aspire.Hosting.Azure.CosmosDB
```

### [PackageReference](#tab/package-reference)

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

---

In your app host project, register the .NET Aspire Microsoft Entity Framework Core Cosmos DB integration and consume the service using the following methods:

```csharp
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.
>
> ```csharp
> cosmosdb.RunAsEmulator();
> ```

## Configuration
### Configuration

The .NET Aspire Microsoft Entity Framework Core Cosmos DB integration provides multiple options to configure the Azure Cosmos DB connection based on the requirements and conventions of your project.

### Use a connection string
#### Use a connection string

When using a connection string from the `ConnectionStrings` configuration section, you can provide the name of the connection string when calling `builder.AddCosmosDbContext`:

Expand All @@ -111,9 +86,9 @@ And then the connection string will be retrieved from the `ConnectionStrings` co

For more information, see the [ConnectionString documentation](/azure/cosmos-db/nosql/how-to-dotnet-get-started#connect-with-a-connection-string).

### Use configuration providers
#### Use configuration providers

The .NET Aspire Microsoft Entity Framework Core Cosmos DB integration 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:
The .NET Aspire Microsoft Entity Framework Core Cosmos DB integration supports <xref:Microsoft.Extensions.Configuration?displayProperty=fullName>. It loads the <xref:Aspire.Microsoft.EntityFrameworkCore.Cosmos.EntityFrameworkCoreCosmosSettings> from configuration files such as _:::no-loc text="appsettings.json":::_. Example _:::no-loc text="appsettings.json"::: that configures some of the options:

```json
{
Expand All @@ -129,7 +104,9 @@ The .NET Aspire Microsoft Entity Framework Core Cosmos DB integration supports <
}
```

### Use inline delegates
For the complete Cosmos DB client integration JSON schema, see [Aspire.Microsoft.EntityFrameworkCore.Cosmos/ConfigurationSchema.json](https://github.com/dotnet/aspire/blob/v9.0.0/src/Components/Aspire.Microsoft.EntityFrameworkCore.Cosmos/ConfigurationSchema.json).

#### Use inline delegates

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:

Expand All @@ -139,44 +116,46 @@ builder.AddCosmosDbContext<MyDbContext>(
settings => settings.DisableTracing = true);
```

[!INCLUDE [integration-health-checks](../includes/integration-health-checks.md)]
### Client integration health checks

By default, .NET Aspire integrations enable health checks for all services. For more information, see [.NET Aspire integrations overview](../fundamentals/integrations-overview.md).

The .NET Aspire Microsoft Entity Framework Core Cosmos DB integration currently doesn't implement health checks, though this may change in future releases.

[!INCLUDE [integration-observability-and-telemetry](../includes/integration-observability-and-telemetry.md)]

### Logging
#### Logging

The .NET Aspire Microsoft Entity Framework Core Cosmos DB integration uses the following log categories:

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

### Tracing
#### Tracing

The .NET Aspire Microsoft Entity Framework Core Cosmos DB integration will emit the following tracing activities using OpenTelemetry:

- Azure.Cosmos.Operation
- OpenTelemetry.Instrumentation.EntityFrameworkCore
- `Azure.Cosmos.Operation`
- `OpenTelemetry.Instrumentation.EntityFrameworkCore`

### Metrics
#### Metrics

The .NET Aspire Microsoft Entity Framework Core Cosmos DB integration 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
- `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`

## See also

Expand Down
Loading
Loading