如何让.NET 8项目引用Windows专属库时触发构建失败？

一、通过MSBuild配置直接阻止特定Windows包 #

在项目的.csproj文件中添加自定义构建目标，在编译前检查是否引用了Windows专属库，一旦检测到就终止构建并抛出明确错误。

比如针对System.Drawing.Common这类典型Windows专属库，可以添加以下配置：

<Target Name="BlockWindowsOnlyPackages" BeforeTargets="Build">
  <!-- 定义需要拦截的Windows专属包列表 -->
  <ItemGroup>
    <WindowsOnlyPackage Include="System.Drawing.Common" />
    <WindowsOnlyPackage Include="Microsoft.Win32.Registry" />
    <!-- 可根据需求继续添加其他Windows专属包 -->
  </ItemGroup>

  <!-- 当目标平台为非Windows时，检查是否引用了上述包 -->
  <Error Text="检测到Windows专属库：%(WindowsOnlyPackage.Identity)，Linux环境无法运行，请移除该引用"
         Condition="'$(RuntimeIdentifier)' != '' AND !$(RuntimeIdentifier.StartsWith('win')) AND '@(PackageReference->AnyHaveMetadataValue('Id', '%(WindowsOnlyPackage.Identity)'))' == 'True'" />
</Target>

配置后，只要指定Linux相关的RuntimeIdentifier（比如linux-x64）进行构建，一旦项目引用了列表中的包，构建会直接失败并提示错误。

二、启用.NET平台兼容性分析器（推荐） #

.NET 5及以上版本自带平台兼容性分析器，可以在编译阶段检测代码中调用的平台专属API（包括第三方库中的API），将这类问题从运行时提前到构建阶段暴露。

在.csproj中启用分析器并将警告转为错误：

<PropertyGroup>
  <!-- 启用.NET内置分析器 -->
  <EnableNETAnalyzers>true</EnableNETAnalyzers>
  <!-- 启用所有默认规则 -->
  <AnalysisMode>AllEnabledByDefault</AnalysisMode>
  <!-- 将平台兼容性相关警告视为错误，强制构建失败 -->
  <PlatformCompatibilityAnalyzerTreatWarningsAsErrors>true</PlatformCompatibilityAnalyzerTreatWarningsAsErrors>
</PropertyGroup>

这个方案不仅能检测System.Drawing.Common这类库，还能扫描代码中直接调用的Windows专属API（比如System.Windows.Forms相关方法），覆盖范围更广。

三、免费扫描工具与针对性配置 #

1. dotnet analyze命令：配合上述分析器配置，直接在终端执行dotnet analyze，可扫描整个解决方案中的平台兼容性问题，输出详细的错误/警告列表。
2. System.Drawing.Common专属拦截：针对这个库，.NET 8中可以添加以下配置，直接在编译阶段阻止非Windows环境下的引用：

<PropertyGroup>
  <!-- 禁止在非Windows环境下使用System.Drawing.Common -->
  <SystemDrawingEnableUnixSupport>false</SystemDrawingEnableUnixSupport>
</PropertyGroup>

开启后在Linux环境构建时，只要引用了System.Drawing.Common就会直接报错。

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