ASP.NET Core Razor SDKASP.NET Core Razor SDK

Di Rick AndersonBy Rick Anderson

PanoramicaOverview

Il .NET Core 2.1 SDK o versione successiva.NET Core 2.1 SDK or later include Microsoft.NET.Sdk.Razor MSBuild SDK (Razor SDK).The .NET Core 2.1 SDK o versione successiva.NET Core 2.1 SDK or later includes the Microsoft.NET.Sdk.Razor MSBuild SDK (Razor SDK). Il Razor SDK:The Razor SDK:

  • È necessario per compilare, creare pacchetti e pubblicare progetti contenenti file Razor per ASP.NET Core progetti basati su MVC o Blazor .Is required to build, package, and publish projects containing Razor files for ASP.NET Core MVC-based or Blazor projects.
  • Include un set di destinazioni, proprietà ed elementi predefiniti che consentono di personalizzare la compilazione dei file Razor ( . cshtml o . Razor).Includes a set of predefined targets, properties, and items that allow customizing the compilation of Razor (.cshtml or .razor) files.

Razor SDK include Content elementi con Include attributi impostati sui modelli di **\*.cshtml e **\*.razor glob.The Razor SDK includes Content items with Include attributes set to the **\*.cshtml and **\*.razor globbing patterns. I file corrispondenti vengono pubblicati.Matching files are published.

  • Consente di standardizzare l'esperienza in termini di compilazione, creazione dei pacchetti e pubblicazione dei progetti contenenti file Razor per i progetti ASP.NET Core basati su MVC.Standardizes the experience around building, packaging, and publishing projects containing Razor files for ASP.NET Core MVC-based projects.
  • Include un set di destinazioni, proprietà e di elementi predefiniti che consentono di personalizzare la compilazione dei file Razor.Includes a set of predefined targets, properties, and items that allow customizing the compilation of Razor files.

Razor SDK include un elemento di Content con un attributo Include impostato sul modello **\*.cshtml glob.The Razor SDK includes a Content item with an Include attribute set to the **\*.cshtml globbing pattern. I file corrispondenti vengono pubblicati.Matching files are published.

PrerequisitesPrerequisites

.NET Core 2.1 SDK o versione successiva.NET Core 2.1 SDK or later

Usare Razor SDKUse the Razor SDK

La maggior parte delle app Web non è necessaria per fare riferimento in modo esplicito a Razor SDK.Most web apps aren't required to explicitly reference the Razor SDK.

Per usare Razor SDK per compilare librerie di classi contenenti visualizzazioni Razor o Razor Pages, è consigliabile iniziare con il modello di progetto libreria di classi Razor (RCL).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. Un RCL usato per compilare i file di Blazor (Razor) richiede almeno un riferimento al pacchetto Microsoft. AspNetCore. Components .An RCL that's used to build Blazor (.razor) files minimally requires a reference to the Microsoft.AspNetCore.Components package. Un RCL usato per compilare visualizzazioni o pagine Razor (file conestensione cshtml ) richiede almeno la destinazione netcoreapp3.0 o versione successiva e ha una FrameworkReference al metapacchetto Microsoft. AspNetCore. app nel file di progetto.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.

Per usare il Razor SDK per compilare librerie di classi contenenti visualizzazioni Razor o Razor Pages:To use the Razor SDK to build class libraries containing Razor views or Razor Pages:

  • Usare Microsoft.NET.Sdk.Razor anziché Microsoft.NET.Sdk:Use Microsoft.NET.Sdk.Razor instead of Microsoft.NET.Sdk:

    <Project SDK="Microsoft.NET.Sdk.Razor">
      <!-- omitted for brevity -->
    </Project>
    
  • In genere, è necessario un riferimento al pacchetto Microsoft.AspNetCore.Mvc per ricevere dipendenze aggiuntive necessarie per compilare e compilare Razor Pages e visualizzazioni 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. Come minimo, il progetto deve aggiungere riferimenti a pacchetti:At a minimum, your project should add package references to:

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

    Il pacchetto di Microsoft.AspNetCore.Razor.Design fornisce le attività di compilazione Razor e le destinazioni per il progetto.The Microsoft.AspNetCore.Razor.Design package provides the Razor compilation tasks and targets for the project.

    I pacchetti precedenti sono inclusi in Microsoft.AspNetCore.Mvc.The preceding packages are included in Microsoft.AspNetCore.Mvc. Il markup seguente illustra un file di progetto che usa Razor SDK per compilare file Razor per un'app Razor Pages ASP.NET Core: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>
    

Avviso

I pacchetti Microsoft.AspNetCore.Razor.Design e Microsoft.AspNetCore.Mvc.Razor.Extensions sono inclusi nel metapacchetto Microsoft. AspNetCore. app.The Microsoft.AspNetCore.Razor.Design and Microsoft.AspNetCore.Mvc.Razor.Extensions packages are included in the Microsoft.AspNetCore.App metapackage. Tuttavia, la versione meno Microsoft.AspNetCore.App riferimento al pacchetto fornisce un metapacchetto all'app che non include la versione più recente di 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. I progetti devono fare riferimento a una versione coerente di Microsoft.AspNetCore.Razor.Design (o Microsoft.AspNetCore.Mvc), in modo che siano incluse le correzioni più recenti della fase di compilazione per Razor.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. Per altre informazioni, vedere questo problema di GitHub.For more information, see this GitHub issue.

ProprietàProperties

Le proprietà seguenti controllano il comportamento del Razor SDK come parte della compilazione del progetto:The following properties control the Razor's SDK behavior as part of a project build:

  • RazorCompileOnBuild – quando true, compila ed emette l'assembly Razor come parte della compilazione del progetto.RazorCompileOnBuild – When true, compiles and emits the Razor assembly as part of building the project. Il valore predefinito è true.Defaults to true.
  • RazorCompileOnPublish – quando true, compila ed emette l'assembly Razor come parte della pubblicazione del progetto.RazorCompileOnPublish – When true, compiles and emits the Razor assembly as part of publishing the project. Il valore predefinito è true.Defaults to true.

Le proprietà e gli elementi nella tabella seguente vengono usati per configurare gli input e l'output per Razor SDK.The properties and items in the following table are used to configure inputs and output to the Razor SDK.

Avviso

A partire da ASP.NET Core 3,0, le visualizzazioni MVC o Razor Pages non vengono gestite per impostazione predefinita se le proprietà RazorCompileOnBuild o RazorCompileOnPublish MSBuild nel file di progetto sono disabilitate.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. Le applicazioni devono aggiungere un riferimento esplicito al pacchetto Microsoft. AspNetCore. Mvc. Razor. RuntimeCompilation se l'app si basa sulla compilazione di runtime per elaborare i file con estensione 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.

ElementiItems DescrizioneDescription
RazorGenerate Elementi Item (file conestensione cshtml ) che sono input per la generazione di codice.Item elements (.cshtml files) that are inputs to code generation.
RazorComponent Elementi elemento (fileRazor ) che sono input per la generazione di codice del componente Razor.Item elements (.razor files) that are inputs to Razor component code generation.
RazorCompile Elementi Item (file conestensione cs ) che sono input per le destinazioni di compilazione Razor.Item elements (.cs files) that are inputs to Razor compilation targets. Usare questa ItemGroup per specificare i file aggiuntivi da compilare nell'assembly Razor.Use this ItemGroup to specify additional files to be compiled into the Razor assembly.
RazorTargetAssemblyAttribute Elementi della voce usati per attributi di generazione del codice per l'assembly Razor.Item elements used to code generate attributes for the Razor assembly. Esempio:For example:
RazorAssemblyAttribute
Include="System.Reflection.AssemblyMetadataAttribute"
_Parameter1="BuildSource" _Parameter2="https://docs.microsoft.com/">
RazorEmbeddedResource Elementi elemento aggiunti come risorse incorporate all'assembly Razor generato.Item elements added as embedded resources to the generated Razor assembly.
proprietàProperty DescrizioneDescription
RazorTargetName Nome di file (senza estensione) dell'assembly generato da Razor.File name (without extension) of the assembly produced by Razor.
RazorOutputPath Directory di output di Razor.The Razor output directory.
RazorCompileToolset Usato per determinare il set di strumenti utilizzato per compilare l'assembly Razor.Used to determine the toolset used to build the Razor assembly. I valori validi sono Implicit, RazorSDK e PrecompilationTool.Valid values are Implicit, RazorSDK, and PrecompilationTool.
EnableDefaultContentItemsEnableDefaultContentItems Il valore predefinito è true.Default is true. Quando true, include i file Web. config, . JSONe . cshtml come contenuto nel progetto.When true, includes web.config, .json, and .cshtml files as content in the project. Quando si fa riferimento tramite Microsoft.NET.Sdk.Web, vengono inclusi anche i file in wwwroot e nei file di configurazione.When referenced via Microsoft.NET.Sdk.Web, files under wwwroot and config files are also included.
EnableDefaultRazorGenerateItems Quando è true, include i file cshtml degli elementi di Content negli elementi di RazorGenerate.When true, includes .cshtml files from Content items in RazorGenerate items.
GenerateRazorTargetAssemblyInfo Quando true, genera un file con estensione cs contenente gli attributi specificati da RazorAssemblyAttribute e include il file nell'output di compilazione.When true, generates a .cs file containing attributes specified by RazorAssemblyAttribute and includes the file in the compile output.
EnableDefaultRazorTargetAssemblyInfoAttributes Quando è true, aggiunge un set predefinito di attributi degli assembly a RazorAssemblyAttribute.When true, adds a default set of assembly attributes to RazorAssemblyAttribute.
CopyRazorGenerateFilesToPublishDirectory Quando true, RazorGenerate copia i file di elementi (conestensione cshtml) nella directory di pubblicazione.When true, copies RazorGenerate items (.cshtml) files to the publish directory. In genere, i file Razor non sono necessari per un'app pubblicata se partecipano alla compilazione in fase di compilazione o di pubblicazione.Typically, Razor files aren't required for a published app if they participate in compilation at build-time or publish-time. Il valore predefinito è false.Defaults to false.
CopyRefAssembliesToPublishDirectory Quando è true, copiare gli elementi dell'assembly di riferimento nella directory di pubblicazione.When true, copy reference assembly items to the publish directory. Gli assembly di riferimento non sono in genere necessari per un'app pubblicata se la compilazione Razor viene eseguita in fase di compilazione o di pubblicazione.Typically, reference assemblies aren't required for a published app if Razor compilation occurs at build-time or publish-time. Impostare su true se l'app pubblicata richiede la compilazione del runtime.Set to true if your published app requires runtime compilation. Ad esempio, impostare il valore su true se l'app modifica i file cshtml in fase di esecuzione o usa le visualizzazioni incorporate.For example, set the value to true if the app modifies .cshtml files at runtime or uses embedded views. Il valore predefinito è false.Defaults to false.
IncludeRazorContentInPack Quando true, tutti gli elementi di contenuto Razor (file conestensione cshtml ) vengono contrassegnati per l'inclusione nel pacchetto NuGet generato.When true, all Razor content items (.cshtml files) are marked for inclusion in the generated NuGet package. Il valore predefinito è false.Defaults to false.
EmbedRazorGenerateSources Quando è true, aggiunge gli elementi (cshtml) di RazorGenerate come file incorporati nell'assembly Razor generato.When true, adds RazorGenerate (.cshtml) items as embedded files to the generated Razor assembly. Il valore predefinito è false.Defaults to false.
UseRazorBuildServer Quando è true, usa un processo del server di compilazione permanente per ripartire il lavoro di generazione del codice.When true, uses a persistent build server process to offload code generation work. Valore predefinito è il valore di UseSharedCompilation.Defaults to the value of UseSharedCompilation.
GenerateMvcApplicationPartsAssemblyAttributes Quando true, l'SDK genera attributi aggiuntivi usati da MVC in fase di esecuzione per eseguire l'individuazione delle parti dell'applicazione.When true, the SDK generates additional attributes used by MVC at runtime to perform application part discovery.

Per altre informazioni sulle proprietà, vedere Proprietà di MSBuild.For more information on properties, see MSBuild properties.

DestinazioniTargets

Il Razor SDK definisce due obiettivi principali:The Razor SDK defines two primary targets:

  • RazorGenerate codice – genera file con estensione cs da elementi RazorGenerate elemento.RazorGenerate – Code generates .cs files from RazorGenerate item elements. Utilizzare la proprietà RazorGenerateDependsOn per specificare destinazioni aggiuntive che possono essere eseguite prima o dopo questa destinazione.Use the RazorGenerateDependsOn property to specify additional targets that can run before or after this target.
  • RazorCompile – compila i file con estensione cs generati in un assembly Razor.RazorCompile – Compiles generated .cs files in to a Razor assembly. Usare il RazorCompileDependsOn per specificare destinazioni aggiuntive che possono essere eseguite prima o dopo questa destinazione.Use the RazorCompileDependsOn to specify additional targets that can run before or after this target.
  • RazorComponentGenerate codice – genera file con estensione cs per gli elementi RazorComponent elemento.RazorComponentGenerate – Code generates .cs files for RazorComponent item elements. Utilizzare la proprietà RazorComponentGenerateDependsOn per specificare destinazioni aggiuntive che possono essere eseguite prima o dopo questa destinazione.Use the RazorComponentGenerateDependsOn property to specify additional targets that can run before or after this target.

Compilazione runtime di visualizzazioni RazorRuntime compilation of Razor views

  • Per impostazione predefinita, Razor SDK non pubblica gli assembly di riferimento necessari per eseguire la compilazione runtime.By default, the Razor SDK doesn't publish reference assemblies that are required to perform runtime compilation. Vengono pertanto generati errori di compilazione nel caso in cui il modello di applicazione si basi su una compilazione runtime—ad esempio, l'app usa visualizzazioni incorporate o modifica le visualizzazioni dopo aver pubblicato l'app.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. Impostare CopyRefAssembliesToPublishDirectory su true per continuare con la pubblicazione degli assembly di riferimento.Set CopyRefAssembliesToPublishDirectory to true to continue publishing reference assemblies.

  • Per un'app Web, verificare che l'app sia destinata a Microsoft.NET.Sdk.Web SDK.For a web app, ensure your app is targeting the Microsoft.NET.Sdk.Web SDK.

Versione della lingua RazorRazor language version

Quando la destinazione è Microsoft.NET.Sdk.Web SDK, la versione della lingua Razor viene dedotta dalla versione del Framework di destinazione dell'app.When targeting the Microsoft.NET.Sdk.Web SDK, the Razor language version is inferred from the app's target framework version. Per i progetti destinati a Microsoft.NET.Sdk.Razor SDK o nel raro caso in cui l'app richieda una versione diversa della lingua Razor rispetto al valore derivato, è possibile configurare una versione impostando la proprietà <RazorLangVersion> nel file di progetto dell'app: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>

La versione del linguaggio Razor è strettamente integrata con la versione del runtime per cui è stata creata.Razor's language version is tightly integrated with the version of the runtime that it was built for. La destinazione di una versione di linguaggio non progettata per il runtime non è supportata e probabilmente genera errori di compilazione.Targeting a language version that isn't designed for the runtime is unsupported and likely produces build errors.

Risorse aggiuntiveAdditional resources