including-generated-files
Fix MSBuild targets that generate files during the build but those files are missing from compilation or output. USE FOR: generated source files not compiling (CS0246 for a type that should exist), custom build tasks that create files but they are invisible to subsequent targets, globs not capturing build-generated files because they expand at evaluation time before execution creates them, ensuring generated files are cleaned by the Clean target. Covers correct BeforeTargets timing (CoreCompile, BeforeBuild, AssignTargetPaths), adding to Compile/FileWrites item groups, using $(IntermediateOutputPath) instead of hardcoded obj/ paths. DO NOT USE FOR: C# source generators that already work via the Roslyn pipeline, T4 design-time generation that runs in Visual Studio, non-MSBuild build systems.
- License 许可
- MIT
- 最近更新
- 2026-09-18
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- including-generated-files
- license
- MIT
- description
- Fix MSBuild targets that generate files during the build but those files are missing from compilation or output. USE FOR: generated source files not compiling (CS0246 for a type that should exist), custom build tasks that create files but they are invisible to subsequent targets, globs not capturing build-generated files because they expand at evaluation time before execution creates them, ensuring generated files are cleaned by the Clean target. Covers correct BeforeTargets timing (CoreCompile, BeforeBuild, AssignTargetPaths), adding to Compile/FileWrites item groups, using $(IntermediateOutputPath) instead of hardcoded obj/ paths. DO NOT USE FOR: C# source generators that already work via the Roslyn pipeline, T4 design-time generation that runs in Visual Studio, non-MSBuild build 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 toNoneorContent. Runs early enough for copy-to-output scenarios.BeforeTargets="CoreCompile;BeforeCompile"— For generated source files added toCompile. Ensures the file is included before the compiler runs.BeforeTargets="AssignTargetPaths"— The "final stop" beforeNoneandContentitems (among others) are transformed into new items. Use as a fallback ifBeforeBuildis 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
vectorization
Design, implement, optimize, and review SIMD code in .NET. USE FOR: vectorizing scalar loops with TensorPrimitives, Vector64/128/256/512, or platform hardware intrinsics; reviewing existing SIMD code, including Vector<T>, for contract equivalence, tail handling, memory safety, portability, fallbacks, and measured performance. DO NOT USE FOR: performance work unrelated to SIMD or vectorization.
resolve-project-references
Guide for interpreting ResolveProjectReferences time in MSBuild performance summaries. Activate when ResolveProjectReferences appears as the most expensive target and developers are trying to optimize it directly. Explains that the reported time includes wait time for dependent project builds and is misleading. Guides users to focus on task self-time instead. Do not activate for general build performance -- use build-perf-diagnostics instead.
optimizing-ef-core-queries
Optimize and improve the performance of slow Entity Framework Core (EF Core) queries: make them generate less SQL, make fewer database round-trips, and return results faster. Use whenever an EF Core or DbContext query or data-access path is slow or should be made faster — whether or not EF Core owns the database schema. For EF Core, not Dapper or raw ADO.NET.
microbenchmarking
Activate this skill when BenchmarkDotNet (BDN) is involved in the task — creating, running, configuring, or reviewing BDN benchmarks. Also activate when microbenchmarking .NET code would be useful and BenchmarkDotNet is the likely tool. Consider activating when answering a .NET performance question requires measurement and BenchmarkDotNet may be needed. Covers microbenchmark design, BDN configuration and project setup, how to run BDN microbenchmarks efficiently and effectively, and using BDN for side-by-side performance comparisons. Do NOT use for profiling/tracing .NET code (dotnet-trace, PerfView), production telemetry, or load/stress testing (Crank, k6).
incremental-build
Guide for optimizing MSBuild incremental builds. USE FOR: builds slower than expected on subsequent runs, 'nothing changed but it rebuilds anyway', diagnosing why targets re-execute unnecessarily, fixing broken no-op builds. Covers 8 common causes: missing Inputs/Outputs on custom targets, volatile properties in output paths (timestamps/GUIDs), file writes outside tracked Outputs, missing FileWrites registration, glob changes, Visual Studio Fast Up-to-Date Check (FUTDC) issues. Key diagnostic: look for 'Building target completely' vs 'Skipping target' in binlog. DO NOT USE FOR: first-time build slowness (use build-perf-baseline), parallelism issues (use build-parallelism), evaluation-phase slowness (use eval-performance), non-MSBuild build systems.
eval-performance
Guide for diagnosing and improving MSBuild project evaluation performance. USE FOR: builds slow before any compilation starts, high evaluation time in binlog analysis, expensive glob patterns walking large directories (node_modules, .git, bin/obj), deep import chains (>20 levels), preprocessed output >10K lines indicating heavy evaluation, property functions with file I/O ($([System.IO.File]::ReadAllText(...))), multiple evaluations per project. Covers the 5 MSBuild evaluation phases, glob optimization via DefaultItemExcludes, import chain analysis with /pp preprocessing. DO NOT USE FOR: compilation-time slowness (use build-perf-diagnostics), incremental build issues (use incremental-build), non-MSBuild build systems.