Resolver carregamentos de assembly

Artigo
05/10/2023

O .NET fornece o evento AppDomain.AssemblyResolve para aplicativos que exigem maior controle sobre o carregamento do assembly. Ao tratar esse evento, seu aplicativo pode carregar um assembly no contexto de carga de fora dos caminhos normais de investigação, selecionar qual das várias versões de assembly carregar, emitir um assembly dinâmico e retorná-lo, etc. Este tópico fornece orientação para a manipulação do evento AssemblyResolve.

Observação

Para resolver carregamentos de assembly no contexto de somente reflexão, use o evento AppDomain.ReflectionOnlyAssemblyResolve em vez disso.

Como o evento AssemblyResolve funciona

Quando você registra um manipulador para o evento AssemblyResolve, o manipulador é invocado sempre que o runtime falha ao se associar a um assembly por nome. Por exemplo, chamar os seguintes métodos usando o código do usuário pode fazer com que o evento AssemblyResolve seja gerado:

Uma sobrecarga de método AppDomain.Load ou uma sobrecarga de método Assembly.Load cujo primeiro argumento é uma cadeia de caracteres que representa o nome de exibição do assembly a ser carregado (ou seja, a cadeia de caracteres retornada pela propriedade Assembly.FullName).
Uma sobrecarga de método AppDomain.Load ou uma sobrecarga de método Assembly.Load cujo primeiro argumento é um objeto AssemblyName que identifica o assembly a ser carregado.
Uma sobrecarga de método Assembly.LoadWithPartialName.
Uma sobrecarga de método AppDomain.CreateInstance ou AppDomain.CreateInstanceAndUnwrap que cria uma instância de um objeto em outro domínio de aplicativo.

O que o manipulador de eventos faz

O manipulador do evento AssemblyResolve recebe o nome de exibição do assembly a ser carregado na propriedade ResolveEventArgs.Name. Se o manipulador não reconhecer o nome do assembly, ele retornará null (C#), Nothing (Visual Basic) ou nullptr (Visual C++).

Se o manipulador reconhecer o nome do assembly, ele poderá carregar e retornar um assembly que atende à solicitação. A lista a seguir descreve alguns cenários de exemplo.

Se o manipulador conhecer o local de uma versão do assembly, ele poderá carregar o assembly usando o método Assembly.LoadFrom ou Assembly.LoadFile e poderá retornar o assembly carregado se tiver êxito.
Se o manipulador tiver acesso a um banco de dados de assemblies armazenados como matrizes de bytes, ele poderá carregar uma matriz de bytes usando uma das sobrecargas do método Assembly.Load que usa uma matriz de bytes.
O manipulador pode gerar um assembly dinâmico e retorná-lo.

Observação

O manipulador deve carregar o assembly no contexto de carregamento, no contexto de carga ou sem contexto. Se o manipulador carregar o assembly no contexto de somente reflexão usando o método Assembly.ReflectionOnlyLoad ou o Assembly.ReflectionOnlyLoadFrom, a tentativa de carregamento que gerou o evento AssemblyResolve falhará.

É responsabilidade do manipulador de eventos retornar um assembly adequado. O manipulador pode analisar o nome de exibição do assembly solicitado passando o valor da propriedade ResolveEventArgs.Name para o construtor AssemblyName(String). A partir do .NET Framework 4, o manipulador pode usar a propriedade ResolveEventArgs.RequestingAssembly para determinar se a solicitação atual é uma dependência de outro assembly. Essas informações podem ajudar a identificar um assembly que atenderá à dependência.

O manipulador de eventos pode retornar uma versão diferente do assembly do que a versão que foi solicitada.

Na maioria dos casos, o assembly que é retornado pelo manipulador aparece no contexto de carga, independentemente do contexto em que o manipulador o carrega. Por exemplo, se o manipulador usar o método Assembly.LoadFrom para carregar um assembly no contexto de origem de carga, o assembly aparecerá no contexto de carga quando o manipulador o retornar. No entanto, no seguinte caso, o assembly aparece sem contexto quando o manipulador o retorna:

O manipulador carrega um assembly sem contexto.
A propriedade ResolveEventArgs.RequestingAssembly não é nula.
O assembly solicitante (ou seja, o assembly que é retornado pela propriedade ResolveEventArgs.RequestingAssembly) foi carregado sem contexto.

Para obter informações sobre os contextos, consulte a sobrecarga de método Assembly.LoadFrom(String).

Várias versões do mesmo assembly podem ser carregadas no mesmo domínio do aplicativo. Essa prática não é recomendada, pois ela pode levar a problemas de atribuição de tipo. Confira Práticas recomendadas para carregamento de assembly.

O que o manipulador de eventos não deve fazer

A regra principal para tratamento do evento AssemblyResolve é que você não deve tentar retornar um assembly que não reconhece. Ao escrever o manipulador, você deve saber quais assemblies podem fazer com que o evento seja acionado. O manipulador deve retornar nulo para outros assemblies.

Importante

Começando com o .NET Framework 4, o evento AssemblyResolve é gerado para assemblies satélite. Essa alteração afeta um manipulador de eventos que foi escrito para uma versão anterior do .NET Framework, se o manipulador tenta resolver todas as solicitações de carga do assembly. Os manipuladores de eventos que ignoram assemblies que eles não reconhecem não são afetados por essa alteração: eles retornam null, e os mecanismos normais de fallback são seguidos.

Ao carregar um assembly, o manipulador de eventos não deve usar nenhuma das sobrecargas de método AppDomain.Load ou Assembly.Load que possam fazer com que o evento AssemblyResolve seja gerado recursivamente, pois isso poderia levar a um excedente de pilha. (Confira a lista fornecida anteriormente neste tópico.) Isso acontece mesmo se você fornecer tratamento de exceções para a solicitação de carga, pois nenhuma exceção será gerada até que todos os manipuladores de eventos tenham retornado. Desse modo, o seguinte código resultará em um excedente de pilha se MyAssembly não for encontrado:

using System;
using System.Reflection;

class BadExample
{
    static void Main()
    {
        AppDomain ad = AppDomain.CreateDomain("Test");
        ad.AssemblyResolve += MyHandler;

        try
        {
            object obj = ad.CreateInstanceAndUnwrap(
                "MyAssembly, version=1.2.3.4, culture=neutral, publicKeyToken=null",
                "MyType");
        }
        catch (Exception ex)
        {
            Console.WriteLine(ex.Message);
        }
    }

    static Assembly MyHandler(object source, ResolveEventArgs e)
    {
        Console.WriteLine("Resolving {0}", e.Name);
        // DO NOT DO THIS: This causes a StackOverflowException
        return Assembly.Load(e.Name);
    }
}

/* This example produces output similar to the following:

Resolving MyAssembly, Version=1.2.3.4, Culture=neutral, PublicKeyToken=null
Resolving MyAssembly, Version=1.2.3.4, Culture=neutral, PublicKeyToken=null
...
Resolving MyAssembly, Version=1.2.3.4, Culture=neutral, PublicKeyToken=null
Resolving MyAssembly, Version=1.2.3.4, Culture=neutral, PublicKeyToken=null

Process is terminated due to StackOverflowException.
 */

Imports System.Reflection

Class BadExample

    Shared Sub Main()

        Dim ad As AppDomain = AppDomain.CreateDomain("Test")
        AddHandler ad.AssemblyResolve, AddressOf MyHandler

        Try
            Dim obj As object = ad.CreateInstanceAndUnwrap(
                "MyAssembly, version=1.2.3.4, culture=neutral, publicKeyToken=null",
                "MyType")
        Catch ex As Exception
            Console.WriteLine(ex.Message)
        End Try
    End Sub

    Shared Function MyHandler(ByVal source As Object, _
                              ByVal e As ResolveEventArgs) As Assembly
        Console.WriteLine("Resolving {0}", e.Name)
        // DO NOT DO THIS: This causes a StackOverflowException
        Return Assembly.Load(e.Name)
    End Function
End Class

' This example produces output similar to the following:
'
'Resolving MyAssembly, Version=1.2.3.4, Culture=neutral, PublicKeyToken=null
'Resolving MyAssembly, Version=1.2.3.4, Culture=neutral, PublicKeyToken=null
'...
'Resolving MyAssembly, Version=1.2.3.4, Culture=neutral, PublicKeyToken=null
'Resolving MyAssembly, Version=1.2.3.4, Culture=neutral, PublicKeyToken=null
'
'Process is terminated due to StackOverflowException.

using namespace System;
using namespace System::Reflection;

ref class Example
{
internal:
    static Assembly^ MyHandler(Object^ source, ResolveEventArgs^ e)
    {
        Console::WriteLine("Resolving {0}", e->Name);
        // DO NOT DO THIS: This causes a StackOverflowException
        return Assembly::Load(e->Name);
    }
};

void main()
{
    AppDomain^ ad = AppDomain::CreateDomain("Test");
    ad->AssemblyResolve += gcnew ResolveEventHandler(&Example::MyHandler);

    try
    {
        Object^ obj = ad->CreateInstanceAndUnwrap(
            "MyAssembly, version=1.2.3.4, culture=neutral, publicKeyToken=null",
            "MyType");
    }
    catch (Exception^ ex)
    {
        Console::WriteLine(ex->Message);
    }
}

/* This example produces output similar to the following:

Resolving MyAssembly, Version=1.2.3.4, Culture=neutral, PublicKeyToken=null
Resolving MyAssembly, Version=1.2.3.4, Culture=neutral, PublicKeyToken=null
...
Resolving MyAssembly, Version=1.2.3.4, Culture=neutral, PublicKeyToken=null
Resolving MyAssembly, Version=1.2.3.4, Culture=neutral, PublicKeyToken=null

Process is terminated due to StackOverflowException.
*/

A maneira correta de lidar com AssemblyResolve

Ao resolver assemblies do manipulador de eventos AssemblyResolve, um StackOverflowException eventualmente será gerado se o manipulador usar as chamadas do método Assembly.Load ou AppDomain.Load. Em vez disso, use métodos LoadFile ou LoadFrom, pois eles não geram o evento AssemblyResolve.

Imagine que MyAssembly.dll esteja localizado próximo ao assembly em execução, em um local conhecido; ele pode ser resolvido usando Assembly.LoadFile dado o caminho para o assembly.

using System;
using System.IO;
using System.Reflection;

class CorrectExample
{
    static void Main()
    {
        AppDomain ad = AppDomain.CreateDomain("Test");
        ad.AssemblyResolve += MyHandler;

        try
        {
            object obj = ad.CreateInstanceAndUnwrap(
                "MyAssembly, version=1.2.3.4, culture=neutral, publicKeyToken=null",
                "MyType");
        }
        catch (Exception ex)
        {
            Console.WriteLine(ex.Message);
        }
    }

    static Assembly MyHandler(object source, ResolveEventArgs e)
    {
        Console.WriteLine("Resolving {0}", e.Name);

        var path = Path.GetFullPath("../../MyAssembly.dll");
        return Assembly.LoadFile(path);
     }
}

Imports System.IO
Imports System.Reflection

Class CorrectExample

    Shared Sub Main()

        Dim ad As AppDomain = AppDomain.CreateDomain("Test")
        AddHandler ad.AssemblyResolve, AddressOf MyHandler

        Try
            Dim obj As Object = ad.CreateInstanceAndUnwrap(
                "MyAssembly, version=1.2.3.4, culture=neutral, publicKeyToken=null",
                "MyType")
        Catch ex As Exception
            Console.WriteLine(ex.Message)
        End Try
    End Sub

    Shared Function MyHandler(ByVal source As Object,
                              ByVal e As ResolveEventArgs) As Assembly
        Console.WriteLine("Resolving {0}", e.Name)

        Dim fullPath = Path.GetFullPath("../../MyAssembly.dll")
        Return Assembly.LoadFile(fullPath)
    End Function
End Class

using namespace System;
using namespace System::IO;
using namespace System::Reflection;

ref class Example
{
internal:
    static Assembly^ MyHandler(Object^ source, ResolveEventArgs^ e)
    {
        Console::WriteLine("Resolving {0}", e->Name);

        String^ fullPath = Path::GetFullPath("../../MyAssembly.dll");
        return Assembly::LoadFile(fullPath);
    }
};

void main()
{
    AppDomain^ ad = AppDomain::CreateDomain("Test");
    ad->AssemblyResolve += gcnew ResolveEventHandler(&Example::MyHandler);

    try
    {
        Object^ obj = ad->CreateInstanceAndUnwrap(
            "MyAssembly, version=1.2.3.4, culture=neutral, publicKeyToken=null",
            "MyType");
    }
    catch (Exception^ ex)
    {
        Console::WriteLine(ex->Message);
    }
}

Compartilhar via

Resolver carregamentos de assembly

Como o evento AssemblyResolve funciona

O que o manipulador de eventos faz

O que o manipulador de eventos não deve fazer

A maneira correta de lidar com AssemblyResolve

Confira também

Recursos adicionais