Realizando marshaling de interoperabilidadeInterop Marshaling

O marshaling de interoperabilidade rege como os dados são passados em argumentos de método e valores de retorno entre memória gerenciada e não gerenciada durante chamadas.Interop marshaling governs how data is passed in method arguments and return values between managed and unmanaged memory during calls. O marshaling de interoperabilidade é uma atividade de tempo de execução executada pelo serviço de marshaling do Common Language Runtime.Interop marshaling is a run-time activity performed by the common language runtime's marshaling service.

A maioria dos tipos de dados têm representações comuns tanto na memória gerenciada quanto na não gerenciada.Most data types have common representations in both managed and unmanaged memory. O marshaler de interoperabilidade manipula esses tipos para você.The interop marshaler handles these types for you. Outros tipos podem ser ambíguos ou não representados em absoluto na memória gerenciada.Other types can be ambiguous or not represented at all in managed memory.

Um tipo ambíguo pode ter várias representações não gerenciadas que são mapeadas para um único tipo gerenciado ou ter informações de tipo ausentes, tais como o tamanho de uma matriz.An ambiguous type can have either multiple unmanaged representations that map to a single managed type, or missing type information, such as the size of an array. Para tipos ambíguos, o marshaler fornece uma representação padrão e representações alternativas em que existem várias representações.For ambiguous types, the marshaler provides a default representation and alternative representations where multiple representations exist. Você pode fornecer instruções explícitas para o marshaler sobre como ele deve realizar marshaling de um tipo ambíguo.You can supply explicit instructions to the marshaler on how it is to marshal an ambiguous type.

Invocação de plataforma e modelos de interoperabilidade COMPlatform Invoke and COM Interop Models

O common language runtime fornece dois mecanismos para interoperação com código não gerenciado:The common language runtime provides two mechanisms for interoperating with unmanaged code:

  • Invocação de plataforma, que permite que o código gerenciado chame funções exportadas de uma biblioteca não gerenciada.Platform invoke, which enables managed code to call functions exported from an unmanaged library.
  • Interoperabilidade COM, que permite que o código gerenciado interaja com objetos COM (Component Object Model) por meio de interfaces.COM interop, which enables managed code to interact with Component Object Model (COM) objects through interfaces.

Tanto a invocação de plataforma quanto a interoperabilidade COM usam marshaling de interoperabilidade para mover com precisão os argumentos de método entre o chamador e o receptor e vice-versa, se necessário.Both platform invoke and COM interop use interop marshaling to accurately move method arguments between caller and callee and back, if required. Conforme mostra a ilustração a seguir, uma chamada de método de invocação de plataforma flui do código gerenciado para código não gerenciado e nunca na direção contrária, exceto quando funções de retorno de chamada estão envolvidas.As the following illustration shows, a platform invoke method call flows from managed to unmanaged code and never the other way, except when callback functions are involved. Embora as chamadas de invocação de plataforma possam fluir somente de código gerenciado para código não gerenciado, os dados podem fluir em ambas as direções como parâmetros de entrada ou de saída.Even though platform invoke calls can flow only from managed to unmanaged code, data can flow in both directions as input or output parameters. As chamadas de método de interoperabilidade COM podem fluir em ambas as direções.COM interop method calls can flow in either direction.

Invocação de plataformaPlatform invoke

No nível mais baixo, ambos os mecanismos usam o mesmo serviço de marshaling de interoperabilidade; no entanto, alguns tipos de dados têm suporte apenas pela interoperabilidade COM ou pela invocação de plataforma.At the lowest level, both mechanisms use the same interop marshaling service; however, certain data types are supported exclusively by COM interop or platform invoke. Para obter detalhes, consulte Comportamento de marshaling padrão.For details, see Default Marshaling Behavior.

Marshaling e apartments COMMarshaling and COM Apartments

O marshaler de interoperabilidade realiza marshaling de dados entre o heap do Common Language Runtime e o heap não gerenciado.The interop marshaler marshals data between the common language runtime heap and the unmanaged heap. O marshaling ocorre sempre que o chamador e o receptor não podem operar na mesma instância dos dados.Marshaling occurs whenever the caller and callee cannot operate on the same instance of data. O marshaler de interoperabilidade torna possível que o chamador e o receptor pareçam estar funcionando nos mesmos dados, mesmo que eles tenham sua própria cópia dos dados.The interop marshaler makes it possible for the caller and callee to appear to be operating on the same data even if they have their own copy of the data.

O COM também tem um marshaler que realiza marshaling de dados entre apartments COM ou processos COM diferentes.COM also has a marshaler that marshals data between COM apartments or different COM processes. Ao chamar entre código gerenciado e código não gerenciado dentro do mesmo apartment COM, o marshaler de interoperabilidade é o único marshaler envolvido.When calling between managed and unmanaged code within the same COM apartment, the interop marshaler is the only marshaler involved. Ao chamar entre código gerenciado e o código não gerenciado em um apartment COM diferente ou um processo diferente, tanto o marshaler de interoperabilidade quanto o marshaler COM estão envolvidos.When calling between managed code and unmanaged code in a different COM apartment or a different process, both the interop marshaler and the COM marshaler are involved.

Clientes COM e servidores gerenciadosCOM Clients and Managed Servers

Um servidor gerenciado exportado com uma biblioteca de tipos registrada pelo Regasm.exe (Ferramenta de Registro de Assembly) tem uma ThreadingModel entrada do Registro definida como Both.An exported managed server with a type library registered by the Regasm.exe (Assembly Registration Tool) has a ThreadingModel registry entry set to Both. Esse valor indica que o servidor pode ser ativado em um STA (Single-Threaded Apartment) ou um MTA (Multi-Threaded Apartment).This value indicates that the server can be activated in a single-threaded apartment (STA) or a multithreaded apartment (MTA). O objeto Server é criado no mesmo apartamento que seu chamador, conforme mostrado na tabela a seguir:The server object is created in the same apartment as its caller, as shown in the following table:

Cliente COMCOM client .NET Server.NET server Requisitos de marshalingMarshaling requirements
STASTA Both se torna isso STA.Both becomes STA. Marshaling no mesmo apartment.Same-apartment marshaling.
MTAMTA Both se torna MTA.Both becomes MTA. Marshaling no mesmo apartment.Same-apartment marshaling.

Já que o cliente e o servidor estão no mesmo apartment, o serviço de marshaling de interoperabilidade manipula automaticamente todo o marshaling de dados.Because the client and server are in the same apartment, the interop marshaling service automatically handles all data marshaling. A ilustração a seguir mostra o serviço de marshaling de interoperabilidade funcionando entre heaps gerenciados e não gerenciados dentro do mesmo apartment de estilo COM.The following illustration shows the interop marshaling service operating between managed and unmanaged heaps within the same COM-style apartment.

Marshaling de interoperabilidade entre heaps gerenciados e não gerenciadosInterop marshaling between managed and unmanaged heaps

Se você planeja exportar um servidor gerenciado, lembre-se de que o cliente COM determina o apartment do servidor.If you plan to export a managed server, be aware that the COM client determines the apartment of the server. Um servidor gerenciado chamado por um cliente COM inicializado em um MTA deve assegurar acesso thread-safe.A managed server called by a COM client initialized in an MTA must ensure thread safety.

Clientes gerenciados e servidores COMManaged Clients and COM Servers

A configuração padrão para apartments de cliente gerenciado é MTA; no entanto, o tipo de aplicativo do cliente .NET pode alterar a configuração padrão.The default setting for managed client apartments is MTA; however, the application type of the .NET client can change the default setting. Por exemplo, a configuração de apartment de um cliente do Visual Basic é STA.For example, a Visual Basic client apartment setting is STA. Você pode usar uma das propriedades System.STAThreadAttribute, System.MTAThreadAttribute, Thread.ApartmentState ou Page.AspCompatMode para examinar e alterar a configuração de apartment de um cliente gerenciado.You can use the System.STAThreadAttribute, the System.MTAThreadAttribute, the Thread.ApartmentState property, or the Page.AspCompatMode property to examine and change the apartment setting of a managed client.

O autor do componente define a afinidade do thread de um servidor COM.The author of the component sets the thread affinity of a COM server. A tabela a seguir mostra as combinações de configurações de apartment de clientes .NET e servidores COM.The following table shows the combinations of apartment settings for .NET clients and COM servers. Ele também mostra os requisitos de marshaling resultantes para as combinações.It also shows the resulting marshaling requirements for the combinations.

Cliente .NET.NET client Servidor COMCOM server Requisitos de marshalingMarshaling requirements
MTA (padrão)MTA (default) MTAMTA

STASTA
Marshaling de interoperabilidade.Interop marshaling.

Marshaling COM e de interoperabilidade.Interop and COM marshaling.
STASTA MTAMTA

STASTA
Marshaling COM e de interoperabilidade.Interop and COM marshaling.

Marshaling de interoperabilidade.Interop marshaling.

Quando um cliente gerenciado e servidor não gerenciado estão no mesmo apartment, o serviço de marshaling de interoperabilidade manipula todo o marshaling de dados.When a managed client and unmanaged server are in the same apartment, the interop marshaling service handles all data marshaling. No entanto, quando o cliente e servidor são inicializados em apartments diferentes, o marshaling de COM também é necessário.However, when client and server are initialized in different apartments, COM marshaling is also required. A ilustração a seguir mostra os elementos de uma chamada entre apartamento:The following illustration shows the elements of a cross-apartment call:

Marshaling COMCOM marshaling

Para realizar marshaling entre apartments, você pode fazer o seguinte:For cross-apartment marshaling, you can do the following:

  • Aceite a sobrecarga de marshaling de apartment cruzada, que é perceptível somente quando há muitas chamadas entre dos limites.Accept the overhead of the cross-apartment marshaling, which is noticeable only when there are many calls across the boundary. Você deve registrar a biblioteca de tipos do componente COM para que chamadas cruzem o limite do apartment com êxito.You must register the type library of the COM component for calls to successfully cross the apartment boundary.

  • Altere o thread principal, definindo o thread de cliente para STA ou MTA.Alter the main thread by setting the client thread to STA or MTA. Por exemplo, se o cliente C# chama muitos componentes COM STA, você pode evitar marshaling entre apartments definindo o thread principal para STA.For example, if your C# client calls many STA COM components, you can avoid cross-apartment marshaling by setting the main thread to STA.

    Observação

    Depois que o thread de um cliente C# for definido para STA, chamadas para componentes COM MTA exigirão marshaling entre apartments.Once the thread of a C# client is set to STA, calls to MTA COM components will require cross-apartment marshaling.

Para obter instruções sobre como selecionar explicitamente um modelo de apartment, consulte Threading gerenciado e não gerenciado.For instructions on explicitly selecting an apartment model, see Managed and Unmanaged Threading.

Marshaling de chamadas remotasMarshaling Remote Calls

Assim como ocorre com marshaling entre apartments, o marshaling COM está envolvido em cada chamada entre código gerenciado e código não gerenciado e sempre que os objetos residem em processos separados.As with cross-apartment marshaling, COM marshaling is involved in each call between managed and unmanaged code whenever the objects reside in separate processes. Por exemplo:For example:

  • Um cliente COM que invoca um servidor gerenciado em um host remoto usa COM distribuído (DCOM).A COM client that invokes a managed server on a remote host uses distributed COM (DCOM).
  • Um cliente gerenciado que chama um servidor COM em um host remoto usa DCOM.A managed client that invokes a COM server on a remote host uses DCOM.

A ilustração a seguir mostra como o empacotamento de interoperabilidade e o marshaling COM fornecem canais de comunicação entre limites de host e processo:The following illustration shows how interop marshaling and COM marshaling provide communications channels across process and host boundaries:

Marshaling COMCOM marshaling

Preservação de identidadePreserving Identity

O Common Language Runtime preserva a identidade de referências gerenciadas e não gerenciados.The common language runtime preserves the identity of managed and unmanaged references. A ilustração a seguir mostra o fluxo de referências diretas não gerenciadas (linha superior) e referências diretas gerenciadas (linha inferior) entre limites de processo e de host.The following illustration shows the flow of direct unmanaged references (top row) and direct managed references (bottom row) across process and host boundaries.

Wrapper callable COM Callable Wrapper e RuntimeCOM callable wrapper and runtime callable wrapper

Nessa ilustração:In this illustration:

  • Um cliente não gerenciado obtém uma referência para um objeto COM de um objeto gerenciado que obtém essa referência de um host remoto.An unmanaged client gets a reference to a COM object from a managed object that gets this reference from a remote host. O mecanismo de comunicação remota é DCOM.The remoting mechanism is DCOM.

  • Um cliente gerenciado obtém uma referência para um objeto gerenciado de um objeto COM que obtém essa referência de um host remoto.A managed client gets a reference to a managed object from a COM object that gets this reference from a remote host. O mecanismo de comunicação remota é DCOM.The remoting mechanism is DCOM.

    Observação

    A biblioteca de tipos exportada do servidor gerenciado deve ser registrada.The exported type library of the managed server must be registered.

O número de limites de processo entre o chamador e o receptor é irrelevante; a mesma referência direta ocorre para chamadas em processo e fora de processo.The number of process boundaries between caller and callee is irrelevant; the same direct referencing occurs for in-process and out-of-process calls.

Comunicação remota gerenciadaManaged Remoting

O runtime também fornece comunicação remota gerenciada, que pode ser usada para estabelecer um canal de comunicação entre os objetos gerenciados entre limites de processo e de host.The runtime also provides managed remoting, which you can use to establish a communications channel between managed objects across process and host boundaries. A comunicação remota gerenciada pode acomodar um firewall entre os componentes de comunicação, como mostra a ilustração a seguir:Managed remoting can accommodate a firewall between the communicating components, as the following illustration shows:

SOAP ou TcpChannel Chamadas remotas entre firewalls usando SOAP ou a classe TcpChannelSOAP or TcpChannel Remote calls across firewalls using SOAP or the TcpChannel class

Algumas chamadas não gerenciadas podem ser canalizadas por SOAP, assim como as chamadas entre os componentes de serviço e o COM.Some unmanaged calls can be channeled through SOAP, such as the calls between serviced components and COM.

TítuloTitle DescriçãoDescription
Comportamento de marshaling padrãoDefault Marshaling Behavior Descreve as regras que o serviço de marshaling de interoperabilidade usa para realizar marshaling de dados.Describes the rules that the interop marshaling service uses to marshal data.
Marshaling de dados com a invocação de plataformaMarshaling Data with Platform Invoke Descreve como declarar parâmetros de método e passar argumentos para funções exportadas por bibliotecas não gerenciadas.Describes how to declare method parameters and pass arguments to functions exported by unmanaged libraries.
Realizando marshaling em dados com interoperabilidade COMMarshaling Data with COM Interop Descreve como personalizar os wrappers COM para alterar o comportamento de marshaling.Describes how to customize COM wrappers to alter marshaling behavior.
Como: migrar código DCOM gerenciado para o WCFHow to: Migrate Managed-Code DCOM to WCF Descreve como migrar do DCOM para o WCF.Describes how to migrate from DCOM to WCF.
Como mapear HRESULTs e exceçõesHow to: Map HRESULTs and Exceptions Descreve como mapear exceções personalizadas para HRESULTs e fornece o mapeamento completo de cada HRESULT para a respectiva classe de exceção comparável no .NET Framework.Describes how to map custom exceptions to HRESULTs and provides the complete mapping from each HRESULT to its comparable exception class in the .NET Framework.
Interoperação usando tipos genéricosInteroperating Using Generic Types Descreve quais ações têm suporte ao usar tipos genéricos para interoperabilidade COM.Describes which actions are supported when using generic types for COM interoperability.
Interoperação com código não gerenciadoInteroperating with Unmanaged Code Descreve os serviços de interoperabilidade fornecidos pelo Common Language Runtime.Describes interoperability services provided by the common language runtime.
Interoperabilidade COM avançadaAdvanced COM Interoperability Fornece links para obter mais informações sobre como incorporar componentes COM no aplicativo do .NET Framework.Provides links to more information about incorporating COM components into your .NET Framework application.
Considerações sobre design para interoperaçãoDesign Considerations for Interoperation Fornece dicas para escrever componentes COM integrados.Provides tips for writing integrated COM components.

ReferênciaReference

System.Runtime.InteropServices