ASP.NET Core Razor SDK

  • Статья

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

Обзор

.NET 6.0 SDK включает пакет SDK MSBuild Microsoft.NET.Sdk.Razor (пакет SDK для Razor). Пакет SDK для Razor:

  • Требуется для сборки, упаковки и публикации проектов, содержащих файлы Razor для проектов ASP.NET Core на основе MVC или проектов Blazor.
  • Включает набор предопределенных свойств и элементов, которые позволяют настраивать параметры компиляции файлов Razor (.cshtml или .razor).

Пакет SDK для Razor включает элементы Content с атрибутами Include, для которых установлено значение **\*.cshtml и шаблоны подстановки **\*.razor. Публикуются соответствующие файлы.

Необходимые компоненты

Пакет SDK для .NET 6.0

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

Большинству веб-приложений не требуется явная ссылка на пакет SDK для Razor.

Чтобы использовать пакет SDK для Razor для построения библиотек классов, содержащих представления Razor или Razor Pages, мы рекомендуем начать с шаблона проекта "Библиотека классов Razor" (RCL). Для RCL, который используется для сборки файлов Blazor (.razor), требуется ссылка на пакет Microsoft.AspNetCore.Components. RCL, который используется для сборки представлений или страниц Razor (файлы .cshtml), требует как минимум netcoreapp3.0 или более поздней версии и имеет ссылку FrameworkReference на метапакет Microsoft.AspNetCore.App metapackage в файле проекта.

Свойства

Следующие свойства управляют поведением пакета SDK для Razor в ходе создания проекта:

  • RazorCompileOnBuild: при trueкомпиляции и отправке Razor сборки в рамках сборки проекта. По умолчанию — true.
  • RazorCompileOnPublish: при trueкомпиляции и отправке Razor сборки в рамках публикации проекта. По умолчанию — true.
  • UseRazorSourceGenerator: по trueумолчанию . Когда: true
    • Компилируется с помощью создания источника.
    • Не создает <app_name>.Views.dll. Представления включены в <app_name>.dll.
    • Поддерживает Горячая перезагрузка .NET.

Свойства и элементы в следующей таблице используются для настройки входных и выходных данных в пакете SDK для Razor.

Товаров Description
RazorGenerate Элементы элемента (.cshtml файлы), которые являются входными данными для создания кода.
RazorComponent Элементы (файлы .razor), которые являются входными данными для создания кода компонентов Razor.
RazorCompile Элементы (файлы .cs), которые являются входными данными для целей компиляции Razor. Используйте этот элемент ItemGroup, чтобы указать дополнительные файлы для компиляции в сборку Razor.
RazorEmbeddedResource Элементы, добавленные в качестве внедренных ресурсов к созданной сборке Razor.
Свойство Description
RazorOutputPath Выходной каталог Razor.
RazorCompileToolset Используется для определения набора инструментов для построения сборки Razor. Допустимые значения — Implicit, RazorSDK и PrecompilationTool.
EnableDefaultContentItems По умолчанию — true. Если trueв проекте содержатся файлы web.config и .cshtml.jsonфайлы в качестве содержимого. При ссылке через Microsoft.NET.Sdk.Web также включает все файлы в wwwroot и файлы конфигурации.
EnableDefaultRazorGenerateItems Когда trueфайлы включаются .cshtml из Content элементов в RazorGenerate элементах.
GenerateRazorTargetAssemblyInfo Не используется в .NET 6 и более поздних версиях.
EnableDefaultRazorTargetAssemblyInfoAttributes Не используется в .NET 6 и более поздних версиях.
CopyRazorGenerateFilesToPublishDirectory При trueкопировании RazorGenerate элементов (.cshtml) в каталог публикации. Обычно опубликованному приложению не нужны файлы Razor, если они участвуют в компиляции во время сборки или публикации. По умолчанию — false.
PreserveCompilationReferences При значении true копирует элементы базовой сборки в каталог публикации. Обычно опубликованному приложению не нужны базовые сборки, если компиляция Razor происходит во время сборки или публикации. Задайте значение true, если для опубликованного приложения требуется компиляция в среде выполнения. Например, задайте значение true, если приложение изменяет файлы .cshtml во время выполнения или использует внедренные представления. По умолчанию — false.
IncludeRazorContentInPack Когда trueвсе Razor элементы содержимого (.cshtml файлы) помечены для включения в созданный пакет NuGet. По умолчанию — false.
EmbedRazorGenerateSources При значении true элементы RazorGenerate (.cshtml) добавляются в виде внедренных файлов к создаваемой сборке Razor. По умолчанию — false.
GenerateMvcApplicationPartsAssemblyAttributes Не используется в .NET 6 и более поздних версиях.
DefaultWebContentItemExcludes Шаблон подстановки для элементов, которые должны быть исключены из группы элементов Content в проектах, предназначенных для веб-пакета или пакета SDK для Razor
ExcludeConfigFilesFromBuildOutput При значении true файлы CONGIF и .json не копируются в выходной каталог сборки.
AddRazorSupportForMvc При значении true настраивается пакет SDK для Razor для добавления поддержки конфигурации MVC, которая необходима при создании приложений, содержащих представления MVC или Razor Pages. Это свойство неявно задано для проектов .NET Core 3.0 или более поздней версии, предназначенных для веб-пакета SDK
RazorLangVersion Используемая версия языка Razor.
EmitCompilerGeneratedFiles Если задано значение true, создаваемые исходные файлы записываются на диск. Задание значения true может быть полезным при отладке компилятора. Значение по умолчанию — false.

Дополнительные сведения о свойствах см. в статье MSBuild Properties (Свойства MSBuild).

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

  • По умолчанию пакет SDK для Razor не публикует базовые сборки, необходимые для компиляции среды выполнения. Это приведет к сбою компиляции, если модель приложения зависит от компиляции среды выполнения — например, приложение использует внедренные представления или меняет представления после публикации. Установите для CopyRefAssembliesToPublishDirectory значение true, чтобы продолжить публикацию базовых сборок. Поддерживается создание и компиляция кода всего одним вызовом компилятора. Создается отдельная сборка, содержащая типы приложений и создаваемые представления.

  • Для веб-приложений убедитесь, что приложение предназначено для пакета SDK Microsoft.NET.Sdk.Web.

Версия языка Razor

При использовании пакета SDK Microsoft.NET.Sdk.Web версия языка Razor выводится из целевой версии платформы приложения. Для проектов, предназначенных для SDK Microsoft.NET.Sdk.Razor, или в редких случаях, когда приложению требуется другая версия языка Razor, отличная от выводимого значения, можно настроить версию, задав свойство <RazorLangVersion> в файле проекта приложения.

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

Версия языка Razor тесно интегрирована с версией среды выполнения, для которой она была создана. Выбор языковой версии, не предназначенной для среды выполнения, не поддерживается и, скорее всего, приведет к ошибкам сборки.

Дополнительные ресурсы

Пакет SDK для .NET Core 2.1 или более поздней версии включает пакет SDK MSBuild Microsoft.NET.Sdk.Razor (пакет SDK для Razor). Пакет SDK для Razor:

  • Требуется для сборки, упаковки и публикации проектов, содержащих файлы Razor для проектов ASP.NET Core на основе MVC или проектов Blazor.
  • Включает набор предопределенных целевых объектов, свойств и элементов, которые позволяют настраивать параметры компиляции файлов Razor (.cshtml или .razor).

Пакет SDK для Razor включает элементы Content с атрибутами Include, для которых установлено значение **\*.cshtml и шаблоны подстановки **\*.razor. Публикуются соответствующие файлы.

Необходимые компоненты

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

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

Большинству веб-приложений не требуется явная ссылка на пакет SDK для Razor.

Чтобы использовать пакет SDK для Razor для построения библиотек классов, содержащих представления Razor или Razor Pages, мы рекомендуем начать с шаблона проекта "Библиотека классов Razor" (RCL). Для RCL, который используется для сборки файлов Blazor (.razor), требуется ссылка на пакет Microsoft.AspNetCore.Components. RCL, который используется для сборки представлений или страниц Razor (файлы .cshtml), требует как минимум netcoreapp3.0 или более поздней версии и имеет ссылку FrameworkReference на метапакет Microsoft.AspNetCore.App metapackage в файле проекта.

Свойства

Следующие свойства управляют поведением пакета SDK для Razor в ходе создания проекта:

  • RazorCompileOnBuild: при trueкомпиляции и отправке Razor сборки в рамках сборки проекта. По умолчанию — true.
  • RazorCompileOnPublish: при trueкомпиляции и отправке Razor сборки в рамках публикации проекта. По умолчанию — true.

Свойства и элементы в следующей таблице используются для настройки входных и выходных данных в пакете SDK для Razor.

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

Начиная с ASP.NET Core 3.0 представления MVC или Razor Pages не обслуживаются по умолчанию, если в файле проекта отключены свойства RazorCompileOnBuild или RazorCompileOnPublish MSBuild. Приложения должны добавить явную ссылку на Microsoft.AspNetCore.Mvc.Razor. Пакет RuntimeCompilation , если приложение использует компиляцию среды выполнения для обработки .cshtml файлов.

Товаров Description
RazorGenerate Элементы элемента (.cshtml файлы), которые являются входными данными для создания кода.
RazorComponent Элементы (файлы .razor), которые являются входными данными для создания кода компонентов Razor.
RazorCompile Элементы (файлы .cs), которые являются входными данными для целей компиляции Razor. Используйте этот элемент ItemGroup, чтобы указать дополнительные файлы для компиляции в сборку Razor.
RazorTargetAssemblyAttribute Элементы, используемые для создания атрибутов для сборки Razor. Пример:
RazorAssemblyAttribute
Include="System.Reflection.AssemblyMetadataAttribute"
_Parameter1="BuildSource" _Parameter2="https://learn.microsoft.com/">
RazorEmbeddedResource Элементы, добавленные в качестве внедренных ресурсов к созданной сборке Razor.
Свойство Description
RazorTargetName Имя файла (без расширения) для сборки, созданной Razor.
RazorOutputPath Выходной каталог Razor.
RazorCompileToolset Используется для определения набора инструментов для построения сборки Razor. Допустимые значения — Implicit, RazorSDK и PrecompilationTool.
EnableDefaultContentItems По умолчанию — true. Если trueв проекте содержатся файлы web.config и .cshtml.jsonфайлы в качестве содержимого. При ссылке через Microsoft.NET.Sdk.Web также включает все файлы в wwwroot и файлы конфигурации.
EnableDefaultRazorGenerateItems Когда trueфайлы включаются .cshtml из Content элементов в RazorGenerate элементах.
GenerateRazorTargetAssemblyInfo При значении true создает файл .cs с атрибутами, заданными RazorAssemblyAttribute, и включает его в выходные данные компиляции.
EnableDefaultRazorTargetAssemblyInfoAttributes При значении true добавляет стандартный набор атрибутов сборки в RazorAssemblyAttribute.
CopyRazorGenerateFilesToPublishDirectory При trueкопировании RazorGenerate элементов (.cshtml) в каталог публикации. Обычно опубликованному приложению не нужны файлы Razor, если они участвуют в компиляции во время сборки или публикации. По умолчанию — false.
PreserveCompilationReferences При значении 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 Шаблон подстановки для элементов, которые должны быть исключены из группы элементов Content в проектах, предназначенных для веб-пакета или пакета SDK для Razor
ExcludeConfigFilesFromBuildOutput При значении true файлы CONGIF и .json не копируются в выходной каталог сборки.
AddRazorSupportForMvc При значении true настраивается пакет SDK для Razor для добавления поддержки конфигурации MVC, которая необходима при создании приложений, содержащих представления MVC или Razor Pages. Это свойство неявно задано для проектов .NET Core 3.0 или более поздней версии, предназначенных для веб-пакета SDK
RazorLangVersion Используемая версия языка Razor.

Дополнительные сведения о свойствах см. в статье MSBuild Properties (Свойства MSBuild).

Цели

Пакет SDK для Razor определяет два основных целевых объекта.

  • RazorGenerate. Код создает файлы .cs из элементов RazorGenerate. Используйте свойство RazorGenerateDependsOn, чтобы указать дополнительные целевые объекты, которые могут выполняться до или после этого целевого объекта.
  • RazorCompile: компилирует созданные .cs файлы в сборку Razor . Используйте RazorCompileDependsOn, чтобы указать дополнительные целевые объекты, которые могут выполняться до или после этого целевого объекта.
  • RazorComponentGenerate. Код создает файлы .cs для элементов RazorComponent. Используйте свойство RazorComponentGenerateDependsOn, чтобы указать дополнительные целевые объекты, которые могут выполняться до или после этого целевого объекта.

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

  • По умолчанию пакет SDK для Razor не публикует базовые сборки, необходимые для компиляции среды выполнения. Это приведет к сбою компиляции, если модель приложения зависит от компиляции среды выполнения — например, приложение использует внедренные представления или меняет представления после публикации. Установите для CopyRefAssembliesToPublishDirectory значение true, чтобы продолжить публикацию базовых сборок.

  • Для веб-приложений убедитесь, что приложение предназначено для пакета SDK Microsoft.NET.Sdk.Web.

Версия языка Razor

При использовании пакета SDK Microsoft.NET.Sdk.Web версия языка Razor выводится из целевой версии платформы приложения. Для проектов, предназначенных для SDK Microsoft.NET.Sdk.Razor, или в редких случаях, когда приложению требуется другая версия языка Razor, отличная от выводимого значения, можно настроить версию, задав свойство <RazorLangVersion> в файле проекта приложения.

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

Версия языка Razor тесно интегрирована с версией среды выполнения, для которой она была создана. Выбор языковой версии, не предназначенной для среды выполнения, не поддерживается и, скорее всего, приведет к ошибкам сборки.

Дополнительные ресурсы

  • Стандартизирует процесс создания, упаковки и публикации проектов, содержащих файлы Razor, для проектов на основе MVC ASP.NET.
  • Включает набор предопределенных целевых объектов, свойств и элементов, которые позволяют настраивать параметры компиляции файлов Razor.

Пакет SDK для Razor включает элементы Content с атрибутами Include, для которых установлены шаблоны подстановки **\*.cshtml. Публикуются соответствующие файлы.

Необходимые компоненты

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

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

Большинству веб-приложений не требуется явная ссылка на пакет SDK для Razor.

Чтобы использовать пакет SDK для Razor для построения библиотек классов, содержащих представления Razor или страницы Razor:

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

    <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.

Свойства

Следующие свойства управляют поведением пакета SDK для Razor в ходе создания проекта:

  • RazorCompileOnBuild: при trueкомпиляции и отправке Razor сборки в рамках сборки проекта. По умолчанию — true.
  • RazorCompileOnPublish: при trueкомпиляции и отправке Razor сборки в рамках публикации проекта. По умолчанию — true.

Свойства и элементы в следующей таблице используются для настройки входных и выходных данных в пакете SDK для Razor.

Товаров Description
RazorGenerate Элементы элемента (.cshtml файлы), которые являются входными данными для создания кода.
RazorComponent Элементы (файлы .razor), которые являются входными данными для создания кода компонентов Razor.
RazorCompile Элементы (файлы .cs), которые являются входными данными для целей компиляции Razor. Используйте этот элемент ItemGroup, чтобы указать дополнительные файлы для компиляции в сборку Razor.
RazorTargetAssemblyAttribute Элементы, используемые для создания атрибутов для сборки Razor. Пример:
RazorAssemblyAttribute
Include="System.Reflection.AssemblyMetadataAttribute"
_Parameter1="BuildSource" _Parameter2="https://learn.microsoft.com/">
RazorEmbeddedResource Элементы, добавленные в качестве внедренных ресурсов к созданной сборке Razor.
Свойство Description
RazorTargetName Имя файла (без расширения) для сборки, созданной Razor.
RazorOutputPath Выходной каталог Razor.
RazorCompileToolset Используется для определения набора инструментов для построения сборки Razor. Допустимые значения — Implicit, RazorSDK и PrecompilationTool.
EnableDefaultContentItems По умолчанию — true. Если trueв проекте содержатся файлы web.config и .cshtml.jsonфайлы в качестве содержимого. При ссылке через Microsoft.NET.Sdk.Web также включает все файлы в wwwroot и файлы конфигурации.
EnableDefaultRazorGenerateItems Когда trueфайлы включаются .cshtml из Content элементов в RazorGenerate элементах.
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 Шаблон подстановки для элементов, которые должны быть исключены из группы элементов Content в проектах, предназначенных для веб-пакета или пакета SDK для Razor
ExcludeConfigFilesFromBuildOutput При значении true файлы CONGIF и .json не копируются в выходной каталог сборки.
AddRazorSupportForMvc При значении true настраивается пакет SDK для Razor для добавления поддержки конфигурации MVC, которая необходима при создании приложений, содержащих представления MVC или Razor Pages. Это свойство неявно задано для проектов .NET Core 3.0 или более поздней версии, предназначенных для веб-пакета SDK
RazorLangVersion Используемая версия языка Razor.

Дополнительные сведения о свойствах см. в статье MSBuild Properties (Свойства MSBuild).

Цели

Пакет SDK для Razor определяет два основных целевых объекта.

  • RazorGenerate. Код создает файлы .cs из элементов RazorGenerate. Используйте свойство RazorGenerateDependsOn, чтобы указать дополнительные целевые объекты, которые могут выполняться до или после этого целевого объекта.
  • RazorCompile: компилирует созданные .cs файлы в сборку Razor . Используйте RazorCompileDependsOn, чтобы указать дополнительные целевые объекты, которые могут выполняться до или после этого целевого объекта.
  • RazorComponentGenerate. Код создает файлы .cs для элементов RazorComponent. Используйте свойство RazorComponentGenerateDependsOn, чтобы указать дополнительные целевые объекты, которые могут выполняться до или после этого целевого объекта.

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

  • По умолчанию пакет SDK для Razor не публикует базовые сборки, необходимые для компиляции среды выполнения. Это приведет к сбою компиляции, если модель приложения зависит от компиляции среды выполнения — например, приложение использует внедренные представления или меняет представления после публикации. Установите для CopyRefAssembliesToPublishDirectory значение true, чтобы продолжить публикацию базовых сборок.

  • Для веб-приложений убедитесь, что приложение предназначено для пакета SDK Microsoft.NET.Sdk.Web.

Версия языка Razor

При использовании пакета SDK Microsoft.NET.Sdk.Web версия языка Razor выводится из целевой версии платформы приложения. Для проектов, предназначенных для SDK Microsoft.NET.Sdk.Razor, или в редких случаях, когда приложению требуется другая версия языка Razor, отличная от выводимого значения, можно настроить версию, задав свойство <RazorLangVersion> в файле проекта приложения.

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

Версия языка Razor тесно интегрирована с версией среды выполнения, для которой она была создана. Выбор языковой версии, не предназначенной для среды выполнения, не поддерживается и, скорее всего, приведет к ошибкам сборки.

Дополнительные ресурсы