Aspire.Microsoft.EntityFrameworkCore.Cosmos 8.0.0-preview.1.23557.2

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][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 a connection name parameter.

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

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;
}

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");

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};"
  }
}

See the ConnectionString documentation for more information.

Use configuration providers

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

{
  "Aspire": {
    "Microsoft": {
      "EntityFrameworkCore": {
        "Cosmos": {
          "DbContextPooling": true,
          "Tracing": false
        }
      }
    }
  }
}

Use inline delegates

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

    builder.AddCosmosDbContext<MyDbContext>("cosmosdb", settings => settings.Tracing = false);

AppHost extensions

In your AppHost project, 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 WithReference method configures a connection in the MyService project named cosmosdb. In the Program.cs file of MyService, the database connection can be consumed using:

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

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