ASP.NET Core Razor SDK

作者：Rick Anderson

概述

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

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

Razor SDK 包括 Content 项，其 Include 属性设置为 **\*.cshtml 和 **\*.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 的类库，我们建议从 Razor 类库（RCL）项目模板开始。用于生成 Blazor （razor）文件的 RCL 最低要求对AspNetCore包的引用。用于生成 Razor 视图或页面（cshtml文件）的 RCL 最低要求目标 netcoreapp3.0 或更高版本，并在其项目文件中具有AspNetCore 元包的 FrameworkReference。

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

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

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

通常情况下，对的包引用Microsoft.AspNetCore.Mvc，才能接收生成和编译 Razor 页面和 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 页面应用程序的 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 用于属性和下表中的项。

警告

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

项目	描述
`RazorGenerate`	作为代码生成的输入的项元素（cshtml文件）。
`RazorComponent`	作为 Razor 组件代码生成的输入的项元素（razor文件）。
`RazorCompile`	作为 Razor 编译目标的输入的项元素（ .cs文件）。使用此 `ItemGroup` 来指定要编译到 Razor 程序集中的其他文件。
`RazorTargetAssemblyAttribute`	用于编码生成 Razor 程序集属性的项元素。例如： `RazorAssemblyAttribute` `Include="System.Reflection.AssemblyMetadataAttribute"` `_Parameter1="BuildSource" _Parameter2="https://docs.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`如果你已发布的应用需要运行时编译。例如，将值设置为`true`如果应用程序修改 .cshtml文件在运行时或使用嵌入的视图。默认为 `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` 项组中排除的项元素的组合模式
`ExcludeConfigFilesFromBuildOutput`	如果 `true`，则不会将 .config文件和json文件复制到生成输出目录。
`AddRazorSupportForMvc`	`true`时，会将 Razor SDK 配置为添加生成包含 MVC 视图或 Razor Pages 的应用程序时所需的 MVC 配置支持。为针对 Web SDK 的 .NET Core 3.0 或更高版本项目隐式设置此属性
`RazorLangVersion`	要面向的 Razor 语言的版本。

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

目标

Razor SDK 定义两个主要目标：

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

Razor 视图的运行时编译

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

Razor 语言版本

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

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

Razor 的语言版本与生成它的运行时版本紧密集成。针对不是为运行时设计的语言版本，不受支持，并且可能会产生生成错误。

Razor SDK

ASP.NET Core Razor SDK

概述

先决条件

使用 Razor SDK

属性

目标

Razor 视图的运行时编译

Razor 语言版本

其他资源

Razor页面

通用

客户端开发

标记帮助程序

高级