Events
Mar 17, 11 PM - Mar 21, 11 PM
Join the meetup series to build scalable AI solutions based on real-world use cases with fellow developers and experts.
Register nowThis browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Since .NET Aspire projects use a containerized architecture, databases are ephemeral and can be recreated at any time. Entity Framework Core (EF Core) uses a feature called migrations to create and update database schemas. Since databases are recreated when the app starts, you need to apply migrations to initialize the database schema each time your app starts. This is accomplished by registering a migration service project in your app that runs migrations during startup.
In this tutorial, you learn how to configure .NET Aspire projects to run EF Core migrations during app startup.
To work with .NET Aspire, you need the following installed locally:
For more information, see .NET Aspire setup and tooling, and .NET Aspire SDK.
This tutorial uses a sample app that demonstrates how to apply EF Core migrations in .NET Aspire. Use Visual Studio to clone the sample app from GitHub or use the following command:
git clone https://github.com/MicrosoftDocs/aspire-docs-samples/
The sample app is in the SupportTicketApi folder. Open the solution in Visual Studio or VS Code and take a moment to review the sample app and make sure it runs before proceeding. The sample app is a rudimentary support ticket API, and it contains the following projects:
Run the app to ensure it works as expected. From the .NET Aspire dashboard, select the https Swagger endpoint and test the API's GET /api/SupportTickets endpoint by expanding the operation and selecting Try it out. Select Execute to send the request and view the response:
[
{
"id": 1,
"title": "Initial Ticket",
"description": "Test ticket, please ignore."
}
]
Start by creating some migrations to apply.
Open a terminal (Ctrl+` in Visual Studio).
Set SupportTicketApiSupportTicketApi.Api as the current directory.
Use the dotnet ef
command-line tool to create a new migration to capture the initial state of the database schema:
dotnet ef migrations add InitialCreate --project ..\SupportTicketApi.Data\SupportTicketApi.Data.csproj
The proceeding command:
dotnet ef
is run in this location because the API service is where the DB context is used.Modify the model so that it includes a new property. Open SupportTicketApi.DataModelsSupportTicket.cs and add a new property to the SupportTicket
class:
public sealed class SupportTicket
{
public int Id { get; set; }
[Required]
public string Title { get; set; } = string.Empty;
[Required]
public string Description { get; set; } = string.Empty;
public bool Completed { get; set; }
}
Create another new migration to capture the changes to the model:
dotnet ef migrations add AddCompleted --project ..\SupportTicketApi.Data\SupportTicketApi.Data.csproj
Now you've got some migrations to apply. Next, you'll create a migration service that applies these migrations during app startup.
To run the migrations at startup, you need to create a service that applies the migrations.
Add a new Worker Service project to the solution. If using Visual Studio, right-click the solution in Solution Explorer and select Add > New Project. Select Worker Service and name the project SupportTicketApi.MigrationService. If using the command line, use the following commands from the solution directory:
dotnet new worker -n SupportTicketApi.MigrationService
dotnet sln add SupportTicketApi.MigrationService
Add the SupportTicketApi.Data and SupportTicketApi.ServiceDefaults project references to the SupportTicketApi.MigrationService project using Visual Studio or the command line:
dotnet add SupportTicketApi.MigrationService reference SupportTicketApi.Data
dotnet add SupportTicketApi.MigrationService reference SupportTicketApi.ServiceDefaults
Add the 📦 Aspire.Microsoft.EntityFrameworkCore.SqlServer NuGet package reference to the SupportTicketApi.MigrationService project using Visual Studio or the command line:
dotnet add package Aspire.Microsoft.EntityFrameworkCore.SqlServer
Add the highlighted lines to the Program.cs file in the SupportTicketApi.MigrationService project:
using SupportTicketApi.Data.Contexts;
using SupportTicketApi.MigrationService;
var builder = Host.CreateApplicationBuilder(args);
builder.AddServiceDefaults();
builder.Services.AddHostedService<Worker>();
builder.Services.AddOpenTelemetry()
.WithTracing(tracing => tracing.AddSource(Worker.ActivitySourceName));
builder.AddSqlServerDbContext<TicketContext>("sqldata");
var host = builder.Build();
host.Run();
In the preceding code:
AddServiceDefaults
extension method adds service defaults functionality.AddOpenTelemetry
extension method configures OpenTelemetry functionality.AddSqlServerDbContext
extension method adds the TicketContext
service to the service collection. This service is used to run migrations and seed the database.Replace the contents of the Worker.cs file in the SupportTicketApi.MigrationService project with the following code:
using System.Diagnostics;
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Infrastructure;
using Microsoft.EntityFrameworkCore.Storage;
using OpenTelemetry.Trace;
using SupportTicketApi.Data.Contexts;
using SupportTicketApi.Data.Models;
namespace SupportTicketApi.MigrationService;
public class Worker(
IServiceProvider serviceProvider,
IHostApplicationLifetime hostApplicationLifetime) : BackgroundService
{
public const string ActivitySourceName = "Migrations";
private static readonly ActivitySource s_activitySource = new(ActivitySourceName);
protected override async Task ExecuteAsync(CancellationToken cancellationToken)
{
using var activity = s_activitySource.StartActivity("Migrating database", ActivityKind.Client);
try
{
using var scope = serviceProvider.CreateScope();
var dbContext = scope.ServiceProvider.GetRequiredService<TicketContext>();
await EnsureDatabaseAsync(dbContext, cancellationToken);
await RunMigrationAsync(dbContext, cancellationToken);
await SeedDataAsync(dbContext, cancellationToken);
}
catch (Exception ex)
{
activity?.RecordException(ex);
throw;
}
hostApplicationLifetime.StopApplication();
}
private static async Task EnsureDatabaseAsync(TicketContext dbContext, CancellationToken cancellationToken)
{
var dbCreator = dbContext.GetService<IRelationalDatabaseCreator>();
var strategy = dbContext.Database.CreateExecutionStrategy();
await strategy.ExecuteAsync(async () =>
{
// Create the database if it does not exist.
// Do this first so there is then a database to start a transaction against.
if (!await dbCreator.ExistsAsync(cancellationToken))
{
await dbCreator.CreateAsync(cancellationToken);
}
});
}
private static async Task RunMigrationAsync(TicketContext dbContext, CancellationToken cancellationToken)
{
var strategy = dbContext.Database.CreateExecutionStrategy();
await strategy.ExecuteAsync(async () =>
{
// Run migration in a transaction to avoid partial migration if it fails.
await using var transaction = await dbContext.Database.BeginTransactionAsync(cancellationToken);
await dbContext.Database.MigrateAsync(cancellationToken);
await transaction.CommitAsync(cancellationToken);
});
}
private static async Task SeedDataAsync(TicketContext dbContext, CancellationToken cancellationToken)
{
SupportTicket firstTicket = new()
{
Title = "Test Ticket",
Description = "Default ticket, please ignore!",
Completed = true
};
var strategy = dbContext.Database.CreateExecutionStrategy();
await strategy.ExecuteAsync(async () =>
{
// Seed the database
await using var transaction = await dbContext.Database.BeginTransactionAsync(cancellationToken);
await dbContext.Tickets.AddAsync(firstTicket, cancellationToken);
await dbContext.SaveChangesAsync(cancellationToken);
await transaction.CommitAsync(cancellationToken);
});
}
}
In the preceding code:
ExecuteAsync
method is called when the worker starts. It in turn performs the following steps:
TicketContext
service from the service provider.EnsureDatabaseAsync
to create the database if it doesn't exist.RunMigrationAsync
to apply any pending migrations.SeedDataAsync
to seed the database with initial data.StopApplication
.EnsureDatabaseAsync
, RunMigrationAsync
, and SeedDataAsync
methods all encapsulate their respective database operations using execution strategies to handle transient errors that may occur when interacting with the database. To learn more about execution strategies, see Connection Resiliency.The migration service is created, but it needs to be added to the .NET Aspire app host so that it runs when the app starts.
In the SupportTicketApi.AppHost project, open the Program.cs file.
Add the following highlighted code to the ConfigureServices
method:
var builder = DistributedApplication.CreateBuilder(args);
var sql = builder.AddSqlServer("sql")
.AddDatabase("sqldata");
builder.AddProject<Projects.SupportTicketApi_Api>("api")
.WithReference(sql);
builder.AddProject<Projects.SupportTicketApi_MigrationService>("migrations")
.WithReference(sql);
builder.Build().Run();
This enlists the SupportTicketApi.MigrationService project as a service in the .NET Aspire app host.
Important
If you are using Visual Studio, and you selected the Enlist in Aspire orchestration option when creating the Worker Service project, similar code is added automatically with the service name supportticketapi-migrationservice
. Replace that code with the preceding code.
Since the migration service seeds the database, you should remove the existing data seeding code from the API project.
In the SupportTicketApi.Api project, open the Program.cs file.
Delete the highlighted lines.
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI();
using (var scope = app.Services.CreateScope())
{
var context = scope.ServiceProvider.GetRequiredService<TicketContext>();
context.Database.EnsureCreated();
if(!context.Tickets.Any())
{
context.Tickets.Add(new SupportTicket { Title = "Initial Ticket", Description = "Test ticket, please ignore." });
context.SaveChanges();
}
}
}
Now that the migration service is configured, run the app to test the migrations.
Run the app and observe the SupportTicketApi dashboard.
After a short wait, the migrations
service state will display Finished.
Select the View link on the migration service to investigate the logs showing the SQL commands that were executed.
You can find the completed sample app on GitHub.
The Aspire Shop sample app uses this approach to apply migrations. See the AspireShop.CatalogDbManager
project for the migration service implementation.
.NET Aspire feedback
.NET Aspire is an open source project. Select a link to provide feedback:
Events
Mar 17, 11 PM - Mar 21, 11 PM
Join the meetup series to build scalable AI solutions based on real-world use cases with fellow developers and experts.
Register nowTraining
Module
Customize a .NET Aspire app to use existing Azure resources - Training
In this module, you'll learn how to move backing services for your Azure-hosted .NET Aspire app from containers into native Azure services.
Certification
Microsoft Certified: Azure for SAP Workloads Specialty - Certifications
Demonstrate planning, migration, and operation of an SAP solution on Microsoft Azure while you leverage Azure resources.