Unclear information in 'Static files in non-Development environments' + missing Razor static assets description (WithStaticAssets)

[dcarapic]

Description

I do not understand the information in 'Static files in non-Development environments'.
It starts with 'When running an app locally ...' ... what does this mean? This is a web app, it's always run locally somewhere, do you mean when using launchProfiles or with debugger? What about dotnet watch or dotnet run ... will it correctly serve the static files?
I did not know that there is a difference in serving static files based on environment (except the caching header stuff in Development .. that part is clear).
Please elaborate more.

In addition to this the latest Razor pages template adds:
app.MapRazorPages.WithStaticAssets()
What does this do, there seems to be no documentation for it?

Page URL

https://learn.microsoft.com/en-us/aspnet/core/fundamentals/static-files?view=aspnetcore-10.0#static-files-in-non-development-environments

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/fundamentals/static-files.md

Document ID

3fec6e08-fc99-7a5c-796f-3f2347cad891

Platform Id

5c42c2c8-be1b-60de-8cde-f9b8d8c24f5f

Article author

@wadepickett

Metadata

• ID: d47f38e2-bc36-cfb8-b0cc-17a534689f8b
• PlatformId: 5c42c2c8-be1b-60de-8cde-f9b8d8c24f5f
• Service: aspnet-core
• Sub-service: fundamentals

Related Issues

[wadepickett]

@dcarapic, thanks for taking the time to let us know your experience. Greatly appreciated!

Regarding "Static files in non-Development environments": You're right that the phrase "when running an app locally" is ambiguous! That could certainly be improved. The key factor is actually the ASPNETCORE_ENVIRONMENT value, not how the app is launched. The UseStaticWebAssets() call is automatically made in the Development environment to resolve static files from referenced projects and packages (like Razor class libraries). In non-Development environments, that automatic call doesn't happen, so you need to add it explicitly if you're testing with a different environment name. Your app's own wwwroot files are always served regardless of environment. We'll rewrite this section to make that distinction clear.

Regarding WithStaticAssets(): This is a .NET 9+ method that you chain after MapRazorPages() or MapControllerRoute(). It enables Razor Pages/MVC tag helpers (like the Script and Link tag helpers) to automatically resolve the fingerprinted static asset file names generated by MapStaticAssets(). Without it, your views won't pick up the optimized, fingerprinted URLs. We agree this needs to be documented in the static files article. Currently it's only briefly mentioned in the Razor Pages tutorial and the 8.0-to-9.0 migration guide.

We'll update the article to address both concerns. Thanks again for the detailed feedback!

[wadepickett]

🤖 AI Triage Summary

📌 Note to community: This is an automated preliminary analysis to help our documentation team quickly review, determine scope and prioritize this issue. This report is not a resolution — it's a starting point for the team's evaluation.

---

This preliminary assessment report was run by: @wadepickett
Date: 2026-05-29
Issue: 37197
Model: GitHub Copilot

---

Issue Analysis: Unclear "Static files in non-Development environments" section + missing WithStaticAssets documentation

✅ Issue Validation

Status: Valid and actionable

📋 Issue Summary

The issue raises two distinct concerns:

1. Unclear language in "Static files in non-Development environments" section: The phrase "When running an app locally" is ambiguous — the reporter correctly notes that a web app is always "run locally somewhere." The section doesn't clarify what "locally" means (e.g., dotnet run, dotnet watch, Visual Studio debugging, etc.) or adequately explain why static web assets behave differently based on environment. The UseStaticWebAssets() call and when it's needed is not well-motivated.

2. Missing documentation for WithStaticAssets(): The Razor Pages and MVC templates generate app.MapRazorPages().WithStaticAssets() (or .MapControllerRoute(...).WithStaticAssets()), but the static files article does not explain what WithStaticAssets() does. The only existing explanation is a brief one-liner in the Razor Pages tutorial: "Ensures Razor Pages participate in the optimization system for static assets."

📁 Potentially Affected Files

These files have been identified as possibly related to this issue and may need review.

File	Path	Lines	Section
Main article	aspnetcore/fundamentals/static-files.md	153-165	"Static files in non-Development environments"
Main article	aspnetcore/fundamentals/static-files.md	19-43	MapStaticAssets introduction (>=aspnetcore-9.0 moniker)
Migration guide	aspnetcore/migration/80-to-90.md	55-96	"Replace UseStaticFiles with MapStaticAssets"

📝 Preliminary Change Assessment (Including wadepickett's assessment in the issue discussion)

The following are initial observations for the documentation team to evaluate—not final decisions.

1. Clarify "Static files in non-Development environments" section

File: aspnetcore/fundamentals/static-files.md
Location: Lines 153-165
Type: Rewrite for clarity

Current content (lines 153-165):

## Static files in non-`Development` environments

When running an app locally, static web assets are only enabled in the `Development` environment. To enable static files for environments other than `Development` during local development and testing, call UseStaticWebAssets...

> [!WARNING]
> Call UseStaticWebAssets for the ***exact environment*** to prevent activating the feature in production, as it serves files from separate locations on disk...

if (builder.Environment.IsStaging())
{
    builder.WebHost.UseStaticWebAssets();
}

Suggested direction:

## Static files in non-`Development` environments

ASP.NET Core uses a build-time feature called *static web assets* to resolve static files from referenced projects and packages (such as Razor class libraries). In the `Development` environment, `UseStaticWebAssets` is called automatically by `WebApplication.CreateBuilder`, so static files from referenced projects and packages are served without additional configuration.

However, when running the app in any other environment (for example, `Staging` or a custom environment), static web assets from referenced projects and packages aren't resolved automatically. This applies regardless of how the app is launched — whether with `dotnet run`, `dotnet watch`, Visual Studio, or any other method. The distinguishing factor is the value of the `ASPNETCORE_ENVIRONMENT` environment variable, not the launch method.

If you need to serve static web assets from referenced projects or packages in a non-`Development` environment during local development or testing, call UseStaticWebAssets:

> [!WARNING]
> Call `UseStaticWebAssets` only for the ***exact environment*** where you need it. Never call it unconditionally, as it serves files from separate locations on disk and may expose unintended content in production.

if (builder.Environment.IsStaging())
{
    builder.WebHost.UseStaticWebAssets();
}

> [!NOTE]
> This section applies to static web assets from *referenced projects and packages*. Static files in the app's own `wwwroot` folder are always served by `MapStaticAssets` (or `UseStaticFiles`) regardless of the environment.

2. Add documentation for WithStaticAssets()

File: aspnetcore/fundamentals/static-files.md
Location: After line 98 (the app.MapStaticAssets(); code block), within the >= aspnetcore-9.0 moniker
Type: New subsection

Suggested direction:

### `WithStaticAssets` for MVC and Razor Pages

In MVC and Razor Pages apps, chain a call to `WithStaticAssets` after `MapRazorPages` or `MapControllerRoute` to enable Razor Pages and MVC views to participate in the static asset optimization system. This allows tag helpers (such as the Script and Link tag helpers) to automatically resolve fingerprinted file names generated by `MapStaticAssets`.

For Razor Pages:

app.MapStaticAssets();
app.MapRazorPages()
   .WithStaticAssets();

For MVC:

app.MapStaticAssets();
app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}")
    .WithStaticAssets();

Without `WithStaticAssets`, tag helpers in Razor Pages and MVC views won't resolve the fingerprinted static asset URLs generated by `MapStaticAssets`. The `WithStaticAssets` call isn't needed in Blazor apps, which use the `@Assets["..."]` syntax instead.

🎯 Suggested Action Plan

For documentation team review

1. Rewrite the "Static files in non-Development environments" section:

   • Navigate to: Lines 153-165
   • Clarify that "locally" refers to the environment name, not the launch method
   • Explain why UseStaticWebAssets is needed (referenced project/package assets only)
   • Distinguish from the app's own wwwroot assets

2. Add a WithStaticAssets subsection:

   • Navigate to: Lines 92-100
   • Add a new subsection within the >= aspnetcore-9.0 moniker explaining WithStaticAssets
   • Include code examples for both Razor Pages and MVC
   • Explain the relationship between MapStaticAssets and WithStaticAssets

⚠️ Review Considerations

• Verify the exact behavior of UseStaticWebAssets with the ASP.NET Core product team if needed
• Ensure the explanation applies consistently to .NET 9 and .NET 10
• Check if the migration guide (80-to-90.md) should also be updated with a clearer explanation of WithStaticAssets
• Consider adding a cross-reference from the Razor Pages tutorial to the static files article for WithStaticAssets

🔗 References

• Published article: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/static-files?view=aspnetcore-10.0
• Source file: https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/fundamentals/static-files.md
• Migration guide with brief WithStaticAssets mention: https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/migration/80-to-90.md
• Razor Pages tutorial with WithStaticAssets description: https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/tutorials/razor-pages/razor-pages-start.md

[dcarapic]

Thank you for the clarification but it does not explain why is call to UseStaticWebAssets not automatically included in other environments?
Does this mean that some assets do not work in other environments? Why should I not call UseStaticWebAssets always? What is the drawback?