Item Management

作者 dotnet0608d8924cd3MIT5.5K 个星标收录于 2026年10月8日更新于 2026年10月8日仓库今天更新

Own concrete MSBuild ItemGroup and item-expression questions. USE FOR: Include, Remove, Update, item identity and metadata, transforms, filtering, batching, duplicate or overlapping items, and reviews that verify whether those operations are correct. Generated items stay in scope when the central defect is item identity, metadata, batching, duplicate declarations, or glob/Remove/Update semantics. For a generated artifact missing from compilation or output, wrong target timing/path, or FileWrites clean tracking without a broader item-semantics defect, use including-generated-files. The item operation may be broken, suspected, or already correct. Exclude property-only issues, general incrementality with no item question, broad reviews with no concrete item concern, and non-MSBuild systems.

仅含说明Software Development

AI 生成的概览

讲解 MSBuild ItemGroup 的 Include、Remove、Update、元数据、转换、批处理与重复项处理。

功能: 该技能提供源自 Microsoft.Common.CurrentVersion.targets 的 MSBuild 项管理规范模式。它说明 Include、Remove、Update 三种操作、项标识与元数据、转换、Exclude 模式、条件包含以及使用 %(Metadata) 的批处理。它还列出常见陷阱，例如交叉乘积批处理、在源码树中生成文件以及遗漏 FileWrites 条目。
适用场景: 适用于具体的 MSBuild ItemGroup 或项表达式问题，包括核查项操作是否正确的评审。适合涉及项标识、元数据、批处理、重复或重叠项，以及 glob、Remove 或 Update 语义的问题。不适用于仅涉及属性的问题、没有项问题的通用增量构建，或非 MSBuild 系统。
运行要求: 无需脚本或工具，仅为说明性参考。代理不需要软件包、凭据或网络访问。

MSBuild Item Management Patterns

Canonical patterns for working with item groups, from Microsoft.Common.CurrentVersion.targets.

Include / Remove / Update — Three Operations

Operation	Purpose	When to use
`Include`	Add new items to the group	Creating items with identity + metadata
`Remove`	Remove items matching a pattern	Excluding files or clearing a group
`Update`	Modify metadata on existing items	Adding/changing metadata without re-adding

Include — Add Items

Remove — Subtract Items

xml

<ItemGroup>  <!-- Remove specific items -->  <Reference Remove="$(AdditionalExplicitAssemblyReferences)" />
  <!-- Set subtraction: prior minus current -->  <_CleanOrphanFileWrites Include="@(_CleanPriorFileWrites)"      Exclude="@(_CleanCurrentFileWrites)" />
  <!-- Clear an entire group -->  <_Temporary Remove="@(_Temporary)" /></ItemGroup>

<ItemGroup>  <!-- Remove specific items -->  <Reference Remove="$(AdditionalExplicitAssemblyReferences)" />
  <!-- Set subtraction: prior minus current -->  <_CleanOrphanFileWrites Include="@(_CleanPriorFileWrites)"      Exclude="@(_CleanCurrentFileWrites)" />
  <!-- Clear an entire group -->  <_Temporary Remove="@(_Temporary)" /></ItemGroup>

Update — Modify Existing Items

xml

<ItemGroup>  <EmbeddedResource Update="@(EmbeddedResource)"      Condition="'%(NuGetPackageId)' == 'Microsoft.CodeAnalysis.Collections'">    <GenerateSource>true</GenerateSource>    <ClassName>Microsoft.CodeAnalysis.Collections.SR</ClassName>  </EmbeddedResource></ItemGroup>

<ItemGroup>  <EmbeddedResource Update="@(EmbeddedResource)"      Condition="'%(NuGetPackageId)' == 'Microsoft.CodeAnalysis.Collections'">    <GenerateSource>true</GenerateSource>    <ClassName>Microsoft.CodeAnalysis.Collections.SR</ClassName>  </EmbeddedResource></ItemGroup>

Update does not add items — it only modifies items already in the group.

Item Batching — %(Metadata)

When %(Metadata) appears in target attributes or task parameters, MSBuild batches execution per unique metadata value.

Target-level batching (Outputs)

xml

<Target Name="GenerateSatelliteAssemblies"    Inputs="$(MSBuildAllProjects);@(_SatelliteAssemblyResourceInputs)"    Outputs="$(IntermediateOutputPath)%(Culture)\$(TargetName).resources.dll">  <!-- Runs once per unique Culture value --></Target>

<Target Name="GenerateSatelliteAssemblies"    Inputs="$(MSBuildAllProjects);@(_SatelliteAssemblyResourceInputs)"    Outputs="$(IntermediateOutputPath)%(Culture)\$(TargetName).resources.dll">  <!-- Runs once per unique Culture value --></Target>

Task-level batching

xml

<Copy SourceFiles="@(_SourceItems)"    DestinationFiles="@(_SourceItems->'$(OutDir)%(TargetPath)')"></Copy>

<Copy SourceFiles="@(_SourceItems)"    DestinationFiles="@(_SourceItems->'$(OutDir)%(TargetPath)')"></Copy>

Per-item filtering with Condition

xml

<ItemGroup>  <_ResxOutput Include="@(EmbeddedResource->'%(OutputResource)')"      Condition="'%(EmbeddedResource.WithCulture)' == 'false'" /></ItemGroup>

<ItemGroup>  <_ResxOutput Include="@(EmbeddedResource->'%(OutputResource)')"      Condition="'%(EmbeddedResource.WithCulture)' == 'false'" /></ItemGroup>

Batching rules

%(Metadata) in Condition or Outputs → target batches per unique value.
%(Metadata) in task parameters → task batches per unique value.
Do not mix %() from different item groups in the same expression — this causes a cross-product (see Common Pitfalls).

Item Transforms — @(Item->'expression')

Transforms create new item lists by applying an expression to each item:

xml

<!-- Transform file paths to destinations --><Copy SourceFiles="@(IntermediateAssembly)"    DestinationFiles="@(IntermediateAssembly->'$(OutDir)%(Filename)%(Extension)')"/>
<!-- Transform with separator for display --><Message Text="Files: @(Compile->'%(Filename)', ', ')" />

<!-- Transform file paths to destinations --><Copy SourceFiles="@(IntermediateAssembly)"    DestinationFiles="@(IntermediateAssembly->'$(OutDir)%(Filename)%(Extension)')"/>
<!-- Transform with separator for display --><Message Text="Files: @(Compile->'%(Filename)', ', ')" />

Exclude Pattern — Set Subtraction on Include

Exclude only works on Include — it cannot be used with Update or Remove.

Conditional Item Inclusion

xml

<!-- Condition on ItemGroup — all or nothing --><ItemGroup Condition="'$(NetCoreBuild)' == 'true'">  <PackageReference Include="System.IO.Pipelines" /></ItemGroup>
<!-- Condition on individual items --><ItemGroup>  <PackageReference Include="System.IO.Pipelines"      Condition="'$(NetCoreBuild)' == 'true'" /></ItemGroup>

<!-- Condition on ItemGroup — all or nothing --><ItemGroup Condition="'$(NetCoreBuild)' == 'true'">  <PackageReference Include="System.IO.Pipelines" /></ItemGroup>
<!-- Condition on individual items --><ItemGroup>  <PackageReference Include="System.IO.Pipelines"      Condition="'$(NetCoreBuild)' == 'true'" /></ItemGroup>

PrivateAssets on Tool/Analyzer Packages

xml

<ItemGroup>  <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" PrivateAssets="all" />  <PackageReference Include="StyleCop.Analyzers" PrivateAssets="all" /></ItemGroup>

<ItemGroup>  <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" PrivateAssets="all" />  <PackageReference Include="StyleCop.Analyzers" PrivateAssets="all" /></ItemGroup>

Common Pitfalls

Cross-product batching

Referencing %(Metadata) from two different item groups creates O(N×M) executions:

xml

<!-- BAD: Cross-product of @(Source) × @(Config) --><Exec Command="process %(Source.Identity) with %(Config.Identity)" />
<!-- GOOD: Reference one group via batching, the other via property --><Exec Command="process %(Source.Identity) with $(ConfigFile)" />

<!-- BAD: Cross-product of @(Source) × @(Config) --><Exec Command="process %(Source.Identity) with %(Config.Identity)" />
<!-- GOOD: Reference one group via batching, the other via property --><Exec Command="process %(Source.Identity) with $(ConfigFile)" />

Generated files in source tree

Write to $(IntermediateOutputPath) (obj/), not the source directory. Source-tree generation pollutes version control and can cause duplicate compilation via globs.

Missing FileWrites

Every file created during a target must be added to @(FileWrites) for dotnet clean support.

来源与署名

来源：dotnet/skills位于plugins/dotnet-msbuild/skills/item-management提交0608d89

许可证： MIT

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

Item Management

MSBuild Item Management Patterns

Include / Remove / Update — Three Operations

Include — Add Items

Remove — Subtract Items

Update — Modify Existing Items

Item Batching — %(Metadata)

Target-level batching (Outputs)

Task-level batching

Per-item filtering with Condition

Batching rules

Item Transforms — @(Item->'expression')

Exclude Pattern — Set Subtraction on Include

Conditional Item Inclusion

PrivateAssets on Tool/Analyzer Packages

Common Pitfalls

Cross-product batching

Generated files in source tree

Missing FileWrites

来源与署名

更多来自 dotnet/skills 的技能

Setup Local Sdk

System Text Json Net11

Thread Abort Migration

Migrate Dotnet9 To Dotnet10

Target Authoring

Resolve Project References

更多Software Development技能

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices