SDK Razor do ASP.NET Core

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

• Adições ao formato csproj para .NET Core
• Itens de projeto comuns do MSBuild