diff --git a/aspnetcore/migration/50-to-60.md b/aspnetcore/migration/50-to-60.md index 9a5a184c9e..c6306d5d30 100644 --- a/aspnetcore/migration/50-to-60.md +++ b/aspnetcore/migration/50-to-60.md @@ -77,6 +77,31 @@ For apps using Docker, update your *Dockerfile* `FROM` statements and scripts. U + docker pull mcr.microsoft.com/dotnet/aspnet:6.0 ``` +## Changes to the ASP.NET Core Razor SDK + +The Razor compiler now leverages the new [source generators feature](https://devblogs.microsoft.com/dotnet/introducing-c-source-generators/) to generate compiled C# files from the Razor views and pages in a project. In previous versions: + +* The compilation relied on the `RazorGenerate` and `RazorCompile` targets to produce the generated code. These targets are no longer valid. In .NET 6, both code generation and compilation are supported by a single call to the compiler. `RazorComponentGenerateDependsOn` is still supported to specify dependencies that are required before the build runs. +* A separate Razor assembly, `AppName.Views.dll`, was generated that contained the compiled view types in an application. This behavior has been deprecated and a single assembly `AppName.dll` is produced that contains both the app types and the generated views. +* The app types in `AppName.Views.dll` were public. In .NET 6, the app types are in `AppName.dll` but are `internal sealed`. Apps doing type discover on `AppName.Views.dll` won't be able to do type discover on `AppName.dll`. The following shows the API change: + +```diff +- public class Views_Home_Index : global::Microsoft.AspNetCore.Mvc.Razor.RazorPage ++ internal sealed class Views_Home_Index : global::Microsoft.AspNetCore.Mvc.Razor.RazorPage +``` + +Make the following changes: + +* The following properties are no longer applicable with the single-step compilation model. + * `RazorTargetAssemblyAttribute` + * `RazorTargetName` + * `EnableDefaultRazorTargetAssemblyInfoAttributes` + * `UseRazorBuildServer` + * `GenerateRazorTargetAssemblyInfo` + * `GenerateMvcApplicationPartsAssemblyAttributes` + +For more information, see [Razor compiler no longer produces a Views assembly](https://github.com/aspnet/Announcements/issues/459). + ## Review breaking changes For breaking changes from .NET 5.0 to .NET 6.0, see [Breaking changes for migration from version 5.0 to 6.0](/dotnet/core/compatibility/6.0). ASP.NET Core and Entity Framework Core are also included in the list. diff --git a/aspnetcore/razor-pages/sdk.md b/aspnetcore/razor-pages/sdk.md index fea40da5d6..95f5fc4192 100644 --- a/aspnetcore/razor-pages/sdk.md +++ b/aspnetcore/razor-pages/sdk.md @@ -17,17 +17,16 @@ By [Rick Anderson](https://twitter.com/RickAndMSFT) ::: moniker range=">= aspnetcore-6.0" - -The [!INCLUDE[](~/includes/2.1-SDK.md)] includes the `Microsoft.NET.Sdk.Razor` MSBuild SDK (Razor SDK). The Razor SDK: +The [!INCLUDE[](~/includes/6.0-SDK.md)] includes the `Microsoft.NET.Sdk.Razor` MSBuild SDK (Razor SDK). The Razor SDK: * Is required to build, package, and publish projects containing [Razor](xref:mvc/views/razor) files for ASP.NET Core MVC-based or [Blazor](xref:blazor/index) projects. -* Includes a set of predefined targets, properties, and items that allow customizing the compilation of Razor (*.cshtml* or *.razor*) files. +* Includes a set of predefined properties, and items that allow customizing the compilation of Razor (*.cshtml* or *.razor*) files. The Razor SDK includes `Content` items with `Include` attributes set to the `**\*.cshtml` and `**\*.razor` globbing patterns. Matching files are published. ## Prerequisites -[!INCLUDE[](~/includes/2.1-SDK.md)] +[!INCLUDE[](~/includes/6.0-SDK.md)] ## Use the Razor SDK @@ -44,50 +43,37 @@ The following properties control the Razor's SDK behavior as part of a project b The properties and items in the following table are used to configure inputs and output to the Razor SDK. -> [!WARNING] -> Starting with ASP.NET Core 3.0, MVC Views or Razor Pages aren't served by default if the `RazorCompileOnBuild` or `RazorCompileOnPublish` MSBuild properties in the project file are disabled. Applications must add an explicit reference to the [Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation](https://www.nuget.org/packages/Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation) package if the app relies on runtime compilation to process *.cshtml* files. - | Items | Description | | ----- | ----------- | | `RazorGenerate` | Item elements (*.cshtml* files) that are inputs to code generation. | | `RazorComponent` | Item elements (*.razor* files) that are inputs to Razor component code generation. | | `RazorCompile` | Item elements (*.cs* files) that are inputs to Razor compilation targets. Use this `ItemGroup` to specify additional files to be compiled into the Razor assembly. | -| `RazorTargetAssemblyAttribute` | Item elements used to code generate attributes for the Razor assembly. For example:
`RazorAssemblyAttribute`
`Include="System.Reflection.AssemblyMetadataAttribute"`
`_Parameter1="BuildSource" _Parameter2="https://docs.microsoft.com/">` | | `RazorEmbeddedResource` | Item elements added as embedded resources to the generated Razor assembly. | | Property | Description | | -------- | ----------- | -| `RazorTargetName` | File name (without extension) of the assembly produced by Razor. | | `RazorOutputPath` | The Razor output directory. | | `RazorCompileToolset` | Used to determine the toolset used to build the Razor assembly. Valid values are `Implicit`, `RazorSDK`, and `PrecompilationTool`. | | [EnableDefaultContentItems](https://github.com/aspnet/websdk/blob/rel-2.0.0/src/ProjectSystem/Microsoft.NET.Sdk.Web.ProjectSystem.Targets/netstandard1.0/Microsoft.NET.Sdk.Web.ProjectSystem.targets#L21) | Default is `true`. When `true`, includes *web.config*, *.json*, and *.cshtml* files as content in the project. When referenced via `Microsoft.NET.Sdk.Web`, files under *wwwroot* and config files are also included. | | `EnableDefaultRazorGenerateItems` | When `true`, includes *.cshtml* files from `Content` items in `RazorGenerate` items. | -| `GenerateRazorTargetAssemblyInfo` | When `true`, generates a *.cs* file containing attributes specified by `RazorAssemblyAttribute` and includes the file in the compile output. | -| `EnableDefaultRazorTargetAssemblyInfoAttributes` | When `true`, adds a default set of assembly attributes to `RazorAssemblyAttribute`. | +| `GenerateRazorTargetAssemblyInfo` | Not used in .NET 6 and later. | +| `EnableDefaultRazorTargetAssemblyInfoAttributes` | Not used in .NET 6 and later. | | `CopyRazorGenerateFilesToPublishDirectory` | When `true`, copies `RazorGenerate` items (*.cshtml*) files to the publish directory. Typically, Razor files aren't required for a published app if they participate in compilation at build-time or publish-time. Defaults to `false`. | | `PreserveCompilationReferences` | When `true`, copy reference assembly items to the publish directory. Typically, reference assemblies aren't required for a published app if Razor compilation occurs at build-time or publish-time. Set to `true` if your published app requires runtime compilation. For example, set the value to `true` if the app modifies *.cshtml* files at runtime or uses embedded views. Defaults to `false`. | | `IncludeRazorContentInPack` | When `true`, all Razor content items (*.cshtml* files) are marked for inclusion in the generated NuGet package. Defaults to `false`. | | `EmbedRazorGenerateSources` | When `true`, adds RazorGenerate (*.cshtml*) items as embedded files to the generated Razor assembly. Defaults to `false`. | -| `UseRazorBuildServer` | When `true`, uses a persistent build server process to offload code generation work. Defaults to the value of `UseSharedCompilation`. | -| `GenerateMvcApplicationPartsAssemblyAttributes` | When `true`, the SDK generates additional attributes used by MVC at runtime to perform application part discovery. | +| `GenerateMvcApplicationPartsAssemblyAttributes` | Not used in .NET 6 and later. | | `DefaultWebContentItemExcludes` | A globbing pattern for item elements that are to be excluded from the `Content` item group in projects targeting the Web or Razor SDK | | `ExcludeConfigFilesFromBuildOutput` | When `true`, *.config* and *.json* files do not get copied to the build output directory. | | `AddRazorSupportForMvc` | When `true`, configures the Razor SDK to add support for the MVC configuration that is required when building applications containing MVC views or Razor Pages. This property is implicitly set for .NET Core 3.0 or later projects targeting the Web SDK | | `RazorLangVersion` | The version of the Razor Language to target. | +| `EmitCompilerGeneratedFiles` | When set to `true`, the generated source files are written to disk. Setting to `true` is useful when debugging the compiler. The default is `false`. | For more information on properties, see [MSBuild properties](/visualstudio/msbuild/msbuild-properties). -### Targets - -The Razor SDK defines two primary targets: - -* `RazorGenerate`: Code generates *.cs* files from `RazorGenerate` item elements. Use the `RazorGenerateDependsOn` property to specify additional targets that can run before or after this target. -* `RazorCompile`: Compiles generated *.cs* files in to a Razor assembly. Use the `RazorCompileDependsOn` to specify additional targets that can run before or after this target. -* `RazorComponentGenerate`: Code generates *.cs* files for `RazorComponent` item elements. Use the `RazorComponentGenerateDependsOn` property to specify additional targets that can run before or after this target. - ### Runtime compilation of Razor views -* By default, the Razor SDK doesn't publish reference assemblies that are required to perform runtime compilation. This results in compilation failures when the application model relies on runtime compilation—for example, the app uses embedded views or changes views after the app is published. Set `CopyRefAssembliesToPublishDirectory` to `true` to continue publishing reference assemblies. +* By default, the Razor SDK doesn't publish reference assemblies that are required to perform runtime compilation. This results in compilation failures when the application model relies on runtime compilation—for example, the app uses embedded views or changes views after the app is published. Set `CopyRefAssembliesToPublishDirectory` to `true` to continue publishing reference assemblies. Both code generation and compilation are supported by a single call to the compiler. A single assembly is produced that contains the app types and the generated views. * For a web app, ensure your app is targeting the `Microsoft.NET.Sdk.Web` SDK.