diff --git a/aspnetcore/razor-pages/sdk.md b/aspnetcore/razor-pages/sdk.md index 9df091e1dd..d50be401ab 100644 --- a/aspnetcore/razor-pages/sdk.md +++ b/aspnetcore/razor-pages/sdk.md @@ -16,8 +16,16 @@ By [Rick Anderson](https://twitter.com/RickAndMSFT) The [!INCLUDE[](~/includes/2.1-SDK.md)] includes the `Microsoft.NET.Sdk.Razor` MSBuild SDK (Razor SDK). The Razor SDK: +::: moniker range=">= aspnetcore-2.1 <= aspnetcore-2.2" * Standardizes the experience around building, packaging, and publishing projects containing [Razor](xref:mvc/views/razor) files for ASP.NET Core MVC-based projects. * Includes a set of predefined targets, properties, and items that allow customizing the compilation of Razor files. +::: moniker-end + +::: moniker range=">= aspnetcore-3.0" +* is required to build, package, and publish projects containing [Razor](xref:mvc/views/razor) files for ASP.NET Core MVC-based projects, 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. +::: moniker-end + ::: moniker range=">= aspnetcore-2.1 <= aspnetcore-2.2" @@ -39,6 +47,7 @@ The Razor SDK includes `` elements with `Include` attributes set to the Most web apps aren't required to explicitly reference the Razor SDK. +::: moniker range=">= aspnetcore-2.1 <= aspnetcore-2.2" To use the Razor SDK to build class libraries containing Razor views or Razor Pages: * Use `Microsoft.NET.Sdk.Razor` instead of `Microsoft.NET.Sdk`: @@ -60,6 +69,13 @@ To use the Razor SDK to build class libraries containing Razor views or Razor Pa The preceding packages are included in `Microsoft.AspNetCore.Mvc`. The following markup shows a project file that uses the Razor SDK to build Razor files for an ASP.NET Core Razor Pages app: [!code-xml[](sdk/sample/RazorSDK.csproj)] + +::: moniker-end + +::: moniker range=">= aspnetcore-3.0" +To use the Razor SDK to build class libraries containing Razor views or Razor Pages we recommend starting with the Razor Class Library project template. A Razor class library that is used to build Blazor (.razor) files will at minimum require a reference to the `Microsoft.AspNetCore.Components` package. A Razor class library that is used to build Razor views or pages (.cshtml files), will require targeting `netcoreapp3.0` or newer and have a `FrameworkReference` to `Microsoft.AspNetCore.App`. + +::: moniker-end ::: moniker range="= aspnetcore-2.1" @@ -77,9 +93,16 @@ 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. +::: moniker range=">= aspnetcore-3.0" +> [!WARNING] +Starting with ASP.NET Core 3.0, MVC Views or Razor Pages will not be served by default if `RazorCompileOnBuild` or `RazorCompileOnPublish` is disabled. Applications must add an explicit reference to `Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation` package to add support for runtime compilation if they rely on runtime compilation to process cshtml files. +::: moniker-end + + | Items | Description | | ----- | ----------- | -| `RazorGenerate` | Item elements (*.cshtml* files) that are inputs to code generation targets. | +| `RazorGenerate` | Item elements (*.cshtml* files) that are inputs to code generation. | +| `RazorComponent` | Item elements (*.razor* files) that are inputs to 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. | @@ -98,6 +121,7 @@ The properties and items in the following table are used to configure inputs and | `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. | For more information on properties, see [MSBuild properties](/visualstudio/msbuild/msbuild-properties). @@ -107,6 +131,7 @@ The Razor SDK defines two primary targets: * `RazorGenerate` – Code generates *.cs* files from `RazorGenerate` item elements. Use `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 `RazorCompileDependsOn` to specify additional targets that can run before or after this target. +* `RazorComponentGenerate` – Code generates *.cs* files for `RazorComponent` item elements. Use `RazorComponentGenerateDependsOn` property to specify additional targets that can run before or after this target. ### Runtime compilation of Razor views @@ -124,6 +149,8 @@ When targeting the `Microsoft.NET.Sdk.Web` SDK, the Razor language version is in ``` +Razor's language version is tightly integrated with the version of the runtime that it was built for. Targeting a language version that is not designed for the runtime is unsupported, and will likely produce build errors. + ## Additional resources * [Additions to the csproj format for .NET Core](/dotnet/core/tools/csproj)