Przewodnik: osadzanie typów z zarządzanych zestawów w programie Visual Studio

Artykuł
05/10/2023

Jeśli osadzasz informacje o typie z zestawu zarządzanego o silnej nazwie, możesz luźno parować typy w aplikacji, aby uzyskać niezależność wersji. Oznacza to, że program może być zapisywany w celu używania typów z dowolnej wersji biblioteki zarządzanej bez konieczności ponownego komilowania dla każdej nowej wersji.

Osadzanie typu jest często używane z międzyoperacyjności COM, na przykład aplikacji korzystającej z obiektów automatyzacji z pakietu Microsoft Office. Osadzanie informacji o typie umożliwia tę samą kompilację programu do pracy z różnymi wersjami pakietu Microsoft Office na różnych komputerach. Można jednak również użyć osadzania typu z w pełni zarządzanymi rozwiązaniami.

Po określeniu interfejsów publicznych, które można osadzać, należy utworzyć klasy środowiska uruchomieniowego, które implementują te interfejsy. Program kliencki może osadzić informacje o typie interfejsów w czasie projektowania, odwołując się do zestawu zawierającego interfejsy publiczne i ustawiając Embed Interop Types właściwość odwołania do True. Program kliencki może następnie załadować wystąpienia obiektów środowiska uruchomieniowego wpisanych jako te interfejsy. Jest to równoważne użyciu kompilatora wiersza polecenia i odwoływania się do zestawu przy użyciu opcji kompilatora EmbedInteropTypes.

Jeśli tworzysz nową wersję zestawu środowiska uruchomieniowego o silnej nazwie, program kliencki nie musi być ponownie skompilowany. Program kliencki nadal używa niezależnie od dostępnej wersji zestawu uruchomieniowego przy użyciu osadzonych informacji o typie dla interfejsów publicznych.

W tym przewodniku:

Utwórz zestaw o silnej nazwie za pomocą interfejsu publicznego zawierającego informacje o typie, które można osadzać.
Utwórz zestaw środowiska uruchomieniowego o silnej nazwie, który implementuje interfejs publiczny.
Utwórz program kliencki, który osadza informacje o typie z interfejsu publicznego i tworzy wystąpienie klasy z zestawu środowiska uruchomieniowego.
Zmodyfikuj i ponownie skompiluj zestaw środowiska uruchomieniowego.
Uruchom program kliencki, aby zobaczyć, że używa nowej wersji zestawu środowiska uruchomieniowego bez konieczności ponownego komilowania.

Uwaga

Na komputerze w poniższych instrukcjach mogą być wyświetlane inne nazwy i lokalizacje niektórych elementów interfejsu użytkownika programu Visual Studio. Te elementy są określane przez numer wersji Visual Studio oraz twoje ustawienia. Aby uzyskać więcej informacji, zobacz Personalizowanie środowiska IDE.

Warunki i ograniczenia

Informacje o typie można osadzić z zestawu w następujących warunkach:

Zestaw uwidacznia co najmniej jeden interfejs publiczny.
Osadzone interfejsy są oznaczone atrybutami ComImport i Guid atrybutami z unikatowymi identyfikatorami GUID.
Zestaw jest dodawać adnotacje do atrybutu ImportedFromTypeLib lub atrybutu PrimaryInteropAssembly oraz atrybutu na poziomie Guid zestawu. Szablony projektów Visual C# i Visual Basic domyślnie zawierają atrybut na poziomie Guid zestawu.

Ponieważ podstawową funkcją osadzania typu jest obsługa zestawów międzyoperacyjnych modelu COM, podczas osadzania informacji o typie w pełni zarządzanym rozwiązaniu obowiązują następujące ograniczenia:

Osadzone są tylko atrybuty specyficzne dla międzyoperacyjnego modelu COM. Inne atrybuty są ignorowane.
Jeśli typ używa parametrów ogólnych, a typ parametru ogólnego jest typem osadzonym, tego typu nie można używać przez granicę zestawu. Przykłady przekraczania granicy zestawu obejmują wywoływanie metody z innego zestawu lub wyprowadzanie typu z typu zdefiniowanego w innym zestawie.
Stałe nie są osadzone.
Klasa System.Collections.Generic.Dictionary<TKey,TValue> nie obsługuje typu osadzonego jako klucza. Możesz zaimplementować własny typ słownika, aby obsługiwać typ osadzony jako klucz.

Tworzenie interfejsu

Pierwszym krokiem jest utworzenie zestawu interfejsu równoważności typu.

W programie Visual Studio wybierz pozycję Plik>nowy>projekt.
W oknie dialogowym Tworzenie nowego projektu wpisz bibliotekę klas w polu Wyszukaj szablony . Wybierz szablon Biblioteki klas języka C# lub Visual Basic (.NET Framework) z listy, a następnie wybierz przycisk Dalej.
W oknie dialogowym Konfigurowanie nowego projektu w obszarze Nazwa projektu wpisz TypeEquivalenceInterface, a następnie wybierz pozycję Utwórz. Zostanie utworzony nowy projekt.
W Eksplorator rozwiązań kliknij prawym przyciskiem myszy plik Class1.cs lub Class1.vb, wybierz polecenie Zmień nazwę i zmień nazwę pliku z Class1 na ISampleInterface. Zareaguj tak na monit, aby zmienić nazwę klasy na ISampleInterface. Ta klasa reprezentuje interfejs publiczny dla klasy.
W Eksplorator rozwiązań kliknij prawym przyciskiem myszy projekt TypeEquivalenceInterface, a następnie wybierz polecenie Właściwości.
Wybierz pozycję Kompiluj w lewym okienku ekranu Właściwości i ustaw ścieżkę dane wyjściowe na lokalizację na komputerze, taką jak C:\TypeEquivalenceSample. Ta sama lokalizacja jest używana w tym przewodniku.
Wybierz pozycję Skompiluj>silne nazewnictwo w lewym okienku ekranu Właściwości , a następnie zaznacz pole wyboru Podpisz zestaw . W pliku klucza silnej nazwy wybierz pozycję Przeglądaj.
Przejdź do i wybierz plik key.snk utworzony w projekcie TypeEquivalenceInterface , a następnie wybierz przycisk OK. Aby uzyskać więcej informacji, zobacz Create a public-private key pair (Tworzenie pary kluczy publicznych i prywatnych).

Otwórz plik klasy ISampleInterface w edytorze kodu i zastąp jego zawartość następującym kodem, aby utworzyć ISampleInterface interfejs:

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

W menu Narzędzia wybierz pozycję Utwórz identyfikator GUID, a następnie w oknie dialogowym Tworzenie identyfikatora GUID wybierz pozycję Format rejestru. Wybierz pozycję Kopiuj, a następnie wybierz pozycję Zakończ.
W atrybucie Guid kodu zastąp przykładowy identyfikator GUID skopiowaną identyfikatorem GUID i usuń nawiasy klamrowe ({ }).
W Eksplorator rozwiązań rozwiń folder Properties i wybierz plik AssemblyInfo.cs lub AssemblyInfo.vb. W edytorze kodu dodaj następujący atrybut do pliku:
```
[assembly: ImportedFromTypeLib("")]
```
```
<Assembly: ImportedFromTypeLib("")>
```
Wybierz pozycję Plik >Zapisz wszystko lub naciśnij klawisze Ctrl+Shift+S, aby zapisać pliki i projekt.
W Eksplorator rozwiązań kliknij prawym przyciskiem myszy projekt TypeEquivalenceInterface i wybierz pozycję Kompilacja. Plik DLL biblioteki klas jest kompilowany i zapisywany w określonej ścieżce wyjściowej kompilacji, na przykład C:\TypeEquivalenceSample.

Tworzenie klasy środowiska uruchomieniowego

Następnie utwórz klasę środowiska uruchomieniowego równoważności typów.

W programie Visual Studio wybierz pozycję Plik>nowy>projekt.
W oknie dialogowym Tworzenie nowego projektu wpisz bibliotekę klas w polu Wyszukaj szablony . Wybierz szablon Biblioteki klas języka C# lub Visual Basic (.NET Framework) z listy, a następnie wybierz przycisk Dalej.
W oknie dialogowym Konfigurowanie nowego projektu w obszarze Nazwa projektu wpisz TypeEquivalenceRuntime, a następnie wybierz pozycję Utwórz. Zostanie utworzony nowy projekt.
W Eksplorator rozwiązań kliknij prawym przyciskiem myszy plik Class1.cs lub Class1.vb, wybierz polecenie Zmień nazwę i zmień nazwę pliku z Class1 na SampleClass. Zareaguj tak na monit, aby zmienić nazwę klasy na SampleClass. Ta klasa implementuje ISampleInterface interfejs.
W Eksplorator rozwiązań kliknij prawym przyciskiem myszy projekt TypeEquivalenceInterface i wybierz polecenie Właściwości.
Wybierz pozycję Kompiluj w lewym okienku ekranu Właściwości , a następnie ustaw ścieżkę dane wyjściowe na tę samą lokalizację, która została użyta dla projektu TypeEquivalenceInterface , na przykład C:\TypeEquivalenceSample.
Wybierz pozycję Skompiluj>silne nazewnictwo w lewym okienku ekranu Właściwości , a następnie zaznacz pole wyboru Podpisz zestaw . W pliku klucza silnej nazwy wybierz pozycję Przeglądaj.
Przejdź do i wybierz plik key.snk utworzony w projekcie TypeEquivalenceInterface , a następnie wybierz przycisk OK. Aby uzyskać więcej informacji, zobacz Create a public-private key pair (Tworzenie pary kluczy publicznych i prywatnych).
W Eksplorator rozwiązań kliknij prawym przyciskiem myszy projekt TypeEquivalenceRuntime i wybierz pozycję Dodaj>odwołanie.
W oknie dialogowym Menedżer odwołań wybierz pozycję Przeglądaj i przejdź do folderu ścieżki wyjściowej. Wybierz plik TypeEquivalenceInterface.dll , wybierz pozycję Dodaj, a następnie wybierz przycisk OK.
W Eksplorator rozwiązań rozwiń folder Odwołania i wybierz odwołanie TypeEquivalenceInterface. W okienku Właściwości ustaw wartość Określona wersja na Fałsz , jeśli jeszcze nie jest.

Otwórz plik klasy SampleClass w edytorze kodu i zastąp jego zawartość następującym kodem, aby utworzyć klasę 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

Wybierz pozycję Plik >Zapisz wszystko lub naciśnij klawisze Ctrl+Shift+S, aby zapisać pliki i projekt.
W Eksplorator rozwiązań kliknij prawym przyciskiem myszy projekt TypeEquivalenceRuntime i wybierz pozycję Kompilacja. Plik DLL biblioteki klas jest kompilowany i zapisywany w określonej ścieżce wyjściowej kompilacji.

Tworzenie projektu klienta

Na koniec utwórz program klienta równoważności typu, który odwołuje się do zestawu interfejsu.

W programie Visual Studio wybierz pozycję Plik>nowy>projekt.
W oknie dialogowym Tworzenie nowego projektu wpisz konsolę w polu Wyszukaj szablony . Wybierz szablon Aplikacji konsolowej języka C# lub Visual Basic (.NET Framework) z listy, a następnie wybierz przycisk Dalej.
W oknie dialogowym Konfigurowanie nowego projektu w obszarze Nazwa projektu wpisz TypeEquivalenceClient, a następnie wybierz pozycję Utwórz. Zostanie utworzony nowy projekt.
W Eksplorator rozwiązań kliknij prawym przyciskiem myszy projekt TypeEquivalenceClient i wybierz polecenie Właściwości.
Wybierz pozycję Kompiluj w lewym okienku ekranu Właściwości , a następnie ustaw ścieżkę dane wyjściowe na tę samą lokalizację, która została użyta dla projektu TypeEquivalenceInterface, na przykład C:\TypeEquivalenceSample.
W Eksplorator rozwiązań kliknij prawym przyciskiem myszy projekt TypeEquivalenceClient i wybierz pozycję Dodaj>odwołanie.
W oknie dialogowym Menedżer odwołań , jeśli plik TypeEquivalenceInterface.dll jest już wyświetlany, wybierz go. Jeśli nie, wybierz pozycję Przeglądaj, przejdź do folderu ścieżki wyjściowej, wybierz plik TypeEquivalenceInterface.dll (a nie TypeEquivalenceRuntime.dll), a następnie wybierz pozycję Dodaj. Wybierz przycisk OK.
W Eksplorator rozwiązań rozwiń folder Odwołania i wybierz odwołanie TypeEquivalenceInterface. W okienku Właściwości ustaw wartość Osadź typy międzyoperacyjnych na wartość True.

Otwórz plik Program.cs lub Module1.vb w edytorze kodu i zastąp jego zawartość następującym kodem, aby utworzyć program kliencki:

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

Wybierz pozycję Plik >Zapisz wszystko lub naciśnij klawisze Ctrl+Shift+S, aby zapisać pliki i projekt.
Naciśnij klawisze Ctrl+F5 , aby skompilować i uruchomić program. Zwróć uwagę, że dane wyjściowe konsoli zwracają zestaw w wersji 1.0.0.0.

Modyfikowanie interfejsu

Teraz zmodyfikuj zestaw interfejsu i zmień jego wersję.

W programie Visual Studio wybierz pozycję Plik>Otwórz>projekt/rozwiązanie i otwórz projekt TypeEquivalenceInterface .
W Eksplorator rozwiązań kliknij prawym przyciskiem myszy projekt TypeEquivalenceInterface i wybierz polecenie Właściwości.
Wybierz pozycję Aplikacja w lewym okienku ekranu Właściwości , a następnie wybierz pozycję Informacje o zestawie.
W oknie dialogowym Informacje o zestawie zmień wartości wersji zestawu i wersji pliku na 2.0.0.0, a następnie wybierz przycisk OK.
Otwórz plik SampleInterface.cs lub SampleInterface.vb i dodaj następujący wiersz kodu do interfejsu ISampleInterface :
```
DateTime GetDate();
```
```
Function GetDate() As Date
```
Wybierz pozycję Plik >Zapisz wszystko lub naciśnij klawisze Ctrl+Shift+S, aby zapisać pliki i projekt.
W Eksplorator rozwiązań kliknij prawym przyciskiem myszy projekt TypeEquivalenceInterface i wybierz pozycję Kompilacja. Nowa wersja pliku DLL biblioteki klas jest kompilowana i zapisywana w ścieżce wyjściowej kompilacji.

Modyfikowanie klasy środowiska uruchomieniowego

Zmodyfikuj również klasę środowiska uruchomieniowego i zaktualizuj jej wersję.

W programie Visual Studio wybierz pozycję Plik>Otwórz>projekt/rozwiązanie i otwórz projekt TypeEquivalenceRuntime .
W Eksplorator rozwiązań kliknij prawym przyciskiem myszy projekt TypeEquivalenceRuntime i wybierz polecenie Właściwości.
Wybierz pozycję Aplikacja w lewym okienku ekranu Właściwości , a następnie wybierz pozycję Informacje o zestawie.
W oknie dialogowym Informacje o zestawie zmień wartości wersji zestawu i wersji pliku na 2.0.0.0, a następnie wybierz przycisk OK.

Otwórz plik SampleClass.cs lub SampleClass.vb i dodaj następujący kod do SampleClass klasy:

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

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

Wybierz pozycję Plik >Zapisz wszystko lub naciśnij klawisze Ctrl+Shift+S, aby zapisać pliki i projekt.
W Eksplorator rozwiązań kliknij prawym przyciskiem myszy projekt TypeEquivalenceRuntime i wybierz pozycję Kompilacja. Nowa wersja pliku DLL biblioteki klas jest kompilowana i zapisywana w ścieżce wyjściowej kompilacji.

Uruchamianie zaktualizowanego programu klienckiego

Przejdź do lokalizacji folderu danych wyjściowych kompilacji i uruchom polecenieTypeEquivalenceClient.exe. Pamiętaj, że dane wyjściowe konsoli odzwierciedlają teraz nową wersję TypeEquivalenceRuntime zestawu , 2.0.0.0, bez ponownego skompilowania programu.