Using Databases In Aspire

Aspire is all about making your life as a developer easier, and working with databases is no different. With Aspire, in just a couple of steps, you can set up and configure your application to use a data source. Our example uses SQL Server, and we include a list to other supported data sources at the end of this article.

AppHost Setup

For most data sources there are two integration packages you’ll need to install. The first one is the Hosting package. That will get installed into the Aspire AppHost project. We’ll start by installing the relevant NuGet package for SQL Server. There are multiple ways to install the Hosting package.

Dotnet Command Line

dotnet add package Aspire.Hosting.SqlServer

Aspire CLI

aspire add Aspire.Hosting.SqlServer --project .

Remember with the Aspire CLI you will need to specify the project you want it to work with, even if you’re in the folder of the project. See more about that in our previous blog post about the Aspire CLI.

Visual Studio

Visual Studio makes it easy to find Aspire packages in NuGet. Right click on Dependencies under your AppHost project in Solution Explorer.

This will open the NuGet package manager and filter the list of NuGet packages to those Aspire packages you might add to your AppHost project. Here you can see it opened NuGet Package Manager and added the filters: owner:Aspire tags:integration+hosting.

Once you’ve got the package added, you can add your initial configuration to you AppHost.cs file. You would typically add code like the following.

var sqlServer = builder.AddSqlServer("sqlServer");
var database = sqlServer.AddDatabase("appdb");

These two lines define a SQL Server database instance and a database on that server. By default, if you don’t do anything else, when the AppHost runs, it will use Docker Desktop to spin up a new instance of SQL Server in a container and then create an database named “appdb” on that server. When you shut down your Aspire app, that instance will go away.

If you want Aspire to keep that Docker instance of SQL Server so it doesn’t get recreated each time, you can do that in a couple of ways. First, you can just assign a data volume. Docker will keep that data and attach it to the instance of SQL Server that gets spun up when you run your Aspire application.

var sql = builder.AddSqlServer("sqlServer")
    .WithDataVolume();
var database = sql.AddDatabase("appdb");

Or, if you want to keep the container with SQL Server running, you can use the .WithLifetime command. This will keep the created container and won’t create a new SQL Server instance each time you run your Aspire app. This is the fastest, but it also keeps an instance of SQL Server running on your machine.

var sql = builder.AddSqlServer("sqlServer")
    .WithLifetime(ContainerLifetime.Persistent);
var database = sql.AddDatabase("appdb");

If you would rather Aspire make use of an existing instance of SQL Server, such as on your LocalDB or some other instance of SQL Server, you can instead provide a reference to the existing database’s connection string, as follows:

var sqlDb = builder.AddConnectionString("sqldb");

Then, in the appSettings.json file in the AppHost project, you would add a connectionString reference with the name "sqldb", just as you would anywhere else.

{
  "ConnectionStrings": {
    "sqldb": "Server=(localdb)\\mssqllocaldb;Database=my-aspire-database;Trusted_Connection=True;MultipleActiveResultSets=true"
  }
}

Instead of spinning up an instance of SQL Server in Docker Desktop and passing that connectionString to the client projects, it will pass along the connectionString from the AppHost appSettings file.

So now that we’ve defined our server and database, we want our API project to be able to receive the configuration information about that database so that it can connect to it. For this we use the .WithReference() Fluent syntax. The reference gets added as part of the API project definition in our AppHost.cs file, like so:

var apiService = builder.AddProject<Projects.AspireDemo1_ApiService>("apiservice")
    .WithReference(database)
    .WithHttpHealthCheck("/health");

This block of code defines the ApiService project as part of our Aspire application and defines that it will receive the configuration information (i.e. the connection string) regarding the database that we have created. Make sure that the reference is to the database instance, and not the server instance.

Client Setup

Now that we’ve set up our AppHost project, we can move on to setting up our API project to consume and use that information about our database. The first thing we need to do is add the second of our Aspire NuGet packages for SQL Server. For this, you can either use dotnet add or the NuGet Package Manager in Visual Studio. At present, the Aspire CLI does not support adding client Aspire integration packages. Hopefully, it will get added soon.

For this demo we’ll use the EntityFramework Core version, so we’ll add the following package in our Api project. For some of the database integrations there are two different versions of the client package: One version if you’re using Entity Framework Core, and a different one if you’re using some other framework.

dotnet add Aspire.Microsoft.EntityFrameworkCore.SqlServer

Each of the Aspire client packages is essentially just a wrapper around the regular packages that adds the functionality needed to enable Aspire integration. So, the Aspire.Microsoft.EntityFrameworkCore.SqlServer package is just an Aspire wrapper for Microsoft.EntityFrameworkCore.SqlServer.

Once we have added our package, the next step is to set up our DbContext reference in the Program.cs file. That’s as simple as adding one single line of code:

builder.AddSqlServerDbContext<AppDbContext>("appdb");

The key here is the name inside the quotes. We use the same name that we defined for our database (not the SQL Server instance) in our AppHost.cs file. In this case we called it "appdb". When Aspire is launching the application locally, it will recognize that it needs to replace the information in quotes with the connectionString to the instance of SQL Server and its database inside of our local Docker Desktop image. As a developer, that’s all you need to do.

When the application gets deployed to a server, you just make sure that there is a connectionString defined in the server config named "appdb" that has the related server instance. You would set that up the same as you do any application deployment, whether you do that in appSettings.json or server config or do a string replacement or however is up to you and your DevOps team. But nothing in the code really needs to change.

After that, everything is the same as what you would do otherwise for interacting with your database in your application. In this example, you would proceed to use Entity Framework Core just as you normally would. Nothing else aside from that initial DbContext setup changes.

Conclusion

Setting up data sources in Aspire is an easy 2-step process. You add your configuration in your AppHost, then reference it in the client project(s). That’s it. No need to replicate your configuration in multiple places. It stays in one spot and Aspire takes care of the rest. And the process is pretty much the same no matter the datasource. Currently, the list of supported database sources includes: SQL Server, PostgreSQL, MongoDB, Raven, CosmosDB, Oracle, SQLite, SurrealDB, Qdrant, KurrentDB, Meilisearch, Milvus, and Elasticsearch. No matter what your data source, Aspire is there to make your dev life easier.