共用方式為

控制程式碼產生的 C# 編譯器選項

  • 發行項

下列選項可控制編譯器的程式碼產生。 新的 MSBuild 語法會以「粗體」顯示。 較舊的 csc.exe 語法會以code style顯示。

  • DebugType / -debug：發出 (或不發出) 偵錯資訊。
  • 最佳化 / -optimize：啟用最佳化。
  • 決定性 / -deterministic：從相同的輸入來源產生位元組對等的輸出。
  • ProduceOnlyReferenceAssembly / -refonly：產生參考組件，而非完整組件做為主要輸出。

注意

如需為專案設定這些選項的詳細資訊，請參閱 [編譯器選項]。

DebugType

DebugType 選項可讓編譯器產生偵錯資訊，並將它放在一個或多個輸出檔案中。 預設會新增偵錯資訊。

<DebugType>pdbonly</DebugType>

對於從 C# 6.0 開始的所有編譯器版本，pdbonly 和 full 之間沒有任何差異。 選擇 pdbonly。 若要變更 .pdb 檔案的位置，請參閱 PdbFile。

下列是有效值：

值 意義
full 使用目前平台的預設格式，將偵錯資訊發出至 .pdb 檔案：
Windows：Windows 的 .pdb 檔案。
Linux/macOS：可攜式 PDB 檔案。
pdbonly 與 full 相同。 如需詳細資訊，請參閱下列注意事項。
portable 使用跨平台可攜式 PDB 格式，將偵錯資訊發出至 .pdb 檔案。
embedded 使用可攜式 PDB 格式將偵錯資訊發出至 .dll/.exe 本身 (不產生 .pdb 檔案)。

重要

下列資訊僅適用於 C# 6.0 之前的編譯器。 這個元素的值可以是 full 或 pdbonly。 完整引數 (您未指定 pdbonly 時，這就會生效) 允許將偵錯工具附加至執行中的程式。 指定 pdbonly 讓原始程式碼在偵錯工具中啟動程式時進行偵錯，但只有在將執行中的程式附加到偵錯工具時，才會顯示組譯工具。 若要建立偵錯組建，請使用此選項。 如果您使用 full，請注意會對 JIT 最佳化程式碼速度和大小造成某種程度的影響，以及對使用 full 的程式碼品質造成某種程度的影響。 建議使用 pdbonly 或不使用 PDB 來產生釋出程式碼。 pdbonly 與 full 之間的一項差異在於使用 full 時，編譯器會發出 DebuggableAttribute，以用來告知 JIT 編譯器有偵錯資訊可用。 因此，如果使用 DebuggableAttribute，則會在程式碼包含設定為 false 的 時收到錯誤。 如需如何設定應用程式偵錯效能的詳細資訊，請參閱使映像偵錯更容易。

最佳化

Optimize 選項啟用或停用由編譯器執行的最佳化，讓您的輸出檔案變得更小、更快且更有效率。 預設會針對發行版本組建設定啟用最佳化選項。 預設設為關閉偵錯和任何其他建置組態。

<Optimize>true</Optimize>

您可以在 Visual Studio 中從專案的 [建置] 屬性頁面設定 Optimize 選項。

Optimize 也會告知通用語言執行平台在執行階段進行程式碼最佳化。 根據預設，會停用最佳化。 指定 Optimize+ 以啟用最佳化。 建置組件要使用的模組時，使用組件所用的相同 Optimize 設定。 它可以合併 Optimize 和 Debug 選項。

具決定性

可讓編譯器產生相同輸入之編譯間的逐一位元組輸出相同的組件。

<Deterministic>true</Deterministic>

根據預設，一組指定輸入的編譯器輸出是唯一的，因為編譯器會新增時間戳記以及從隨機數字產生的 MVID (一個 Module.ModuleVersionId。基本上，是可唯一識別模組和版本的 GUID。) 您可以使用 <Deterministic> 選項來產生「確定性組件」，這是只要輸入維持不變，其二進位內容在編譯之間就相同的組件。 在這類建置中，時間戳記和 MVID 欄位中的值將被從所有編譯輸入雜湊得出的值所取代。 編譯器會考量下列影響決定性的輸入：

  • 命令列參數序列。
  • 編譯器之 .rsp 回應檔的內容。
  • 使用的編譯器精確版本和其參考的組件。
  • 目前的目錄路徑。
  • 以直接或間接方式明確地傳遞給編譯器之所有檔案的二進位內容，包含：
    • 原始程式檔
    • 參考的組件
    • 參考的模組
    • 資源
    • 強式名稱金鑰檔
    • @ 回應檔
    • 分析器
    • 規則集
    • Source Link 從存放庫擷取的數據（例如 git 認可 SHA、存放庫 URL 等）
    • 分析器可能使用的其他檔案
  • 目前語言環境（用於產生診斷和例外訊息）。
  • 如果未指定編碼，則為預設編碼 (或目前字碼頁)。
  • 編譯器搜尋路徑（例如，透過 -lib 或 -recurse 指定）上的檔案存在與否及其內容。
  • Common Language Runtime (CLR) 執行編譯器的平台。
  • %LIBPATH% 的值，可能會影響分析器相依性載入。

決定性編譯可以用於驗證二進位檔案是否是從信任的來源編譯而成。 來源可供公開使用時，決定性輸出可能會很有用。 判斷是否有任何建置步驟相依於建置流程中使用的二進位檔案更改。

僅生成參考組件

ProduceOnlyReferenceAssembly 選項表示應輸出參考組件作為主要輸出，而非實作組件。 ProduceOnlyReferenceAssembly 參數靜默地停用輸出 PDB 檔案，因為無法執行參考組件。

<ProduceOnlyReferenceAssembly>true</ProduceOnlyReferenceAssembly>

參考組件是特殊的組件類型。 參考組件只包含代表程式庫公用 API 介面所需的最小中繼資料量。 其中包括在建置工具中參考組件時所有重要成員的宣告，但排除所有成員的實作以及對私人成員的宣告，因為這些對其 API 合約沒有產生可見影響。 如需詳細資訊，請參閱參考組件。

ProduceOnlyReferenceAssembly 和 ProduceReferenceAssembly 選項互斥。