Enable trim/AOT analyzers for Microsoft.Build and clean up annotations

[JeremyKuhne]

Summary

Makes the Microsoft.Build evaluation object model trim- and Native-AOT-capable so an AOT-compiled host (the dotnet CLI) can evaluate and build projects in-process, and fail observably wherever a path genuinely requires run-time reflection (loading a task, SDK resolver, logger, or build check discovered by name) so the host can fall back to a JIT MSBuild - never a silent no-op and never a crash deep in the engine.

The work is evaluation-first: evaluation is kept fully trim/AOT-clean today, and execution becomes possible through closed-world host registration (registered SDK resolvers and task classes) while open-world reflective paths fail observably. The build is clean on both net10.0 and net472 (0 IL warnings, 0 warnings, 0 errors).

Change breakdown

About half the diff is documentation; validation and engine code are each roughly a quarter. The engine change is intentionally small and surgical - overwhelmingly trim/AOT annotations and feature-switch gating rather than behavior changes to the JIT path.

Category	Files	Added	Deleted
Documentation	15	4,653	0
Validation (AOT harness + unit tests)	22	2,158	21
Engine code	69	1,990	355
Localization (.xlf/.resx for 4 new diagnostics)	14	344	0
Other (.gitignore)	1	3	0
Total	121	9,148	376

The actual engine code change is ~2,000 lines across 69 files; the remaining ~7,000 lines are documentation, the validation harness/tests, and auto-generated localization.

New public API surface

Three reflection-free, closed-world registration entry points let a host hand MSBuild the types it needs up front so the trimmer preserves them:

• Microsoft.Build.Framework.SdkResolver.Register(SdkResolver) - contribute a pre-constructed SDK resolver instead of MSBuild discovering and Assembly.LoadFrom-ing one by reflection.
• Microsoft.Build.Utilities.Task.RegisterTask<T>() (plus a RegisterTask(string, Func<ITask>) overload) - register a task class so the engine constructs, binds, and runs it with reflective task execution disabled.
• Microsoft.Build.Utilities.TaskItem.RegisterTaskParameterValueType<T>() and RegisterTaskParameterItemType<T>() - resolve <UsingTask> / <ParameterGroup> parameter types without a by-name Type.GetType.

Four new diagnostics report unsupported reflective paths under trimming/AOT:

• MSB4282 - an SDK requires a dynamically-loaded SDK resolver (unsupported in a trimmed/AOT host).
• MSB4283 - a task requires reflective loading/execution (unsupported in a trimmed/AOT host).
• MSB4284 - a custom BuildCheck requires reflective plugin loading (unsupported in a trimmed/AOT host).
• MSB4285 - a logger named by its assembly/class requires reflective loading (unsupported in a trimmed/AOT host).

API-review callout: besides the additive registration APIs above, there is a deliberate public trim-metadata change - the public ITaskFactory / ITaskFactory2 / ITaskFactory3 Initialize and CreateTask members now carry [RequiresUnreferencedCode], and ITaskFactory.TaskType carries [DynamicallyAccessedMembers(PublicProperties)]. There is no managed signature change, but a host reaching task creation through the interface now sees an honest IL2026, and a third-party ITaskFactory that enables trim analysis gets IL2046 until it adds the matching attribute.

AOT validation

A new Native AOT validation harness (src/aot-validation/) publishes a fully AOT-compiled image and runs it end-to-end. It validates that AOT works for both evaluating and building the basic library (dotnet new classlib) and executable (dotnet new console) project templates:

• Evaluate - DotnetNew_Classlib_EvaluatesAsLibraryProject, DotnetNew_Console_EvaluatesAsExecutableProject: evaluate the stock templates through the object model under AOT.
• Build - DotnetNew_Classlib_BuildUnderAot_RunsRegisteredTasksThenFailsObservably, DotnetNew_Console_BuildUnderAot_RunsRegisteredTasksThenFailsObservably: build the templates in-process under AOT, confirming registered/intrinsic tasks run and that an unsupported reflective task fails observably (MSB4283) rather than crashing.

Additional harness coverage exercised against the published AOT image: object-model evaluation, property-function reachability, and each of the three registration APIs (SDK resolver, task class, task-parameter type).

Design criterion: fail observably, never silently

A trimmed/AOT path that cannot run surfaces a reported error (or a host-readable property) so the host can branch and fall back; it never silently drops a project's expressed intent and never crashes in the engine. [UnconditionalSuppressMessage] is used only for provable false positives; accurate warnings are gated behind feature switches (with observable failure) or carry honest [RequiresUnreferencedCode] to a public boundary.

Design notes, the strategy catalog, and living suppression/annotation trackers are in documentation/aot/; the host-registration API proposals are in documentation/specs/.

[Copilot]

Pull request overview

This PR enables IL trim/AOT analysis for Microsoft.Build (via IsAotCompatible on net8.0+) and resolves the resulting IL warnings primarily by propagating [RequiresUnreferencedCode] through reflection-heavy/extensibility call chains, adding targeted suppressions at message-pump/delegate boundaries, and tightening DynamicallyAccessedMembers annotations.

Changes:

• Enable trim/AOT analyzers for src/Build/Microsoft.Build.csproj (net8.0+ only) and eliminate IL warnings across net10.0 + net472.
• Propagate [RequiresUnreferencedCode] across task loading, SDK resolution, logging, project cache, evaluation/graph, build-request engine, and BuildCheck acquisition.
• Apply a small set of AOT-friendly refactors (notably ParallelWorkSet, task-parameter array creation, and logger registration) to avoid analyzer-triggering patterns.

Reviewed changes

Copilot reviewed 64 out of 64 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/Build/Microsoft.Build.csproj	Enables IsAotCompatible for net8.0+ to run trim/AOT analyzers.
src/Tasks/XamlTaskFactory/XamlTaskFactory.cs	Adds DynamicallyAccessedMembers annotation to TaskType.
src/Tasks/RoslynCodeTaskFactory/RoslynCodeTaskFactory.cs	Isolates trim-unsafe reflection behind RUC helpers; adjusts suppressions.
src/Tasks/CodeTaskFactory.cs	Annotates TaskType with DynamicallyAccessedMembers; updates stub branch.
src/Shared/TypeLoader.cs	Marks runtime assembly/type loading paths as RUC.
src/Shared/TaskParameter.cs	AOT-friendly array creation for primitive arrays during translation.
src/Shared/TaskLoader.cs	Adds suppression on type-filter delegate used during reflective discovery.
src/Shared/TaskEngineAssemblyResolver.cs	Adds suppression on assembly-resolve handlers.
src/Framework/ReflectableTaskPropertyInfo.cs	Reworks property lookup to avoid trim-unfriendly APIs; narrows DAM.
src/Framework/Loader/LoadedType.cs	Expands DAM requirements to include public parameterless ctor.
src/Framework/ITaskFactory.cs	Adds DAM annotation to ITaskFactory.TaskType.
src/Build/Utilities/NuGetFrameworkWrapper.cs	Marks runtime load/reflection over NuGet.Frameworks as RUC.
src/Build/ObjectModelRemoting/DefinitionObjectsLinks/ProjectLink.cs	Marks remote evaluation/build helper APIs as RUC.
src/Build/Logging/LoggerDescription.cs	Marks reflective logger creation as RUC; adds delegate suppressions.
src/Build/Instance/TaskRegistry.cs	Marks reflective task factory loading/parameter reflection as RUC; adds suppressions for unrecognized reflection patterns.
src/Build/Instance/TaskFactories/AssemblyTaskFactory.cs	Marks assembly task factory type-loading paths as RUC; annotates TaskType.
src/Build/Instance/ProjectInstance.cs	Marks project instance constructors/build/evaluation-heavy entrypoints as RUC.
src/Build/Graph/ProjectGraph.cs	Marks project graph construction/evaluation entrypoints as RUC.
src/Build/Graph/ParallelWorkSet.cs	Replaces Lazy<TResult> with custom lazy work item to avoid IL2091.
src/Build/Graph/GraphBuildSubmission.cs	Marks cache-plugin initialization paths as RUC.
src/Build/Evaluation/IntrinsicFunctions.cs	Suppresses trim warning around Lazy factory calling RUC code.
src/Build/Evaluation/Expander.cs	Adds DAM annotations and suppressions around property-function reflection paths.
src/Build/Evaluation/Evaluator.cs	Marks evaluation/import expansion paths as RUC.
src/Build/Definition/ProjectCollection.cs	Adds RUC propagation and boundary suppressions around logger registration and project loading.
src/Build/Definition/Project.cs	Marks public project construction/evaluation/build entrypoints as RUC.
src/Build/Construction/Solution/SolutionProjectGenerator.cs	Marks solution evaluation/generation paths as RUC.
src/Build/BuildCheck/Infrastructure/NullBuildCheckManager.cs	Marks custom BuildCheck acquisition as RUC.
src/Build/BuildCheck/Infrastructure/IBuildCheckManager.cs	Adds RUC to custom BuildCheck acquisition contract.
src/Build/BuildCheck/Infrastructure/BuildCheckManagerProvider.cs	Marks custom check materialization/acquisition paths as RUC; adds suppression boundary.
src/Build/BuildCheck/Infrastructure/BuildCheckBuildEventHandler.cs	Adds suppression boundary on build-event handler invoking acquisition.
src/Build/BuildCheck/Acquisition/IBuildCheckAcquisitionModule.cs	Marks acquisition interface as RUC.
src/Build/BuildCheck/Acquisition/BuildCheckAcquisitionModule.cs	Marks acquisition implementation as RUC.
src/Build/BackEnd/TaskExecutionHost/TaskExecutionHost.cs	Adds RUC propagation and AOT-friendly array creation for task parameters.
src/Build/BackEnd/Shared/BuildRequestConfiguration.cs	Marks project load/eval into configuration as RUC.
src/Build/BackEnd/Node/OutOfProcNode.cs	Adds message-pump suppression boundary; propagates RUC into request handling.
src/Build/BackEnd/Node/InProcNode.cs	Adds message-pump suppression boundary; propagates RUC into request handling.
src/Build/BackEnd/Components/SdkResolution/SdkResolverService.cs	Marks SDK resolution (runtime resolver load/reflection) as RUC.
src/Build/BackEnd/Components/SdkResolution/SdkResolverLoader.cs	Marks SDK resolver discovery/loading/reflection as RUC.
src/Build/BackEnd/Components/SdkResolution/OutOfProcNodeSdkResolverService.cs	Propagates RUC to out-of-proc resolver service.
src/Build/BackEnd/Components/SdkResolution/MainNodeSdkResolverService.cs	Adds suppression boundary in packet handler; propagates RUC to ResolveSdk.
src/Build/BackEnd/Components/SdkResolution/ISdkResolverService.cs	Adds RUC to SDK resolver service contract.
src/Build/BackEnd/Components/SdkResolution/HostedSdkResolverServiceBase.cs	Adds RUC to hosted resolver service base contract.
src/Build/BackEnd/Components/SdkResolution/CachingSdkResolverService.cs	Propagates RUC to caching wrapper.
src/Build/BackEnd/Components/SdkResolution/CachingSdkResolverLoader.cs	Propagates RUC to caching loader overrides.
src/Build/BackEnd/Components/RequestBuilder/TaskHost.cs	Adds suppression boundary for public task-callback contract; propagates RUC into internal build entrypoints.
src/Build/BackEnd/Components/RequestBuilder/TaskBuilder.cs	Propagates RUC to task execution pipeline methods.
src/Build/BackEnd/Components/RequestBuilder/TargetEntry.cs	Propagates RUC to target execution pipeline methods.
src/Build/BackEnd/Components/RequestBuilder/TargetBuilder.cs	Propagates RUC to target build/callback methods.
src/Build/BackEnd/Components/RequestBuilder/RequestBuilder.cs	Propagates RUC through request builder thread/pump paths.
src/Build/BackEnd/Components/RequestBuilder/ITaskBuilder.cs	Adds RUC to task-builder contract.
src/Build/BackEnd/Components/RequestBuilder/ITargetBuilderCallback.cs	Adds RUC to target-builder callback contract.
src/Build/BackEnd/Components/RequestBuilder/ITargetBuilder.cs	Adds RUC to target-builder contract.
src/Build/BackEnd/Components/RequestBuilder/IRequestBuilderCallback.cs	Adds RUC to request-builder callback contract.
src/Build/BackEnd/Components/RequestBuilder/IRequestBuilder.cs	Adds RUC to request-builder contract.
src/Build/BackEnd/Components/RequestBuilder/IntrinsicTasks/MSBuild.cs	Adds suppression boundary for intrinsic-task reflective execution wall.
src/Build/BackEnd/Components/RequestBuilder/IntrinsicTasks/IntrinsicTaskFactory.cs	Adds DAM annotations to intrinsic task factory TaskType.
src/Build/BackEnd/Components/ProjectCache/ProjectCacheService.cs	Marks plugin loading/reflection/materialization as RUC; adds DAM for ctor activation.
src/Build/BackEnd/Components/Logging/LoggingService.cs	Removes reflection for in-box forwarding logger; factors core registration helper; adds RUC to reflective entrypoints.
src/Build/BackEnd/Components/Logging/ILoggingService.cs	Adds RUC to distributed logger registration / node logger init contracts.
src/Build/BackEnd/Components/Logging/BuildErrorTelemetryTracker.cs	Replaces enum-values reflection with constant-length array sizing.
src/Build/BackEnd/Components/BuildRequestEngine/IBuildRequestEngine.cs	Adds RUC to engine contract entrypoints.
src/Build/BackEnd/Components/BuildRequestEngine/BuildRequestEngine.cs	Propagates RUC into engine implementation; adds suppression boundaries for event handlers.
src/Build/BackEnd/BuildManager/BuildSubmission.cs	Propagates RUC through submission execution entrypoints.
src/Build/BackEnd/BuildManager/BuildManager.cs	Propagates RUC through build lifecycle and packet processing entrypoints; adds message-pump suppression boundary.

[github-actions]

Design Before Implementation — ISSUE
SEVERITY: MAJOR
FILE: src/Build/BackEnd/Components/Logging/BuildErrorTelemetryTracker.cs
LINES: 39 (the _errorCounts initializer)
SCENARIO: A developer adds a new ErrorCategory value after Other — e.g., ErrorCategory.Security at ordinal 16. (int)ErrorCategory.Other + 1 remains 16 (array indices 0–15). TrackError calls Interlocked.Increment(ref _errorCounts[(int)ErrorCategory.Security]) which dereferences _errorCounts[16] → IndexOutOfRangeException at runtime. There is nothing in the code that enforces the "Other is always last" invariant, so this is a silent time bomb for the next contributor who extends the enum.
FINDING: The replacement of Enum.GetValues(typeof(ErrorCategory)).Length with (int)ErrorCategory.Other + 1 avoids the reflection/trimming warning but introduces a fragile positional assumption that is not machine-checkable. The original code was self-maintaining; the new code is not.
RECOMMENDATION: Use the trim-safe generic overload Enum.GetValues<ErrorCategory>().Length (available since .NET 5, annotated only with [RequiresDynamicCode], not [RequiresUnreferencedCode], so it does not trigger IL2026). Add a #if NET guard for the .NET Framework build path (Enum.GetValues(typeof(ErrorCategory)).Length). Alternatively, add a sentinel Count member at the end of the enum and use new int[(int)ErrorCategory.Count] — that is the classic pattern to make array sizing both AOT-safe and self-maintaining.

---

All other evaluated dimensions are clean:

• WorkItem class (ParallelWorkSet.cs): The explicit comment correctly explains why Lazy<T> is unsuitable (its [DynamicallyAccessedMembers] annotation on T propagates to ParallelWorkSet<TKey, TResult> and produces IL2091). The documented single-writer / happens-before model makes the lock-free Value getter sound. LGTM.
• RegisterDistributedLoggerCore extraction (LoggingService.cs): Both call sites hold _lockObject before entering Core, so all shared mutable state is properly guarded. The extraction cleanly separates the reflection-free fast path (RegisterLogger with a pre-instantiated CentralForwardingLogger) from the reflection path. LGTM.
• ReflectableTaskPropertyInfo.cs manual loop: The change from GetProperty(..., BindingFlags.IgnoreCase) (which required NonPublicProperties in the DAM annotation) to an explicit loop over GetProperties(PublicProperties) with OrdinalIgnoreCase is the correct trim-safe replacement. Using LINQ FirstOrDefault would be semantically equivalent but would allocate an enumerator; the manual loop is preferred on a property-lookup hot path. LGTM.
• Array.CreateInstanceFromArrayType (TaskParameter.cs, TaskExecutionHost.cs): Switching the switch arms to concrete array types (typeof(char[]) etc.) and using Array.CreateInstanceFromArrayType is exactly the right API for AOT-safe typed-array construction, with a correct #if NET fallback for .NET Framework. LGTM.

Warning

Firewall blocked 2 domains

The following domains were blocked by the firewall during workflow execution:

• dnceng.pkgs.visualstudio.com
• pkgs.dev.azure.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "dnceng.pkgs.visualstudio.com"
    - "pkgs.dev.azure.com"

See Network Configuration for more information.

Generated by Expert Code Review (on open) for issue #14064 · 5.7K AIC · ⌖ 12.4 AIC · ⊞ 30.1K ambient context

[Copilot]

Pull request overview

Copilot reviewed 120 out of 121 changed files in this pull request and generated 1 comment.

[JeremyKuhne]

Windows Core failure — investigation

TL;DR: The Windows Core failure is an unrelated flaky Coordinator IPC test, not a regression from this PR. Recommend re-running the leg.

What failed

• Build 1495736 reported Windows Core red with 1 error / 0 warnings.
• The compile itself succeeded (0 Warning(s), 0 Error(s)). The single error is a process-level test failure: MSBuild.Coordinator.UnitTests.exe [net472|x86] crashed/hung (the Tests tab shows 0 clean test failures — the runner died rather than reporting an assertion).
• Every other assembly passed, including Microsoft.Build.Engine.UnitTests on both net472 and net10.0.

Why it's unrelated to this PR

• MSBuild.Coordinator / MSBuild.Coordinator.UnitTests is entirely upstream code — none of it is touched by this branch (git log main..HEAD -- src/MSBuild.Coordinator* is empty), and the suite references none of the files changed here (BuildEnvironmentHelper, DotNetSdkPaths, TaskExecutionHost, etc.).
• This PR's changes are no-ops on net472 (the failing config): the new RuntimeFeature.IsDynamicCodeSupported / IL3050 guard is #if NET, and BuildEnvironmentHelper.TryFromSdkRoot reads AppContext.GetData("Microsoft.DotNet.Sdk.Root"), which is unset on net472 / SDK 10.0.300 and returns null.
• Linux Core and macOS Core passed because the Coordinator component is net472-only and doesn't run there.

Why it's flaky

• CoordinatorIntegration_Tests.ParallelBuilds_BothSucceedWithCoordinator spawns two parallel bootstrapped MSBuild processes over a named pipe with node-budget negotiation and 60s timeouts — inherently timing-sensitive under CI load.
• The suite is recent (Add MSBuild Coordinator for fair-share node allocation #13653) and already has known Windows flakiness (see [Flaky Test] Quarantine 5 flaky tests (Windows-only) #14197, "[Flaky Test] Quarantine 5 flaky tests (Windows-only)").

Recommendation

Re-run the Windows Core leg — no code change is warranted for this PR. If the Coordinator suite keeps flaking it may warrant an additional quarantine entry, but that's separate from this change.

[JeremyKuhne]

@ViktorHofer I've updated for merge conflicts and the AppContext SDK root that the SDK pushes.

[ViktorHofer]

How should we maintain that list of BuildInTasks? I assume we don't want to register ALL msbuild inbox tasks? https://github.com/dotnet/msbuild/blob/main/src/Tasks/Microsoft.Common.tasks

[ViktorHofer]

/review