指定輸入的 C# 編譯器選項

文章
05/10/2023

下列選項會控制編譯器輸入。新的 MSBuild 語法會以「粗體」顯示。較舊的 csc.exe 語法會以code style顯示。

References / -reference 或 -references：從指定的組件檔或檔案參考中繼資料。
AddModules / -addmodule：新增模組 (使用 target:module 建立至此組件。)
EmbedInteropTypes / -link：從指定的 Interop 組件檔案內嵌中繼資料。

參考資料

References 選項可讓編譯器將指定檔案的 public 型別資訊匯入至目前的專案，讓您透過指定的組件檔案參考中繼資料。

<Reference Include="filename" />

filename 是含有資訊清單的檔案名稱。若要匯入多個檔案，請為每個檔案納入個別的 Reference 元素。您可以將別名定義為 Reference 元素的子項目：

<Reference Include="filename.dll">
  <Aliases>LS</Aliases>
</Reference>

在上一個範例中，LS 是代表根命名空間的有效 C# 識別碼，其中包含組件 filename.dll 中的所有命名空間。您匯入的檔案必須包含資訊清單。請使用 AdditionalLibPaths 指定一或多個組件參考所在的目錄。 AdditionalLibPaths 主題也會說明編譯器會在其中搜尋組件的目錄。為了讓編譯器可以辨識位於組件中的類型 (而不是模組中)，您必須定義類型的執行個體，以強制讓編譯器解析類型。您也可以使用其他方法，讓編譯器解析組件中的類型名稱：例如，您可以繼承組件的類型，編譯器即可辨識類型名稱。有時候，您必須參考組件內相同元件的兩個不同版本。若要這樣做，請針對每個檔案，使用 References 元素上的 Aliases 元素，以區別兩個不同的檔案。系統會將此別名作為元件名稱的限定詞，並將元件解析為其中一個檔案。

注意

在 Visual Studio 中，使用 [新增參考] 命令。如需詳細資訊，請參閱如何：使用參考管理員新增或移除參考。

AddModules

此選項會將使用 <TargetType>module</TargetType> 參數所建立的模組新增至目前的編譯：

<AddModule Include=file1 />
<AddModule Include=file2 />

其中 file、file2 是包含中繼資料的輸出檔案。該檔案不包含資訊清單。若要匯入多個檔案，請以逗號或分號分隔檔案名稱。所有加上 AddModules 的模組都必須和執行階段的輸出檔案位於相同的目錄中。也就是說，您可以在編譯時間指定任一目錄中的模組，但該模組於執行階段必須位在應用程式目錄中。如果模組於執行階段不在應用程式目錄中，您就會有 TypeLoadException。 file 不包含組件。例如，如果輸出檔案使用 module 的 TargetType 選項建立，則可以使用 AddModules 匯入其中繼資料。

如果輸出檔案使用非 module 的 TargetType 選項建立，則無法使用 AddModules 匯入其中繼資料，但可使用 References 選項匯入。

EmbedInteropTypes

讓編譯器將所指定組件的 COM 類型資訊全部提供給您目前編譯的專案。

<References>
  <EmbedInteropTypes>file1;file2;file3</EmbedInteropTypes>
</References>

其中 file1;file2;file3 是以分號分隔的組件檔案名稱清單。如果檔案名稱包含空格，請用引號括住名稱。 EmbedInteropTypes 選項可讓您部署具有內嵌型別資訊的應用程式。應用程式接著可以使用執行階段組件中實作內嵌類型資訊的類型，而不需要參考執行階段組件。如果執行階段組件有許多發行版本，包含內嵌類型資訊的應用程式不需要重新編譯，就可以搭配各種版本使用。如需範例，請參閱 Walkthrough: Embedding Types from Managed Assemblies (逐步解說：從 Managed 組件內嵌類型)。

如果您正在使用 COM Interop，使用 EmbedInteropTypes 選項會特別有用。您可以內嵌 COM 類型，如此一來您的應用程式就不會再要求目標電腦上必須有主要 Interop 組件 (PIA)。 EmbedInteropTypes 選項會指示編譯器將所參考 Interop 組件的 COM 型別資訊嵌入編譯產生的程式碼。 COM 類型是由 CLSID (GUID) 值來識別。因此，應用程式可以在已安裝含相同 CLSID 值之相同 COM 類型的目標電腦上執行。自動化 Microsoft Office 的應用程式即為一個很好的例子。由於 Office 等應用程式通常會在不同版本間保持相同的 CLSID 值，因此只要目標電腦上已安裝 .NET Framework 4 或更新版本，且應用程式使用包含在所參考 COM 類型中的方法、屬性或事件，應用程式就可以使用這些參考的 COM 類型。 EmbedInteropTypes 選項只能內嵌介面、結構和委派。不支援內嵌 COM 類別。

注意

當您在程式碼中建立內嵌 COM 類型的執行個體時，必須使用適當的介面來建立執行個體。嘗試使用 CoClass 建立內嵌 COM 類型的執行個體將會導致錯誤。

如同 References 編譯器選項，EmbedInteropTypes 編譯器選項會使用參考常用 .NET 組件的 Csc.rsp 回應檔。如果您不想要讓編譯器使用 Csc.rsp 檔，請使用 NoConfig 編譯器選項。

// The following code causes an error if ISampleInterface is an embedded interop type.
ISampleInterface<SampleType> sample;

如果具有泛型參數的類型來自外部組件，且其參數的類型是從 Interop 組件內嵌的，則無法使用該類型。這項限制不適用於介面。例如，請考慮使用 Microsoft.Office.Interop.Excel 組件中所定義的 Range 介面。如果程式庫內嵌來自 Microsoft.Office.Interop.Excel 組件的 Interop 類型，並公開傳回泛型型別的方法，但是此泛型型別具有類型為 Range 介面的參數，則該方法就必須傳回泛型介面，如下列程式碼範例所示。

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Microsoft.Office.Interop.Excel;

public class Utility
{
    // The following code causes an error when called by a client assembly.
    public List<Range> GetRange1()
    {
        return null;
    }

    // The following code is valid for calls from a client assembly.
    public IList<Range> GetRange2()
    {
        return null;
    }
}

在下列範例中，用戶端程式碼可以呼叫傳回 IList 泛型介面的方法，且不會發生錯誤。

public class Client
{
    public void Main()
    {
        Utility util = new Utility();

        // The following code causes an error.
        List<Range> rangeList1 = util.GetRange1();

        // The following code is valid.
        List<Range> rangeList2 = (List<Range>)util.GetRange2();
    }
}

分享方式：

指定輸入的 C# 編譯器選項

參考資料

AddModules

EmbedInteropTypes

更多資源