System.Runtime.InteropServices.ICustomMarshaler インターフェイス

この記事では、この API のリファレンス ドキュメントへの補足的な解説を提供します。

このインターフェイスには ICustomMarshaler 、メソッド呼び出しを処理するためのカスタム ラッパーが用意されています。

マーシャラーは、古いインターフェイスと新しいインターフェイスの機能の間のブリッジを提供します。 カスタム マーシャリングには、次の利点があります。

• これにより、古いインターフェイスで動作するように設計されたクライアント アプリケーションは、新しいインターフェイスを実装するサーバーでも動作できます。
• これにより、新しいインターフェイスで動作するように構築されたクライアント アプリケーションは、古いインターフェイスを実装するサーバーと連携できます。

異なるマーシャリング動作を導入するインターフェイス、またはコンポーネント オブジェクト モデル (COM) に別の方法で公開されるインターフェイスがある場合は、相互運用マーシャラーを使用する代わりにカスタム マーシャラーを設計できます。 カスタム マーシャラーを使用すると、新しい .NET Framework コンポーネントと既存の COM コンポーネントの区別を最小限に抑えることができます。

たとえば、次のような INewマネージド インターフェイスを開発しているとします。 このインターフェイスが標準の COM 呼び出し可能ラッパー (CCW) を介して COM に公開されている場合は、マネージド インターフェイスと同じメソッドを持ち、相互運用マーシャラーに組み込まれているマーシャリング規則を使用します。 ここで、よく知られている COM インターフェイスが IOld 既にインターフェイスと同じ機能を INew 提供しているとします。 カスタム マーシャラーを設計することで、インターフェイスの IOld マネージド実装への呼び出しを委任するだけのアンマネージ実装を INew 提供できます。 そのため、カスタム マーシャラーは、マネージド インターフェイスとアンマネージド インターフェイスの間のブリッジとして機能します。

マーシャリングの種類を定義する

カスタム マーシャラーを構築する前に、マーシャリングされるマネージド インターフェイスとアンマネージド インターフェイスを定義する必要があります。 これらのインターフェイスは一般的に同じ関数を実行しますが、マネージド オブジェクトとアンマネージド オブジェクトには異なる方法で公開されます。

マネージド コンパイラはメタデータからマネージド インターフェイスを生成し、結果として得られるインターフェイスは他のマネージド インターフェイスと同様です。 次の例は、一般的なインターフェイスを示しています。

public interface INew
{
    void NewMethod();
}

Public Interface INew
    Sub NewMethod()
End Interface

アンマネージ型は、インターフェイス定義言語 (IDL) で定義し、Microsoft インターフェイス定義言語 (MIDL) コンパイラを使用してコンパイルします。 次の例に示すように、ライブラリ ステートメント内でインターフェイスを定義し、ユニバーサル一意識別子 (UUID) 属性を持つインターフェイス ID を割り当てます。

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

MIDL コンパイラは、複数の出力ファイルを生成します。 インターフェイスが Old.idl で定義されている場合、出力ファイル Old_i.c は、次の例に示すように、インターフェイスのインターフェイス識別子 (IID) を持つ変数を定義 const します。

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

Old.h ファイルも MIDL によって生成されます。 これには、C++ ソース コードに含めることができるインターフェイスの C++ 定義が含まれています。

ICustomMarshaler インターフェイスを実装する

カスタム マーシャラーは、ランタイムに ICustomMarshaler 適切なラッパーを提供するインターフェイスを実装する必要があります。

次の C# コードは、すべてのカスタム マーシャラーによって実装される必要がある基本インターフェイスを表示します。

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には、変換のサポート、クリーンup のサポート、およびマーシャリングするデータに関する情報を提供するメソッドが含まれています。

変換

ICustomMarshaler.MarshalNativeToManaged

ネイティブ データへのポインターをマネージド オブジェクトにマーシャリングします。 このメソッドは、引数として渡されるアンマネージ インターフェイスをマーシャリングできるカスタム ランタイム呼び出し可能ラッパー (RCW) を返します。 マーシャラーは、その型のカスタム RCW のインスタンスを返す必要があります。

ICustomMarshaler.MarshalManagedToNative

マネージド オブジェクトをネイティブ データへのポインターにマーシャリングします。 このメソッドは、引数として渡されるマネージド インターフェイスをマーシャリングできるカスタム COM 呼び出し可能ラッパー (CCW) を返します。 マーシャラーは、その型のカスタム CCW のインスタンスを返す必要があります。

クリーンアップ

ICustomMarshaler.CleanUpNativeData

マーシャラーが、メソッドによってMarshalManagedToNative返されるネイティブ データ (CCW) をクリーンできるようにします。

ICustomMarshaler.CleanUpManagedData

マーシャラーが、メソッドによってMarshalNativeToManaged返されるマネージド データ (RCW) をクリーンできるようにします。

サイズ情報

ICustomMarshaler.GetNativeDataSize

マーシャリングするアンマネージ データのサイズを返します。

GetInstance メソッドを実装する

インターフェイスのICustomMarshaler実装に加えて、カスタム マーシャラーは、パラメーターとして a String をstatic受け取り、戻り値のICustomMarshaler型を持つ呼び出しGetInstanceメソッドを実装する必要があります。 この static メソッドは、カスタム マーシャラーのインスタンスをインスタンス化するために、共通言語ランタイムの COM 相互運用層によって呼び出されます。 渡される文字列は、返された GetInstance カスタム マーシャラーをカスタマイズするためにメソッドが使用できる Cookie です。 次の例は、最小限の完全 ICustomMarshaler な実装を示しています。

public class NewOldMarshaler : ICustomMarshaler
{
    public static ICustomMarshaler GetInstance(string pstrCookie)
        => new NewOldMarshaler();

    public Object MarshalNativeToManaged(IntPtr pNativeData) => throw new NotImplementedException();
    public IntPtr MarshalManagedToNative(Object ManagedObj) => throw new NotImplementedException();
    public void CleanUpNativeData(IntPtr pNativeData) => throw new NotImplementedException();
    public void CleanUpManagedData(Object ManagedObj) => throw new NotImplementedException();
    public int GetNativeDataSize() => throw new NotImplementedException();
}

MarshalAsAttribute を適用する

カスタム マーシャラーを使用するには、マーシャリングされるパラメーターまたはフィールドに属性を適用 MarshalAsAttribute する必要があります。

また、列挙値を UnmanagedType.CustomMarshaler コンストラクターに渡す MarshalAsAttribute 必要があります。 さらに、次のいずれかの名前付きパラメーターを MarshalType 持つフィールドを指定する必要があります。

• MarshalType (必須): カスタム マーシャラーのアセンブリ修飾名。 名前には、カスタム マーシャラーの名前空間とクラスを含める必要があります。 使用されているアセンブリでカスタム マーシャラーが定義されていない場合は、定義されているアセンブリの名前を指定する必要があります。

  Note

  フィールドの MarshalTypeRef 代わりにフィールドを MarshalType 使用できます。 MarshalTypeRef は、指定が容易な型を受け取ります。

• MarshalCookie (省略可能): カスタム マーシャラーに渡される Cookie。 Cookie を使用して、マーシャラーに追加情報を提供できます。 たとえば、同じマーシャラーを使用して多数のラッパーを提供する場合、Cookie は特定のラッパーを識別します。 クッキーはマーシャラーの GetInstance メソッドに渡されます。

この属性は MarshalAsAttribute 、適切なラッパーをアクティブ化できるように、カスタム マーシャラーを識別します。 次に、共通言語ランタイムの相互運用サービスは属性を調べ、引数 (パラメーターまたはフィールド) を初めてマーシャリングする必要がある場合にカスタム マーシャラーを作成します。

その後、ランタイムはカスタム マーシャラーのメソッドとMarshalManagedToNativeメソッドを呼び出して、呼びMarshalNativeToManaged出しを処理する正しいラッパーをアクティブにします。

カスタム マーシャラーを使用する

カスタム マーシャラーが完了したら、特定の型のカスタム ラッパーとして使用できます。 次の例は、マネージド インターフェイスの定義を IUserData 示しています。

interface IUserData
{
    void DoSomeStuff(INew pINew);
}

Public Interface IUserData
    Sub DoSomeStuff(pINew As INew)
End Interface

次の例では、インターフェイスはIUserDataカスタム マーシャラーをNewOldMarshaler使用して、アンマネージ クライアント アプリケーションがメソッドにインターフェイスDoSomeStuffをIOld渡せるようにします。 メソッドのマネージド記述は、前の DoSomeStuff 例に示すようにインターフェイスを受け取ります INew が、アンマネージ バージョンでは、次の DoSomeStuff 例に示すようにインターフェイス ポインターを受け取ります IOld 。

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

マネージド定義のエクスポートによって生成されるタイプ ライブラリは、標準定義 IUserData ではなく、この例に示すアンマネージ定義を生成します。 メソッドのINewマネージド定義の引数に適用される属性はMarshalAsAttribute、次のDoSomeStuff例に示すように、引数がカスタム マーシャラーを使用することを示します。

using System.Runtime.InteropServices;

Imports System.Runtime.InteropServices

interface IUserData
{
    void DoSomeStuff(
        [MarshalAs(UnmanagedType.CustomMarshaler,
         MarshalType="NewOldMarshaler")]
    INew pINew
    );
}

Public Interface IUserData
    Sub DoSomeStuff( _
        <MarshalAs(UnmanagedType.CustomMarshaler, _
        MarshalType := "MyCompany.NewOldMarshaler")> pINew As INew)
End Interface

前の例では、属性に指定された最初のMarshalAsAttributeパラメーターは列挙値UnmanagedType.CustomMarshalerですUnmanagedType.CustomMarshaler。

2 番目の MarshalType パラメーターは、カスタム マーシャラーのアセンブリ修飾名を提供するフィールドです。 この名前は、カスタム マーシャラー (MarshalType="MyCompany.NewOldMarshaler") の名前空間とクラスで構成されます。