Partilhar via

SDK do ASP.NET Core Razor

Por Rick Anderson

Overview

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

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

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

Prerequisites

SDK do .NET 6

Utilizar o Razor SDK

A maioria dos aplicativos Web não precisa fazer referência explícita ao Razor SDK.

Para usar o Razor SDK para criar bibliotecas de classes contendo Razor visualizações ou Razor páginas, recomendamos começar com o modelo de projeto de biblioteca de classes Razor (RCL). Um RCL que é usado para construir Blazor(.razor) arquivos exige no mínimo uma referência ao pacote Microsoft.AspNetCore.Components. Um RCL usado para construir Razor visualizações ou páginas (.cshtml ficheiros) requer, no mínimo, que se dirija a netcoreapp3.0 ou uma versão posterior e tenha uma referência ao FrameworkReference no seu ficheiro de projeto.

Properties

As propriedades a seguir controlam o Razorcomportamento do SDK como parte de uma compilação de projeto:

  • RazorCompileOnBuild: Quando true, compila e emite o Razor assembly como parte da construção do projeto. O padrão é true.
  • RazorCompileOnPublish: Quando true, compila e emite a Razor montagem como parte da publicação do projeto. O padrão é true.
  • UseRazorSourceGenerator: O padrão é true. Quando true:
    • Compila usando a geração de código-fonte.
    • Não cria <app_name>.Views.dll. As visualizações são incluídas no <app_name>.dll.
    • Suporta .NET Hot Reload.

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

Items Description
RazorGenerate Elementos do item (.cshtml arquivos) que são entradas para o processo de geração de código.
RazorComponent Elementos de item (.razor arquivos) que são entradas para a Razor geração de código do componente.
RazorCompile Elementos do item (.cs ficheiros) que são entradas para os destinos de compilação Razor. Utilize este ItemGroup para especificar ficheiros adicionais a serem compilados na Razor assemblagem.
RazorEmbeddedResource Elementos de item adicionados como recursos incorporados ao assembly gerado Razor .
Property Description
RazorOutputPath O Razor diretório de saída.
RazorCompileToolset Usado para determinar o conjunto de ferramentas usado para construir o Razor assembly. Os valores válidos são Implicit, RazorSDKe PrecompilationTool.
EnableDefaultContentItems A predefinição é true. Quando true, inclui web.config, .json e .cshtml ficheiros como conteúdo do projeto. Quando referenciados via Microsoft.NET.Sdk.Web, os ficheiros sob wwwroot e os ficheiros de configuração também estão incluídos.
EnableDefaultRazorGenerateItems Quando true, inclui .cshtml ficheiros de Content itens em RazorGenerate itens.
GenerateRazorTargetAssemblyInfo Não usado no .NET 6 ou posterior.
EnableDefaultRazorTargetAssemblyInfoAttributes Não usado no .NET 6 ou posterior.
CopyRazorGenerateFilesToPublishDirectory Quando true, copia RazorGenerate arquivos de itens (.cshtml) para o diretório de publicação. Normalmente, os ficheiros Razor não são necessários para uma aplicação publicada se participarem na compilação no momento da compilação ou da publicação. O padrão é false.
PreserveCompilationReferences Quando true, copie itens de assembly de referência para o diretório de publicação. Normalmente, os assemblies de referência não são necessários para uma aplicação publicada se Razor a compilação ocorrer no momento da compilação ou no momento da publicação. Defina como true se seu aplicativo publicado requer compilação em tempo de execução. Por exemplo, defina o valor como true se o aplicativo modifica .cshtml arquivos em tempo de execução ou usa exibições incorporadas. O padrão é false.
IncludeRazorContentInPack Quando true, todos os Razor itens de conteúdo (.cshtml ficheiros) são marcados para inclusão no pacote NuGet gerado. O padrão é false.
EmbedRazorGenerateSources Quando true, adiciona os itens RazorGenerate (.cshtml) como ficheiros incorporados ao Razor assembly gerado. O padrão é false.
GenerateMvcApplicationPartsAssemblyAttributes Não usado no .NET 6 ou posterior.
DefaultWebContentItemExcludes Um padrão de globbing para elementos de item que devem ser excluídos do grupo de itens Content em projetos voltados para a Web ou para o SDK Razor.
ExcludeConfigFilesFromBuildOutput Quando true, .config e .json arquivos não são copiados para o diretório de saída da compilação.
AddRazorSupportForMvc Quando true, configura o Razor SDK para adicionar suporte para a configuração MVC que é necessária ao criar aplicativos que contêm vistas MVC ou Razor Páginas. Esta propriedade é implicitamente definida para o .NET Core 3.0 ou projetos posteriores destinados ao SDK da Web
RazorLangVersion A versão do Razor idioma de destino.
EmitCompilerGeneratedFiles Quando definido como true, os arquivos de origem gerados são gravados no disco. A configuração como true é útil ao depurar o compilador. A predefinição é false.

Para obter mais informações sobre propriedades, consulte Propriedades do MSBuild.

Compilação de Razor vistas em tempo de execução

  • Por padrão, o SDK não publica assemblies de referência necessários para a compilação em tempo de execução Razor. Isso resulta em falhas de compilação quando o modelo de aplicativo depende da compilação em tempo de execução — por exemplo, o aplicativo usa modos de exibição incorporados ou altera modos de exibição depois que o aplicativo é publicado. Defina CopyRefAssembliesToPublishDirectory para true para continuar a publicar os assemblies de referência. Tanto a geração de código quanto a compilação são suportadas por uma única chamada para o compilador. É produzido um único assembly que contém os tipos de aplicação e as vistas geradas.

  • Para um aplicativo Web, verifique se seu aplicativo está direcionado ao Microsoft.NET.Sdk.Web SDK.

Razor Versão linguística

Ao apontar para o Microsoft.NET.Sdk.Web SDK, a versão de linguagem Razor é inferida a partir da versão do framework de destino do aplicativo. Para projetos destinados ao Microsoft.NET.Sdk.Razor SDK ou no raro caso de o aplicativo exigir uma versão de idioma 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>

Razor A versão de idioma está totalmente integrada com a versão do tempo de execução para o qual foi construída. O direcionamento de uma versão de idioma que não foi projetada para o tempo de execução não é suportado e provavelmente produz erros de compilação.

Recursos adicionais

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

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

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

Prerequisites

SDK do .NET Core 2.1 ou posterior

Utilizar o Razor SDK

A maioria dos aplicativos Web não precisa fazer referência explícita ao Razor SDK.

Para usar o Razor SDK para criar bibliotecas de classes contendo Razor visualizações ou Razor páginas, recomendamos começar com o modelo de projeto de biblioteca de classes Razor (RCL). Um RCL que é usado para construir Blazor(.razor) arquivos exige no mínimo uma referência ao pacote Microsoft.AspNetCore.Components. Um RCL usado para construir Razor visualizações ou páginas (.cshtml ficheiros) requer, no mínimo, que se dirija a netcoreapp3.0 ou uma versão posterior e tenha uma referência ao FrameworkReference no seu ficheiro de projeto.

Properties

As propriedades a seguir controlam o Razorcomportamento do SDK como parte de uma compilação de projeto:

  • RazorCompileOnBuild: Quando true, compila e emite o Razor assembly como parte da construção do projeto. O padrão é true.
  • RazorCompileOnPublish: Quando true, compila e emite a Razor montagem como parte da publicação do projeto. O padrão é true.

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

Warning

A partir do ASP.NET Core 3.0, as Vistas ou Páginas MVC não são disponibilizadas por padrão se as propriedades Razor ou RazorCompileOnBuild do MSBuild no arquivo de projeto estiverem desativadas. As aplicações devem adicionar uma referência explícita ao pacote Microsoft.AspNetCore.Mvc.RuntimeCompilation se a aplicação depender da compilação em tempo de execução para processar Razor arquivos.

Items Description
RazorGenerate Elementos do item (.cshtml arquivos) que são entradas para o processo de geração de código.
RazorComponent Elementos de item (.razor arquivos) que são entradas para a Razor geração de código do componente.
RazorCompile Elementos do item (.cs ficheiros) que são entradas para os destinos de compilação Razor. Utilize este ItemGroup para especificar ficheiros adicionais a serem compilados na Razor assemblagem.
RazorTargetAssemblyAttribute Os elementos de item usados para codificar geram atributos para o Razor assembly. Por exemplo:
RazorAssemblyAttribute
Include="System.Reflection.AssemblyMetadataAttribute"
_Parameter1="BuildSource" _Parameter2="https://learn.microsoft.com/">
RazorEmbeddedResource Elementos de item adicionados como recursos incorporados ao assembly gerado Razor .
Property Description
RazorTargetName Nome do arquivo (sem extensão) do assembly produzido pelo Razor.
RazorOutputPath O Razor diretório de saída.
RazorCompileToolset Usado para determinar o conjunto de ferramentas usado para construir o Razor assembly. Os valores válidos são Implicit, RazorSDKe PrecompilationTool.
EnableDefaultContentItems A predefinição é true. Quando true, inclui web.config, .json e .cshtml ficheiros como conteúdo do projeto. Quando referenciados via Microsoft.NET.Sdk.Web, os ficheiros sob wwwroot e os ficheiros de configuração também estão incluídos.
EnableDefaultRazorGenerateItems Quando true, inclui .cshtml ficheiros de Content itens em RazorGenerate itens.
GenerateRazorTargetAssemblyInfo Quando true, gera um .cs arquivo contendo atributos especificados por RazorAssemblyAttribute e inclui o arquivo na saída da compilação.
EnableDefaultRazorTargetAssemblyInfoAttributes Quando true, adiciona um conjunto padrão de atributos de assembly ao RazorAssemblyAttribute.
CopyRazorGenerateFilesToPublishDirectory Quando true, copia RazorGenerate arquivos de itens (.cshtml) para o diretório de publicação. Normalmente, os ficheiros Razor não são necessários para uma aplicação publicada se participarem na compilação no momento da compilação ou da publicação. O padrão é false.
PreserveCompilationReferences Quando true, copie itens de assembly de referência para o diretório de publicação. Normalmente, os assemblies de referência não são necessários para uma aplicação publicada se Razor a compilação ocorrer no momento da compilação ou no momento da publicação. Defina como true se seu aplicativo publicado requer compilação em tempo de execução. Por exemplo, defina o valor como true se o aplicativo modifica .cshtml arquivos em tempo de execução ou usa exibições incorporadas. O padrão é false.
IncludeRazorContentInPack Quando true, todos os Razor itens de conteúdo (.cshtml ficheiros) são marcados para inclusão no pacote NuGet gerado. O padrão é false.
EmbedRazorGenerateSources Quando true, adiciona os itens RazorGenerate (.cshtml) como ficheiros incorporados ao Razor assembly gerado. O padrão é false.
UseRazorBuildServer Quando true, usa um processo de servidor de compilação persistente para descarregar o trabalho de geração de código. O padrão é o valor de UseSharedCompilation.
GenerateMvcApplicationPartsAssemblyAttributes Quando true, o SDK gera atributos adicionais usados pelo MVC em tempo de execução para executar a descoberta de peças do aplicativo.
DefaultWebContentItemExcludes Um padrão de globbing para elementos de item que devem ser excluídos do grupo de itens Content em projetos voltados para a Web ou para o SDK Razor.
ExcludeConfigFilesFromBuildOutput Quando true, .config e .json arquivos não são copiados para o diretório de saída da compilação.
AddRazorSupportForMvc Quando true, configura o Razor SDK para adicionar suporte para a configuração MVC que é necessária ao criar aplicativos que contêm vistas MVC ou Razor Páginas. Esta propriedade é implicitamente definida para o .NET Core 3.0 ou projetos posteriores destinados ao SDK da Web
RazorLangVersion A versão do Razor idioma de destino.

Para obter mais informações sobre propriedades, consulte Propriedades do MSBuild.

Targets

O Razor SDK define dois destinos principais:

  • RazorGenerate: O código gera .cs arquivos a partir de elementos de RazorGenerate item. Use a RazorGenerateDependsOn propriedade para especificar destinos adicionais que podem ser executados antes ou depois desse destino.
  • RazorCompile: Compila os ficheiros gerados .cs num Razor assembly. Use o RazorCompileDependsOn para especificar destinos adicionais que podem ser executados antes ou depois desse destino.
  • RazorComponentGenerate: O código gera .cs ficheiros para RazorComponent elementos do item. Use a RazorComponentGenerateDependsOn propriedade para especificar destinos adicionais que podem ser executados antes ou depois desse destino.

Compilação de Razor vistas em tempo de execução

  • Por padrão, o SDK não publica assemblies de referência necessários para a compilação em tempo de execução Razor. Isso resulta em falhas de compilação quando o modelo de aplicativo depende da compilação em tempo de execução — por exemplo, o aplicativo usa modos de exibição incorporados ou altera modos de exibição depois que o aplicativo é publicado. Defina CopyRefAssembliesToPublishDirectory para true para continuar a publicar os assemblies de referência.

  • Para um aplicativo Web, verifique se seu aplicativo está direcionado ao Microsoft.NET.Sdk.Web SDK.

Razor Versão linguística

Ao apontar para o Microsoft.NET.Sdk.Web SDK, a versão de linguagem Razor é inferida a partir da versão do framework de destino do aplicativo. Para projetos destinados ao Microsoft.NET.Sdk.Razor SDK ou no raro caso de o aplicativo exigir uma versão de idioma 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>

Razor A versão de idioma está totalmente integrada com a versão do tempo de execução para o qual foi construída. O direcionamento de uma versão de idioma que não foi projetada para o tempo de execução não é suportado e provavelmente produz erros de compilação.

Recursos adicionais

  • Padroniza a experiência em torno da compilação, empacotamento e publicação de projetos contendo Razor ficheiros para projetos baseados em ASP.NET Core MVC.
  • Inclui um conjunto de destinos, propriedades e itens predefinidos que permitem personalizar a compilação de Razor arquivos.

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

Prerequisites

SDK do .NET Core 2.1 ou posterior

Utilizar o Razor SDK

A maioria dos aplicativos Web não precisa fazer referência explícita ao Razor SDK.

Para usar o Razor SDK para criar bibliotecas de classes contendo Razor visualizações ou Razor páginas:

  • Utilizar 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 para receber dependências adicionais que são necessárias para criar e compilar Razor páginas e Razor exibições. No mínimo, o seu projeto deverá adicionar referências de pacotes a:

    • 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 alvos para o projeto.

    Os pacotes anteriores estão incluídos no Microsoft.AspNetCore.Mvc. A marcação a seguir mostra um arquivo de projeto que usa o Razor SDK para criar Razor arquivos para um aplicativo ASP.NET Core Razor Pages:

    <Project Sdk="Microsoft.NET.Sdk.Razor">

  <PropertyGroup>
    <TargetFramework>netcoreapp2.1</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.1.3" />
  </ItemGroup>

</Project>

Warning

Os Microsoft.AspNetCore.Razor.Design pacotes e Microsoft.AspNetCore.Mvc.Razor.Extensions estão incluídos no metapacote Microsoft.AspNetCore.App. No entanto, a referência de pacote sem versão para Microsoft.AspNetCore.App fornece um metapacote à aplicação que não inclui a versão mais recente de 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 mais recentes durante o tempo de compilação de Razor sejam incluídas. Para obter mais informações, consulte este problema do GitHub.

Properties

As propriedades a seguir controlam o Razorcomportamento do SDK como parte de uma compilação de projeto:

  • RazorCompileOnBuild: Quando true, compila e emite o Razor assembly como parte da construção do projeto. O padrão é true.
  • RazorCompileOnPublish: Quando true, compila e emite a Razor montagem como parte da publicação do projeto. O padrão é true.

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

Items Description
RazorGenerate Elementos do item (.cshtml arquivos) que são entradas para o processo de geração de código.
RazorComponent Elementos de item (.razor arquivos) que são entradas para a Razor geração de código do componente.
RazorCompile Elementos do item (.cs ficheiros) que são entradas para os destinos de compilação Razor. Utilize este ItemGroup para especificar ficheiros adicionais a serem compilados na Razor assemblagem.
RazorTargetAssemblyAttribute Os elementos de item usados para codificar geram atributos para o Razor assembly. Por exemplo:
RazorAssemblyAttribute
Include="System.Reflection.AssemblyMetadataAttribute"
_Parameter1="BuildSource" _Parameter2="https://learn.microsoft.com/">
RazorEmbeddedResource Elementos de item adicionados como recursos incorporados ao assembly gerado Razor .
Property Description
RazorTargetName Nome do arquivo (sem extensão) do assembly produzido pelo Razor.
RazorOutputPath O Razor diretório de saída.
RazorCompileToolset Usado para determinar o conjunto de ferramentas usado para construir o Razor assembly. Os valores válidos são Implicit, RazorSDKe PrecompilationTool.
EnableDefaultContentItems A predefinição é true. Quando true, inclui web.config, .json e .cshtml ficheiros como conteúdo do projeto. Quando referenciados via Microsoft.NET.Sdk.Web, os ficheiros sob wwwroot e os ficheiros de configuração também estão incluídos.
EnableDefaultRazorGenerateItems Quando true, inclui .cshtml ficheiros de Content itens em RazorGenerate itens.
GenerateRazorTargetAssemblyInfo Quando true, gera um .cs arquivo contendo atributos especificados por RazorAssemblyAttribute e inclui o arquivo na saída da compilação.
EnableDefaultRazorTargetAssemblyInfoAttributes Quando true, adiciona um conjunto padrão de atributos de assembly ao RazorAssemblyAttribute.
CopyRazorGenerateFilesToPublishDirectory Quando true, copia RazorGenerate arquivos de itens (.cshtml) para o diretório de publicação. Normalmente, os ficheiros Razor não são necessários para uma aplicação publicada se participarem na compilação no momento da compilação ou da publicação. O padrão é false.
CopyRefAssembliesToPublishDirectory Quando true, copie itens de assembly de referência para o diretório de publicação. Normalmente, os assemblies de referência não são necessários para uma aplicação publicada se Razor a compilação ocorrer no momento da compilação ou no momento da publicação. Defina como true se seu aplicativo publicado requer compilação em tempo de execução. Por exemplo, defina o valor como true se o aplicativo modifica .cshtml arquivos em tempo de execução ou usa exibições incorporadas. O padrão é false.
IncludeRazorContentInPack Quando true, todos os Razor itens de conteúdo (.cshtml ficheiros) são marcados para inclusão no pacote NuGet gerado. O padrão é false.
EmbedRazorGenerateSources Quando true, adiciona os itens RazorGenerate (.cshtml) como ficheiros incorporados ao Razor assembly gerado. O padrão é false.
UseRazorBuildServer Quando true, usa um processo de servidor de compilação persistente para descarregar o trabalho de geração de código. O padrão é o valor de UseSharedCompilation.
GenerateMvcApplicationPartsAssemblyAttributes Quando true, o SDK gera atributos adicionais usados pelo MVC em tempo de execução para executar a descoberta de peças do aplicativo.
DefaultWebContentItemExcludes Um padrão de globbing para elementos de item que devem ser excluídos do grupo de itens Content em projetos voltados para a Web ou para o SDK Razor.
ExcludeConfigFilesFromBuildOutput Quando true, .config e .json arquivos não são copiados para o diretório de saída da compilação.
AddRazorSupportForMvc Quando true, configura o Razor SDK para adicionar suporte para a configuração MVC que é necessária ao criar aplicativos que contêm vistas MVC ou Razor Páginas. Esta propriedade é implicitamente definida para o .NET Core 3.0 ou projetos posteriores destinados ao SDK da Web
RazorLangVersion A versão do Razor idioma de destino.

Para obter mais informações sobre propriedades, consulte Propriedades do MSBuild.

Targets

O Razor SDK define dois destinos principais:

  • RazorGenerate: O código gera .cs arquivos a partir de elementos de RazorGenerate item. Use a RazorGenerateDependsOn propriedade para especificar destinos adicionais que podem ser executados antes ou depois desse destino.
  • RazorCompile: Compila os ficheiros gerados .cs num Razor assembly. Use o RazorCompileDependsOn para especificar destinos adicionais que podem ser executados antes ou depois desse destino.
  • RazorComponentGenerate: O código gera .cs ficheiros para RazorComponent elementos do item. Use a RazorComponentGenerateDependsOn propriedade para especificar destinos adicionais que podem ser executados antes ou depois desse destino.

Compilação de Razor vistas em tempo de execução

  • Por padrão, o SDK não publica assemblies de referência necessários para a compilação em tempo de execução Razor. Isso resulta em falhas de compilação quando o modelo de aplicativo depende da compilação em tempo de execução — por exemplo, o aplicativo usa modos de exibição incorporados ou altera modos de exibição depois que o aplicativo é publicado. Defina CopyRefAssembliesToPublishDirectory para true para continuar a publicar os assemblies de referência.

  • Para um aplicativo Web, verifique se seu aplicativo está direcionado ao Microsoft.NET.Sdk.Web SDK.

Razor Versão linguística

Ao apontar para o Microsoft.NET.Sdk.Web SDK, a versão de linguagem Razor é inferida a partir da versão do framework de destino do aplicativo. Para projetos destinados ao Microsoft.NET.Sdk.Razor SDK ou no raro caso de o aplicativo exigir uma versão de idioma 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>

Razor A versão de idioma está totalmente integrada com a versão do tempo de execução para o qual foi construída. O direcionamento de uma versão de idioma que não foi projetada para o tempo de execução não é suportado e provavelmente produz erros de compilação.

Recursos adicionais

  • Last updated on