控制編譯器輸出的 C# 編譯器選項

  • 發行項

下列選項可控制編譯器輸出產生。

MSBuild csc.exe 描述
DocumentationFile -doc: 從 /// 註解產生 XML 文件檔案。
OutputAssembly -out: 指定輸出組件檔案。
PlatformTarget -platform: 指定目標平台 CPU。
ProduceReferenceAssembly -refout: 產生參考組件。
TargetType -target: 指定輸出組件的型別。

DocumentationFile

DocumentationFile 選項可讓您在 XML 檔案中放入文件註解。 若要深入瞭解如何記錄程式碼，請參閱建議使用的文件註解標籤。 值會指定輸出 XML 檔案的路徑。 XML 檔案包含編譯原始程式碼檔案中的註解。

<DocumentationFile>path/to/file.xml</DocumentationFile>

包含主要或上層陳述式的原始程式碼檔案會先輸出為 XML。 您通常會想要搭配 IntelliSense 使用產生的 .xml 檔案。 .xml 檔案名稱必須與組件名稱相同。 .xml 檔案必須位於與組件相同的目錄中。 在 Visual Studio 專案中參考組件時，也會找到 .xml 檔案。 如需產生程式碼註解的詳細資訊，請參閱提供程式碼註解。 除非您使用 <TargetType:Module> 編譯，否則 file 會包含 <assembly> 和 </assembly> 標記，以對於輸出檔案的資訊清單包含在內的檔案指定檔案名稱。 例如，請參閱如何使用 XML 文件功能。

注意

DocumentationFile 選項會套用於專案中的所有檔案。 若要停用與特定檔案或程式碼區段文件註解相關的警告，請使用#pragma 警告。

此選項可用於任何 .NET SDK 樣式的專案。 如需詳細資訊，請參閱 DocumentationFile 屬性。

OutputAssembly

OutputAssembly 選項指定輸出檔案的名稱。 輸出路徑會指定放置編譯器輸出的資料夾。

<OutputAssembly>folder</OutputAssembly>

請指定您要建立的檔案的完整名稱和副檔名。 如果您未指定輸出檔案的名稱，MSBuild 會使用專案的名稱來指定輸出組件的名稱。 舊樣式專案使用下列規則：

  • .exe 的名稱將來自從包含 Main 方法或最上層陳述式的原始程式碼檔。
  • .dll 或 .netmodule 的名稱將來自第一個原始程式碼檔。

任何在編譯過程中產生的模組，都會變成與編譯中同時產生的任何組件建立關聯的檔案。 請使用 ildasm.exe 來檢視組件資訊清單，以查看關聯的檔案。

必須有 OutputAssembly 編譯器選項，才能讓 exe 成為 Friend 組件的目標。

PlatformTarget

指定哪個 CLR 版本可以執行組件。

<PlatformTarget>anycpu</PlatformTarget>
  • anycpu (預設值) 會將組件編譯為可在所有平台上執行。 您的應用程式會盡可能做為 64 位元處理序執行，而且只有在 32 位元模式可用時才會回到該模式。
  • anycpu32bitpreferred 會將組件編譯為可在所有平台上執行。 您的應用程式在同時支援 64 位元和 32 位元應用程式的系統上會以 32 位元模式執行。 您只能針對以 .NET Framework 4.5 或更新版本為目標的專案指定此選項。
  • ARM 會將您的組件編譯為可在採用 Advanced RISC Machine (ARM) 處理器的電腦上執行。
  • ARM64 會編譯您的組件，使其可由具備支援 A64 指令集進階 RISC 機器 (ARM) 處理器電腦上的 64 位元 CLR 執行。
  • 在支援 AMD64 或 EM64T 指令集的電腦上，x64 會將組件編譯成由 64 位元 CLR 執行。
  • x86 會將組件編譯為以 32 位元、與 x86 相容的 CLR 執行。
  • Itanium 會將組件編譯為可以在使用 Itanium 處理器的電腦上以 64 位元 CLR 執行。

在 64 位元 Windows 作業系統上：

  • 使用 x86 編譯的組件在 WOW64 下執行的 32 位元 CLR 上執行。
  • 使用 anycpu 所編譯的 DLL 會在與載入它的程序相同的 CLR 上執行。
  • 使用 anycpu 所編譯的可執行檔會在 64 位元 CLR 上執行。
  • 使用 anycpu32bitpreferred 所編譯的可執行檔會在 32 位元 CLR 上執行。

anycpu32bitpreferred 設定只對可執行檔 (.EXE) 有效，而且需要 .NET Framework 4.5 或更新版本。 如需開發要在 Windows 64 位元作業系統上執行之應用程式的詳細資訊，請參閱 64 位元應用程式。

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

anycpu 的行為在 .NET Core 和 .NET 5 與更新版本上有一些額外的細微差異。 您設定 anycpu 時，請發佈您的應用程式，並使用 x86 dotnet.exe 或 x64 dotnet.exe 執行。 針對獨立應用程式，dotnet publish 步驟會封裝設定 RID 的可執行檔。

ProduceReferenceAssembly

ProduceReferenceAssembly 選項可控制編譯器是否產生參考組件。

<ProduceReferenceAssembly>true</ProduceReferenceAssembly>

參考組件是特殊的組件類型，只包含代表程式庫公用 API 介面所需的最小中繼資料量。 這些包含參考建置工具中組件時所有重要成員的宣告。 參考組件會排除私人成員的所有成員實作和宣告。 這些成員對其 API 合約沒有任何可觀察的影響。 如需詳細資訊，請參閱 .NET 指南中的參考組件 (部分機器翻譯)。

ProduceReferenceAssembly 和 ProduceOnlyReferenceAssembly 選項互斥。

您通常不需要直接使用參考組件檔。 根據預設，參考組件會在中繼路徑的 ref 子資料夾中產生 (也就是 obj/ref/)。 若要在輸出目錄下產生這些，請改為 (也就是 bin/ref/) 在您的專案中將 ProduceReferenceAssemblyInOutDir 設定為 true。

.NET SDK 6.0.200 預設會進行參考組件從輸出目錄移至中繼目錄的變更。

TargetType

TargetType 編譯器選項可以用下列其中一種形式指定：

  • library：建立程式碼程式庫。 library 是預設值。
  • exe：建立 .exe 檔案。
  • module 建立模組的模組。
  • winexe 建立 Windows 程式。
  • winmdobj 建立中繼 .winmdobj 檔案。
  • appcontainerexe 為 Windows 8.x 市集應用程式建立 .exe 檔案。

注意

針對 .NET Framework 目標，除非您指定模組，否則此選項會導致 .NET Framework 組件資訊清單放在輸出檔案中。 如需詳細資訊，請參閱 .NET 中的組件 (部分機器翻譯) 與常見屬性 (部分機器翻譯)。

<TargetType>library</TargetType>

編譯器在每次編譯時都只會建立一個組件資訊清單。 編譯中所有檔案的資訊會放入組件資訊清單中。 在命令列產生多個輸出檔時，只能建立一個組件資訊清單，而且它必須移至命令列上所指定的第一個輸出檔。

如果您建立組件，則可以使用 CLSCompliantAttribute 屬性指出所有或部分程式碼符合 CLS 標準。

程式庫

library 選項可讓編譯器建立動態連結程式庫 (DLL)，而不是可執行檔 (EXE)。 將建立副檔名為 .dll 的 DLL。 除非特別使用 OutputAssembly 選項指定輸出檔案名稱，否則輸出檔案名稱會採用第一個輸入檔案的名稱。 建置 .dll 檔案時，不需要 Main 方法。

exe

exe 選項可讓編譯器建立可執行檔 (EXE)：主控台應用程式。 將會建立副檔名為 .exe 的可執行檔。 使用 winexe 建立 Windows 程式可執行檔。 除非特別使用 OutputAssembly 選項指定輸出檔案名稱，否則輸出檔案名稱會採用包含進入點 (Main 方法或最上層陳述式) 的輸入檔案名稱。 編譯為 .exe 檔案的原始程式碼檔中只需要一個進入點。 如果您的程式碼有多個具有 Main 方法的類別，則 StartupObject 編譯器選項可讓您指定哪個類別包含 Main 方法。

模組

這個選項可讓編譯器不要產生組件資訊清單。 根據預設，使用這個選項編譯時，所建立的輸出檔案副檔名會是 .netmodule。 .NET 執行階段無法載入沒有組件資訊清單的檔案。 不過，這類檔案可以透過 AddModules 併入組件的資訊清單。 如果在單一編譯中建立多個模組，則編譯中的其他模組可以使用某個模組中的 internal 類型。 某個模組中的程式碼參考另一個模組中的 internal 型別時，必須透過 AddModules 將這兩個模組併入資訊清單。 Visual Studio 開發環境不支援建立模組。

winexe

winexe 選項可讓編譯器建立可執行檔 (EXE)，其為一個 Windows 程式。 將會建立副檔名為 .exe 的可執行檔。 Windows 程式是從 .NET 程式庫或使用 Windows API 提供使用者介面的程式。 使用 exe 建立主控台應用程式。 除非特別使用 OutputAssembly 選項指定輸出檔案名稱，否則輸出檔案名稱會採用包含 Main 方法的輸入檔案名稱。 編譯為 .exe 檔案的原始程式碼檔中只需要一個 Main 方法。 如果您的程式碼有多個具有 Main 方法的類別，則 StartupObject 選項可讓您指定哪個類別包含 Main 方法。

winmdobj

如果您使用 winmdobj 編譯器選項，編譯器會建立一個可轉換成 Windows 執行階段二進位檔案 (.winmd) 的中繼 .winmdobj 檔案。 除了受控語言程式之外，JavaScript 和 C++ 程式也可以使用 .winmd 檔案。

winmdobj 設定對編譯器發出訊號，表示需要中繼模組。 然後 .winmdobj 檔案可以透過 WinMDExp 匯出工具產生 Windows 中繼資料 (.winmd) 檔案。 .winmd 檔案包含原始類別庫的程式碼，以及 JavaScript 或 C++ 和 Windows 執行階段所使用的 WinMD 中繼資料。 使用 winmdobj 編譯器選項編譯的檔案輸出只會做為 WimMDExp 匯出工具的輸入。 不會直接參考 .winmdobj 檔案本身。 除非您使用 OutputAssembly 選項指定輸出檔案名稱，否則輸出檔案名稱會採用第一個輸入檔案的名稱。 不需要 Main 方法。

appcontainerexe

如果您使用 appcontainerexe 編譯器選項，編譯器會建立一個必須在應用程式容器中執行的 Windows 可執行檔 (.exe)。 這個選項相當於 -target:winexe，但是專為 Windows 8.x 市集應用程式所設計。

這個選項會在 Portable Executable (可攜式執行檔) (PE) 中設定一個位元，以要求應用程式在應用程式容器中執行。 當這個位元設定時，如果 CreateProcess 方法嘗試在應用程式容器之外啟動可執行檔，則會發生錯誤。 除非您使用 OutputAssembly 選項指定輸出檔案名稱，否則輸出檔案名稱會採用包含 Main 方法的輸入檔案名稱。