Add note to the Razor runtime compilation doc that it is obsolete

[danroth27]

Description

We obsoleted Razor runtime compilation in .NET 10: https://learn.microsoft.com/dotnet/core/compatibility/aspnet-core/10/razor-runtime-compilation-obsolete. We should add a note to the Razor runtime compilation doc clarifying that it is obsolete and recommend using Hot Reload instead for development scenarios.

Page URL

https://learn.microsoft.com/en-us/aspnet/core/mvc/views/view-compilation?view=aspnetcore-10.0&tabs=visual-studio

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/mvc/views/view-compilation.md

Document ID

16438f35-f35d-c097-0903-ec17e83e051e

Platform Id

de165183-f986-f872-0447-6c3550b1c278

Article author

@tdykstra

Metadata

• ID: 8a83deb2-e035-bb66-be4f-68709bcad341
• PlatformId: de165183-f986-f872-0447-6c3550b1c278
• Service: aspnet-core
• Sub-service: mvc

Related Issues

---

Associated WorkItem - 551116

[wadepickett]

@tdykstra

[tdykstra]

🤖 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 or final decision. A maintainer will review and may adjust the proposed approach.

---

This preliminary assessment report was run by: @tdykstra
Date: 2026-01-29
Issue: 36658
Model: GitHub Copilot

---

Issue Analysis: Add note to the Razor runtime compilation doc that it is obsolete

✅ Issue Validation

Status: Valid and actionable

📋 Issue Summary

Razor runtime compilation was obsoleted in .NET 10, but the “Razor file compilation in ASP.NET Core” article currently discusses enabling runtime compilation without clearly stating its obsolescence status for .NET 10+ readers. The issue requests adding a note in the article to clarify that runtime compilation is obsolete (in .NET 10) and to recommend using Hot Reload for development scenarios.

This is a documentation-only change, in scope for ASP.NET Core docs, and can be addressed by updating the existing article.

🔎 Information gathered

• Issue: Add note to the Razor runtime compilation doc that it is obsolete #36658
• Published doc (target): https://learn.microsoft.com/en-us/aspnet/core/mvc/views/view-compilation?view=aspnetcore-10.0&tabs=visual-studio
• Source file: aspnetcore/mvc/views/view-compilation.md
• External reference: .NET compatibility note: https://learn.microsoft.com/dotnet/core/compatibility/aspnet-core/10/razor-runtime-compilation-obsolete

📁 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/mvc/views/view-compilation.md	13-35	Intro + first NOTE block (runtime compilation bullets)
Main article	aspnetcore/mvc/views/view-compilation.md	29-34	Hot Reload mention + NOTE recommending Hot Reload

📝 Preliminary Change Assessment

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

Potential documentation updates (primary)

File: aspnetcore/mvc/views/view-compilation.md

There are two obvious places to add an “obsolete in .NET 10” callout:

Option A (recommended): Update the first NOTE block near the top (most visible)

Location: Lines 17-24 (the NOTE block titled “Runtime compilation:”)
Type: Add a bullet and/or add a sentence with link to the compatibility note.

Current content (lines 17-24):

> [!NOTE]
> Runtime compilation:
> * Isn't supported for Razor components of Blazor apps.
> * Doesn't support [global using directives](/dotnet/csharp/whats-new/csharp-10#global-using-directives).
> * Doesn't support [implicit using directives](/dotnet/core/tutorials/top-level-templates#implicit-using-directives).
> * Disables [.NET Hot Reload](xref:test/hot-reload).
> * Is recommended for development, not for production.

Suggested direction (example text):

> [!NOTE]
> Runtime compilation:
> ...
> * Is obsolete in .NET 10. For development scenarios, prefer [.NET Hot Reload](xref:test/hot-reload). For details, see the compatibility note: https://learn.microsoft.com/dotnet/core/compatibility/aspnet-core/10/razor-runtime-compilation-obsolete

Option B (secondary): Strengthen the later NOTE where Hot Reload is already recommended

Location: Lines 31-33 (NOTE: “When enabled, runtime compilation disables Hot Reload…”)
Type: Add an “obsolete in .NET 10” sentence + link.

Current content (lines 31-33):

> [!NOTE]
> When enabled, runtime compilation disables [.NET Hot Reload](xref:test/hot-reload). We recommend using Hot Reload instead of Razor runtime compilation during development.

Suggested direction (example text):

> [!NOTE]
> When enabled, runtime compilation disables [.NET Hot Reload](xref:test/hot-reload).
> Razor runtime compilation is obsolete in .NET 10. We recommend using Hot Reload instead for development scenarios.
> For details, see: https://learn.microsoft.com/dotnet/core/compatibility/aspnet-core/10/razor-runtime-compilation-obsolete

🎯 Suggested Action Plan

For documentation team review

1. Confirm intended guidance for .NET 10 view of the article

   • Verify the published doc at:
     • https://learn.microsoft.com/en-us/aspnet/core/mvc/views/view-compilation?view=aspnetcore-10.0&tabs=visual-studio
   • Ensure the note clearly communicates “obsolete in .NET 10” without implying the feature is removed (unless removed is also true and should be stated).

2. Update the source file

   • File: aspnetcore/mvc/views/view-compilation.md
   • Primary edit location to consider:
     • NOTE block near top:

       AspNetCore.Docs/aspnetcore/mvc/views/view-compilation.md

       Lines 17 to 24 in 2716548

       	> [!NOTE]
       	> Runtime compilation:
       	> * Isn't supported for Razor components of Blazor apps.
       	> * Doesn't support [global using directives](/dotnet/csharp/whats-new/csharp-10#global-using-directives).
       	> * Doesn't support [implicit using directives](/dotnet/core/tutorials/top-level-templates#implicit-using-directives).
       	> * Disables [.NET Hot Reload](xref:test/hot-reload).
       	> * Is recommended for development, not for production.

   • Secondary edit location (optional/additional clarity):
     • Hot Reload NOTE:

       AspNetCore.Docs/aspnetcore/mvc/views/view-compilation.md

       Lines 31 to 33 in 2716548

       	> [!NOTE]
       	> When enabled, runtime compilation disables [.NET Hot Reload](xref:test/hot-reload). We recommend using Hot Reload instead of Razor runtime compilation during development.

3. Add cross-reference to the official compatibility note

   • Include: https://learn.microsoft.com/dotnet/core/compatibility/aspnet-core/10/razor-runtime-compilation-obsolete

4. Check for related content needing similar update

   • If other pages discuss enabling Razor runtime compilation, consider whether they also need an obsolescence note (search repo for “Razor.RuntimeCompilation” and “AddRazorRuntimeCompilation”).

5. Post results and label

   • After posting this report, apply the label:
     • ai-reviewed-issue-reported-action-plan

⚠️ Review Considerations

• The article uses monikers (:::moniker range=">= aspnetcore-6.0"), but does not currently split guidance for .NET 10 specifically. Consider whether the obsolescence note should be:
  • Always shown for >=6.0 readers, or
  • Only shown for >= aspnetcore-10.0 (if the repo uses/permits that moniker range here).
• Ensure wording matches platform guidance: “obsolete” typically means “still available but not recommended; may be removed in a future release”.

🔗 References

• Issue: Add note to the Razor runtime compilation doc that it is obsolete #36658
• Source file: https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/mvc/views/view-compilation.md
• Permalink used for line references: https://github.com/dotnet/AspNetCore.Docs/blob/2716548f33d83dc7caf4a9fbbe3b87150a41349c/aspnetcore/mvc/views/view-compilation.md
• Compatibility note: https://learn.microsoft.com/dotnet/core/compatibility/aspnet-core/10/razor-runtime-compilation-obsolete