ASP.NET Core Razor SDK

2025-05-28

作者：Rick Anderson

概觀

.NET 6 SDK 包含 Microsoft.NET.Sdk.Razor MSBuild SDK （RazorSDK）。 Razor SDK：

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

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

必要條件

.NET 6 SDK

使用 Razor SDK

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

若要使用 Razor SDK 建置包含 Razor 檢視或 Razor Pages 的類別庫，建議您從 Razor 類別庫 (RCL) 專案範本開始。用來建置 Blazor (.razor) 檔案的 RCL 至少需參考 Microsoft.AspNetCore.Components 套件。用來建置 Razor 檢視或頁面 (.cshtml 檔案) 的 RCL 至少需以 netcoreapp3.0 或更新版本為目標，並在專案檔中具有 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`	為 `.cs` 編譯目標輸入的項目元素 (Razor 檔案)。請使用此 `ItemGroup` 來指定要編譯成 Razor 組件的其他檔案。
`RazorEmbeddedResource`	新增為所產生 Razor 組件之內嵌資源的項目元素。

屬性	描述
`RazorOutputPath`	Razor 輸出目錄。
`RazorCompileToolset`	用來判斷可用來建置 Razor 組件的工具組。有效值為 `Implicit`、`RazorSDK` 及 `PrecompilationTool`。
啟用預設內容項目	預設值為 `true`。如果是 `true`，則將 web.config、`.json` 和 `.cshtml` 檔案納入專案中的內容。透過 `Microsoft.NET.Sdk.Web` 參考時，也包含 wwwroot 下的檔案和組態檔。
`EnableDefaultRazorGenerateItems`	如果是 `true`，則包含來自 `.cshtml` 項目中 `Content` 項目的 `RazorGenerate` 檔案。
`GenerateRazorTargetAssemblyInfo`	不適用於 .NET 6 或更新版本。
`EnableDefaultRazorTargetAssemblyInfoAttributes`	不適用於 .NET 6 或更新版本。
`CopyRazorGenerateFilesToPublishDirectory`	如果是 `true`，則將 `RazorGenerate` 項目 (`.cshtml`) 檔案複製到發佈目錄。如果已發佈的應用程式在建置階段或發佈階段參與編譯，通常不需要 Razor 檔案。預設為 `false`。
`PreserveCompilationReferences`	如果是 `true`，請將參考組件項目複製到發行目錄。如果在建置階段或發佈階段進行 Razor 編譯，已發佈的應用程式通常不需要參考組件。如果已發佈的應用程式需要進行執行階段編譯，請設定為 `true`。例如，如果應用程式在執行階段修改 `true` 檔案或使用內嵌檢視，請將值設定為 `.cshtml`。預設為 `false`。
`IncludeRazorContentInPack`	如果是 `true`，所有 Razor 內容項目 (`.cshtml` 檔案) 會標示為要包含在產生的 NuGet 套件中。預設為 `false`。
`EmbedRazorGenerateSources`	如果是 `true`，則將 RazorGenerate (`.cshtml`) 項目當作內嵌檔案新增至產生的 Razor 組件。預設為 `false`。
`GenerateMvcApplicationPartsAssemblyAttributes`	不適用於 .NET 6 或更新版本。
`DefaultWebContentItemExcludes`	在以 Web 或 `Content` SDK 為目標的專案中，Razor 項目群組的待排除項目元素萬用字元模式
`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.Razor MSBuild SDK （RazorSDK）。 Razor SDK：

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

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

必要條件

.NET Core 2.1 或更新版本的 SDK

使用 Razor SDK

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

屬性

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

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

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

警告

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

項目	描述
`RazorGenerate`	為程式碼產生輸入的項目元素 (`.cshtml` 檔案)。
`RazorComponent`	為 `.razor` 元件程式碼產生輸入的項目元素 (Razor 檔案)。
`RazorCompile`	為 `.cs` 編譯目標輸入的項目元素 (Razor 檔案)。請使用此 `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`。
啟用預設內容項目	預設值為 `true`。如果是 `true`，則將 web.config、`.json` 和 `.cshtml` 檔案納入專案中的內容。透過 `Microsoft.NET.Sdk.Web` 參考時，也包含 wwwroot 下的檔案和組態檔。
`EnableDefaultRazorGenerateItems`	如果是 `true`，則包含來自 `.cshtml` 項目中 `Content` 項目的 `RazorGenerate` 檔案。
`GenerateRazorTargetAssemblyInfo`	如果是 `true`，則產生包含 `.cs` 所指定屬性的 `RazorAssemblyAttribute` 檔案，並將其包含在編譯輸出中。
`EnableDefaultRazorTargetAssemblyInfoAttributes`	如果是 `true`，請將一組預設的組件屬性新增至 `RazorAssemblyAttribute`。
`CopyRazorGenerateFilesToPublishDirectory`	如果是 `true`，則將 `RazorGenerate` 項目 (`.cshtml`) 檔案複製到發佈目錄。如果已發佈的應用程式在建置階段或發佈階段參與編譯，通常不需要 Razor 檔案。預設為 `false`。
`PreserveCompilationReferences`	如果是 `true`，請將參考組件項目複製到發行目錄。如果在建置階段或發佈階段進行 Razor 編譯，已發佈的應用程式通常不需要參考組件。如果已發佈的應用程式需要進行執行階段編譯，請設定為 `true`。例如，如果應用程式在執行階段修改 `true` 檔案或使用內嵌檢視，請將值設定為 `.cshtml`。預設為 `false`。
`IncludeRazorContentInPack`	如果是 `true`，所有 Razor 內容項目 (`.cshtml` 檔案) 會標示為要包含在產生的 NuGet 套件中。預設為 `false`。
`EmbedRazorGenerateSources`	如果是 `true`，則將 RazorGenerate (`.cshtml`) 項目當作內嵌檔案新增至產生的 Razor 組件。預設為 `false`。
`UseRazorBuildServer`	如果是 `true`，請使用持續性組建伺服器處理序來卸載程式碼產生工作。預設值為 `UseSharedCompilation`。
`GenerateMvcApplicationPartsAssemblyAttributes`	如果是 `true`，SDK 會在執行階段產生 MVC 使用的其他屬性以執行應用程式組件探索。
`DefaultWebContentItemExcludes`	在以 Web 或 `Content` SDK 為目標的專案中，Razor 項目群組的待排除項目元素萬用字元模式
`ExcludeConfigFilesFromBuildOutput`	如果是 `true`，.config 和 `.json` 檔案不會複製到建置輸出目錄。
`AddRazorSupportForMvc`	如果是 `true`，則設定 Razor SDK 以新增對 MVC 組態的支援；此為建置包含 MVC 檢視或 Razor Pages 的應用程式時所需的支援項目。此屬性會針對以 Web SDK 為目標的 .NET Core 3.0 或更新版本的專案隱含設定
`RazorLangVersion`	要設為目標的 Razor 語言版本。

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

目標

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

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

Razor 檢視的執行階段編譯

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

Razor 語言版本

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

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

其他資源

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

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

必要條件

.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`	為 `.cs` 編譯目標輸入的項目元素 (Razor 檔案)。請使用此 `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`。
啟用預設內容項目	預設值為 `true`。如果是 `true`，則將 web.config、`.json` 和 `.cshtml` 檔案納入專案中的內容。透過 `Microsoft.NET.Sdk.Web` 參考時，也包含 wwwroot 下的檔案和組態檔。
`EnableDefaultRazorGenerateItems`	如果是 `true`，則包含來自 `.cshtml` 項目中 `Content` 項目的 `RazorGenerate` 檔案。
`GenerateRazorTargetAssemblyInfo`	如果是 `true`，則產生包含 `.cs` 所指定屬性的 `RazorAssemblyAttribute` 檔案，並將其包含在編譯輸出中。
`EnableDefaultRazorTargetAssemblyInfoAttributes`	如果是 `true`，請將一組預設的組件屬性新增至 `RazorAssemblyAttribute`。
`CopyRazorGenerateFilesToPublishDirectory`	如果是 `true`，則將 `RazorGenerate` 項目 (`.cshtml`) 檔案複製到發佈目錄。如果已發佈的應用程式在建置階段或發佈階段參與編譯，通常不需要 Razor 檔案。預設為 `false`。
`CopyRefAssembliesToPublishDirectory`	如果是 `true`，請將參考組件項目複製到發行目錄。如果在建置階段或發佈階段進行 Razor 編譯，已發佈的應用程式通常不需要參考組件。如果已發佈的應用程式需要進行執行階段編譯，請設定為 `true`。例如，如果應用程式在執行階段修改 `true` 檔案或使用內嵌檢視，請將值設定為 `.cshtml`。預設為 `false`。
`IncludeRazorContentInPack`	如果是 `true`，所有 Razor 內容項目 (`.cshtml` 檔案) 會標示為要包含在產生的 NuGet 套件中。預設為 `false`。
`EmbedRazorGenerateSources`	如果是 `true`，則將 RazorGenerate (`.cshtml`) 項目當作內嵌檔案新增至產生的 Razor 組件。預設為 `false`。
`UseRazorBuildServer`	如果是 `true`，請使用持續性組建伺服器處理序來卸載程式碼產生工作。預設值為 `UseSharedCompilation`。
`GenerateMvcApplicationPartsAssemblyAttributes`	如果是 `true`，SDK 會在執行階段產生 MVC 使用的其他屬性以執行應用程式組件探索。
`DefaultWebContentItemExcludes`	在以 Web 或 `Content` SDK 為目標的專案中，Razor 項目群組的待排除項目元素萬用字元模式
`ExcludeConfigFilesFromBuildOutput`	如果是 `true`，.config 和 `.json` 檔案不會複製到建置輸出目錄。
`AddRazorSupportForMvc`	如果是 `true`，則設定 Razor SDK 以新增對 MVC 組態的支援；此為建置包含 MVC 檢視或 Razor Pages 的應用程式時所需的支援項目。此屬性會針對以 Web SDK 為目標的 .NET Core 3.0 或更新版本的專案隱含設定
`RazorLangVersion`	要設為目標的 Razor 語言版本。

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

目標

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

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

Razor 檢視的執行階段編譯

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

Razor 語言版本

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

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

共用方式為

ASP.NET Core Razor SDK

概觀

必要條件

使用 Razor SDK

屬性

Razor 檢視的執行階段編譯

Razor 語言版本

其他資源

必要條件

使用 Razor SDK

屬性

目標

Razor 檢視的執行階段編譯

Razor 語言版本

其他資源

必要條件

使用 Razor SDK

屬性

目標

Razor 檢視的執行階段編譯

Razor 語言版本

其他資源

其他資源