HN 日本語サマリー

← 一覧へ戻る
プログラミング

MemoryPack: C#向けのエンコーディング不要で極めて高性能なバイナリシリアライザー

MemoryPack: Zero encoding extreme performance binary serializer for C# (github.com)

14 pointsby breve3 コメント

要約

MemoryPackは、C#およびUnity向けの、エンコーディング不要で極めて高性能なバイナリシリアライザーです。System.Text.JsonやMessagePack for C#などの既存シリアライザーと比較して、標準オブジェクトで最大10倍、構造体配列では最大200倍高速であることを謳っています。C#に特化した最適化されたバイナリフォーマットと、.NET 7およびC# 11の機能を活用したソースジェネレーターベースのコード生成により、高いパフォーマンスとメモリ効率を実現しています。

全文翻訳

MemoryPack

[画像: NuGet] [画像: GitHub Actions] [画像: Releases]

C#およびUnity向けのゼロエンコーディング超高速バイナリシリアライザー。

[画像: image]

System.Text.Json, protobuf-net, MessagePack for C#, Orleans.Serialization との比較。 .NET 7 / Ryzen 9 5950X マシンで測定。これらのシリアライザーは IBufferWriter<byte> メソッドを持ち、ArrayBufferWriter<byte> を使用してシリアル化し、バッファコピーの測定を避けるために再利用しました。

標準オブジェクトの場合、MemoryPackは他のバイナリシリアライザーと比較して10倍高速で、2〜5倍高速です。構造体配列の場合、MemoryPackはさらに強力で、他のシリアライザーよりも最大50〜200倍高速です。

MemoryPackは私の4番目のシリアライザーであり、以前は有名なシリアライザーであるZeroFormatter、Utf8Json、MessagePack for C# を作成しました。MemoryPackの速度の理由は、C#固有でC#に最適化されたバイナリフォーマットと、過去の経験に基づいた調整済みの実装にあります。また、.NET 7およびC# 11、Incremental Source Generator(.NET Standard 2.1(.NET 5, 6)およびUnityサポートも利用可能)を活用した完全に新しい設計です。

他のシリアライザーは、VarIntエンコーディング、タグ、文字列などの多くのエンコーディング操作を実行します。MemoryPackフォーマットは、C#のメモリを可能な限りコピーするゼロエンコーディング設計を使用しています。ゼロエンコーディングはFlatBuffersに似ていますが、特別な型を必要とせず、MemoryPackのシリアル化ターゲットはPOCOです。

パフォーマンス以外にも、MemoryPackには以下の機能があります。

  • モダンなI/O API(IBufferWriter<byte>, ReadOnlySpan<byte>, ReadOnlySequence<byte>)のサポート
  • ネイティブAOTフレンドリーなソースジェネレーターベースのコード生成、動的コード生成(IL.Emit)なし
  • リフレクションレスな非ジェネリックAPI
  • 既存インスタンスへのデシリアライズ
  • ポリモーフィズム(Union)シリアル化
  • 限定的なバージョン耐性(高速/デフォルト)と完全なバージョン耐性サポート
  • 循環参照シリアル化
  • PipeWriter/Readerベースのストリーミングシリアル化
  • TypeScriptコード生成およびASP.NET Core Formatter
  • .NET Source Generatorを介したUnity(2021.3)IL2CPPサポート

インストール

このライブラリはNuGet経由で配布されます。最高のパフォーマンスを得るには、.NET 7の使用を推奨します。最小要件は.NET Standard 2.1です。

PM> Install-Package MemoryPack

また、コードエディターはRoslyn 4.3.1のサポートが必要です。例えば、Visual Studio 2022バージョン17.3、.NET SDK 6.0.401などです。詳細はRoslynバージョンサポートドキュメントを参照してください。

Unityの場合、要件とインストールプロセスは完全に異なります。詳細はUnityセクションを参照してください。

クイックスタート

シリアル化する構造体またはクラスを定義し、[MemoryPackable]属性とpartialキーワードで注釈を付けます。

using MemoryPack;

[MemoryPackable]
public partial class Person
{
    public int Age { get; set; }
    public string Name { get; set; }
}

シリアル化コードは、IMemoryPackable<T>インターフェースを実装するC#ソースジェネレーター機能によって生成されます。Visual Studioでは、クラス名上でショートカット Ctrl+K, R を使用し、*.MemoryPackFormatter.g.cs を選択することで生成されたコードを確認できます。

MemoryPackSerializer.Serialize<T>/Deserialize<T> を呼び出して、オブジェクトインスタンスをシリアル化/デシリアル化します。

var v = new Person { Age = 40, Name = "John" };

var bin = MemoryPackSerializer.Serialize(v);
var val = MemoryPackSerializer.Deserialize<Person>(bin);

Serializeメソッドは、byte[]の戻り値型をサポートするだけでなく、IBufferWriter<byte>またはStreamにシリアル化できます。Deserializeメソッドは、ReadOnlySpan<byte>, ReadOnlySequence<byte>, Streamをサポートします。また、非ジェネリックバージョンもあります。

標準サポート型

これらの型はデフォルトでシリアル化できます:

  • .NETプリミティブ (byte, int, bool, char, doubleなど)
  • アンマネージド型(参照型を含まない任意のenum、任意のユーザー定義struct)
  • string, decimal, Half, Int128, UInt128, Guid, Rune, BigInteger
  • TimeSpan, DateTime, DateTimeOffset, TimeOnly, DateOnly, TimeZoneInfo
  • Complex, Plane, Quaternion Matrix3x2, Matrix4x4, Vector2, Vector3, Vector4
  • Uri, Version, StringBuilder, Type, BitArray, CultureInfo
  • T[], T[,], T[,,], T[,,,], Memory<>, ReadOnlyMemory<>, ArraySegment<>, ReadOnlySequence<>
  • Nullable<>, Lazy<>, KeyValuePair<,>, Tuple<,...>, ValueTuple<,...>
  • List<>, LinkedList<>, Queue<>, Stack<>, HashSet<>, SortedSet<>, PriorityQueue<,>
  • Dictionary<,>, SortedList<,>, SortedDictionary<,>, ReadOnlyDictionary<,>
  • Collection<>, ReadOnlyCollection<>, ObservableCollection<>, ReadOnlyObservableCollection<>
  • IEnumerable<>, ICollection<>, IList<>, IReadOnlyCollection<>, IReadOnlyList<>, ISet<>
  • IDictionary<,>, IReadOnlyDictionary<,>, ILookup<,>, IGrouping<,>
  • ConcurrentBag<>, ConcurrentQueue<>, ConcurrentStack<>, ConcurrentDictionary<,>, BlockingCollection<>
  • Immutableコレクション(ImmutableList<>など)およびインターフェース(IImmutableList<>など)

[MemoryPackable] class / struct / record / record struct の定義

[MemoryPackable] は、任意の class, struct, record, record struct, interface に注釈を付けることができます。型が参照型を含まない struct または record struct (C# のアンマネージド型)の場合、追加の注釈(ignore, include, constructor, callbacks)は使用されず、メモリから直接シリアル化/デシリアル化されます。

それ以外の場合、デフォルトで [MemoryPackable] はパブリックなインスタンスプロパティまたはフィールドをシリアル化します。シリアル化対象から除外するには [MemoryPackIgnore] を使用し、プライベートメンバーをシリアル化対象に昇格させるには [MemoryPackInclude] を使用します。

[MemoryPackable]
public partial class Sample
{
    // これらの型はデフォルトでシリアル化されます
    public int PublicField;
    public readonly int PublicReadOnlyField;
    public int PublicProperty { get; set; }
    public int PrivateSetPublicProperty { get; private set; }
    public int ReadOnlyPublicProperty { get; }
    public int InitProperty { get; init; }
    public required int RequiredInitProperty { get; init; }

    // これらの型はデフォルトでシリアル化されません
    int privateProperty { get; set; }
    int privateField;
    readonly int privateReadOnlyField;

    // [MemoryPackIgnore] を使用して、パブリックメンバーの対象を除外します
    [MemoryPackIgnore]
    public int PublicProperty2 => PublicProperty + PublicField;

    // [MemoryPackInclude] を使用して、プライベートメンバーをシリアル化対象に昇格させます
    [MemoryPackInclude]
    int privateField2;
    [MemoryPackInclude]
    int privateProperty2 { get; set; }
}

MemoryPackのコードジェネレーターは、どのメンバーがシリアル化されるかについての情報を <remarks /> セクションに追加します。これは、IntelliSenseで型にカーソルを合わせると表示されます。

[画像: image]

すべてのメンバーはmemorypackでシリアル化可能である必要があります。そうでない場合、コードジェネレーターはエラーを生成します。

[画像: image]

MemoryPackには、快適に定義するための35個の診断ルール(MEMPACK001からMEMPACK035)があります。

ターゲット型がMemoryPackシリアル化を外部で定義し登録されている場合、診断を抑制するために[MemoryPackAllowSerialize]を使用します。

[MemoryPackable]
public partial class Sample2
{
    [MemoryPackAllowSerialize]
    public NotSerializableType? NotSerializableProperty { get; set; }
}

メンバーの順序は重要です。MemoryPackはメンバー名やその他の情報をシリアル化せず、宣言された順序でフィールドをシリアル化します。型が継承されている場合、シリアル化は親→子の順序で行われます。メンバーの順序はデシリアライズのために変更できません。スキーマ進化については、バージョン耐性セクションを参照してください。

デフォルトの順序はシーケンシャルですが、[MemoryPackable(SerializeLayout.Explicit)]と[MemoryPackOrder()]を使用して明示的なレイアウトを選択できます。

// Prop0 -> Prop1 をシリアル化
[MemoryPackable(SerializeLayout.Explicit)]
public partial class SampleExplicitOrder
{
    [MemoryPackOrder(1)]
    public int Prop1 { get; set; }
    [MemoryPackOrder(0)]
    public int Prop0 { get; set; }
}
コンストラクタの選択

MemoryPackは、パラメータ付きおよびパラメータなしコンストラクタの両方をサポートします。コンストラクタの選択は以下のルールに従います(クラスおよび構造体に適用)。

  • [MemoryPackConstructor]がある場合、それを使用します。
  • 明示的なコンストラクタ(プライベートを含む)がない場合、パラメータなしコンストラクタを使用します。
  • パラメータなし/パラメータ付きコンストラクタが1つある場合(プライベートを含む)、それを使用します。
  • 複数のコンストラクタがある場合、[MemoryPackConstructor]属性を目的のコンストラクタに適用する必要があります(ジェネレーターは自動的に選択しません)。それ以外の場合、ジェネレーターはエラーを生成します。
  • パラメータ付きコンストラクタを使用する場合、すべてのパラメータ名は対応するメンバー名と一致する必要があります(大文字小文字を区別しない)。
[MemoryPackable]
public partial class Person
{
    public readonly int Age;
    public readonly string Name;

    // パラメータ付きコンストラクタを使用できます - パラメータ名は対応するメンバー名と一致する必要があります(大文字小文字を区別しない)
    public Person(int age, string name)
    {
        this.Age = age;
        this.Name = name;
    }
}

// レコードのプライマリコンストラクタもサポートします
[MemoryPackable]
public partial record Person2(int Age, string Name);

public partial class Person3
{
    public int Age { get; set; }
    public string Name { get; set; }

    public Person3()
    {
    }

    // 複数のコンストラクタがある場合、[MemoryPackConstructor] を使用する必要があります
    [MemoryPackConstructor]
    public Person3(int age, string name)
    {
        this.Age = age;
        this.Name = name;
    }
}
シリアル化コールバック

シリアル化/デシリアル化時、MemoryPackは [MemoryPackOnSerializing], [MemoryPackOnSerialized], [MemoryPackOnDeserializing], [MemoryPackOnDeserialized] 属性を使用して、イベントの前後を呼び出すことができます。これらは静的メソッドとインスタンス(非静的)メソッドの両方、パブリックおよびプライベートメソッドに注釈を付けることができます。

[MemoryPackable]
public partial class MethodCallSample
{
    // メソッド呼び出し順序は static -> instance
    [MemoryPackOnSerializing]
    public static void OnSerializing1()
    {
        Console.WriteLine(nameof(OnSerializing1));
    }

    // プライベートメソッドも許可されます
    [MemoryPackOnSerializing]
    void OnSerializing2()
    {
        Console.WriteLine(nameof(OnSerializing2));
    }

    // serializing -> /* serialize */ -> serialized
    [MemoryPackOnSerialized]
    static void OnSerialized1()
    {
        Console.WriteLine(nameof(OnSerialized1));
    }

    [MemoryPackOnSerialized]
    public void OnSerialized2()
    {
        Console.WriteLine(nameof(OnSerialized2));
    }

    [MemoryPackOnDeserializing]
    public static void OnDeserializing1()
    {
        Console.WriteLine(nameof(OnDeserializing1));
    }

    // 注意: MemoryPackOnDeserializing を持つインスタンスメソッドは、インスタンスが `ref` で渡されない限り呼び出されません
    [MemoryPackOnDeserializing]
    public void OnDeserializing2()
    {
        Console.WriteLine(nameof(OnDeserializing2));
    }

    [MemoryPackOnDeserialized]
    public static void OnDeserialized1()
    {
        Console.WriteLine(nameof(OnDeserialized1));
    }

    [MemoryPackOnDeserialized]
    public void OnDeserialized2()
    {
        Console.WriteLine(nameof(OnDeserialized2));
    }
}

コールバックは、パラメータなしメソッドと ref reader/writer, ref T value メソッドを許可します。例えば、refコールバックはシリアル化プロセスの前にカスタムヘッダーを書き込んだり読み込んだりできます。

[MemoryPackable]
public partial class EmitIdData
{
    public int MyProperty { get; set; }

    [MemoryPackOnSerializing]
    static void WriteId<TBufferWriter>(ref MemoryPackWriter<TBufferWriter> writer, ref EmitIdData? value)
        where TBufferWriter : IBufferWriter<byte> // .NET Standard 2.1, use where TBufferWriter : class, IBufferWriter<byte>
    {
        writer.WriteUnmanaged(Guid.NewGuid()); // GUID をヘッダーにエミットします。
    }

    [MemoryPackOnDeserializing]
    static void ReadId(ref MemoryPackReader reader, ref EmitIdData? value)
    {
        // デシリアライズ前にカスタムヘッダーを読み取ります
        var guid = reader.ReadUnmanaged<Guid>();
        Console.WriteLine(guid);
    }
}

ref value に値を設定すると、シリアル化/デシリアル化に使用される値を変更できます。例えば、ServiceProviderからインスタンス化します。

// このフォーマッタを使用する前に、ServiceProvider を設定します
// var options = MemoryPackSerializerOptions.Default with { ServiceProvider = provider };
// MemoryPackSerializer.Deserialize(value, options);

[MemoryPackable]
public partial class InstantiateFromServiceProvider
{
    static IServiceProvider serviceProvider = default!;

    public int MyProperty { get; private set; }

    [MemoryPackOnDeserializing]
    static void OnDeserializing(ref MemoryPackReader reader, ref InstantiateFromServiceProvider value)
    {
        if (value != null) return;
        value = reader.Options.ServiceProvider!.GetRequiredService<InstantiateFromServiceProvider>();
    }
}

カスタムコレクションの定義

デフォルトでは、注釈付きの[MemoryPackObject]型はメンバーのシリアル化を試みます。しかし、型がコレクション(ICollection<>, ISet<>, IDictionary<,>)の場合、正しくシリアル化するには GenerateType.Collection を使用します。

[MemoryPackable(GenerateType.Collection)]
public partial class MyList<T> : List<T>
{
}

[MemoryPackable(GenerateType.Collection)]
public partial class MyStringDictionary<TValue> : Dictionary<string, TValue>
{

}

静的コンストラクタ

生成される部分クラスが使用するため、MemoryPackableクラスは静的コンストラクタを定義できません。代わりに、static partial void StaticConstructor() を定義して同じことを行うことができます。

[MemoryPackable]
public partial class CctorSample
{
    static partial void StaticConstructor()
    {
    }
}

ポリモーフィズム(Union)

MemoryPackは、ポリモーフィズムシリアル化のためにインターフェースおよび抽象クラスオブジェクトのシリアル化をサポートします。MemoryPackでは、この機能をUnionと呼びます。[MemoryPackUnion]属性はインターフェースと抽象クラスにのみ適用できます。一意のユニオンタグが必要です。

// [MemoryPackable] および継承型に [MemoryPackUnion] で注釈を付けます
// Union は抽象クラスもサポートします
[MemoryPackable]
[MemoryPackUnion(0, typeof(FooClass))]
[MemoryPackUnion(1, typeof(BarClass))]
public partial interface IUnionSample
{
}

[MemoryPackable]
public partial class FooClass : IUnionSample
{
    public int XYZ { get; set; }
}

[MemoryPackable]
public partial class BarClass : IUnionSample
{
    public string? OPQ { get; set; }
}
// ---

IUnionSample data = new FooClass() { XYZ = 999 };

// インターフェース型としてシリアル化します。
var bin = MemoryPackSerializer.Serialize(data);

// インターフェース型としてデシリアライズします。
var reData = MemoryPackSerializer.Deserialize<IUnionSample>(bin);

switch (reData)
{
    case FooClass x:
        Console.WriteLine(x.XYZ);
        break;
    case BarClass x:
        Console.WriteLine(x.OPQ);
        break;
    default:
        break;
}

tagは0〜65535まで許可され、特に250未満では効率的です。

インターフェースと派生型が異なるアセンブリにある場合、代わりにMemoryPackUnionFormatterAttributeを使用できます。フォーマッタは、C# 9.0以降ではModuleInitializerを介して自動的に登録されるように生成されます。

ModuleInitializerはUnityではサポートされていないため、フォーマッタは手動で登録する必要があります。ユニオンフォーマッタを登録するには、Startupで{your union formatter name}Initializer.RegisterFormatter()を手動で呼び出します。例:UnionSampleFormatterInitializer.RegisterFormatter()。

// AssemblyA
[MemoryPackable(GenerateType.NoGenerate)]
public partial interface IUnionSample
{
}

// AssemblyB はターゲット型外で定義します
[MemoryPackUnionFormatter(typeof(IUnionSample))]
[MemoryPackUnion(0, typeof(FooClass))]
[MemoryPackUnion(1, typeof(BarClass))]
public partial class UnionSampleFormatter
{
}

UnionはDynamicUnionFormatter<T>を介してコードで組み立てることができます。

// (ushort, Type)[]
var formatter = new DynamicUnionFormatter<IFooBarBaz>(
    (0, typeof(Foo)),
    (1, typeof(Bar)),
    (2, typeof(Baz))
);

MemoryPackFormatterProvider.Register(formatter);

シリアル化API

Serializeには3つのオーバーロードがあります。

// 非ジェネリックAPIも利用可能です。これらのバージョンは、最初の引数がTypeで、値はobject?です。
byte[] Serialize<T>(in T? value, MemoryPackSerializerOptions? options = default)
void Serialize<T, TBufferWriter>(in TBufferWriter bufferWriter, in T? value, MemoryPackSerializerOptions? options = default)
async ValueTask SerializeAsync<T>(Stream stream, T? value, MemoryPackSerializerOptions? options = default, CancellationToken cancellationToken = default)

パフォーマンスのために、推奨されるAPIはBufferWriterを使用します。これはバッファに直接シリアル化します。これはSystem.IO.PipelinesのPipeWriter、ASP.NET CoreのBodyWriterなどに適用できます。

byte[]が必要な場合(例:StackExchange.RedisのRedisValue)、戻り値のbyte[] APIはシンプルでほぼ同等の速度です。

SerializeAsync for Streamは、Flushのためだけの非同期です。すべてのデータを一度MemoryPackの内部プールバッファに読み込み、その後WriteAsyncを使用して書き込みます。したがって、バッファとフラッシュを分離・制御するBufferWriterオーバーロードの方が優れています。

完全なストリーミング書き込みを行いたい場合は、ストリーミングシリアル化セクションを参照してください。

MemoryPackSerializerOptions

MemoryPackSerializerOptionsは、文字列がUTF16またはUTF8としてシリアル化されるかどうかを構成します。これは、UTF8エンコーディングの場合はMemoryPackSerializerOptions.Utf8、UTF16エンコーディングの場合はMemoryPackSerializerOptions.Utf16、またはデフォルトでUTF8になるMemoryPackSerializerOptions.Defaultを渡すことで構成できます。nullを渡すか、デフォルトパラメータを使用するとUTF8エンコーディングになります。

C#の内部文字列表現はUTF16であるため、UTF16の方がパフォーマンスは向上します。ただし、ペイロードは大きくなる傾向があります。UTF8では、ASCII文字列は1バイトですが、UTF16では2バイトになります。このペイロードサイズの差が非常に大きいため、デフォルトではUTF8が設定されています。

データが非ASCII(例えば、3バイト以上になる可能性があり、UTF8の方が大きい日本語)の場合、または別途圧縮する必要がある場合、UTF16の方が良い結果をもたらす可能性があります。

UTF8またはUTF16はシリアル化時に選択できますが、デシリアライズ時に指定する必要はありません。自動的に検出され、正常にデシリアライズされます。

さらに、オプションからIServiceProvider? ServiceProvider { get; init; }を取得/設定できます。これは、シリアル化プロセス(MemoryPackReader/MemoryPackWriterには.Optionsプロパティがあります)からDIオブジェクト(ILogger<T>など)を取得するのに役立ちます。

デシリアライズAPI

Deserializeには、ReadOnlySpan<byte>、ReadOnlySequence<byte>、Streamのオーバーロードとrefサポートがあります。

T? Deserialize<T>(ReadOnlySpan<byte> buffer)
int Deserialize<T>(ReadOnlySpan<byte> buffer, ref T? value)
T? Deserialize<T>(in ReadOnlySequence<byte> buffer)
int Deserialize<T>(in ReadOnlySequence<byte> buffer, ref T? value)
async ValueTask<T?> DeserializeAsync<T>(Stream stream)

refオーバーロードは既存のインスタンスを上書きします。詳細は上書きセクションを参照してください。

DeserializeAsync(Stream)は完全なストリーミング読み取り操作ではありません。まず、ストリームの終端までMemoryPackの内部プールに読み込み、その後デシリアライズします。

完全なストリーミング読み取り操作を行いたい場合は、ストリーミングシリアル化セクションを参照してください。

上書き

割り当てを削減するために、MemoryPackは既存のインスタンスへのデシリアライズをサポートし、それを上書きします。これはDeserialize(ref T? value)オーバーロードで使用できます。

var person = new Person();
var bin = MemoryPackSerializer.Serialize(person);

// 既存のインスタンスにデータを上書きします。
MemoryPackSerializer.Deserialize(bin, ref person);

MemoryPackは可能な限り上書きを試みますが、以下の条件が一致しない場合は、新しいインスタンスを作成します(通常のデシリアライズと同様)。

  • ref値(オブジェクトグラフ内のメンバーを含む)がnullの場合、新しいインスタンスを設定します。
  • パラメータなしコンストラクタのみ許可されます。パラメータ付きコンストラクタが使用される場合は、新しいインスタンスを作成します。
  • 値がT[]の場合、長さが同じ場合にのみ再利用します。それ以外の場合は新しいインスタンスを作成します。
  • 値が.Clear()メソッドを持つコレクション(List<>, Stack<>, Queue<>, LinkedList<>, HashSet<>, PriorityQueue<,>, ObservableCollection, Collection, ConcurrentQueue<>, ConcurrentStack<>, ConcurrentBag<>, Dictionary<,>, SortedDictionary<,>, SortedList<,>, ConcurrentDictionary<,>)の場合、Clear()を呼び出して再利用します。それ以外の場合は新しいインスタンスを作成します。

バージョン耐性

デフォルト(GenerateType.Object)では、MemoryPackは限定的なスキーマ進化をサポートします。

  • アンマネージド構造体は変更できなくなります。
  • メンバーは追加できますが、削除はできません。
  • メンバー名を変更できます。
  • メンバーの順序を変更できません。
  • メンバーの型を変更できません。
[MemoryPackable]
public partial class VersionCheck
{
    public int Prop1 { get; set; }
    public long Prop2 { get; set; }
}

// 追加はOKです。
[MemoryPackable]
public partial class VersionCheck
{
    public int Prop1 { get; set; }
    public long Prop2 { get; set; }
    public int? AddedProp { get; set; }
}

// 削除はNGです。
[MemoryPackable]
public partial class VersionCheck
{
    // public int Prop1 { get; set; }
    public long Prop2 { get; set; }
}

// 順序変更はNGです。
[MemoryPackable]
public partial class VersionCheck
{
    public long Prop2 { get; set; }
    public int Prop1 { get; set; }
}

ユースケースでは、古いデータを(ファイルやRedisなどに)保存し、新しいスキーマに読み込むことは常に可能です。RPCシナリオでは、クライアントとサーバーの両方にスキーマが存在するため、クライアントはサーバーより前に更新する必要があります。更新されたクライアントは古いサーバーに問題なく接続できますが、古いクライアントは新しいサーバーに接続できません。

デフォルトでは、古いデータを新しいスキーマに読み込む際に、データ側に存在しないメンバーはdefaultリテラルで初期化されます。この動作を避け、フィールド/プロパティの初期値を使用したい場合は、[SuppressDefaultInitialization]を使用できます。

[MemoryPackable]
public partial class DefaultValue
{
    public string Prop1 { get; set; }

    [SuppressDefaultInitialization]
    public int Prop2 { get; set; } = 111; // 古いデータが見つからない場合、`111`が設定されます。
    
    public int Prop3 { get; set; } = 222; // 古いデータが見つからない場合、`default`が設定されます。
}

[SuppressDefaultInitialization]には以下の制限があります。

  • readonly、init-only、required修飾子とは一緒に使用できません。

次のシリアル化情報セクションでは、CIなどでスキーマ変更をチェックし、事故を防ぐ方法を示します。

GenerateType.VersionTolerantを使用すると、完全なバージョン耐性がサポートされます。

  • アンマネージド構造体は一切変更できません。
  • すべてのメンバーは(SerializeLayout.Sequentialに注釈が付いている場合を除き)[MemoryPackOrder]を明示的に追加する必要があります。
  • メンバーの追加、削除は可能ですが、順序の再利用はできません(欠落した順序を使用できます)。
  • メンバー名を変更できます。
  • メンバーの順序を変更できません。
  • メンバーの型を変更できません。
// VersionTolerantObject1 -> VersionTolerantObject2 および
// VersionTolerantObject2 -> VersionTolerantObject1 の両方をシリアル化/デシリアル化しても問題ありません

[MemoryPackable(GenerateType.VersionTolerant)]
public partial class VersionTolerantObject1
{
    [MemoryPackOrder(0)]
    public int MyProperty0 { get; set; } = default;

    [MemoryPackOrder(1)]
    public long MyProperty1 { get; set; } = default;

    [MemoryPackOrder(2)]
    public short MyProperty2 { get; set; } = default;
}

[MemoryPackable(GenerateType.VersionTolerant)]
public partial class VersionTolerantObject2
{
    [MemoryPackOrder(0)]
    public int MyProperty0 { get; set; } = default;

    // 削除済み
    //[MemoryPackOrder(1)]
    //public long MyProperty1 { get; set; } = default;

    [MemoryPackOrder(2)]
    public short MyProperty2 { get; set; } = default;

    // 追加済み
    [MemoryPackOrder(3)]
    public short MyProperty3 { get; set; } = default;
}
// SerializeLayout.Sequential を明示的に設定した場合、順序が自動的に許可されます。
// ただし、バージョン耐性のためメンバーを削除することはできません。
[MemoryPackable(GenerateType.VersionTolerant, SerializeLayout.Sequential)]
public partial class VersionTolerantObject3
{
    public int MyProperty0 { get; set; } = default;
    public long MyProperty1 { get; set; } = default;
    public short MyProperty2 { get; set; } = default;
}

GenerateType.VersionTolerant は GenerateType.Object よりもシリアル化が遅くなります。また、ペイロードサイズもわずかに大きくなります。

シリアル化情報

型内のIntelliSenseで、どのメンバーがシリアル化されるかを確認できます。コンパイル時にその情報をファイルに書き出すオプションがあります。以下のように MemoryPackGenerator_SerializationInfoOutputDirectory を設定します。

<!-- memorypack シリアル化情報をディレクトリに出力 -->
<ItemGroup>
    <CompilerVisibleProperty Include="MemoryPackGenerator_SerializationInfoOutputDirectory" />
</ItemGroup>
<PropertyGroup>
    <MemoryPackGenerator_SerializationInfoOutputDirectory>$(MSBuildProjectDirectory)\MemoryPackLogs</MemoryPackGenerator_SerializationInfoOutputDirectory>
</PropertyGroup>

ファイルには以下の情報が書き込まれます。

[画像: image]

型がアンマネージドの場合、型名の前にunmanagedと表示されます。

unmanaged FooStruct
---
int x
int y

このファイルの差分を確認することで、危険なスキーマ変更を防ぐことができます。例えば、CIを使用して以下のルールを検出したい場合があります。

  • アンマネージド型の変更
  • メンバー順序の変更
  • メンバーの削除

循環参照

MemoryPackは循環参照もサポートしています。これにより、ツリーオブジェクトをそのままシリアル化できます。

// 循環参照を有効にするには、GenerateType.CircularReference を使用します
[MemoryPackable(GenerateType.CircularReference)]
public partial class Node
{
    [MemoryPackOrder(0)]
    public Node? Parent { get; set; }
    [MemoryPackOrder(1)]
    public Node[]? Children { get; set; }
}

例えば、System.Text.Json の参照の保持コードは以下のようになります。

// https://learn.microsoft.com/en-us/dotnet/standard/serialization/system-text-json/preserve-references?pivots=dotnet-7-0
Employee tyler = new() 
{
    Name = "Tyler Stein"
};

Employee adrian = new() 
{
    Name = "Adrian King"
};

tyler.DirectReports = new List<Employee> { adrian };
adrian.Manager = tyler;

var bin = MemoryPackSerializer.Serialize(tyler);
Employee? tylerDeserialized = MemoryPackSerializer.Deserialize<Employee>(bin);

Console.WriteLine(tylerDeserialized?.DirectReports?[0].Manager == tylerDeserialized); // true

[MemoryPackable(GenerateType.CircularReference)]
public partial class Employee
{
    [MemoryPackOrder(0)]
    public string? Name { get; set; }
    [MemoryPackOrder(1)]
    public Employee? Manager { get; set; }
    [MemoryPackOrder(2)]
    public List<Employee>? DirectReports { get; set; }
}

GenerateType.CircularReference はバージョン耐性と同じ特性を持ちます。ただし、追加の制約として、パラメータなしコンストラクタのみが許可されます。また、オブジェクト参照の追跡は GenerateType.CircularReference でマークされたオブジェクトに対してのみ行われます。他のオブジェクトを追跡したい場合は、ラップしてください。

CustomFormatter

MemoryPackCustomFormatterAttribute<T> または MemoryPackCustomFormatterAttribute<TFormatter, T>(より高性能ですが複雑です)を実装すると、MemoryPackObjectのメンバーにカスタムフォーマッタを使用するように構成できます。

[AttributeUsage(AttributeTargets.Field | AttributeTargets.Property, AllowMultiple = false, Inherited = false)]
public abstract class MemoryPackCustomFormatterAttribute<T> : Attribute
{
    public abstract IMemoryPackFormatter<T> GetFormatter();
}

MemoryPackは以下のフォーマット属性を提供します:Utf8StringFormatterAttribute, Utf16StringFormatterAttribute, InternStringFormatterAttribute, OrdinalIgnoreCaseStringDictionaryFormatter<TValue>, BitPackFormatterAttribute, BrotliFormatter, BrotliStringFormatter, BrotliFormatter<T>, MemoryPoolFormatter<T>, ReadOnlyMemoryPoolFormatter<T>。

[MemoryPackable]
public partial class Sample
{
    // このメンバーをUTF16文字列としてシリアル化します。UTF8よりもパフォーマンスが良いですが、ASCIIの場合、サイズは大きくなります(ただし、非ASCIIの場合は小さいこともあります)。
    [Utf16StringFormatter]
    public string? Text { get; set; }

    // デシリアライズ時、DictionaryはStringComparer.OrdinalIgnoreCaseで初期化されます。
    [OrdinalIgnoreCaseStringDictionaryFormatter<int>]
    public Dictionary<string, int>? Ids { get; set; }
    
    // デシリアライズ時、すべての文字列がインターン化されます(String.Internを参照)。同様の値が繰り返し出現する場合、メモリが節約されます。
    [InternStringFormatter]
    public string? Flag { get; set; }
}

セット/辞書の比較子を構成するために、すべての組み込みフォーマッタにはコンストラクタオーバーロードがあります。カスタム比較子フォーマッタを簡単に作成できます。

public sealed class OrdinalIgnoreCaseStringDictionaryFormatter<TValue> : MemoryPackCustomFormatterAttribute<Dictionary<string, TValue?>>
{
    static readonly DictionaryFormatter<string, TValue?> formatter = new DictionaryFormatter<string, TValue?>(StringComparer.OrdinalIgnoreCase);

    public override IMemoryPackFormatter<Dictionary<string, TValue?>> GetFormatter()
    {
        return formatter;
    }
}

BitPackFormatterはbool[]型のみを圧縮します。bool[]は通常、ブール値ごとに1バイトとしてシリアル化されますが、BitPackFormatterはbool[]をBitArrayのように各ブール値を1ビットとして格納します。BitPackFormatterを使用すると、8つのブール値が通常8バイトになるところを1バイトで表現できるため、サイズが8倍小さくなります。

[MemoryPackable]
public partial class Sample
{
    public int Id { get; set; }

    [BitPackFormatter]
    public bool[]? Data { get; set; }
}

BrotliFormatterはbyte[]用です。例えば、大きなペイロードをBrotliで圧縮できます。

[MemoryPackable]
public partial class Sample
{
    public int Id { get; set; }

    [BrotliFormatter]
    public byte[]? Payload { get; set; }
}

BrotliStringFormatterはstring用で、圧縮された文字列(UTF16)をBrotliでシリアル化します。

[MemoryPackable]
public partial class Sample
{
    public int Id { get; set; }

    [BrotliStringFormatter]
    public string? LargeText { get; set; }
}

BrotliFormatter<T>は任意の型用で、シリアル化されたデータをBrotliで圧縮します。型がbyte[]またはstringの場合、パフォーマンスのためにBrotliFormatterまたはBrotliStringFormatterを使用する必要があります。

[MemoryPackable]
public partial class Sample
{
    public int Id { get; set; }

    [BrotliFormatter<ChildType>]
    public ChildType? Child { get; set; }
}

デシリアライズ配列プーリング

大きな配列(任意のT)をデシリアライズするために、MemoryPackは複数の効率的なプーリング方法を提供します。最も効果的な方法は、上書き機能を使用することです。特にList<T>は常に再利用されます。

[MemoryPackable]
public partial class ListBytesSample
{
    public int Id { get; set; }
    public List<byte> Payload { get; set; }
}

// ----

// List<byte> は再利用され、デシリアライズ時に割り当ては発生しません。
MemoryPackSerializer.Deserialize<ListBytesSample>(bin, ref reuseObject);

// 効率的な操作のために、CollectionsMarshalを使用してSpan<T>を取得できます
var span = CollectionsMarshal.AsSpan(value.Payload);

便利な方法は、デシリアライズ時にArrayPoolにデシリアライズすることです。MemoryPackはMemoryPoolFormatter<T>とReadOnlyMemoryPoolFormatter<T>を提供します。

[MemoryPackable]
public partial class PoolModelSample : IDisposable
{
    public int Id { get; }

    [MemoryPoolFormatter<byte>]
    public Memory<byte> Payload { get; private set; }

    public PoolModelSample(int id, Memory<byte> payload)
    {
        Id = id;
        Payload = payload;
    }

    // 返却コードは自分で記述する必要があります。以下はスニペットです。

    bool usePool;

    [MemoryPackOnDeserialized]
    void OnDeserialized()
    {
        usePool = true;
    }

    public void Dispose()
    {
        if (!usePool) return;

        Return(Payload); Payload = default;
    }

    static void Return<T>(Memory<T> memory) => Return((ReadOnlyMemory<T>)memory);

    static void Return<T>(ReadOnlyMemory<T> memory)
    {
        if (MemoryMarshal.TryGetArray(memory, out var segment) && segment.Array is { Length: > 0 })
        {
            ArrayPool<T>.Shared.Return(segment.Array, clearArray: RuntimeHelpers.IsReferenceOrContainsReferences<T>());
        }
    }
}

// ---

using(var value = MemoryPackSerializer.Deserialize<PoolModelSample>(bin))
{
    // 何か処理を行う...
}   // ArrayPool に返却されます

パフォーマンス

私のブログ記事How to make the fastest .NET Serializer with .NET 7 / C# 11, case of MemoryPackを参照してください。

ペイロードサイズと圧縮

ペイロードサイズはターゲット値に依存します。JSONとは異なり、キーがなくバイナリフォーマットであるため、ペイロードサイズはJSONよりも小さくなる可能性が高いです。

MessagePackやProtobufのような可変長エンコーディングを使用する形式と比較して、MemoryPackは整数を多用する場合に大きくなる傾向があります(MemoryPackでは整数は固定サイズエンコーディングのため常に4バイトですが、MessagePackは1〜5バイトです)。

floatとdoubleは、MemoryPackでは4バイトと8バイトですが、MessagePackでは5バイトと9バイトです。したがって、例えばVector3(float, float, float)配列の場合、MemoryPackの方が小さいです。

文字列はデフォルトでUTF8であり、他のシリアライザーと同様ですが、UTF16オプションを選択した場合、性質が異なります。

いずれにしても、ペイロードサイズが大きい場合は、圧縮を検討すべきです。LZ4、ZStandard、Brotliが推奨されます。

圧縮

MemoryPackは、Brotli圧縮のための効率的なヘルパーを[BrotliEncoder](https://learn.microsoft.com/en-us/dotnet/api/system.io.compression.brotliencoder)および[BrotliDecoder](https://learn.microsoft.com/en-us/dotnet/api/system.io.compression.brotlidecoder)経由で提供します。MemoryPackのBrotliCompressorとBrotliDecompressorは、MemoryPackの内部動作に最適化された圧縮/解凍を提供します。

using MemoryPack.Compression;

// 圧縮(usingが必要です)
using var compressor = new BrotliCompressor();
MemoryPackSerializer.Serialize(compressor, value);

// 圧縮されたbyte[]を取得
var compressedBytes = compressor.ToArray();

// または他のIBufferWriter<byte>(例: PipeWriter)に書き込みます
compressor.CopyTo(response.BodyWriter);
using MemoryPack.Compression;

// 解凍(usingが必要です)
using var decompressor = new BrotliDecompressor();

// 圧縮されたReadOnlySequence<byte>をReadOnlySpan<byte>またはReadOnlySequence<byte>から取得します
var decompressedBuffer = decompressor.Decompress(buffer);

var value = MemoryPackSerializer.Deserialize<T>(decompressedBuffer);

BrotliCompressorとBrotliDecompressorはどちらも構造体であり、ヒープにメモリを割り当てません。どちらも、Serialize/Deserializeのために内部メモリプールに圧縮または解凍されたデータを格納します。したがって、メモリプーリングを解放する必要があるため、usingの使用を忘れないでください。

圧縮レベルは非常に重要です。デフォルトは品質-1(CompressionLevel.Fastest)に設定されており、.NETのデフォルト(CompressionLevel.Optimal, 品質-4)とは異なります。これは、シリアライザーの使用シナリオではクリティカルであることが判明しました。標準のBrotliStream(デフォルトで品質-4)を使用する際は注意してください。いずれにしても、圧縮/解凍の速度とサイズは、データによって非常に異なる結果になります。アプリケーションで処理されるデータを準備し、自分でテストしてください。

MemoryPackの非圧縮とBrotliの追加圧縮の間には、数倍の速度ペナルティがあることに注意してください。

Brotliはカスタムフォーマッタでもサポートされています。BrotliFormatterは特定のメンバーを圧縮できます。

[MemoryPackable]
public partial class Sample
{
    public int Id { get; set; }

    [BrotliFormatter]
    public byte[]? Payload { get; set; }
}

外部型のシリアル化

外部型をシリアル化したい場合は、カスタムフォーマッタを作成してプロバイダーに登録できます。Formatter/Provider APIを参照してください。ただし、カスタムフォーマッタの作成は困難です。そのため、ラッパー型を作成することを推奨します。例えば、AnimationCurveという外部型をシリアル化したい場合。

// Keyframe: (float time, float inTangent, float outTangent, int tangentMode, int weightedMode, float inWeight, float outWeight)
[MemoryPackable]
public readonly partial struct SerializableAnimationCurve
{
    [MemoryPackIgnore]
    public readonly AnimationCurve AnimationCurve;

    [MemoryPackInclude]
    WrapMode preWrapMode => AnimationCurve.preWrapMode;
    [MemoryPackInclude]
    WrapMode postWrapMode => AnimationCurve.postWrapMode;
    [MemoryPackInclude]
    Keyframe[] keys => AnimationCurve.keys;

    [MemoryPackConstructor]
    SerializableAnimationCurve(WrapMode preWrapMode, WrapMode postWrapMode, Keyframe[] keys)
    {
        var curve = new AnimationCurve(keys);
        curve.preWrapMode = preWrapMode;
        curve.postWrapMode = postWrapMode;
        this.AnimationCurve = curve;
    }

    public SerializableAnimationCurve(AnimationCurve animationCurve)
    {
        this.AnimationCurve = animationCurve;
    }
}

ラップする型は公開されていますが、シリアル化からは除外されます(MemoryPackIgnore)。シリアル化したいプロパティはプライベートですが、含められます(MemoryPackInclude)。コンストラクタの2つのパターンも用意する必要があります。シリアライザーが使用するコンストラクタはプライベートである必要があります。

そのままでは、毎回ラップする必要があり、不便です。また、構造体のラッパーはnullを表すことができません。そこでカスタムフォーマッタを作成しましょう。

public class AnimationCurveFormatter : MemoryPackFormatter<AnimationCurve>
{
    // UnityはscopedとTBufferWriterをサポートしていないため、シグネチャを `Serialize(ref MemoryPackWriter writer, ref AnimationCurve value)` に変更します
    public override void Serialize<TBufferWriter>(ref MemoryPackWriter<TBufferWriter> writer, scoped ref AnimationCurve? value)
    {
        if (value == null)
        {
            writer.WriteNullObjectHeader();
            return;
        }

        writer.WritePackable(new SerializableAnimationCurve(value));
    }

    public override void Deserialize(ref MemoryPackReader reader, scoped ref AnimationCurve? value)
    {
        if (reader.PeekIsNull())
        {
            reader.Advance(1); // nullブロックをスキップ
            value = null;
            return;
        }
        
        var wrapped = reader.ReadPackable<SerializableAnimationCurve>();
        value = wrapped.AnimationCurve;
    }
}

最後に、スタートアップでフォーマッタを登録します。

MemoryPackFormatterProvider.Register<AnimationCurve>(new AnimationCurveFormatter());

注意:UnityのAnimationCurveはデフォルトでシリアル化可能なので、AnimationCurveにはこのカスタムフォーマッタは必要ありません。

パッケージ

MemoryPackには以下のパッケージがあります。

  • MemoryPack
  • MemoryPack.Core
  • MemoryPack.Generator
  • MemoryPack.Streaming
  • MemoryPack.AspNetCoreMvcFormatter
  • MemoryPack.UnityShims

MemoryPackはメインライブラリで、高性能なバイナリオブジェクトのシリアル化とデシリアライズのための完全なサポートを提供します。コアベースライブラリにはMemoryPack.Core、コード生成にはMemoryPack.Generatorに依存しています。MemoryPack.Streamingは、ストリーミングシリアル化のための追加拡張機能を提供します。MemoryPack.AspNetCoreMvcFormatterは、ASP.NET Core用の入力および出力フォーマッタを追加します。MemoryPack.UnityShimsは、.NETとUnity間で型を共有するためのUnityシム型とフォーマッタを追加します。

TypeScriptおよびASP.NET Core Formatter

MemoryPackはTypeScriptコード生成をサポートしています。C#からクラスとシリアル化コードを生成します。つまり、OpenAPI、protoなどを使用せずにブラウザと型を共有できます。

コード生成はSource Generatorと統合されており、以下のオプション(MemoryPackGenerator_TypeScriptOutputDirectory)でTypeScriptコードの出力ディレクトリを設定します。ランタイムコードも同時に出力されるため、追加の依存関係は不要です。

<!-- memorypack TypeScriptコードをディレクトリに出力 -->
<ItemGroup>
    <CompilerVisibleProperty Include="MemoryPackGenerator_TypeScriptOutputDirectory" />
</ItemGroup>
<PropertyGroup>
    <MemoryPackGenerator_TypeScriptOutputDirectory>$(MSBuildProjectDirectory)\wwwroot\js\memorypack</MemoryPackGenerator_TypeScriptOutputDirectory>
</PropertyGroup>

C#のMemoryPackable型には[GenerateTypeScript]で注釈を付ける必要があります。

[MemoryPackable]
[GenerateTypeScript]
public partial class Person
{
    public required Guid Id { get; init; }
    public required int Age { get; init; }
    public required string FirstName { get; init; }
    public required string LastName { get; init; }
    public required DateTime DateOfBirth { get; init; }
    public required Gender Gender { get; init; }
    public required string[] Emails { get; init; }
}

public enum Gender
{
    Male, Female, Other
}

ターゲットディレクトリにランタイムコードとTypeScript型が生成されます。

[画像: image]

生成されたコードは以下のようになり、単純なフィールドと、シリアル化/シリアル化配列、デシリアライズ/デシリアライズ配列のための静的メソッドが含まれます。

import { MemoryPackWriter } from "./MemoryPackWriter.js";
import { MemoryPackReader } from "./MemoryPackReader.js";
import { Gender } from "./Gender.js"; 

export class Person {
    id: string;
    age: number;
    firstName: string | null;
    lastName: string | null;
    dateOfBirth: Date;
    gender: Gender;
    emails: (string | null)[] | null;

    constructor() {
        // snip...
    }

    static serialize(value: Person | null): Uint8Array {
        // snip...
    }

    static serializeCore(writer: MemoryPackWriter, value: Person | null): void {
        // snip...
    }

    static serializeArray(value: (Person | null)[] | null): Uint8Array {
        // snip...
    }

    static serializeArrayCore(writer: MemoryPackWriter, value: (Person | null)[] | null): void {
        // snip...
    }
    static deserialize(buffer: ArrayBuffer): Person | null {
        // snip...
    }

    static deserializeCore(reader: MemoryPackReader): Person | null {
        // snip...
    }

    static deserializeArray(buffer: ArrayBuffer): (Person | null)[] | null {
        // snip...
    }

    static deserializeArrayCore(reader: MemoryPackReader): (Person | null)[] | null {
        // snip...
    }
}

この型は以下のように使用できます。

let person = new Person();
person.id = crypto.randomUUID();
person.age = 30;
person.firstName = "foo";
person.lastName = "bar";
person.dateOfBirth = new Date(1999, 12, 31, 0, 0, 0);
person.gender = Gender.Other;
person.emails = ["foo@bar.com", "zoo@bar.net"];

// Uint8Arrayにシリアル化
let bin = Person.serialize(person);

let blob = new Blob([bin.buffer], { type: "application/x-memorypack" })

let response = await fetch("http://localhost:5260/api",
    { method: "POST", body: blob, headers: { "Content-Type": "application/x-memorypack" } });

let buffer = await response.arrayBuffer();

// ArrayBufferからデシリアライズ 
let person2 = Person.deserialize(buffer);

MemoryPack.AspNetCoreMvcFormatterパッケージは、ASP.NET Core MVC用のMemoryPack入力および出力フォーマッタを追加します。以下のコードでASP.NET Core MVCにMemoryPackInputFormatter、MemoryPackOutputFormatterを追加できます。

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.AddControllers(options =>
{
    options.InputFormatters.Insert(0, new MemoryPackInputFormatter());
    // checkContentType: true の場合、複数のフォーマット(JSON/MemoryPackなど)を出力できます。デフォルトはfalseです。
    options.OutputFormatters.Insert(0, new MemoryPackOutputFormatter(checkContentType: false));
});

HttpClientから呼び出す場合、Contentヘッダーにapplication/x-memorypackを設定できます。

var content = new ByteArrayContent(bin)
content.Headers.ContentType = new MediaTypeHeaderValue("application/x-memorypack");
TypeScript型マッピング

生成できる型にはいくつかの制限があります。プリミティブのうち、charとdecimalはサポートされていません。また、OpenGenerics型は使用できません。

C#TypeScript説明
boolboolean
bytenumber
sbytenumber
intnumber
uintnumber
shortnumber
ushortnumber
longbigint
ulongbigint
floatnumber
doublenumber
stringstring | null
GuidstringTypeScriptでは文字列として表現されますが、16バイトバイナリとしてシリアル化/デシリアル化されます
DateTimeDateDateTimeKind は無視されます
enumconst enumlong および ulong の基底型はサポートされていません
T?T | null
T[]T[] | null
byte[]Uint8Array | null
: ICollection<T>T[] | nullList<T>のようなICollection<T>実装型をすべてサポートします
: ISet<T>Set<T> | nullHashSet<T>のようなISet<T>実装型をすべてサポートします
: IDictionary<K,V>Map<K, V> | nullDictionary<K,V>のようなIDictionary<K,V>実装型をすべてサポートします。
[MemoryPackable]classクラスのみサポートします
[MemoryPackUnion]abstract class

[GenerateTypeScript]はクラスにのみ適用でき、現在は構造体ではサポートされていません。

インポートファイルの拡張子とメンバー名のキャッシングの設定

デフォルトでは、MemoryPackはimport { MemoryPackWriter } from "./MemoryPackWriter.js";のような.js拡張子でファイルを生成します。他の拡張子に変更したい場合や空にしたい場合は、MemoryPackGenerator_TypeScriptImportExtensionを使用して設定します。また、メンバー名は自動的にキャメルケースに変換されます。元の名前を使用したい場合は、MemoryPackGenerator_TypeScriptConvertPropertyNameをfalseに設定します。

<ItemGroup>
    <CompilerVisibleProperty Include="MemoryPackGenerator_TypeScriptOutputDirectory" />
    <CompilerVisibleProperty Include="MemoryPackGenerator_TypeScriptImportExtension" />
    <CompilerVisibleProperty Include="MemoryPackGenerator_TypeScriptConvertPropertyName" />
    <CompilerVisibleProperty Include="MemoryPackGenerator_TypeScriptEnableNullableTypes" />
</ItemGroup>
<PropertyGroup>
    <MemoryPackGenerator_TypeScriptOutputDirectory>$(MSBuildProjectDirectory)\wwwroot\js\memorypack</MemoryPackGenerator_TypeScriptOutputDirectory>
    <!-- 空を許可 -->
    <MemoryPackGenerator_TypeScriptImportExtension></MemoryPackGenerator_TypeScriptImportExtension>
    <!-- デフォルトはtrue -->
    <MemoryPackGenerator_TypeScriptConvertPropertyName>false</MemoryPackGenerator_TypeScriptConvertPropertyName>
    <!-- デフォルトはfalse -->
    <MemoryPackGenerator_TypeScriptEnableNullableTypes>true</MemoryPackGenerator_TypeScriptEnableNullableTypes>
</PropertyGroup>

MemoryPackGenerator_TypeScriptEnableNullableTypesは、C#のnull許容アノテーションをTypeScriptコードに反映させることができます。デフォルトはfalseで、すべてがnull許容になります。

ストリーミングシリアル化

MemoryPack.Streamingは、コレクションのストリームでのシリアル化とデシリアル化を追加サポートするMemoryPackStreamingSerializerを提供します。

public static class MemoryPackStreamingSerializer
{
    public static async ValueTask SerializeAsync<T>(PipeWriter pipeWriter, int count, IEnumerable<T> source, int flushRate = 4096, CancellationToken cancellationToken = default)
    public static async ValueTask SerializeAsync<T>(Stream stream, int count, IEnumerable<T> source, int flushRate = 4096, CancellationToken cancellationToken = default)
    public static async IAsyncEnumerable<T?> DeserializeAsync<T>(PipeReader pipeReader, int bufferAtLeast = 4096, int readMinimumSize = 8192, [EnumeratorCancellation] CancellationToken cancellationToken = default)
    public static IAsyncEnumerable<T?> DeserializeAsync<T>(Stream stream, int bufferAtLeast = 4096, int readMinimumSize = 8192, CancellationToken cancellationToken = default)
}

フォーマッタ/プロバイダAPI

フォーマッタを手動で実装したい場合は、MemoryPackFormatter<T>を継承し、SerializeおよびDeserializeメソッドをオーバーライドします。

public class SkeltonFormatter : MemoryPackFormatter<Skelton>
{
    public override void Serialize<TBufferWriter>(ref MemoryPackWriter<TBufferWriter> writer, scoped ref Skelton? value)
    {
        if (value == null)
        {
            writer.WriteNullObjectHeader();
            return;
        }

        // writerメソッドを使用します。
    }

    public override void Deserialize(ref MemoryPackReader reader, scoped ref Skelton? value)
    {
        if (!reader.TryReadObjectHeader(out var count))
        {
            value = null;
            return;
        }

        // readerメソッドを使用します。
    }
}

作成したフォーマッタはMemoryPackFormatterProviderに登録されます。

MemoryPackFormatterProvider.Register(new SkeltonFormatter());

注意:unmanged struct(参照型を含まない構造体)はカスタムフォーマッタを使用できません。常にネイティブメモリレイアウトをシリアル化します。

MemoryPackWriter/ReaderOptionalState

MemoryPackWriter/MemoryPackReaderの初期化にはOptionalStateが必要です。これはMemoryPackSerializerOptionsのラッパーであり、MemoryPackWriterOptionalStatePoolから作成できます。

// Dispose時に、OptionalStateはプールに戻されます。
using(var state = MemoryPackWriterOptionalStatePool.Rent(MemoryPackSerializerOptions.Default))
{
    var writer = new MemoryPackWriter<T>(ref t, state);
}

// Readerの場合
using (var state = MemoryPackReaderOptionalStatePool.Rent(MemoryPackSerializerOptions.Default))
{
    var reader = new MemoryPackReader(buffer, state);
}

ターゲットフレームワークの依存関係

MemoryPackはnetstandard2.1とnet7.0を提供しますが、両者は互換性がありません。例えば、netstandard2.1プロジェクト下のMemoryPackable型をnet7.0プロジェクトから使用すると、実行時例外が発生します。

Unhandled exception. System.TypeLoadException: Virtual static method '' is not implemented on type '' from assembly '*'.

.NET 7は静的抽象メンバー(Virtual static method)を使用しており、netstandard2.1ではサポートされていないため、この動作は仕様です。

.NET 7プロジェクトはnetstandard 2.1 DLLを使用すべきではありません。つまり、アプリケーションが.NET 7プロジェクトの場合、MemoryPackを使用するすべての依存関係は.NET 7をサポートする必要があります。したがって、ライブラリ開発者がMemoryPackに依存している場合、デュアルターゲットフレームワークを設定する必要があります。

<TargetFrameworks>netstandard2.1;net7.0</TargetFrameworks>

RPC

Cysharp/MagicOnionは、protobufの代わりにMessagePackを使用するコードファーストのgrpc-dotnetフレームワークです。MagicOnionは現在、MagicOnion.Serialization.MemoryPackパッケージ(プレビュー)を介してMemoryPackをシリアル化レイヤーとしてサポートしています。詳細はMagicOnion#MemoryPack supportを参照してください。

Unity

最小サポートUnityバージョンは2022.3.12f1です。

MemoryPackコアパッケージはNuGetから提供されます。Unityでも利用可能です。Unity組み込み型サポートを取得したい場合は、追加でMemoryPack.Unity拡張機能を提供します。

  1. NuGetForUnityを使用してNuGetからMemoryPackをインストールします。
  • NuGet -> Manage NuGet Packages からウィンドウを開き、「MemoryPack」を検索してインストールします。[画像: screenshot]

  • バージョン競合エラーが発生した場合は、Player Settings(Edit -> Project Settings -> Player -> 下部までスクロールして「Other Settings」を展開し、「Configuration」セクションの「Assembly Version Validation」のチェックを外します)でバージョン検証を無効にしてください。

  1. Git URL を参照して MemoryPack.Unity パッケージをインストールします。

MemoryPack は ..* リリースタグを使用するため、バージョンを指定して #1.0.0 のように指定できます。例:https://github.com/Cysharp/MemoryPack.git?path=src/MemoryPack.Unity/Assets/MemoryPack.Unity#1.0.0

.NET バージョンと同様に、コードはコードジェネレーター(MemoryPack.Generator.dll)によって生成されます。リフレクションフリーの実装は、IL2CPPでも最高のパフォーマンスを提供します。

UnityとSource Generatorの詳細については、Unityドキュメントを参照してください。

Source Generatorは、com.unity.properties および com.unity.entities によってUnityでも公式に使用されています。つまり、次世代Unityのコード生成の標準です。

Vector3、Rectなどのすべてのアンマネージド型、および一部のクラス(AnimationCurve、Gradient、RectOffset)をシリアル化できます。他のUnity固有の型をシリアル化したい場合は、外部型のシリアル化セクションを参照してください。

Unityのパフォーマンスでは、MemoryPackはJsonUtilityよりも3〜10倍高速です。

[画像: image]

共有コードにUnityの型(Vector2など)が含まれている場合、MemoryPackはNuGetでMemoryPack.UnityShimsパッケージを提供します。

MemoryPack.UnityShimsパッケージは、Unityの標準構造体(Vector2, Vector3, Vector4, Quaternion, Color, Bounds, Rect, Keyframe, WrapMode, Matrix4x4, GradientColorKey, GradientAlphaKey, GradientMode, Color32, LayerMask, Vector2Int, Vector3Int, RangeInt, RectInt, BoundsInt)および一部のクラス(AnimationCurve, Gradient, RectOffset)のシムを提供します。

警告

現在、Unityでの使用には以下の制限があります。

  1. UnityバージョンはCustomFormatterをサポートしていません。
  2. .NET7以降を使用している場合、MemoryPackバイナリフォーマットはUnityと完全には互換性がありません。
    • この問題は、[StructLayout(LayoutKind.Auto)]が明示的に指定されている値型で発生します。(構造体のデフォルトはLayoutKind.Sequencilです。)そのような型の場合、.NETでシリアル化されたバイナリはUnityでデシリアライズできません。同様に、Unityでシリアル化されたバイナリは.NET側でシリアル化できません。
    • 影響を受ける型には通常、以下の型が含まれます。
      • DateTimeOffset
      • ValueTuple
    • 現在、簡単な解決策はこれらの型を使用しないことです。

ネイティブAOT

残念ながら、.NET 7 Native AOTは、MemoryPackを使用するとランタイムバグによりクラッシュします(Generic virtual method pointer lookup failure)。これは.NET 8で修正される予定です。Microsoft.DotNet.ILCompilerのプレビューバージョンを使用すると、.NET 7で修正できます。設定方法については、issueのコメントを参照してください。

バイナリワイヤフォーマット仕様

Serialize<T>およびDeserialize<T>で定義されたTの型は、C#スキーマと呼ばれます。MemoryPackフォーマットは自己記述型フォーマットではありません。デシリアライズには対応するC#スキーマが必要です。これらの型はバイナリの内部表現として存在しますが、C#スキーマなしでは型を決定できません。

エンディアンはLittle Endianである必要があります。ただし、参照C#実装はエンディアンを気にしないため、ビッグエンディアンマシンでは使用できません。しかし、現代のコンピュータは通常リトルエンディアンです。

フォーマットには8つのタイプがあります。

  • アンマネージド構造体
  • オブジェクト
  • バージョン耐性オブジェクト
  • 循環参照オブジェクト
  • タプル
  • コレクション
  • 文字列
  • ユニオン
アンマネージド構造体

アンマネージド構造体は、参照型を含まないC#構造体であり、C# のアンマネージド型の制約に似ています。構造体レイアウトをそのままシリアル化し、パディングも含まれます。

オブジェクト

(byte memberCount, [values...])

オブジェクトは、ヘッダーに1バイトの符号なしバイトをメンバー数として持ちます。メンバー数は0から249まで許可され、255はオブジェクトがnullであることを表します。値は、メンバー数のMemoryPack値を格納します。

バージョン耐性オブジェクト

(byte memberCount, [varint byte-length-of-values...], [values...])

バージョン耐性オブジェクトはオブジェクトに似ていますが、ヘッダーに値のバイト長を持ちます。varintは以下の仕様に従います。最初のsbyteは値または型コードであり、次のXバイトが値です。0から127は符号なしバイト値、-1から-120は符号なしバイト値、-121はbyte、-122はsbyte、-123はushort、-124はshort、-125はuint、-126はint、-127はulong、-128はlongです。

循環参照オブジェクト

(byte memberCount, [varint byte-length-of-values...], varint referenceId, [values...])
(250, varint referenceId)

循環参照オブジェクトはバージョン耐性オブジェクトに似ていますが、メンバー数が250の場合、次のvarint(符号なし32ビット整数)が参照IDになります。そうでない場合、byte-length-of-valuesの後ろにvarint参照IDが書き込まれます。

タプル

(values...)

タプルは固定サイズで、null許容でない値のコレクションです。.NETでは、KeyValuePair<TKey, TValue>およびValueTuple<T,...>はタプルとしてシリアル化されます。

コレクション

(int length, [values...])

コレクションはヘッダーに4バイト符号付き整数をデータ数として持ち、-1はnullを表します。値は、長さのMemoryPack値を格納します。

文字列

(int utf16-length, utf16-value)
(int ~utf8-byte-count, int utf16-length, utf8-bytes)

文字列には2つの形式があります、UTF16とUTF8です。最初の4バイト符号付き整数が-1の場合、nullを表します。0は空を表します。UTF16はコレクションと同じです(ReadOnlySpan<char>としてシリアル化され、utf16-valueのバイト数はutf16-length * 2です)。最初の符号付き整数が-2以下の場合、値はUTF8でエンコードされます。utf8-byte-countは補数でエンコードされ、バイト数を取得するには~utf8-byte-countを使用します。次の符号付き整数はutf16-lengthで、-1(不明な長さ)を許可します。utf8-bytesはutf8-byte-countのバイト数を格納します。

ユニオン

(byte tag, value)
(250, ushort tag, value)

最初の符号なしバイトは、判別された値型またはフラグのタグです。0から249はタグを表し、250は次の符号なしショートがタグであることを表し、255はユニオンがnullであることを表します。

ライセンス

このライブラリはMITライセンスの下でライセンスされています。