進階 C# 編譯器選項

  • 發行項

下列選項支援進階案例。 新的 MSBuild 語法會以「粗體」顯示。 較舊的 csc.exe 語法會以 code style 顯示。

  • MainEntryPoint、StartupObject / -main：指定內含進入點的型別。
  • PdbFile / -pdb：指定偵錯資訊檔案名稱。
  • PathMap / -pathmap：指定編譯器所輸出來源路徑名稱的對應。
  • ApplicationConfiguration / -appconfig：指定內含組件繫結設定的應用程式組態檔。
  • AdditionalLibPaths / -lib：指定要搜尋參考的其他目錄。
  • GenerateFullPaths / -fullpath：編譯器產生完整路徑。
  • PreferredUILang / -preferreduilang：指定慣用的輸出語言名稱。
  • BaseAddress / -baseaddress：指定要組建程式庫的基底位址。
  • ChecksumAlgorithm / -checksumalgorithm：指定用於計算儲存在 PDB 的來源檔案總和檢查碼的演算法。
  • CodePage / -codepage：指定開啟來源檔案時所要使用的程式碼頁。
  • Utf8Output / -utf8output：在 UTF-8 編碼中輸出編譯器訊息。
  • FileAlignment / -filealign：指定用來輸出檔案區段的對齊。
  • ErrorEndLocation / -errorendlocation：輸出每個錯誤結束位置的行與列。
  • NoStandardLib / -nostdlib：請勿參考標準程式庫 mscorlib.dll。
  • SubsystemVersion / -subsystemversion：指定此組件的子系統版本。
  • ModuleAssemblyName / -moduleassemblyname：將包含此模組的組件名稱。
  • ReportIVT / -reportivts：產生 System.Runtime.CompilerServices.InternalsVisibleToAttribute 資訊的其他資訊。

您可以在 *.csproj 檔案中的 <PropertyGroup> 元素新增下列任何選項：

<PropertyGroup>
    <StartupObject>...</StartupObject>
    ...
</PropertyGroup>

MainEntryPoint or StartupObject

如果有多個包含 Main 方法的類別，這個選項會指定含有程式進入點的類別。

<StartupObject>MyNamespace.Program</StartupObject>

或

<MainEntryPoint>MyNamespace.Program</MainEntryPoint>

其中 Program 是含有 Main 方法的型別。 提供的類別名稱必須完整。名稱必須包括內含類別的完整命名空間，後面接著類別名稱。 例如，當 Main 方法位於 MyApplication.Core 命名空間中的 Program 類別時，編譯器選項必須是 -main:MyApplication.Core.Program。 如果您的編譯含有多個含有 Main 的方法，您可以指定含有 Main 方法的型別。

注意

此選項無法用於包含最上層陳述式的專案，即使該專案包含一或多個 Main 方法。

PdbFile

PdbFile 編譯器選項指定偵錯符號檔的名稱和位置。 filename值指定偵錯符號檔的名稱和位置。

<PdbFile>filename</PdbFile>

當您指定 DebugType 時，編譯器會在編譯器建立輸出檔案 (.exe 或 .dll) 的相同目錄中，建立一個 .pdb 檔案。 .pdb 檔案的基底檔案名稱與輸出檔案名稱相同。 PdbFile 可讓您指定 .pdb 檔案的非預設檔案名稱和位置。 無法在 Visual Studio 開發環境中設定此編譯器選項，也無法以程式設計方式進行變更。

PathMap

注意

指定 PathMap 可防止中斷點在本機偵錯組建中運作。 僅針對生產環境或持續整合組建設定 PathMap。

PathMap 編譯器選項會指定如何將實體路徑對應到編譯器所輸出的來源路徑名稱。 此選項會將編譯器執行所在電腦上的每個實體路徑對應到應寫入輸出檔案的對應路徑。 在下列範例中，path1 是目前環境中來源檔案的完整路徑，而 sourcePath1 是任何輸出檔案中替換 path1 的來源路徑。 若要指定多個對應的來源路徑，請以逗號隔開每個來源路徑。

<PathMap>path1=sourcePath1,path2=sourcePath2</PathMap>

編譯器會基於下列因素，將來源路徑寫入其輸出中：

  1. 將 CallerFilePathAttribute 套用到選擇性參數時，會針對引數替代來源路徑。
  2. 來源路徑內嵌於 PDB 檔案。
  3. PDB 檔案的路徑內嵌於 PE (可攜式執行檔) 檔案。

ApplicationConfiguration

ApplicationConfiguration 編譯器選項可讓 C# 應用程式在組件繫結時間時，將組件應用程式組態檔 (app.config) 的位置指定到通用語言執行平台 (CLR)。

<ApplicationConfiguration>file</ApplicationConfiguration>

其中 file 是包含組件繫結設定的應用程式組態檔。 ApplicationConfiguration 的其中一種用法就是進階案例；在此案例中，組件必須同時參考特定參考組件的 .NET Framework 版本以及 .NET Framework for Silverlight 版本。 例如，以 Windows Presentation Foundation (WPF) 撰寫的 XAML 設計工具，可能必須同時參考 WPF Desktop (設計工具的使用者介面) 和 Silverlight 所附的 WPF 子集。 相同的設計工具組件必須存取這兩個組件。 根據預設，不同的參考會導致編譯器錯誤，因為組件繫結關係會將兩個組件視為對等項目。 ApplicationConfiguration 編譯器選項可讓您使用 <supportPortability> 指定停用預設行為的 app.config 檔案位置，如下列範例所示。

<supportPortability PKT="7cec85d7bea7798e" enable="false"/>

編譯器會將檔案位置傳遞至 CLR 的組件繫結關係邏輯。

注意

若要使用專案中已設定的 app.config 檔案，請將屬性標記 <UseAppConfigForCompiler> 新增至 .csproj 檔案，並將其值設定為 true。 若要指定不同的 app.config 檔案，請新增屬性標記 <AppConfigForCompiler> 並將其值設定為檔案位置。

下例示範的 app.config 檔案，可讓應用程式同時參考存在於兩個實作中之任何 .NET Framework 組件的 .NET Framework 實作和 .NET Framework for Silverlight 實作。 ApplicationConfiguration 編譯器選項會指定此 app.config 檔案的位置。

<configuration>
  <runtime>
    <assemblyBinding>
      <supportPortability PKT="7cec85d7bea7798e" enable="false"/>
      <supportPortability PKT="31bf3856ad364e35" enable="false"/>
    </assemblyBinding>
  </runtime>
</configuration>

AdditionalLibPaths

AdditionalLibPaths 選項指定使用 References 選項參考的組件位置。

<AdditionalLibPaths>dir1[,dir2]</AdditionalLibPaths>

如果編譯器在目前的工作目錄 (您叫用編譯器的起點目錄) 或通用語言執行平台的系統目錄中找不到參考的組件，則 dir1 是編譯器查詢的目錄。 dir2 是可尋找組件參考的一或多個其他目錄。 使用逗號分隔的目錄名稱，之間不含任何空白字元。 編譯器會以下列順序搜尋不完整的組件參考：

  1. 目前的工作目錄。
  2. 通用語言執行平台系統目錄。
  3. AdditionalLibPaths 指定的目錄。
  4. LIB 環境變數所指定的目錄。

使用 Reference 指定組件參考。 Reference 為加法。 指定超過一次時，即會附加到任何先前的值。 由於資訊清單中未指定相依組件的路徑，因此應用程式會在全域組件快取中尋找和使用組件。 參考組件的編譯器不表示通用語言執行平台可在執行階段尋找和載入組件。 如需執行階段如何搜尋參考組件的詳細資訊，請參閱執行階段如何找出組件。

GenerateFullPaths

列出編譯錯誤和警告時，GenerateFullPaths 選項可讓編譯器指定檔案的完整路徑。

<GenerateFullPaths>true</GenerateFullPaths>

根據預設，編譯造成的錯誤和警告會指定發現錯誤的檔案名稱。 GenerateFullPaths 選項可讓編譯器指定檔案的完整路徑。 Visual Studio 不提供這個編譯器選項，您亦無法以程式設計方式變更。

PreferredUILang

使用 PreferredUILang 編譯器選項，您就可以指定 C# 編譯器顯示輸出的語言，例如錯誤訊息。

<PreferredUILang>language</PreferredUILang>

其中 language 是編譯器輸出所用語言的語言名稱。 您可以使用 PreferredUILang 編譯器選項指定 C# 編譯器用於錯誤訊息和其他命令列輸出的語言。 如果尚未安裝此語言的語言套件，則會改用作業系統的語言設定。

BaseAddress

BaseAddress 選項讓您指定要載入 DLL 的慣用基底位址。 如需此選項的使用時機與使用原因之詳細資訊，請參閱 Larry Osterman 的部落格。

<BaseAddress>address</BaseAddress>

其中 address 是 DLL 的基底位址。 這個位址可以指定十進位、十六進位或八進位數字。 DLL 的預設基底位址是由 .NET 通用語言執行平台所設定。 此位址的低順序字組會被捨去。 例如，如果您指定的是 0x11110001，它會去掉尾數變成 0x11110000。 若要完成 DLL 的簽章程序，請使用 SN.EXE 和 -R 選項。

ChecksumAlgorithm

此選項可控制我們用於 PDB 中編碼來源檔案的總和檢查碼演算法。

<ChecksumAlgorithm>algorithm</ChecksumAlgorithm>

algorithm 必須是 SHA1 (預設) 或 SHA256。

CodePage

如果所需的頁面不是系統目前預設的字碼頁，這個選項可指定編譯期間使用的字碼頁。

<CodePage>id</CodePage>

其中 id 是編譯過程中所有原始程式碼檔使用的字碼頁的識別碼。 編譯器會先嘗試將所有來源檔案解譯為 UTF-8。 如果您的原始程式檔不是以 UTF-8 編碼，也不使用 7 位元的 ASCII 字元，則請使用 CodePage 選項指定應該使用的字碼頁。 CodePage 會套用至您所編譯的所有原始程式碼檔。 如需如何尋找系統所支援之字碼頁的詳細資訊，請參閱 GetCPInfo。

Utf8Output

Utf8Output 選項會使用 UTF-8 編碼顯示編譯器輸出。

<Utf8Output>true</Utf8Output>

在某些國際設定中，編譯器輸出無法正確地顯示在主控台中。 使用 Utf8Output 並將編譯器輸出重新導向至檔案。

FileAlignment

FileAlignment 選項可讓您指定輸出檔案中的區段大小。 有效值為 512、1024、2048、4096 和 8192。 這些值是以位元組為單位。

<FileAlignment>number</FileAlignment>

在Visual Studio 中您可以從[組建] 屬性的[進階] 頁面為您的專案設定 FileAlignment 選項。 每個區段都會對齊界限，而這個界限是 FileAlignment 值的倍數。 沒有固定預設值。 如果未指定 FileAlignment，通用語言執行平台會在編譯階段選取預設值。 您可以藉由指定區段大小，來影響輸出檔案的大小。 修改區段大小對執行於較小裝置上的程式而言可能很有用。 請使用 DUMPBIN 來查看輸出檔案中區段的相關資訊。

ErrorEndLocation

指示編譯器輸出每個錯誤結束位置的行與列。

<ErrorEndLocation>true</ErrorEndLocation>

編譯器預設會在來源中寫入所有錯誤和警告的起始位置。 當此選項設為 true 時，編譯器會寫入每個錯誤和警告的起始和結束位置。

NoStandardLib

NoStandardLib 會導致無法匯入 mscorlib.dll，而此檔案定義整個系統命名空間。

<NoStandardLib>true</NoStandardLib>

如果您想要定義或建立自己的系統命名空間和物件，請使用此選項。 若您沒有指定 NoStandardLib，mscorlib.dll 會匯入您的程式中 (與指定 <NoStandardLib>false</NoStandardLib> 相同)。

SubsystemVersion

指定可執行檔執行的最低子系統版本。 大多數情況下，此選項可確保可執行檔可以使用舊版 Windows 未提供的安全性功能。

注意

若要指定子系統本身，請使用 TargetType 編譯器選項。

<SubsystemVersion>major.minor</SubsystemVersion>

major.minor 會指定子系統的最小必要版本，以點標記法表示主要和次要版本。 例如，您可以指定應用程式無法在早於 Windows 7 的作業系統上執行。 如本文稍後表格所述，將此選項的值設為 6.01。 您可以將 major 和 minor 的值指定為整數。 minor 版本中的前置零不會變更版本，但尾端零則會。 例如，6.1 和 6.01 參照相同版本，但 6.10 參照不同版本。 建議您將次要版本表示為兩位數，以避免混淆。

下表列出常見的 Windows 子系統版本。

Windows 版本 子系統版本
Windows Server 2003 5.02
Windows Vista 6.00
Windows 7 6.01
Windows Server 2008 6.01
Windows 8 6.02

SubsystemVersion 編譯器選項的預設值取決於下列清單中的條件：

  • 如果設定下列清單中的任何編譯器選項，則預設值為 6.02：
  • 如果您使用的是 MSBuild、以 .NET Framework 4.5 為目標，且尚未設定稍早在此清單中指定的任何編譯器選項，則預設值為 6.00。
  • 如果先前的條件均非為 true，則預設值是 4.00。

ModuleAssemblyName

指定 .netmodule 可以存取其非公用類型的組件名稱。

<ModuleAssemblyName>assembly_name</ModuleAssemblyName>

ModuleAssemblyName 應在組建 .netmodule 時，以及符合下列條件時使用：

  • .netmodule 需要存取現有組件中的非公用類型。
  • 您知道將在其中建置 .netmodule 之組件的名稱。
  • 現存組件已對將在其中組建 .netmodule 的組件授與 friend 組件的存取權。

如需組建 .netmodule 的詳細資訊，請參閱 模組的 TargetType 選項。 如需 Friend 組件的詳細資訊，請參閱 Friend 組件。

ReportIVTs

啟用或停用編譯期間找到的其他 System.Runtime.CompilerServices.InternalsVisibleToAttribute 診斷資訊：

<ReportIVTs>true</ReportIVTs>

如果元素內容為 true，則啟用診斷，如果為 false 或不存在，則停用。

ReportIVTs 會在啟用時報告下列資訊：

  1. 如果與目前組件不同，則任何無法存取的成員診斷都包含其來源組件。
  2. 編譯器會列印要編譯之專案的組件識別、其組件名稱和公開金鑰。
  3. 針對傳遞至編譯器的每個參考，它會列印；
    1. 參考的組件識別
    2. 參考是否授與目前專案 InternalsVisibleTo
    3. 從這個組件授與 InternalsVisibleTo 之任何組件的名稱和所有公開金鑰