Aspire.Microsoft.EntityFrameworkCore.Cosmos 9.0.0-rc.1.24511.1

Aspire.Microsoft.EntityFrameworkCore.Cosmos library

Registers EntityFrameworkCore DbContext in the DI container for connecting to Azure Cosmos DB. Enables connection pooling, logging and telemetry.

Getting started

Prerequisites

• CosmosDB database and connection string for accessing the database.

Install the package

Install the .NET Aspire Microsoft EntityFrameworkCore Cosmos library with NuGet:

dotnet add package Aspire.Microsoft.EntityFrameworkCore.Cosmos

Usage example

In the Program.cs file of your project, call the AddCosmosDbContext extension method to register a DbContext for use via the dependency injection container. The method takes connection name and database name parameters.

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

You can then retrieve the MyDbContext instance using dependency injection. For example, to retrieve the context from a Web API controller:

private readonly MyDbContext _context;

public ProductsController(MyDbContext context)
{
    _context = context;
}

You might also need to configure specific option of CosmosDB, or register a DbContext in other ways. In this case call the EnrichCosmosDbContext extension method, for example:

var connectionString = builder.Configuration.GetConnectionString("mydb");
builder.Services.AddDbContextPool<MyDbContext>(dbContextOptionsBuilder => dbContextOptionsBuilder.UseCosmos(connectionString, "mydb"));
builder.EnrichCosmosDbContext<MyDbContext>();

Configuration

The .NET Aspire Microsoft EntityFrameworkCore Cosmos component provides multiple options to configure the database connection based on the requirements and conventions of your project.

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

builder.AddCosmosDbContext<MyDbContext>("myConnection", "mydb");

And then the connection string will be retrieved from the ConnectionStrings configuration section:

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

The EnrichCosmosDbContext won't make use of the ConnectionStrings, Region and AccountEndpoint configuration section since it expects a DbContext to be registered at the point it is called.

See the ConnectionString documentation for more information.

Use configuration providers

The .NET Aspire Microsoft EntityFrameworkCore Cosmos component supports Microsoft.Extensions.Configuration. It loads the EntityFrameworkCoreCosmosSettings from configuration by using the Aspire:Microsoft:EntityFrameworkCore:Cosmos key. Example appsettings.json that configures some of the options:

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

Use inline delegates

Also you can pass the Action<EntityFrameworkCoreCosmosSettings> configureSettings delegate to set up some or all the options inline, for example to disable tracing from code:

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

or

    builder.EnrichCosmosDbContext<MyDbContext>(settings => settings.DisableTracing = true);

AppHost extensions

In your AppHost project, install the Aspire Azure CosmosDB Hosting library with NuGet:

dotnet add package Aspire.Hosting.Azure.CosmosDB

Then, in the Program.cs file of AppHost, add a Cosmos DB connection and consume the connection using the following methods:

var cosmosdb = builder.AddAzureCosmosDB("cdb").AddDatabase("cosmosdb");

var myService = builder.AddProject<Projects.MyService>()
                       .WithReference(cosmosdb);

The AddAzureCosmosDB method will read connection information from the AppHost's configuration (for example, from "user secrets") under the ConnectionStrings:cosmosdb config key. The WithReference method passes that connection information into a connection string named cosmosdb in the MyService project. In the Program.cs file of MyService, the connection can be consumed using:

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

Emulator usage

Aspire supports the usage of the Azure Cosmos DB emulator to use the emulator, add the following to your AppHost project:

// AppHost
var cosmosdb = builder.AddAzureCosmosDB("cosmos").RunAsEmulator();

When the AppHost starts up a local container running the Azure CosmosDB will also be started:

// Service code
builder.AddCosmosDbContext<MyDbContext>("cosmos", "mydb");

Additional documentation

• https://learn.microsoft.com/ef/core/
• https://github.com/dotnet/aspire/tree/main/src/Components/README.md

Feedback & contributing

https://github.com/dotnet/aspire