Windows10下Dotnet CLI构建webapi项目报错MSB3021问题求助

原因分析 #

MSB3021错误的本质是构建过程中无法覆盖输出目录下的可执行文件，核心诱因是目标文件被进程锁定。结合给出的复现规律，该问题由dotnet run/dotnet watch run执行后进程未正常退出，或输出文件被第三方工具锁定导致，通过资源监视器未找到对应句柄，属于隐藏进程/第三方工具的隐性锁定场景。

可执行的解决方案 #

1. 优先排查残留进程 #

停止程序时不要直接关闭运行命令的终端窗口，必须在终端按Ctrl+C触发正常退出逻辑，避免dotnet子进程后台残留。
如果已经出现构建报错，直接打开任务管理器，结束所有名称为dotnet.exe的进程，再重新执行dotnet build验证是否恢复正常。

2. 排查第三方工具锁定 #

检查设备上是否运行企业杀毒软件、EDR终端管控工具、文件同步工具，这类工具扫描输出目录时会对文件加锁，且锁定状态不会展示在资源监视器的普通句柄列表中，可以临时将项目输出目录加入这类工具的扫描白名单后测试。

3. 调整项目构建配置规避锁定 #

在项目的.csproj文件中添加如下配置，让不同配置的构建输出到独立目录，避免覆盖被锁定的旧文件：

<PropertyGroup>
  <AppendTargetFrameworkToOutputPath>true</AppendTargetFrameworkToOutputPath>
  <AppendRuntimeIdentifierToOutputPath>true</AppendRuntimeIdentifierToOutputPath>
  <IntermediateOutputPath>obj\$(Configuration)\$(TargetFramework)\</IntermediateOutputPath>
</PropertyGroup>

临时构建时也可以添加--no-incremental参数执行全量重建，命令如下：
dotnet build --no-incremental

4. 规避.NET 5已知BUG #

你使用的.NET 5版本已经终止支持，5.0.401版本的dotnet watch run存在已知的进程残留缺陷，运行时可以添加--no-hot-reload参数关闭热重载功能，降低进程残留概率：
dotnet watch run --no-hot-reload

内容的提问来源于stack exchange，提问作者Realm Of Code