FluentMigrator迁移执行问题排查：运行时与CLI差异分析

在使用FluentMigrator进行数据库迁移时，开发者可能会遇到一个典型问题：通过dotnet-fm命令行工具可以成功执行迁移，但在应用程序运行时却抛出"MissingMigrationsException: No migrations found"异常。本文将深入分析这一问题的成因及解决方案。

问题现象

当开发者在.NET 8项目中集成FluentMigrator 5进行PostgreSQL数据库迁移时，可能会观察到以下现象：

1. 项目结构通常分为API项目(主程序)和Database项目(包含迁移的类库)
2. 迁移类已正确标注特性并继承自Migration基类
3. 通过dotnet-fm命令行工具执行迁移成功
4. 但在应用程序运行时抛出找不到迁移的异常

根本原因

这个问题的核心在于FluentMigrator运行时扫描程序集的配置不正确。FluentMigrator需要明确知道从哪个程序集加载迁移类，而默认情况下它只会扫描主程序集。

当迁移类位于单独的程序集(类库项目)中时，必须显式指定要扫描的程序集，否则运行时无法发现这些迁移类。

解决方案

正确的配置方式是在构建迁移服务时，明确指定包含迁移类的程序集：

var serviceProvider = new ServiceCollection()
    .AddFluentMigratorCore()
    .ConfigureRunner(rb => rb
        .AddPostgres()
        .WithGlobalConnectionString(connectionString)
        .ScanIn(typeof(Database).Assembly) // 关键配置
        .WithMigrationsIn(typeof(Database).Assembly))
    .BuildServiceProvider(false);

其中Database是迁移类所在程序集中的任意类型，通过它的Assembly属性可以获取到包含迁移的程序集引用。

深入理解

1. 程序集扫描机制：FluentMigrator使用反射来发现迁移类，需要知道从哪些程序集加载这些类

2. 命令行工具差异：dotnet-fm工具通常会自动扫描所有引用的程序集，而运行时需要显式配置

3. 最佳实践：

   • 将迁移类组织在单独的程序集中
   • 在配置中明确指定该程序集
   • 可以使用程序集中的任何公共类型作为扫描入口

4. 错误排查步骤：

   • 确认迁移类是否位于正确程序集
   • 检查程序集是否被主项目引用
   • 验证ScanIn配置是否正确指向该程序集

通过正确配置程序集扫描路径，可以确保FluentMigrator在运行时和命令行工具中都能一致地发现并执行迁移。