SDK Razor do ASP.NET Core

  • Artigo

De Rick Anderson

Visão geral

O SDK do .NET 6.0 inclui o SDK do MSBuild Microsoft.NET.Sdk.Razor (SDK do Razor). O SDK do Razor:

  • É necessário para pacote, empacotar e publicar projetos que contenham arquivos Razor para projetos Blazor ou baseados em MVC do ASP.NET Core.
  • Inclui um conjunto de propriedades e itens predefinidos que permitem personalizar a compilação de arquivos Razor (.cshtml ou .razor).

O SDK Razor inclui itens Content com atributos Include definidos para os padrões de globbing **\*.cshtml e **\*.razor. Os arquivos correspondentes são publicados.

Pré-requisitos

SDK do .NET 6.0

Usar o SDK do Razor

A maioria dos aplicativos Web não é necessária para referenciar explicitamente o SDK do Razor.

Para usar o SDK do Razor para criar bibliotecas de classes que contêm exibições Razor ou Razor Pages, recomendamos começar com o modelo de projeto de RCL (biblioteca de classes) Razor. Uma RCL usada para compilar arquivos Blazor (.razor) requer minimamente uma referência ao pacote Microsoft.AspNetCore.Components. Uma RCL usada para compilar exibições Razor ou páginas (arquivos .cshtml) requer minimamente o direcionamento netcoreapp3.0 ou posterior e tem um FrameworkReference para o metapacote Microsoft.AspNetCore.App em seu arquivo de projeto.

Propriedades

As seguintes propriedades controlam o comportamento do SDK do Razor como parte de um build de projeto:

  • RazorCompileOnBuild: Quando true, compila e emite o assembly Razor como parte da criação do projeto. Assume o padrão de true.
  • RazorCompileOnPublish: quando true, compila e emite o assembly Razor como parte da publicação do projeto. Assume o padrão de true.
  • UseRazorSourceGenerator: usa true como padrão. Quando: true
    • Compila usando a geração de origem.
    • Não cria <app_name>.Views.dll. Os modos de exibição estão incluídos no <app_name>.dll.
    • Dá suporte a Recarga Dinâmica do .NET.

As propriedades e os itens na tabela a seguir são usados para configurar entradas e saídas para o SDK do Razor.

Itens Descrição
RazorGenerate Elementos de item (arquivos .cshtml) que são entradas para geração de código.
RazorComponent Elementos de item (arquivos .razor) que são entradas para geração de código do componente Razor.
RazorCompile Elementos de item (arquivos .cs) que são entradas para os destinos de compilação do Razor. Use este ItemGroup para especificar arquivos adicionais a serem compilados no assembly Razor.
RazorEmbeddedResource Elementos de item adicionados como recursos incorporados ao assembly Razor gerado.
Propriedade Descrição
RazorOutputPath O diretório de saída Razor.
RazorCompileToolset Usado para determinar o conjunto de ferramentas usado para criar o assembly do Razor. Os valores válidos são Implicit, RazorSDK e PrecompilationTool.
EnableDefaultContentItems O padrão é true. Quando true, inclui arquivos web.config, .json e .cshtml como conteúdo no projeto. Quando referenciados por meio de Microsoft.NET.Sdk.Web, os arquivos em wwwroot e arquivos de configuração também são incluídos.
EnableDefaultRazorGenerateItems Quando true, inclui arquivos .cshtml de itens de Content em itens de RazorGenerate.
GenerateRazorTargetAssemblyInfo Não usado no .NET 6 e posterior.
EnableDefaultRazorTargetAssemblyInfoAttributes Não usado no .NET 6 e posterior.
CopyRazorGenerateFilesToPublishDirectory Quando true, copia arquivos de itens RazorGenerate (.cshtml) para o diretório de publicação. Normalmente, os arquivos Razor não são necessários para um aplicativo publicado quando eles participam da compilação no tempo de build ou no tempo de publicação. Assume o padrão de false.
PreserveCompilationReferences Quando true, copia os itens do assembly de referência no diretório de publicação. Normalmente, os assemblies de referência não são necessários para um aplicativo publicado quando a compilação do Razor ocorre no tempo de build ou no tempo de publicação. Defina como true se o aplicativo publicado exigir compilação de runtime. Por exemplo, defina o valor como true se o aplicativo modificar arquivos .cshtml em runtime ou usar exibições inseridas. Assume o padrão de false.
IncludeRazorContentInPack Quando true, todos os itens de conteúdo do Razor (arquivos .cshtml) são marcados para inclusão no pacote do NuGet gerado. Assume o padrão de false.
EmbedRazorGenerateSources Quando true, adiciona itens de RazorGenerate (.cshtml) como arquivos incorporados ao assembly Razor gerado. Assume o padrão de false.
GenerateMvcApplicationPartsAssemblyAttributes Não usado no .NET 6 e posterior.
DefaultWebContentItemExcludes Um padrão de globbing para elementos de item que devem ser excluídos do grupo de itens Content em projetos direcionados à Web ou ao SDK do Razor
ExcludeConfigFilesFromBuildOutput Quando os arquivos true, .config e .json não são copiados para o diretório de saída de build.
AddRazorSupportForMvc Quando true, configura o SDK do Razor para adicionar suporte para a configuração do MVC necessária ao compilar aplicativos que contêm exibições MVC ou Razor Pages. Essa propriedade é definida implicitamente para projetos do .NET Core 3.0 ou posteriores direcionados ao SDK da Web
RazorLangVersion A versão da Linguagem Razor a ser direcionada.
EmitCompilerGeneratedFiles Quando definido como true, os arquivos de origem gerados são gravados no disco. Definir como true é útil ao depurar o compilador. O padrão é false.

Para saber mais sobre as propriedades, confira Propriedades do MSBuild.

Compilação de runtime de modos de exibição do Razor

  • Por padrão, o SDK do Razor não publica assemblies de referência que são necessários para realizar compilação no runtime. Isso resulta em falhas de compilação quando o modelo de aplicativo se baseia na compilação em runtime, por exemplo, o aplicativo usa exibições inseridas ou muda as exibições depois que o aplicativo é publicado. Defina CopyRefAssembliesToPublishDirectory como true para continuar publicando assemblies de referência. A geração de código e a compilação são compatíveis com uma única chamada para o compilador. Um único assembly é produzido que contém os tipos de aplicativo e as exibições geradas.

  • Para um aplicativo Web, verifique se o seu aplicativo tem o SDK do Microsoft.NET.Sdk.Web como destino.

Versão da linguagem Razor

Ao ter o SDK do Microsoft.NET.Sdk.Web como destino, a versão da linguagem Razor é inferida da versão da estrutura de destino do aplicativo. Para projetos direcionados ao SDK do Microsoft.NET.Sdk.Razor ou em casos raros em que o aplicativo requer uma versão de linguagem Razor diferente do valor inferido, uma versão pode ser configurada definindo a propriedade <RazorLangVersion> no arquivo de projeto do aplicativo:

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

A versão da linguagem Razor é totalmente integrada à versão do runtime para a qual ela foi compilada. O direcionamento de uma versão de linguagem que não foi projetada para o runtime não tem suporte e provavelmente produz erros de build.

Recursos adicionais

O SDK do .NET Core 2.1 ou posterior inclui o SDK do MSBuild Microsoft.NET.Sdk.Razor (SDK do Razor). O SDK do Razor:

  • É necessário para pacote, empacotar e publicar projetos que contenham arquivos Razor para projetos Blazor ou baseados em MVC do ASP.NET Core.
  • Inclui um conjunto de destinos, propriedades e itens predefinidos que permitem personalizar a compilação de arquivos Razor (.cshtml ou .razor).

O SDK Razor inclui itens Content com atributos Include definidos para os padrões de globbing **\*.cshtml e **\*.razor. Os arquivos correspondentes são publicados.

Pré-requisitos

SDK do .NET Core 2.1 ou posteriores

Usar o SDK do Razor

A maioria dos aplicativos Web não é necessária para referenciar explicitamente o SDK do Razor.

Para usar o SDK do Razor para criar bibliotecas de classes que contêm exibições Razor ou Razor Pages, recomendamos começar com o modelo de projeto de RCL (biblioteca de classes) Razor. Uma RCL usada para compilar arquivos Blazor (.razor) requer minimamente uma referência ao pacote Microsoft.AspNetCore.Components. Uma RCL usada para compilar exibições Razor ou páginas (arquivos .cshtml) requer minimamente o direcionamento netcoreapp3.0 ou posterior e tem um FrameworkReference para o metapacote Microsoft.AspNetCore.App em seu arquivo de projeto.

Propriedades

As seguintes propriedades controlam o comportamento do SDK do Razor como parte de um build de projeto:

  • RazorCompileOnBuild: Quando true, compila e emite o assembly Razor como parte da criação do projeto. Assume o padrão de true.
  • RazorCompileOnPublish: quando true, compila e emite o assembly Razor como parte da publicação do projeto. Assume o padrão de true.

As propriedades e os itens na tabela a seguir são usados para configurar entradas e saídas para o SDK do Razor.

Aviso

A partir do ASP.NET Core 3.0, as exibições do MVC ou Razor Pages não serão atendidas por padrão se as propriedades de RazorCompileOnBuild ou RazorCompileOnPublish do MSBuild no arquivo de projeto estiverem desabilitadas. Os aplicativos devem adicionar uma referência explícita ao pacote Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation se o aplicativo depender da compilação de runtime para processar arquivos .cshtml.

Itens Descrição
RazorGenerate Elementos de item (arquivos .cshtml) que são entradas para geração de código.
RazorComponent Elementos de item (arquivos .razor) que são entradas para geração de código do componente Razor.
RazorCompile Elementos de item (arquivos .cs) que são entradas para os destinos de compilação do Razor. Use este ItemGroup para especificar arquivos adicionais a serem compilados no assembly Razor.
RazorTargetAssemblyAttribute Os elementos de item usados para a codificação geram atributos para o assembly Razor. Por exemplo:
RazorAssemblyAttribute
Include="System.Reflection.AssemblyMetadataAttribute"
_Parameter1="BuildSource" _Parameter2="https://video2.skills-academy.com/">
RazorEmbeddedResource Elementos de item adicionados como recursos incorporados ao assembly Razor gerado.
Propriedade Descrição
RazorTargetName Nome do arquivo (sem extensão) do assembly produzido pelo Razor.
RazorOutputPath O diretório de saída Razor.
RazorCompileToolset Usado para determinar o conjunto de ferramentas usado para criar o assembly do Razor. Os valores válidos são Implicit, RazorSDK e PrecompilationTool.
EnableDefaultContentItems O padrão é true. Quando true, inclui arquivos web.config, .json e .cshtml como conteúdo no projeto. Quando referenciados por meio de Microsoft.NET.Sdk.Web, os arquivos em wwwroot e arquivos de configuração também são incluídos.
EnableDefaultRazorGenerateItems Quando true, inclui arquivos .cshtml de itens de Content em itens de RazorGenerate.
GenerateRazorTargetAssemblyInfo Quando true, gera um arquivo .cs que contém atributos especificados pelo RazorAssemblyAttribute e inclui o arquivo na saída da compilação.
EnableDefaultRazorTargetAssemblyInfoAttributes Quando true, adiciona um conjunto padrão de atributos de assembly em RazorAssemblyAttribute.
CopyRazorGenerateFilesToPublishDirectory Quando true, copia arquivos de itens RazorGenerate (.cshtml) para o diretório de publicação. Normalmente, os arquivos Razor não são necessários para um aplicativo publicado quando eles participam da compilação no tempo de build ou no tempo de publicação. Assume o padrão de false.
PreserveCompilationReferences Quando true, copia os itens do assembly de referência no diretório de publicação. Normalmente, os assemblies de referência não são necessários para um aplicativo publicado quando a compilação do Razor ocorre no tempo de build ou no tempo de publicação. Defina como true se o aplicativo publicado exigir compilação de runtime. Por exemplo, defina o valor como true se o aplicativo modificar arquivos .cshtml em runtime ou usar exibições inseridas. Assume o padrão de false.
IncludeRazorContentInPack Quando true, todos os itens de conteúdo do Razor (arquivos .cshtml) são marcados para inclusão no pacote do NuGet gerado. Assume o padrão de false.
EmbedRazorGenerateSources Quando true, adiciona itens de RazorGenerate (.cshtml) como arquivos incorporados ao assembly Razor gerado. Assume o padrão de false.
UseRazorBuildServer Quando true, usa um processo de servidor de build persistente para descarregar o trabalho de geração de código. Seu valor padrão é UseSharedCompilation.
GenerateMvcApplicationPartsAssemblyAttributes Quando true, o SDK gera atributos adicionais usados pelo MVC em runtime para executar a descoberta de parte do aplicativo.
DefaultWebContentItemExcludes Um padrão de globbing para elementos de item que devem ser excluídos do grupo de itens Content em projetos direcionados à Web ou ao SDK do Razor
ExcludeConfigFilesFromBuildOutput Quando os arquivos true, .config e .json não são copiados para o diretório de saída de build.
AddRazorSupportForMvc Quando true, configura o SDK do Razor para adicionar suporte para a configuração do MVC necessária ao compilar aplicativos que contêm exibições MVC ou Razor Pages. Essa propriedade é definida implicitamente para projetos do .NET Core 3.0 ou posteriores direcionados ao SDK da Web
RazorLangVersion A versão da Linguagem Razor a ser direcionada.

Para saber mais sobre as propriedades, confira Propriedades do MSBuild.

Destinos

O SDK do Razor define dois destinos primários:

  • RazorGenerate: o código gera arquivos .cs de elementos de item RazorGenerate. Use a propriedade RazorGenerateDependsOn para especificar destinos adicionais que podem ser executados antes ou depois desse destino.
  • RazorCompile: compila arquivos .cs gerados em um assembly Razor. Use RazorCompileDependsOn para especificar destinos adicionais que podem ser executados antes ou depois desse destino.
  • RazorComponentGenerate: o código gera arquivos .cs para elementos de item RazorComponent. Use a propriedade RazorComponentGenerateDependsOn para especificar destinos adicionais que podem ser executados antes ou depois desse destino.

Compilação de runtime de modos de exibição do Razor

  • Por padrão, o SDK do Razor não publica assemblies de referência que são necessários para realizar compilação no runtime. Isso resulta em falhas de compilação quando o modelo de aplicativo se baseia na compilação em runtime, por exemplo, o aplicativo usa exibições inseridas ou muda as exibições depois que o aplicativo é publicado. Defina CopyRefAssembliesToPublishDirectory como true para continuar publicando assemblies de referência.

  • Para um aplicativo Web, verifique se o seu aplicativo tem o SDK do Microsoft.NET.Sdk.Web como destino.

Versão da linguagem Razor

Ao ter o SDK do Microsoft.NET.Sdk.Web como destino, a versão da linguagem Razor é inferida da versão da estrutura de destino do aplicativo. Para projetos direcionados ao SDK do Microsoft.NET.Sdk.Razor ou em casos raros em que o aplicativo requer uma versão de linguagem Razor diferente do valor inferido, uma versão pode ser configurada definindo a propriedade <RazorLangVersion> no arquivo de projeto do aplicativo:

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

A versão da linguagem Razor é totalmente integrada à versão do runtime para a qual ela foi compilada. O direcionamento de uma versão de linguagem que não foi projetada para o runtime não tem suporte e provavelmente produz erros de build.

Recursos adicionais

  • Padroniza a experiência de criação, empacotamento e publicação de projetos que contêm arquivos Razor para projetos baseados no ASP.NET Core MVC.
  • Inclui um conjunto de destinos, propriedades e itens predefinidos que permitem personalizar a compilação de arquivos Razor.

O SDK Razor inclui um item Content com um atributo Include definido como o padrão de globbing **\*.cshtml. Os arquivos correspondentes são publicados.

Pré-requisitos

SDK do .NET Core 2.1 ou posteriores

Usar o SDK do Razor

A maioria dos aplicativos Web não é necessária para referenciar explicitamente o SDK do Razor.

Para usar o SDK do Razor para criar bibliotecas de classe contendo exibições Razor ou Razor Pages:

  • Use Microsoft.NET.Sdk.Razor em vez de Microsoft.NET.Sdk:

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

  • Normalmente, uma referência de pacote para Microsoft.AspNetCore.Mvc é necessária receber dependências adicionais necessárias para criar e compilar Razor Pages e exibições Razor. No mínimo, o projeto deve adicionar referências de pacote para:

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

    O pacote Microsoft.AspNetCore.Razor.Design fornece as tarefas de compilação Razor e os destinos para o projeto.

    Os pacotes anteriores são incluídos em Microsoft.AspNetCore.Mvc. A marcação a seguir mostra um arquivo de projeto que usa o SDK do Razor para criar arquivos Razor para um aplicativo Razor Pages do 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>

Aviso

Os pacotes Microsoft.AspNetCore.Razor.Design e Microsoft.AspNetCore.Mvc.Razor.Extensionssão incluídos no metapacote Microsoft.AspNetCore.App. No entanto, a referência de pacote Microsoft.AspNetCore.App sem versão fornece um metapacote para o aplicativo que não inclui a versão mais recente do Microsoft.AspNetCore.Razor.Design. Os projetos devem fazer referência a uma versão consistente de Microsoft.AspNetCore.Razor.Design (ou Microsoft.AspNetCore.Mvc) para que as correções de tempo de build mais recentes para Razor sejam incluídas. Saiba mais neste tópico do GitHub.

Propriedades

As seguintes propriedades controlam o comportamento do SDK do Razor como parte de um build de projeto:

  • RazorCompileOnBuild: Quando true, compila e emite o assembly Razor como parte da criação do projeto. Assume o padrão de true.
  • RazorCompileOnPublish: quando true, compila e emite o assembly Razor como parte da publicação do projeto. Assume o padrão de true.

As propriedades e os itens na tabela a seguir são usados para configurar entradas e saídas para o SDK do Razor.

Itens Descrição
RazorGenerate Elementos de item (arquivos .cshtml) que são entradas para geração de código.
RazorComponent Elementos de item (arquivos .razor) que são entradas para geração de código do componente Razor.
RazorCompile Elementos de item (arquivos .cs) que são entradas para os destinos de compilação do Razor. Use este ItemGroup para especificar arquivos adicionais a serem compilados no assembly Razor.
RazorTargetAssemblyAttribute Os elementos de item usados para a codificação geram atributos para o assembly Razor. Por exemplo:
RazorAssemblyAttribute
Include="System.Reflection.AssemblyMetadataAttribute"
_Parameter1="BuildSource" _Parameter2="https://video2.skills-academy.com/">
RazorEmbeddedResource Elementos de item adicionados como recursos incorporados ao assembly Razor gerado.
Propriedade Descrição
RazorTargetName Nome do arquivo (sem extensão) do assembly produzido pelo Razor.
RazorOutputPath O diretório de saída Razor.
RazorCompileToolset Usado para determinar o conjunto de ferramentas usado para criar o assembly do Razor. Os valores válidos são Implicit, RazorSDK e PrecompilationTool.
EnableDefaultContentItems O padrão é true. Quando true, inclui arquivos web.config, .json e .cshtml como conteúdo no projeto. Quando referenciados por meio de Microsoft.NET.Sdk.Web, os arquivos em wwwroot e arquivos de configuração também são incluídos.
EnableDefaultRazorGenerateItems Quando true, inclui arquivos .cshtml de itens de Content em itens de RazorGenerate.
GenerateRazorTargetAssemblyInfo Quando true, gera um arquivo .cs que contém atributos especificados pelo RazorAssemblyAttribute e inclui o arquivo na saída da compilação.
EnableDefaultRazorTargetAssemblyInfoAttributes Quando true, adiciona um conjunto padrão de atributos de assembly em RazorAssemblyAttribute.
CopyRazorGenerateFilesToPublishDirectory Quando true, copia arquivos de itens RazorGenerate (.cshtml) para o diretório de publicação. Normalmente, os arquivos Razor não são necessários para um aplicativo publicado quando eles participam da compilação no tempo de build ou no tempo de publicação. Assume o padrão de false.
CopyRefAssembliesToPublishDirectory Quando true, copia os itens do assembly de referência no diretório de publicação. Normalmente, os assemblies de referência não são necessários para um aplicativo publicado quando a compilação do Razor ocorre no tempo de build ou no tempo de publicação. Defina como true se o aplicativo publicado exigir compilação de runtime. Por exemplo, defina o valor como true se o aplicativo modificar arquivos .cshtml em runtime ou usar exibições inseridas. Assume o padrão de false.
IncludeRazorContentInPack Quando true, todos os itens de conteúdo do Razor (arquivos .cshtml) são marcados para inclusão no pacote do NuGet gerado. Assume o padrão de false.
EmbedRazorGenerateSources Quando true, adiciona itens de RazorGenerate (.cshtml) como arquivos incorporados ao assembly Razor gerado. Assume o padrão de false.
UseRazorBuildServer Quando true, usa um processo de servidor de build persistente para descarregar o trabalho de geração de código. Seu valor padrão é UseSharedCompilation.
GenerateMvcApplicationPartsAssemblyAttributes Quando true, o SDK gera atributos adicionais usados pelo MVC em runtime para executar a descoberta de parte do aplicativo.
DefaultWebContentItemExcludes Um padrão de globbing para elementos de item que devem ser excluídos do grupo de itens Content em projetos direcionados à Web ou ao SDK do Razor
ExcludeConfigFilesFromBuildOutput Quando os arquivos true, .config e .json não são copiados para o diretório de saída de build.
AddRazorSupportForMvc Quando true, configura o SDK do Razor para adicionar suporte para a configuração do MVC necessária ao compilar aplicativos que contêm exibições MVC ou Razor Pages. Essa propriedade é definida implicitamente para projetos do .NET Core 3.0 ou posteriores direcionados ao SDK da Web
RazorLangVersion A versão da Linguagem Razor a ser direcionada.

Para saber mais sobre as propriedades, confira Propriedades do MSBuild.

Destinos

O SDK do Razor define dois destinos primários:

  • RazorGenerate: o código gera arquivos .cs de elementos de item RazorGenerate. Use a propriedade RazorGenerateDependsOn para especificar destinos adicionais que podem ser executados antes ou depois desse destino.
  • RazorCompile: compila arquivos .cs gerados em um assembly Razor. Use RazorCompileDependsOn para especificar destinos adicionais que podem ser executados antes ou depois desse destino.
  • RazorComponentGenerate: o código gera arquivos .cs para elementos de item RazorComponent. Use a propriedade RazorComponentGenerateDependsOn para especificar destinos adicionais que podem ser executados antes ou depois desse destino.

Compilação de runtime de modos de exibição do Razor

  • Por padrão, o SDK do Razor não publica assemblies de referência que são necessários para realizar compilação no runtime. Isso resulta em falhas de compilação quando o modelo de aplicativo se baseia na compilação em runtime, por exemplo, o aplicativo usa exibições inseridas ou muda as exibições depois que o aplicativo é publicado. Defina CopyRefAssembliesToPublishDirectory como true para continuar publicando assemblies de referência.

  • Para um aplicativo Web, verifique se o seu aplicativo tem o SDK do Microsoft.NET.Sdk.Web como destino.

Versão da linguagem Razor

Ao ter o SDK do Microsoft.NET.Sdk.Web como destino, a versão da linguagem Razor é inferida da versão da estrutura de destino do aplicativo. Para projetos direcionados ao SDK do Microsoft.NET.Sdk.Razor ou em casos raros em que o aplicativo requer uma versão de linguagem Razor diferente do valor inferido, uma versão pode ser configurada definindo a propriedade <RazorLangVersion> no arquivo de projeto do aplicativo:

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

A versão da linguagem Razor é totalmente integrada à versão do runtime para a qual ela foi compilada. O direcionamento de uma versão de linguagem que não foi projetada para o runtime não tem suporte e provavelmente produz erros de build.

Recursos adicionais