Razor compilation APIs exposing Roslyn types being obsoleted in 2.2.0 and removed in 3.0.0

[danroth27]

As part of the 2.1.0 release, ASP.NET Core added support for build time compilation of cshtml files (Razor Views & Razor Pages). This feature is on by default and allows build time verification of the correctness of Razor files, and also faster startup performance. Additionally, MVC watches for changes to cshtml files and seamlessly updates build-time compiled views with runtime compiled views. This allows editing cshtml files and then refreshing the browser to see the changes.

MVC uses the app's compilation context, details about the references and settings that were used to compile the source code (.cs) in the app, to compile views at runtime. In addition to the compilation context, MVC exposes options such as RazorViewEngineOptions.CompilationCallback and AdditionalCompilationReferences that allow configuring compilation specifically for runtime.

Runtime specific customizations are unavailable at build time and consequently the two outputs could be different.

To address this inconsistency, we plan on removing APIs in MVC that change or modify runtime compilation. For 2.2.0, we're marking these APIs obsolete with the intent to remove them in 3.0.0. This is the list of affected APIs:

• Properties on Microsoft.AspNetCore.Mvc.Razor.RazorViewEngineOptions

  • AdditionalCompilationReferences
  • CompilationCallback

• Microsoft.AspNetCore.Mvc.Razor.Compilation.MetadataReferenceFeature

• Microsoft.AspNetCore.Mvc.Razor.Compilation.MetadataReferenceFeatureProvider

• Microsoft.AspNetCore.Mvc.Razor.Compilation.RazorReferenceManager

No changes are required to your application if it does not use these APIs.

Apps using these APIs to add assembly references to the compilation context for runtime compilation should instead use ApplicationPartManager.AddApplicationPart to add application parts for each assembly reference, or switch to a built-time compilation model (see Create reusable UI using the Razor Class Library project).

Other scenarios blocked by the removal of these APIs and not covered by alternative MVC features should raised in the linked discussion issue.

For discussion, use https://github.com/aspnet/Mvc/issues/8177