SDK do Razor do ASP.NET CoreASP.NET Core Razor SDK

Por Rick AndersonBy Rick Anderson

Visão GeralOverview

O SDK do .NET Core 2.1 ou posteriores.NET Core 2.1 SDK or later inclui o SDK do MSBuild do Microsoft.NET.Sdk.Razor (SDK do Razor).The SDK do .NET Core 2.1 ou posteriores.NET Core 2.1 SDK or later includes the Microsoft.NET.Sdk.Razor MSBuild SDK (Razor SDK). O SDK do Razor:The Razor SDK:

  • É necessário para compilar, empacotar e publicar projetos que contenham arquivos Razor para ASP.NET Core projetos baseados em MVC ou Blazor .Is required to build, package, and publish projects containing Razor files for ASP.NET Core MVC-based or Blazor projects.
  • Inclui um conjunto de destinos, propriedades e itens predefinidos que permitem personalizar a compilação de arquivos Razor ( . cshtml ou . Razor).Includes a set of predefined targets, properties, and items that allow customizing the compilation of Razor (.cshtml or .razor) files.

O SDK do Razor inclui Content itens com Include atributos definidos para os padrões de mascaramento **\*.cshtml e **\*.razor.The Razor SDK includes Content items with Include attributes set to the **\*.cshtml and **\*.razor globbing patterns. Os arquivos correspondentes são publicados.Matching files are published.

  • 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.Standardizes the experience around building, packaging, and publishing projects containing Razor files for ASP.NET Core MVC-based projects.
  • Inclui um conjunto de destinos, propriedades e itens predefinidos que permitem personalizar a compilação de arquivos Razor.Includes a set of predefined targets, properties, and items that allow customizing the compilation of Razor files.

O SDK do Razor inclui um Content item com um atributo Include definido como o padrão de mascaramento **\*.cshtml.The Razor SDK includes a Content item with an Include attribute set to the **\*.cshtml globbing pattern. Os arquivos correspondentes são publicados.Matching files are published.

PrerequisitesPrerequisites

SDK do .NET Core 2.1 ou posteriores.NET Core 2.1 SDK or later

Usar o SDK do RazorUse the Razor SDK

A maioria dos aplicativos Web não é necessária para referenciar explicitamente o SDK do Razor.Most web apps aren't required to explicitly reference the Razor SDK.

Para usar o SDK do Razor para criar bibliotecas de classes que contêm exibições do Razor ou Razor Pages, é recomendável começar com o modelo de projeto RCL (biblioteca de classes Razor).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. Um RCL que é usado para compilar arquivos Blazor ( . Razor) requer minimamente uma referência ao pacote Microsoft. AspNetCore. Components .An RCL that's used to build Blazor (.razor) files minimally requires a reference to the Microsoft.AspNetCore.Components package. Um RCL que é usado para criar exibições ou páginas do Razor (arquivos . cshtml ) requer minimamente o direcionamento netcoreapp3.0 ou posterior e tem uma FrameworkReference ao metapacote Microsoft. AspNetCore. app em seu arquivo de projeto.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.

Para usar o SDK do Razor para criar bibliotecas de classe contendo exibições Razor ou Páginas Razor:To use the Razor SDK to build class libraries containing Razor views or Razor Pages:

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

    <Project SDK="Microsoft.NET.Sdk.Razor">
      <!-- omitted for brevity -->
    </Project>
    
  • Normalmente, uma referência de pacote a Microsoft.AspNetCore.Mvc é necessária para receber dependências adicionais que são necessárias para compilar e compilar Razor Pages e exibições do 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. No mínimo, o projeto deve adicionar referências de pacote a:At a minimum, your project should add package references to:

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

    O pacote de Microsoft.AspNetCore.Razor.Design fornece as tarefas de compilação do Razor e os destinos para o projeto.The Microsoft.AspNetCore.Razor.Design package provides the Razor compilation tasks and targets for the project.

    Os pacotes anteriores são incluídos em Microsoft.AspNetCore.Mvc.The preceding packages are included in 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 ASP.NET Core Razor Pages: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>
    

Aviso

Os pacotes Microsoft.AspNetCore.Razor.Design e Microsoft.AspNetCore.Mvc.Razor.Extensions estão incluídos no metapacote Microsoft. AspNetCore. app.The Microsoft.AspNetCore.Razor.Design and Microsoft.AspNetCore.Mvc.Razor.Extensions packages are included in the Microsoft.AspNetCore.App metapackage. No entanto, a referência de pacote sem versão Microsoft.AspNetCore.App fornece um metapacote para o aplicativo que não inclui a versão mais recente do 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. Os projetos devem fazer referência a uma versão consistente do Microsoft.AspNetCore.Razor.Design (ou Microsoft.AspNetCore.Mvc) para que as correções de tempo de compilação mais recentes para o Razor sejam incluídas.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. Para obter mais informações, consulte este problema do GitHub.For more information, see this GitHub issue.

PropriedadesProperties

As seguintes propriedades controlam o comportamento do SDK do Razor como parte de um build de projeto:The following properties control the Razor's SDK behavior as part of a project build:

  • RazorCompileOnBuild – quando true, compila e emite o assembly Razor como parte da criação do projeto.RazorCompileOnBuild – When true, compiles and emits the Razor assembly as part of building the project. Assume o padrão de true.Defaults to true.
  • RazorCompileOnPublish – quando true, compila e emite o assembly Razor como parte da publicação do projeto.RazorCompileOnPublish – When true, compiles and emits the Razor assembly as part of publishing the project. Assume o padrão de true.Defaults to true.

As propriedades e os itens na tabela a seguir são usados para configurar entradas e saídas para o SDK do Razor.The properties and items in the following table are used to configure inputs and output to the Razor SDK.

Aviso

A partir do ASP.NET Core 3,0, as exibições do MVC ou Razor Pages não são servidas por padrão se as propriedades RazorCompileOnBuild ou RazorCompileOnPublish do MSBuild no arquivo de projeto estão desabilitadas.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. Os aplicativos devem adicionar uma referência explícita ao pacote Microsoft. AspNetCore. Mvc. Razor. RuntimeCompilation se o aplicativo depender da compilação de tempo de execução para processar arquivos . 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.

ItensItems DescriçãoDescription
RazorGenerate Elementos de item (arquivos . cshtml ) que são entradas para geração de código.Item elements (.cshtml files) that are inputs to code generation.
RazorComponent Elementos de item (arquivos . Razor ) que são entradas para a geração de código de componente Razor.Item elements (.razor files) that are inputs to Razor component code generation.
RazorCompile Elementos de item (arquivos . cs ) que são entradas para destinos de compilação do Razor.Item elements (.cs files) that are inputs to Razor compilation targets. Use esta ItemGroup para especificar arquivos adicionais a serem compilados no assembly Razor.Use this ItemGroup to specify additional files to be compiled into the Razor assembly.
RazorTargetAssemblyAttribute Os elementos de item usados para a codificação geram atributos para o assembly Razor.Item elements used to code generate attributes for the Razor assembly. Por exemplo:For example:
RazorAssemblyAttribute
Include="System.Reflection.AssemblyMetadataAttribute"
_Parameter1="BuildSource" _Parameter2="https://docs.microsoft.com/">
RazorEmbeddedResource Elementos de item adicionados como recursos incorporados ao assembly do Razor gerado.Item elements added as embedded resources to the generated Razor assembly.
propriedadeProperty DescriçãoDescription
RazorTargetName Nome do arquivo (sem extensão) do assembly produzido pelo Razor.File name (without extension) of the assembly produced by Razor.
RazorOutputPath O diretório de saída do Razor.The Razor output directory.
RazorCompileToolset Usado para determinar o conjunto de ferramentas usado para criar o assembly do Razor.Used to determine the toolset used to build the Razor assembly. Os valores válidos são Implicit, RazorSDK e PrecompilationTool.Valid values are Implicit, RazorSDK, and PrecompilationTool.
EnableDefaultContentItemsEnableDefaultContentItems O padrão é true.Default is true. Quando true, inclui arquivos Web. config, . JSONe . cshtml como conteúdo no projeto.When true, includes web.config, .json, and .cshtml files as content in the project. Quando referenciado via Microsoft.NET.Sdk.Web, os arquivos em arquivos wwwroot e config também são incluídos.When referenced via Microsoft.NET.Sdk.Web, files under wwwroot and config files are also included.
EnableDefaultRazorGenerateItems Quando true, inclui arquivos .cshtml de itens de Content em itens de RazorGenerate.When true, includes .cshtml files from Content items in RazorGenerate items.
GenerateRazorTargetAssemblyInfo Quando true, o gera um arquivo . cs contendo atributos especificados por RazorAssemblyAttribute e inclui o arquivo na saída de compilação.When true, generates a .cs file containing attributes specified by RazorAssemblyAttribute and includes the file in the compile output.
EnableDefaultRazorTargetAssemblyInfoAttributes Quando true, adiciona um conjunto padrão de atributos de assembly em RazorAssemblyAttribute.When true, adds a default set of assembly attributes to RazorAssemblyAttribute.
CopyRazorGenerateFilesToPublishDirectory Quando true, o copia os arquivos de RazorGenerate itens ( . cshtml) para o diretório de publicação.When true, copies RazorGenerate items (.cshtml) files to the publish directory. Normalmente, os arquivos do Razor não são necessários para um aplicativo publicado se participarem da compilação em tempo de compilação ou em tempo de publicação.Typically, Razor files aren't required for a published app if they participate in compilation at build-time or publish-time. Assume o padrão de false.Defaults to false.
CopyRefAssembliesToPublishDirectory Quando true, copia os itens do assembly de referência no diretório de publicação.When true, copy reference assembly items to the publish directory. Normalmente, os assemblies de referência não são necessários para um aplicativo publicado se a compilação do Razor ocorrer em tempo de compilação ou em tempo de publicação.Typically, reference assemblies aren't required for a published app if Razor compilation occurs at build-time or publish-time. Defina como true se seu aplicativo publicado exigir compilação em tempo de execução.Set to true if your published app requires runtime compilation. Por exemplo, defina o valor como true se o aplicativo modificar arquivos . cshtml em tempo de execução ou usar exibições inseridas.For example, set the value to true if the app modifies .cshtml files at runtime or uses embedded views. Assume o padrão de false.Defaults to false.
IncludeRazorContentInPack Quando true, todos os itens de conteúdo do Razor (arquivos . cshtml ) são marcados para inclusão no pacote NuGet gerado.When true, all Razor content items (.cshtml files) are marked for inclusion in the generated NuGet package. Assume o padrão de false.Defaults to false.
EmbedRazorGenerateSources Quando true, adiciona itens de RazorGenerate ( .cshtml) como arquivos incorporados ao assembly Razor gerado.When true, adds RazorGenerate (.cshtml) items as embedded files to the generated Razor assembly. Assume o padrão de false.Defaults to false.
UseRazorBuildServer Quando true, usa um processo de servidor de build persistente para descarregar o trabalho de geração de código.When true, uses a persistent build server process to offload code generation work. Seu valor padrão é UseSharedCompilation.Defaults to the value of UseSharedCompilation.
GenerateMvcApplicationPartsAssemblyAttributes Quando true, o SDK gera atributos adicionais usados pelo MVC em tempo de execução para executar a descoberta de parte do aplicativo.When true, the SDK generates additional attributes used by MVC at runtime to perform application part discovery.

Para saber mais sobre as propriedades, confira Propriedades do MSBuild.For more information on properties, see MSBuild properties.

DestinosTargets

O SDK do Razor define dois destinos primários:The Razor SDK defines two primary targets:

  • RazorGenerate – código gera arquivos . cs de elementos RazorGenerate item.RazorGenerate – Code generates .cs files from RazorGenerate item elements. Use a propriedade RazorGenerateDependsOn para especificar destinos adicionais que podem ser executados antes ou depois desse destino.Use the RazorGenerateDependsOn property to specify additional targets that can run before or after this target.
  • RazorCompile – compila arquivos . cs gerados em um assembly Razor.RazorCompile – Compiles generated .cs files in to a Razor assembly. Use o RazorCompileDependsOn para especificar destinos adicionais que podem ser executados antes ou depois desse destino.Use the RazorCompileDependsOn to specify additional targets that can run before or after this target.
  • RazorComponentGenerate – código gera arquivos . cs para elementos de RazorComponent item.RazorComponentGenerate – Code generates .cs files for RazorComponent item elements. Use a propriedade RazorComponentGenerateDependsOn para especificar destinos adicionais que podem ser executados antes ou depois desse destino.Use the RazorComponentGenerateDependsOn property to specify additional targets that can run before or after this target.

Compilação de runtime de modos de exibição do RazorRuntime compilation of Razor views

  • 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.By default, the Razor SDK doesn't publish reference assemblies that are required to perform runtime compilation. 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.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. Defina CopyRefAssembliesToPublishDirectory como true para continuar publicando assemblies de referência.Set CopyRefAssembliesToPublishDirectory to true to continue publishing reference assemblies.

  • Para um aplicativo Web, verifique se seu aplicativo está direcionando o SDK do Microsoft.NET.Sdk.Web.For a web app, ensure your app is targeting the Microsoft.NET.Sdk.Web SDK.

Versão do idioma RazorRazor language version

Ao direcionar o SDK do Microsoft.NET.Sdk.Web, a versão do idioma do Razor é inferida a partir da versão da estrutura de destino do aplicativo.When targeting the Microsoft.NET.Sdk.Web SDK, the Razor language version is inferred from the app's target framework version. Para projetos direcionados ao SDK do Microsoft.NET.Sdk.Razor ou no caso raro de o aplicativo exigir uma versão diferente da linguagem Razor do que o valor inferido, uma versão pode ser configurada definindo a propriedade <RazorLangVersion> no arquivo de projeto do aplicativo: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>

A versão do idioma do Razor está totalmente integrada à versão do tempo de execução para a qual foi criada.Razor's language version is tightly integrated with the version of the runtime that it was built for. O direcionamento de uma versão de idioma que não é projetada para o tempo de execução não é suportado e provavelmente produz erros de compilação.Targeting a language version that isn't designed for the runtime is unsupported and likely produces build errors.

Recursos adicionaisAdditional resources