在 Entity Framework Core 中应用 .NET Aspire 迁移

项目
12/15/2024

由于 .NET.NET Aspire 项目使用容器化体系结构，因此数据库是临时的，可以随时重新创建。 Entity Framework Core（EF Core）使用一种称为迁移的功能来创建和更新数据库架构。由于在应用启动时重新创建数据库，每次启动应用时都需要应用迁移来初始化数据库架构。这可以通过在应用中注册一个在启动期间执行迁移的迁移服务的项目来实现。

本教程介绍如何配置 .NET Aspire 项目，以在应用启动期间运行 EF Core 迁移。

先决条件

若要使用 .NET.NET Aspire，需要在本地安装以下各项：

.NET 8.0 或 .NET 9.0
符合 OCI 的容器运行时，例如：
- Docker 桌面或 Podman。有关详细信息，请参阅容器运行时。
集成开发人员环境（IDE）或代码编辑器，例如：
- Visual Studio 2022 17.9 或更高版本（可选）
- Visual Studio Code （可选）
  - C# Dev Kit：扩展（可选）
- 使用插件 JetBrains Rider （可选）

有关详细信息，请参阅 .NET.NET Aspire 设置和工具，以及 .NET.NET Aspire SDK。

获取入门应用程序

本教程使用了一个示例应用程序，来演示如何在 EF Core中应用 .NET Aspire 迁移。使用从克隆示例应用或使用以下命令：

git clone https://github.com/MicrosoftDocs/aspire-docs-samples/

示例应用位于 SupportTicketApi 文件夹中。在 Visual Studio 或 VS Code 中打开解决方案，花点时间查看示例应用程序，并确保它能正常运行，然后再继续。示例应用是一个基本的支持票证 API，其中包含以下项目：

SupportTicketApi.Api：托管 API 的 ASP.NET Core 项目。
SupportTicketApi.Data：包含 EF Core 上下文和模型。
SupportTicketApi.AppHost：包含 .NET.NET Aspire 应用主机和配置。
SupportTicketApi.ServiceDefaults：包含默认服务配置。

运行应用以确保它按预期工作。在 .NET.NET Aspire 仪表板中，选择 https Swagger 终结点，并通过展开操作并选择“试用来测试 API GET /api/SupportTickets 终结点。选择执行发送请求并查看响应：

[
  {
    "id": 1,
    "title": "Initial Ticket",
    "description": "Test ticket, please ignore."
  }
]

创建迁移

首先创建一些要应用的迁移。

在中打开终端（+`Visual Studio）。
将 SupportTicketApiSupportTicketApi.Api 设置为当前目录。
使用 dotnet ef 命令行工具创建新的迁移来捕获数据库架构的初始状态：
```
dotnet ef migrations add InitialCreate --project ..\SupportTicketApi.Data\SupportTicketApi.Data.csproj
```
继续命令：
- 在 EF Core 目录中运行迁移命令行工具。 dotnet ef 在这里运行，因为这是 API 服务使用 DB 上下文的地方。
- 创建名为 InitialCreate的迁移。
- 在 SupportTicketApi.Data 项目中的 Migrations 文件夹中创建迁移。

修改模型，使其包含新属性。打开 SupportTicketApi.DataModelsSupportTicket.cs 并将新属性添加到 SupportTicket 类：

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

创建另一个新迁移以记录模型更改。

dotnet ef migrations add AddCompleted --project ..\SupportTicketApi.Data\SupportTicketApi.Data.csproj

现在，你有一些迁移需要应用。接下来，你将创建一个在应用程序启动时应用这些迁移的迁移服务。

创建迁移服务

若要在启动时运行迁移，需要创建一个应用迁移的服务。

向解决方案添加新 Worker Service 项目。如果使用 Visual Studio，请在解决方案资源管理器中右键单击解决方案，然后选择 Add>New Project。选择 Worker Service 并将项目命名为 SupportTicketApi.MigrationService。如果使用命令行，请使用解决方案目录中的以下命令：
```
dotnet new worker -n SupportTicketApi.MigrationService
dotnet sln add SupportTicketApi.MigrationService
```

使用 SupportTicketApi.Data 或命令行向 SupportTicketApi.ServiceDefaults 项目添加 SupportTicketApi.MigrationService 和 Visual Studio 项目引用：

dotnet add SupportTicketApi.MigrationService reference SupportTicketApi.Data
dotnet add SupportTicketApi.MigrationService reference SupportTicketApi.ServiceDefaults

添加 SupportTicketApi.MigrationService NuGet 包引用添加到 Visual Studio 项目：
```
dotnet add package Aspire.Microsoft.EntityFrameworkCore.SqlServer
```

将突出显示的行添加到 Program.cs 项目中的 SupportTicketApi.MigrationService 文件中：

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

在前面的代码中：

AddServiceDefaults 扩展方法添加了服务默认功能。
AddOpenTelemetry 扩展方法可配置 OpenTelemetry 功能。
AddSqlServerDbContext 扩展方法将 TicketContext 服务添加到服务集合。此服务用于进行迁移操作并初始化数据库。

将 Worker.cs 项目中 SupportTicketApi.MigrationService 文件的内容替换为以下代码：

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

在前面的代码中：

工作人员启动时调用 ExecuteAsync 方法。它又执行以下步骤：
1. 从服务提供商获取对 TicketContext 服务的引用。
2. 调用 EnsureDatabaseAsync 创建数据库（如果不存在）。
3. 调用功能 RunMigrationAsync 来应用所有待处理的迁移。
4. 调用 SeedDataAsync 来为数据库初始化初始数据。
5. 使用 StopApplication停止工人。
EnsureDatabaseAsync、RunMigrationAsync和 SeedDataAsync 方法都使用执行策略封装各自的数据库操作，以处理与数据库交互时可能发生的暂时性错误。若要详细了解执行策略，请参阅连接恢复。

将迁移服务添加到编排器

迁移服务已创建，但需要将其添加到 .NET.NET Aspire 应用主机，以便在应用启动时运行。

在 SupportTicketApi.AppHost 项目中，打开 Program.cs 文件。
将以下突出显示的代码添加到 ConfigureServices 方法：
```
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();
```
这会将 SupportTicketApi.MigrationService 项目登记为 .NET.NET Aspire 应用主机中的服务。

重要

如果使用 Visual Studio，并且你在创建 Enlist in Aspire orchestration 项目时选择了 Worker Service 选项，则会自动使用服务名称 supportticketapi-migrationservice添加类似的代码。将该代码替换为前面的代码。

删除现有播种代码

由于迁移服务为数据库设定种子，因此应从 API 项目中删除现有的数据种子设定代码。

在 SupportTicketApi.Api 项目中，打开 Program.cs 文件。

删除突出显示的行。

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

测试迁移服务

配置迁移服务后，请运行应用来测试迁移。

运行应用并观察 SupportTicketApi 仪表板。
等待一段时间后，migrations 服务状态会显示 已完成。
请选择迁移服务中的 View 链接，以分析显示执行的 SQL 命令的日志。

获取代码

可以在上找到已完成的示例应用。

通过