Instruções: Incorporar tipos de assemblagens geridas no Visual Studio

Artigo
04/11/2023

Se incorporar informações de uma assemblagem gerida com um nome forte, pode acoplar vagamente tipos numa aplicação para alcançar a independência da versão. Ou seja, o programa pode ser escrito para utilizar tipos de qualquer versão de uma biblioteca gerida sem ter de ser recompilado para cada nova versão.

A incorporação de tipos é frequentemente utilizada com a interoperabilidade COM, como uma aplicação que utiliza objetos de automatização do Microsoft Office. As informações do tipo de incorporação permitem que a mesma compilação de um programa funcione com versões diferentes do Microsoft Office em computadores diferentes. No entanto, também pode utilizar a incorporação de tipos com soluções totalmente geridas.

Depois de especificar as interfaces públicas que podem ser incorporadas, cria classes de runtime que implementam essas interfaces. Um programa cliente pode incorporar as informações de tipo para as interfaces no momento da conceção ao referenciar a assemblagem que contém as interfaces públicas e definir a Embed Interop Types propriedade da referência para True. Em seguida, o programa cliente pode carregar instâncias dos objetos de runtime escritos como essas interfaces. Isto é equivalente à utilização do compilador da linha de comandos e à referência da assemblagem através da opção compilador EmbedInteropTypes.

Se criar uma nova versão da sua assemblagem de runtime com o nome forte, o programa cliente não tem de ser recompilado. O programa cliente continua a utilizar a versão da assemblagem de runtime que estiver disponível para o mesmo, utilizando as informações de tipo incorporado para as interfaces públicas.

Nestas instruções, irá:

Crie uma assemblagem com um nome forte com uma interface pública que contenha informações de tipo que podem ser incorporadas.
Crie uma assemblagem de runtime com um nome forte que implemente a interface pública.
Crie um programa cliente que incorpore as informações do tipo a partir da interface pública e crie uma instância da classe a partir da assemblagem de runtime.
Modifique e recrie a assemblagem do runtime.
Execute o programa cliente para ver que utiliza a nova versão da assemblagem de runtime sem ter de ser recompilada.

Nota

O computador pode mostrar nomes ou localizações diferentes para alguns dos elementos da interface de utilizador do Visual Studio nas seguintes instruções. A edição do Visual Studio que tem e as definições que utiliza determinam estes elementos. Para obter mais informações, veja Personalizar o IDE.

Condições e limitações

Pode incorporar informações de tipo de uma assemblagem nas seguintes condições:

A assemblagem expõe pelo menos uma interface pública.
As interfaces incorporadas são anotadas com ComImport atributos e Guid atributos com GUIDs exclusivos.
A assemblagem é anotada com o ImportedFromTypeLib atributo ou o PrimaryInteropAssembly atributo e um atributo ao nível Guid da assemblagem. Os modelos de projeto visual C# e Visual Basic incluem um atributo ao nível Guid da assemblagem por predefinição.

Uma vez que a função principal da incorporação do tipo é suportar assemblagens interop COM, aplicam-se as seguintes limitações quando incorpora informações de tipo numa solução totalmente gerida:

Apenas os atributos específicos da interoperabilidade COM são incorporados. Outros atributos são ignorados.
Se um tipo utilizar parâmetros genéricos e o tipo do parâmetro genérico for um tipo incorporado, esse tipo não pode ser utilizado através de um limite de assemblagem. Exemplos de cruzamento de um limite de assemblagem incluem chamar um método de outra assemblagem ou derivar um tipo de um tipo definido noutra assemblagem.
As constantes não estão incorporadas.
A System.Collections.Generic.Dictionary<TKey,TValue> classe não suporta um tipo incorporado como chave. Pode implementar o seu próprio tipo de dicionário para suportar um tipo incorporado como chave.

Criar uma interface

O primeiro passo é criar a assemblagem da interface de equivalência de tipo.

No Visual Studio, selecione Ficheiro>Novo>Projeto.
Na caixa de diálogo Criar um novo projeto , escreva biblioteca de classes na caixa Procurar modelos . Selecione o modelo C# ou Visual Basic Class Library (.NET Framework) na lista e, em seguida, selecione Seguinte.
Na caixa de diálogo Configurar o novo projeto , em Nome do projeto, escreva TypeEquivalenceInterface e, em seguida, selecione Criar. O novo projeto é criado.
No Explorador de Soluções, clique com o botão direito do rato no ficheiro Class1.cs ou Class1.vb, selecione Mudar o Nome e mude o nome do ficheiro de Classe1 para ISampleInterface. Responda Sim ao pedido para também mudar o nome da classe para ISampleInterface. Esta classe representa a interface pública da classe .
No Explorador de Soluções, clique com o botão direito do rato no projeto TypeEquivalenceInterface e, em seguida, selecione Propriedades.
Selecione Compilar no painel esquerdo do ecrã Propriedades e defina o caminho saída para uma localização no seu computador, como C:\TypeEquivalenceSample. Irá utilizar a mesma localização ao longo destas instruções.
Selecione Criar>Nomenclatura Forte no painel esquerdo do ecrã Propriedades e, em seguida, selecione a caixa de verificação Assinar a assemblagem . No ficheiro de chave de nome Forte, selecione Procurar.
Navegue para e selecione o ficheiro key.snk que criou no projeto TypeEquivalenceInterface e, em seguida, selecione OK. Para obter mais informações, consulte Criar um par de chaves público-privado.

Abra o ficheiro de classe ISampleInterface no editor de código e substitua os respetivos conteúdos pelo seguinte código para criar a ISampleInterface interface:

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

No menu Ferramentas , selecione Criar Guid e, na caixa de diálogo Criar GUID , selecione Formato do Registo. Selecione Copiar e, em seguida, selecione Sair.
Guid No atributo do seu código, substitua o GUID de exemplo pelo GUID que copiou e remova as chavetas ({ }).
No Explorador de Soluções, expanda a pasta Propriedades e selecione o ficheiro AssemblyInfo.cs ou AssemblyInfo.vb. No editor de código, adicione o seguinte atributo ao ficheiro:
```
[assembly: ImportedFromTypeLib("")]
```
```
<Assembly: ImportedFromTypeLib("")>
```
SelecioneGuardar Todos os Ficheiros> ou prima Ctrl+Shift+S para guardar os ficheiros e o projeto.
No Explorador de Soluções, clique com o botão direito do rato no projeto TypeEquivalenceInterface e selecione Compilar. O ficheiro DLL da biblioteca de classes é compilado e guardado no caminho de saída da compilação especificado, por exemplo C:\TypeEquivalenceSample.

Criar uma classe de runtime

Em seguida, crie a classe de runtime de equivalência de tipo.

No Visual Studio, selecione Ficheiro>Novo>Projeto.
Na caixa de diálogo Criar um novo projeto , escreva biblioteca de classes na caixa Procurar modelos . Selecione o modelo C# ou Visual Basic Class Library (.NET Framework) na lista e, em seguida, selecione Seguinte.
Na caixa de diálogo Configurar o novo projeto , em Nome do projeto, escreva TypeEquivalenceRuntime e, em seguida, selecione Criar. O novo projeto é criado.
No Explorador de Soluções, clique com o botão direito do rato no ficheiro Class1.cs ou Class1.vb, selecione Mudar o Nome e mude o nome do ficheiro de Classe1 para SampleClass. Responda Sim ao pedido para também mudar o nome da classe para SampleClass. Esta classe implementa a ISampleInterface interface.
No Explorador de Soluções, clique com o botão direito do rato no projeto TypeEquivalenceInterface e selecione Propriedades.
Selecione Compilar no painel esquerdo do ecrã Propriedades e, em seguida, defina o caminho Saída para a mesma localização que utilizou para o projeto TypeEquivalenceInterface , por exemplo C:\TypeEquivalenceSample.
Selecione Criar>Nomenclatura Forte no painel esquerdo do ecrã Propriedades e, em seguida, selecione a caixa de verificação Assinar a assemblagem . No ficheiro de chave de nome Forte, selecione Procurar.
Navegue para e selecione o ficheiro key.snk que criou no projeto TypeEquivalenceInterface e, em seguida, selecione OK. Para obter mais informações, consulte Criar um par de chaves público-privado.
No Explorador de Soluções, clique com o botão direito do rato no projeto TypeEquivalenceRuntime e selecione Adicionar>Referência.
Na caixa de diálogo Gestor de Referência , selecione Procurar e navegue para a pasta de caminho de saída. Selecione o ficheiro TypeEquivalenceInterface.dll , selecione Adicionar e, em seguida, selecione OK.
Em Explorador de Soluções, expanda a pasta Referências e selecione a referência TypeEquivalenceInterface. No painel Propriedades , defina Versão Específica como Falsa se ainda não estiver.

Abra o ficheiro de classe SampleClass no editor de código e substitua os respetivos conteúdos pelo seguinte código para criar a SampleClass classe:

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

SelecioneGuardar Todos os Ficheiros> ou prima Ctrl+Shift+S para guardar os ficheiros e o projeto.
No Explorador de Soluções, clique com o botão direito do rato no projeto TypeEquivalenceRuntime e selecione Compilar. O ficheiro DLL da biblioteca de classes é compilado e guardado no caminho de saída da compilação especificado.

Criar um projeto de cliente

Por fim, crie um programa de cliente de equivalência de tipo que faça referência à assemblagem da interface.

No Visual Studio, selecione Ficheiro>Novo>Projeto.
Na caixa de diálogo Criar um novo projeto , escreva consola na caixa Procurar modelos . Selecione o modelo C# ou Visual Basic Console App (.NET Framework) na lista e, em seguida, selecione Seguinte.
Na caixa de diálogo Configurar o novo projeto , em Nome do projeto, escreva TypeEquivalenceClient e, em seguida, selecione Criar. O novo projeto é criado.
No Explorador de Soluções, clique com o botão direito do rato no projeto TypeEquivalenceClient e selecione Propriedades.
Selecione Compilar no painel esquerdo do ecrã Propriedades e, em seguida, defina o caminho Saída para a mesma localização que utilizou para o projeto TypeEquivalenceInterface, por exemplo C:\TypeEquivalenceSample.
No Explorador de Soluções, clique com o botão direito do rato no projeto TypeEquivalenceClient e selecione Adicionar>Referência.
Na caixa de diálogo Gestor de Referências , se o ficheiro TypeEquivalenceInterface.dll já estiver listado, selecione-o. Caso contrário, selecione Procurar, navegue para a pasta de caminho de saída, selecione o ficheiro deTypeEquivalenceInterface.dll (não o TypeEquivalenceRuntime.dll) e selecione Adicionar. Selecione OK.
Em Explorador de Soluções, expanda a pasta Referências e selecione a referência TypeEquivalenceInterface. No painel Propriedades , defina Incorporar Tipos de Interoperabilidade como Verdadeiro.

Abra o ficheiro Program.cs ou Module1.vb no editor de código e substitua os respetivos conteúdos pelo seguinte código para criar o programa cliente:

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

SelecioneGuardar Todos os Ficheiros> ou prima Ctrl+Shift+S para guardar os ficheiros e o projeto.
Prima Ctrl+F5 para compilar e executar o programa. Tenha em atenção que o resultado da consola devolve a versão de assemblagem 1.0.0.0.

Modificar a interface

Agora, modifique a assemblagem da interface e altere a respetiva versão.

No Visual Studio, selecione Ficheiro>Abrir>Projeto/Solução e abra o projeto TypeEquivalenceInterface .
No Explorador de Soluções, clique com o botão direito do rato no projeto TypeEquivalenceInterface e selecione Propriedades.
Selecione Aplicação no painel esquerdo do ecrã Propriedades e, em seguida, selecione Informações de Assemblagem.
Na caixa de diálogo Informações de Assemblagem , altere os valores versão da Assemblagem e Versão do ficheiro para 2.0.0.0 e, em seguida, selecione OK.
Abra o ficheiro SampleInterface.cs ou SampleInterface.vb e adicione a seguinte linha de código à ISampleInterface interface:
```
DateTime GetDate();
```
```
Function GetDate() As Date
```
SelecioneGuardar Todos os Ficheiros> ou prima Ctrl+Shift+S para guardar os ficheiros e o projeto.
No Explorador de Soluções, clique com o botão direito do rato no projeto TypeEquivalenceInterface e selecione Compilar. Uma nova versão do ficheiro DLL da biblioteca de classes é compilada e guardada no caminho de saída da compilação.

Modificar a classe runtime

Modifique também a classe runtime e atualize a respetiva versão.

No Visual Studio, selecione Ficheiro>Abrir>Projeto/Solução e abra o projeto TypeEquivalenceRuntime .
No Explorador de Soluções, clique com o botão direito do rato no projeto TypeEquivalenceRuntime e selecione Propriedades.
Selecione Aplicação no painel esquerdo do ecrã Propriedades e, em seguida, selecione Informações de Assemblagem.
Na caixa de diálogo Informações de Assemblagem , altere os valores versão da Assemblagem e Versão do ficheiro para 2.0.0.0 e, em seguida, selecione OK.

Abra o ficheiro SampleClass.cs ou SampleClass.vb e adicione o seguinte código à SampleClass classe :

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

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

SelecioneGuardar Todos os Ficheiros> ou prima Ctrl+Shift+S para guardar os ficheiros e o projeto.
No Explorador de Soluções, clique com o botão direito do rato no projeto TypeEquivalenceRuntime e selecione Compilar. Uma nova versão do ficheiro DLL da biblioteca de classes é compilada e guardada no caminho de saída da compilação.

Executar o programa cliente atualizado

Aceda à localização da pasta de saída da compilação e execute TypeEquivalenceClient.exe. Tenha em atenção que o resultado da consola reflete agora a nova versão da TypeEquivalenceRuntime assemblagem, 2.0.0.0, sem que o programa seja recompilado.

Partilhar via