[Static Assets] Improve development experience (#57764)

Backport of #57671 to release/9.0

/cc @javiercn

# [Static Assets] Improve development experience

Fixes an issue when running a published app on Development and provides a better error when static web assets are not enabled during development

## Description

- Addresses two issues that we found during development:
  - When the user publishes the app and runs against the `Development` environment:
    - Some logic that is pivoted on based on the Environment and is only used during development (Build as opposed to Publish) interferes with the output and causes issues on the running app.
  - When the app runs during development, but Static Web Assets are not enabled for some reason:
    - The app isn't able to find some static files and errors out.
    - The fix improves the experience by detecting this situation and logging a warning on the console with instructions on how to enable static web assets explicitly.

## Customer Impact

* Running in Docker 'Regular Mode' in Visual Studio breaks as the app runs the published output with `Development` environment.
* Running the app during development with a custom environment or without a launch profile will cause some static files to not be found.

## Regression?

- [X] Yes
- [ ] No

8.0 and earlier, the published output was runnable in `Development` environment. For example in Docker containers regular mode (how the issue was found).

## Risk

- [ ] High
- [ ] Medium
- [X] Low

The changes uses information that we produce during the build (Build and Publish) to differentiate between the two scenarios and disable the development functionality for the published output and provide a better error message when static web assets are not enabled during development.

## Verification

- [X] Manual (required)
- [ ] Automated

## Packaging changes reviewed?

- [ ] Yes
- [ ] No
- [X] N/A

----

## When servicing release/2.1

- [ ] Make necessary changes in eng/PatchConfig.props

Author: github-actions[bot]

src/StaticAssets/src/BuildAssetMetadata.cs

@@ -0,0 +1,6 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Microsoft.AspNetCore.StaticAssets;
+
+internal sealed class BuildAssetMetadata { }

src/StaticAssets/src/Development/StaticAssetDevelopmentRuntimeHandler.cs

@@ -15,7 +15,6 @@
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.FileProviders;
-using Microsoft.Extensions.Hosting;
 using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Primitives;
 using Microsoft.Net.Http.Headers;
@@ -156,11 +155,11 @@ private static StaticAssetDescriptor FindOriginalAsset(string tag, List<StaticAs
         throw new InvalidOperationException("The original asset was not found.");
     }
 
-    internal static bool IsEnabled(IServiceProvider serviceProvider, IWebHostEnvironment environment)
+    internal static bool IsEnabled(bool isBuildManifest, IServiceProvider serviceProvider)
     {
         var config = serviceProvider.GetRequiredService<IConfiguration>();
         var explicitlyConfigured = bool.TryParse(config[ReloadStaticAssetsAtRuntimeKey], out var hotReload);
-        return (!explicitlyConfigured && environment.IsDevelopment()) || (explicitlyConfigured && hotReload);
+        return (!explicitlyConfigured && isBuildManifest) || (explicitlyConfigured && hotReload);
     }
 
     internal static void EnableSupport(

src/StaticAssets/src/LoggerExtensions.cs

@@ -59,5 +59,10 @@ public static void FileServed(this ILogger logger, string virtualPath, string ph
     [LoggerMessage(16, LogLevel.Warning,
         "The WebRootPath was not found: {WebRootPath}. Static files may be unavailable.", EventName = "WebRootPathNotFound")]
     public static partial void WebRootPathNotFound(this ILogger logger, string webRootPath);
+
+    [LoggerMessage(17, LogLevel.Warning,
+        "The application is not running against the published output and Static Web Assets are not enabled." +
+        " To configure static web assets in other environments, call 'StaticWebAssetsLoader.UseStaticWebAssets(IWebHostEnvironment, IConfiguration)' to enable them.", EventName = "StaticWebAssetsNotEnabled")]
+    public static partial void EnsureStaticWebAssetsEnabled(this ILogger logger);
 }
 

src/StaticAssets/src/StaticAssetEndpointDataSource.cs

@@ -28,6 +28,7 @@ internal StaticAssetsEndpointDataSource(
         IServiceProvider serviceProvider,
         StaticAssetEndpointFactory endpointFactory,
         string manifestName,
+        bool isBuildManifest,
         List<StaticAssetDescriptor> descriptors)
     {
         ServiceProvider = serviceProvider;
@@ -37,8 +38,14 @@ internal StaticAssetsEndpointDataSource(
         _cancellationTokenSource = new CancellationTokenSource();
         _changeToken = new CancellationChangeToken(_cancellationTokenSource.Token);
 
+        if (isBuildManifest)
+        {
+            _conventions.Add(c => c.Metadata.Add(new BuildAssetMetadata()));
+        }
+
         DefaultBuilder = new StaticAssetsEndpointConventionBuilder(
             _lock,
+            isBuildManifest,
             descriptors,
             _conventions,
             _finallyConventions);

src/StaticAssets/src/StaticAssetsEndpointConventionBuilder.cs

@@ -11,20 +11,24 @@ namespace Microsoft.AspNetCore.StaticAssets;
 public sealed class StaticAssetsEndpointConventionBuilder : IEndpointConventionBuilder
 {
     private readonly object _lck;
+    private readonly bool _isBuildManifest;
     private readonly List<StaticAssetDescriptor> _descriptors;
     private readonly List<Action<EndpointBuilder>> _conventions;
     private readonly List<Action<EndpointBuilder>> _finallyConventions;
 
-    internal StaticAssetsEndpointConventionBuilder(object lck, List<StaticAssetDescriptor> descriptors, List<Action<EndpointBuilder>> conventions, List<Action<EndpointBuilder>> finallyConventions)
+    internal StaticAssetsEndpointConventionBuilder(object lck, bool isBuildManifest, List<StaticAssetDescriptor> descriptors, List<Action<EndpointBuilder>> conventions, List<Action<EndpointBuilder>> finallyConventions)
     {
         _lck = lck;
+        _isBuildManifest = isBuildManifest;
         _descriptors = descriptors;
         _conventions = conventions;
         _finallyConventions = finallyConventions;
     }
 
     internal List<StaticAssetDescriptor> Descriptors => _descriptors;
 
+    internal bool IsBuildManifest => _isBuildManifest;
+
     /// <inheritdoc/>
     public void Add(Action<EndpointBuilder> convention)
     {

src/StaticAssets/src/StaticAssetsEndpointRouteBuilderExtensions.cs

@@ -36,7 +36,7 @@ public static StaticAssetsEndpointConventionBuilder MapStaticAssets(this IEndpoi
 
         var result = MapStaticAssetsCore(endpoints, staticAssetsManifestPath);
 
-        if (StaticAssetDevelopmentRuntimeHandler.IsEnabled(endpoints.ServiceProvider, environment))
+        if (StaticAssetDevelopmentRuntimeHandler.IsEnabled(result.IsBuildManifest, endpoints.ServiceProvider))
         {
             StaticAssetDevelopmentRuntimeHandler.EnableSupport(endpoints, result, environment, result.Descriptors);
         }
@@ -56,7 +56,7 @@ private static StaticAssetsEndpointConventionBuilder MapStaticAssetsCore(
 
         var manifest = ResolveManifest(manifestPath);
 
-        var dataSource = StaticAssetsManifest.CreateDataSource(endpoints, manifestPath, manifest.Endpoints);
+        var dataSource = StaticAssetsManifest.CreateDataSource(endpoints, manifestPath, manifest.Endpoints, manifest.IsBuildManifest());
         return dataSource.DefaultBuilder;
     }
 
@@ -89,9 +89,9 @@ internal static StaticAssetsEndpointConventionBuilder MapStaticAssets(this IEndp
         ArgumentNullException.ThrowIfNull(endpoints);
 
         var environment = endpoints.ServiceProvider.GetRequiredService<IWebHostEnvironment>();
-        var result = StaticAssetsManifest.CreateDataSource(endpoints, "", manifest.Endpoints).DefaultBuilder;
+        var result = StaticAssetsManifest.CreateDataSource(endpoints, "", manifest.Endpoints, manifest.IsBuildManifest()).DefaultBuilder;
 
-        if (StaticAssetDevelopmentRuntimeHandler.IsEnabled(endpoints.ServiceProvider, environment))
+        if (StaticAssetDevelopmentRuntimeHandler.IsEnabled(result.IsBuildManifest, endpoints.ServiceProvider))
         {
             StaticAssetDevelopmentRuntimeHandler.EnableSupport(endpoints, result, environment, result.Descriptors);
         }

src/StaticAssets/src/StaticAssetsInvoker.cs

@@ -3,10 +3,13 @@
 
 using System.Diagnostics;
 using System.Globalization;
+using Microsoft.AspNetCore.Hosting;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Http.Headers;
 using Microsoft.AspNetCore.Internal;
+using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.FileProviders;
+using Microsoft.Extensions.Hosting;
 using Microsoft.Extensions.Logging;
 using Microsoft.Net.Http.Headers;
 
@@ -81,7 +84,7 @@ public StaticAssetsInvoker(StaticAssetDescriptor resource, IFileProvider filePro
     public IFileInfo FileInfo => _fileInfo ??=
         _fileProvider.GetFileInfo(_resource.AssetPath) is IFileInfo file and { Exists: true } ?
         file :
-        throw new InvalidOperationException($"The file '{_resource.AssetPath}' could not be found.");
+        throw new FileNotFoundException($"The file '{_resource.AssetPath}' could not be found.");
 
     private Task ApplyResponseHeadersAsync(StaticAssetInvocationContext context, int statusCode)
     {
@@ -157,6 +160,14 @@ public async Task Invoke(HttpContext context)
                 }
                 catch (FileNotFoundException)
                 {
+                    if (context.GetEndpoint() is Endpoint { Metadata: { } metadata } && metadata.GetMetadata<BuildAssetMetadata>() != null)
+                    {
+                        var environment = context.RequestServices.GetRequiredService<IWebHostEnvironment>();
+                        if (!environment.IsDevelopment() && environment.WebRootFileProvider is not CompositeFileProvider)
+                        {
+                            _logger.EnsureStaticWebAssetsEnabled();
+                        }
+                    }
                     context.Response.Clear();
                 }
                 return;

src/StaticAssets/src/StaticAssetsManifest.cs

@@ -35,14 +35,23 @@ internal static StaticAssetsManifest Parse(string manifestPath)
         return result;
     }
 
-    internal static StaticAssetsEndpointDataSource CreateDataSource(IEndpointRouteBuilder endpoints, string manifestName, List<StaticAssetDescriptor> descriptors)
+    internal static StaticAssetsEndpointDataSource CreateDataSource(IEndpointRouteBuilder endpoints, string manifestName, List<StaticAssetDescriptor> descriptors, bool isBuildManifest)
     {
-        var dataSource = new StaticAssetsEndpointDataSource(endpoints.ServiceProvider, new StaticAssetEndpointFactory(endpoints.ServiceProvider), manifestName, descriptors);
+        var dataSource = new StaticAssetsEndpointDataSource(
+            endpoints.ServiceProvider,
+            new StaticAssetEndpointFactory(endpoints.ServiceProvider),
+            manifestName,
+            isBuildManifest,
+            descriptors);
         endpoints.DataSources.Add(dataSource);
         return dataSource;
     }
 
     public int Version { get; set; }
 
+    public string ManifestType { get; set; } = "";
+
     public List<StaticAssetDescriptor> Endpoints { get; set; } = [];
+
+    public bool IsBuildManifest() => string.Equals(ManifestType, "Build", StringComparison.OrdinalIgnoreCase);
 }

src/StaticAssets/test/StaticAssetsIntegrationTests.cs

@@ -492,6 +492,7 @@ private static void CreateTestManifest(string appName, string webRoot, params Sp
             var lastModified = DateTimeOffset.UtcNow;
             File.WriteAllText(filePath, resource.Content);
             var hash = GetEtag(resource.Content);
+            manifest.ManifestType = "Build";
             manifest.Endpoints.Add(new StaticAssetDescriptor
             {
                 Route = resource.Path,