Kit SDK ASP.NET Core Razor

Par Rick Anderson

Vue d’ensemble

Le kit SDK .NET 6.0 inclut le kit SDK Microsoft.NET.Sdk.Razor MSBuild (kit SDK Razor). Le kit SDK Razor :

• Est requis pour générer, empaqueter et publier des projets contenant des fichiers Razor pour des projets basés sur ASP.NET Core MVC ou Blazor.
• Inclut un ensemble de propriétés prédéfinies et d’éléments qui permettent de personnaliser la compilation des fichiers Razor (.cshtml ou .razor).

Le kit SDK Razor inclut des éléments Content avec des attributs Include définis sur les modèles d’utilisation des caractères génériques **\*.cshtml et **\*.razor. Les fichiers correspondants sont publiés.

Prérequis

SDK .NET 6.0

Utiliser le kit SDK Razor

La plupart des applications web ne sont pas tenues de référencer explicitement le kit SDK Razor.

Pour utiliser le kit SDK Razor afin de créer des bibliothèques de classes contenant des vues Razor ou des pages Razor, nous vous recommandons de commencer par le modèle de projet de bibliothèque de classes Razor (RCL). Une bibliothèque RCL utilisée pour générer des fichiers Blazor (.razor) nécessite au minimum une référence au package Microsoft.AspNetCore.Components. Une bibliothèque RCL utilisée pour générer des vues ou des pages Razor (fichiers .cshtml) nécessite un ciblage minimal de netcoreapp3.0 ou version ultérieure et a une référence FrameworkReference au métapackage Microsoft.AspNetCore.App dans son fichier projet.

Propriétés

Les propriétés suivantes contrôlent le comportement du kit SDK Razor dans le cadre d’une build de projet :

• RazorCompileOnBuild : si la valeur est true, compile et émet l’assembly Razor dans le cadre de la génération du projet. La valeur par défaut est true.
• RazorCompileOnPublish : si la valeur est true, compile et émet l’assembly Razor dans le cadre de la publication du projet. La valeur par défaut est true.
• UseRazorSourceGenerator : a la valeur par défaut true. Quand : true
  • Compile à l’aide de la génération source.
  • Ne crée pas <app_name>.Views.dll. Les vues sont incluses dans <app_name>.dll.
  • Prend en charge le rechargement à chaud .NET.

Les propriétés et éléments du tableau suivant sont utilisés pour configurer les entrées et la sortie du kit SDK Razor.

Éléments	Description
RazorGenerate	Composants d’élément (fichiers .cshtml) fournis en entrée à la génération de code.
RazorComponent	Composants d’élément (fichiers .razor) fournis en entrée à la génération de code de composant Razor.
RazorCompile	Composants d’élément (fichiers .cs) fournis en entrée aux cibles de compilation Razor. Utilisez ItemGroup pour spécifier d’autres fichiers à compiler dans l’assembly Razor.
RazorEmbeddedResource	Composants d’élément ajoutés comme ressources incorporées à l’assembly Razor généré.

Propriété	Description
RazorOutputPath	Répertoire de sortie Razor.
RazorCompileToolset	Utilisé pour déterminer l’ensemble d’outils utilisé pour générer l’assembly Razor. Les valeurs correctes sont Implicit, RazorSDK et PrecompilationTool.
EnableDefaultContentItems	La valeur par défaut est true. Si la valeur est true, inclut les fichiers web.config, .json et .cshtml en tant que contenu dans le projet. Lorsqu’ils sont référencés via Microsoft.NET.Sdk.Web, les fichiers sous wwwroot et les fichiers de configuration sont également inclus.
EnableDefaultRazorGenerateItems	Si la valeur est true, inclut les fichiers .cshtml des éléments Content dans les éléments RazorGenerate.
GenerateRazorTargetAssemblyInfo	Non utilisé dans .NET 6 et versions ultérieures.
EnableDefaultRazorTargetAssemblyInfoAttributes	Non utilisé dans .NET 6 et versions ultérieures.
CopyRazorGenerateFilesToPublishDirectory	Si la valeur est true, copie les fichiers (.cshtml) des éléments RazorGenerate dans le répertoire de publication. En général, une application publiée ne nécessite pas de fichiers Razor s’ils participent à la compilation au moment de la génération ou de la publication. La valeur par défaut est false.
PreserveCompilationReferences	Si la valeur est true, copie les éléments d’assembly de référence dans le répertoire de publication. En général, une application publiée ne nécessite pas d’assemblys de référence si la compilation Razor se produit au moment de la génération ou de la publication. Définissez sur true si votre application publiée nécessite une compilation au moment de l’exécution. Par exemple, définissez la valeur sur true si l’application modifie les fichiers .cshtml au moment de l’exécution ou utilise des vues incorporées. La valeur par défaut est false.
IncludeRazorContentInPack	Si la valeur est true, tous les éléments de contenu Razor (fichiers .cshtml) sont marqués pour inclusion dans le package NuGet généré. La valeur par défaut est false.
EmbedRazorGenerateSources	Si la valeur est true, ajoute des éléments RazorGenerate (.cshtml) comme fichiers incorporés à l’assembly Razor généré. La valeur par défaut est false.
GenerateMvcApplicationPartsAssemblyAttributes	Non utilisé dans .NET 6 et versions ultérieures.
DefaultWebContentItemExcludes	Modèle d’utilisation des caractères génériques pour les composants d’élément qui doivent être exclus du groupe d’éléments Content dans les projets ciblant le kit SDK Web ou Razor
ExcludeConfigFilesFromBuildOutput	Si la valeur est true, les fichiers .config et .json ne sont pas copiés dans le répertoire de sortie de build.
AddRazorSupportForMvc	Si la valeur est true, configure le kit SDK Razor pour ajouter la prise en charge de la configuration MVC requise lors de la création d’applications contenant des vues MVC ou des pages Razor. Cette propriété est implicitement définie pour les projets .NET Core 3.0 ou version ultérieure ciblant le kit SDK Web.
RazorLangVersion	Version du langage Razor à cibler.
EmitCompilerGeneratedFiles	Si la valeur est définie sur true, les fichiers sources générés sont écrits sur le disque. La définition de la valeur true est utile lors du débogage du compilateur. Par défaut, il s’agit de false.

Pour plus d’informations sur les propriétés, voir Propriétés MSBuild.

Compilation au moment de l’exécution des vues Razor

• Par défaut, le kit SDK Razor ne publie pas les assemblys de référence nécessaires à l’exécution de la compilation au moment de l’exécution. Cela entraîne des échecs de compilation quand le modèle d’application s’appuie sur la compilation au moment de l’exécution (par exemple, l’application utilise des vues incorporées ou change les vues une fois l’application publiée). Définissez CopyRefAssembliesToPublishDirectory sur true pour continuer à publier les assemblys de référence. La génération et la compilation de code sont prises en charge par un seul appel au compilateur. Un assembly unique est produit qui contient les types d’application et les vues générées.

• Pour une web application, veillez à ce que votre application cible le kit SDK Microsoft.NET.Sdk.Web.

Version du langage Razor

Lorsque vous ciblez le kit SDK Microsoft.NET.Sdk.Web, la version du langage Razor est déduite de la version de l’infrastructure cible de l’application. Pour les projets ciblant le kit SDK Microsoft.NET.Sdk.Razor ou dans les rares cas où l’application nécessite une version de langage Razor différente de la valeur déduite, une version peut être configurée en définissant la propriété <RazorLangVersion> dans le fichier projet de l’application :

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

La version du langage Razor est étroitement intégrée à la version du runtime pour laquelle elle a été créée. Le ciblage d’une version de langage qui n’est pas conçue pour le runtime n’est pas pris en charge et générera probablement des erreurs de build.

Ressources supplémentaires

• Ajouts au format csproj pour .NET Core
• Éléments communs des projets MSBuild