通过

ASP.NET Core Razor SDK

  • 项目

作者：Rick Anderson

概述

.NET 6.0 SDK 包含 Microsoft.NET.Sdk.Razor MSBuild SDK (Razor SDK)。 Razor SDK：

  • 需要生成、打包和发布包含 Razor 文件的项目，这些项目用于基于 ASP.NET Core MVC 的项目或 Blazor 项目。
  • 包含一组预定义的属性和项目，它们可用于自定义 Razor（.cshtml 或 .razor）文件的编译。

Razor SDK 包含 Content 项，其 Include 属性设置为 **\*.cshtml 和 **\*.razor 通配模式。 发布匹配文件。

先决条件

.NET 6.0 SDK

使用 Razor SDK

大多数 Web 应用不需要显式引用 Razor SDK。

若要使用 Razor SDK 生成包含 Razor 视图或 Razor Pages 的类库，建议从 Razor 类库 (RCL) 项目模板开始。 用于生成 Blazor (.razor) 文件的 RCL 至少需要引用 Microsoft.AspNetCore.Components 包。 用于生成 Razor 视图或页面（.cshtml 文件）的 RCL 至少需要面向 netcoreapp3.0 或更高版本，且其项目文件中至少具有指向 Microsoft.AspNetCore.App 元包的 FrameworkReference。

属性

以下属性控制项目生成过程中 Razor 的 SDK 行为：

  • RazorCompileOnBuild：若为 true，则在生成项目的过程中，编译并发出 Razor 程序集。 默认为 true。
  • RazorCompileOnPublish：若为 true，则在发布项目的过程中，编译并发出 Razor 程序集。 默认为 true。
  • UseRazorSourceGenerator：默认为 true。 时间：true
    • 使用源生成进行编译。
    • 不创建 <app_name>.Views.dll。 视图包含在 <app_name>.dll 中。
    • 支持 .NET 热重载。

下表中的属性和项用于配置 Razor SDK 的输入和输出。

项 描述
RazorGenerate 输入到代码生成的项元素（.cshtml 文件）。
RazorComponent 输入到 Razor 组件代码生成的项元素（.razor 文件）。
RazorCompile 输入到 Razor 编译目标的项元素（.cs 文件）。 使用此 ItemGroup 指定要编译到 Razor 程序集中的其他文件。
RazorEmbeddedResource 作为嵌入的资源添加到生成的 Razor 程序集中的项元素。
Property 说明
RazorOutputPath Razor 输出目录。
RazorCompileToolset 用于确定用于生成 Razor 程序集的工具集。 有效值为 Implicit、RazorSDK 和 PrecompilationTool。
EnableDefaultContentItems 默认值为 true。 若为 true，则包含 web.config、.json 和 .cshtml 文件作为项目中的内容。 通过 Microsoft.NET.Sdk.Web 引用时，还包括 wwwroot 下的文件和配置文件。
EnableDefaultRazorGenerateItems 若为 true，则包括 RazorGenerate 项中 Content 项的 .cshtml 文件。
GenerateRazorTargetAssemblyInfo 不在 .NET 6 及更高版本中使用。
EnableDefaultRazorTargetAssemblyInfoAttributes 不在 .NET 6 及更高版本中使用。
CopyRazorGenerateFilesToPublishDirectory 若为 true，则将 RazorGenerate 项 (.cshtml) 文件复制到发布目录。 如果在生成时或发布时参与编译，则通常发布的应用无需 Razor 文件。 默认为 false。
PreserveCompilationReferences 为 true 时，将引用程序集项复制到发布目录。 如果在生成时或发布时出现 Razor 编译，则通常发布的应用无需引用程序集。 如果发布的应用需要运行时编译，则设置为 true。 例如，如果应用在运行时修改 .cshtml 文件或使用嵌入视图，则将值设置为 true。 默认为 false。
IncludeRazorContentInPack 若为 true，则所有 Razor 内容项（.cshtml 文件）标记为包含在生成的 NuGet 包中。 默认为 false。
EmbedRazorGenerateSources 当 true 时，将 RazorGenerate (.cshtml) 项作为嵌入的文件添加到生成的 Razor 程序集中。 默认为 false。
GenerateMvcApplicationPartsAssemblyAttributes 不在 .NET 6 及更高版本中使用。
DefaultWebContentItemExcludes 要从面向 Web 或 Razor SDK 的项目的 Content 项组中排除的项元素的 glob 模式
ExcludeConfigFilesFromBuildOutput 若为 true，则 .config 和 .json 文件不会复制到生成输出目录。
AddRazorSupportForMvc 若为 true，则配置 Razor SDK，以添加对生成包含 MVC 视图或 Razor Pages 的应用程序时所需的 MVC 配置的支持。 对于面向 Web SDK 的 .NET Core 3.0 或更高版本的项目，隐式设置该属性
RazorLangVersion 要面向的 Razor 语言版本。
EmitCompilerGeneratedFiles 设置为 true 时，生成的源文件将写入磁盘。 设置为 true 在调试编译器时很有用。 默认为 false。

有关属性的详细信息，请参阅 MSBuild 属性。

Razor 视图的运行时编译

  • 默认情况下，Razor SDK 不发布执行运行时编译所需的引用程序集。 当应用程序模型依赖于运行时编译时，这会导致编译失败—例如，应用在发布后使用嵌入视图或更改视图。 将 CopyRefAssembliesToPublishDirectory 设置为 true，以继续发布引用程序集。 对编译器的单个调用支持代码生成和编译。 生成一个包含应用类型和生成的视图的程序集。

  • 对于 Web 应用，请确保应用面向 Microsoft.NET.Sdk.Web SDK。

Razor 语言版本

面向 Microsoft.NET.Sdk.Web SDK 时，Razor 语言版本是从应用的目标框架版本推断出来的。 对于面向 Microsoft.NET.Sdk.Razor SDK 的项目，或应用需要不同于推断值的 Razor 语言版本的极少数情况下，可在应用的项目文件中设置 <RazorLangVersion> 属性来配置版本：

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

Razor 的语言版本与其面向的运行时版本紧密集成。 不支持面向不专为运行时而设计的语言版本，这可能会产生生成错误。

其他资源

.NET Core 2.1 SDK 或更高版本包含 Microsoft.NET.Sdk.Razor MSBuild SDK (Razor SDK)。 Razor SDK：

  • 需要生成、打包和发布包含 Razor 文件的项目，这些项目用于基于 ASP.NET Core MVC 的项目或 Blazor 项目。
  • 包含一组预定义的目标、属性和项目，它们允许自定义 Razor（.cshtml 或 .razor）文件的编译。

Razor SDK 包含 Content 项，其 Include 属性设置为 **\*.cshtml 和 **\*.razor 通配模式。 发布匹配文件。

先决条件

.NET Core 2.1 SDK 或更高版本

使用 Razor SDK

大多数 Web 应用不需要显式引用 Razor SDK。

若要使用 Razor SDK 生成包含 Razor 视图或 Razor Pages 的类库，建议从 Razor 类库 (RCL) 项目模板开始。 用于生成 Blazor (.razor) 文件的 RCL 至少需要引用 Microsoft.AspNetCore.Components 包。 用于生成 Razor 视图或页面（.cshtml 文件）的 RCL 至少需要面向 netcoreapp3.0 或更高版本，且其项目文件中至少具有指向 Microsoft.AspNetCore.App 元包的 FrameworkReference。

属性

以下属性控制项目生成过程中 Razor 的 SDK 行为：

  • RazorCompileOnBuild：若为 true，则在生成项目的过程中，编译并发出 Razor 程序集。 默认为 true。
  • RazorCompileOnPublish：若为 true，则在发布项目的过程中，编译并发出 Razor 程序集。 默认为 true。

下表中的属性和项用于配置 Razor SDK 的输入和输出。

警告

从 ASP.NET Core 3.0 开始，如果禁用项目文件中的 RazorCompileOnBuild 或 RazorCompileOnPublish MSBuild 属性，则不会默认提供 MVC 视图或 Razor Pages。 如果应用依赖运行时编译来处理 .cshtml 文件，则应用程序必须添加对 Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation 包的显式引用。

项 描述
RazorGenerate 输入到代码生成的项元素（.cshtml 文件）。
RazorComponent 输入到 Razor 组件代码生成的项元素（.razor 文件）。
RazorCompile 输入到 Razor 编译目标的项元素（.cs 文件）。 使用此 ItemGroup 指定要编译到 Razor 程序集中的其他文件。
RazorTargetAssemblyAttribute 用于编码生成 Razor 程序集属性的项元素。 例如：
RazorAssemblyAttribute
Include="System.Reflection.AssemblyMetadataAttribute"
_Parameter1="BuildSource" _Parameter2="https://learn.microsoft.com/">
RazorEmbeddedResource 作为嵌入的资源添加到生成的 Razor 程序集中的项元素。
Property 描述
RazorTargetName Razor 生成的程序集的文件名（不含扩展名）。
RazorOutputPath Razor 输出目录。
RazorCompileToolset 用于确定用于生成 Razor 程序集的工具集。 有效值为 Implicit、RazorSDK 和 PrecompilationTool。
EnableDefaultContentItems 默认值为 true。 若为 true，则包含 web.config、.json 和 .cshtml 文件作为项目中的内容。 通过 Microsoft.NET.Sdk.Web 引用时，还包括 wwwroot 下的文件和配置文件。
EnableDefaultRazorGenerateItems 若为 true，则包括 RazorGenerate 项中 Content 项的 .cshtml 文件。
GenerateRazorTargetAssemblyInfo 若为 true，则生成 .cs 文件（其中包含由 RazorAssemblyAttribute 指定的属性），并将文件包含在编译输出中。
EnableDefaultRazorTargetAssemblyInfoAttributes 为 true 时，将一组默认的程序集属性添加到 RazorAssemblyAttribute。
CopyRazorGenerateFilesToPublishDirectory 若为 true，则将 RazorGenerate 项 (.cshtml) 文件复制到发布目录。 如果在生成时或发布时参与编译，则通常发布的应用无需 Razor 文件。 默认为 false。
PreserveCompilationReferences 为 true 时，将引用程序集项复制到发布目录。 如果在生成时或发布时出现 Razor 编译，则通常发布的应用无需引用程序集。 如果发布的应用需要运行时编译，则设置为 true。 例如，如果应用在运行时修改 .cshtml 文件或使用嵌入视图，则将值设置为 true。 默认为 false。
IncludeRazorContentInPack 若为 true，则所有 Razor 内容项（.cshtml 文件）标记为包含在生成的 NuGet 包中。 默认为 false。
EmbedRazorGenerateSources 当 true 时，将 RazorGenerate (.cshtml) 项作为嵌入的文件添加到生成的 Razor 程序集中。 默认为 false。
UseRazorBuildServer 为 true 时，使用永久生成服务器进程来卸载代码生成工作。 默认值为 UseSharedCompilation。
GenerateMvcApplicationPartsAssemblyAttributes 若为 true，则 SDK 会生成 MVC 在运行时使用的其他属性，以执行应用程序部件的发现。
DefaultWebContentItemExcludes 要从面向 Web 或 Razor SDK 的项目的 Content 项组中排除的项元素的 glob 模式
ExcludeConfigFilesFromBuildOutput 若为 true，则 .config 和 .json 文件不会复制到生成输出目录。
AddRazorSupportForMvc 若为 true，则配置 Razor SDK，以添加对生成包含 MVC 视图或 Razor Pages 的应用程序时所需的 MVC 配置的支持。 对于面向 Web SDK 的 .NET Core 3.0 或更高版本的项目，隐式设置该属性
RazorLangVersion 要面向的 Razor 语言版本。

有关属性的详细信息，请参阅 MSBuild 属性。

目标

Razor SDK 定义两个主要目标：

  • RazorGenerate：代码基于 RazorGenerate 项元素生成 .cs 文件。 使用 RazorGenerateDependsOn 属性指定可在此目标之前或之后运行的其他目标。
  • RazorCompile：将生成的 .cs 文件编译到 Razor 程序集中。 使用 RazorCompileDependsOn 指定可在此目标之前或之后运行的其他目标。
  • RazorComponentGenerate：代码为 RazorComponent 项元素生成 .cs 文件。 使用 RazorComponentGenerateDependsOn 属性指定可在此目标之前或之后运行的其他目标。

Razor 视图的运行时编译

  • 默认情况下，Razor SDK 不发布执行运行时编译所需的引用程序集。 当应用程序模型依赖于运行时编译时，这会导致编译失败—例如，应用在发布后使用嵌入视图或更改视图。 将 CopyRefAssembliesToPublishDirectory 设置为 true，以继续发布引用程序集。

  • 对于 Web 应用，请确保应用面向 Microsoft.NET.Sdk.Web SDK。

Razor 语言版本

面向 Microsoft.NET.Sdk.Web SDK 时，Razor 语言版本是从应用的目标框架版本推断出来的。 对于面向 Microsoft.NET.Sdk.Razor SDK 的项目，或应用需要不同于推断值的 Razor 语言版本的极少数情况下，可在应用的项目文件中设置 <RazorLangVersion> 属性来配置版本：

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

Razor 的语言版本与其面向的运行时版本紧密集成。 不支持面向不专为运行时而设计的语言版本，这可能会产生生成错误。

其他资源

  • 针对基于 ASP.NET Core MVC 的项目，围绕包含 Razor 文件的项目的生成、打包和发布设定了体验标准。
  • 包含一组预定义的目标、属性和项目，它们允许自定义 Razor 文件的编译。

Razor SDK 包含 Content 项，其 Include 属性设置为 **\*.cshtml 通配模式。 发布匹配文件。

先决条件

.NET Core 2.1 SDK 或更高版本

使用 Razor SDK

大多数 Web 应用不需要显式引用 Razor SDK。

若要使用 Razor SDK 来生成包含 Razor 视图或 Razor Pages 的类库，请执行以下操作：

  • 使用 Microsoft.NET.Sdk.Razor 而非 Microsoft.NET.Sdk：

    <Project SDK="Microsoft.NET.Sdk.Razor">
  <!-- omitted for brevity -->
</Project>

  • 通常，对 Microsoft.AspNetCore.Mvc 的包引用需要接收生成和编译 Razor Pages 和 Razor 视图所需的其他依赖项。 项目至少应将包引用添加到：

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

    Microsoft.AspNetCore.Razor.Design 包为项目提供 Razor 编译任务和目标。

    前面的包包含在 Microsoft.AspNetCore.Mvc 中。 以下标记显示了使用 Razor SDK 为 ASP.NET Core Razor Pages 应用生成 Razor 文件的项目文件：

    <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.Design 和 Microsoft.AspNetCore.Mvc.Razor.Extensions 包均包含在 Microsoft.AspNetCore.App 元包中。 但无版本的 Microsoft.AspNetCore.App 包引用可为不含最新版 Microsoft.AspNetCore.Razor.Design 的应用提供元包。 项目必须引用一致版本的 Microsoft.AspNetCore.Razor.Design（或 Microsoft.AspNetCore.Mvc），以便包含 Razor 的最新生成时修补程序。 有关详细信息，请参阅此 GitHub 问题。

属性

以下属性控制项目生成过程中 Razor 的 SDK 行为：

  • RazorCompileOnBuild：若为 true，则在生成项目的过程中，编译并发出 Razor 程序集。 默认为 true。
  • RazorCompileOnPublish：若为 true，则在发布项目的过程中，编译并发出 Razor 程序集。 默认为 true。

下表中的属性和项用于配置 Razor SDK 的输入和输出。

项 描述
RazorGenerate 输入到代码生成的项元素（.cshtml 文件）。
RazorComponent 输入到 Razor 组件代码生成的项元素（.razor 文件）。
RazorCompile 输入到 Razor 编译目标的项元素（.cs 文件）。 使用此 ItemGroup 指定要编译到 Razor 程序集中的其他文件。
RazorTargetAssemblyAttribute 用于编码生成 Razor 程序集属性的项元素。 例如：
RazorAssemblyAttribute
Include="System.Reflection.AssemblyMetadataAttribute"
_Parameter1="BuildSource" _Parameter2="https://learn.microsoft.com/">
RazorEmbeddedResource 作为嵌入的资源添加到生成的 Razor 程序集中的项元素。
Property 描述
RazorTargetName Razor 生成的程序集的文件名（不含扩展名）。
RazorOutputPath Razor 输出目录。
RazorCompileToolset 用于确定用于生成 Razor 程序集的工具集。 有效值为 Implicit、RazorSDK 和 PrecompilationTool。
EnableDefaultContentItems 默认值为 true。 若为 true，则包含 web.config、.json 和 .cshtml 文件作为项目中的内容。 通过 Microsoft.NET.Sdk.Web 引用时，还包括 wwwroot 下的文件和配置文件。
EnableDefaultRazorGenerateItems 若为 true，则包括 RazorGenerate 项中 Content 项的 .cshtml 文件。
GenerateRazorTargetAssemblyInfo 若为 true，则生成 .cs 文件（其中包含由 RazorAssemblyAttribute 指定的属性），并将文件包含在编译输出中。
EnableDefaultRazorTargetAssemblyInfoAttributes 为 true 时，将一组默认的程序集属性添加到 RazorAssemblyAttribute。
CopyRazorGenerateFilesToPublishDirectory 若为 true，则将 RazorGenerate 项 (.cshtml) 文件复制到发布目录。 如果在生成时或发布时参与编译，则通常发布的应用无需 Razor 文件。 默认为 false。
CopyRefAssembliesToPublishDirectory 为 true 时，将引用程序集项复制到发布目录。 如果在生成时或发布时出现 Razor 编译，则通常发布的应用无需引用程序集。 如果发布的应用需要运行时编译，则设置为 true。 例如，如果应用在运行时修改 .cshtml 文件或使用嵌入视图，则将值设置为 true。 默认为 false。
IncludeRazorContentInPack 若为 true，则所有 Razor 内容项（.cshtml 文件）标记为包含在生成的 NuGet 包中。 默认为 false。
EmbedRazorGenerateSources 当 true 时，将 RazorGenerate (.cshtml) 项作为嵌入的文件添加到生成的 Razor 程序集中。 默认为 false。
UseRazorBuildServer 为 true 时，使用永久生成服务器进程来卸载代码生成工作。 默认值为 UseSharedCompilation。
GenerateMvcApplicationPartsAssemblyAttributes 若为 true，则 SDK 会生成 MVC 在运行时使用的其他属性，以执行应用程序部件的发现。
DefaultWebContentItemExcludes 要从面向 Web 或 Razor SDK 的项目的 Content 项组中排除的项元素的 glob 模式
ExcludeConfigFilesFromBuildOutput 若为 true，则 .config 和 .json 文件不会复制到生成输出目录。
AddRazorSupportForMvc 若为 true，则配置 Razor SDK，以添加对生成包含 MVC 视图或 Razor Pages 的应用程序时所需的 MVC 配置的支持。 对于面向 Web SDK 的 .NET Core 3.0 或更高版本的项目，隐式设置该属性
RazorLangVersion 要面向的 Razor 语言版本。

有关属性的详细信息，请参阅 MSBuild 属性。

目标

Razor SDK 定义两个主要目标：

  • RazorGenerate：代码基于 RazorGenerate 项元素生成 .cs 文件。 使用 RazorGenerateDependsOn 属性指定可在此目标之前或之后运行的其他目标。
  • RazorCompile：将生成的 .cs 文件编译到 Razor 程序集中。 使用 RazorCompileDependsOn 指定可在此目标之前或之后运行的其他目标。
  • RazorComponentGenerate：代码为 RazorComponent 项元素生成 .cs 文件。 使用 RazorComponentGenerateDependsOn 属性指定可在此目标之前或之后运行的其他目标。

Razor 视图的运行时编译

  • 默认情况下，Razor SDK 不发布执行运行时编译所需的引用程序集。 当应用程序模型依赖于运行时编译时，这会导致编译失败—例如，应用在发布后使用嵌入视图或更改视图。 将 CopyRefAssembliesToPublishDirectory 设置为 true，以继续发布引用程序集。

  • 对于 Web 应用，请确保应用面向 Microsoft.NET.Sdk.Web SDK。

Razor 语言版本

面向 Microsoft.NET.Sdk.Web SDK 时，Razor 语言版本是从应用的目标框架版本推断出来的。 对于面向 Microsoft.NET.Sdk.Razor SDK 的项目，或应用需要不同于推断值的 Razor 语言版本的极少数情况下，可在应用的项目文件中设置 <RazorLangVersion> 属性来配置版本：

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

Razor 的语言版本与其面向的运行时版本紧密集成。 不支持面向不专为运行时而设计的语言版本，这可能会产生生成错误。

其他资源