ASP.NET Core Razor SDKASP.NET Core Razor SDK

作者:Rick AndersonBy Rick Anderson

概述Overview

.NET Core 2.1 SDK 或更高版本.NET Core 2.1 SDK or later 包含 Microsoft.NET.Sdk.Razor MSBuild SDK (Razor SDK)。The .NET Core 2.1 SDK 或更高版本.NET Core 2.1 SDK or later includes the Microsoft.NET.Sdk.Razor MSBuild SDK (Razor SDK). Razor SDK:The Razor SDK:

  • 需要生成、打包和发布包含 Razor 文件的项目,这些项目用于基于 ASP.NET Core MVC 的项目或 Blazor 项目。Is required to build, package, and publish projects containing Razor files for ASP.NET Core MVC-based or Blazor projects.
  • 包含一组预定义的目标、属性和项目,它们可用于自定义 Razor(.cshtml 或 .razor)文件的编译 。Includes a set of predefined targets, properties, and items that allow customizing the compilation of Razor (.cshtml or .razor) files.

Razor SDK 包含 Content 项,其 Include 属性设置为 **\*.cshtml**\*.razor 通配模式。The Razor SDK includes Content items with Include attributes set to the **\*.cshtml and **\*.razor globbing patterns. 发布匹配文件。Matching files are published.

  • 针对基于 ASP.NET Core MVC 的项目,围绕包含 Razor 文件的项目的生成、打包和发布设定了体验标准。Standardizes the experience around building, packaging, and publishing projects containing Razor files for ASP.NET Core MVC-based projects.
  • 包含一组预定义的目标、属性和项目,它们允许自定义 Razor 文件的编译。Includes a set of predefined targets, properties, and items that allow customizing the compilation of Razor files.

Razor SDK 包含 Content 项,其 Include 属性设置为 **\*.cshtml 通配模式。The Razor SDK includes a Content item with an Include attribute set to the **\*.cshtml globbing pattern. 发布匹配文件。Matching files are published.

先决条件Prerequisites

.NET Core 2.1 SDK 或更高版本.NET Core 2.1 SDK or later

使用 Razor SDKUse the Razor SDK

大多数 Web 应用不需要显式引用 Razor SDK。Most web apps aren't required to explicitly reference the Razor SDK.

若要使用 Razor SDK 生成包含 Razor 视图或 Razor Pages 的类库,建议从 Razor 类库 (RCL) 项目模板开始。To use the Razor SDK to build class libraries containing Razor views or Razor Pages, we recommend starting with the Razor class library (RCL) project template. 用于生成 Blazor (.razor) 文件的 RCL 至少需要引用 Microsoft.AspNetCore.Components 包。An RCL that's used to build Blazor (.razor) files minimally requires a reference to the Microsoft.AspNetCore.Components package. 用于生成 Razor 视图或页面(.cshtml 文件)的 RCL 至少需要面向 netcoreapp3.0 或更高版本,且其项目文件中至少具有指向 Microsoft.AspNetCore.App 元包FrameworkReferenceAn RCL that's used to build Razor views or pages (.cshtml files) minimally requires targeting netcoreapp3.0 or later and has a FrameworkReference to the Microsoft.AspNetCore.App metapackage in its project file.

若要使用 Razor SDK 来生成包含 Razor 视图或 Razor Pages 的类库,请执行以下操作:To use the Razor SDK to build class libraries containing Razor views or Razor Pages:

  • 使用 Microsoft.NET.Sdk.Razor 而非 Microsoft.NET.SdkUse Microsoft.NET.Sdk.Razor instead of Microsoft.NET.Sdk:

    <Project SDK="Microsoft.NET.Sdk.Razor">
      <!-- omitted for brevity -->
    </Project>
    
  • 通常,对 Microsoft.AspNetCore.Mvc 的包引用需要接收生成和编译 Razor Pages 和 Razor 视图所需的其他依赖项。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
    • Microsoft.AspNetCore.Mvc.Razor

    Microsoft.AspNetCore.Razor.Design 包为项目提供 Razor 编译任务和目标。The Microsoft.AspNetCore.Razor.Design package provides the Razor compilation tasks and targets for the project.

    前面的包包含在 Microsoft.AspNetCore.Mvc 中。The preceding packages are included in Microsoft.AspNetCore.Mvc. 以下标记显示了使用 Razor SDK 为 ASP.NET Core Razor Pages 应用生成 Razor 文件的项目文件:The following markup shows a project file that uses the Razor SDK to build Razor files for an ASP.NET Core Razor Pages app:

    <Project Sdk="Microsoft.NET.Sdk.Razor">
    
      <PropertyGroup>
        <TargetFramework>netcoreapp2.1</TargetFramework>
      </PropertyGroup>
    
      <ItemGroup>
        <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.1.3" />
      </ItemGroup>
    
    </Project>
    

警告

Microsoft.AspNetCore.Razor.DesignMicrosoft.AspNetCore.Mvc.Razor.Extensions 包均包含在 Microsoft.AspNetCore.App 元包中。The Microsoft.AspNetCore.Razor.Design and Microsoft.AspNetCore.Mvc.Razor.Extensions packages are included in the Microsoft.AspNetCore.App metapackage. 但无版本的 Microsoft.AspNetCore.App 包引用可为不含最新版 Microsoft.AspNetCore.Razor.Design 的应用提供元包。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. 项目必须引用一致版本的 Microsoft.AspNetCore.Razor.Design(或 Microsoft.AspNetCore.Mvc),以便包含 Razor 的最新生成时修补程序。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. 有关详细信息,请参阅此 GitHub 问题For more information, see this GitHub issue.

属性Properties

以下属性控制项目生成过程中 Razor 的 SDK 行为:The following properties control the Razor's SDK behavior as part of a project build:

  • RazorCompileOnBuild:若为 true,则在生成项目的过程中,编译并发出 Razor 程序集。RazorCompileOnBuild: When true, compiles and emits the Razor assembly as part of building the project. 默认为 trueDefaults to true.
  • RazorCompileOnPublish:若为 true,则在发布项目的过程中,编译并发出 Razor 程序集。RazorCompileOnPublish: When true, compiles and emits the Razor assembly as part of publishing the project. 默认为 trueDefaults to true.

下表中的属性和项用于配置 Razor SDK 的输入和输出。The properties and items in the following table are used to configure inputs and output to the Razor SDK.

警告

从 ASP.NET Core 3.0 开始,如果禁用项目文件中的 RazorCompileOnBuildRazorCompileOnPublish MSBuild 属性,则不会默认提供 MVC 视图或 Razor Pages。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. 如果应用依赖运行时编译来处理 .cshtml 文件,则应用程序必须添加对 Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation 包的显式引用。Applications must add an explicit reference to the Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation package if the app relies on runtime compilation to process .cshtml files.

Items 描述Description
RazorGenerate 输入到代码生成的项元素(.cshtml 文件)。Item elements (.cshtml files) that are inputs to code generation.
RazorComponent 输入到 Razor 组件代码生成的项元素(.razor 文件)。Item elements (.razor files) that are inputs to Razor component code generation.
RazorCompile 输入到 Razor 编译目标的项元素(.cs 文件)。Item elements (.cs files) that are inputs to Razor compilation targets. 使用此 ItemGroup 指定要编译到 Razor 程序集中的其他文件。Use this ItemGroup to specify additional files to be compiled into the Razor assembly.
RazorTargetAssemblyAttribute 用于编码生成 Razor 程序集属性的项元素。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 作为嵌入的资源添加到生成的 Razor 程序集中的项元素。Item elements added as embedded resources to the generated Razor assembly.
PropertyProperty 描述Description
RazorTargetName Razor 生成的程序集的文件名(不含扩展名)。File name (without extension) of the assembly produced by Razor.
RazorOutputPath Razor 输出目录。The Razor output directory.
RazorCompileToolset 用于确定用于生成 Razor 程序集的工具集。Used to determine the toolset used to build the Razor assembly. 有效值为 ImplicitRazorSDKPrecompilationToolValid values are Implicit, RazorSDK, and PrecompilationTool.
EnableDefaultContentItemsEnableDefaultContentItems 默认值为 trueDefault is true. 若为 true,则包含 web.config、.json 和 .cshtml 文件作为项目中的内容 。When true, includes web.config, .json, and .cshtml files as content in the project. 通过 Microsoft.NET.Sdk.Web 引用时,还包括 wwwroot 下的文件和配置文件。When referenced via Microsoft.NET.Sdk.Web, files under wwwroot and config files are also included.
EnableDefaultRazorGenerateItems true 时,包括 RazorGenerate 项中 Content 项的 .cshtml 文件。When true, includes .cshtml files from Content items in RazorGenerate items.
GenerateRazorTargetAssemblyInfo 若为 true,则生成 .cs 文件(其中包含由 RazorAssemblyAttribute 指定的属性),并将文件包含在编译输出中。When true, generates a .cs file containing attributes specified by RazorAssemblyAttribute and includes the file in the compile output.
EnableDefaultRazorTargetAssemblyInfoAttributes true 时,将一组默认的程序集属性添加到 RazorAssemblyAttributeWhen true, adds a default set of assembly attributes to RazorAssemblyAttribute.
CopyRazorGenerateFilesToPublishDirectory 若为 true,则将 RazorGenerate 项 (.cshtml) 文件复制到发布目录。When true, copies RazorGenerate items (.cshtml) files to the publish directory. 如果在生成时或发布时参与编译,则通常发布的应用无需 Razor 文件。Typically, Razor files aren't required for a published app if they participate in compilation at build-time or publish-time. 默认为 falseDefaults to false.
PreserveCompilationReferences true 时,将引用程序集项复制到发布目录。When true, copy reference assembly items to the publish directory. 如果在生成时或发布时出现 Razor 编译,则通常发布的应用无需引用程序集。Typically, reference assemblies aren't required for a published app if Razor compilation occurs at build-time or publish-time. 如果发布的应用需要运行时编译,则设置为 trueSet to true if your published app requires runtime compilation. 例如,如果应用在运行时修改 .cshtml 文件或使用嵌入视图,则将值设置为 trueFor example, set the value to true if the app modifies .cshtml files at runtime or uses embedded views. 默认为 falseDefaults to false.
IncludeRazorContentInPack 若为 true,则所有 Razor 内容项(.cshtml 文件)标记为包含在生成的 NuGet 包中。When true, all Razor content items (.cshtml files) are marked for inclusion in the generated NuGet package. 默认为 falseDefaults to false.
EmbedRazorGenerateSources true 时,将 RazorGenerate (.cshtml) 项作为嵌入的文件添加到生成的 Razor 程序集中。When true, adds RazorGenerate (.cshtml) items as embedded files to the generated Razor assembly. 默认为 falseDefaults to false.
UseRazorBuildServer true 时,使用永久生成服务器进程来卸载代码生成工作。When true, uses a persistent build server process to offload code generation work. 默认值为 UseSharedCompilationDefaults to the value of UseSharedCompilation.
GenerateMvcApplicationPartsAssemblyAttributes 若为 true,则 SDK 会生成 MVC 在运行时使用的其他属性,以执行应用程序部件的发现。When true, the SDK generates additional attributes used by MVC at runtime to perform application part discovery.
DefaultWebContentItemExcludes 要从面向 Web 或 Razor SDK 的项目的 Content 项组中排除的项元素的 glob 模式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 若为 true,则 .config 和 .json 文件不会复制到生成输出目录 。When true, .config and .json files do not get copied to the build output directory.
AddRazorSupportForMvc 若为 true,则配置 Razor SDK,以添加对生成包含 MVC 视图或 Razor Pages 的应用程序时所需的 MVC 配置的支持。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. 对于面向 Web SDK 的 .NET Core 3.0 或更高版本的项目,隐式设置该属性This property is implicitly set for .NET Core 3.0 or later projects targeting the Web SDK
RazorLangVersion 要面向的 Razor 语言版本。The version of the Razor Language to target.
PropertyProperty 描述Description
RazorTargetName Razor 生成的程序集的文件名(不含扩展名)。File name (without extension) of the assembly produced by Razor.
RazorOutputPath Razor 输出目录。The Razor output directory.
RazorCompileToolset 用于确定用于生成 Razor 程序集的工具集。Used to determine the toolset used to build the Razor assembly. 有效值为 ImplicitRazorSDKPrecompilationToolValid values are Implicit, RazorSDK, and PrecompilationTool.
EnableDefaultContentItemsEnableDefaultContentItems 默认值为 trueDefault is true. 若为 true,则包含 web.config、.json 和 .cshtml 文件作为项目中的内容 。When true, includes web.config, .json, and .cshtml files as content in the project. 通过 Microsoft.NET.Sdk.Web 引用时,还包括 wwwroot 下的文件和配置文件。When referenced via Microsoft.NET.Sdk.Web, files under wwwroot and config files are also included.
EnableDefaultRazorGenerateItems true 时,包括 RazorGenerate 项中 Content 项的 .cshtml 文件。When true, includes .cshtml files from Content items in RazorGenerate items.
GenerateRazorTargetAssemblyInfo 若为 true,则生成 .cs 文件(其中包含由 RazorAssemblyAttribute 指定的属性),并将文件包含在编译输出中。When true, generates a .cs file containing attributes specified by RazorAssemblyAttribute and includes the file in the compile output.
EnableDefaultRazorTargetAssemblyInfoAttributes true 时,将一组默认的程序集属性添加到 RazorAssemblyAttributeWhen true, adds a default set of assembly attributes to RazorAssemblyAttribute.
CopyRazorGenerateFilesToPublishDirectory 若为 true,则将 RazorGenerate 项 (.cshtml) 文件复制到发布目录。When true, copies RazorGenerate items (.cshtml) files to the publish directory. 如果在生成时或发布时参与编译,则通常发布的应用无需 Razor 文件。Typically, Razor files aren't required for a published app if they participate in compilation at build-time or publish-time. 默认为 falseDefaults to false.
CopyRefAssembliesToPublishDirectory true 时,将引用程序集项复制到发布目录。When true, copy reference assembly items to the publish directory. 如果在生成时或发布时出现 Razor 编译,则通常发布的应用无需引用程序集。Typically, reference assemblies aren't required for a published app if Razor compilation occurs at build-time or publish-time. 如果发布的应用需要运行时编译,则设置为 trueSet to true if your published app requires runtime compilation. 例如,如果应用在运行时修改 .cshtml 文件或使用嵌入视图,则将值设置为 trueFor example, set the value to true if the app modifies .cshtml files at runtime or uses embedded views. 默认为 falseDefaults to false.
IncludeRazorContentInPack 若为 true,则所有 Razor 内容项(.cshtml 文件)标记为包含在生成的 NuGet 包中。When true, all Razor content items (.cshtml files) are marked for inclusion in the generated NuGet package. 默认为 falseDefaults to false.
EmbedRazorGenerateSources true 时,将 RazorGenerate (.cshtml) 项作为嵌入的文件添加到生成的 Razor 程序集中。When true, adds RazorGenerate (.cshtml) items as embedded files to the generated Razor assembly. 默认为 falseDefaults to false.
UseRazorBuildServer true 时,使用永久生成服务器进程来卸载代码生成工作。When true, uses a persistent build server process to offload code generation work. 默认值为 UseSharedCompilationDefaults to the value of UseSharedCompilation.
GenerateMvcApplicationPartsAssemblyAttributes 若为 true,则 SDK 会生成 MVC 在运行时使用的其他属性,以执行应用程序部件的发现。When true, the SDK generates additional attributes used by MVC at runtime to perform application part discovery.
DefaultWebContentItemExcludes 要从面向 Web 或 Razor SDK 的项目的 Content 项组中排除的项元素的 glob 模式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 若为 true,则 .config 和 .json 文件不会复制到生成输出目录 。When true, .config and .json files do not get copied to the build output directory.
AddRazorSupportForMvc 若为 true,则配置 Razor SDK,以添加对生成包含 MVC 视图或 Razor Pages 的应用程序时所需的 MVC 配置的支持。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. 对于面向 Web SDK 的 .NET Core 3.0 或更高版本的项目,隐式设置该属性This property is implicitly set for .NET Core 3.0 or later projects targeting the Web SDK
RazorLangVersion 要面向的 Razor 语言版本。The version of the Razor Language to target.

有关属性的详细信息,请参阅 MSBuild 属性For more information on properties, see MSBuild properties.

目标Targets

Razor SDK 定义两个主要目标:The Razor SDK defines two primary targets:

  • RazorGenerate:代码基于 RazorGenerate 项元素生成 .cs 文件。RazorGenerate: Code generates .cs files from RazorGenerate item elements. 使用 RazorGenerateDependsOn 属性指定可在此目标之前或之后运行的其他目标。Use the RazorGenerateDependsOn property to specify additional targets that can run before or after this target.
  • RazorCompile:将生成的 .cs 文件编译到 Razor 程序集中。RazorCompile: Compiles generated .cs files in to a Razor assembly. 使用 RazorCompileDependsOn 指定可在此目标之前或之后运行的其他目标。Use the RazorCompileDependsOn to specify additional targets that can run before or after this target.
  • RazorComponentGenerate:代码为 RazorComponent 项元素生成 .cs 文件。RazorComponentGenerate: Code generates .cs files for RazorComponent item elements. 使用 RazorComponentGenerateDependsOn 属性指定可在此目标之前或之后运行的其他目标。Use the RazorComponentGenerateDependsOn property to specify additional targets that can run before or after this target.

Razor 视图的运行时编译Runtime compilation of Razor views

  • 默认情况下,Razor SDK 不发布执行运行时编译所需的引用程序集。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. CopyRefAssembliesToPublishDirectory 设置为 true,以继续发布引用程序集。Set CopyRefAssembliesToPublishDirectory to true to continue publishing reference assemblies.

  • 对于 Web 应用,请确保应用面向 Microsoft.NET.Sdk.Web SDK。For a web app, ensure your app is targeting the Microsoft.NET.Sdk.Web SDK.

Razor 语言版本 language version

面向 Microsoft.NET.Sdk.Web SDK 时,Razor 语言版本是从应用的目标框架版本推断出来的。When targeting the Microsoft.NET.Sdk.Web SDK, the Razor language version is inferred from the app's target framework version. 对于面向 Microsoft.NET.Sdk.Razor SDK 的项目,或应用需要不同于推断值的 Razor 语言版本的极少数情况下,可在应用的项目文件中设置 <RazorLangVersion> 属性来配置版本:For projects targeting the Microsoft.NET.Sdk.Razor SDK or in the rare case that the app requires a different Razor language version than the inferred value, a version can be configured by setting the <RazorLangVersion> property in the app's project file:

<PropertyGroup>
  <RazorLangVersion>{VERSION}</RazorLangVersion>
</PropertyGroup>

Razor 的语言版本与其面向的运行时版本紧密集成。's language version is tightly integrated with the version of the runtime that it was built for. 不支持面向不专为运行时而设计的语言版本,这可能会产生生成错误。Targeting a language version that isn't designed for the runtime is unsupported and likely produces build errors.

其他资源Additional resources