構造体のマーシャリングをカスタマイズする

[アーティクル]
2023/05/10

構造体の既定のマーシャリング規則が、必要な規則とは異なる場合があります。 .NET ランタイムには、構造体のレイアウトやフィールドのマーシャリング方法をカスタマイズできる拡張ポイントがいくつか用意されています。構造のレイアウトのカスタマイズはすべてのシナリオでサポートされますが、フィールドのマーシャリングのカスタマイズは、ランタイムマーシャリングが有効になっているシナリオでのみサポートされます。ランタイムマーシャリングが無効になっている場合は、すべてのフィールドマーシャリングを手動で行う必要があります。

注意

この記事では、ソース生成の相互運用のためのマーシャリングのカスタマイズについては説明しません。 P/Invoke または COM に対するソース生成の相互運用を使っている場合は、マーシャリングのカスタマイズに関するページを参照してください。

構造レイアウトをカスタマイズする

.NET には System.Runtime.InteropServices.StructLayoutAttribute 属性と System.Runtime.InteropServices.LayoutKind 列挙型が用意されており、フィールドをメモリに配置する方法をカスタマイズできます。次のガイダンスを使用すると、一般的な問題を回避できます。

✔️ 推奨: 可能な限り LayoutKind.Sequential を使用するようにします。

✔️ 実行: ネイティブ構造体に共用体などの明示的なレイアウトもある場合にのみ、マーシャリングで LayoutKind.Explicit を使用します。

❌ 回避: クラスを使い、継承によって複雑なネイティブ型を表現しないようにしてください。

❌ 回避: .NET Core 3.0 より前のランタイムをターゲットにする必要がある場合、Windows 以外のプラットフォームで構造体をマーシャリングするときは LayoutKind.Explicit を使用しないでください。 3\.0 より前の .NET Core ランタイムは、Intel または AMD 64 ビットの Windows 以外のシステム上でネイティブ関数への値による明示的な構造体の受け渡しをサポートしていません。ただし、ランタイムはすべてのプラットフォーム上で明示的な構造体の参照渡しをサポートしています。

ブール値フィールドのマーシャリングのカスタマイズ

ネイティブコードには、さまざまなブール表現があります。 Windows だけでも、ブール値を表現する方法が 3 つあります。ランタイムは構造体のネイティブ定義を認識しないので、可能な最善の処理は、ブール値のマーシャリング方法を推測することです。 .NET ランタイムには、ブール値フィールドのマーシャリング方法を示す方法が用意されています。以下の例は、.NET bool をさまざまなネイティブブール型にマーシャリングする方法を示しています。

次の例に示すように、ブール値は既定でネイティブの 4 バイト Win32 BOOL 値としてマーシャリングされます。

public struct WinBool
{
    public bool b;
}

struct WinBool
{
    public BOOL b;
};

明示的にする場合は、UnmanagedType.Bool 値を使用して上記と同じ動作にすることができます。

public struct WinBool
{
    [MarshalAs(UnmanagedType.Bool)]
    public bool b;
}

struct WinBool
{
    public BOOL b;
};

以下の UnmanagedType.U1 値または UnmanagedType.I1 値を使用して、b フィールドを 1 バイトのネイティブ bool 型としてマーシャリングするようにランタイムに指示できます。

public struct CBool
{
    [MarshalAs(UnmanagedType.U1)]
    public bool b;
}

struct CBool
{
    public bool b;
};

Windows では、UnmanagedType.VariantBool 値を使用して、ブール値を 2 バイトの VARIANT_BOOL 値にマーシャリングするようにランタイムに指示できます。

public struct VariantBool
{
    [MarshalAs(UnmanagedType.VariantBool)]
    public bool b;
}

struct VariantBool
{
    public VARIANT_BOOL b;
};

注意

VARIANT_BOOL は、VARIANT_TRUE = -1 と VARIANT_FALSE = 0 が他のほとんどのブール型とは異なります。さらに、VARIANT_TRUE と等しくないすべての値は false と見なされます。

配列フィールドのマーシャリングのカスタマイズ

.NET には、配列のマーシャリングをカスタマイズする方法もいくつか用意されています。

既定では、.NET は要素の連続したリストへのポインターとして配列をマーシャリングします。

public struct DefaultArray
{
    public int[] values;
}

struct DefaultArray
{
    int32_t* values;
};

COM API とやり取りする場合は、必要に応じて配列を SAFEARRAY* オブジェクトとしてマーシャリングします。 System.Runtime.InteropServices.MarshalAsAttribute 値と UnmanagedType.SafeArray 値を使用して、配列を SAFEARRAY* としてマーシャリングするようにランタイムに指示できます。

public struct SafeArrayExample
{
    [MarshalAs(UnmanagedType.SafeArray)]
    public int[] values;
}

struct SafeArrayExample
{
    SAFEARRAY* values;
};

SAFEARRAY に含まれる要素の型をカスタマイズする必要がある場合は、MarshalAsAttribute.SafeArraySubType および MarshalAsAttribute.SafeArrayUserDefinedSubType フィールドを使用して SAFEARRAY の正確な要素の種類をカスタマイズできます。

インプレースで配列をマーシャリングする必要がある場合は、UnmanagedType.ByValArray 値を使用して、インプレースで配列をマーシャリングするようマーシャラーに指示できます。このマーシャリングを使用するときは、ランタイムが構造体の空間を適切に割り当てられるように、MarshalAsAttribute.SizeConst フィールドに配列内の要素数の値を指定する必要もあります。

public struct InPlaceArray
{
    [MarshalAs(UnmanagedType.ByValArray, SizeConst = 4)]
    public int[] values;
}

struct InPlaceArray
{
    int values[4];
};

注意

.NET は、C99 の柔軟な配列のメンバーとして可変長配列フィールドをマーシャリングすることをサポートしていません。

文字列フィールドのマーシャリングのカスタマイズ

.NET には、文字列フィールドをマーシャリングするためのさまざまなカスタマイズも用意されています。

既定では、.NET は文字列を null で終わる文字列へのポインターとしてマーシャリングします。エンコードは、System.Runtime.InteropServices.StructLayoutAttribute の StructLayoutAttribute.CharSet フィールドの値によって決まります。属性が指定されていない場合、エンコードは既定で ANSI エンコードになります。

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Ansi)]
public struct DefaultString
{
    public string str;
}

struct DefaultString
{
    char* str;
};

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
public struct DefaultString
{
    public string str;
}

struct DefaultString
{
    char16_t* str; // Could also be wchar_t* on Windows.
};

フィールドごとに異なるエンコードを使用する必要がある場合、または単に構造体の定義内でより明示的にする場合は、System.Runtime.InteropServices.MarshalAsAttribute 属性に UnmanagedType.LPStr 値または UnmanagedType.LPWStr 値を使用できます。

public struct AnsiString
{
    [MarshalAs(UnmanagedType.LPStr)]
    public string str;
}

struct AnsiString
{
    char* str;
};

public struct UnicodeString
{
    [MarshalAs(UnmanagedType.LPWStr)]
    public string str;
}

struct UnicodeString
{
    char16_t* str; // Could also be wchar_t* on Windows.
};

UTF-8 エンコードを使用して文字列をマーシャリングする場合は、MarshalAsAttribute に UnmanagedType.LPUTF8Str 値を使用できます。

public struct UTF8String
{
    [MarshalAs(UnmanagedType.LPUTF8Str)]
    public string str;
}

struct UTF8String
{
    char* str;
};

注意

UnmanagedType.LPUTF8Str を使用するには、.NET Framework 4.7 (またはそれ以降のバージョン) または .NET Core 1.1 (またはそれ以降のバージョン) のいずれかが必要です。 .NET Standard 2.0 では使用できません。

COM API を使用している場合は、文字列を BSTR としてマーシャリングする必要があります。 UnmanagedType.BStr 値を使用すると、文字列を BSTR としてマーシャリングできます。

public struct BString
{
    [MarshalAs(UnmanagedType.BStr)]
    public string str;
}

struct BString
{
    BSTR str;
};

WinRT ベースの API を使用している場合は、文字列を HSTRING としてマーシャリングする必要があります。 UnmanagedType.HString 値を使用すると、文字列を HSTRING としてマーシャリングできます。 HSTRING のマーシャリングは、組み込みの WinRT サポートを備えたランタイムでのみサポートされます。 WinRT のサポートは .NET 5 で削除されたので、HSTRING のマーシャリングは .NET 5 以降ではサポートされません。

public struct HString
{
    [MarshalAs(UnmanagedType.HString)]
    public string str;
}

struct BString
{
    HSTRING str;
};

API で、構造体でインプレースで文字列を渡す必要がある場合は、UnmanagedType.ByValTStr 値を使用できます。 ByValTStr でマーシャリングされた文字列のエンコードは、CharSet 属性によって決まる点に注意してください。さらに、文字列長を MarshalAsAttribute.SizeConst フィールドで渡す必要があります。

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Ansi)]
public struct DefaultString
{
    [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 4)]
    public string str;
}

struct DefaultString
{
    char str[4];
};

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
public struct DefaultString
{
    [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 4)]
    public string str;
}

struct DefaultString
{
    char16_t str[4]; // Could also be wchar_t[4] on Windows.
};

10 進数フィールドのマーシャリングのカスタマイズ

Windows を使用している場合は、ネイティブの CY または CURRENCY 構造体を使用する API がいくつかあります。既定で、.NET の decimal 型はネイティブの DECIMAL 構造体にマーシャリングされます。ただし、値が UnmanagedType.Currency の MarshalAsAttribute を使用して、decimal 値をネイティブの CY 値に変換するようにマーシャラーに指示することができます。

public struct Currency
{
    [MarshalAs(UnmanagedType.Currency)]
    public decimal dec;
}

struct Currency
{
    CY dec;
};

Unions

共用体は、同じメモリ上に異なる型のデータを含めることができるデータ型です。これは、C 言語のデータの一般的な形式です。共用体は、.NET では LayoutKind.Explicit を使って表すことができます。 .NET で共用体を定義するときは、構造体を使うことをお勧めします。クラスの使用は、レイアウトの問題が生じ、予期しない動作が発生する原因となるおそれがあります。

struct device1_config
{
    void* a;
    void* b;
    void* c;
};
struct device2_config
{
    int32_t a;
    int32_t b;
};
struct config
{
    int32_t type;

    union
    {
        device1_config dev1;
        device2_config dev2;
    };
};

public unsafe struct Device1Config
{
    void* a;
    void* b;
    void* c;
}

public struct Device2Config
{
    int a;
    int b;
}

public struct Config
{
    public int Type;

    public _Union Anonymous;

    [StructLayout(LayoutKind.Explicit)]
    public struct _Union
    {
        [FieldOffset(0)]
        public Device1Config Dev1;

        [FieldOffset(0)]
        public Device2Config Dev2;
    }
}

`System.Object` をマーシャリングする

Windows では、object 型のフィールドをネイティブコードにマーシャリングできます。このようなフィールドは、次の 3 つの型のいずれかにマーシャリングできます。

既定では、object 型のフィールドはオブジェクトをラップする IUnknown* にマーシャリングされます。

public struct ObjectDefault
{
    public object obj;
}

struct ObjectDefault
{
    IUnknown* obj;
};

オブジェクトフィールドを IDispatch* にマーシャリングする場合は、値が UnmanagedType.IDispatch の MarshalAsAttribute を追加します。

public struct ObjectDispatch
{
    [MarshalAs(UnmanagedType.IDispatch)]
    public object obj;
}

struct ObjectDispatch
{
    IDispatch* obj;
};

VARIANT としてマーシャリングする場合は、値が UnmanagedType.Struct の MarshalAsAttribute を追加します。

public struct ObjectVariant
{
    [MarshalAs(UnmanagedType.Struct)]
    public object obj;
}

struct ObjectVariant
{
    VARIANT obj;
};

次の表は、obj フィールドのさまざまなランタイム型が VARIANT に格納されるさまざまな型にどのようにマップされるかを示しています。

.NET 型	バリアント型
`byte`	`VT_UI1`
`sbyte`	`VT_I1`
`short`	`VT_I2`
`ushort`	`VT_UI2`
`int`	`VT_I4`
`uint`	`VT_UI4`
`long`	`VT_I8`
`ulong`	`VT_UI8`
`float`	`VT_R4`
`double`	`VT_R8`
`char`	`VT_UI2`
`string`	`VT_BSTR`
`System.Runtime.InteropServices.BStrWrapper`	`VT_BSTR`
`object`	`VT_DISPATCH`
`System.Runtime.InteropServices.UnknownWrapper`	`VT_UNKNOWN`
`System.Runtime.InteropServices.DispatchWrapper`	`VT_DISPATCH`
`System.Reflection.Missing`	`VT_ERROR`
`(object)null`	`VT_EMPTY`
`bool`	`VT_BOOL`
`System.DateTime`	`VT_DATE`
`decimal`	`VT_DECIMAL`
`System.Runtime.InteropServices.CurrencyWrapper`	`VT_CURRENCY`
`System.DBNull`	`VT_NULL`

GitHub で Microsoft と共同作業する

このコンテンツのソースは GitHub にあります。そこで、issue や pull request を作成および確認することもできます。詳細については、共同作成者ガイドを参照してください。

.NET に関するフィードバック

.NET はオープンソースプロジェクトです。フィードバックを提供するにはリンクを選択します。

ドキュメントの問題を開く製品フィードバックの提供

その他のリソース

ドキュメント

クラス、構造体、および共用体のマーシャリング - .NET Framework

クラス、構造体、および共用体をマーシャリングする方法を確認します。クラス、入れ子になった構造体を含む構造体、構造体の配列、および共用体のマーシャリングサンプルを表示します。
型のマーシャリング - .NET

.NET が型をネイティブ表現にマーシャリングする方法について説明します。
さまざまな型の配列のマーシャリング - .NET Framework

値渡しまたは参照渡しの整数、値渡しの 2 次元の整数、値渡しの文字列、および整数または文字列を含む構造体など、さまざまな配列の型をマーシャリングします。
文字列に対する既定のマーシャリング - .NET Framework

.NET でのインターフェイス、プラットフォーム呼び出し、構造体、固定長文字列バッファーの文字列に対する既定のマーシャリング動作について確認します。
配列に対する既定のマーシャリング - .NET Framework

配列に対する既定のマーシャリングについて説明します。マネージド配列、アンマネージド配列、.NET コードへの配列パラメーターの受け渡し、および COM への配列の受け渡しについて説明します。
文字セットとマーシャリング - .NET

CharSet の値によって、.NET でデータをネイティブコードにマーシャリングする方法がどのように変わるかについて説明します。

トレーニング

モジュール

C# コードで正しいデータ型を選択する - Training

C# で使われる複数の基本型から、コードに適したデータ型を選びます。

events

AI アプリとエージェントの構築

3月17日 21時 - 3月21日 10時

meetup シリーズに参加して、実際のユースケースに基づくスケーラブルな AI ソリューションを、仲間の開発者や専門家と共に構築します。

今すぐ登録

次の方法で共有