ICustomMarshaler ICustomMarshaler ICustomMarshaler ICustomMarshaler Interface

定義

メソッド呼び出しを処理するためのカスタム ラッパーを提供します。Provides custom wrappers for handling method calls.

public interface class ICustomMarshaler
[System.Runtime.InteropServices.ComVisible(true)]
public interface ICustomMarshaler
type ICustomMarshaler = interface
Public Interface ICustomMarshaler
派生
属性

注釈

マーシャラーは、以前の機能と新しいインターフェイス間のブリッジを提供します。A marshaler provides a bridge between the functionality of old and new interfaces. カスタム マーシャ リングには、次の利点が提供されます。Custom marshaling provides the following benefits:

  • 新しいインターフェイスを実装するサーバーとも連携する以前のインターフェイスを使用するように設計されたクライアント アプリケーションができるようにします。It enables client applications that were designed to work with an old interface to also work with servers that implement a new interface.

  • 以前のインターフェイスを実装しているサーバーを使用するクライアント アプリケーションの新しいインターフェイスを使用するために構築できます。It enables client applications built to work with a new interface to work with servers that implement an old interface.

別のマーシャ リング動作を導入するか、コンポーネント オブジェクト モデル (COM) を別の方法で公開されるインターフェイスを使っている場合は、相互運用マーシャラーを使用する代わりに、カスタム マーシャラーをデザインできます。If you have an interface that introduces different marshaling behavior or that is exposed to the Component Object Model (COM) in a different way, you can design a custom marshaler instead of using the interop marshaler. カスタム マーシャラーを使用すると、新しい .NET Framework コンポーネントと既存の COM コンポーネントの違いを最小限に抑えることができます。By using a custom marshaler, you can minimize the distinction between new .NET Framework components and existing COM components.

たとえばと呼ばれるマネージ インターフェイスを開発しているINewします。For example, suppose that you are developing a managed interface called INew. このインターフェイスは、標準の COM 呼び出し可能ラッパー (CCW) を COM に公開される、ときに同じメソッドは、マネージ インターフェイスとは、相互運用マーシャラーに組み込まれているマーシャ リング規則を使用します。When this interface is exposed to COM through a standard COM callable wrapper (CCW), it has the same methods as the managed interface and uses the marshaling rules built into the interop marshaler. たとえば、よく知られている COM インターフェイスと呼ばれることIOldと同じ機能を既に提供されて、INewインターフェイス。Now suppose that a well-known COM interface called IOld already provides the same functionality as the INew interface. カスタム マーシャラーを設計することでの非管理対象の実装を行うことができますIOldのマネージ実装への呼び出しを単純にデリゲートされる、INewインターフェイス。By designing a custom marshaler, you can provide an unmanaged implementation of IOld that simply delegates the calls to the managed implementation of the INew interface. そのため、カスタム マーシャラーは、マネージ コードとアンマネージ インターフェイス間の仲介役として機能します。Therefore, the custom marshaler acts as a bridge between the managed and unmanaged interfaces.

注意

カスタム マーシャラーは、ディスパッチ専用インターフェイスでマネージ コードからアンマネージ コードに呼び出す場合は呼び出されません。Custom marshalers are not invoked when calling from managed code to unmanaged code on a dispatch-only interface.

マーシャリング型の定義Defining the Marshaling Type

カスタム マーシャラーを作成するには、マーシャ リングするマネージ コードとアンマネージ インターフェイスを定義する必要があります。Before you can build a custom marshaler, you must define the managed and unmanaged interfaces that will be marshaled. これらのインターフェイスは、よく同じ機能を実行がマネージ コードとアンマネージ オブジェクトに異なる方法で公開されます。These interfaces commonly perform the same function but are exposed differently to managed and unmanaged objects.

マネージ コンパイラがメタデータからマネージ インターフェイスを生成し、結果として得られるインターフェイスが他のマネージ インターフェイスのようになります。A managed compiler produces a managed interface from metadata, and the resulting interface looks like any other managed interface. 次の例では、代表的なインターフェイスを示します。The following example shows a typical interface.

public interface class INew
{
    void NewMethod();
};
public interface INew
{
    void NewMethod();
}
Public Interface INew
    Sub NewMethod()
End Interface

アンマネージ型のインターフェイス定義言語 (IDL) を定義し、Microsoft インターフェイス定義言語 (MIDL) コンパイラでコンパイルします。You define the unmanaged type in Interface Definition Language (IDL) and compile it with the Microsoft Interface Definition Language (MIDL) compiler. ライブラリのステートメント内でインターフェイスを定義し、次の例に示すように、ユニバーサル一意識別子 (UUID) 属性を持つインターフェイス ID を割り当てます、します。You define the interface within a library statement and assign it an interface ID with the universal unique identifier (UUID) attribute, as the following example demonstrates.

 [uuid(9B2BAADA-0705-11D3-A0CD-00C04FA35826)]  
library OldLib {  
     [uuid(9B2BAADD-0705-11D3-A0CD-00C04FA35826)]  
     interface IOld : IUnknown  
         HRESULT OldMethod();  
}  

MIDL コンパイラは、いくつかの出力ファイルを生成します。The MIDL compiler produces several output files. 出力ファイル Old_i.c が定義されて Old.idl でインターフェイスが定義されている場合、constインターフェイスのインターフェイス id (IID) 変数例を次に示します。If the interface is defined in Old.idl, the output file Old_i.c defines a const variable with the interface identifier (IID) of the interface, as the following example demonstrates.

const IID IID_IOld = {0x9B2BAADD,0x0705,0x11D3,{0xA0,0xCD,0x00,0xC0,0x4F,0xA3,0x58,0x26}};  

Old.h ファイルは、MIDL によっても生成されます。The Old.h file is also produced by MIDL. C++ ソース コードに含めることができるインターフェイスの C++ 定義が含まれています。It contains a C++ definition of the interface that can be included in your C++ source code.

ICustomMarshaler インターフェイスの実装Implementing the ICustomMarshaler Interface

カスタム マーシャラーを実装する必要があります、ICustomMarshalerランタイムに適切なラッパーを提供するインターフェイス。Your custom marshaler must implement the ICustomMarshaler interface to provide the appropriate wrappers to the runtime.

次の c# コードでは、すべてのカスタム マーシャラーで実装する必要がある基本インターフェイスが表示されます。The following C# code displays the base interface that must be implemented by all custom marshalers.

public interface class ICustomMarshaler
{
     Object^ MarshalNativeToManaged( IntPtr^ pNativeData );
     IntPtr^ MarshalManagedToNative( Object^ ManagedObj );
     void CleanUpNativeData( IntPtr^ pNativeData );
     void CleanUpManagedData( Object^ ManagedObj );
     int GetNativeDataSize();
};
public interface ICustomMarshaler
{
     Object MarshalNativeToManaged( IntPtr pNativeData );
     IntPtr MarshalManagedToNative( Object ManagedObj );
     void CleanUpNativeData( IntPtr pNativeData );
     void CleanUpManagedData( Object ManagedObj );
     int GetNativeDataSize();
}
Public Interface ICustomMarshaler
     Function MarshalNativeToManaged( pNativeData As IntPtr ) As Object
     Function MarshalManagedToNative( ManagedObj As Object ) As IntPtr
     Sub CleanUpNativeData( pNativeData As IntPtr )
     Sub CleanUpManagedData( ManagedObj As Object )
     Function GetNativeDataSize() As Integer
End Interface

ICustomMarshalerインターフェイスには、変換のサポートやクリーンアップのサポート、マーシャ リングするデータに関する情報を提供するメソッドが含まれています。The ICustomMarshaler interface includes methods that provide conversion support, cleanup support, and information about the data to be marshaled.

操作の種類Type of operation ICustomMarshaler メソッドICustomMarshaler method 説明Description
(ネイティブ コードからマネージ コードに) 変換Conversion (from native to managed code) MarshalNativeToManaged マネージ オブジェクトには、ネイティブのデータへのポインターをマーシャ リングします。Marshals a pointer to native data into a managed object. このメソッドは、引数として渡されるアンマネージ インターフェイスのマーシャ リングできるカスタム ランタイム呼び出し可能ラッパー (RCW) を返します。This method returns a custom runtime callable wrapper (RCW) that can marshal the unmanaged interface that is passed as an argument. マーシャラーは、カスタム RCW をその型のインスタンスを返す必要があります。The marshaler should return an instance of the custom RCW for that type.
変換 (マネージ コードからネイティブ コード)Conversion (from managed to native code) MarshalManagedToNative ネイティブのデータへのポインターには、マネージ オブジェクトをマーシャ リングします。Marshals a managed object into a pointer to native data. このメソッドは、カスタム COM 呼び出し可能ラッパー (CCW) を引数として渡されるマネージ インターフェイスのマーシャ リングできるを返します。This method returns a custom COM callable wrapper (CCW) that can marshal the managed interface that is passed as an argument. マーシャラーは、その型のカスタムの CCW のインスタンスを返す必要があります。The marshaler should return an instance of the custom CCW for that type.
(ネイティブ コードのクリーンアップCleanup (of native code) CleanUpNativeData 使用するマーシャラーがによって返されるネイティブのデータ (CCW) をクリーンアップする、MarshalManagedToNativeメソッド。Enables the marshaler to clean up the native data (the CCW) that is returned by the MarshalManagedToNative method.
(マネージ コード) のクリーンアップCleanup (of managed code) CleanUpManagedData 使用するマーシャラーがによって返される管理対象のデータ (RCW) をクリーンアップする、MarshalNativeToManagedメソッド。Enables the marshaler to clean up the managed data (the RCW) that is returned by the MarshalNativeToManaged method.
(ネイティブ コード) に関する情報Information (about native code) GetNativeDataSize マーシャ リングされるアンマネージ データのサイズを返します。Returns the size of the unmanaged data to be marshaled.

変換Conversion

ICustomMarshaler.MarshalNativeToManaged

マネージ オブジェクトには、ネイティブのデータへのポインターをマーシャ リングします。Marshals a pointer to native data into a managed object. このメソッドは、引数として渡されるアンマネージ インターフェイスのマーシャ リングできるカスタム ランタイム呼び出し可能ラッパー (RCW) を返します。This method returns a custom runtime callable wrapper (RCW) that can marshal the unmanaged interface that is passed as an argument. マーシャラーは、カスタム RCW をその型のインスタンスを返す必要があります。The marshaler should return an instance of the custom RCW for that type.

ICustomMarshaler.MarshalManagedToNative

ネイティブのデータへのポインターには、マネージ オブジェクトをマーシャ リングします。Marshals a managed object into a pointer to native data. このメソッドは、カスタム COM 呼び出し可能ラッパー (CCW) を引数として渡されるマネージ インターフェイスのマーシャ リングできるを返します。This method returns a custom COM callable wrapper (CCW) that can marshal the managed interface that is passed as an argument. マーシャラーは、その型のカスタムの CCW のインスタンスを返す必要があります。The marshaler should return an instance of the custom CCW for that type.

クリーンアップCleanup

ICustomMarshaler.CleanUpNativeData

使用するマーシャラーがによって返されるネイティブのデータ (CCW) をクリーンアップする、MarshalManagedToNativeメソッド。Enables the marshaler to clean up the native data (the CCW) that is returned by the MarshalManagedToNative method.

ICustomMarshaler.CleanUpManagedData

使用するマーシャラーがによって返される管理対象のデータ (RCW) をクリーンアップする、MarshalNativeToManagedメソッド。Enables the marshaler to clean up the managed data (the RCW) that is returned by the MarshalNativeToManaged method.

サイズの情報Size Information

ICustomMarshaler.GetNativeDataSize

マーシャ リングされるアンマネージ データのサイズを返します。Returns the size of the unmanaged data to be marshaled.

GetInstance メソッドを実装します。Implementing the GetInstance Method

実装するだけでなく、ICustomMarshalerインターフェイス、カスタム マーシャラーを実装する必要があります、staticメソッドと呼ばれるGetInstanceを受け入れる、Stringをパラメーターとしての戻り値の型でありICustomMarshalerします。In addition to implementing the ICustomMarshaler interface, custom marshalers must implement a static method called GetInstance that accepts a String as a parameter and has a return type of ICustomMarshaler. これは、staticメソッドは、カスタム マーシャラーのインスタンスをインスタンス化する共通言語ランタイムの COM の相互運用層によって呼び出されます。This static method is called by the common language runtime's COM interop layer to instantiate an instance of the custom marshaler. 渡される文字列GetInstanceはメソッドが返されるカスタム マーシャラーのカスタマイズに使用できるクッキーです。The string that is passed to GetInstance is a cookie that the method can use to customize the returned custom marshaler.

static ICustomMarshaler *GetInstance(String *pstrCookie);  

MarshalAsAttribute の適用Applying MarshalAsAttribute

カスタム マーシャラーを使用することを適用する必要があります、MarshalAsAttribute属性をパラメーターまたはマーシャ リングされるフィールド。To use a custom marshaler, you must apply the MarshalAsAttribute attribute to the parameter or field that is being marshaled.

渡す必要があります、UnmanagedType.CustomMarshaler列挙値をMarshalAsAttributeコンス トラクター。You must also pass the UnmanagedType.CustomMarshaler enumeration value to the MarshalAsAttribute constructor. さらに、指定する必要があります、MarshalTypeフィールドの名前付きパラメーターが次のいずれか。In addition, you must specify the MarshalType field with one of the following named parameters:

  • MarshalType (必須)。カスタム マーシャラーのアセンブリ修飾名。MarshalType (required): The assembly-qualified name of the custom marshaler. 名前には、名前空間と、カスタム マーシャラーのクラスを含める必要があります。The name should include the namespace and class of the custom marshaler. カスタム マーシャラーがで使用されているアセンブリで定義されていない場合が定義されているアセンブリの名前を指定する必要があります。If the custom marshaler is not defined in the assembly it is used in, you must specify the name of the assembly in which it is defined.

    注意

    使用することができます、MarshalTypeRefフィールドの代わりに、MarshalTypeフィールド。You can use the MarshalTypeRef field instead of the MarshalType field. MarshalTypeRef 簡単に指定される型を受け取る。MarshalTypeRef takes a type that is easier to specify.

  • MarshalCookie (省略可能)。カスタム マーシャラーに渡されるクッキー。MarshalCookie (optional): A cookie that is passed to the custom marshaler. Cookie を使用するには、マーシャラーに追加情報を提供します。You can use the cookie to provide additional information to the marshaler. たとえば、同じマーシャラーを使用するラッパーの番号を入力すると、cookie は特定のラッパーを識別します。For example, if the same marshaler is used to provide a number of wrappers, the cookie identifies a specific wrapper. Cookie に渡される、GetInstanceマーシャラーのメソッド。The cookie is passed to the GetInstance method of the marshaler.

MarshalAsAttribute属性は、適切なラッパーがアクティブにすることができるために、カスタム マーシャラーを識別します。The MarshalAsAttribute attribute identifies the custom marshaler so it can activate the appropriate wrapper. 共通言語ランタイムの相互運用機能のサービスは、属性を検査し、カスタム マーシャラーの最初の時間にマーシャ リングする引数 (パラメーターまたはフィールド) のニーズを作成します。The common language runtime's interop service then examines the attribute and creates the custom marshaler the first time the argument (parameter or field) needs to be marshaled.

ランタイムを呼び出して、MarshalNativeToManagedMarshalManagedToNativeメソッドの呼び出しを処理するために、正しいラッパーをアクティブ化するカスタム マーシャラーにします。The runtime then calls the MarshalNativeToManaged and MarshalManagedToNative methods on the custom marshaler to activate the correct wrapper to handle the call.

カスタム マーシャラーの使用Using a Custom Marshaler

カスタム マーシャラーが完了したらは、特定の型のカスタム ラッパーとして使用することができます。When the custom marshaler is complete, you can use it as a custom wrapper for a particular type. 次の例では、定義、IUserDataマネージ インターフェイス。The following example shows the definition of the IUserData managed interface:

public interface class IUserData
{
    void DoSomeStuff(INew^ pINew);
};
interface IUserData
{
    void DoSomeStuff(INew pINew);
}
Public Interface IUserData
    Sub DoSomeStuff(pINew As INew)
End Interface

次の例では、IUserDataインターフェイスの使用、NewOldMarshalerカスタム マーシャラーに渡すアンマネージ クライアント アプリケーションを有効にする、IOldへのインターフェイス、DoSomeStuffメソッド。In the following example, the IUserData interface uses the NewOldMarshaler custom marshaler to enable unmanaged client applications to pass an IOld interface to the DoSomeStuff method. 管理対象の説明、DoSomeStuffメソッドは、INewインターフェイスには、前の例で示すように、アンマネージ バージョンのDoSomeStuffは、IOldインターフェイス ポインターを次の例に示すようにします。The managed description of the DoSomeStuff method takes an INew interface, as shown in the previous example, whereas the unmanaged version of DoSomeStuff takes an IOld interface pointer, as shown in the following example.

[uuid(9B2BAADA-0705-11D3-A0CD-00C04FA35826)]  
library UserLib {  
     [uuid(9B2BABCD-0705-11D3-A0CD-00C04FA35826)]  
     interface IUserData : IUnknown  
         HRESULT DoSomeStuff(IUnknown* pIOld);  
}  

マネージ定義をエクスポートすることによって生成されるタイプ ライブラリIUserData標準の定義ではなく、この例に示すアンマネージの定義を生成します。The type library that is generated by exporting the managed definition of IUserData yields the unmanaged definition shown in this example instead of the standard definition. MarshalAsAttribute属性が適用されて、INewのマネージ定義内の引数、DoSomeStuffメソッドは、引数が、次の例として、カスタム マーシャラーを使用することを示します。The MarshalAsAttribute attribute applied to the INew argument in the managed definition of the DoSomeStuff method indicates that the argument uses a custom marshaler, as the following example shows.

using namespace System::Runtime::InteropServices;
using System.Runtime.InteropServices;
Imports System.Runtime.InteropServices
public interface class IUserData
{
    void DoSomeStuff(
        [MarshalAs(UnmanagedType::CustomMarshaler,
             MarshalType="MyCompany.NewOldMarshaler")]
        INew^ pINew
    );
};
interface IUserData
{
    void DoSomeStuff(
        [MarshalAs(UnmanagedType.CustomMarshaler,
             MarshalType="MyCompany.NewOldMarshaler")]
        INew pINew
    );
}
Public Interface IUserData
    Sub DoSomeStuff( _
        <MarshalAs(UnmanagedType.CustomMarshaler, _
        MarshalType := "MyCompany.NewOldMarshaler")> pINew As INew)
End Interface

前の例では、最初のパラメーターが提供される、MarshalAsAttribute属性は、UnmanagedType.CustomMarshaler列挙値UnmanagedType.CustomMarshalerします。In the previous examples, the first parameter provided to the MarshalAsAttribute attribute is the UnmanagedType.CustomMarshaler enumeration value UnmanagedType.CustomMarshaler.

2 番目のパラメーターは、MarshalTypeフィールドで、カスタム マーシャラーのアセンブリ修飾名を提供します。The second parameter is the MarshalType field, which provides the assembly-qualified name of the custom marshaler. この名前は、名前空間と、カスタム マーシャラーのクラス (MarshalType="MyCompany.NewOldMarshaler")。This name consists of the namespace and class of the custom marshaler (MarshalType="MyCompany.NewOldMarshaler").

メソッド

CleanUpManagedData(Object) CleanUpManagedData(Object) CleanUpManagedData(Object) CleanUpManagedData(Object)

不要になったときに、マネージド データの必要なクリーンアップを実行します。Performs necessary cleanup of the managed data when it is no longer needed.

CleanUpNativeData(IntPtr) CleanUpNativeData(IntPtr) CleanUpNativeData(IntPtr) CleanUpNativeData(IntPtr)

不要になったときに、アンマネージ データの必要なクリーンアップを実行します。Performs necessary cleanup of the unmanaged data when it is no longer needed.

GetNativeDataSize() GetNativeDataSize() GetNativeDataSize() GetNativeDataSize()

マーシャリングするネイティブ データのサイズを返します。Returns the size of the native data to be marshaled.

MarshalManagedToNative(Object) MarshalManagedToNative(Object) MarshalManagedToNative(Object) MarshalManagedToNative(Object)

マネージド データをアンマネージド データに変換します。Converts the managed data to unmanaged data.

MarshalNativeToManaged(IntPtr) MarshalNativeToManaged(IntPtr) MarshalNativeToManaged(IntPtr) MarshalNativeToManaged(IntPtr)

アンマネージド データをマネージド データに変換します。Converts the unmanaged data to managed data.

適用対象