共用方式為

ASP.NET Core Razor SDK

  • 發行項

作者：Rick Anderson

概觀

.NET 6.0 SDK 包含 Microsoft.NET.Sdk.Razor MSBuild SDK (Razor SDK)。 Razor SDK：

  • 需要建置、封裝及發佈專案，該專案包含 ASP.NET Core MVC 型或 Blazor 專案的 Razor 檔案。
  • 包含一組預先定義的屬性和項目，可讓您自訂 Razor (.cshtml 或 .razor) 檔案的編譯作業。

Razor SDK 包含 Content 項目，其 Include 屬性設定為 **\*.cshtml 和 **\*.razor 萬用字元模式。 相符的檔案已發佈。

必要條件

.NET 6.0 SDK

使用 Razor SDK

大部分的 Web 應用程式都不需明確參考 Razor SDK。

若要使用 Razor SDK 建置包含 Razor 檢視或 Razor Pages 的類別庫，建議您從 Razor 類別庫 (RCL) 專案範本開始。 用來建置 Blazor (.razor) 檔案的 RCL 至少需參考 Microsoft.AspNetCore.Components 套件。 用來建置 Razor 檢視或頁面 (.cshtml 檔案) 的 RCL 至少需以 netcoreapp3.0 或更新版本為目標，並在專案檔中具有 Microsoft.AspNetCore.App 中繼套件 的 FrameworkReference。

屬性

下列屬性可在專案建置期間控制 Razor 的 SDK 行為：

  • RazorCompileOnBuild：如果是 true，則在建置專案期間編譯和發出 Razor 組件。 預設為 true。
  • RazorCompileOnPublish：如果是 true，則在發佈專案期間編譯和發出 Razor 組件。 預設為 true。
  • UseRazorSourceGenerator 預設為 true。 時間：true
    • 使用來源產生作業進行編譯。
    • 不會建立 <app_name>.Views.dll。 檢視包含在 <app_name>.dll 中。
    • 支援 .NET 熱重新載入。

下表中的屬性和項目可用來設定 Razor SDK 的輸入和輸出。

項目 描述
RazorGenerate 為程式碼產生輸入的項目元素 (.cshtml 檔案)。
RazorComponent 為 Razor 元件程式碼產生輸入的項目元素 (.razor 檔案)。
RazorCompile 為 Razor 編譯目標輸入的項目元素 (.cs 檔案)。 請使用此 ItemGroup 來指定要編譯成 Razor 組件的其他檔案。
RazorEmbeddedResource 新增為所產生 Razor 組件之內嵌資源的項目元素。
屬性 說明
RazorOutputPath Razor 輸出目錄。
RazorCompileToolset 用來判斷可用來建置 Razor 組件的工具組。 有效值為 Implicit、RazorSDK 及 PrecompilationTool。
EnableDefaultContentItems 預設值為 true。 如果是 true，則將 web.config、.json 和 .cshtml 檔案納入專案中的內容。 透過 Microsoft.NET.Sdk.Web 參考時，也包含 wwwroot 下的檔案和組態檔。
EnableDefaultRazorGenerateItems 如果是 true，則包含來自 RazorGenerate 項目中 Content 項目的 .cshtml 檔案。
GenerateRazorTargetAssemblyInfo 不適用於 .NET 6 和更新版本。
EnableDefaultRazorTargetAssemblyInfoAttributes 不適用於 .NET 6 和更新版本。
CopyRazorGenerateFilesToPublishDirectory 如果是 true，則將 RazorGenerate 項目 (.cshtml) 檔案複製到發佈目錄。 如果已發佈的應用程式在建置階段或發佈階段參與編譯，通常不需要 Razor 檔案。 預設為 false。
PreserveCompilationReferences 如果是 true，請將參考組件項目複製到發行目錄。 如果在建置階段或發佈階段進行 Razor 編譯，已發佈的應用程式通常不需要參考組件。 如果已發佈的應用程式需要進行執行階段編譯，請設定為 true。 例如，如果應用程式在執行階段修改 .cshtml 檔案或使用內嵌檢視，請將 值設定為 true。 預設為 false。
IncludeRazorContentInPack 如果是 true，所有 Razor 內容項目 (.cshtml 檔案) 會標示為要包含在產生的 NuGet 套件中。 預設為 false。
EmbedRazorGenerateSources 如果是 true，則將 RazorGenerate (.cshtml) 項目當作內嵌檔案新增至產生的 Razor 組件。 預設為 false。
GenerateMvcApplicationPartsAssemblyAttributes 不適用於 .NET 6 和更新版本。
DefaultWebContentItemExcludes 在以 Web 或 Razor SDK 為目標的專案中，Content 項目群組的待排除項目元素萬用字元模式
ExcludeConfigFilesFromBuildOutput 如果是 true，.config 和 .json 檔案不會複製到建置輸出目錄。
AddRazorSupportForMvc 如果是 true，則設定 Razor SDK 以新增對 MVC 組態的支援；此為建置包含 MVC 檢視或 Razor Pages 的應用程式時所需的支援項目。 此屬性會針對以 Web SDK 為目標的 .NET Core 3.0 或更新版本的專案隱含設定
RazorLangVersion 要設為目標的 Razor 語言版本。
EmitCompilerGeneratedFiles 如果設定為 true，產生的來源檔案會寫入磁碟。 對編譯器進行偵錯時，設定為 true 很有用。 預設值為 false。

如需有關屬性的詳細資訊，請參閱 MSBuild 屬性。

Razor 檢視的執行階段編譯

  • 根據預設，Razor SDK 不會發佈執行執行階段編譯所需的參考組件。 當應用程式模型依賴執行階段編譯時，會導致編譯失敗；例如，發佈應用程式之後，應用程式使用內嵌的檢視或變更檢視。 將 CopyRefAssembliesToPublishDirectory 設為 true 以繼續發佈參考組件。 對編譯器的單一呼叫支援程式碼產生和編譯作業。 會產生單一組件，其中包含應用程式類型和產生的檢視。

  • 若為 Web 應用程式，請確定您的應用程式是以 Microsoft.NET.Sdk.Web SDK 為目標。

Razor 語言版本

以 Microsoft.NET.Sdk.Web SDK 為目標時，Razor 語言版本會從應用程式的目標框架版本推斷。 針對以 Microsoft.NET.Sdk.Razor SDK 為目標的專案，或在應用程式需要與推斷值不同 Razor 語言版本的少數情況下，可以透過在應用程式專案檔中設定 <RazorLangVersion> 屬性來設定版本：

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

Razor 的語言版本與為其建置的執行階段版本緊密整合。 不支援以非針對執行階段設計的語言版本為目標，且可能產生建置錯誤。

其他資源

.NET Core 2.1 SDK 或更新版本包含 Microsoft.NET.Sdk.RazorMSBuild SDK (Razor SDK)。 Razor SDK：

  • 需要建置、封裝及發佈專案，該專案包含 ASP.NET Core MVC 架構或 Blazor 專案的 Razor 檔案。
  • 包含一組預先定義的目標、屬性和項目，可讓您自訂 Razor (.cshtml 或 .razor) 檔案的編譯作業。

Razor SDK 包含 Content 項目，其 Include 屬性設定為 **\*.cshtml 和 **\*.razor 萬用字元模式。 相符的檔案已發佈。

必要條件

.NET Core 2.1 SDK 或更新版本

使用 Razor SDK

大部分的 Web 應用程式都不需明確參考 Razor SDK。

若要使用 Razor SDK 建置包含 Razor 檢視或 Razor Pages 的類別庫，建議您從 Razor 類別庫 (RCL) 專案範本開始。 用來建置 Blazor (.razor) 檔案的 RCL 至少需參考 Microsoft.AspNetCore.Components 套件。 用來建置 Razor 檢視或頁面 (.cshtml 檔案) 的 RCL 至少需以 netcoreapp3.0 或更新版本為目標，並在專案檔中具有 Microsoft.AspNetCore.App 中繼套件 的 FrameworkReference。

屬性

下列屬性可在專案建置期間控制 Razor 的 SDK 行為：

  • RazorCompileOnBuild：如果是 true，則在建置專案期間編譯和發出 Razor 組件。 預設為 true。
  • RazorCompileOnPublish：如果是 true，則在發佈專案期間編譯和發出 Razor 組件。 預設為 true。

下表中的屬性和項目可用來設定 Razor SDK 的輸入和輸出。

警告

從 ASP.NET Core 3.0 開始，如果專案檔中的 RazorCompileOnBuild 或 RazorCompileOnPublish MSBuild 屬性已停用，則預設不會提供 MVC 檢視或 Razor Pages。 如果應用程式依賴執行階段編譯來處理 .cshtml 文件，則應用程式必須新增對 Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation 套件的明確參考。

項目 描述
RazorGenerate 為程式碼產生輸入的項目元素 (.cshtml 檔案)。
RazorComponent 為 Razor 元件程式碼產生輸入的項目元素 (.razor 檔案)。
RazorCompile 為 Razor 編譯目標輸入的項目元素 (.cs 檔案)。 請使用此 ItemGroup 來指定要編譯成 Razor 組件的其他檔案。
RazorTargetAssemblyAttribute 用於 Razor 組件的程式碼產生屬性的項目元素。 例如：
RazorAssemblyAttribute
Include="System.Reflection.AssemblyMetadataAttribute"
_Parameter1="BuildSource" _Parameter2="https://learn.microsoft.com/">
RazorEmbeddedResource 新增為所產生 Razor 組件之內嵌資源的項目元素。
屬性 說明
RazorTargetName Razor 所產生組件的檔案名稱 (不含副檔名)。
RazorOutputPath Razor 輸出目錄。
RazorCompileToolset 用來判斷可用來建置 Razor 組件的工具組。 有效值為 Implicit、RazorSDK 及 PrecompilationTool。
EnableDefaultContentItems 預設值為 true。 如果是 true，則將 web.config、.json 和 .cshtml 檔案納入專案中的內容。 透過 Microsoft.NET.Sdk.Web 參考時，也包含 wwwroot 下的檔案和組態檔。
EnableDefaultRazorGenerateItems 如果是 true，則包含來自 RazorGenerate 項目中 Content 項目的 .cshtml 檔案。
GenerateRazorTargetAssemblyInfo 如果是 true，則產生包含 RazorAssemblyAttribute 所指定屬性的 .cs 檔案，並將其包含在編譯輸出中。
EnableDefaultRazorTargetAssemblyInfoAttributes 如果是 true，請將一組預設的組件屬性新增至 RazorAssemblyAttribute。
CopyRazorGenerateFilesToPublishDirectory 如果是 true，則將 RazorGenerate 項目 (.cshtml) 檔案複製到發佈目錄。 如果已發佈的應用程式在建置階段或發佈階段參與編譯，通常不需要 Razor 檔案。 預設為 false。
PreserveCompilationReferences 如果是 true，請將參考組件項目複製到發行目錄。 如果在建置階段或發佈階段進行 Razor 編譯，已發佈的應用程式通常不需要參考組件。 如果已發佈的應用程式需要進行執行階段編譯，請設定為 true。 例如，如果應用程式在執行階段修改 .cshtml 檔案或使用內嵌檢視，請將 值設定為 true。 預設為 false。
IncludeRazorContentInPack 如果是 true，所有 Razor 內容項目 (.cshtml 檔案) 會標示為要包含在產生的 NuGet 套件中。 預設為 false。
EmbedRazorGenerateSources 如果是 true，則將 RazorGenerate (.cshtml) 項目當作內嵌檔案新增至產生的 Razor 組件。 預設為 false。
UseRazorBuildServer 如果是 true，請使用持續性組建伺服器處理序來卸載程式碼產生工作。 預設值為 UseSharedCompilation。
GenerateMvcApplicationPartsAssemblyAttributes 如果是 true，SDK 會在執行階段產生 MVC 使用的其他屬性以執行應用程式組件探索。
DefaultWebContentItemExcludes 在以 Web 或 Razor SDK 為目標的專案中，Content 項目群組的待排除項目元素萬用字元模式
ExcludeConfigFilesFromBuildOutput 如果是 true，.config 和 .json 檔案不會複製到建置輸出目錄。
AddRazorSupportForMvc 如果是 true，則設定 Razor SDK 以新增對 MVC 組態的支援；此為建置包含 MVC 檢視或 Razor Pages 的應用程式時所需的支援項目。 此屬性會針對以 Web SDK 為目標的 .NET Core 3.0 或更新版本的專案隱含設定
RazorLangVersion 要設為目標的 Razor 語言版本。

如需有關屬性的詳細資訊，請參閱 MSBuild 屬性。

目標

Razor SDK 會定義兩個主要目標：

  • RazorGenerate：程式碼會從 RazorGenerate 項目元素產生 .cs 檔案。 請使用 RazorGenerateDependsOn 屬性來指定可在此目標之前或之後執行的其他目標。
  • RazorCompile：將產生的 .cs 檔案編譯到 Razor 組件中。 請使用 RazorCompileDependsOn 來指定可在此目標之前或之後執行的其他目標。
  • RazorComponentGenerate：程式碼會產生 RazorComponent 項目元素的 .cs 檔案。 請使用 RazorComponentGenerateDependsOn 屬性來指定可在此目標之前或之後執行的其他目標。

Razor 檢視的執行階段編譯

  • 根據預設，Razor SDK 不會發佈執行執行階段編譯所需的參考組件。 當應用程式模型依賴執行階段編譯時，會導致編譯失敗；例如，發佈應用程式之後，應用程式使用內嵌的檢視或變更檢視。 將 CopyRefAssembliesToPublishDirectory 設為 true 以繼續發佈參考組件。

  • 若為 Web 應用程式，請確定您的應用程式是以 Microsoft.NET.Sdk.Web SDK 為目標。

Razor 語言版本

以 Microsoft.NET.Sdk.Web SDK 為目標時，Razor 語言版本會從應用程式的目標框架版本推斷。 針對以 Microsoft.NET.Sdk.Razor SDK 為目標的專案，或在應用程式需要與推斷值不同 Razor 語言版本的少數情況下，可以透過在應用程式專案檔中設定 <RazorLangVersion> 屬性來設定版本：

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

Razor 的語言版本與為其建置的執行階段版本緊密整合。 不支援以非針對執行階段設計的語言版本為目標，且可能產生建置錯誤。

其他資源

  • 標準化關於建置、封裝和發佈專案 (包含 ASP.NET Core MVC 架構專案的 Razor 檔案) 的體驗。
  • 包含一組預先定義的目標、屬性和項目，可讓您自訂 Razor 檔案的編譯作業。

Razor SDK 包含 Include 屬性設為 **\*.cshtml 萬用字元模式的 Content 項目。 相符的檔案已發佈。

必要條件

.NET Core 2.1 SDK 或更新版本

使用 Razor SDK

大部分的 Web 應用程式都不需明確參考 Razor SDK。

若要使用 Razor SDK 來建置包含 Razor 檢視或 Razor Pages 的類別庫：

  • 使用 Microsoft.NET.Sdk.Razor 來取代 Microsoft.NET.Sdk：

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

  • 通常需要有 Microsoft.AspNetCore.Mvc 的套件參考，才能接收建置和編譯 Razor Pages 與 Razor 檢視所需的其他相依性。 您的專案至少應將套件參考新增至：

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

    Microsoft.AspNetCore.Razor.Design 套件提供專案的 Razor 編譯工作和目標。

    Microsoft.AspNetCore.Mvc 中包含上述套件。 下列標記會顯示專案檔，該檔案使用 Razor SDK 來建置 ASP.NET Core Razor Pages 應用程式的 Razor 檔案：

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

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

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

</Project>

警告

Microsoft.AspNetCore.Razor.Design 和 Microsoft.AspNetCore.Mvc.Razor.Extensions 套件均包含在 Microsoft.AspNetCore.App 中繼套件中。 不過，無版本的 Microsoft.AspNetCore.App 套件參考為不含 Microsoft.AspNetCore.Razor.Design 最新版本的應用程式提供中繼套件。 專案必須參考版本一致的 Microsoft.AspNetCore.Razor.Design (或 Microsoft.AspNetCore.Mvc)，才會包含 Razor 的最新建置時間修正。 如需詳細資訊，請參閱這個 GitHub 問題。

屬性

下列屬性可在專案建置期間控制 Razor 的 SDK 行為：

  • RazorCompileOnBuild：如果是 true，則在建置專案期間編譯和發出 Razor 組件。 預設為 true。
  • RazorCompileOnPublish：如果是 true，則在發佈專案期間編譯和發出 Razor 組件。 預設為 true。

下表中的屬性和項目可用來設定 Razor SDK 的輸入和輸出。

項目 描述
RazorGenerate 為程式碼產生輸入的項目元素 (.cshtml 檔案)。
RazorComponent 為 Razor 元件程式碼產生輸入的項目元素 (.razor 檔案)。
RazorCompile 為 Razor 編譯目標輸入的項目元素 (.cs 檔案)。 請使用此 ItemGroup 來指定要編譯成 Razor 組件的其他檔案。
RazorTargetAssemblyAttribute 用於 Razor 組件的程式碼產生屬性的項目元素。 例如：
RazorAssemblyAttribute
Include="System.Reflection.AssemblyMetadataAttribute"
_Parameter1="BuildSource" _Parameter2="https://learn.microsoft.com/">
RazorEmbeddedResource 新增為所產生 Razor 組件之內嵌資源的項目元素。
屬性 說明
RazorTargetName Razor 所產生組件的檔案名稱 (不含副檔名)。
RazorOutputPath Razor 輸出目錄。
RazorCompileToolset 用來判斷可用來建置 Razor 組件的工具組。 有效值為 Implicit、RazorSDK 及 PrecompilationTool。
EnableDefaultContentItems 預設值為 true。 如果是 true，則將 web.config、.json 和 .cshtml 檔案納入專案中的內容。 透過 Microsoft.NET.Sdk.Web 參考時，也包含 wwwroot 下的檔案和組態檔。
EnableDefaultRazorGenerateItems 如果是 true，則包含來自 RazorGenerate 項目中 Content 項目的 .cshtml 檔案。
GenerateRazorTargetAssemblyInfo 如果是 true，則產生包含 RazorAssemblyAttribute 所指定屬性的 .cs 檔案，並將其包含在編譯輸出中。
EnableDefaultRazorTargetAssemblyInfoAttributes 如果是 true，請將一組預設的組件屬性新增至 RazorAssemblyAttribute。
CopyRazorGenerateFilesToPublishDirectory 如果是 true，則將 RazorGenerate 項目 (.cshtml) 檔案複製到發佈目錄。 如果已發佈的應用程式在建置階段或發佈階段參與編譯，通常不需要 Razor 檔案。 預設為 false。
CopyRefAssembliesToPublishDirectory 如果是 true，請將參考組件項目複製到發行目錄。 如果在建置階段或發佈階段進行 Razor 編譯，已發佈的應用程式通常不需要參考組件。 如果已發佈的應用程式需要進行執行階段編譯，請設定為 true。 例如，如果應用程式在執行階段修改 .cshtml 檔案或使用內嵌檢視，請將 值設定為 true。 預設為 false。
IncludeRazorContentInPack 如果是 true，所有 Razor 內容項目 (.cshtml 檔案) 會標示為要包含在產生的 NuGet 套件中。 預設為 false。
EmbedRazorGenerateSources 如果是 true，則將 RazorGenerate (.cshtml) 項目當作內嵌檔案新增至產生的 Razor 組件。 預設為 false。
UseRazorBuildServer 如果是 true，請使用持續性組建伺服器處理序來卸載程式碼產生工作。 預設值為 UseSharedCompilation。
GenerateMvcApplicationPartsAssemblyAttributes 如果是 true，SDK 會在執行階段產生 MVC 使用的其他屬性以執行應用程式組件探索。
DefaultWebContentItemExcludes 在以 Web 或 Razor SDK 為目標的專案中，Content 項目群組的待排除項目元素萬用字元模式
ExcludeConfigFilesFromBuildOutput 如果是 true，.config 和 .json 檔案不會複製到建置輸出目錄。
AddRazorSupportForMvc 如果是 true，則設定 Razor SDK 以新增對 MVC 組態的支援；此為建置包含 MVC 檢視或 Razor Pages 的應用程式時所需的支援項目。 此屬性會針對以 Web SDK 為目標的 .NET Core 3.0 或更新版本的專案隱含設定
RazorLangVersion 要設為目標的 Razor 語言版本。

如需有關屬性的詳細資訊，請參閱 MSBuild 屬性。

目標

Razor SDK 會定義兩個主要目標：

  • RazorGenerate：程式碼會從 RazorGenerate 項目元素產生 .cs 檔案。 請使用 RazorGenerateDependsOn 屬性來指定可在此目標之前或之後執行的其他目標。
  • RazorCompile：將產生的 .cs 檔案編譯到 Razor 組件中。 請使用 RazorCompileDependsOn 來指定可在此目標之前或之後執行的其他目標。
  • RazorComponentGenerate：程式碼會產生 RazorComponent 項目元素的 .cs 檔案。 請使用 RazorComponentGenerateDependsOn 屬性來指定可在此目標之前或之後執行的其他目標。

Razor 檢視的執行階段編譯

  • 根據預設，Razor SDK 不會發佈執行執行階段編譯所需的參考組件。 當應用程式模型依賴執行階段編譯時，會導致編譯失敗；例如，發佈應用程式之後，應用程式使用內嵌的檢視或變更檢視。 將 CopyRefAssembliesToPublishDirectory 設為 true 以繼續發佈參考組件。

  • 若為 Web 應用程式，請確定您的應用程式是以 Microsoft.NET.Sdk.Web SDK 為目標。

Razor 語言版本

以 Microsoft.NET.Sdk.Web SDK 為目標時，Razor 語言版本會從應用程式的目標框架版本推斷。 針對以 Microsoft.NET.Sdk.Razor SDK 為目標的專案，或在應用程式需要與推斷值不同 Razor 語言版本的少數情況下，可以透過在應用程式專案檔中設定 <RazorLangVersion> 屬性來設定版本：

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

Razor 的語言版本與為其建置的執行階段版本緊密整合。 不支援以非針對執行階段設計的語言版本為目標，且可能產生建置錯誤。

其他資源