MSBuild 反模式 AP-07分析器与构建工具包必须使用PrivateAssetsall——阻止私有依赖泄漏给库消费者【免费下载链接】skillsRepository for skills to assist AI coding agents with .NET and C#项目地址: https://gitcode.com/GitHub_Trending/skills17/skills本文是dotnet-msbuild插件msbuild-antipatterns技能中AP-07反模式缺失PrivateAssetsall的专项详解。核心场景你在编写/审查类库Library的.csproj时如果StyleCop.Analyzers、Microsoft.SourceLink.GitHub、MinVer这类仅供构建期使用的包没有标记为私有它们就会作为传递依赖transitive dependency泄漏给你的下游消费者。读完本文你将掌握PrivateAssets的取值与语义、哪些包几乎必须私有化、BAD→GOOD 的完整改写示范以及如何在仓库的真实工程与评测用例中识别和验证这一问题。问题本质构建期依赖与运行时依赖的边界Roslyn 分析器、源代码生成器、SourceLink、版本号工具等包有一个共同特点它们只在编译/打包阶段起作用运行时与下游消费者完全无关。StyleCop.Analyzers在编译时对代码做静态分析生成的 DLL 不需要随你的库分发Microsoft.SourceLink.GitHub只在打包时把仓库提交哈希嵌入 PDB/程序集属性消费者用不到MinVer只在构建时根据 Git 标签计算版本号不产生任何运行时依赖。NuGet 的默认行为却把PackageReference视为可传递当你把库打包成.nupkg发布后PackageReference会写入依赖清单nuspec 的dependencies节点消费者还原时会被自动拉下来。于是下游用户莫名其妙地收到了你内部才需要的分析器或构建工具——这正是 AP-07 定义的泄漏问题。在 msbuild-antipatterns/SKILL.md 中该反模式被记录为AP-07: MissingPrivateAssetsallon Analyzer/Tool PackagesSmellPackageReference IncludeStyleCop.Analyzers Version... /withoutPrivateAssetsall。Why its badWithoutPrivateAssetsall, analyzer and build-tool packages flow as transitive dependencies to consumers of your library. Consumers get unwanted analyzers or build-time tools they didnt ask for.并在 references/additional-antipatterns.md 的快速检查清单中标记为 Leaks to consumers泄漏给消费者级别的问题。PrivateAssets属性语法、取值与作用范围PrivateAssets是PackageReference项Item上的一个元数据属性控制该包中的哪些资产assets不会被传递给下游消费者。它最常见的取值如下取值语义all该包的所有资产都不外传分析器、编译时引用、build 脚本等全部私有化compile不把编译资产compile/与lib/下的引用传递给消费者runtime不把运行时资产runtime/下的 DLL传递给消费者contentfiles不把contentFiles/资产传递给消费者build不把build/、buildTransitive/下的.props/.targets传递给消费者analyzers不把analyzers/目录下的分析器 DLL 传递给消费者native不把native/资产传递给消费者none默认所有资产都按默认规则传递实践中分析器与构建工具几乎总是直接用all因为这类包的所有内容对消费者都是无用的。本文的主角是PrivateAssetsall它与IncludeAssets控制包中哪些资产进入当前项目正好形成互补IncludeAssets管自己用多少PrivateAssets管外传多少。注意PrivateAssets是元数据属性写在PackageReference元素上不是全局的 MSBuild 属性Property。它不会影响当前项目对该包的使用——分析器依然会在你自己的项目上生效——只是切断向下的传递链条。BAD → GOOD最小改动示范原文档 references/private-assets.md 给出的示范如下!-- BAD: Flows to consumers -- PackageReference IncludeStyleCop.Analyzers Version1.2.0-beta.556 / PackageReference IncludeMicrosoft.SourceLink.GitHub Version8.0.0 / PackageReference IncludeMinVer Version5.0.0 / !-- GOOD: Stays private -- PackageReference IncludeStyleCop.Analyzers Version1.2.0-beta.556 PrivateAssetsall / PackageReference IncludeMicrosoft.SourceLink.GitHub Version8.0.0 PrivateAssetsall / PackageReference IncludeMinVer Version5.0.0 PrivateAssetsall /改写只增加了一个属性改动量极小收益却很大发布后的.nupkg依赖清单里不再出现这三个包下游消费者不会被迫安装你的分析器或版本工具。这也是该反模式修复成本最低的原因——值得在每次 code review 时顺手检查。哪些包几乎必须私有化原文档给出了完整清单private-assets.mdRoslyn 分析器*.Analyzers、*.CodeFixes如StyleCop.Analyzers、Microsoft.CodeAnalysis.NetAnalyzers、Microsoft.CodeAnalysis.BannedApiAnalyzers源代码生成器Source generators编译期生成代码运行时不参与SourceLink 系列Microsoft.SourceLink.*如Microsoft.SourceLink.GitHub、Microsoft.SourceLink.AzureRepos.Git版本号工具MinVer、Nerdbank.GitVersioning纯构建期工具Microsoft.DotNet.ApiCompatAPI 兼容性校验等这些包的共同模式是名字带Analyzers/SourceLink/版本工具特征、产物只出现在构建产物目录或打包流程中。命名上它们常以*.Analyzers、*.CodeFixes、Microsoft.SourceLink.*、MinVer、Nerdbank.GitVersioning等形态出现审查时可以作为快速扫描的关键词。仓库中的真实验证测试夹具如何制造这个反模式本仓库专门为msbuild-antipatterns技能准备了评测夹具fixture其中就包含 AP-07 的实例用于验证 Agent 能否识别该问题。在 tests/dotnet-msbuild/msbuild-antipatterns/Directory.Build.props 中故意写入了一个带 BUG 的PackageReference!-- BUG: Analyzer package without PrivateAssets — leaks analyzer to downstream consumers. Should use PrivateAssetsall/PrivateAssets and IncludeAssets... analyzers/IncludeAssets. -- ItemGroup PackageReference IncludeStyleCop.Analyzers Version1.2.0-beta.556 / /ItemGroup注意这里的写法有两点其一缺失PrivateAssets其二注释提示理想修复除了PrivateAssetsall还常配合IncludeAssets例如IncludeAssetsruntime; build; native; contentfiles; analyzers; buildtransitive把 compile 资产也排除进一步减少对自身项目的侵入。注释中Should usePrivateAssetsall/PrivateAssetsandIncludeAssets... analyzers/IncludeAssets直接点出了双属性配合的正确姿势。对应的评测用例在 tests/dotnet-msbuild/msbuild-antipatterns/eval.yaml 中把识别出分析器PackageReference缺少PrivateAssets列为明确的能力考核点Identified analyzer PackageReference missing PrivateAssets, unquoted MSBuild condition, mixed Include/Update in same ItemGroup, or Exec instead of Message task也就是说看到StyleCop.Analyzers之类的包没写PrivateAssets就报出 AP-07是本仓库对 Agent 的硬性评测标准。审查.csproj/Directory.Build.props时这一条属于必查项。相邻技能与交叉验证不止一处强调同一规则PrivateAssetsall在本仓库dotnet-msbuild插件中并非孤立规则多处技能文件都把它作为独立的最佳实践章节plugins/dotnet-msbuild/skills/item-management/SKILL.md 设有专门的PrivateAssets on Tool/Analyzer Packages小节示范Microsoft.CodeAnalysis.NetAnalyzers与StyleCop.Analyzers的写法plugins/dotnet-msbuild/agents/msbuild-code-review.agent.md 在代码审查检查清单中列出 MissingPrivateAssetsallon analyzer packages?作为审查 Agent 的默认提问项msbuild-antipatterns/SKILL.md 本身AP-07则把详细 BAD/GOOD 示例与完整清单指向本参考文档。三处形成技能目录 → 参考文档 → 审查 Agent 清单的闭环说明这是一个团队级约定而不是个别人的偏好。审查任何类库项目时都应当把它当作默认检查项。实操审查与修复清单结合原文档与仓库证据给出可直接执行的审查流程扫描范围打开每个会被打包发布的.csproj以及Directory.Build.props如果分析器放在全局 props 中如评测夹具所示关键词扫描查找*.Analyzers、*.CodeFixes、Microsoft.SourceLink.*、MinVer、Nerdbank.GitVersioning、Microsoft.DotNet.ApiCompat等命名的PackageReference逐项检查确认每一项都带有PrivateAssetsall修复为缺失项补上属性或与IncludeAssets配合使用!-- 修复后 -- ItemGroup PackageReference IncludeStyleCop.Analyzers Version1.2.0-beta.556 PrivateAssetsall / PackageReference IncludeMicrosoft.SourceLink.GitHub Version8.0.0 PrivateAssetsall / PackageReference IncludeMinVer Version5.0.0 PrivateAssetsall / /ItemGroup验证dotnet pack后检查生成的.nupkg内的.nuspec文件确认dependencies节点中不再出现这些包或对下游测试项目dotnet restore后确认分析器没有被动安装。常见误区与边界误区一不发布库就不需要只有纯可执行程序如控制台/Web 应用不打包时泄漏影响有限只要是类库且会dotnet pack发布给他人使用就必须私有化。判断依据是这个项目是否会被其他项目作为包引用。误区二加了PrivateAssets后分析器在自己项目上就不生效了不会。PrivateAssets只切断向下的传递当前项目的构建期功能分析、版本号计算、SourceLink 嵌入完全不受影响。误区三IncludeAssets与PrivateAssets二选一两者职责不同——IncludeAssets决定当前项目消费包中哪些资产PrivateAssets决定哪些资产不外传。分析器包常二者并用如评测夹具注释所示以最小化对构建和下游的影响。总结PrivateAssetsall是分析器与构建工具包在类库项目中的强制约定而非可选优化缺失它会把构建期噪音泄漏给每一个下游消费者。本仓库将这一规则固化为msbuild-antipatterns的 AP-07 反模式、item-management的独立最佳实践章节、msbuild-code-reviewAgent 的默认检查项并在 tests/dotnet-msbuild/msbuild-antipatterns 的评测夹具中制造真实反例来考核 Agent 的识别能力。编写或审查类库工程文件时把分析器/工具包是否带了PrivateAssetsall列为第一轮扫描项即可用一行代码的改动避免整条依赖链上的污染。【免费下载链接】skillsRepository for skills to assist AI coding agents with .NET and C#项目地址: https://gitcode.com/GitHub_Trending/skills17/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考