AGENT SKILL

including-generated-files

Own MSBuild generated-artifact integration. USE FOR: a target that creates or should create source, Content, None, or another physical file but the artifact is missing from compilation or output; target timing; evaluation-time glob misses; $(IntermediateOutputPath) placement; and FileWrites clean tracking. The prompt may describe the generated artifact without naming the producing task. DO NOT USE when the primary defect is general Include/Remove/Update semantics, item metadata or batching, duplicate/overlapping declarations, or a generated-item identity relationship; use item-management. Exclude Roslyn source-generator internals and non-MSBuild systems.

License 许可
MIT
所属仓库
microsoft/testfx
最近更新
2026-11-14
Stars
★ 1.1k
Forks
315

01 前言 Front Matter

name
including-generated-files
license
MIT
description
Own MSBuild generated-artifact integration. USE FOR: a target that creates or should create source, Content, None, or another physical file but the artifact is missing from compilation or output; target timing; evaluation-time glob misses; $(IntermediateOutputPath) placement; and FileWrites clean tracking. The prompt may describe the generated artifact without naming the producing task. DO NOT USE when the primary defect is general Include/Remove/Update semantics, item metadata or batching, duplicate/overlapping declarations, or a generated-item identity relationship; use item-management. Exclude Roslyn source-generator internals and non-MSBuild systems.

03 SKILL.md 正文

Including Generated Files Into Your Build

Overview

Files generated during the build are generally ignored by the build process. This leads to confusing results such as:

  • Generated files not being included in the output directory
  • Generated source files not being compiled
  • Globs not capturing files created during the build

This happens because of how MSBuild's build phases work.

Quick Takeaway

For code files generated during the build - we need to add those to Compile and FileWrites item groups within the target generating the file(s):

  <ItemGroup>
    <Compile Include="$(GeneratedFilePath)" />
    <FileWrites Include="$(GeneratedFilePath)" />
  </ItemGroup>

The target generating the file(s) should be hooked before CoreCompile and BeforeCompile targets - BeforeTargets="CoreCompile;BeforeCompile"

Why Generated Files Are Ignored

For detailed explanation, see How MSBuild Builds Projects.

Evaluation Phase

MSBuild reads your project, imports everything, creates Properties, expands globs for Items outside of Targets, and sets up the build process.

Execution Phase

MSBuild runs Targets & Tasks with the provided Properties & Items to perform the build.

Key Takeaway: Files generated during execution don't exist during evaluation, therefore they aren't found. This particularly affects files that are globbed by default, such as source files (.cs).

Solution: Manually Add Generated Files

When files are generated during the build, manually add them into the build process. The approach depends on the type of file being generated.

Use $(IntermediateOutputPath) for Generated File Location

Always use $(IntermediateOutputPath) as the base directory for generated files. Do not hardcode obj\ or construct the intermediary path manually (e.g., obj\$(Configuration)\$(TargetFramework)\). The intermediate output path can be redirected to a different location in some build configurations (e.g., shared output directories, CI environments). Using $(IntermediateOutputPath) ensures your target works correctly regardless of the actual path.

Always Add Generated Files to FileWrites

Every generated file should be added to the FileWrites item group. This ensures that MSBuild's Clean target properly removes your generated files. Without this, generated files will accumulate as stale artifacts across builds.

<ItemGroup>
  <FileWrites Include="$(IntermediateOutputPath)my-generated-file.xyz" />
</ItemGroup>

Basic Pattern (Non-Code Files)

For generated files that need to be copied to output (config files, data files, etc.), add them to Content or None items before BeforeBuild:

<Target Name="IncludeGeneratedFiles" BeforeTargets="BeforeBuild">
  
  <!-- Your logic that generates files goes here -->

  <ItemGroup>
    <None Include="$(IntermediateOutputPath)my-generated-file.xyz" CopyToOutputDirectory="PreserveNewest"/>
    
    <!-- Capture all files of a certain type with a glob -->
    <None Include="$(IntermediateOutputPath)generated\*.xyz" CopyToOutputDirectory="PreserveNewest"/>

    <!-- Register generated files for proper cleanup -->
    <FileWrites Include="$(IntermediateOutputPath)my-generated-file.xyz" />
    <FileWrites Include="$(IntermediateOutputPath)generated\*.xyz" />
  </ItemGroup>
</Target>

For Generated Source Files (Code That Needs Compilation)

If you're generating .cs files that need to be compiled, use BeforeTargets="CoreCompile;BeforeCompile". This is the correct timing for adding Compile items — it runs late enough that the file generation has occurred, but before the compiler runs. Using BeforeBuild is too early for some scenarios and may not work reliably with all SDK features.

<Target Name="IncludeGeneratedSourceFiles" BeforeTargets="CoreCompile;BeforeCompile">
  <PropertyGroup>
    <GeneratedCodeDir>$(IntermediateOutputPath)Generated\</GeneratedCodeDir>
    <GeneratedFilePath>$(GeneratedCodeDir)MyGeneratedFile.cs</GeneratedFilePath>
  </PropertyGroup>

  <MakeDir Directories="$(GeneratedCodeDir)" />

  <!-- Your logic that generates the .cs file goes here -->

  <ItemGroup>
    <Compile Include="$(GeneratedFilePath)" />
    <FileWrites Include="$(GeneratedFilePath)" />
  </ItemGroup>
</Target>

Note: Specifying both CoreCompile and BeforeCompile ensures the target runs before whichever target comes first, providing robust ordering regardless of customizations in the build.

Target Timing

Choose the BeforeTargets value based on the type of file being generated:

  • BeforeTargets="BeforeBuild" — For non-code files added to None or Content. Runs early enough for copy-to-output scenarios.
  • BeforeTargets="CoreCompile;BeforeCompile" — For generated source files added to Compile. Ensures the file is included before the compiler runs.
  • BeforeTargets="AssignTargetPaths" — The "final stop" before None and Content items (among others) are transformed into new items. Use as a fallback if BeforeBuild is too early.

Globbing Behavior

Globs behave according to when the glob took place:

Glob Location Files Captured
Outside of a target Only files visible during Evaluation phase (before build starts)
Inside of a target Files visible when the target runs (can capture generated files if timed correctly)

This is why the solution places the <ItemGroup> inside a <Target> - the glob runs during execution when the generated files exist.

Relevant Links

04 同仓库更多 Skills

microsoft
microsoft/testfx

dotnet-breaking-changes

Use before changing .NET/C# code whose callers you do not control: a NuGet library, or a repo with PublicAPI.Shipped/Unshipped.txt, ApiCompat, multiple TargetFrameworks, InternalsVisibleTo, or generated (.g.cs) partials. Green builds miss silent breaks from optional parameters, parameter names, sealing, const values, nullability, and #if. USE FOR: "without breaking existing callers"; adding a public method, overload, optional parameter, or interface member to a shipped library; renaming a public method or an internal helper a friend assembly uses; consolidating duplicated logic; changing a signature, nullability, default, or attribute; adding a target framework; RS0016/RS0017 or ApiCompat errors; "is this PR breaking?". For a rename, extract, or merge, also invoke csharp-refactoring. DO NOT USE FOR: an executable whose callers all live in one project; renaming a local variable or private member, even in a shipped library; formatting; framework/SDK/NuGet upgrades (use dotnet-upgrade).

★ 1.1k
microsoft
microsoft/testfx

testfx-test-value-evidence

Apply the vendored test-value-evidence skill with TestFx toolchain, assertion, parallel-safety, packed-consumer, and review conventions. Use when implementing or reviewing behavior-changing TestFx PRs or commits, including source-only changes.

测试与质量
★ 1.1k
microsoft
microsoft/testfx

testfx-parallel-safety-preflight

Check concurrency and isolation before implementing or refactoring TestFx tests, lifecycle code, helpers, shared-state declarations, or production paths those tests exercise. Use before narrowing DoNotParallelize or ResourceLock, changing parallelization settings, or introducing asynchronous workers; repeat against the final diff.

★ 1.1k
microsoft
microsoft/testfx

testfx-localization-validation

Validate generated TestFx localization catalogs, resource IDs, placeholders and locked tokens. Use for RESX/XLF changes, OneLoc PRs, localization build failures, duplicate targets or units, and orphaned translation entries.

★ 1.1k
microsoft
microsoft/testfx

testfx-acceptance-validation

Validate TestFx shipping paths and capable CI execution using packed consumers, package/cache provenance, exact exits and artifacts, and selected-versus-executed test evidence. Use for acceptance regressions, package/MSBuild/launcher/protocol changes, or skipped-only CI results; not for unrelated unit-only or documentation changes.

测试与质量
★ 1.1k
microsoft
microsoft/testfx

session-delivery-hygiene

Gate local-session scope, persistent delivery, live PR state, integration provenance, and owned cleanup. Use before implementing guidance changes, changing or pushing PR work, diagnosing package/output mismatches, or handing off implementation.

★ 1.1k