daohualiuxiang
/
AspNetCore.Docs
mirror of https://github.com/dotnet/AspNetCore.Docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
AspNetCore.Docs/aspnetcore/razor-pages/sdk.md

7.1 KiB
Raw Blame History

title author description monikerRange ms.author ms.custom ms.date uid
ASP.NET Core Razor SDK Rick-Anderson Learn how Razor Pages in ASP.NET Core makes coding page-focused scenarios easier and more productive than using MVC. >= aspnetcore-2.1 riande mvc, seodec18 10/25/2018 razor-pages/sdk

ASP.NET Core Razor SDK

By Rick Anderson

The [!INCLUDE] includes the Microsoft.NET.Sdk.Razor MSBuild SDK (Razor SDK). The Razor SDK:

  • Standardizes the experience around building, packaging, and publishing projects containing 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.

Prerequisites

[!INCLUDE]

Using the Razor SDK

Most web apps aren't required to explicitly reference the Razor SDK.

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:

    <Project SDK="Microsoft.NET.Sdk.Razor">
  ...
</Project>

  • Typically, a package reference to Microsoft.AspNetCore.Mvc is required to receive additional dependencies that are required to build and compile Razor Pages and Razor views. At a minimum, your project should add package references to:

    • Microsoft.AspNetCore.Razor.Design
    • Microsoft.AspNetCore.Mvc.Razor.Extensions

    The Microsoft.AspNetCore.Razor.Design package provides the Razor compilation tasks and targets for the project.

    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]

::: moniker range="= aspnetcore-2.1"

[!WARNING] The Microsoft.AspNetCore.Razor.Design and Microsoft.AspNetCore.Mvc.Razor.Extensions packages are included in the Microsoft.AspNetCore.App metapackage. However, the version-less Microsoft.AspNetCore.App package reference provides a metapackage to the app that doesn't include the latest version of Microsoft.AspNetCore.Razor.Design. Projects must reference a consistent version of Microsoft.AspNetCore.Razor.Design (or Microsoft.AspNetCore.Mvc) so that the latest build-time fixes for Razor are included. For more information, see this GitHub issue.

::: moniker-end

Properties

The following properties control the Razor's SDK behavior as part of a project build:

  • RazorCompileOnBuild – When true, compiles and emits the Razor assembly as part of building the project. Defaults to true.
  • RazorCompileOnPublish – When true, compiles and emits the Razor assembly as part of publishing the project. Defaults to true.

The properties and items in the following table are used to configure inputs and output to the Razor SDK.

Items Description
RazorGenerate Item elements (.cshtml files) that are inputs to code generation targets.
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 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.
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.
CopyRefAssembliesToPublishDirectory 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.

For more information on properties, see MSBuild properties.

Targets

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.

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.

  • For a web app, ensure your app is targeting the Microsoft.NET.Sdk.Web SDK.