逐步解說：在 Visual Studio 中內嵌來自受控組件的類型

發行項
05/22/2023

若要內嵌來自強式名稱 Managed 組件的類型資訊，您可以鬆散地結合應用程式中的類型以確保版本獨立。也就是說，您可以撰寫程式來使用受控程式庫多個版本的類型，而不需重新編譯每個版本。

內嵌型別時，通常會搭配使用 COM Interop (例如從 Microsoft Office 使用 Automation 物件的應用程式)。當您內嵌類型資訊時，可讓相同組建的程式使用不同電腦上版本各異的 Microsoft Office。不過，您也可以搭配使用類型內嵌功能與完全受管理的解決方案。

指定可內嵌的公用介面之後，您可以建立執行階段類別以實作這些介面。接著，用戶端程式即會參考包含公用介面的組件，然後將參考的 Embed Interop Types 屬性設為 True，在設計階段內嵌這些介面的類型資訊。用戶端程式即可載入以這些介面為類型的執行階段物件執行個體。這相當於使用命令列編譯器，並使用 EmbedInteropTypes 編譯器選項來參考組件。

如果您建立新版本的強式名稱執行階段組件，用戶端程式就不需要重新編譯。用戶端程式會繼續使用執行階段組件適用的任何版本，並針對公用介面使用內嵌的類型資訊。

在本逐步解說中，您將：

建立具有公用介面的強式名稱組件，且該介面包含可內嵌的類型資訊。
建立強式名稱的執行階段組件，以實作上述公用介面。
建立用戶端程式，以內嵌公用介面的類型資訊，並從執行階段組件建立類別的執行個體。
修改並重新建置執行階段組件。
執行用戶端程式，查看是否正在使用新版本的執行階段組件，而不必進行重新編譯。

注意

在下列指示的某些 Visual Studio 使用者介面項目中，您的電腦可能會顯示不同的名稱或位置：您所擁有的 Visual Studio 版本以及使用的設定會決定這些項目。如需詳細資訊，請參閱將 Visual Studio IDE 個人化。

條件和限制

您可以在下列情況下，透過組件內嵌類型資訊：

組件已公開至少一個公用介面。
內嵌介面會以 Guid 具有唯一 GUID 的屬性和 ComImport 屬性加上批註。
您可以使用 ImportedFromTypeLib 屬性或 PrimaryInteropAssembly 屬性及組件層級 Guid 屬性，來標註組件 Visual C# 和 Visual Basic 專案範本預設包含元組件層級 Guid 屬性。

由於類型內嵌的主要功能是支援 COM Interop 組件，因此當您將類型資訊內嵌在完全受管理的解決方案中時，也會套用下列限制：

只會內嵌 COM Interop 專屬的屬性，其他屬性則會忽略。
如果某類型使用泛型參數，而該泛型參數的類型是內嵌的類型，您就不能跨組件界限使用此類型。跨組件界限的範例包括從其他組件呼叫方法，或透過定義於其他組件上的類型來衍生類型。
系統不會內嵌常數。
System.Collections.Generic.Dictionary<TKey,TValue> 類別不支援內嵌類型作為索引鍵。您可以實作自己的字典類型，以支援索引鍵形式的內嵌類型。

建立介面

第一個步驟是建立類型等價介面組件。

在 Visual Studio 中，選取 [檔案]> [新增]> [專案]。
在 [建立新專案] 對話方塊的 [搜尋範本] 方塊中輸入「類別庫」。從清單中選取 C# 或 Visual Basic類別庫 (.NET Framework) 範本，然後選取 [下一步]。
在 [設定新專案] 對話方塊的 [專案名稱] 下，輸入 TypeEquivalenceInterface，然後選取 [建立]。隨即建立新專案。
在 [方案總管] 中，以滑鼠右鍵按一下 Class1.cs 或 Class1.vb 檔案，選取 [重新命名]，然後將檔案從 Class1 重新命名為 ISampleInterface。向提示回應 [是]，同時將類別重新命名為 ISampleInterface。這個類別將代表類別的公用介面。
在 [方案總管] 中，以滑鼠右鍵按一下 [TypeEquivalenceInterface] 專案，然後選取 [屬性]。
選取 [屬性] 畫面左窗格中的 [組建]，然後將 [輸出路徑] 設定為電腦上的某個位置，例如 C：\TypeEquivalenceSample。在本逐步解說中，您會使用相同的位置。
選取 [屬性] 畫面左窗格中的 [組建]>[強式命名]，然後選取 [簽署組件] 核取方塊。在 [強式名稱金鑰檔案] 中，選取 [瀏覽]。
瀏覽然後選取您在 TypeEquivalenceInterface 專案中建立的 key.snk 檔案，然後選取 [確定]。如需詳細資訊，請參閱建立公開/私密金鑰組。

在程式碼編輯器中開啟 ISampleInterface 類別檔案，並以下列程式碼取代其內容來建立 ISampleInterface 介面：

using System;
using System.Runtime.InteropServices;

namespace TypeEquivalenceInterface
{
    [ComImport]
    [Guid("8DA56996-A151-4136-B474-32784559F6DF")]
    public interface ISampleInterface
    {
        void GetUserInput();
        string UserInput { get; }
    }
}

Imports System.Runtime.InteropServices

<ComImport()>
<Guid("8DA56996-A151-4136-B474-32784559F6DF")>
Public Interface ISampleInterface
    Sub GetUserInput()
    ReadOnly Property UserInput As String
End Interface

在 [工具] 功能表上，選取 [建立 Guid]，然後在 [建立 GUID] 對話方塊中選取 [登錄格式]。選取 [複製]，然後選取 [結束]。
在程式碼的 Guid 屬性中，將範例 GUID 取代為您複製的 GUID，然後移除大括弧 ({ })。
在 [方案總管] 中，展開 [屬性] 資料夾，然後選取 AssemblyInfo.cs 或 AssemblyInfo.vb 檔案。在程式碼編輯器中，將下列屬性新增至檔案中：
```
[assembly: ImportedFromTypeLib("")]
```
```
<Assembly: ImportedFromTypeLib("")>
```
選取 [檔案]>[全部儲存]，或按 Ctrl+Shift+S 以儲存檔案和專案。
在 [方案總管] 中，以滑鼠右鍵按一下 [TypeEquivalenceInterface] 專案，然後選取 [組件]。即會編譯類別庫 DLL 檔案，並將其儲存至指定的組建輸出路徑，例如 C:\TypeEquivalenceSample。

建立執行階段類別

接下來，建立類型等價執行階段類別。

在 Visual Studio 中，選取 [檔案]> [新增]> [專案]。
在 [建立新專案] 對話方塊的 [搜尋範本] 方塊中輸入「類別庫」。從清單中選取 C# 或 Visual Basic類別庫 (.NET Framework) 範本，然後選取 [下一步]。
在 [設定新專案] 對話方塊的 [專案名稱] 下，輸入 TypeEquivalenceRuntime，然後選取 [建立]。隨即建立新專案。
在 [方案總管] 中，以滑鼠右鍵按一下 Class1.cs 或 Class1.vb 檔案，選取 [重新命名]，然後將檔案從 Class1 重新命名為 SampleClass。向提示回應 [是]，同時將類別重新命名為 SampleClass。此類別會實作 ISampleInterface 介面。
在 [方案總管] 中，以滑鼠右鍵按一下 [TypeEquivalenceInterface] 專案，再選取 [屬性]。
選取 [屬性] 畫面左窗格中的 [組建]，然後將 [輸出路徑] 設定為您用於 TypeEquivalenceInterface 專案的相同位置，例如 C：\TypeEquivalenceSample。
選取 [屬性] 畫面左窗格中的 [組建]>[強式命名]，然後選取 [簽署組件] 核取方塊。在 [強式名稱金鑰檔案] 中，選取 [瀏覽]。
瀏覽然後選取您在 TypeEquivalenceInterface 專案中建立的 key.snk 檔案，然後選取 [確定]。如需詳細資訊，請參閱建立公開/私密金鑰組。
在 [方案總管]中，以滑鼠右鍵按一下 [TypeEquivalenceRuntime] 專案，然後選取 [新增]>[參考]。
在 [參考管理員] 對話方塊中，選取 [瀏覽] 並瀏覽至輸出路徑資料夾。選取 TypeEquivalenceInterface.dll 檔案再選取 [新增]，然後按一下 [確定]。
在 [方案總管] 中，展開[參考] 資料夾，然後選取 [TypeEquivalenceInterface] 參考。在 [屬性] 窗格中，如果尚未將 [特定版本] 設定為 [False]，請進行該設定。

在程式碼編輯器中開啟 SampleClass 類別檔案，並以下列程式碼取代其內容來建立 SampleClass 類別：

using System;
using TypeEquivalenceInterface;

namespace TypeEquivalenceRuntime
{
    public class SampleClass : ISampleInterface
    {
        private string p_UserInput;
        public string UserInput { get { return p_UserInput; } }

        public void GetUserInput()
        {
            Console.WriteLine("Please enter a value:");
            p_UserInput = Console.ReadLine();
        }
    }
}

Imports TypeEquivalenceInterface

Public Class SampleClass
    Implements ISampleInterface

    Private p_UserInput As String
    Public ReadOnly Property UserInput() As String Implements ISampleInterface.UserInput
        Get
            Return p_UserInput
        End Get
    End Property

    Public Sub GetUserInput() Implements ISampleInterface.GetUserInput
        Console.WriteLine("Please enter a value:")
        p_UserInput = Console.ReadLine()
    End Sub
End Class

選取 [檔案]>[全部儲存]，或按 Ctrl+Shift+S 以儲存檔案和專案。
在 [方案總管]中，以滑鼠右鍵按一下 [TypeEquivalenceRuntime] 專案，然後選取 [組件]。即會編譯類別庫 DLL 檔案，並將其儲存至指定的組建輸出路徑。

建立用戶端專案

最後，建立參考介面組件的類型等價用戶端程式。

在 Visual Studio 中，選取 [檔案]> [新增]> [專案]。
在 [建立新專案] 對話方塊的 [搜尋範本] 方塊中輸入「主控台」。從清單中選取 C# 或 Visual Basic主控台應用程式 (.NET Framework) 範本，然後選取 [下一步]。
在 [設定新專案] 對話方塊的 [專案名稱] 下，輸入 TypeEquivalenceClient，然後選取 [建立]。隨即建立新專案。
在 [方案總管] 中，以滑鼠右鍵按一下 [TypeEquivalenceClient] 專案，再選取 [屬性]。
選取 [屬性] 畫面左窗格中的 [組建]，然後將 [輸出路徑] 設定為您用於 TypeEquivalenceInterface 專案的相同位置，例如 C：\TypeEquivalenceSample。
在 [方案總管] 中，以滑鼠右鍵按一下 [TypeEquivalenceClient] 專案，再選取 [屬性]>[參照]。
在 [參考管理員] 對話方塊中，如果已列出 [TypeEquivalenceInterface.dll] 檔案，請選取該項目。如果沒有，請選取 [瀏覽]，瀏覽至輸出路徑資料夾、選取 [TypeEquivalenceInterface.dll] 檔案 (不是 TypeEquivalenceRuntime.dll)，然後選取 [新增]。選取 [確定]。
在 [方案總管] 中，展開[參考] 資料夾，然後選取 [TypeEquivalenceInterface] 參考。在 [屬性] 窗格中，將 [內嵌 Interop 類型] 設定為 [True]。

在程式碼編輯器中開啟 Program.cs 或 Module1.vb 檔案，並以下列程式碼取代其內容來建立用戶端程式：

using System;
using System.Reflection;
using TypeEquivalenceInterface;

namespace TypeEquivalenceClient
{
    class Program
    {
        static void Main(string[] args)
        {
            Assembly sampleAssembly = Assembly.Load("TypeEquivalenceRuntime");
            ISampleInterface sampleClass =
                (ISampleInterface)sampleAssembly.CreateInstance("TypeEquivalenceRuntime.SampleClass");
            sampleClass.GetUserInput();
            Console.WriteLine(sampleClass.UserInput);
            Console.WriteLine(sampleAssembly.GetName().Version.ToString());
            Console.ReadLine();
        }
    }
}

Imports System.Reflection
Imports TypeEquivalenceInterface

Module Module1

    Sub Main()
        Dim sampleAssembly = Assembly.Load("TypeEquivalenceRuntime")
        Dim sampleClass As ISampleInterface = CType( _
            sampleAssembly.CreateInstance("TypeEquivalenceRuntime.SampleClass"), ISampleInterface)
        sampleClass.GetUserInput()
        Console.WriteLine(sampleClass.UserInput)
        Console.WriteLine(sampleAssembly.GetName().Version)
        Console.ReadLine()
    End Sub

End Module

選取 [檔案]>[全部儲存]，或按 Ctrl+Shift+S 以儲存檔案和專案。
按 CTRL+F5 組建並執行程式。請注意，主控台輸出會傳回組件版本 1.0.0.0。

修改介面

現在請修改介面組件，並變更其版本。

在 Visual Studio 中，選取 [檔案]>[開啟]>[專案/解決方案]，然後開啟 [TypeEquivalenceInterface] 專案。
在 [方案總管] 中，以滑鼠右鍵按一下 [TypeEquivalenceInterface] 專案，再選取 [屬性]。
選取 [屬性] 畫面左窗格中的 [應用程式]，然後選取 [組件資訊]。
在 [組件資訊] 對話方塊中，將 [組件版本] 和 [檔案版本] 值變更為 2.0.0.0，然後選取 [確定]。
開啟 SampleInterface.cs 或 SampleInterface.vb 檔案，並將下列程式程式碼新增至 ISampleInterface 介面：
```
DateTime GetDate();
```
```
Function GetDate() As Date
```
選取 [檔案]>[全部儲存]，或按 Ctrl+Shift+S 以儲存檔案和專案。
在 [方案總管] 中，以滑鼠右鍵按一下 [TypeEquivalenceInterface] 專案，然後選取 [組件]。即會編譯新版本類別庫 DLL 檔案，並將其儲存至組建輸出路徑。

若要修改執行階段類別

同時修改執行時間類別並更新其版本。

在 Visual Studio 中，選取 [檔案]>[開啟]>[專案/解決方案]，然後開啟 [TypeEquivalenceRuntime] 專案。
在 [方案總管]中，以滑鼠右鍵按一下 [TypeEquivalenceRuntime] 專案，然後選取 [屬性]。
選取 [屬性] 畫面左窗格中的 [應用程式]，然後選取 [組件資訊]。
在 [組件資訊] 對話方塊中，將 [組件版本] 和 [檔案版本] 值變更為 2.0.0.0，然後選取 [確定]。

開啟 SampleClass.cs 或 SampleClass.vb 檔案，並將下列程式碼新增至 SampleClass 類別：

 public DateTime GetDate()
 {
     return DateTime.Now;
 }

Public Function GetDate() As DateTime Implements ISampleInterface.GetDate
    Return Now
End Function

選取 [檔案]>[全部儲存]，或按 Ctrl+Shift+S 以儲存檔案和專案。
在 [方案總管]中，以滑鼠右鍵按一下 [TypeEquivalenceRuntime] 專案，然後選取 [組件]。即會編譯新版本類別庫 DLL 檔案，並將其儲存至組建輸出路徑。

執行更新的用戶端程式

移至組建輸出資料夾位置，然後執行 TypeEquivalenceClient.exe。請注意，主控台輸出現在會反映新版本的 TypeEquivalenceRuntime 組件 2.0.0.0，而不需要重新編譯程式。