建工具包必須使用 `PrivateAssets=“all“`——阻止私有依賴泄漏給庫消費者)
MSBuild 反模式 AP-07分析器與構(gòu)建工具包必須使用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這類僅供構(gòu)建期使用的包沒有標記為私有它們就會作為傳遞依賴transitive dependency泄漏給你的下游消費者。讀完本文你將掌握PrivateAssets的取值與語義、哪些包幾乎必須私有化、BAD→GOOD 的完整改寫示范以及如何在倉庫的真實工程與評測用例中識別和驗證這一問題。問題本質(zhì)構(gòu)建期依賴與運行時依賴的邊界Roslyn 分析器、源代碼生成器、SourceLink、版本號工具等包有一個共同特點它們只在編譯/打包階段起作用運行時與下游消費者完全無關(guān)。StyleCop.Analyzers在編譯時對代碼做靜態(tài)分析生成的 DLL 不需要隨你的庫分發(fā)Microsoft.SourceLink.GitHub只在打包時把倉庫提交哈希嵌入 PDB/程序集屬性消費者用不到MinVer只在構(gòu)建時根據(jù) Git 標簽計算版本號不產(chǎn)生任何運行時依賴。NuGet 的默認行為卻把PackageReference視為可傳遞當你把庫打包成.nupkg發(fā)布后PackageReference會寫入依賴清單nuspec 的dependencies節(jié)點消費者還原時會被自動拉下來。于是下游用戶莫名其妙地收到了你內(nèi)部才需要的分析器或構(gòu)建工具——這正是 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上的一個元數(shù)據(jù)屬性控制該包中的哪些資產(chǎn)assets不會被傳遞給下游消費者。它最常見的取值如下取值語義all該包的所有資產(chǎn)都不外傳分析器、編譯時引用、build 腳本等全部私有化compile不把編譯資產(chǎn)compile/與lib/下的引用傳遞給消費者runtime不把運行時資產(chǎn)runtime/下的 DLL傳遞給消費者contentfiles不把contentFiles/資產(chǎn)傳遞給消費者build不把build/、buildTransitive/下的.props/.targets傳遞給消費者analyzers不把analyzers/目錄下的分析器 DLL 傳遞給消費者native不把native/資產(chǎn)傳遞給消費者none默認所有資產(chǎn)都按默認規(guī)則傳遞實踐中分析器與構(gòu)建工具幾乎總是直接用all因為這類包的所有內(nèi)容對消費者都是無用的。本文的主角是PrivateAssetsall它與IncludeAssets控制包中哪些資產(chǎn)進入當前項目正好形成互補IncludeAssets管自己用多少PrivateAssets管外傳多少。注意PrivateAssets是元數(shù)據(jù)屬性寫在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 /改寫只增加了一個屬性改動量極小收益卻很大發(fā)布后的.nupkg依賴清單里不再出現(xiàn)這三個包下游消費者不會被迫安裝你的分析器或版本工具。這也是該反模式修復成本最低的原因——值得在每次 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純構(gòu)建期工具Microsoft.DotNet.ApiCompatAPI 兼容性校驗等這些包的共同模式是名字帶Analyzers/SourceLink/版本工具特征、產(chǎn)物只出現(xiàn)在構(gòu)建產(chǎn)物目錄或打包流程中。命名上它們常以*.Analyzers、*.CodeFixes、Microsoft.SourceLink.*、MinVer、Nerdbank.GitVersioning等形態(tài)出現(xiàn)審查時可以作為快速掃描的關(guān)鍵詞。倉庫中的真實驗證測試夾具如何制造這個反模式本倉庫專門為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 資產(chǎn)也排除進一步減少對自身項目的侵入。注釋中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時這一條屬于必查項。相鄰技能與交叉驗證不止一處強調(diào)同一規(guī)則PrivateAssetsall在本倉庫dotnet-msbuild插件中并非孤立規(guī)則多處技能文件都把它作為獨立的最佳實踐章節(jié)plugins/dotnet-msbuild/skills/item-management/SKILL.md 設(shè)有專門的PrivateAssets on Tool/Analyzer Packages小節(jié)示范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 清單的閉環(huán)說明這是一個團隊級約定而不是個別人的偏好。審查任何類庫項目時都應當把它當作默認檢查項。實操審查與修復清單結(jié)合原文檔與倉庫證據(jù)給出可直接執(zhí)行的審查流程掃描范圍打開每個會被打包發(fā)布的.csproj以及Directory.Build.props如果分析器放在全局 props 中如評測夾具所示關(guān)鍵詞掃描查找*.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內(nèi)的.nuspec文件確認dependencies節(jié)點中不再出現(xiàn)這些包或?qū)ο掠螠y試項目dotnet restore后確認分析器沒有被動安裝。常見誤區(qū)與邊界誤區(qū)一不發(fā)布庫就不需要只有純可執(zhí)行程序如控制臺/Web 應用不打包時泄漏影響有限只要是類庫且會dotnet pack發(fā)布給他人使用就必須私有化。判斷依據(jù)是這個項目是否會被其他項目作為包引用。誤區(qū)二加了PrivateAssets后分析器在自己項目上就不生效了不會。PrivateAssets只切斷向下的傳遞當前項目的構(gòu)建期功能分析、版本號計算、SourceLink 嵌入完全不受影響。誤區(qū)三IncludeAssets與PrivateAssets二選一兩者職責不同——IncludeAssets決定當前項目消費包中哪些資產(chǎn)PrivateAssets決定哪些資產(chǎn)不外傳。分析器包常二者并用如評測夾具注釋所示以最小化對構(gòu)建和下游的影響?？偨Y(jié)PrivateAssetsall是分析器與構(gòu)建工具包在類庫項目中的強制約定而非可選優(yōu)化缺失它會把構(gòu)建期噪音泄漏給每一個下游消費者。本倉庫將這一規(guī)則固化為msbuild-antipatterns的 AP-07 反模式、item-management的獨立最佳實踐章節(jié)、msbuild-code-reviewAgent 的默認檢查項并在 tests/dotnet-msbuild/msbuild-antipatterns 的評測夾具中制造真實反例來考核 Agent 的識別能力。編寫或?qū)彶轭悗旃こ涛募r把分析器/工具包是否帶了PrivateAssetsall列為第一輪掃描項即可用一行代碼的改動避免整條依賴鏈上的污染。【免費下載鏈接】skillsRepository for skills to assist AI coding agents with .NET and C#項目地址: https://gitcode.com/GitHub_Trending/skills17/skills創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 MSBuild 反模式 AP-07：分析器與構(gòu)建工具包必須使用 `PrivateAssets=“all“`——阻止私有依賴泄漏給庫消費者
MSBuild 反模式 AP-07分析器與構(gòu)建工具包必須使用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這類僅供構(gòu)建期使用的包沒有標記為私有它們就會作為傳遞依賴transitive dependency泄漏給你的下游消費者。讀完本文你將掌握PrivateAssets的取值與語義、哪些包幾乎必須私有化、BAD→GOOD 的完整改寫示范以及如何在倉庫的真實工程與評測用例中識別和驗證這一問題。問題本質(zhì)構(gòu)建期依賴與運行時依賴的邊界Roslyn 分析器、源代碼生成器、SourceLink、版本號工具等包有一個共同特點它們只在編譯/打包階段起作用運行時與下游消費者完全無關(guān)。StyleCop.Analyzers在編譯時對代碼做靜態(tài)分析生成的 DLL 不需要隨你的庫分發(fā)Microsoft.SourceLink.GitHub只在打包時把倉庫提交哈希嵌入 PDB/程序集屬性消費者用不到MinVer只在構(gòu)建時根據(jù) Git 標簽計算版本號不產(chǎn)生任何運行時依賴。NuGet 的默認行為卻把PackageReference視為可傳遞當你把庫打包成.nupkg發(fā)布后PackageReference會寫入依賴清單nuspec 的dependencies節(jié)點消費者還原時會被自動拉下來。于是下游用戶莫名其妙地收到了你內(nèi)部才需要的分析器或構(gòu)建工具——這正是 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上的一個元數(shù)據(jù)屬性控制該包中的哪些資產(chǎn)assets不會被傳遞給下游消費者。它最常見的取值如下取值語義all該包的所有資產(chǎn)都不外傳分析器、編譯時引用、build 腳本等全部私有化compile不把編譯資產(chǎn)compile/與lib/下的引用傳遞給消費者runtime不把運行時資產(chǎn)runtime/下的 DLL傳遞給消費者contentfiles不把contentFiles/資產(chǎn)傳遞給消費者build不把build/、buildTransitive/下的.props/.targets傳遞給消費者analyzers不把analyzers/目錄下的分析器 DLL 傳遞給消費者native不把native/資產(chǎn)傳遞給消費者none默認所有資產(chǎn)都按默認規(guī)則傳遞實踐中分析器與構(gòu)建工具幾乎總是直接用all因為這類包的所有內(nèi)容對消費者都是無用的。本文的主角是PrivateAssetsall它與IncludeAssets控制包中哪些資產(chǎn)進入當前項目正好形成互補IncludeAssets管自己用多少PrivateAssets管外傳多少。注意PrivateAssets是元數(shù)據(jù)屬性寫在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 /改寫只增加了一個屬性改動量極小收益卻很大發(fā)布后的.nupkg依賴清單里不再出現(xiàn)這三個包下游消費者不會被迫安裝你的分析器或版本工具。這也是該反模式修復成本最低的原因——值得在每次 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純構(gòu)建期工具Microsoft.DotNet.ApiCompatAPI 兼容性校驗等這些包的共同模式是名字帶Analyzers/SourceLink/版本工具特征、產(chǎn)物只出現(xiàn)在構(gòu)建產(chǎn)物目錄或打包流程中。命名上它們常以*.Analyzers、*.CodeFixes、Microsoft.SourceLink.*、MinVer、Nerdbank.GitVersioning等形態(tài)出現(xiàn)審查時可以作為快速掃描的關(guān)鍵詞。倉庫中的真實驗證測試夾具如何制造這個反模式本倉庫專門為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 資產(chǎn)也排除進一步減少對自身項目的侵入。注釋中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時這一條屬于必查項。相鄰技能與交叉驗證不止一處強調(diào)同一規(guī)則PrivateAssetsall在本倉庫dotnet-msbuild插件中并非孤立規(guī)則多處技能文件都把它作為獨立的最佳實踐章節(jié)plugins/dotnet-msbuild/skills/item-management/SKILL.md 設(shè)有專門的PrivateAssets on Tool/Analyzer Packages小節(jié)示范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 清單的閉環(huán)說明這是一個團隊級約定而不是個別人的偏好。審查任何類庫項目時都應當把它當作默認檢查項。實操審查與修復清單結(jié)合原文檔與倉庫證據(jù)給出可直接執(zhí)行的審查流程掃描范圍打開每個會被打包發(fā)布的.csproj以及Directory.Build.props如果分析器放在全局 props 中如評測夾具所示關(guān)鍵詞掃描查找*.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內(nèi)的.nuspec文件確認dependencies節(jié)點中不再出現(xiàn)這些包或?qū)ο掠螠y試項目dotnet restore后確認分析器沒有被動安裝。常見誤區(qū)與邊界誤區(qū)一不發(fā)布庫就不需要只有純可執(zhí)行程序如控制臺/Web 應用不打包時泄漏影響有限只要是類庫且會dotnet pack發(fā)布給他人使用就必須私有化。判斷依據(jù)是這個項目是否會被其他項目作為包引用。誤區(qū)二加了PrivateAssets后分析器在自己項目上就不生效了不會。PrivateAssets只切斷向下的傳遞當前項目的構(gòu)建期功能分析、版本號計算、SourceLink 嵌入完全不受影響。誤區(qū)三IncludeAssets與PrivateAssets二選一兩者職責不同——IncludeAssets決定當前項目消費包中哪些資產(chǎn)PrivateAssets決定哪些資產(chǎn)不外傳。分析器包常二者并用如評測夾具注釋所示以最小化對構(gòu)建和下游的影響?？偨Y(jié)PrivateAssetsall是分析器與構(gòu)建工具包在類庫項目中的強制約定而非可選優(yōu)化缺失它會把構(gòu)建期噪音泄漏給每一個下游消費者。本倉庫將這一規(guī)則固化為msbuild-antipatterns的 AP-07 反模式、item-management的獨立最佳實踐章節(jié)、msbuild-code-reviewAgent 的默認檢查項并在 tests/dotnet-msbuild/msbuild-antipatterns 的評測夾具中制造真實反例來考核 Agent 的識別能力。編寫或?qū)彶轭悗旃こ涛募r把分析器/工具包是否帶了PrivateAssetsall列為第一輪掃描項即可用一行代碼的改動避免整條依賴鏈上的污染。【免費下載鏈接】skillsRepository for skills to assist AI coding agents with .NET and C#項目地址: https://gitcode.com/GitHub_Trending/skills17/skills創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考