@cratis/pi 7.102.0 → 7.103.1

package/package/corpus/skills/msbuild/references/build-perf-diagnostics.md

@@ -0,0 +1,268 @@
+# Diagnosing MSBuild Build Performance
+
+## Contents
+
+- Performance Analysis Methodology
+- Key Metrics and Thresholds
+- Common Bottlenecks
+- Using Binlog Replay for Performance Analysis
+- Quick Wins Checklist
+- Impact Categorization
+
+Source: original build perf diagnostics skill.
+
+## Performance Analysis Methodology
+
+1. Establish the relevant cold, warm changed-input, or no-change
+   [baseline](build-perf-baseline.md). Keep `Rebuild` and ordinary `Build` distinct.
+2. Use an existing matching binlog first. If one is missing, follow
+   [binlog generation](binlog-generation.md) without changing the reported scenario.
+3. [Replay the binary log](binlog-failure-analysis.md#replay-a-binary-log) locally
+   to a diagnostic text log with a performance summary. The searches below assume
+   that log is named `full-01.log`, as in the replay command; use its actual path.
+4. Find expensive projects, targets, and tasks, then inspect the corresponding
+   instance, execution reason, inputs, and dependency waits. Select one cause
+   for a controlled change, not every plausible optimization.
+
+Performance summaries report cumulative/inclusive durations, not additive shares
+of elapsed wall time or CPU usage. Parallel work overlaps; orchestration targets
+and tasks can include child work and waits.
+
+In particular, **`ResolveProjectReferences` can mostly represent waiting for
+dependent builds**, while a yielded node performs other work. Do not optimize it
+solely because it tops the target summary. Follow the dependencies to actual
+`Csc`, `ResolveAssemblyReference`, `Copy`, or custom-task work. Even `MSBuild`
+task duration can include child builds rather than exclusive self-time.
+
+## Key Metrics and Thresholds
+
+Use these as investigation hints, not universal budgets or proof of a cause:
+
+- **Build duration:** historical rough examples are under 10 seconds for a small
+  workload, 60 seconds for a medium one, and 5 minutes for a large one. Compare
+  the repository's actual scenario and machine, not labels alone.
+- **Node utilization:** activity below roughly 80% warrants checking dependency
+  waits, limited parallel work, and resource contention. Text-summary totals
+  alone cannot establish utilization.
+- **Single-target domination:** investigate a target near or above 50% of elapsed
+  build time, but separate inclusive waits and nested work.
+- **Analyzer versus compiler time:** around 30% or more of `Csc` time deserves
+  investigation. Analyzer timings can overlap; do not add them as wall time or
+  remove diagnostics solely to reach a percentage.
+- **RAR time:** over 5 seconds per project, especially over 15 seconds, merits
+  examination of reference count, paths, and resolution work.
+
+## Common Bottlenecks
+
+### 1. ResolveAssemblyReference (RAR) Slowness
+
+- **Symptoms:** substantial `ResolveAssemblyReference` task time, for example
+  over 5 seconds per affected project.
+- **Root causes:** many assembly references, network-based paths, or expensive
+  assembly search paths.
+- **Fixes:** remove demonstrated unused references/search paths and avoid
+  unnecessary network resolution, preserving all consumers.
+- **Diagnostic guardrail:** `DesignTimeBuild`, `ResolveAssemblyReferencesSilent`,
+  and `ResolveAssemblyWarnOrErrorOnTargetArchitectureMismatch` affect build or
+  diagnostic behavior; changing them is not an established RAR performance fix.
+- **Key insight:** RAR can legitimately execute on no-change builds to account
+  for external resolution state, including installed targeting packs or GAC
+  assemblies. Do not force it to skip using an incomplete freshness check.
+- **Reduce transitive references carefully:** `DisableTransitiveProjectReferences`
+  is a last resort requiring explicit references to consumed dependencies.
+  `ReferenceOutputAssembly="false"` is appropriate when only build ordering is
+  needed, but still retains that ordering. Trim only unused package references.
+  Use the [dependency-graph audit](build-perf-baseline.md#step-4-dependency-graph-trimming).
+
+### 2. Roslyn Analyzers and Source Generators
+
+- **Symptoms:** `Csc` takes much longer than a comparable compilation, sometimes
+  more than twice a measured compiler-only scenario.
+- **Diagnosis:** inspect `Csc` and analyzer/generator timing in the replayed log.
+  If timing detail is absent, obtain compiler-supported diagnostic timing rather
+  than guessing from package count. A controlled `-p:RunAnalyzers=false`
+  comparison must compile the same inputs on both sides, not compare a no-op
+  against forced compilation.
+- **Conditional development policy:** after measuring and agreeing the policy,
+  examples include:
+
+  ```xml
+  <PropertyGroup>
+    <RunAnalyzers Condition="'$(ContinuousIntegrationBuild)' != 'true'">false</RunAnalyzers>
+    <EnforceCodeStyleInBuild Condition="'$(ContinuousIntegrationBuild)' == 'true'">true</EnforceCodeStyleInBuild>
+  </PropertyGroup>
+  ```
+
+- **Per-configuration:** if development Debug builds are the intended scope, also
+  guard the CI case, for example
+  `Condition="'$(Configuration)' == 'Debug' and '$(ContinuousIntegrationBuild)' != 'true'"`.
+  CI can build Debug too.
+- **Rule/package scope:** configure genuinely redundant or expensive diagnostics
+  appropriately, including `.editorconfig` severity policy, instead of blindly
+  removing analyzer packages.
+- **Key principle:** preserve required analyzer enforcement in CI. Verify effective
+  properties and that the pipeline actually sets the CI signal. A conditional
+  assignment does not undo an earlier or later unconditional override.
+- **Source generators:** do not assume `RunAnalyzers=false` disables or measures
+  every generator. Preserve required generated code and inspect generator-specific
+  evidence.
+- **GlobalPackageReference:** examine the project, `Directory.Build.props`,
+  `Directory.Packages.props`, and package imports. Active global analyzer
+  references can affect production and test projects; a declaration alone does
+  not prove restoration or inclusion in the compiler's analyzer list.
+- **EnforceCodeStyleInBuild:** when enabled it adds code-style checks to compiler
+  execution; it does not mean analyzers execute when compilation itself skips.
+  Conditionalize only under an agreed development/CI policy.
+
+### 3. Serialization Bottlenecks (Single-threaded Targets)
+
+- **Symptoms:** one project dominates while other nodes are idle or waiting.
+- **Common culprits:** a long dependency chain, a critical-path project, or custom
+  orchestration issuing independent project requests sequentially.
+- **Fixes:** optimize the measured critical path, remove false dependencies, or
+  split a bottleneck only when it exposes independent work. In custom `MSBuild`
+  tasks, `BuildInParallel="true"` also needs multiple available nodes.
+- Follow [parallel build tuning](build-perf-baseline.md#step-6-parallel-build-tuning).
+  More nodes cannot parallelize required serial dependencies.
+
+### 4. Excessive File I/O (Copy Tasks)
+
+- **Symptoms:** high Copy aggregate time or excessive copy invocations.
+- **Root causes:** thousands of unnecessary files, network destinations, or
+  accidental per-item task batching instead of an appropriate item batch.
+- **First fixes:** inspect item metadata, source/destination paths, and invocation
+  counts. Reduce only unnecessary copies and choose the correct
+  [copy mode](copy-to-output-directory.md); replacing `Always` blindly with
+  `PreserveNewest` can leave mutated destination files stale.
+- **Skip unchanged files:** inspect whether the actual target consumes
+  `SkipCopyUnchangedFiles`; it may already be true. Custom `Copy` tasks expose
+  `SkipUnchangedFiles`. Neither setting is a content-hash comparison.
+- **Hardlinks:** identify the hot copy target in the binlog, then set only the
+  property that target passes to `Copy.UseHardlinksIfPossible`:
+  `CreateHardLinksForCopyFilesToOutputDirectoryIfPossible` for primary build
+  outputs, `CreateHardLinksForAdditionalFilesIfPossible` for content/additional
+  files, or `CreateHardLinksForCopyLocalIfPossible` for copy-local references.
+  Custom `Copy` tasks need their own `UseHardlinksIfPossible` value. Hardlinks
+  can help compatible same-volume, immutable-file workloads. A destination
+  mutation through a hardlink can modify its source, so do not use this for
+  writable/resettable content.
+- **Shared layout:** `UseCommonOutputDirectory=true` assumes a genuinely shared,
+  collision-free output layout. Verify ownership and consumers first.
+  [Artifacts output](build-perf-baseline.md#step-2-artifacts-output-layout), including
+  `--artifacts-path`, requires SDK 8+ and is a separate measured layout change.
+- **Dev Drive:** on supported Windows development or self-hosted CI machines,
+  evaluate Dev Drive for a measured I/O bottleneck. Do not promise automatic
+  copy-on-write gains for every task or disable security tooling for a benchmark.
+
+### 5. Evaluation Overhead
+
+- **Symptoms:** significant startup/evaluation time before target execution.
+- **Root causes:** expensive `Directory.Build.props` logic, globs traversing
+  large trees, imports, or SDK-resolution overhead. NuGet-based SDK resolver
+  latency depends on the toolset and environment; historical timings are not a
+  fixed per-project cost.
+- **Fixes:** simplify only measured costly logic and narrow offending globs.
+  `EnableDefaultItems=false` is a last resort requiring complete intentional item
+  lists, not the first optimization. Changing SDK resolution must preserve the
+  build's actual SDK contract.
+- Use [evaluation performance](eval-performance.md) for focused evidence and fixes.
+
+### 6. NuGet Restore in Build
+
+- **Symptoms:** restore contributes substantial work repeatedly. Distinguish an
+  up-to-date check from actual repeated network/dependency-resolution work.
+- **Separate restore from build:** successfully restore matching inputs, then
+  use `dotnet build --no-restore`. Keep build-only and restore-inclusive baselines
+  distinct; dependency changes require fresh assets.
+- **Static graph restore:** `RestoreUseStaticGraphEvaluation=true` in
+  `Directory.Build.props` is a candidate for a measured large restore graph.
+  Validate equivalent resolved assets and toolset support. It is distinct from
+  graph build and its benefit is workload-dependent.
+- Investigate changing inputs and feed/cache behavior rather than purging shared
+  package caches.
+
+### 7. Large Project Count and Graph Shape
+
+- **Symptoms:** many tiny projects add evaluation/invocation overhead, or deep
+  dependency chains serialize otherwise parallelizable work.
+- **Consider:** graph mode for scheduling, consolidating small leaves for measured
+  overhead, or splitting a large bottleneck into independent pieces. These are
+  different remedies for different evidence.
+- **Graph shape matters:** wide independent branches expose parallelism; a long
+  required chain remains serial regardless of node count.
+- **Actions:** identify the exact unnecessary edge or costly project. Preserve
+  direct API/metadata contracts and compare the resulting critical path.
+  [Static graph builds](build-perf-baseline.md#step-5-static-graph-builds-graph)
+  do not automatically provide isolation or a cache.
+
+## Using Binlog Replay for Performance Analysis
+
+1. [Replay the existing binlog](binlog-failure-analysis.md#replay-a-binary-log)
+   with diagnostic verbosity and a performance summary.
+2. Read the target/task summaries, usually near the end of the replayed log:
+
+   ```powershell
+   Select-String -Path .\full-01.log -Pattern 'Target Performance Summary|Task Performance Summary' -Context 0,50
+   ```
+
+   Use the cumulative timings to select candidates, not to compute additive
+   percentages of elapsed build time.
+3. Find per-project timings and instances:
+
+   ```powershell
+   Select-String -Path .\full-01.log -Pattern 'Done Building Project|Project Performance Summary' -Context 0,20
+   ```
+
+4. Inspect recorded scheduling evidence:
+
+   ```powershell
+   Select-String -Path .\full-01.log -Pattern 'node.*assigned|building with|scheduler'
+   ```
+
+   These messages alone are not a utilization measurement. Report missing
+   scheduling/timestamp detail rather than inferring an exact timeline.
+5. Check analyzer timing, when the original capture contains it:
+
+   ```powershell
+   Select-String -Path .\full-01.log -Pattern 'Total analyzer execution time|analyzer.*elapsed|CompilerAnalyzerDriver'
+   ```
+
+6. Drill into the relevant project's slow target and its tasks:
+
+   ```powershell
+   Select-String -Path .\full-01.log -Pattern 'Target "CoreCompile"|Target "ResolveAssemblyReferences"' -Context 0,20
+   ```
+
+## Quick Wins Checklist
+
+Choose only items supported by the diagnosis, one experiment at a time:
+
+- [ ] Confirm the intended `-m` node budget rather than assuming host defaults.
+- [ ] Separate restore and build only with current matching assets.
+- [ ] Measure static graph restore and verify equivalent assets.
+- [ ] Consider hardlinks only for compatible immutable-file workloads.
+- [ ] Scope analyzer changes to an agreed development policy; retain CI enforcement.
+- [ ] Inspect `ProduceReferenceAssembly` before enabling it; many SDK configurations
+  already enable it. Verify implementation-only and public-API changes downstream.
+- [ ] Check [incremental behavior](incremental-build.md) on an ordinary second build.
+- [ ] Inspect evaluated output/intermediate paths for collisions between projects,
+  configurations, TFMs, and RIDs; do not just give everything one common directory.
+- [ ] Measure graph mode for a statically discoverable multi-project build.
+- [ ] Evaluate SDK 8+ artifacts layout only with its path-consumer checks.
+- [ ] Consider a separate Dev Drive environment experiment for Windows I/O limits.
+
+## Impact Categorization
+
+- **HIGH IMPACT:** a verified critical-path cost above roughly 10% of elapsed
+  build time, or substantial real work behind a target reported above 50%.
+- **MEDIUM IMPACT:** verified costs around 2-10%.
+- **QUICK WINS:** low-effort changes with demonstrated modest benefit, not
+  unmeasured property toggles.
+
+Report the project/TFM, target/task, evidence, one targeted change, and a
+same-scenario before/after comparison with spread. Verify required artifacts,
+diagnostics, and relevant tests/consumers. Stop if the result is unmeasured, within
+noise, or breaks correctness; do not claim success from disabled validation or
+inclusive timing arithmetic.
+
+> **Cratis:** Only as a labelled timing experiment; restore analyzers and warnings-as-errors and run the real gate before finishing.

package/package/corpus/skills/msbuild/references/copy-to-output-directory.md

@@ -0,0 +1,183 @@
+# Choosing a CopyToOutputDirectory Mode
+
+## Contents
+
+- Overview
+- Why `Always` Is Usually the Wrong Choice
+- `IfDifferent`: Copy When Different, in Either Direction
+- Globally Softening `Always` with `$(SkipUnchangedFilesOnCopyAlways)`
+- How the Modes Flow Through the Build
+- Version Requirement
+- Quick Decision Guide
+- Verify the Choice
+
+Source: original copy to output directory skill.
+
+## Overview
+
+`CopyToOutputDirectory` metadata controls whether an item such as `Content`,
+`None`, `EmbeddedResource`, or `Compile` is copied next to the build output.
+`CopyToPublishDirectory` controls the corresponding publish selection. Picking
+the wrong mode can leave stale files or add recurring copy work.
+
+As of **MSBuild 17.13 / .NET SDK 9.0.2xx**, the common build targets support four
+values. Check the publishing SDK separately for publish behavior.
+
+| Mode | Copies when | Incremental cost | Typical use |
+| --- | --- | --- | --- |
+| `Never` | Never through this copy pipeline | None | Files not needed in that output |
+| `PreserveNewest` | Source is newer than destination, or destination is missing | Timestamp checks | Normal source-edited content |
+| `Always` | Every build that reaches the copy target, unless a skip-unchanged override is enabled | Repeated copies in classic mode | A real unconditional-copy/reset requirement |
+| `IfDifferent` | Timestamp or size differs in either direction, or destination is missing | Timestamp and size checks | Destination may be mutated between builds |
+
+Omitted metadata commonly means `Never`, but SDKs/imports can supply item-specific
+defaults. Inspect effective metadata before assuming omission disables copying.
+
+The following `Include` examples are for explicitly included files. When an SDK
+already includes a file, use `Update` on its actual item type instead; for example,
+a web SDK can classify `appsettings.json` as `Content`, not `None`.
+
+```xml
+<ItemGroup>
+  <None Include="appsettings.json" CopyToOutputDirectory="PreserveNewest" />
+  <None Include="testdata\seed.db" CopyToOutputDirectory="IfDifferent" />
+</ItemGroup>
+```
+
+The child-element form is equivalent:
+
+```xml
+<None Include="testdata\seed.db">
+  <CopyToOutputDirectory>IfDifferent</CopyToOutputDirectory>
+</None>
+```
+
+## Why `Always` Is Usually the Wrong Choice
+
+Classic `Always` re-copies files whenever that copy pipeline executes, including
+otherwise no-change MSBuild builds. Many or large content files can make this a
+measurable recurring cost. An IDE up-to-date check that skips MSBuild entirely is
+a separate decision.
+
+Historically, `Always` addressed a specific scenario: **the destination changes
+between builds**. Tests or applications might mutate a database, state file, or
+configuration file. With `PreserveNewest`, a newer destination is not reset
+because the source is no longer newer. `Always` forces a reset, but pays for it
+even when the destination has not changed.
+
+Do not replace `Always` solely because it appears in project text. First measure
+copy work and establish whether unconditional copying is part of the required
+behavior.
+
+## `IfDifferent`: Copy When Different, in Either Direction
+
+`IfDifferent` restores the source when the destination is missing or its timestamp
+or size differs, whether the destination is newer or older. It skips unchanged
+files according to that metadata comparison.
+
+`_CopyDifferingSourceItemsToOutputDirectory` uses the `Copy` task with
+`SkipUnchangedFiles="true"`. This is a **timestamp-and-size heuristic, not a content
+hash**. A destination edited to the same size and last-write timestamp is treated
+as unchanged and is not restored.
+
+Use `IfDifferent` when:
+
+- Tests or the application mutate copied databases, state/storage files, or
+  editable configuration, and the metadata-based reset meets the contract.
+- `Always` was used only to synchronize a drifting destination, not because
+  every build must perform a fresh copy.
+
+```xml
+<ItemGroup>
+  <!-- For an explicitly included fixture; use Update if already included -->
+  <None Include="fixtures\catalog.db" CopyToOutputDirectory="IfDifferent" />
+</ItemGroup>
+```
+
+If same-size/same-timestamp mutations must also be reset, retain genuine
+unconditional copying or a separately verified content-based mechanism.
+
+## Globally Softening `Always` with `$(SkipUnchangedFilesOnCopyAlways)`
+
+For a codebase with many legacy `Always` items, a bulk opt-in is:
+
+```xml
+<PropertyGroup>
+  <SkipUnchangedFilesOnCopyAlways>true</SkipUnchangedFilesOnCopyAlways>
+</PropertyGroup>
+```
+
+The common `Always` copy target then passes `SkipUnchangedFiles="true"` to `Copy`,
+giving those items the same timestamp/size skip heuristic as `IfDifferent`.
+
+- Unset/default behavior is effectively `false`: classic `Always` copying.
+- Setting it in `Directory.Build.props` can affect the entire repository.
+- Prefer per-item intent when practical. A bulk property avoids individual item
+  edits, but still changes behavior and requires checking every affected reset
+  contract.
+- Do not assume this build-target property governs every publish copy task.
+
+## How the Modes Flow Through the Build
+
+`GetCopyToOutputDirectoryItems` buckets items by their metadata. The common
+`_CopySourceItemsToOutputDirectory` pipeline, invoked by
+`CopyFilesToOutputDirectory`, uses:
+
+- `_CopyOutOfDateSourceItemsToOutputDirectory` for `PreserveNewest`, with
+  `Inputs`/`Outputs` timestamp checks.
+- `_CopyOutOfDateSourceItemsToOutputDirectoryAlways` for `Always`, with the
+  skip-unchanged property controlling its `Copy` task.
+- `_CopyDifferingSourceItemsToOutputDirectory` for `IfDifferent`, with
+  `SkipUnchangedFiles="true"`.
+
+These standard build copies register `FileWrites` for the normal Clean pipeline.
+Custom tasks and publish outputs can have different tracking; inspect ownership
+and use only approved, scoped cleanup.
+
+**Transitive copy:** copyable items can flow to referencing projects through
+`ProjectReference`, including `_CopyToOutputDirectoryTransitiveItems`; `Never`
+does not participate in that copy pipeline. Verify consumers as well as the
+defining project. Supporting targets also collect `IfDifferent` for ClickOnce;
+test the publishing mode and supported toolset actually used by the repository.
+
+## Version Requirement
+
+`IfDifferent` and `SkipUnchangedFilesOnCopyAlways` require **MSBuild 17.13+**
+(**.NET SDK 9.0.2xx+ / Visual Studio 2022 17.13+**) for the common build-target
+behavior described here. Older common targets can silently omit an item whose
+mode they do not recognize.
+
+Check the actual SDK/MSBuild host and the minimum supported toolset, not the
+target framework. Gate usage or require a compatible SDK through `global.json`,
+and check Visual Studio/MSBuild.exe hosts too. On older hosts, retaining `Always`
+can preserve required reset behavior; substituting `PreserveNewest` may not.
+An unsupported skip-unchanged property is not evidence of a speedup.
+
+`CopyToPublishDirectory` is implemented by publishing targets. Verify recognition,
+transitive collection, and reset behavior on the selected publishing SDK rather
+than inferring support from the common build-target version alone.
+
+## Quick Decision Guide
+
+- Not needed in this output: explicitly choose `Never` when defaults might copy it.
+- Normal source-edited file: `PreserveNewest`.
+- Mutated destination should reset when metadata differs: `IfDifferent`.
+- Fresh copy required on every pipeline execution, including metadata-identical
+  changes: `Always`, without a skip-unchanged override.
+- Many compatible legacy `Always` items: consider
+  `SkipUnchangedFilesOnCopyAlways=true` after checking the same behavioral limits.
+
+## Verify the Choice
+
+In an approved disposable workspace or on explicitly scoped files, check an
+ordinary no-change build, a source edit, a missing destination, and destination
+mutations with newer and older timestamps. Check same-size/same-timestamp mutation
+when strict reset matters. Also test source addition/removal and the intended
+stale-output policy: copy metadata alone does not guarantee obsolete destinations
+are deleted.
+
+Check build, referencing projects, runtime use, and relevant publish/ClickOnce
+outputs. Do not hardlink writable/resettable outputs to sources: writes through a
+hardlink can change the source. Compare copy counts and same-scenario timings
+using the [baseline](build-perf-baseline.md); preserve the output contract rather
+than claiming success merely because fewer files were copied.

package/package/corpus/skills/msbuild/references/eval-performance.md

@@ -0,0 +1,190 @@
+# Diagnosing MSBuild Evaluation Performance
+
+## Contents
+
+- Confirm the Problem Before Changing Anything
+- MSBuild Evaluation Phases
+- Diagnosing Evaluation Performance
+- Expensive Glob Patterns
+- Import Chain Analysis
+- Multiple Evaluations
+- TreatAsLocalProperty
+- Property Function Cost
+- Optimization Checklist
+
+Source: original eval performance skill.
+
+Evaluation is work MSBuild does before executing targets: reading project files,
+processing imports, expanding globs, and establishing definitions. Find and
+confirm the bottleneck first; recommend a change only when measurements justify it.
+
+## Confirm the Problem Before Changing Anything
+
+Engage only when evaluation is **measurably** costly. Do not act when:
+
+- **Slowness is in compilation or target execution.** Use
+  [build performance diagnostics](build-perf-diagnostics.md).
+- **The complaint is unnecessary rebuilding.** Use
+  [incremental-build diagnosis](incremental-build.md).
+- **There is no measurement.** Reuse a matching binlog or timing summary, or
+  collect one through [binlog generation](binlog-generation.md). Do not infer
+  slowness solely from project syntax.
+- **A pattern below appears but evaluation is already fast.** Broad globs, deep
+  imports, and item-default settings are not reasons to rewrite healthy builds.
+
+Report unmeasured patterns as observations, not causes. Prefer the smallest
+targeted change; never disable SDK defaults as the first move.
+
+## MSBuild Evaluation Phases
+
+1. **Initial properties:** environment variables, global properties, and reserved properties.
+2. **Imports and properties:** process imports and property groups in evaluation order.
+3. **Item definitions:** establish metadata defaults.
+4. **Items:** process `Include`, `Remove`, `Update`, and glob expansion.
+5. **UsingTask definitions:** register task implementations.
+6. **Target definitions:** establish targets for subsequent execution.
+
+Evaluation precedes execution for a project instance. It can be expensive even
+when compilation later skips; a source generator running in `Csc` is execution,
+not project evaluation.
+
+## Diagnosing Evaluation Performance
+
+### Using Binlog Replay
+
+1. [Replay the existing binary log](binlog-failure-analysis.md#replay-a-binary-log)
+   locally with diagnostic verbosity and performance summaries. The search below uses that
+   command's `full-01.log`; substitute the actual path if you chose another name.
+2. Look for evaluation timing and instance information:
+
+   ```powershell
+   Select-String -Path .\full-01.log -Pattern 'Project Evaluation Performance Summary|Evaluation started|Evaluation finished|Project evaluation' -Context 0,20
+   ```
+
+3. Record the expensive project instance, global properties, configuration,
+   TFM/RID, and invocation purpose. Distinct instances may be expected rather
+   than duplicate work.
+4. Inspect its imports and property/item definitions. If the capture lacks
+   detailed evaluation timing, do not fabricate it from the number of imports.
+   On supporting MSBuild versions, `-profileEvaluation:eval.tsv` provides a
+   focused profile; record the extra instrumentation separately.
+
+### Using /pp (Preprocess)
+
+```powershell
+dotnet msbuild .\MyProject.csproj "-pp:full.xml"
+```
+
+- Supply the same configuration/TFM/global properties as the affected instance.
+- `/pp` inlines imports and shows their boundaries and definitions.
+- It does **not** fully expand every property/item value or measure evaluation cost.
+- Over 10,000 lines can be a clue to inspect, not proof of heavy evaluation.
+
+For evaluated values, **MSBuild 17.8+** also supports queries such as:
+
+```powershell
+dotnet msbuild .\MyProject.csproj -p:TargetFramework=net8.0 -getProperty:Configuration,TargetFramework -getItem:Compile
+```
+
+Without a target request, this evaluates rather than builds. On older hosts, use
+the available diagnostic evidence instead of assuming these query switches exist.
+
+### Using /clp:PerformanceSummary
+
+Add `-clp:PerformanceSummary` to the same build invocation for evaluation,
+project, target, and task summaries. Keep evaluation separate from execution,
+and remember that cumulative/nested/parallel durations are not additive wall time.
+
+## Expensive Glob Patterns
+
+Pursue these remedies only when item evaluation is slow and the globs are the
+measured cause; a custom glob over a small intended tree is fine.
+
+- Broad patterns such as `**\*.cs` can traverse large trees.
+- SDK default globs have exclusions; custom globs may not share them.
+- Watch for unexpected traversal of `node_modules`, `.git`, and generated
+  `bin`/`obj` trees, not just the text of the pattern.
+- Append appropriate `DefaultItemExcludes` rather than replacing existing
+  exclusions. A custom item must actually consume the exclusion property.
+- Narrow roots/file types where equivalent, such as `src\**\*.cs`.
+- `EnableDefaultItems=false` is a last resort requiring an intentional
+  replacement for compile/resource/content discovery and future file changes.
+- Inspect evaluated `Compile` and other affected items for unexpected files.
+
+For an offending custom item, adapt exclusions and paths to the intended input set:
+
+```xml
+<PropertyGroup>
+  <DefaultItemExcludes>$(DefaultItemExcludes);**\node_modules\**;**\.git\**</DefaultItemExcludes>
+</PropertyGroup>
+<ItemGroup>
+  <AdditionalFiles Include="src\**\*.json" Exclude="$(DefaultItemExcludes)" />
+</ItemGroup>
+```
+
+Verify item equivalence and file addition/removal behavior, not just a faster scan.
+
+## Import Chain Analysis
+
+- Deep chains, for example over 20 levels, are candidates to inspect, not
+  inherently slow builds.
+- Imports require reading, parsing, and evaluation; measure the costly portion.
+- Common sources include package `.props`/`.targets`, framework SDK imports,
+  and `Directory.Build` chains.
+- Use `/pp` import-boundary comments and file paths to understand ownership and
+  nesting; do not depend on one exact comment phrase.
+- Consolidate/remove imports or package-provided build content only when the
+  chain is measurably costly and all property/item/target consumers are preserved.
+
+## Multiple Evaluations
+
+- The same project path can legitimately have multiple evaluations.
+- Different global-property sets, TFM/RID/configurations, outer/inner
+  multi-targeting builds, restore, and design-time builds can require distinct
+  instances.
+- Compare instance identity and call purpose, not just an evaluation count or a
+  rule of "one evaluation per project per TFM."
+- Investigate callers that introduce accidental global-property differences.
+  Normalize only differences that do not change intended behavior.
+- [Graph build](build-perf-baseline.md#step-5-static-graph-builds-graph) is an
+  experiment for compatible graphs, not a guarantee of evaluation deduplication.
+
+## TreatAsLocalProperty
+
+- Allows listed global properties to be overridden within the current project.
+- A local override is not automatically forwarded as a new global value to
+  child projects. For example, a command-line value can still reach a child even
+  though the parent locally changed that property.
+- It is therefore not a blanket mechanism for removing inherited properties
+  from child builds. Use explicit `MSBuild` task property controls, such as
+  `Properties` or `RemoveProperties`, when that is the intended contract.
+- Use it when local override semantics are genuinely needed. The number of names
+  listed is not by itself evidence of measurable evaluation overhead.
+
+## Property Function Cost
+
+- Property functions used during evaluation run at evaluation time; expressions
+  inside targets instead run when that execution reaches them.
+- Most string operations are cheap.
+- `$([System.IO.File]::ReadAllText(...))` can repeat file I/O on each evaluation.
+- Network access and heavy computations can be costly; measure the actual
+  function rather than declaring every file read a bottleneck.
+- Keep evaluation-time functions fast and side-effect-free. Move work into a
+  correctly incremental target only if evaluation-time consumers do not need
+  its result.
+
+## Optimization Checklist
+
+- [ ] Inspect `/pp` definitions/imports without treating line count as timing.
+- [ ] Explain evaluation counts by project-instance identity.
+- [ ] Exclude large unintended directories from measured costly globs.
+- [ ] Reduce measured unnecessary evaluation-time I/O.
+- [ ] Simplify expensive import chains while preserving consumers.
+- [ ] Compare graph mode only where statically discoverable and relevant.
+- [ ] Remove `UsingTask` declarations only if their consumers and measurable cost
+  justify it.
+
+Repeat the same build scenario and evaluate the same intended item/property sets.
+Check additions, changes, removals, affected configurations, and downstream
+behavior. Report timing and evidence before/after; leave configuration unchanged
+when evaluation is cheap, unmeasured, or the apparent gain is within noise.