Dela via

ASP.NET Core Razor SDK

Av Rick Anderson

Översikt

.NET 6 SDK innehåller Microsoft.NET.Sdk.Razor MSBuild SDK (RazorSDK). Razor SDK:et:

  • Krävs för att skapa, paketera och publicera projekt som innehåller Razor filer för ASP.NET Core MVC-baserade eller Blazor projekt.
  • Innehåller en uppsättning fördefinierade egenskaper och objekt som gör det möjligt att anpassa kompileringen av Razor (.cshtml eller .razor) filer.

Razor SDK:et innehåller Content objekt med Include attribut inställda på **\*.cshtml och **\*.razor globbmönster. Matchande filer publiceras.

Förutsättningar

.NET 6 SDK

Använd Razor SDK

De flesta webbappar behöver inte uttryckligen hänvisa till SDK:t Razor.

Om du vill använda Razor SDK:t för att skapa klassbibliotek som innehåller Razor vyer eller Razor sidor rekommenderar vi att du börjar med projektmallen Razor klassbibliotek (RCL). En RCL som används för att skapa Blazor (.razor) filer kräver minimalt en referens till paketet Microsoft.AspNetCore.Components . En RCL som används för att skapa Razor vyer eller sidor (.cshtml filer) kräver minst netcoreapp3.0 eller senare och har en FrameworkReference till Microsoft.AspNetCore.App metapaketet i sin projektfil.

Egenskaper

Följande egenskaper styr RazorSDK-beteendet som en del av en projektversion:

  • RazorCompileOnBuild: När true kompilerar och genererar Razor sammansättningen som en del av projektets byggprocess. Standardinställningen är true.
  • RazorCompileOnPublish: När truekompilerar och genererar Razor sammansättningen som en del av publiceringen av projektet. Standardinställningen är true.
  • UseRazorSourceGenerator: Standardvärdet är true. När true:
    • Kompilerar med källgenerering.
    • Skapar inte <app_name>.Views.dll. Vyer ingår i <app_name>.dll.
    • Stöder .NET Hot Reload.

Egenskaperna och objekten i följande tabell används för att konfigurera indata och utdata till SDK:t Razor .

Föremål Beskrivning
RazorGenerate Objektelement (.cshtml filer) som är indata för kodgenerering.
RazorComponent Objektelement (.razor filer) som är indata för Razor komponentkodgenerering.
RazorCompile Objektelement (.cs filer) som är indata till Razor kompileringsmål. Använd det här ItemGroup alternativet om du vill ange ytterligare filer som ska kompileras till Razor sammansättningen.
RazorEmbeddedResource Objektelement har lagts till som inbäddade resurser i den genererade Razor sammansättningen.
Fastighet Beskrivning
RazorOutputPath Utdatakatalogen Razor.
RazorCompileToolset Används för att fastställa den verktygsuppsättning som används för att skapa Razor sammansättningen. Giltiga värden är Implicit, RazorSDKoch PrecompilationTool.
AktiveraStandardInnehållsObjekt Standard är true. När true, innehåller web.config, .json och .cshtml-filer som innehåll i projektet. När de refereras via Microsoft.NET.Sdk.Webinkluderas även filer under wwwroot - och konfigurationsfiler.
EnableDefaultRazorGenerateItems När true inkluderar .cshtml-filer från Content objekt i RazorGenerate objekt.
GenerateRazorTargetAssemblyInfo Används inte i .NET 6 eller senare.
EnableDefaultRazorTargetAssemblyInfoAttributes Används inte i .NET 6 eller senare.
CopyRazorGenerateFilesToPublishDirectory När du true kopierar RazorGenerate objektfiler (.cshtml) till publiceringskatalogen. En publicerad app kräver normalt inte Razor filer om de deltar i kompileringen vid byggtillfälle eller publicering. Standardinställningen är false.
PreserveCompilationReferences När truekopierar du referenssammansättningsobjekt till publiceringskatalogen. Normalt krävs inte referenssammansättningar för en publicerad app om Razor kompilering sker vid byggtid eller publiceringstid. Ställ in till true om den publicerade appen kräver körningskompilering. Ange till exempel värdet till true om appen ändrar .cshtml filer vid körning eller använder inbäddade vyer. Standardinställningen är false.
IncludeRazorContentInPack När truemarkeras alla Razor innehållsobjekt (.cshtml filer) för inkludering i det genererade NuGet-paketet. Standardinställningen är false.
EmbedRazorGenerateSources När truelägger du till RazorGenerate-objekt (.cshtml) som inbäddade filer i den genererade Razor sammansättningen. Standardinställningen är false.
GenerateMvcApplicationPartsAssemblyAttributes Används inte i .NET 6 eller senare.
DefaultWebContentItemExcludes Ett mönster för globbing för objektelement som ska undantas från Content objektgruppen i projekt som är avsedda för webben eller Razor SDK
ExcludeConfigFilesFromBuildOutput När true, .config och .json filer inte kopieras till utdatakatalogen för bygget.
AddRazorSupportForMvc När true konfigurerar du Razor SDK:t för att lägga till stöd för den nödvändiga MVC-konfigurationen när du bygger program som innehåller MVC-vyer eller Razor-sidor. Den här egenskapen anges implicit för .NET Core 3.0- eller senare projekt som riktar sig till Webb-SDK
RazorLangVersion Versionen av Razor-språket som ska riktas.
EmitCompilerGeneratedFiles När värdet trueär inställt på skrivs de genererade källfilerna till disk. Inställningen till true är användbar när du felsöker kompilatorn. Standardvärdet är false.

Mer information om egenskaper finns i MSBuild-egenskaper.

Körningskompilering av Razor vyer

  • SDK publicerar som standard Razor inte referenssammansättningar som krävs för att genomföra körningskompilering. Detta resulterar i kompileringsfel när programmodellen förlitar sig på körningskompilering, till exempel använder appen inbäddade vyer eller ändrar vyer när appen har publicerats. Ställ in CopyRefAssembliesToPublishDirectory till true för att fortsätta publicera referenssammansättningar. Både kodgenerering och kompilering stöds av ett enda anrop till kompilatorn. En enskild sammansättning skapas som innehåller apptyperna och de genererade vyerna.

  • För en webbapp kontrollerar du att din app riktar in sig på SDK:t Microsoft.NET.Sdk.Web .

Razor språkversion

När du riktar in dig på Microsoft.NET.Sdk.Web SDK:et Razor härleds språkversionen från appens målramverksversion. För projekt som riktar sig till Microsoft.NET.Sdk.Razor SDK eller i sällsynta fall att appen kräver en annan Razor språkversion än det här angivna värdet kan en version konfigureras genom att ange <RazorLangVersion> egenskapen i appens projektfil:

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

Razor:s språkversion är nära integrerad med den version av körmiljön som den skapades för. Det går inte att använda en språkversion som inte är avsedd för körmiljön och som sannolikt ger upphov till byggfel.

Ytterligare resurser

.NET Core 2.1 eller senare SDK innehåller Microsoft.NET.Sdk.Razor MSBuild SDK (RazorSDK). Razor SDK:et:

  • Krävs för att skapa, paketera och publicera projekt som innehåller Razor filer för ASP.NET Core MVC-baserade eller Blazor projekt.
  • Innehåller en uppsättning fördefinierade mål, egenskaper och objekt som gör det möjligt att anpassa kompileringen av Razor (.cshtml eller .razor) filer.

Razor SDK:et innehåller Content objekt med Include attribut inställda på **\*.cshtml och **\*.razor globbmönster. Matchande filer publiceras.

Förutsättningar

.NET Core 2.1 eller senare SDK

Använd Razor SDK

De flesta webbappar behöver inte uttryckligen hänvisa till SDK:t Razor.

Om du vill använda Razor SDK:t för att skapa klassbibliotek som innehåller Razor vyer eller Razor sidor rekommenderar vi att du börjar med projektmallen Razor klassbibliotek (RCL). En RCL som används för att skapa Blazor (.razor) filer kräver minimalt en referens till paketet Microsoft.AspNetCore.Components . En RCL som används för att skapa Razor vyer eller sidor (.cshtml filer) kräver minst netcoreapp3.0 eller senare och har en FrameworkReference till Microsoft.AspNetCore.App metapaketet i sin projektfil.

Egenskaper

Följande egenskaper styr RazorSDK-beteendet som en del av en projektversion:

  • RazorCompileOnBuild: När true kompilerar och genererar Razor sammansättningen som en del av projektets byggprocess. Standardinställningen är true.
  • RazorCompileOnPublish: När truekompilerar och genererar Razor sammansättningen som en del av publiceringen av projektet. Standardinställningen är true.

Egenskaperna och objekten i följande tabell används för att konfigurera indata och utdata till SDK:t Razor .

Varning

Från och med ASP.NET Core 3.0 hanteras inte MVC-vyer eller Razor -sidor som standard om RazorCompileOnBuild egenskaperna eller RazorCompileOnPublish MSBuild i projektfilen är inaktiverade. Program måste lägga till en explicit referens till Microsoft.AspNetCore.Mvc.Razor. RuntimeCompilation-paket om appen förlitar sig på körningskompilering för att bearbeta .cshtml filer.

Föremål Beskrivning
RazorGenerate Objektelement (.cshtml filer) som är indata för kodgenerering.
RazorComponent Objektelement (.razor filer) som är indata för Razor komponentkodgenerering.
RazorCompile Objektelement (.cs filer) som är indata till Razor kompileringsmål. Använd det här ItemGroup alternativet om du vill ange ytterligare filer som ska kompileras till Razor sammansättningen.
RazorTargetAssemblyAttribute Objektelement som används för att koda genererar attribut för Razor sammansättningen. Till exempel:
RazorAssemblyAttribute
Include="System.Reflection.AssemblyMetadataAttribute"
_Parameter1="BuildSource" _Parameter2="https://learn.microsoft.com/">
RazorEmbeddedResource Objektelement har lagts till som inbäddade resurser i den genererade Razor sammansättningen.
Fastighet Beskrivning
RazorTargetName Filnamn (utan tillägg) för sammansättningen som skapas av Razor.
RazorOutputPath Utdatakatalogen Razor.
RazorCompileToolset Används för att fastställa den verktygsuppsättning som används för att skapa Razor sammansättningen. Giltiga värden är Implicit, RazorSDKoch PrecompilationTool.
AktiveraStandardInnehållsObjekt Standard är true. När true, innehåller web.config, .json och .cshtml-filer som innehåll i projektet. När de refereras via Microsoft.NET.Sdk.Webinkluderas även filer under wwwroot - och konfigurationsfiler.
EnableDefaultRazorGenerateItems När true inkluderar .cshtml-filer från Content objekt i RazorGenerate objekt.
GenerateRazorTargetAssemblyInfo När truegenererar en .cs fil som innehåller attribut som anges av RazorAssemblyAttribute och innehåller filen i kompileringsutdata.
EnableDefaultRazorTargetAssemblyInfoAttributes När truelägger till en standarduppsättning sammansättningsattribut till RazorAssemblyAttribute.
CopyRazorGenerateFilesToPublishDirectory När du true kopierar RazorGenerate objektfiler (.cshtml) till publiceringskatalogen. En publicerad app kräver normalt inte Razor filer om de deltar i kompileringen vid byggtillfälle eller publicering. Standardinställningen är false.
PreserveCompilationReferences När truekopierar du referenssammansättningsobjekt till publiceringskatalogen. Normalt krävs inte referenssammansättningar för en publicerad app om Razor kompilering sker vid byggtid eller publiceringstid. Ställ in till true om den publicerade appen kräver körningskompilering. Ange till exempel värdet till true om appen ändrar .cshtml filer vid körning eller använder inbäddade vyer. Standardinställningen är false.
IncludeRazorContentInPack När truemarkeras alla Razor innehållsobjekt (.cshtml filer) för inkludering i det genererade NuGet-paketet. Standardinställningen är false.
EmbedRazorGenerateSources När truelägger du till RazorGenerate-objekt (.cshtml) som inbäddade filer i den genererade Razor sammansättningen. Standardinställningen är false.
UseRazorBuildServer När true, använder en beständig byggserverprocess för att avlasta kodgenereringsarbete. Standardinställningen är värdet för UseSharedCompilation.
GenerateMvcApplicationPartsAssemblyAttributes När truegenererar SDK ytterligare attribut som används av MVC vid körning för att utföra programdelsidentifiering.
DefaultWebContentItemExcludes Ett mönster för globbing för objektelement som ska undantas från Content objektgruppen i projekt som är avsedda för webben eller Razor SDK
ExcludeConfigFilesFromBuildOutput När true, .config och .json filer inte kopieras till utdatakatalogen för bygget.
AddRazorSupportForMvc När true konfigurerar du Razor SDK:t för att lägga till stöd för den nödvändiga MVC-konfigurationen när du bygger program som innehåller MVC-vyer eller Razor-sidor. Den här egenskapen anges implicit för .NET Core 3.0- eller senare projekt som riktar sig till Webb-SDK
RazorLangVersion Versionen av Razor-språket som ska riktas.

Mer information om egenskaper finns i MSBuild-egenskaper.

Mål

Razor SDK definierar två primära mål:

  • RazorGenerate: Kod genererar .cs filer från RazorGenerate objektelement. Använd egenskapen RazorGenerateDependsOn för att ange ytterligare mål som kan köras före eller efter det här målet.
  • RazorCompile: Kompilerar genererade .cs filer i till en Razor sammansättning. RazorCompileDependsOn Använd för att ange ytterligare mål som kan köras före eller efter det här målet.
  • RazorComponentGenerate: Koden genererar .cs filer för RazorComponent objektelement. Använd egenskapen RazorComponentGenerateDependsOn för att ange ytterligare mål som kan köras före eller efter det här målet.

Körningskompilering av Razor vyer

  • SDK publicerar som standard Razor inte referenssammansättningar som krävs för att genomföra körningskompilering. Detta resulterar i kompileringsfel när programmodellen förlitar sig på körningskompilering, till exempel använder appen inbäddade vyer eller ändrar vyer när appen har publicerats. Ställ in CopyRefAssembliesToPublishDirectory till true för att fortsätta publicera referenssammansättningar.

  • För en webbapp kontrollerar du att din app riktar in sig på SDK:t Microsoft.NET.Sdk.Web .

Razor språkversion

När du riktar in dig på Microsoft.NET.Sdk.Web SDK:et Razor härleds språkversionen från appens målramverksversion. För projekt som riktar sig till Microsoft.NET.Sdk.Razor SDK eller i sällsynta fall att appen kräver en annan Razor språkversion än det här angivna värdet kan en version konfigureras genom att ange <RazorLangVersion> egenskapen i appens projektfil:

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

Razor:s språkversion är nära integrerad med den version av körmiljön som den skapades för. Det går inte att använda en språkversion som inte är avsedd för körmiljön och som sannolikt ger upphov till byggfel.

Ytterligare resurser

  • Standardiserar upplevelsen av att skapa, paketera och publicera projekt som innehåller Razor filer för ASP.NET Core MVC-baserade projekt.
  • Innehåller en uppsättning fördefinierade mål, egenskaper och objekt som gör det möjligt att anpassa kompileringen av Razor filer.

Razor SDK:et innehåller ett Content objekt med ett Include attribut inställt på **\*.cshtml globbningsmönstret. Matchande filer publiceras.

Förutsättningar

.NET Core 2.1 eller senare SDK

Använd Razor SDK

De flesta webbappar behöver inte uttryckligen hänvisa till SDK:t Razor.

Så här använder Razor du SDK:t för att skapa klassbibliotek som innehåller Razor vyer eller Razor sidor:

  • Använd Microsoft.NET.Sdk.Razor i stället för Microsoft.NET.Sdk:

    <Project SDK="Microsoft.NET.Sdk.Razor">
  <!-- omitted for brevity -->
</Project>

  • Vanligtvis krävs en paketreferens till Microsoft.AspNetCore.Mvc för att ta emot ytterligare beroenden som krävs för att skapa och kompilera Razor sidor och Razor vyer. Projektet bör åtminstone lägga till paketreferenser till:

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

    Paketet Microsoft.AspNetCore.Razor.Design innehåller kompileringsuppgifterna Razor och målen för projektet.

    De föregående paketen ingår i Microsoft.AspNetCore.Mvc. Följande markering visar en projektfil som använder Razor SDK:t för att skapa Razor filer för en 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>

Varning

Paketen Microsoft.AspNetCore.Razor.Design och Microsoft.AspNetCore.Mvc.Razor.Extensions ingår i Microsoft.AspNetCore.App metapackage. Paketreferensen utan version Microsoft.AspNetCore.App tillhandahåller dock ett metapaket till appen som inte innehåller den senaste versionen av Microsoft.AspNetCore.Razor.Design. Projekten måste referera till en konsekvent version av Microsoft.AspNetCore.Razor.Design (eller Microsoft.AspNetCore.Mvc) så att de senaste korrigeringarna för byggtiden av Razor ingår. Mer information finns i det här GitHub-problemet.

Egenskaper

Följande egenskaper styr RazorSDK-beteendet som en del av en projektversion:

  • RazorCompileOnBuild: När true kompilerar och genererar Razor sammansättningen som en del av projektets byggprocess. Standardinställningen är true.
  • RazorCompileOnPublish: När truekompilerar och genererar Razor sammansättningen som en del av publiceringen av projektet. Standardinställningen är true.

Egenskaperna och objekten i följande tabell används för att konfigurera indata och utdata till SDK:t Razor .

Föremål Beskrivning
RazorGenerate Objektelement (.cshtml filer) som är indata för kodgenerering.
RazorComponent Objektelement (.razor filer) som är indata för Razor komponentkodgenerering.
RazorCompile Objektelement (.cs filer) som är indata till Razor kompileringsmål. Använd det här ItemGroup alternativet om du vill ange ytterligare filer som ska kompileras till Razor sammansättningen.
RazorTargetAssemblyAttribute Objektelement som används för att koda genererar attribut för Razor sammansättningen. Till exempel:
RazorAssemblyAttribute
Include="System.Reflection.AssemblyMetadataAttribute"
_Parameter1="BuildSource" _Parameter2="https://learn.microsoft.com/">
RazorEmbeddedResource Objektelement har lagts till som inbäddade resurser i den genererade Razor sammansättningen.
Fastighet Beskrivning
RazorTargetName Filnamn (utan tillägg) för sammansättningen som skapas av Razor.
RazorOutputPath Utdatakatalogen Razor.
RazorCompileToolset Används för att fastställa den verktygsuppsättning som används för att skapa Razor sammansättningen. Giltiga värden är Implicit, RazorSDKoch PrecompilationTool.
AktiveraStandardInnehållsObjekt Standard är true. När true, innehåller web.config, .json och .cshtml-filer som innehåll i projektet. När de refereras via Microsoft.NET.Sdk.Webinkluderas även filer under wwwroot - och konfigurationsfiler.
EnableDefaultRazorGenerateItems När true inkluderar .cshtml-filer från Content objekt i RazorGenerate objekt.
GenerateRazorTargetAssemblyInfo När truegenererar en .cs fil som innehåller attribut som anges av RazorAssemblyAttribute och innehåller filen i kompileringsutdata.
EnableDefaultRazorTargetAssemblyInfoAttributes När truelägger till en standarduppsättning sammansättningsattribut till RazorAssemblyAttribute.
CopyRazorGenerateFilesToPublishDirectory När du true kopierar RazorGenerate objektfiler (.cshtml) till publiceringskatalogen. En publicerad app kräver normalt inte Razor filer om de deltar i kompileringen vid byggtillfälle eller publicering. Standardinställningen är false.
CopyRefAssembliesToPublishDirectory När truekopierar du referenssammansättningsobjekt till publiceringskatalogen. Normalt krävs inte referenssammansättningar för en publicerad app om Razor kompilering sker vid byggtid eller publiceringstid. Ställ in till true om den publicerade appen kräver körningskompilering. Ange till exempel värdet till true om appen ändrar .cshtml filer vid körning eller använder inbäddade vyer. Standardinställningen är false.
IncludeRazorContentInPack När truemarkeras alla Razor innehållsobjekt (.cshtml filer) för inkludering i det genererade NuGet-paketet. Standardinställningen är false.
EmbedRazorGenerateSources När truelägger du till RazorGenerate-objekt (.cshtml) som inbäddade filer i den genererade Razor sammansättningen. Standardinställningen är false.
UseRazorBuildServer När true, använder en beständig byggserverprocess för att avlasta kodgenereringsarbete. Standardinställningen är värdet för UseSharedCompilation.
GenerateMvcApplicationPartsAssemblyAttributes När truegenererar SDK ytterligare attribut som används av MVC vid körning för att utföra programdelsidentifiering.
DefaultWebContentItemExcludes Ett mönster för globbing för objektelement som ska undantas från Content objektgruppen i projekt som är avsedda för webben eller Razor SDK
ExcludeConfigFilesFromBuildOutput När true, .config och .json filer inte kopieras till utdatakatalogen för bygget.
AddRazorSupportForMvc När true konfigurerar du Razor SDK:t för att lägga till stöd för den nödvändiga MVC-konfigurationen när du bygger program som innehåller MVC-vyer eller Razor-sidor. Den här egenskapen anges implicit för .NET Core 3.0- eller senare projekt som riktar sig till Webb-SDK
RazorLangVersion Versionen av Razor-språket som ska riktas.

Mer information om egenskaper finns i MSBuild-egenskaper.

Mål

Razor SDK definierar två primära mål:

  • RazorGenerate: Kod genererar .cs filer från RazorGenerate objektelement. Använd egenskapen RazorGenerateDependsOn för att ange ytterligare mål som kan köras före eller efter det här målet.
  • RazorCompile: Kompilerar genererade .cs filer i till en Razor sammansättning. RazorCompileDependsOn Använd för att ange ytterligare mål som kan köras före eller efter det här målet.
  • RazorComponentGenerate: Koden genererar .cs filer för RazorComponent objektelement. Använd egenskapen RazorComponentGenerateDependsOn för att ange ytterligare mål som kan köras före eller efter det här målet.

Körningskompilering av Razor vyer

  • SDK publicerar som standard Razor inte referenssammansättningar som krävs för att genomföra körningskompilering. Detta resulterar i kompileringsfel när programmodellen förlitar sig på körningskompilering, till exempel använder appen inbäddade vyer eller ändrar vyer när appen har publicerats. Ställ in CopyRefAssembliesToPublishDirectory till true för att fortsätta publicera referenssammansättningar.

  • För en webbapp kontrollerar du att din app riktar in sig på SDK:t Microsoft.NET.Sdk.Web .

Razor språkversion

När du riktar in dig på Microsoft.NET.Sdk.Web SDK:et Razor härleds språkversionen från appens målramverksversion. För projekt som riktar sig till Microsoft.NET.Sdk.Razor SDK eller i sällsynta fall att appen kräver en annan Razor språkversion än det här angivna värdet kan en version konfigureras genom att ange <RazorLangVersion> egenskapen i appens projektfil:

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

Razor:s språkversion är nära integrerad med den version av körmiljön som den skapades för. Det går inte att använda en språkversion som inte är avsedd för körmiljön och som sannolikt ger upphov till byggfel.

Ytterligare resurser