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. ここで、というよく知られIOldている COM インターフェイスには、 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. インターフェイスが古い .idl で定義されている場合、出力ファイル Old_i は、次constの例に示すように、インターフェイスのインターフェイス識別子 (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}};  

古い .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 マーシャラーが、 MarshalManagedToNativeメソッドによって返されるネイティブデータ (CCW) をクリーンアップできるようにします。Enables the marshaler to clean up the native data (the CCW) that is returned by the MarshalManagedToNative method.
クリーンアップ (マネージコードの)Cleanup (of managed code) CleanUpManagedData マーシャラーが、 MarshalNativeToManagedメソッドによって返されるマネージデータ (RCW) をクリーンアップできるようにします。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

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

ICustomMarshaler.CleanUpManagedData

マーシャラーが、 MarshalNativeToManagedメソッドによって返されるマネージデータ (RCW) をクリーンアップできるようにします。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インターフェイスを実装するだけでなく、カスタムマーシャラーは、 staticStringパラメーター GetInstanceとして受け取り、戻り値の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渡される文字列は、返されたカスタムマーシャラーをカスタマイズするためにメソッドが使用できる cookie です。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. クッキーは、マーシャラーの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.

次に、ランタイムはMarshalNativeToManagedカスタムMarshalManagedToNativeマーシャラーのメソッドとメソッドを呼び出して、呼び出しを処理する適切なラッパーをアクティブ化します。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マネージ定義の引数に適用される属性は、次の例に示すように、引数がカスタムマーシャラーを使用することを示します。 DoSomeStuffThe 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.

適用対象