VS2022+.NET7构建时自动生成Swagger文档失败求助

使用VS2022 + .NET7开发WebAPI，配置了Swagger并添加了Build后执行dotnet swagger tofile的MSBuild Target，试图自动生成OpenAPI规范文件，但构建时抛出**"ConnectionString属性未初始化"**异常，导致文件生成失败。

错误原因 #

dotnet swagger tofile命令的工作机制是启动整个Web应用程序，通过加载应用的服务配置来生成Swagger文档。如果你的应用启动逻辑（比如Program.cs中调用了EF Core的MigrateAsync、数据库初始化等操作）依赖数据库连接字符串，而构建时输出目录下的配置文件未正确加载，或者连接字符串未配置，就会触发数据库连接错误。

从错误日志可以看到，异常起源于Program.cs第83行的MigrateAsync调用，说明应用启动时尝试执行数据库迁移，但此时没有正确读取到连接字符串。

解决思路与方案 #

方案1：在启动逻辑中跳过数据库相关操作（最直接） #

通过环境变量或条件判断，识别当前是否是Swagger CLI启动场景，跳过数据库迁移、初始化等依赖配置的操作。

1. 修改Program.cs中的启动代码，添加判断逻辑：

var builder = WebApplication.CreateBuilder(args);

// ... 其他服务配置代码 ...

var app = builder.Build();

// 检查是否为Swagger CLI生成文档的场景，跳过数据库操作
var isSwaggerGeneration = Environment.GetEnvironmentVariable("SWAGGER_GENERATION") == "true";
if (!isSwaggerGeneration)
{
    // 原来的数据库迁移或初始化代码
    await app.Services.GetRequiredService<ApplicationDbContext>().Database.MigrateAsync();
}

// ... Swagger和其他中间件配置 ...

app.Run();

2. 修改项目文件中的Target，添加环境变量：

<Target Name="OpenAPI" AfterTargets="Build" Condition="$(Configuration)=='Debug'">
    <Exec Command="echo Generating OpenAPI." />
    <Exec Command="set SWAGGER_GENERATION=true &amp;&amp; dotnet swagger tofile --output ./_open-api.json $(OutputPath)$(AssemblyName).dll public" />
</Target>

方案2：确保配置文件复制到输出目录 #

如果连接字符串配置在appsettings.json中，需要确保文件被复制到构建输出目录，这样dotnet swagger命令才能读取到配置。

在项目文件中添加以下配置：

<ItemGroup>
  <None Update="appsettings.json">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
  </None>
  <None Update="appsettings.Development.json">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
  </None>
</ItemGroup>

方案3：使用Swashbuckle的MSBuild任务替代CLI命令 #

安装Swashbuckle.AspNetCore.Cli NuGet包，使用MSBuild任务直接生成Swagger文档，无需启动整个应用。

1. 安装包：

dotnet add package Swashbuckle.AspNetCore.Cli

2. 在项目文件中添加Target：

<Target Name="GenerateSwagger" AfterTargets="Build" Condition="$(Configuration)=='Debug'">
    <SwaggerGenerator
        Assembly="$(AssemblyName)"
        OutputPath="./_open-api.json"
        DocumentName="public" />
</Target>

方案4：分离Swagger生成逻辑（进阶） #

如果应用启动逻辑复杂，可单独编写一个工具类或项目，通过反射读取控制器和API元数据，直接生成Swagger文档，完全避开应用启动流程。这种方式适合大型项目，避免依赖应用的服务配置。

内容的提问来源于stack exchange，提问作者Wasyster