ASP.NET Core Razor SDKASP.NET Core Razor SDK

Автор: Рик Андерсон (Rick Anderson)By Rick Anderson

ОбзорOverview

Пакет SDK для .NET Core 2.1 или более поздней версии..NET Core 2.1 SDK or later включает пакет SDK MSBuild Microsoft.NET.Sdk.Razor (пакет SDK для Razor).The Пакет SDK для .NET Core 2.1 или более поздней версии..NET Core 2.1 SDK or later includes the Microsoft.NET.Sdk.Razor MSBuild SDK (Razor SDK). Пакет SDK для Razor: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.

Пакет SDK для Razor включает элементы 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.

  • Стандартизирует процесс создания, упаковки и публикации проектов, содержащих файлы Razor, для проектов на основе MVC ASP.NET.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.

Пакет SDK для Razor включает элементы 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

Пакет SDK для .NET Core 2.1 или более поздней версии..NET Core 2.1 SDK or later

Использование пакета SDK для RazorUse the Razor SDK

Большинству веб-приложений не требуется явная ссылка на пакет SDK для Razor.Most web apps aren't required to explicitly reference the Razor SDK.

Чтобы использовать пакет SDK для Razor для построения библиотек классов, содержащих представления 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. Для RCL, который используется для сборки файлов Blazor ( RAZOR ), требуется ссылка на пакет Microsoft.AspNetCore.Components.An RCL that's used to build Blazor ( .razor ) files minimally requires a reference to the Microsoft.AspNetCore.Components package. RCL, который используется для сборки представлений или страниц Razor (файлы CSHTML ), требует как минимум netcoreapp3.0 или более поздней версии и имеет ссылку FrameworkReference на метапакет Microsoft.AspNetCore.App в файле проекта.An 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.

Чтобы использовать пакет SDK для Razor для построения библиотек классов, содержащих представления Razor или страницы Razor:To use the Razor SDK to build class libraries containing Razor views or Razor Pages:

  • Используйте Microsoft.NET.Sdk.Razor вместо Microsoft.NET.Sdk:Use 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. В приведенном ниже коде демонстрируется файл проекта, который использует пакет SDK для Razor, чтобы создавать файлы Razor для приложения Razor Pages ASP.NET Core: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.Design и Microsoft.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

Следующие свойства управляют поведением пакета SDK для Razor в ходе создания проекта: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. По умолчанию — true.Defaults to true.
  • RazorCompileOnPublish. Если имеет значение true, компилирует и создает сборку Razor при публикации проекта.RazorCompileOnPublish: When true, compiles and emits the Razor assembly as part of publishing the project. По умолчанию — true.Defaults to true.

Свойства и элементы в следующей таблице используются для настройки входных и выходных данных в пакете SDK для Razor.The properties and items in the following table are used to configure inputs and output to the Razor SDK.

Предупреждение

Начиная с ASP.NET Core 3.0 представления MVC или Razor Pages не обслуживаются по умолчанию, если в файле проекта отключены свойства RazorCompileOnBuild или RazorCompileOnPublish MSBuild.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. Приложения должны добавить явную ссылку на пакет Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation, если приложение использует компиляцию среды выполнения для обработки файлов CSHTML.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 Элементы (файлы CS ), которые являются входными данными для целей компиляции Razor.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.
Свойство.Property Описание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. Допустимые значения: Implicit, RazorSDK и PrecompilationTool.Valid values are Implicit, RazorSDK, and PrecompilationTool.
EnableDefaultContentItemsEnableDefaultContentItems Значение по умолчанию — true.Default 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 включает файлы .cshtml из элементов Content в элементы RazorGenerate.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 добавляет стандартный набор атрибутов сборки в RazorAssemblyAttribute.When 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. По умолчанию — false.Defaults 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. Задайте значение true, если для опубликованного приложения требуется компиляция в среде выполнения.Set to true if your published app requires runtime compilation. Например, задайте значение true, если приложение изменяет файлы CSHTML во время выполнения или использует внедренные представления.For example, set the value to true if the app modifies .cshtml files at runtime or uses embedded views. По умолчанию — false.Defaults to false.
IncludeRazorContentInPack При значении true все элементы содержимого Razor (файлы CSHTML ) помечаются для включения в создаваемый пакет NuGet.When true, all Razor content items ( .cshtml files) are marked for inclusion in the generated NuGet package. По умолчанию — false.Defaults to false.
EmbedRazorGenerateSources При значении true элементы RazorGenerate ( .cshtml ) добавляются в виде внедренных файлов к создаваемой сборке Razor.When true, adds RazorGenerate ( .cshtml ) items as embedded files to the generated Razor assembly. По умолчанию — false.Defaults to false.
UseRazorBuildServer При значении true использует серверный процесс постоянной сборки для разгрузки работы по созданию кода.When true, uses a persistent build server process to offload code generation work. По умолчанию используется значение UseSharedCompilation.Defaults 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 Шаблон подстановки для элементов, которые должны быть исключены из группы элементов Content в проектах, предназначенных для веб-пакета или пакета SDK для RazorA 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 файлы CONGIF и JSON не копируются в выходной каталог сборки.When true, .config and .json files do not get copied to the build output directory.
AddRazorSupportForMvc При значении true настраивается пакет SDK для Razor для добавления поддержки конфигурации MVC, которая необходима при создании приложений, содержащих представления MVC или Razor Pages.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. Это свойство неявно задано для проектов .NET Core 3.0 или более поздней версии, предназначенных для веб-пакета SDKThis 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.
Свойство.Property Описание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. Допустимые значения: Implicit, RazorSDK и PrecompilationTool.Valid values are Implicit, RazorSDK, and PrecompilationTool.
EnableDefaultContentItemsEnableDefaultContentItems Значение по умолчанию — true.Default 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 включает файлы .cshtml из элементов Content в элементы RazorGenerate.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 добавляет стандартный набор атрибутов сборки в RazorAssemblyAttribute.When 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. По умолчанию — false.Defaults 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. Задайте значение true, если для опубликованного приложения требуется компиляция в среде выполнения.Set to true if your published app requires runtime compilation. Например, задайте значение true, если приложение изменяет файлы CSHTML во время выполнения или использует внедренные представления.For example, set the value to true if the app modifies .cshtml files at runtime or uses embedded views. По умолчанию — false.Defaults to false.
IncludeRazorContentInPack При значении true все элементы содержимого Razor (файлы CSHTML ) помечаются для включения в создаваемый пакет NuGet.When true, all Razor content items ( .cshtml files) are marked for inclusion in the generated NuGet package. По умолчанию — false.Defaults to false.
EmbedRazorGenerateSources При значении true элементы RazorGenerate ( .cshtml ) добавляются в виде внедренных файлов к создаваемой сборке Razor.When true, adds RazorGenerate ( .cshtml ) items as embedded files to the generated Razor assembly. По умолчанию — false.Defaults to false.
UseRazorBuildServer При значении true использует серверный процесс постоянной сборки для разгрузки работы по созданию кода.When true, uses a persistent build server process to offload code generation work. По умолчанию используется значение UseSharedCompilation.Defaults 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 Шаблон подстановки для элементов, которые должны быть исключены из группы элементов Content в проектах, предназначенных для веб-пакета или пакета SDK для RazorA 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 файлы CONGIF и JSON не копируются в выходной каталог сборки.When true, .config and .json files do not get copied to the build output directory.
AddRazorSupportForMvc При значении true настраивается пакет SDK для Razor для добавления поддержки конфигурации MVC, которая необходима при создании приложений, содержащих представления MVC или Razor Pages.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. Это свойство неявно задано для проектов .NET Core 3.0 или более поздней версии, предназначенных для веб-пакета SDKThis 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 Properties (Свойства MSBuild).For more information on properties, see MSBuild properties.

Целевые объектыTargets

Пакет SDK для Razor определяет два основных целевых объекта.The Razor SDK defines two primary targets:

  • RazorGenerate. Код создает файлы CS из элементов RazorGenerate.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. Код создает файлы CS для элементов RazorComponent.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.

Компиляция среды выполнения представлений RazorRuntime compilation of Razor views

  • По умолчанию пакет SDK для Razor не публикует базовые сборки, необходимые для компиляции среды выполнения.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.

  • Для веб-приложений убедитесь, что приложение предназначено для пакета SDK Microsoft.NET.Sdk.Web.For a web app, ensure your app is targeting the Microsoft.NET.Sdk.Web SDK.

Версия языка RazorRazor language version

При использовании пакета SDK Microsoft.NET.Sdk.Web версия языка Razor выводится из целевой версии платформы приложения.When targeting the Microsoft.NET.Sdk.Web SDK, the Razor language version is inferred from the app's target framework version. Для проектов, предназначенных для SDK Microsoft.NET.Sdk.Razor, или в редких случаях, когда приложению требуется другая версия языка 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 тесно интегрирована с версией среды выполнения, для которой она была создана.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