Runtime Callable WrapperRuntime Callable Wrapper

Common Language Runtime espone gli oggetti COM tramite un proxy denominato Runtime Callable Wrapper (RCW).The common language runtime exposes COM objects through a proxy called the runtime callable wrapper (RCW). Benché l'RCW appaia ai client .NET come un normale oggetto, la sua funzione principale consiste nell'effettuare il marshalling tra un client .NET e un oggetto COM.Although the RCW appears to be an ordinary object to .NET clients, its primary function is to marshal calls between a .NET client and a COM object.

Il runtime crea esattamente un RCW per ciascun oggetto COM, indipendentemente dal numero di riferimenti all'oggetto.The runtime creates exactly one RCW for each COM object, regardless of the number of references that exist on that object. Il runtime mantiene un solo RCW a processo per ciascun oggetto.The runtime maintains a single RCW per process for each object. Se si crea un RCW in un apartment o dominio applicazione e si passa quindi un riferimento a un altro apartment o dominio applicazione, verrà usato un proxy al primo oggetto.If you create an RCW in one application domain or apartment, and then pass a reference to another application domain or apartment, a proxy to the first object will be used. Come illustrato nella figura che segue, un numero qualsiasi di client gestiti può stabilire un riferimento agli oggetti COM che espongono le interfacce INew e INewer.As the following illustration shows, any number of managed clients can hold a reference to the COM objects that expose INew and INewer interfaces.

RCWRCW
Accesso a oggetti COM tramite Runtime Callable WrapperAccessing COM objects through the runtime callable wrapper

Usando i metadati derivati da una libreria dei tipi, il runtime crea sia l'oggetto COM che si sta chiamando che il relativo wrapper.Using metadata derived from a type library, the runtime creates both the COM object being called and a wrapper for that object. Ogni RCW mantiene una cache dei puntatori a interfaccia impostati sull'oggetto COM di cui effettua il wrapping e rilascia i riferimenti all'oggetto COM quando l'RCW non è più necessario.Each RCW maintains a cache of interface pointers on the COM object it wraps and releases its reference on the COM object when the RCW is no longer needed. Il runtime esegue la procedura di Garbage Collection sull'RCW.The runtime performs garbage collection on the RCW.

Tra le altre attività, l'RCW effettua il marshalling dei dati trasferiti tra il codice gestito e quello non gestito, per conto dell'oggetto di cui effettua il wrapping.Among other activities, the RCW marshals data between managed and unmanaged code, on behalf of the wrapped object. In particolare, l'RCW effettua il marshalling degli argomenti e dei valori restituiti dei metodi ogni volta che il client e il server adottano rappresentazioni diverse dei dati scambiati.Specifically, the RCW provides marshaling for method arguments and method return values whenever the client and server have different representations of the data passed between them.

Il wrapper standard applica le regole di marshalling incorporate.The standard wrapper enforces built-in marshaling rules. Quando ad esempio un client .NET passa come parte di un argomento un tipo String a un oggetto gestito, il wrapper converte la stringa in un tipo BSTR.For example, when a .NET client passes a String type as part of an argument to an unmanaged object, the wrapper converts the string to a BSTR type. Nel caso in cui l'oggetto COM dovesse restituire un valore di tipo BSTR, il relativo chiamante gestito riceverebbe una stringa.Should the COM object return a BSTR to its managed caller, the caller receives a String. Sia il client che il server inviano e ricevono dati rispettivamente noti.Both the client and the server send and receive data that is familiar to them. Gli altri tipi non richiedono alcuna conversione.Other types require no conversion. Un wrapper standard, ad esempio, trasferirà sempre un intero di 4 byte tra il codice gestito e quello non gestito senza operare alcuna conversione di tipo.For instance, a standard wrapper will always pass a 4-byte integer between managed and unmanaged code without converting the type.

Interfacce sottoposte a marshallingMarshaling selected interfaces

L'obiettivo principale di un oggetto Runtime Callable Wrapper (RCW) è quello di nascondere le differenze tra i modelli di programmazione gestiti e non gestiti.The primary goal of the runtime callable wrapper (RCW) is to hide the differences between the managed and unmanaged programming models. Per semplificare la transizione, l'RCW usa interfacce COM selezionate senza esporle al client .NET, come illustrato nella figura che segue.To create a seamless transition, the RCW consumes selected COM interfaces without exposing them to the .NET client, as shown in the following illustration.

RCW con interfacceRCW With Interfaces
Interfacce COM e il Runtime Callable WrapperCOM interfaces and the runtime callable wrapper

Quando viene creato come oggetto ad associazione anticipata, l'RCW è specifico del tipo.When created as an early-bound object, the RCW is a specific type. Esso implementa le interfacce implementate dall'oggetto COM ed espone i metodi, le proprietà e gli eventi delle interfacce dell'oggetto.It implements the interfaces that the COM object implements and exposes the methods, properties, and events from the object's interfaces. Nella figura l'oggetto RCW espone l'interfaccia INew, ma utilizza le interfacce IUnknown e IDispatch.In the illustration, the RCW exposes the INew interface but consumes the IUnknown and IDispatch interfaces. L'RCW espone inoltre al client .NET tutti i membri dell'interfaccia INew.Further, the RCW exposes all members of the INew interface to the .NET client.

L'RCW usa le interfacce elencate nella tabella che segue, che sono esposte dall'oggetto di cui effettua il wrapping.The RCW consumes the interfaces listed in the following table, which are exposed by the object it wraps.

InterfacciaInterface DescrizioneDescription
IDispatchIDispatch Per l'associazione tardiva a oggetti COM tramite reflection.For late binding to COM objects through reflection.
IErrorInfoIErrorInfo Fornisce una descrizione testuale dell'errore, la relativa origine, un file della Guida, un contesto della Guida e il GUID dell'interfaccia che ha definito l'errore (sempre GUID_NULL per le classi .NET).Provides a textual description of the error, its source, a Help file, Help context, and the GUID of the interface that defined the error (always GUID_NULL for .NET classes).
IProvideClassInfoIProvideClassInfo Se l'oggetto COM di cui si esegue il wrapping implementa IProvideClassInfo, l'oggetto RCW estrarrà le informazioni sul tipo da questa interfaccia per definire meglio l'identità del tipo.If the COM object being wrapped implements IProvideClassInfo, the RCW extracts the type information from this interface to provide better type identity.
IUnknownIUnknown Per l'identità del tipo, la coercizione dei tipi e la gestione della durata:For object identity, type coercion, and lifetime management:

- Identità degli oggetti- Object identity
Il runtime distingue tra gli oggetti COM confrontando il valore dell'interfaccia IUnknown di ciascun oggetto.The runtime distinguishes between COM objects by comparing the value of the IUnknown interface for each object.
- Coercizione dei tipi- Type coercion
L'oggetto RCW riconosce l'individuazione dei tipi dinamica eseguita dal metodo QueryInterface.The RCW recognizes the dynamic type discovery performed by the QueryInterface method.
- Gestione del ciclo di vita- Lifetime management
Usando il metodo QueryInterface, l'oggetto RCW ottiene e mantiene un riferimento a un oggetto non gestito fino a quando il runtime non esegue una procedura di Garbage Collection sul wrapper, rilasciando l'oggetto non gestito.Using the QueryInterface method, the RCW gets and holds a reference to an unmanaged object until the runtime performs garbage collection on the wrapper, which releases the unmanaged object.

RCW usa facoltativamente le interfacce elencate nella tabella che segue, che sono esposte dall'oggetto di cui effettua il wrapping.The RCW optionally consumes the interfaces listed in the following table, which are exposed by the object it wraps.

InterfacciaInterface DescrizioneDescription
IConnectionPoint e IConnectionPointContainerIConnectionPoint and IConnectionPointContainer Talvolta l'RCW usa le interfacce elencate nella tabella che segue, che sono esposte dall'oggetto di cui effettua il wrapping.The RCW converts objects that expose the connection-point event style to delegate-based events.
IDispatchExIDispatchEx Se la classe implementa IDispatchEx, l'oggetto RCW implementa IExpando.If the class implements IDispatchEx, the RCW implements IExpando. L'interfaccia IDispatchEx è un'estensione dell'interfaccia IDispatch che, diversamente da IDispatch, consente l'enumerazione, l'aggiunta, l'eliminazione e la chiamata dei membri con distinzione tra maiuscole e minuscole.The IDispatchEx interface is an extension of the IDispatch interface that, unlike IDispatch, enables enumeration, addition, deletion, and case-sensitive calling of members.
IEnumVARIANTIEnumVARIANT Consente di trattare come raccolte i tipi COM che supportano l'enumerazione.Enables COM types that support enumerations to be treated as collections.

Vedere ancheSee Also

Wrapper COMCOM Wrappers
Sottoporre a marshalling interfacce selezionateMarshaling Selected Interfaces
COM Callable WrapperCOM Callable Wrapper
Riepilogo della conversione da libreria dei tipi ad assemblyType Library to Assembly Conversion Summary
Importazione di una libreria dei tipi come assemblyImporting a Type Library as an Assembly