Get started with the MongoDB Entity Framework Core integrations

MongoDB is a popular, open-source NoSQL document database that offers high performance, scalability, and flexible data modeling. The Aspire MongoDB Entity Framework Core (EF Core) client integration provides a way to connect to existing MongoDB databases, or create new instances from the docker.io/library/mongo container image.

In this introduction, you’ll see how to install and use the Aspire MongoDB Entity Framework Core integrations in a simple configuration. The same hosting integration is used with both the EF Core and the non-EF Core client integrations. If you already have this knowledge, see MongoDB Hosting integration and MongoDB EF Core client integration for full reference details.

Note

To follow this guide, you must have created an Aspire solution to work with. To learn how to do that, see Build your first Aspire app.

Set up hosting integration

To begin, install the Aspire MongoDB Hosting integration in your Aspire AppHost project. This integration allows you to create and manage MongoDB database instances from your Aspire hosting projects:

Aspire CLI

Aspire CLI — Add Aspire.Hosting.MongoDB package

aspire add mongodb

The Aspire CLI is interactive, be sure to select the appropriate search result when prompted:

Aspire CLI — Example output prompt

Select an integration to add:

> mongodb (Aspire.Hosting.MongoDB)
> Other results listed as selectable options...

Note

If there's only one result, the CLI selects it automatically. You'll still need to confirm the version.

apphost.cs (C# file-based app)

C# — AppHost.cs

#:package Aspire.Hosting.MongoDB@*

PackageReference (*.csproj)

XML — Add Aspire.Hosting.MongoDB package reference

<PackageReference Include="Aspire.Hosting.MongoDB" Version="*" />

Next, in the AppHost project, create instances of MongoDB server and database resources, then pass the database to the consuming client projects:

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var mongodb = builder.AddMongoDB("mongodb");
var mydb = mongodb.AddDatabase("mydb");

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
                            .WaitFor(mydb)
                            .WithReference(mydb);

Tip

This is the simplest implementation of MongoDB resources in the AppHost. There are many more options you can choose from to address your requirements. For full details, see MongoDB Hosting integration.

Use the integration in client projects

Now that the hosting integration is ready, the next step is to install and configure the EF Core client integration in any projects that need to use it.

Set up client projects

In each of these consuming client projects, install the Aspire MongoDB EF Core client integration:

.NET CLI

.NET CLI — Add Aspire.MongoDB.EntityFrameworkCore package

dotnet add package Aspire.MongoDB.EntityFrameworkCore

Program.cs (C# file-based app)

Program.cs

#:package Aspire.MongoDB.EntityFrameworkCore@*

PackageReference (*.csproj)

XML — Add Aspire.MongoDB.EntityFrameworkCore package reference

<PackageReference Include="Aspire.MongoDB.EntityFrameworkCore" Version="*" />

In the Program.cs file of your client-consuming project, call the AddMongoDbContext extension method on any IHostApplicationBuilder to register your DbContext subclass for use through the dependency injection container. The method takes a connection name parameter.

C# — Program.cs

builder.AddMongoDbContext<MyDbContext>(connectionName: "mydb");

Tip

The connectionName parameter must match the name used when adding the MongoDB database resource in the AppHost project. For more information, see Set up hosting integration.

Note

When using AddDatabase in the AppHost, the database name is included in the generated connection string, so you don’t need to specify it again in AddMongoDbContext. If your connection string doesn’t include a database name, you can provide it as the second parameter: builder.AddMongoDbContext<MyDbContext>("mydb", "mydatabase").

Use MongoDB resources in client code

Now that you’ve added the DbContext to the builder in the consuming project, you can use the MongoDB resource to get and store data. Get the DbContext instance using dependency injection. For example, to retrieve your database context object from an example service define it as a constructor parameter and ensure the ExampleService class is registered with the dependency injection container:

C# — ExampleService.cs

public class ExampleService(MyDbContext context)
{
    // Use context to interact with the database...
}

Having obtained the database context, you can work with the MongoDB database as you would in any other C# application using EF Core.

Next steps

Now that you have an Aspire app with MongoDB EF Core integrations up and running, you can use the following reference documents to learn how to configure and interact with the MongoDB resources:

Understand the MongoDB hosting integration Discover how to configure persistence, MongoDB Express, and more.

Understand the MongoDB EF Core client integration Discover how to enrich DbContext, configure settings, and more.