@cratis/pi 7.102.0 → 7.103.0

package/package/corpus/skills/msbuild/references/extension-points.md

@@ -0,0 +1,281 @@
+# MSBuild extension points
+
+## Contents
+
+- CustomBefore / CustomAfter hooks
+- Wildcard import directories
+- Import gating and control properties
+- NuGet package build extension layout
+- Source tree vs packed layout
+- Import guard pattern
+- Directory.Build discovery
+- Creating your own extension point
+- Verify the extension
+
+Based on the original `extension-points` skill: import hooks, wildcard extensions, control
+properties, NuGet build assets, import guards, and Directory.Build discovery.
+Use it for a specific import/hook failure or requested authoring modernization.
+
+## CustomBefore / CustomAfter hooks
+
+Common MSBuild targets expose hooks such as:
+
+```xml
+<PropertyGroup>
+  <CustomBeforeMicrosoftCommonTargets Condition="'$(CustomBeforeMicrosoftCommonTargets)' == ''">
+    $(MSBuildExtensionsPath)\v$(MSBuildToolsVersion)\Custom.Before.Microsoft.Common.targets
+  </CustomBeforeMicrosoftCommonTargets>
+</PropertyGroup>
+
+<Import Project="$(CustomBeforeMicrosoftCommonTargets)"
+        Condition="'$(CustomBeforeMicrosoftCommonTargets)' != '' and Exists('$(CustomBeforeMicrosoftCommonTargets)')" />
+<Import Project="$(CustomAfterMicrosoftCommonTargets)"
+        Condition="'$(CustomAfterMicrosoftCommonTargets)' != '' and Exists('$(CustomAfterMicrosoftCommonTargets)')" />
+```
+
+Inspect the actual importing file and version; do not assume every targets file exposes the same
+hooks. Although `Import` supports semicolon-separated paths, the surrounding `Exists()` tests
+the whole property before the import runs. If any optional path in the list is absent, the
+guard can skip the entire import, including a valid new hook. Do not append a new path blindly
+to `CustomBeforeMicrosoftCommonTargets`.
+
+For a hook with one existing optional path, use an aggregation file. In an early
+`Directory.Build.props`, before the common targets consume the hook, preserve that path (or
+its optional installed default) and set the hook to the aggregation file:
+
+```xml
+<PropertyGroup>
+  <_RepoPreviousCommonTargetsHook>$(CustomBeforeMicrosoftCommonTargets)</_RepoPreviousCommonTargetsHook>
+  <_RepoPreviousCommonTargetsHook Condition="'$(_RepoPreviousCommonTargetsHook)' == ''">$(MSBuildExtensionsPath)\v$(MSBuildToolsVersion)\Custom.Before.Microsoft.Common.targets</_RepoPreviousCommonTargetsHook>
+  <CustomBeforeMicrosoftCommonTargets>$(MSBuildThisFileDirectory)BuildHooks.targets</CustomBeforeMicrosoftCommonTargets>
+</PropertyGroup>
+```
+
+Place `BuildHooks.targets` and the required `MyExtension.targets` beside that props file:
+
+```xml
+<!-- BuildHooks.targets -->
+<Project>
+  <Import Project="$(_RepoPreviousCommonTargetsHook)"
+          Condition="'$(_RepoPreviousCommonTargetsHook)' != '' and Exists('$(_RepoPreviousCommonTargetsHook)')" />
+  <Import Project="$(MSBuildThisFileDirectory)MyExtension.targets" />
+</Project>
+```
+
+The optional prior hook has its own guard; its absence cannot suppress the new required hook.
+If the prior value is already a list, inspect its contract and give each optional import its
+own guard in the aggregation file instead of passing that list to a single `Exists()`.
+Verify both the present and absent optional-hook cases, preserving the intended import order.
+
+Guard **optional** imports; required imports should fail explicitly when missing. Defaults that
+refer to installed MSBuild extensions can include a toolset/version segment for side-by-side
+installations. Do not overwrite a configured hook or disable all imports to hide one bad file.
+
+For target execution rather than file imports, prefer uniquely named targets with
+`BeforeTargets`/`AfterTargets`, or extend a documented `...DependsOn` property while preserving its
+existing value. Define the list before a hook extends it, and check for dependency cycles.
+
+## Wildcard import directories
+
+Wildcard imports are sorted by filename:
+
+```xml
+<Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Imports\Microsoft.Common.props\ImportBefore\*"
+        Condition="'$(ImportByWildcardBeforeMicrosoftCommonProps)' == 'true'
+                   and Exists('$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Imports\Microsoft.Common.props\ImportBefore')" />
+```
+
+| Property | Typical location | Scope |
+| --- | --- | --- |
+| `MSBuildUserExtensionsPath` | Per-user MSBuild extension directory | User-specific |
+| `MSBuildExtensionsPath` | MSBuild installation | Machine/toolset |
+| `MSBuildProjectExtensionsPath` | Intermediate directory, normally `obj` | Project/NuGet |
+
+Use names such as `01-defaults.props` and `02-overrides.props` when order is part of the contract.
+Check the expanded imports. A machine- or user-wide extension affects more than the current repo.
+
+## Import gating and control properties
+
+Standard extension/discovery points use control properties with defaults such as:
+
+```xml
+<PropertyGroup>
+  <ImportByWildcardBeforeMicrosoftCommonProps
+      Condition="'$(ImportByWildcardBeforeMicrosoftCommonProps)' == ''">true</ImportByWildcardBeforeMicrosoftCommonProps>
+  <ImportDirectoryBuildProps
+      Condition="'$(ImportDirectoryBuildProps)' == ''">true</ImportDirectoryBuildProps>
+</PropertyGroup>
+```
+
+| Property | Controlled behavior |
+| --- | --- |
+| `ImportDirectoryBuildProps` | Directory.Build.props discovery/import |
+| `ImportDirectoryBuildTargets` | Directory.Build.targets discovery/import |
+| `ImportProjectExtensionProps` | Generated project-extension props, including NuGet |
+| `ImportProjectExtensionTargets` | Generated project-extension targets, including NuGet |
+| `ImportByWildcardBefore*` | Matching ImportBefore extension point |
+| `ImportByWildcardAfter*` | Matching ImportAfter extension point |
+
+Set a control property before its consumer evaluates. These switches change build behavior:
+disabling NuGet-generated imports or shared settings is not a general correctness/performance fix.
+
+## NuGet package build extension layout
+
+Automatically imported entry files use the package ID as their basename:
+
+```text
+MyPackage\
+  build\
+    MyPackage.props
+    MyPackage.targets
+  buildTransitive\
+    MyPackage.props
+    MyPackage.targets
+```
+
+- `build` serves direct consumers.
+- `buildTransitive` can flow to transitive consumers with PackageReference.
+- `buildMultiTargeting` serves the outer cross-targeting build, not ordinary per-TFM execution.
+- Props are imported early and targets late. Framework-specific files can be placed in TFM
+  subdirectories; NuGet selects compatible assets rather than necessarily an exact TFM match.
+- A differently named entry file can cause `NU5129` and not be imported. Supporting files can
+  have other names when an entry file explicitly imports them. Inspect the generated
+  `*.nuget.g.props`/`*.nuget.g.targets` and restored assets to confirm discovery.
+
+Package build files must not redefine restore inputs such as `TargetFramework`, `PackageReference`,
+or `PackageVersion`. See the
+[NuGet build-file conventions](https://learn.microsoft.com/en-us/nuget/concepts/msbuild-props-and-targets).
+
+### Forwarding chain
+
+When sharing implementation, keep a clear `buildTransitive -> build -> shared` chain instead of
+duplicating direct/transitive logic or forwarding blindly to `buildMultiTargeting`.
+For per-TFM layouts, include the matched asset folder segment. Derive it from the importing file,
+not the consumer's `TargetFramework`: a `net10.0` project may consume the package's `net8.0` folder.
+
+```xml
+<!-- Inside packed buildTransitive/<tfm>/MyPackage.props. -->
+<Import Project="$(MSBuildThisFileDirectory)..\..\build\$([System.IO.Path]::GetFileName($([System.IO.Path]::GetDirectoryName('$(MSBuildThisFileDirectory)'))))\MyPackage.props" />
+```
+
+Only use that path for that actual packed layout. Non-TFM-specific assets need a different
+relative path, not an invented framework directory.
+
+## Source tree vs packed layout
+
+A source folder is not necessarily the layout of its `.nupkg`. Before reporting a missing
+`build` or `buildTransitive` import:
+
+1. Inspect the effective `NuspecFile`, `NuspecBasePath`, and `NuspecProperties` for the original
+   pack configuration, including imported assignments and command-line global properties.
+   Follow the configured relative or absolute `NuspecFile` even when it is outside the project
+   directory and its parent. Resolve its `<file src="..." target="...">` mappings using the
+   effective base path and property substitutions. An unavailable configured file is missing
+   evidence, not proof that the packed import is absent.
+2. When no custom nuspec is configured, inspect `.nuspec` files in the project directory and its
+   **immediate parent** as a bounded discovery fallback; do not search unrelated ancestors.
+3. Inspect the project's `Pack`/`PackagePath` item metadata and SDK packaging properties such as
+   `BuildOutputTargetFolder` and `IncludeBuildOutput`.
+4. Project the destination paths, including renamed files and per-TFM copies. Prefer inspecting
+   the actual package when one is available.
+5. Flag the import only if its target is absent from both the applicable source layout and the
+   packed contract. A required file guaranteed by packaging must not gain an `Exists()` guard
+   that would silently hide a broken package.
+
+One shared source can be packed to multiple framework-specific destinations:
+
+```xml
+<files>
+  <file src="buildTransitive\common\MyAdapter.props" target="buildTransitive\net462\MyAdapter.props" />
+  <file src="buildTransitive\common\MyAdapter.props" target="buildTransitive\net8.0\MyAdapter.props" />
+</files>
+```
+
+Equivalent SDK pack metadata can place the same source at each destination:
+
+```xml
+<ItemGroup>
+  <None Include="buildTransitive\common\MyAdapter.props"
+        Pack="true" PackagePath="buildTransitive\net462\MyAdapter.props" />
+  <None Include="buildTransitive\common\MyAdapter.props"
+        Pack="true" PackagePath="buildTransitive\net8.0\MyAdapter.props" />
+</ItemGroup>
+```
+
+The absence of those TFM directories in source is not a missing-import defect. Preserve required
+package contracts; do not add an existence guard to silently conceal a broken published layout.
+See [msbuild-antipatterns](msbuild-antipatterns.md) AP-13.
+
+## Import guard pattern
+
+An imported file can record successful initialization:
+
+```xml
+<!-- At the end of the relevant props initialization. -->
+<PropertyGroup>
+  <MicrosoftCommonPropsHasBeenImported>true</MicrosoftCommonPropsHasBeenImported>
+</PropertyGroup>
+
+<!-- In the corresponding targets file. -->
+<Import Project="Microsoft.Common.props"
+        Condition="'$(MicrosoftCommonPropsHasBeenImported)' != 'true'" />
+```
+
+This pattern supports projects that enter through the targets file. Do not set another SDK's
+guard to pretend its initialization happened; custom SDKs should use their own guard property.
+
+## Directory.Build discovery
+
+Only the nearest `Directory.Build.props` and nearest `Directory.Build.targets` are discovered
+automatically. Nested files must explicitly import parents when inheritance is intended:
+
+```xml
+<Project>
+  <PropertyGroup>
+    <_ParentPropsPath>$([MSBuild]::GetPathOfFileAbove('Directory.Build.props', '$(MSBuildThisFileDirectory)..\'))</_ParentPropsPath>
+  </PropertyGroup>
+  <Import Project="$(_ParentPropsPath)" Condition="'$(_ParentPropsPath)' != ''" />
+</Project>
+```
+
+Start the search above the current file to avoid recursion. Whether an absent parent is optional
+is a repository contract; fail if it is required. Defaults belong before their consumers, while
+values depending on project-defined properties must be evaluated late enough to see them.
+In particular, early property conditions and later item conditions differ; see AP-21 in
+[additional anti-patterns](antipatterns/additional-antipatterns.md).
+
+## Creating your own extension point
+
+For a custom SDK whose required `MySDK.props` sets `MySDKPropsImported`, a targets file can expose
+before/after imports and target hooks:
+
+```xml
+<Project>
+  <Import Project="$(MSBuildThisFileDirectory)MySDK.props"
+          Condition="'$(MySDKPropsImported)' != 'true'" />
+  <PropertyGroup>
+    <CustomBeforeMySDK Condition="'$(CustomBeforeMySDK)' == ''">$(MSBuildProjectDirectory)\MySDK.Before.targets</CustomBeforeMySDK>
+    <CustomAfterMySDK Condition="'$(CustomAfterMySDK)' == ''">$(MSBuildProjectDirectory)\MySDK.After.targets</CustomAfterMySDK>
+    <MySDKBuildDependsOn Condition="'$(MySDKBuildDependsOn)' == ''">BeforeMySDKBuild;CoreMySDKBuild;AfterMySDKBuild</MySDKBuildDependsOn>
+  </PropertyGroup>
+  <Import Project="$(CustomBeforeMySDK)" Condition="Exists('$(CustomBeforeMySDK)')" />
+  <Target Name="MySDKBuild" DependsOnTargets="$(MySDKBuildDependsOn)" />
+  <Target Name="BeforeMySDKBuild" />
+  <Target Name="CoreMySDKBuild" />
+  <Target Name="AfterMySDKBuild" />
+  <Import Project="$(CustomAfterMySDK)" Condition="Exists('$(CustomAfterMySDK)')" />
+</Project>
+```
+
+Initialize the dependency list **before** importing extensions so a before-hook's appended
+targets are not overwritten afterward. An extension can preserve the list and add its own
+target, or use a uniquely named `BeforeTargets`/`AfterTargets` hook. Test that prior extensions,
+the core work, and the new work all remain scheduled.
+
+## Verify the extension
+
+Check the import graph (a preprocessed project can show import ordering), evaluated values, and
+target execution with the original scenario. Preprocessing is not a substitute for evaluated
+property/item values. Exercise both single-targeted and multi-targeted consumers when affected,
+and direct/transitive consumers of package assets. Confirm pre-existing hooks still run, new hooks
+run exactly where intended, and optional versus required missing files behave differently.

package/package/corpus/skills/msbuild/references/incremental-build.md

@@ -0,0 +1,365 @@
+# Optimizing MSBuild Incremental Builds
+
+## Contents
+
+- How MSBuild Incremental Build Works
+- Why Incremental Builds Break (Top Causes)
+- Diagnosing "Why Did This Rebuild?"
+- FileWrites and Clean Build
+- Visual Studio Fast Up-to-Date Check
+- Making Custom Targets Incremental
+- Performance Summary and Preprocess
+- Common Fixes
+- Validation
+
+Source: original incremental build skill.
+
+## How MSBuild Incremental Build Works
+
+MSBuild can skip targets whose outputs are up to date, reducing work on subsequent
+ordinary builds.
+
+- **`Inputs` and `Outputs`:** file-producing targets use file timestamps to
+  determine freshness. Outputs must exist and be at least as new as the relevant
+  inputs. One-to-one item transforms can support partial incremental execution
+  rather than requiring every output to be rebuilt.
+- **Without file-based checks:** a target with neither attribute has no such
+  freshness test when reached. It can still be skipped by conditions or because
+  it already ran for that project instance. Cheap orchestration or discovery
+  targets may correctly execute on every invocation that reaches them.
+- **No `Incremental` target attribute:** `Incremental="false"` is not a valid
+  MSBuild `Target` attribute. Do not add it to force execution.
+- **Timestamps, not hashes:** touching an input can invalidate the target even
+  without content changes. Conversely, unchanged timestamps can hide changes.
+
+```xml
+<!-- A one-to-one input/output mapping -->
+<Target Name="Transform"
+        Inputs="@(TransformFiles)"
+        Outputs="@(TransformFiles->'$(OutputPath)%(Filename).out')">
+  <!-- Existing transformation task goes here -->
+</Target>
+
+<!-- No file-based freshness check when this target is invoked -->
+<Target Name="PrintMessage">
+  <Message Text="This runs when the target is reached" />
+</Target>
+```
+
+Give transformed outputs distinct paths if inputs can have duplicate basenames.
+Do not add fictitious output files merely to skip necessary work.
+
+## Why Incremental Builds Break (Top Causes)
+
+1. **Missing Inputs/Outputs on file-producing custom targets.** Declare meaningful
+   file dependencies for expensive repeatable work, not indiscriminately for every
+   orchestration target.
+2. **Volatile output paths.** Timestamps, build counters, or GUIDs in a path prevent
+   finding the prior output.
+3. **Writes outside declared Outputs.** A target may skip even when an undeclared
+   generated file is missing or stale; track all required outputs.
+4. **Missing FileWrites registration.** Standard Clean tracking may miss custom
+   generated files. Merely putting a file under `obj` does not register it.
+5. **Glob changes.** Additions and removals alter item membership, but general
+   timestamp checks do not remember the previous set. Removing an input, or
+   adding an older input, need not invalidate a custom target. Use appropriate
+   input-set tracking and obsolete-output cleanup when the output depends on
+   membership.
+6. **Property changes.** MSBuild does not automatically compare prior property
+   values used by a generator. Track relevant values explicitly. Changed
+   configuration/TFM/RID paths can select missing outputs, but returning to an
+   already-built configuration can reuse its isolated output set.
+7. **NuGet package updates.** Assets and resolved reference changes can correctly
+   invalidate compilation and resolution work. Preserve necessary invalidation.
+8. **Compiler-server state.** A recycled `VBCSCompiler` can make a compilation that
+   executes slower. It does not by itself explain why an up-to-date `CoreCompile`
+   ran; separate execution decisions from compiler warm-up.
+
+## Diagnosing "Why Did This Rebuild?"
+
+Use binlogs to identify exactly why a target executed instead of skipping.
+
+### Step-by-Step Using Binlog
+
+1. Reuse matching first/second-build artifacts if available. Otherwise follow
+   [binlog generation](binlog-generation.md) and capture two ordinary builds:
+
+   Choose unused explicit names for both logs; the names below are illustrative.
+
+   ```powershell
+   dotnet build "-bl:first.binlog"
+   if ($LASTEXITCODE -ne 0) { throw "First build failed; no valid incremental baseline." }
+   dotnet build "-bl:second.binlog"
+   ```
+
+   Keep configuration, TFM/RID, properties, restore policy, and inputs unchanged.
+   Analyze the second successful build. `Rebuild` and `--no-incremental` force
+   full work and cannot establish a no-change skip result.
+2. [Replay the second binlog](binlog-failure-analysis.md#replay-a-binary-log)
+   locally with diagnostic verbosity and a performance summary, substituting `second.binlog`
+   for `build.binlog`. The searches below use that command's `full-01.log`; substitute the
+   actual path if you chose another name. Replay the first build to a different file when comparing.
+3. Find executed/skipped targets and the accompanying reasons:
+
+   ```powershell
+   Select-String -Path .\full-01.log -Pattern 'Building target|Skipping target|was not skipped|is newer than output' -Context 0,5
+   ```
+
+4. Interpret messages in context (`...` stands for the target name):
+   - **`Building target "..." completely.`:** full target execution; read the reason
+     instead of assuming all outputs were missing.
+   - **`Building target "..." partially, because some output files are out of date
+     with respect to their input files.`:** partial execution for an applicable
+     input/output mapping.
+   - **`Skipping target "..." because all output files are up-to-date with respect
+     to the input files.`:** freshness checks permitted a skip; verify the declared
+     dependency set is complete.
+5. Record the precise input/output path, timestamp, missing output, or condition
+   responsible, for the correct project/global-property instance.
+
+### Additional Diagnostic Techniques
+
+- Compare the two replayed logs for changed properties, items, paths, and reasons.
+- Find expensive second-build targets:
+
+  ```powershell
+  Select-String -Path .\full-01.log -Pattern 'Target Performance Summary|Task Performance Summary' -Context 0,30
+  ```
+
+- Aggregate/nested timings are not additive wall time. Follow orchestration waits
+  to actual task work using [performance diagnostics](build-perf-diagnostics.md).
+- A zero-duration target that runs is not automatically a defect. Inspect its
+  dependencies and actual cost before changing it.
+- If evaluation dominates while compilation correctly skips, use
+  [evaluation performance](eval-performance.md), not a fake incremental shortcut.
+
+## FileWrites and Clean Build
+
+`FileWrites` lets the standard Clean infrastructure track build-generated files.
+It is separate from target freshness and compiler inclusion.
+
+- **`FileWrites`:** register owned generated files so the normal Clean pipeline
+  can discover them.
+- **`FileWritesShareable`:** do not assume reference-counted ownership or protection
+  because another project still uses a file. Inspect the selected Clean targets,
+  locations, and shared-file ownership before relying on it.
+- **Missing registration:** files can accumulate, leaving stale inputs or outputs.
+  A directory named `obj` is not automatic per-file tracking.
+
+### Pattern for Registering Generated Files
+
+For a generator with declared input files and generated line content:
+
+```xml
+<Target Name="MyGenerator"
+        Inputs="$(MSBuildProjectFullPath);@(GeneratorInput)"
+        Outputs="$(IntermediateOutputPath)generated.cs">
+  <WriteLinesToFile File="$(IntermediateOutputPath)generated.cs"
+                    Lines="@(GeneratedLines)"
+                    Overwrite="true" />
+  <ItemGroup>
+    <FileWrites Include="$(IntermediateOutputPath)generated.cs" />
+  </ItemGroup>
+</Target>
+```
+
+Ensure the directory exists and that all settings/tool/template dependencies are
+modeled; project-file timestamps do not track arbitrary property values. Use
+`Overwrite="true"` when replacing generated content rather than appending it.
+
+An `ItemGroup` inside a target with an up-to-date skip can still be evaluated by
+**output inference**. Thus the source pattern of registering `FileWrites` and
+`Compile` inside that target is valid when the paths/items can be inferred.
+Do not move it solely because the task skipped. If an item depends only on task
+output that cannot be inferred, make that item's definition available separately.
+
+Use only authorized, scoped Clean operations. Never register user-authored files
+or another project's outputs merely to make cleanup more aggressive.
+
+## Visual Studio Fast Up-to-Date Check
+
+Visual Studio's Fast Up-to-Date Check (FUTDC) is distinct from MSBuild's
+`Inputs`/`Outputs`: it can skip invoking MSBuild entirely.
+
+- **Fast checks:** the project system examines known inputs, outputs, copy items,
+  and timestamps without a full build.
+- **Custom work:** custom targets, generated files, or nonstandard/dynamic items
+  may not be visible to that check.
+- **Diagnostic comparison:** temporarily force MSBuild checks when investigating
+  a Visual Studio-only discrepancy:
+
+  ```xml
+  <PropertyGroup>
+    <DisableFastUpToDateCheck>true</DisableFastUpToDateCheck>
+  </PropertyGroup>
+  ```
+
+  Do not leave FUTDC disabled as a default performance fix.
+- **Logging:** in Visual Studio's **Tools > Options > Projects and Solutions >
+  SDK-Style Projects**, enable verbose up-to-date-check logging and inspect the
+  Output window for the actual file/reason.
+- **Common cases:** unregistered custom build actions, items added only during
+  target execution, and changed `Content`/`None` copy items. Diagnose FUTDC's
+  decision separately from MSBuild target skip reasons.
+
+## Making Custom Targets Incremental
+
+The following example combines C# templates under `config\$(ConfigFlavor)` into a
+generated compilation input. The small state file tracks both the selected flavor
+and input membership; a plain timestamp list would miss some changes to either.
+Adapt the generator step and declared dependencies to the repository's real tool.
+
+```xml
+<PropertyGroup>
+  <ConfigFlavor Condition="'$(ConfigFlavor)' == ''">Default</ConfigFlavor>
+</PropertyGroup>
+<ItemGroup>
+  <ConfigInput Include="config\$(ConfigFlavor)\*.cs.in" />
+</ItemGroup>
+
+<Target Name="WriteConfigInputs">
+  <MakeDir Directories="$(IntermediateOutputPath)" />
+  <WriteLinesToFile File="$(IntermediateOutputPath)config.inputs"
+                    Lines="Flavor=$(ConfigFlavor);@(ConfigInput->'%(FullPath)')"
+                    Overwrite="true"
+                    WriteOnlyWhenDifferent="true" />
+  <ItemGroup>
+    <FileWrites Include="$(IntermediateOutputPath)config.inputs" />
+  </ItemGroup>
+</Target>
+
+<Target Name="GenerateConfig"
+        DependsOnTargets="WriteConfigInputs"
+        Inputs="$(MSBuildProjectFullPath);@(ConfigInput);$(IntermediateOutputPath)config.inputs"
+        Outputs="$(IntermediateOutputPath)config.generated.cs"
+        BeforeTargets="CoreCompile">
+  <ReadLinesFromFile File="%(ConfigInput.Identity)"
+                     Condition="'@(ConfigInput)' != ''">
+    <Output TaskParameter="Lines" ItemName="_ConfigLines" />
+  </ReadLinesFromFile>
+  <WriteLinesToFile File="$(IntermediateOutputPath)config.generated.cs"
+                    Lines="@(_ConfigLines)"
+                    Overwrite="true" />
+  <ItemGroup>
+    <FileWrites Include="$(IntermediateOutputPath)config.generated.cs" />
+    <Compile Include="$(IntermediateOutputPath)config.generated.cs" />
+  </ItemGroup>
+</Target>
+```
+
+**Key points:**
+
+- The project file, actual input files, and state file participate in freshness.
+  Also declare imported generator logic, tool binaries, templates, and relevant
+  settings when they affect the real generator.
+- `WriteOnlyWhenDifferent` prevents the **state file** from causing churn on every
+  build. Include every relevant property/input-set value in an unambiguous,
+  stable representation.
+- Generated output is overwritten when regeneration is necessary. If a real
+  generator preserves output timestamps for identical content, use appropriate
+  completion-state tracking so newer inputs do not make it execute forever;
+  still detect missing real outputs.
+- `IntermediateOutputPath` should isolate configurations/TFMs/RIDs; inspect custom
+  overrides. `FileWrites`, not the directory name, supplies clean registration.
+- `BeforeTargets="CoreCompile"` makes the file available before compilation.
+  `Compile` inclusion and `FileWrites` registration can be inferred on a skip.
+- Do not duplicate the generated item or rely on an evaluation-time glob to find
+  a file that does not yet exist.
+- For per-input generated outputs, detect removal and clean obsolete **owned**
+  outputs as well as updating the input-set state.
+
+### Common Mistakes to Avoid
+
+```xml
+<!-- Expensive generation without file-based freshness checks -->
+<Target Name="BadTarget" BeforeTargets="CoreCompile">
+  <Exec Command="generate-code.exe" />
+</Target>
+
+<!-- Volatile output path: the next invocation cannot reuse it -->
+<Target Name="BadTarget2"
+        Inputs="@(Compile)"
+        Outputs="$(OutputPath)gen_$([System.DateTime]::Now.Ticks).cs">
+  <Exec Command="generate-code.exe" />
+</Target>
+
+<!-- Stable-output pattern; declare the real tool/configuration inputs too -->
+<Target Name="GoodTarget"
+        Inputs="$(MSBuildProjectFullPath);@(GeneratorInput)"
+        Outputs="$(IntermediateOutputPath)generated.cs"
+        BeforeTargets="CoreCompile">
+  <Exec Command="generate-code.exe -o &quot;$(IntermediateOutputPath)generated.cs&quot;" />
+  <ItemGroup>
+    <FileWrites Include="$(IntermediateOutputPath)generated.cs" />
+    <Compile Include="$(IntermediateOutputPath)generated.cs" />
+  </ItemGroup>
+</Target>
+```
+
+These external-tool patterns assume the actual generator exists and produces the
+declared file. Add property/input-set tracking when needed, as in the full example.
+Do not include generated outputs in their own input set.
+
+## Performance Summary and Preprocess
+
+- **`-clp:PerformanceSummary`:** identifies cumulative project/target/task costs:
+
+  ```powershell
+  dotnet build -clp:PerformanceSummary
+  ```
+
+  Compare the relevant second-build work; inclusive durations are not exclusive
+  CPU time.
+- **`-pp:preprocess.xml`:** expands imports to locate definitions and their origin:
+
+  ```powershell
+  dotnet msbuild .\MyProject.csproj "-pp:preprocess.xml"
+  ```
+
+  It is not a dump of fully evaluated property/item values. Find the definitions
+  of `Inputs`, `Outputs`, and imports, then inspect the matching build instance.
+- Use the summary for what ran and `/pp` for where it was defined, together with
+  replayed skip reasons.
+
+## Common Fixes
+
+- **Declare meaningful Inputs/Outputs** for repeatable file-producing work,
+  including missing-output recovery and all real dependencies.
+- **Use stable intermediate paths** while preserving configuration/TFM/RID
+  isolation and avoiding output collisions.
+- **Register owned generated files in FileWrites**; validate the applicable
+  scoped Clean behavior rather than assuming every intermediate file is tracked.
+- **Avoid unnecessary volatile data.** If per-build timestamps are required,
+  preserve that contract and isolate their downstream impact. For Git revision
+  state, a project-file timestamp or `.git\HEAD` alone is insufficient: branch
+  refs can change without either changing. Use the repository's reliable state
+  mechanism or a cheap probe that writes only changed content; report probe
+  failures instead of freezing a stale value.
+- **Use Returns for return-only item collections.** These are alternative
+  definitions, not two targets to install together:
+
+  ```xml
+  <!-- Outputs also participates in file-based freshness -->
+  <Target Name="GetFiles" Outputs="@(DiscoveredFiles)" />
+
+  <!-- Returns supplies items without a file-based freshness contract -->
+  <Target Name="GetFiles" Returns="@(DiscoveredFiles)" />
+  ```
+
+- **Choose copy metadata deliberately** using
+  [CopyToOutputDirectory modes](copy-to-output-directory.md), especially when
+  consumers mutate copied files.
+
+## Validation
+
+Compare equivalent ordinary builds using the
+[baseline](build-perf-baseline.md). In an authorized disposable/scoped workspace,
+verify: a no-change second build; input modification, addition, and removal;
+property/template/tool changes; deletion of a real generated output; downstream
+compilation and required diagnostics; relevant configuration/TFM/RID variants;
+and approved Clean behavior. For copied content, include destination mutation.
+
+Report the target/project instance, exact reason/file evidence, the correction,
+before/after timings, and checks actually completed. A faster build that misses
+required regeneration, leaves stale outputs, or changes an agreed metadata
+contract is not a successful incremental-build fix.