Static web assets discovery only sees wwwroot content present at project evaluation time, not files written by a BeforeBuild/Build-hooked target

[Popl7]

Summary

A custom MSBuild target hooked at BeforeTargets="BeforeBuild" (or "Build") that writes a generated file straight into wwwroot — the common pattern taught by several real "add Tailwind/Sass/esbuild to ASP.NET Core" tutorials — can silently fail to get a route in the published static web assets endpoints manifest ({Project}.staticwebassets.endpoints.json), even though the file itself is written to disk correctly at the right path and size. Under MapStaticAssets() (added in .NET 9), that means the request 404s in production despite the asset existing.

Originally filed against dotnet/aspnetcore — full investigation, multiple real repro repos, and CI runs are there: dotnet/aspnetcore#68641. Filing here too since tracing it into the actual source landed in this repo, not aspnetcore.

Root cause (as far as traced)

ResolveProjectStaticWebAssets is the target responsible for turning wwwroot content into StaticWebAsset/manifest entries:

sdk/src/StaticWebAssetsSdk/Targets/Microsoft.NET.Sdk.StaticWebAssets.targets

Lines 768 to 812 in 7053edd

	<Target Name="ResolveProjectStaticWebAssets"
	Condition="'$(NoBuild)' != 'true'"
	BeforeTargets="AssignTargetPaths"
	DependsOnTargets="ResolveStaticWebAssetsConfiguration;UpdateExistingPackageStaticWebAssets;AssignLinkMetadata">
	<PropertyGroup>
	<_ResolveProjectStaticWebAssetsCachePath Condition="'$(StaticWebAssetsCacheDefineStaticWebAssetsEnabled)' == 'true'">$(_StaticWebAssetsManifestBase)rpswa.dswa.cache.json</_ResolveProjectStaticWebAssetsCachePath>
	</PropertyGroup>
	<DefineStaticWebAssets
	CandidateAssets="@(Content->Distinct())"
	FingerprintCandidates="$(StaticWebAssetsFingerprintContent)"
	FingerprintPatterns="@(StaticWebAssetFingerprintPattern)"
	RelativePathPattern="wwwroot/**"
	SourceType="Discovered"
	SourceId="$(PackageId)"
	ContentRoot="$(MSBuildProjectDirectory)\wwwroot\"
	BasePath="$(StaticWebAssetBasePath)"
	AssetMergeSource="$(StaticWebAssetMergeTarget)"
	CacheManifestPath="$(_ResolveProjectStaticWebAssetsCachePath)"
	StaticWebAssetGroupDefinitions="@(StaticWebAssetGroupDefinition)">
	<Output TaskParameter="Assets" ItemName="StaticWebAsset" />
	<Output TaskParameter="Assets" ItemName="_CurrentProjectStaticWebAsset" />
	</DefineStaticWebAssets>
	<DefineStaticWebAssetEndpoints
	CandidateAssets="@(_CurrentProjectStaticWebAsset)"
	ContentTypeMappings="@(StaticWebAssetContentTypeMapping)"
	AdditionalEndpointDefinitions="@(StaticWebAssetAdditionalEndpointDefinition)"
	>
	<Output TaskParameter="Endpoints" ItemName="StaticWebAssetEndpoint" />
	</DefineStaticWebAssetEndpoints>
	<ItemGroup>
	<StaticWebAssetDiscoveryPattern Include="$(PackageId)\wwwroot" Condition="Exists('$(MSBuildProjectDirectory)\wwwroot')">
	<Source>$(PackageId)</Source>
	<BasePath>$(StaticWebAssetBasePath)</BasePath>
	<ContentRoot>$(MSBuildProjectDirectory)\wwwroot\</ContentRoot>
	<Pattern>**</Pattern>
	</StaticWebAssetDiscoveryPattern>
	<Content Remove="@(StaticWebAsset)" />
	<FileWrites Include="$(_ResolveProjectStaticWebAssetsCachePath)" />

<Target Name="ResolveProjectStaticWebAssets"
  Condition="'$(NoBuild)' != 'true'"
  BeforeTargets="AssignTargetPaths"
  DependsOnTargets="ResolveStaticWebAssetsConfiguration;UpdateExistingPackageStaticWebAssets;AssignLinkMetadata">
  ...
  <DefineStaticWebAssets
    CandidateAssets="@(Content->Distinct())"
    ...
    RelativePathPattern="wwwroot/**"
    SourceType="Discovered"
    ...

CandidateAssets="@(Content->Distinct())" — this target doesn't scan the filesystem itself. It filters whatever's already in the Content item collection at the point it runs, down to wwwroot/**. That collection is populated by the SDK's default-item globs at project evaluation time, once, before any target executes. A plain file write from a BeforeBuild/Build-hooked target's Exec (or any task) never touches the Content item collection — it just puts a file on disk. ResolveProjectStaticWebAssets never re-scans disk to notice it.

Two things get a generated file into the manifest correctly:

1. It was already on disk when the project was evaluated. Confirmed this exactly: two real example repos (dune-ui/blog-posts, khalidabuhakmeh/TailwindAspNetCore) happen to commit their generated CSS to git rather than gitignoring it, and that alone is what avoids the bug — removing that one committed file and rebuilding from a genuinely fresh checkout reproduces it immediately, 3/3 local + confirmed on GitHub Actions.
2. An explicit <ItemGroup><Content Include=".." Link="wwwroot/.." /></ItemGroup> inside the generating target — the pattern from Microsoft's own Razor Class Library client assets guidance. This is the fix that's held up in every test.

Minimal repro

https://github.com/Popl7/essessay-tailwind-manifest-repro — several branches isolating variables one at a time:

• main — original Tailwind CLI, BeforeTargets="BeforeBuild"
• no-external-process-repro — same bug with a trivial in-process WriteLinesToFile, no Tailwind, no external process at all
• tutorial-pattern-repro — the literal shape real tutorials teach (BeforeTargets="Build")
• dotnet8-repro / dotnet9-repro / dotnet11-repro — same underlying discovery gap exists on .NET 8 too (confirmed via obj/**/staticwebassets.build.json), but is only user-visible from .NET 9 onward since UseStaticFiles() (pre-MapStaticAssets()) never consults that manifest for a plain app's own assets
• official-pattern-repro — the Content/Link fix, confirmed working

Each has a GitHub Actions workflow (workflow_dispatch) that builds with --no-cache and checks both the manifest and the actual HTTP response.

What's still unexplained

The committed-vs-gitignored mechanism above is fully confirmed. What I haven't traced into the source: from-scratch minimal repros with no pre-existing file on either side reproduce 100% reliably on GitHub Actions/Render, but never reproduce on local Docker Desktop (macOS, arm64 and amd64-emulated, under various CPU/memory constraints) — same commit, same Dockerfile, same single dotnet publish invocation. Given Content is fixed at evaluation time either way, I'd naively expect this to be fully deterministic (always missing) once there's genuinely no pre-existing file — but it isn't, it's environment-dependent. Something after this point (possibly in Publish's own separate resolution pass, or an evaluation-cache detail) must be doing something I haven't found. Flagging in case it's a useful thread for someone closer to this code.

Happy to provide binlogs from a passing and a failing build if that would help narrow it down.

[Popl7]

Related: #52301 describes the same underlying mechanism from a different entry point — Microsoft.TypeScript.MSBuild's Compile-phase output not being discovered because it doesn't exist yet when ResolveProjectStaticWebAssets filters @(Content) for wwwroot/**. Same root cause (Content items are fixed at project-evaluation time; a later build phase's output never gets added to that collection unless something explicitly re-adds it), same fix shape (an explicit Content item registered after generation, mirroring the JSModules/ScopedCss pattern #52301 proposes for TypeScript specifically).

This issue is the general case: any custom target following the common "add Tailwind/Sass/esbuild to ASP.NET Core" pattern hits the same thing, not just the official TypeScript integration — see the repro links and the two real third-party example repos confirmed broken above. Cross-linking so anyone triaging either sees the other; not proposing to merge them, since #52301 is scoped to a specific first-party integration and this one covers the general pattern plus some additional findings (the committed-vs-gitignored mechanism, and the still-unexplained local-vs-CI environment split) that are outside its scope.

[Popl7]

Looked at what a fix could actually look like, and put together a build-time diagnostic that's now validated as both a true positive and a true negative, under a real dotnet publish (not just dotnet build):

<UsingTask TaskName="WarnUndiscoveredWwwrootFiles" TaskFactory="RoslynCodeTaskFactory" AssemblyFile="$(MSBuildToolsPath)/Microsoft.Build.Tasks.Core.dll">
    <ParameterGroup>
        <PhysicalFiles ParameterType="Microsoft.Build.Framework.ITaskItem[]" Required="true" />
        <DiscoveredIdentities ParameterType="System.String[]" Required="true" />
    </ParameterGroup>
    <Task>
        <Using Namespace="System.IO" />
        <Using Namespace="System.Linq" />
        <Code Type="Fragment" Language="cs"><![CDATA[
            var discovered = new HashSet<string>(
                (DiscoveredIdentities ?? new string[0]).Select(p => Path.GetFullPath(p)),
                StringComparer.OrdinalIgnoreCase);
            foreach (var item in PhysicalFiles)
            {
                var full = Path.GetFullPath(item.ItemSpec);
                if (!discovered.Contains(full))
                {
                    Log.LogWarning("SWA001", null, null, null, 0, 0, 0, 0,
                        "wwwroot file '{0}' exists on disk but was never discovered as a static web asset — " +
                        "MapStaticAssets() will 404 it. If a build target generates this file, register it " +
                        "explicitly, e.g. <Content Include=\"...\" Link=\"wwwroot/...\" /> instead of writing " +
                        "straight into wwwroot. See https://github.com/dotnet/sdk/issues/55883",
                        item.ItemSpec);
                }
            }
        ]]></Code>
    </Task>
</UsingTask>

<Target Name="WarnAboutUndiscoveredWwwrootFiles" AfterTargets="Build" Condition="Exists('wwwroot')">
    <ItemGroup>
        <_PhysicalWwwrootFile Include="wwwroot/**" />
    </ItemGroup>
    <WarnUndiscoveredWwwrootFiles
        PhysicalFiles="@(_PhysicalWwwrootFile)"
        DiscoveredIdentities="@(StaticWebAsset->'%(Identity)')" />
</Target>

Key design points:

• Compares against @(StaticWebAsset)'s Identity metadata, not RelativePath — RelativePath is a fingerprint pattern like favicon#[.{fingerprint}]?.ico, not a literal path, so it's useless for a direct comparison. Identity is the real physical path each discovered asset actually points at.
• Runs AfterTargets="Build", i.e. as late as reasonably possible — after any BeforeBuild/Build-hooked generator has had its chance to write output, so it sees the final on-disk state.
• Anything left in wwwroot/** with no matching Identity is exactly this bug's signature: on disk, invisible to MapStaticAssets().

Validated with two independent branches on the repro repo:

• True negative: applied to the working (Content/Link) fix — stays silent, correctly does not flag the legitimate, git-tracked favicon.ico (an earlier version of this diagnostic compared against RelativePath and got that wrong before I found the Identity metadata issue). https://github.com/Popl7/essessay-tailwind-manifest-repro/tree/proposed-diagnostic-fix — CI: https://github.com/Popl7/essessay-tailwind-manifest-repro/actions/runs/32347290709
• True positive: the identical block, unchanged, applied to the known-broken variant — fires exactly once, on exactly the broken file, correlated with the actual missing manifest route. https://github.com/Popl7/essessay-tailwind-manifest-repro/tree/proposed-diagnostic-fix-negative-test — CI: https://github.com/Popl7/essessay-tailwind-manifest-repro/actions/runs/32347608107

  SWA001 warning : wwwroot file 'wwwroot/css/site.css' exists on disk but was never discovered as a static web asset...
  SWA001 occurrences: 1
  PASS: fired exactly once, on exactly the broken file
  PASS: manifest route missing too, correlating with the SWA001 warning
  

Also tested and ruled out a tempting-looking alternative: hooking BeforeTargets="ResolveProjectStaticWebAssets" directly (a guaranteed MSBuild dependency edge, rather than being an unordered sibling of it via BeforeTargets="AssignTargetPaths") — without a Content item. Still broken, reliably, both locally and on CI: https://github.com/Popl7/essessay-tailwind-manifest-repro/tree/resolve-target-direct-hook. Confirms ordering was never the deciding factor, so a "fix" that just makes ordering deterministic wouldn't actually help — only explicit Content registration (or a real filesystem re-scan, which is a much bigger change) does.

This is offered as:

1. A drop-in-today workaround — anyone hitting this can add the block above to get a build warning instead of a silent production 404.
2. A concrete starting point for what a real, built-in check could look like, if that's of interest — the RoslynCodeTaskFactory version is obviously not how it'd want to ship in the SDK itself, but the comparison logic (physical wwwroot/** vs. StaticWebAsset.Identity, checked late) seems like it'd translate directly into a proper C# task.

Happy to open a PR with a "real" (non-inline-task) version of this if there's interest.

[Popl7]

Took a shot at implementing the diagnostic properly against this repo's conventions, in case it's useful as a starting point. Full patch at the bottom; happy to open a PR if the approach and the open questions below look right.

Two deliberate changes from the sketch I posted on the aspnetcore issue, based on what the code here actually does:

• No diagnostic code. There's no code scheme anywhere in src/StaticWebAssetsSdk/Tasks — every Log.LogWarning/LogError is a plain string — so inventing an SWA#### prefix would have been a new pattern for this area. Downside: no code means no NoWarn, only the opt-out property. Flagging that as a real tradeoff rather than a clear win; if you'd rather have a code, that's an easy change.
• Compares StaticWebAsset.Identity, plus a route check against @(StaticWebAssetEndpoint). RelativePath is a fingerprint pattern (favicon#[.{fingerprint}]?.ico), not a literal path, so it can't be compared directly — my first sketch used it and produced a false positive on a legitimate favicon.ico. The endpoint-route check is what makes "generate into obj, link into the web root, and also leave a copy in the web root" stay quiet: that copy is shadowed, not missing, so warning "will not be served" there would be factually wrong.

ValidateWebRootFileDiscovery

Follows the local conventions: [MSBuildMultiThreadableTask] + IMultiThreadableTask with TaskEnvironment, #nullable disable, file-scoped namespace, strongly-typed StaticWebAsset/StaticWebAssetEndpoint at the boundary, OSPath.PathComparer for path-keyed sets, and WebRootFiles passed in as an item rather than doing IO in the task (same shape as the legacy ValidateStaticWebAssetsUniquePaths), which keeps it unit-testable.

Targets wiring

@@ -814,6 +820,34 @@ Copyright (c) .NET Foundation. All rights reserved.
 
   </Target>
 
+  <!-- The assets for the project are discovered from the Content items the project defines, and those are
+       determined when the project is evaluated. A target that writes a file into the web root while the
+       build is running does not add anything to Content, so the file ends up on disk without becoming an
+       asset and is not served at runtime, with nothing in the build pointing that out. This runs once the
+       build has produced its final web root contents and reports those files. -->
+  <Target Name="ValidateStaticWebAssetsDiscovery"
+          AfterTargets="Build"
+          Condition="'$(StaticWebAssetsWarnOnUndiscoveredWebRootFiles)' == 'true' And Exists('$(MSBuildProjectDirectory)\wwwroot')">
+
+    <!-- Globbed here rather than in an item outside a target so that it reflects the contents of the web
+         root as they are once the build is done, instead of as they were when the project was evaluated. -->
+    <ItemGroup>
+      <_WebRootFileOnDisk Include="$(MSBuildProjectDirectory)\wwwroot\**" />
+    </ItemGroup>
+
+    <ValidateWebRootFileDiscovery
+      WebRootFiles="@(_WebRootFileOnDisk)"
+      Assets="@(StaticWebAsset)"
+      Endpoints="@(StaticWebAssetEndpoint)"
+      WebRoot="$(MSBuildProjectDirectory)\wwwroot\"
+      BasePath="$(StaticWebAssetBasePath)" />
+
+    <ItemGroup>
+      <_WebRootFileOnDisk Remove="@(_WebRootFileOnDisk)" />
+    </ItemGroup>
+
+  </Target>
+
   <Target Name="ReadPackageStaticWebAssetManifests"
           DependsOnTargets="UpdateExistingPackageStaticWebAssets"
           Condition="'@(StaticWebAssetPackageManifest)' != ''">

Globbing inside the target is the point — an item outside one would capture the web root as it was at evaluation, which is exactly the state that misses the file.

Verification

• Task builds clean, 0 warnings, both TFMs (net11.0 and net472).
• 7 new unit tests, all passing:
  WebRootFileWithoutAsset_Warns, WebRootFileWithMatchingAsset_DoesNotWarn, WebRootFileServedByAnotherAsset_DoesNotWarn, WebRootFileServedUnderBasePath_DoesNotWarn, FileOutsideWebRoot_DoesNotWarn, NoWebRootFiles_DoesNotWarn, MultipleUndiscoveredFiles_WarnsForEach
• No regressions, measured rather than assumed: stashed the change, rebuilt, re-ran --filter "FullyQualifiedName!~IntegrationTest" → 737 total / 71 failed. With the change → 744 total / 71 failed. Exactly +7 tests, +7 passing, identical failure set. (Those 71 are pre-existing in my environment — they need the full ./build.sh test-asset layout, which I didn't bootstrap.)
• End-to-end against a real SDK, by patching the built task and targets into .dotnet/sdk/11.0.100-preview.6.../Sdks/Microsoft.NET.Sdk.StaticWebAssets:

Scenario	Expected	Result
BeforeBuild target writes into wwwroot, fresh build	warn	warned
Same, but the file already existed at evaluation (so no bug)	silent	silent
Generate into obj + <Content Include Link>	silent	silent
Same, plus a stale copy left in wwwroot	silent	silent

The second row is the useful self-check: it goes quiet in exactly the case where a committed/pre-existing generated file makes the bug not happen, which is why the two third-party sample repos I looked at earlier never hit this.

Open questions for you

1. Default-on. It's true by default here, since a silent 404 is the whole problem, but that can turn existing green builds red under TreatWarningsAsErrors. Opt-in for one release may be the safer call — your judgement.
2. No integration test. I didn't add one: that suite doesn't run in my environment without a full ./build.sh, and I'd rather not contribute a test I haven't executed. Happy to add one if you point me at the right test asset to extend.
3. Overlap with Add Static Web Assets integration for Microsoft.TypeScript.MSBuild NuGet package #52301. That issue proposes a TypeScript-specific integration for the same root cause. This is the general case and doesn't conflict, but if a general "re-register late-generated content" mechanism is planned there, this warning may be better as a stopgap than a permanent feature.

Full patch (git am-able)

From efc751a2d8f75e873c5900903d08a18ee1df6f85 Mon Sep 17 00:00:00 2001
From: Steven Thonus <steven@infi.nl>
Date: Thu, 20 Aug 2026 10:51:46 +0200
Subject: [PATCH] Warn when a web root file is not discovered as a static web
 asset

Static web assets are discovered from the Content items a project defines,
which are determined when the project is evaluated. A target that writes a
file into the web root while the build is running does not add anything to
Content, so the file lands on disk but never becomes an asset and is not
served at runtime.

Nothing fails in that case, which is what makes it hard to find: the file is
exactly where its author expects it to be, the build succeeds, and only
requests for it fail. It is a common shape for build-time asset generation
(a bundler hooked before Build writing straight into wwwroot), and it became
user visible when MapStaticAssets started serving a plain application's own
assets from the endpoints manifest.

Add a ValidateWebRootFileDiscovery task that runs once the build has produced
its final web root contents and reports the files in it that no asset points
at. Files whose path is already served by another asset are not reported, so
generating into the intermediate output path and linking the result into the
web root stays quiet even when a copy is left in the web root as well. The
check is opt-out through StaticWebAssetsWarnOnUndiscoveredWebRootFiles.
---
 .../Microsoft.NET.Sdk.StaticWebAssets.targets |  34 ++++
 .../Tasks/ValidateWebRootFileDiscovery.cs     | 175 ++++++++++++++++
 .../ValidateWebRootFileDiscoveryTest.cs       | 189 ++++++++++++++++++
 3 files changed, 398 insertions(+)
 create mode 100644 src/StaticWebAssetsSdk/Tasks/ValidateWebRootFileDiscovery.cs
 create mode 100644 test/Microsoft.NET.Sdk.StaticWebAssets.Tests/StaticWebAssets/ValidateWebRootFileDiscoveryTest.cs

diff --git a/src/StaticWebAssetsSdk/Targets/Microsoft.NET.Sdk.StaticWebAssets.targets b/src/StaticWebAssetsSdk/Targets/Microsoft.NET.Sdk.StaticWebAssets.targets
index 5956ae0470..5ef3cd9b98 100644
--- a/src/StaticWebAssetsSdk/Targets/Microsoft.NET.Sdk.StaticWebAssets.targets
+++ b/src/StaticWebAssetsSdk/Targets/Microsoft.NET.Sdk.StaticWebAssets.targets
@@ -132,6 +132,11 @@ Copyright (c) .NET Foundation. All rights reserved.
     AssemblyFile="$(StaticWebAssetsSdkBuildTasksAssembly)"
     Condition="'$(StaticWebAssetsSdkBuildTasksAssembly)' != ''" />
 
+  <UsingTask
+    TaskName="Microsoft.AspNetCore.StaticWebAssets.Tasks.ValidateWebRootFileDiscovery"
+    AssemblyFile="$(StaticWebAssetsSdkBuildTasksAssembly)"
+    Condition="'$(StaticWebAssetsSdkBuildTasksAssembly)' != ''" />
+
   <!-- Static web assets define how web content needs to be served from web applications, class libraries and packages during
        development and what and where web contents need to be served on the published application.
 
@@ -454,6 +459,7 @@ Copyright (c) .NET Foundation. All rights reserved.
       <StaticWebAssetMergeTarget Condition="'$(TargetFrameworks)' != '' and '$(TargetPlatformIdentifier)' == ''">Server</StaticWebAssetMergeTarget>
       <StaticWebAssetsCacheDefineStaticWebAssetsEnabled Condition="'$(StaticWebAssetsCacheDefineStaticWebAssetsEnabled)' == ''">true</StaticWebAssetsCacheDefineStaticWebAssetsEnabled>
       <StaticWebAssetDefaultDocumentEnabled Condition="'$(StaticWebAssetDefaultDocumentEnabled)' == ''">false</StaticWebAssetDefaultDocumentEnabled>
+      <StaticWebAssetsWarnOnUndiscoveredWebRootFiles Condition="'$(StaticWebAssetsWarnOnUndiscoveredWebRootFiles)' == ''">true</StaticWebAssetsWarnOnUndiscoveredWebRootFiles>
       <StaticWebAssetSpaFallbackEnabled Condition="'$(StaticWebAssetSpaFallbackEnabled)' == ''">false</StaticWebAssetSpaFallbackEnabled>
 
       <!-- Manifest paths -->
@@ -814,6 +820,34 @@ Copyright (c) .NET Foundation. All rights reserved.
 
   </Target>
 
+  <!-- The assets for the project are discovered from the Content items the project defines, and those are
+       determined when the project is evaluated. A target that writes a file into the web root while the
+       build is running does not add anything to Content, so the file ends up on disk without becoming an
+       asset and is not served at runtime, with nothing in the build pointing that out. This runs once the
+       build has produced its final web root contents and reports those files. -->
+  <Target Name="ValidateStaticWebAssetsDiscovery"
+          AfterTargets="Build"
+          Condition="'$(StaticWebAssetsWarnOnUndiscoveredWebRootFiles)' == 'true' And Exists('$(MSBuildProjectDirectory)\wwwroot')">
+
+    <!-- Globbed here rather than in an item outside a target so that it reflects the contents of the web
+         root as they are once the build is done, instead of as they were when the project was evaluated. -->
+    <ItemGroup>
+      <_WebRootFileOnDisk Include="$(MSBuildProjectDirectory)\wwwroot\**" />
+    </ItemGroup>
+
+    <ValidateWebRootFileDiscovery
+      WebRootFiles="@(_WebRootFileOnDisk)"
+      Assets="@(StaticWebAsset)"
+      Endpoints="@(StaticWebAssetEndpoint)"
+      WebRoot="$(MSBuildProjectDirectory)\wwwroot\"
+      BasePath="$(StaticWebAssetBasePath)" />
+
+    <ItemGroup>
+      <_WebRootFileOnDisk Remove="@(_WebRootFileOnDisk)" />
+    </ItemGroup>
+
+  </Target>
+
   <Target Name="ReadPackageStaticWebAssetManifests"
           DependsOnTargets="UpdateExistingPackageStaticWebAssets"
           Condition="'@(StaticWebAssetPackageManifest)' != ''">
diff --git a/src/StaticWebAssetsSdk/Tasks/ValidateWebRootFileDiscovery.cs b/src/StaticWebAssetsSdk/Tasks/ValidateWebRootFileDiscovery.cs
new file mode 100644
index 0000000000..81ea16ad50
--- /dev/null
+++ b/src/StaticWebAssetsSdk/Tasks/ValidateWebRootFileDiscovery.cs
@@ -0,0 +1,175 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+#nullable disable
+
+using Microsoft.AspNetCore.StaticWebAssets.Tasks.Utils;
+using Microsoft.Build.Framework;
+
+namespace Microsoft.AspNetCore.StaticWebAssets.Tasks;
+
+/// <summary>
+/// Reports files that are present in the project web root on disk but that are not part of the set of
+/// static web assets, and whose path is not served by any other asset.
+/// </summary>
+/// <remarks>
+/// Static web assets are discovered from the <c>Content</c> items the project defines, which are
+/// determined when the project is evaluated. A target that writes a file directly into the web root
+/// while the build is running (for example a CSS or JavaScript bundler hooked before <c>Build</c>)
+/// does not add anything to <c>Content</c>, so the file lands on disk but never becomes an asset and
+/// is not served at runtime. Nothing fails in that case, which makes the problem hard to find: the
+/// file is where the author expects it to be, and only requests for it fail. This task runs once the
+/// build has produced its final web root contents and reports those files.
+/// </remarks>
+[MSBuildMultiThreadableTask]
+public class ValidateWebRootFileDiscovery : Task, IMultiThreadableTask
+{
+    /// <summary>
+    /// The files present in <see cref="WebRoot"/> on disk after the build has run.
+    /// </summary>
+    public ITaskItem[] WebRootFiles { get; set; }
+
+    /// <summary>
+    /// The static web assets resolved for the project.
+    /// </summary>
+    public ITaskItem[] Assets { get; set; }
+
+    /// <summary>
+    /// The endpoints resolved for <see cref="Assets"/>. Used to avoid reporting a web root file when an
+    /// asset defined somewhere else already serves the same path.
+    /// </summary>
+    public ITaskItem[] Endpoints { get; set; }
+
+    /// <summary>
+    /// The project web root, typically <c>$(MSBuildProjectDirectory)\wwwroot\</c>.
+    /// </summary>
+    [Required]
+    public string WebRoot { get; set; }
+
+    /// <summary>
+    /// The base path the project serves its assets from. Used to match <see cref="WebRootFiles"/> against
+    /// <see cref="Endpoints"/> for projects that are not served from the root of the application.
+    /// </summary>
+    public string BasePath { get; set; }
+
+    public TaskEnvironment TaskEnvironment { get; set; } = TaskEnvironment.Fallback;
+
+    public override bool Execute()
+    {
+        try
+        {
+            if (WebRootFiles == null || WebRootFiles.Length == 0)
+            {
+                return true;
+            }
+
+            var webRoot = NormalizeDirectory(Path.GetFullPath(TaskEnvironment.GetAbsolutePath(WebRoot)));
+            var assetPaths = GetAssetPaths();
+            var routes = GetRoutes();
+
+            foreach (var file in WebRootFiles)
+            {
+                var identity = Path.GetFullPath(TaskEnvironment.GetAbsolutePath(file.ItemSpec));
+                if (assetPaths.Contains(identity))
+                {
+                    continue;
+                }
+
+                if (!identity.StartsWith(webRoot, OSPath.PathComparison))
+                {
+                    // The file is not inside the web root we were given, so this task has nothing to say
+                    // about how it gets served.
+                    continue;
+                }
+
+                var relativePath = identity.Substring(webRoot.Length).Replace('\\', '/');
+                if (IsServedByAnotherAsset(routes, relativePath))
+                {
+                    // Another asset already serves this path, so the file on disk is shadowed rather than
+                    // missing. This happens when a build target writes its output to the intermediate
+                    // output path and links it into the web root, while a copy is also left on disk.
+                    Log.LogMessage(
+                        MessageImportance.Low,
+                        "Skipping web root file '{0}' because '{1}' is already served by another static web asset.",
+                        identity,
+                        relativePath);
+                    continue;
+                }
+
+                Log.LogWarning(
+                    "No static web asset was found for the web root file '{0}', so it will not be served at runtime. " +
+                    "Files created inside the web root after the project is evaluated, for example by a target that " +
+                    "runs before 'Build', are not discovered as static web assets. Add the file to the 'Content' items " +
+                    "from the target that produces it, for example " +
+                    "<Content Include=\"$(IntermediateOutputPath){1}\" Link=\"wwwroot/{1}\" />, or set " +
+                    "'StaticWebAssetsWarnOnUndiscoveredWebRootFiles' to 'false' to disable this check.",
+                    identity,
+                    relativePath);
+            }
+        }
+        catch (Exception ex)
+        {
+            Log.LogError(ex.Message);
+        }
+
+        return !Log.HasLoggedErrors;
+    }
+
+    private HashSet<string> GetAssetPaths()
+    {
+        var result = new HashSet<string>(OSPath.PathComparer);
+        if (Assets == null)
+        {
+            return result;
+        }
+
+        foreach (var item in Assets)
+        {
+            var asset = StaticWebAsset.FromTaskItem(item, TaskEnvironment);
+            if (!string.IsNullOrEmpty(asset.Identity))
+            {
+                result.Add(Path.GetFullPath(asset.Identity));
+            }
+        }
+
+        return result;
+    }
+
+    private HashSet<string> GetRoutes()
+    {
+        var result = new HashSet<string>(OSPath.PathComparer);
+        if (Endpoints == null)
+        {
+            return result;
+        }
+
+        foreach (var endpoint in StaticWebAssetEndpoint.FromItemGroup(Endpoints))
+        {
+            if (!string.IsNullOrEmpty(endpoint.Route))
+            {
+                result.Add(endpoint.Route.Replace('\\', '/').TrimStart('/'));
+            }
+        }
+
+        return result;
+    }
+
+    private bool IsServedByAnotherAsset(HashSet<string> routes, string relativePath)
+    {
+        if (routes.Contains(relativePath))
+        {
+            return true;
+        }
+
+        // Projects that are not served from the root of the application, class libraries for example,
+        // expose their web root under a base path, so the route does not match the path relative to the
+        // web root on its own.
+        var basePath = BasePath?.Replace('\\', '/').Trim('/');
+        return !string.IsNullOrEmpty(basePath) && routes.Contains($"{basePath}/{relativePath}");
+    }
+
+    private static string NormalizeDirectory(string path) =>
+        path.Length == 0 || path[path.Length - 1] == Path.DirectorySeparatorChar || path[path.Length - 1] == Path.AltDirectorySeparatorChar
+            ? path
+            : path + Path.DirectorySeparatorChar;
+}
diff --git a/test/Microsoft.NET.Sdk.StaticWebAssets.Tests/StaticWebAssets/ValidateWebRootFileDiscoveryTest.cs b/test/Microsoft.NET.Sdk.StaticWebAssets.Tests/StaticWebAssets/ValidateWebRootFileDiscoveryTest.cs
new file mode 100644
index 0000000000..275204b586
--- /dev/null
+++ b/test/Microsoft.NET.Sdk.StaticWebAssets.Tests/StaticWebAssets/ValidateWebRootFileDiscoveryTest.cs
@@ -0,0 +1,189 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+#nullable disable
+
+using Microsoft.Build.Framework;
+using Microsoft.Build.Utilities;
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+using Moq;
+
+namespace Microsoft.AspNetCore.StaticWebAssets.Tasks;
+
+[TestClass]
+public class ValidateWebRootFileDiscoveryTest : IDisposable
+{
+    private readonly string _tempDir;
+    private readonly string _webRoot;
+    private readonly Mock<IBuildEngine> _buildEngine;
+    private readonly List<string> _errorMessages;
+    private readonly List<string> _warningMessages;
+
+    public ValidateWebRootFileDiscoveryTest()
+    {
+        _tempDir = Path.Combine(Path.GetTempPath(), "ValidateWebRootFiles_" + Guid.NewGuid().ToString("N"));
+        _webRoot = Path.Combine(_tempDir, "wwwroot") + Path.DirectorySeparatorChar;
+        Directory.CreateDirectory(_webRoot);
+
+        _errorMessages = new List<string>();
+        _warningMessages = new List<string>();
+        _buildEngine = new Mock<IBuildEngine>();
+        _buildEngine.Setup(e => e.LogErrorEvent(It.IsAny<BuildErrorEventArgs>()))
+            .Callback<BuildErrorEventArgs>(args => _errorMessages.Add(args.Message));
+        _buildEngine.Setup(e => e.LogWarningEvent(It.IsAny<BuildWarningEventArgs>()))
+            .Callback<BuildWarningEventArgs>(args => _warningMessages.Add(args.Message));
+    }
+
+    public void Dispose()
+    {
+        if (Directory.Exists(_tempDir))
+        {
+            try { Directory.Delete(_tempDir, recursive: true); } catch { }
+        }
+    }
+
+    [TestMethod]
+    public void WebRootFileWithoutAsset_Warns()
+    {
+        var generated = CreateWebRootFile("css/site.css");
+
+        var task = CreateTask(webRootFiles: new[] { generated });
+
+        task.Execute().Should().BeTrue("the check reports a warning and does not fail the build");
+        _warningMessages.Should().ContainSingle()
+            .Which.Should().Contain("css/site.css");
+        _errorMessages.Should().BeEmpty();
+    }
+
+    [TestMethod]
+    public void WebRootFileWithMatchingAsset_DoesNotWarn()
+    {
+        var content = CreateWebRootFile("css/site.css");
+
+        var task = CreateTask(
+            webRootFiles: new[] { content },
+            assets: new[] { CreateAssetItem(content.ItemSpec, "css/site.css") });
+
+        task.Execute().Should().BeTrue();
+        _warningMessages.Should().BeEmpty();
+    }
+
+    [TestMethod]
+    public void WebRootFileServedByAnotherAsset_DoesNotWarn()
+    {
+        // A target generated the file under the intermediate output path and linked it into the web root,
+        // while a copy was also left in the web root itself. The route is served, so there is nothing to
+        // report for the copy on disk.
+        var staleCopy = CreateWebRootFile("css/site.css");
+        var generated = Path.Combine(_tempDir, "obj", "site.css");
+
+        var task = CreateTask(
+            webRootFiles: new[] { staleCopy },
+            assets: new[] { CreateAssetItem(generated, "css/site#[.{fingerprint}]?.css") },
+            endpoints: new[] { CreateEndpointItem("css/site.css", generated) });
+
+        task.Execute().Should().BeTrue();
+        _warningMessages.Should().BeEmpty();
+    }
+
+    [TestMethod]
+    public void WebRootFileServedUnderBasePath_DoesNotWarn()
+    {
+        // Class libraries serve their web root under a base path, so the route does not match the path
+        // relative to the web root on its own.
+        var staleCopy = CreateWebRootFile("css/site.css");
+        var generated = Path.Combine(_tempDir, "obj", "site.css");
+
+        var task = CreateTask(
+            webRootFiles: new[] { staleCopy },
+            assets: new[] { CreateAssetItem(generated, "css/site.css") },
+            endpoints: new[] { CreateEndpointItem("_content/MyLibrary/css/site.css", generated) },
+            basePath: "_content/MyLibrary");
+
+        task.Execute().Should().BeTrue();
+        _warningMessages.Should().BeEmpty();
+    }
+
+    [TestMethod]
+    public void FileOutsideWebRoot_DoesNotWarn()
+    {
+        var outside = new TaskItem(Path.Combine(_tempDir, "Styles", "app.css"));
+
+        var task = CreateTask(webRootFiles: new[] { outside });
+
+        task.Execute().Should().BeTrue();
+        _warningMessages.Should().BeEmpty();
+    }
+
+    [TestMethod]
+    public void NoWebRootFiles_DoesNotWarn()
+    {
+        var task = CreateTask(webRootFiles: Array.Empty<ITaskItem>());
+
+        task.Execute().Should().BeTrue();
+        _warningMessages.Should().BeEmpty();
+    }
+
+    [TestMethod]
+    public void MultipleUndiscoveredFiles_WarnsForEach()
+    {
+        var css = CreateWebRootFile("css/site.css");
+        var js = CreateWebRootFile("js/site.js");
+        var discovered = CreateWebRootFile("favicon.ico");
+
+        var task = CreateTask(
+            webRootFiles: new[] { css, js, discovered },
+            assets: new[] { CreateAssetItem(discovered.ItemSpec, "favicon.ico") });
+
+        task.Execute().Should().BeTrue();
+        _warningMessages.Should().HaveCount(2);
+        _warningMessages.Should().Contain(m => m.Contains("css/site.css"));
+        _warningMessages.Should().Contain(m => m.Contains("js/site.js"));
+        _warningMessages.Should().NotContain(m => m.Contains("favicon.ico"));
+    }
+
+    private ValidateWebRootFileDiscovery CreateTask(
+        ITaskItem[] webRootFiles,
+        ITaskItem[] assets = null,
+        ITaskItem[] endpoints = null,
+        string basePath = null) =>
+        new()
+        {
+            BuildEngine = _buildEngine.Object,
+            WebRootFiles = webRootFiles,
+            Assets = assets ?? Array.Empty<ITaskItem>(),
+            Endpoints = endpoints ?? Array.Empty<ITaskItem>(),
+            WebRoot = _webRoot,
+            BasePath = basePath,
+        };
+
+    private TaskItem CreateWebRootFile(string relativePath)
+    {
+        var path = Path.Combine(_webRoot, relativePath.Replace('/', Path.DirectorySeparatorChar));
+        Directory.CreateDirectory(Path.GetDirectoryName(path));
+        File.WriteAllText(path, "/* content */");
+        return new TaskItem(path);
+    }
+
+    private TaskItem CreateAssetItem(string identity, string relativePath)
+    {
+        var item = new TaskItem(identity);
+        item.SetMetadata(nameof(StaticWebAsset.SourceId), "MyProject");
+        item.SetMetadata(nameof(StaticWebAsset.SourceType), StaticWebAsset.SourceTypes.Discovered);
+        item.SetMetadata(nameof(StaticWebAsset.ContentRoot), _webRoot);
+        item.SetMetadata(nameof(StaticWebAsset.BasePath), "/");
+        item.SetMetadata(nameof(StaticWebAsset.RelativePath), relativePath);
+        item.SetMetadata(nameof(StaticWebAsset.AssetKind), StaticWebAsset.AssetKinds.All);
+        item.SetMetadata(nameof(StaticWebAsset.AssetMode), StaticWebAsset.AssetModes.All);
+        item.SetMetadata(nameof(StaticWebAsset.AssetRole), StaticWebAsset.AssetRoles.Primary);
+        item.SetMetadata(nameof(StaticWebAsset.OriginalItemSpec), identity);
+        return item;
+    }
+
+    private static TaskItem CreateEndpointItem(string route, string assetFile)
+    {
+        var item = new TaskItem(route);
+        item.SetMetadata(nameof(StaticWebAssetEndpoint.AssetFile), assetFile);
+        return item;
+    }
+}
-- 
2.50.1 (Apple Git-155)

[Popl7]

Correction to my previous comment: the "no integration test" caveat was wrong, and I've now added them.

I'd claimed that suite "doesn't run in my environment without a full ./build.sh". That was an assumption I never actually verified — I inferred it from a FileNotFoundException instead of reading what it was asking for. When I chased the real error it turned out to be two commands, not a full repo build:

System.IO.FileNotFoundException: Host '.../artifacts/bin/redist/Debug/dotnet/dotnet' not found.
Is 'redist.csproj' built?

./build.sh --restore                                    # 2m42s
./.dotnet/dotnet build src/Layout/redist/redist.csproj  # ~10 min, composes a real SDK

After that the existing integration tests run fine (verified StaticWebAssetsIntegrationTest.Build_GeneratesJsonManifestAndCopiesItToOutputFolder passes), and I confirmed the composed SDK at artifacts/bin/redist/Debug/dotnet/sdk/11.0.100-dev/Sdks/Microsoft.NET.Sdk.StaticWebAssets actually contains the new task and target, so these exercise the real thing rather than a stale copy.

Integration tests added

test/Microsoft.NET.Sdk.StaticWebAssets.Tests/StaticWebAssetsDiscoveryValidationIntegrationTest.cs, deriving from AspNetSdkTest (not the baseline base class, so no baselines to regenerate), using WithProjectChanges to inject the target into RazorComponentApp. All three pass through a real dotnet build:

Test	Asserts
Build_WarnsWhenATargetWritesAFileIntoTheWebRootWithoutRegisteringIt	warning is emitted
Build_DoesNotWarnWhenTheGeneratedFileIsRegisteredAsContent	$(IntermediateOutputPath) + <Content Link> stays quiet
Build_DoesNotWarnWhenTheCheckIsDisabled	StaticWebAssetsWarnOnUndiscoveredWebRootFiles=false silences it

They're mutually discriminating rather than all one-directional: a task that never warned would fail the first, one that always warned would fail the other two.

Still outstanding

The full suite run (unit + integration, ~750 tests each spawning real builds) is still in progress as I write this, so I'm deliberately not claiming a regression result yet — that's the number that actually matters for the default-on question, since this target now runs on every build in the test matrix. I'll follow up with it either way, including if it turns up problems.

The other two open questions from my previous comment stand unchanged: whether default-on is acceptable, and whether you'd prefer a real diagnostic code over following the local uncoded-warning convention (uncoded means NoWarn can't suppress it).

Updated full patch, both commits (git am-able)

From efc751a2d8f75e873c5900903d08a18ee1df6f85 Mon Sep 17 00:00:00 2001
From: Steven Thonus <steven@infi.nl>
Date: Thu, 20 Aug 2026 10:51:46 +0200
Subject: [PATCH 1/2] Warn when a web root file is not discovered as a static
 web asset

Static web assets are discovered from the Content items a project defines,
which are determined when the project is evaluated. A target that writes a
file into the web root while the build is running does not add anything to
Content, so the file lands on disk but never becomes an asset and is not
served at runtime.

Nothing fails in that case, which is what makes it hard to find: the file is
exactly where its author expects it to be, the build succeeds, and only
requests for it fail. It is a common shape for build-time asset generation
(a bundler hooked before Build writing straight into wwwroot), and it became
user visible when MapStaticAssets started serving a plain application's own
assets from the endpoints manifest.

Add a ValidateWebRootFileDiscovery task that runs once the build has produced
its final web root contents and reports the files in it that no asset points
at. Files whose path is already served by another asset are not reported, so
generating into the intermediate output path and linking the result into the
web root stays quiet even when a copy is left in the web root as well. The
check is opt-out through StaticWebAssetsWarnOnUndiscoveredWebRootFiles.
---
 .../Microsoft.NET.Sdk.StaticWebAssets.targets |  34 ++++
 .../Tasks/ValidateWebRootFileDiscovery.cs     | 175 ++++++++++++++++
 .../ValidateWebRootFileDiscoveryTest.cs       | 189 ++++++++++++++++++
 3 files changed, 398 insertions(+)
 create mode 100644 src/StaticWebAssetsSdk/Tasks/ValidateWebRootFileDiscovery.cs
 create mode 100644 test/Microsoft.NET.Sdk.StaticWebAssets.Tests/StaticWebAssets/ValidateWebRootFileDiscoveryTest.cs

diff --git a/src/StaticWebAssetsSdk/Targets/Microsoft.NET.Sdk.StaticWebAssets.targets b/src/StaticWebAssetsSdk/Targets/Microsoft.NET.Sdk.StaticWebAssets.targets
index 5956ae0470..5ef3cd9b98 100644
--- a/src/StaticWebAssetsSdk/Targets/Microsoft.NET.Sdk.StaticWebAssets.targets
+++ b/src/StaticWebAssetsSdk/Targets/Microsoft.NET.Sdk.StaticWebAssets.targets
@@ -132,6 +132,11 @@ Copyright (c) .NET Foundation. All rights reserved.
     AssemblyFile="$(StaticWebAssetsSdkBuildTasksAssembly)"
     Condition="'$(StaticWebAssetsSdkBuildTasksAssembly)' != ''" />
 
+  <UsingTask
+    TaskName="Microsoft.AspNetCore.StaticWebAssets.Tasks.ValidateWebRootFileDiscovery"
+    AssemblyFile="$(StaticWebAssetsSdkBuildTasksAssembly)"
+    Condition="'$(StaticWebAssetsSdkBuildTasksAssembly)' != ''" />
+
   <!-- Static web assets define how web content needs to be served from web applications, class libraries and packages during
        development and what and where web contents need to be served on the published application.
 
@@ -454,6 +459,7 @@ Copyright (c) .NET Foundation. All rights reserved.
       <StaticWebAssetMergeTarget Condition="'$(TargetFrameworks)' != '' and '$(TargetPlatformIdentifier)' == ''">Server</StaticWebAssetMergeTarget>
       <StaticWebAssetsCacheDefineStaticWebAssetsEnabled Condition="'$(StaticWebAssetsCacheDefineStaticWebAssetsEnabled)' == ''">true</StaticWebAssetsCacheDefineStaticWebAssetsEnabled>
       <StaticWebAssetDefaultDocumentEnabled Condition="'$(StaticWebAssetDefaultDocumentEnabled)' == ''">false</StaticWebAssetDefaultDocumentEnabled>
+      <StaticWebAssetsWarnOnUndiscoveredWebRootFiles Condition="'$(StaticWebAssetsWarnOnUndiscoveredWebRootFiles)' == ''">true</StaticWebAssetsWarnOnUndiscoveredWebRootFiles>
       <StaticWebAssetSpaFallbackEnabled Condition="'$(StaticWebAssetSpaFallbackEnabled)' == ''">false</StaticWebAssetSpaFallbackEnabled>
 
       <!-- Manifest paths -->
@@ -814,6 +820,34 @@ Copyright (c) .NET Foundation. All rights reserved.
 
   </Target>
 
+  <!-- The assets for the project are discovered from the Content items the project defines, and those are
+       determined when the project is evaluated. A target that writes a file into the web root while the
+       build is running does not add anything to Content, so the file ends up on disk without becoming an
+       asset and is not served at runtime, with nothing in the build pointing that out. This runs once the
+       build has produced its final web root contents and reports those files. -->
+  <Target Name="ValidateStaticWebAssetsDiscovery"
+          AfterTargets="Build"
+          Condition="'$(StaticWebAssetsWarnOnUndiscoveredWebRootFiles)' == 'true' And Exists('$(MSBuildProjectDirectory)\wwwroot')">
+
+    <!-- Globbed here rather than in an item outside a target so that it reflects the contents of the web
+         root as they are once the build is done, instead of as they were when the project was evaluated. -->
+    <ItemGroup>
+      <_WebRootFileOnDisk Include="$(MSBuildProjectDirectory)\wwwroot\**" />
+    </ItemGroup>
+
+    <ValidateWebRootFileDiscovery
+      WebRootFiles="@(_WebRootFileOnDisk)"
+      Assets="@(StaticWebAsset)"
+      Endpoints="@(StaticWebAssetEndpoint)"
+      WebRoot="$(MSBuildProjectDirectory)\wwwroot\"
+      BasePath="$(StaticWebAssetBasePath)" />
+
+    <ItemGroup>
+      <_WebRootFileOnDisk Remove="@(_WebRootFileOnDisk)" />
+    </ItemGroup>
+
+  </Target>
+
   <Target Name="ReadPackageStaticWebAssetManifests"
           DependsOnTargets="UpdateExistingPackageStaticWebAssets"
           Condition="'@(StaticWebAssetPackageManifest)' != ''">
diff --git a/src/StaticWebAssetsSdk/Tasks/ValidateWebRootFileDiscovery.cs b/src/StaticWebAssetsSdk/Tasks/ValidateWebRootFileDiscovery.cs
new file mode 100644
index 0000000000..81ea16ad50
--- /dev/null
+++ b/src/StaticWebAssetsSdk/Tasks/ValidateWebRootFileDiscovery.cs
@@ -0,0 +1,175 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+#nullable disable
+
+using Microsoft.AspNetCore.StaticWebAssets.Tasks.Utils;
+using Microsoft.Build.Framework;
+
+namespace Microsoft.AspNetCore.StaticWebAssets.Tasks;
+
+/// <summary>
+/// Reports files that are present in the project web root on disk but that are not part of the set of
+/// static web assets, and whose path is not served by any other asset.
+/// </summary>
+/// <remarks>
+/// Static web assets are discovered from the <c>Content</c> items the project defines, which are
+/// determined when the project is evaluated. A target that writes a file directly into the web root
+/// while the build is running (for example a CSS or JavaScript bundler hooked before <c>Build</c>)
+/// does not add anything to <c>Content</c>, so the file lands on disk but never becomes an asset and
+/// is not served at runtime. Nothing fails in that case, which makes the problem hard to find: the
+/// file is where the author expects it to be, and only requests for it fail. This task runs once the
+/// build has produced its final web root contents and reports those files.
+/// </remarks>
+[MSBuildMultiThreadableTask]
+public class ValidateWebRootFileDiscovery : Task, IMultiThreadableTask
+{
+    /// <summary>
+    /// The files present in <see cref="WebRoot"/> on disk after the build has run.
+    /// </summary>
+    public ITaskItem[] WebRootFiles { get; set; }
+
+    /// <summary>
+    /// The static web assets resolved for the project.
+    /// </summary>
+    public ITaskItem[] Assets { get; set; }
+
+    /// <summary>
+    /// The endpoints resolved for <see cref="Assets"/>. Used to avoid reporting a web root file when an
+    /// asset defined somewhere else already serves the same path.
+    /// </summary>
+    public ITaskItem[] Endpoints { get; set; }
+
+    /// <summary>
+    /// The project web root, typically <c>$(MSBuildProjectDirectory)\wwwroot\</c>.
+    /// </summary>
+    [Required]
+    public string WebRoot { get; set; }
+
+    /// <summary>
+    /// The base path the project serves its assets from. Used to match <see cref="WebRootFiles"/> against
+    /// <see cref="Endpoints"/> for projects that are not served from the root of the application.
+    /// </summary>
+    public string BasePath { get; set; }
+
+    public TaskEnvironment TaskEnvironment { get; set; } = TaskEnvironment.Fallback;
+
+    public override bool Execute()
+    {
+        try
+        {
+            if (WebRootFiles == null || WebRootFiles.Length == 0)
+            {
+                return true;
+            }
+
+            var webRoot = NormalizeDirectory(Path.GetFullPath(TaskEnvironment.GetAbsolutePath(WebRoot)));
+            var assetPaths = GetAssetPaths();
+            var routes = GetRoutes();
+
+            foreach (var file in WebRootFiles)
+            {
+                var identity = Path.GetFullPath(TaskEnvironment.GetAbsolutePath(file.ItemSpec));
+                if (assetPaths.Contains(identity))
+                {
+                    continue;
+                }
+
+                if (!identity.StartsWith(webRoot, OSPath.PathComparison))
+                {
+                    // The file is not inside the web root we were given, so this task has nothing to say
+                    // about how it gets served.
+                    continue;
+                }
+
+                var relativePath = identity.Substring(webRoot.Length).Replace('\\', '/');
+                if (IsServedByAnotherAsset(routes, relativePath))
+                {
+                    // Another asset already serves this path, so the file on disk is shadowed rather than
+                    // missing. This happens when a build target writes its output to the intermediate
+                    // output path and links it into the web root, while a copy is also left on disk.
+                    Log.LogMessage(
+                        MessageImportance.Low,
+                        "Skipping web root file '{0}' because '{1}' is already served by another static web asset.",
+                        identity,
+                        relativePath);
+                    continue;
+                }
+
+                Log.LogWarning(
+                    "No static web asset was found for the web root file '{0}', so it will not be served at runtime. " +
+                    "Files created inside the web root after the project is evaluated, for example by a target that " +
+                    "runs before 'Build', are not discovered as static web assets. Add the file to the 'Content' items " +
+                    "from the target that produces it, for example " +
+                    "<Content Include=\"$(IntermediateOutputPath){1}\" Link=\"wwwroot/{1}\" />, or set " +
+                    "'StaticWebAssetsWarnOnUndiscoveredWebRootFiles' to 'false' to disable this check.",
+                    identity,
+                    relativePath);
+            }
+        }
+        catch (Exception ex)
+        {
+            Log.LogError(ex.Message);
+        }
+
+        return !Log.HasLoggedErrors;
+    }
+
+    private HashSet<string> GetAssetPaths()
+    {
+        var result = new HashSet<string>(OSPath.PathComparer);
+        if (Assets == null)
+        {
+            return result;
+        }
+
+        foreach (var item in Assets)
+        {
+            var asset = StaticWebAsset.FromTaskItem(item, TaskEnvironment);
+            if (!string.IsNullOrEmpty(asset.Identity))
+            {
+                result.Add(Path.GetFullPath(asset.Identity));
+            }
+        }
+
+        return result;
+    }
+
+    private HashSet<string> GetRoutes()
+    {
+        var result = new HashSet<string>(OSPath.PathComparer);
+        if (Endpoints == null)
+        {
+            return result;
+        }
+
+        foreach (var endpoint in StaticWebAssetEndpoint.FromItemGroup(Endpoints))
+        {
+            if (!string.IsNullOrEmpty(endpoint.Route))
+            {
+                result.Add(endpoint.Route.Replace('\\', '/').TrimStart('/'));
+            }
+        }
+
+        return result;
+    }
+
+    private bool IsServedByAnotherAsset(HashSet<string> routes, string relativePath)
+    {
+        if (routes.Contains(relativePath))
+        {
+            return true;
+        }
+
+        // Projects that are not served from the root of the application, class libraries for example,
+        // expose their web root under a base path, so the route does not match the path relative to the
+        // web root on its own.
+        var basePath = BasePath?.Replace('\\', '/').Trim('/');
+        return !string.IsNullOrEmpty(basePath) && routes.Contains($"{basePath}/{relativePath}");
+    }
+
+    private static string NormalizeDirectory(string path) =>
+        path.Length == 0 || path[path.Length - 1] == Path.DirectorySeparatorChar || path[path.Length - 1] == Path.AltDirectorySeparatorChar
+            ? path
+            : path + Path.DirectorySeparatorChar;
+}
diff --git a/test/Microsoft.NET.Sdk.StaticWebAssets.Tests/StaticWebAssets/ValidateWebRootFileDiscoveryTest.cs b/test/Microsoft.NET.Sdk.StaticWebAssets.Tests/StaticWebAssets/ValidateWebRootFileDiscoveryTest.cs
new file mode 100644
index 0000000000..275204b586
--- /dev/null
+++ b/test/Microsoft.NET.Sdk.StaticWebAssets.Tests/StaticWebAssets/ValidateWebRootFileDiscoveryTest.cs
@@ -0,0 +1,189 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+#nullable disable
+
+using Microsoft.Build.Framework;
+using Microsoft.Build.Utilities;
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+using Moq;
+
+namespace Microsoft.AspNetCore.StaticWebAssets.Tasks;
+
+[TestClass]
+public class ValidateWebRootFileDiscoveryTest : IDisposable
+{
+    private readonly string _tempDir;
+    private readonly string _webRoot;
+    private readonly Mock<IBuildEngine> _buildEngine;
+    private readonly List<string> _errorMessages;
+    private readonly List<string> _warningMessages;
+
+    public ValidateWebRootFileDiscoveryTest()
+    {
+        _tempDir = Path.Combine(Path.GetTempPath(), "ValidateWebRootFiles_" + Guid.NewGuid().ToString("N"));
+        _webRoot = Path.Combine(_tempDir, "wwwroot") + Path.DirectorySeparatorChar;
+        Directory.CreateDirectory(_webRoot);
+
+        _errorMessages = new List<string>();
+        _warningMessages = new List<string>();
+        _buildEngine = new Mock<IBuildEngine>();
+        _buildEngine.Setup(e => e.LogErrorEvent(It.IsAny<BuildErrorEventArgs>()))
+            .Callback<BuildErrorEventArgs>(args => _errorMessages.Add(args.Message));
+        _buildEngine.Setup(e => e.LogWarningEvent(It.IsAny<BuildWarningEventArgs>()))
+            .Callback<BuildWarningEventArgs>(args => _warningMessages.Add(args.Message));
+    }
+
+    public void Dispose()
+    {
+        if (Directory.Exists(_tempDir))
+        {
+            try { Directory.Delete(_tempDir, recursive: true); } catch { }
+        }
+    }
+
+    [TestMethod]
+    public void WebRootFileWithoutAsset_Warns()
+    {
+        var generated = CreateWebRootFile("css/site.css");
+
+        var task = CreateTask(webRootFiles: new[] { generated });
+
+        task.Execute().Should().BeTrue("the check reports a warning and does not fail the build");
+        _warningMessages.Should().ContainSingle()
+            .Which.Should().Contain("css/site.css");
+        _errorMessages.Should().BeEmpty();
+    }
+
+    [TestMethod]
+    public void WebRootFileWithMatchingAsset_DoesNotWarn()
+    {
+        var content = CreateWebRootFile("css/site.css");
+
+        var task = CreateTask(
+            webRootFiles: new[] { content },
+            assets: new[] { CreateAssetItem(content.ItemSpec, "css/site.css") });
+
+        task.Execute().Should().BeTrue();
+        _warningMessages.Should().BeEmpty();
+    }
+
+    [TestMethod]
+    public void WebRootFileServedByAnotherAsset_DoesNotWarn()
+    {
+        // A target generated the file under the intermediate output path and linked it into the web root,
+        // while a copy was also left in the web root itself. The route is served, so there is nothing to
+        // report for the copy on disk.
+        var staleCopy = CreateWebRootFile("css/site.css");
+        var generated = Path.Combine(_tempDir, "obj", "site.css");
+
+        var task = CreateTask(
+            webRootFiles: new[] { staleCopy },
+            assets: new[] { CreateAssetItem(generated, "css/site#[.{fingerprint}]?.css") },
+            endpoints: new[] { CreateEndpointItem("css/site.css", generated) });
+
+        task.Execute().Should().BeTrue();
+        _warningMessages.Should().BeEmpty();
+    }
+
+    [TestMethod]
+    public void WebRootFileServedUnderBasePath_DoesNotWarn()
+    {
+        // Class libraries serve their web root under a base path, so the route does not match the path
+        // relative to the web root on its own.
+        var staleCopy = CreateWebRootFile("css/site.css");
+        var generated = Path.Combine(_tempDir, "obj", "site.css");
+
+        var task = CreateTask(
+            webRootFiles: new[] { staleCopy },
+            assets: new[] { CreateAssetItem(generated, "css/site.css") },
+            endpoints: new[] { CreateEndpointItem("_content/MyLibrary/css/site.css", generated) },
+            basePath: "_content/MyLibrary");
+
+        task.Execute().Should().BeTrue();
+        _warningMessages.Should().BeEmpty();
+    }
+
+    [TestMethod]
+    public void FileOutsideWebRoot_DoesNotWarn()
+    {
+        var outside = new TaskItem(Path.Combine(_tempDir, "Styles", "app.css"));
+
+        var task = CreateTask(webRootFiles: new[] { outside });
+
+        task.Execute().Should().BeTrue();
+        _warningMessages.Should().BeEmpty();
+    }
+
+    [TestMethod]
+    public void NoWebRootFiles_DoesNotWarn()
+    {
+        var task = CreateTask(webRootFiles: Array.Empty<ITaskItem>());
+
+        task.Execute().Should().BeTrue();
+        _warningMessages.Should().BeEmpty();
+    }
+
+    [TestMethod]
+    public void MultipleUndiscoveredFiles_WarnsForEach()
+    {
+        var css = CreateWebRootFile("css/site.css");
+        var js = CreateWebRootFile("js/site.js");
+        var discovered = CreateWebRootFile("favicon.ico");
+
+        var task = CreateTask(
+            webRootFiles: new[] { css, js, discovered },
+            assets: new[] { CreateAssetItem(discovered.ItemSpec, "favicon.ico") });
+
+        task.Execute().Should().BeTrue();
+        _warningMessages.Should().HaveCount(2);
+        _warningMessages.Should().Contain(m => m.Contains("css/site.css"));
+        _warningMessages.Should().Contain(m => m.Contains("js/site.js"));
+        _warningMessages.Should().NotContain(m => m.Contains("favicon.ico"));
+    }
+
+    private ValidateWebRootFileDiscovery CreateTask(
+        ITaskItem[] webRootFiles,
+        ITaskItem[] assets = null,
+        ITaskItem[] endpoints = null,
+        string basePath = null) =>
+        new()
+        {
+            BuildEngine = _buildEngine.Object,
+            WebRootFiles = webRootFiles,
+            Assets = assets ?? Array.Empty<ITaskItem>(),
+            Endpoints = endpoints ?? Array.Empty<ITaskItem>(),
+            WebRoot = _webRoot,
+            BasePath = basePath,
+        };
+
+    private TaskItem CreateWebRootFile(string relativePath)
+    {
+        var path = Path.Combine(_webRoot, relativePath.Replace('/', Path.DirectorySeparatorChar));
+        Directory.CreateDirectory(Path.GetDirectoryName(path));
+        File.WriteAllText(path, "/* content */");
+        return new TaskItem(path);
+    }
+
+    private TaskItem CreateAssetItem(string identity, string relativePath)
+    {
+        var item = new TaskItem(identity);
+        item.SetMetadata(nameof(StaticWebAsset.SourceId), "MyProject");
+        item.SetMetadata(nameof(StaticWebAsset.SourceType), StaticWebAsset.SourceTypes.Discovered);
+        item.SetMetadata(nameof(StaticWebAsset.ContentRoot), _webRoot);
+        item.SetMetadata(nameof(StaticWebAsset.BasePath), "/");
+        item.SetMetadata(nameof(StaticWebAsset.RelativePath), relativePath);
+        item.SetMetadata(nameof(StaticWebAsset.AssetKind), StaticWebAsset.AssetKinds.All);
+        item.SetMetadata(nameof(StaticWebAsset.AssetMode), StaticWebAsset.AssetModes.All);
+        item.SetMetadata(nameof(StaticWebAsset.AssetRole), StaticWebAsset.AssetRoles.Primary);
+        item.SetMetadata(nameof(StaticWebAsset.OriginalItemSpec), identity);
+        return item;
+    }
+
+    private static TaskItem CreateEndpointItem(string route, string assetFile)
+    {
+        var item = new TaskItem(route);
+        item.SetMetadata(nameof(StaticWebAssetEndpoint.AssetFile), assetFile);
+        return item;
+    }
+}
-- 
2.50.1 (Apple Git-155)


From 7113dae01b843f62522d58960a4b3369c2324c2e Mon Sep 17 00:00:00 2001
From: Steven Thonus <steven@infi.nl>
Date: Thu, 20 Aug 2026 11:19:12 +0200
Subject: [PATCH 2/2] Add integration tests for the web root discovery warning

Cover the three shapes through a real build: a target writing into the web
root without registering the file warns, generating into the intermediate
output path and linking it as Content does not, and the opt-out property
silences the check.
---
 ...ssetsDiscoveryValidationIntegrationTest.cs | 85 +++++++++++++++++++
 1 file changed, 85 insertions(+)
 create mode 100644 test/Microsoft.NET.Sdk.StaticWebAssets.Tests/StaticWebAssetsDiscoveryValidationIntegrationTest.cs

diff --git a/test/Microsoft.NET.Sdk.StaticWebAssets.Tests/StaticWebAssetsDiscoveryValidationIntegrationTest.cs b/test/Microsoft.NET.Sdk.StaticWebAssets.Tests/StaticWebAssetsDiscoveryValidationIntegrationTest.cs
new file mode 100644
index 0000000000..d17ff62ac0
--- /dev/null
+++ b/test/Microsoft.NET.Sdk.StaticWebAssets.Tests/StaticWebAssetsDiscoveryValidationIntegrationTest.cs
@@ -0,0 +1,85 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+#nullable disable
+
+using System.Xml.Linq;
+using Microsoft.NET.TestFramework;
+using Microsoft.NET.TestFramework.Assertions;
+using Microsoft.NET.TestFramework.Commands;
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+
+namespace Microsoft.NET.Sdk.StaticWebAssets.Tests
+{
+    [TestClass]
+    public class StaticWebAssetsDiscoveryValidationIntegrationTest : AspNetSdkTest
+    {
+        private const string WarningFragment = "No static web asset was found for the web root file";
+
+        [TestMethod]
+        public void Build_WarnsWhenATargetWritesAFileIntoTheWebRootWithoutRegisteringIt()
+        {
+            var projectDirectory = CreateAspNetSdkTestAsset("RazorComponentApp", identifier: "Unregistered")
+                .WithProjectChanges(document => document.Root.Add(GenerateIntoWebRootTarget()));
+
+            var build = CreateBuildCommand(projectDirectory);
+
+            ExecuteCommand(build).Should().Pass()
+                .And.HaveStdOutContaining(WarningFragment)
+                .And.HaveStdOutContaining("generated.css");
+        }
+
+        [TestMethod]
+        public void Build_DoesNotWarnWhenTheGeneratedFileIsRegisteredAsContent()
+        {
+            // The supported shape: generate into the intermediate output path and link the result into the
+            // web root, so the file is part of Content by the time assets are discovered.
+            var projectDirectory = CreateAspNetSdkTestAsset("RazorComponentApp", identifier: "Registered")
+                .WithProjectChanges(document => document.Root.Add(
+                    new XElement("Target",
+                        new XAttribute("Name", "GenerateStyles"),
+                        new XAttribute("BeforeTargets", "AssignTargetPaths"),
+                        new XElement("WriteLinesToFile",
+                            new XAttribute("File", "$(IntermediateOutputPath)generated.css"),
+                            new XAttribute("Lines", "body{color:red}"),
+                            new XAttribute("Overwrite", "true")),
+                        new XElement("ItemGroup",
+                            new XElement("Content",
+                                new XAttribute("Include", "$(IntermediateOutputPath)generated.css"),
+                                new XAttribute("Link", "wwwroot/css/generated.css"))))));
+
+            var build = CreateBuildCommand(projectDirectory);
+
+            ExecuteCommand(build).Should().Pass()
+                .And.NotHaveStdOutContaining(WarningFragment);
+        }
+
+        [TestMethod]
+        public void Build_DoesNotWarnWhenTheCheckIsDisabled()
+        {
+            var projectDirectory = CreateAspNetSdkTestAsset("RazorComponentApp", identifier: "Disabled")
+                .WithProjectChanges(document =>
+                {
+                    document.Root.Add(new XElement("PropertyGroup",
+                        new XElement("StaticWebAssetsWarnOnUndiscoveredWebRootFiles", "false")));
+                    document.Root.Add(GenerateIntoWebRootTarget());
+                });
+
+            var build = CreateBuildCommand(projectDirectory);
+
+            ExecuteCommand(build).Should().Pass()
+                .And.NotHaveStdOutContaining(WarningFragment);
+        }
+
+        private static XElement GenerateIntoWebRootTarget() =>
+            new(
+                "Target",
+                new XAttribute("Name", "GenerateStyles"),
+                new XAttribute("BeforeTargets", "BeforeBuild"),
+                new XElement("MakeDir", new XAttribute("Directories", "wwwroot/css")),
+                new XElement("WriteLinesToFile",
+                    new XAttribute("File", "wwwroot/css/generated.css"),
+                    new XAttribute("Lines", "body{color:red}"),
+                    new XAttribute("Overwrite", "true")));
+    }
+}
-- 
2.50.1 (Apple Git-155)

[Popl7]

Following up with the full-suite result I said I'd report either way.

882 tests: 876 passed, 6 skipped, 0 failed. No regressions from this change.

That took one detour worth recording, because my first run of the suite reported 19 failures and I initially wrote them off as merely "pre-existing and unrelated". They are unrelated, but that description undersold what was going on, so here is the accurate version.

All 19 were RewriteCssTest (scoped CSS rewriting), failing with:

System.IO.FileNotFoundException: Could not load file or assembly
'Microsoft.Css.Parser, Version=1.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60'.

Nothing is actually missing. The package is in the NuGet cache and Microsoft.Css.Parser.dll is sitting in the test output directory next to the test assembly. It is simply not declared in Microsoft.NET.Sdk.StaticWebAssets.Tests.deps.json, and the host will not load an assembly it has not been told about. The likely cause is that Microsoft.NET.Sdk.StaticWebAssets.Tasks.csproj applies PrivateAssets=All to every PackageReference through an ItemDefinitionGroup (alongside GenerateDependencyFile=false and CopyLocalLockFileAssemblies=false), so the reference never flows into the test project's dependency graph even though the file gets copied in.

Confirmed by experiment rather than inference: adding a single PackageReference for Microsoft.Css.Parser to the test project makes all 19 pass, and the full suite then goes green at 876/882 with 0 failures. I have reverted that line — it is unrelated to this change and does not belong in the same commit, but it may be worth fixing separately.

I could not determine whether CI hits this. ./build.sh --test is not usable for this project (MSB4057: The target "RunTests" does not exist, since these tests moved to MSTest.Sdk / Microsoft.Testing.Platform), so I could not reproduce the CI invocation to compare. Either CI's build produces a deps.json that includes the assembly, or these 19 are quietly failing on main; I genuinely cannot tell from here. Flagging it in case it is news.

Independently of any of that, the 19 are not caused by this change. Verified against the untouched base commit (7053edd), rebuilding both the tasks and test projects:

Tree	RewriteCssTest
7053edd (base, unmodified)	19 total / 19 failed
this branch	19 total / 19 failed

(My first attempt at that baseline was invalid — I had already committed the change, so git stash had nothing to stash and I was still measuring the modified tree. Redone properly against the base commit.)

Where this leaves the change

• Task builds clean, 0 warnings, net11.0 + net472.
• 7 unit tests, 3 integration tests, all passing.
• Full suite green: 876 passed, 0 failed, 6 skipped (Windows-only).
• End-to-end verified against the composed redist SDK, including the case where a pre-existing generated file means there is no bug and the check correctly stays quiet.

On default-on: the suite is reassuring but not conclusive. 876 passing tests include plenty of real builds of apps with a wwwroot and none tripped the warning. The wider ecosystem is the real risk, where TreatWarningsAsErrors plus a deliberately excluded web root file could turn a green build red. Still your call, and I would defer to your judgement on shipping it opt-in for a release first.

Happy to open a PR whenever you like; equally happy to leave it here if you would rather fold the general case into #52301.