Home

MessagePack for CLI (Common Language Infrastructure) is an implementation of the MessagePack specification for the .NET CLI. That is, this is not only a binding for C#, but also is able to be used from Visual Basic, F#, PowerShell, Iron Python, Iron Ruby, and so on.

Currently supported runtimes are following:

• Fully-Supported(tests are automated):
  • Desktop CLR (3.5, 4.0, 4.5)
  • Windows Runtime 8/8.1 - Tested by official MSTest.
  • Windows Phone Silverlight 8 - Tested by official MSTest.
  • Xamarin Android - Tested by Xamarin's emulator.
  • Xamarin iOS - Tested by iPad, latest iOS.
  • Unity3D (AOT only) - Tested with Mono 2.6.3 AOT, so some issues might remain. There are 2 flavor for Unity3D builds.
• Experimental (maintained, but tests are not automated):
  • Mono - It should work if there is no compatibility bugs. Note that .Mono solution only differ in AppDomain/Code Access Security related unit test code, so you should be able to use desktop build as is.
  • Silverlight 5
• Not Supported - Your contribution is welcome
  • UWP - It will be supported in 0.6.x including .NET Native.
  • CoreCLR - It will be supported in 0.6.x.
  • Unity3D (IL2CPP) - It will be supported in future.
  • .NET Compact Framework
  • .NET Micro Framework

Contents

• API Documents

  • Online API document
  • .chm file distribution

• Usage:

  • Quick Start - Quick start for serialization.
  • MessagePackObject - MessagePackObject supports MessagePack dynamic typing nature in strongly typed CLI style.
  • Serialization Attributes - Describes custom attributes which control serialization for improve interoperability.
  • Serialization Requirements - Describes requirements of serialization for your own types.
  • Considerations About Strings - Describes about string handling in MsgPack-CLI.
  • Default Collections - Describes well known abstract collections in MsgPack-CLI.
  • Dynamic Type Handling - Describes how to handle dynamic types in MsgPack-CLI.
  • Xamarin and Unity - Describes about how to use MessagePack for CLI in Xamarin and Unity.

• Samples

  • Basic Usage - This sample shows basic usage of MessagePack for CLI.
  • Handling Dynamic Object - Do you want to handle the object which value(s) are dynamically typed? This sample shows you the usage of MessagePackObject and provides best choice to deserialize it.
  • SerializationContext and Options - This sample shows how to tweak serializtion options for interoperability etc.
  • Custom Serializer - This sample provides how to use custom(own built) serializer you want to handle complex scenario.
  • Packable and Unpackable - This sample shows about IPackable and IUnpackable. These are extension point for your data type to handle custom serialization.
  • Custom Attributes - This sample shows about some custom attributes to control serializer behavior. These are important to interop other platform bindings.

• Spec:

  • New Message Pack Spec - Describes about new MessagePack specifications including str types and ext types.

• Advanced:

  • Serialization Options - Describes about various serialization options including enum serialization, object serialization, and protocol options.
  • Interoperability Considerations - Describes some considerations for interoperability.
  • Polymorphism - Describes about polymorphism for the members to be serialized/deserialized.
  • Built-in Serializer Specifications - Describes some considerations for interoperability.
  • Manual Packings - Describes manual packings for advanced scenario.
  • Serializer Lifetimes - Describes serializer life times and how to share serializers.
  • Custom Serialization - Describes how to create custom serializer to support own serialization logic.
  • Serialization Architecture - Describes architecture view of the library.
  • Implementation Notes - Implementation notes for code reader.

Features

• Dynamic MessagePack type (MessagePackObject)
• Fast
• Customizable serialization
• Easy to use for basic scenario
• Supports many basic types
• Supports partially trusted environments
• Drops for Mono, Silverlight, Windows Phone (it is not stable because I cannot test them...bug reports welcome)

RPC

Limitations

Serialization

Cyclic References

MessagePack for CLI does NOT support cyclic references. This is differ from runtime serializer like BinaryFormatter. This is intended specification, because many bindings also do not support cyclic references, it is nonsense to support cyclic reference. When you want to serialize object in compact binary format supporting cyclic reference, built-in BinaryFormatter is reasonable choice.

Leap Seconds

Many environments do not consider leap seconds. Therefore, in terms of interoperability, you SHOULD NOT expect that the destination handles it, especially using epoch time as a serialization format (it is the default behavior). If you have to handle leap seconds, you can use ISO-XXX formatted date-time strings, but remember the destination might not be able to interpret it.

Big Array/Map

By design, collections of CLI implementation can have their items up to Int32.MaxValue (about 2 billions), but the MessagePack specification says that Array32 or Map32 may contain up to UInt32.MaxValue (about 4 billions). Currently, MessagePack for CLI does not support such big collection. Note that many implementation, including Java, also do not support them.

APIs

NUnit assertion

NUnit sometimes reports assertion error for comparing MessagePackObject and compatible type. This is because NUnit does not handle implicit type conversion on the assertion logic. You can avoid it with direct invocation to the MessagePackObject.Equals().

Environment

The Runtime Version

There are unsupported version of runtime, because of developing work around cost.

• CLR: CLR v2.0 is not supported yet. It means that .NET Framework 2.0, 3.0, 3.5 is not supported yet. If you think it is critical, please contact me. Note that CLR v1.x should never supported.
• Silverlight: V2 and v3 is not supported.
• Windows Phone: V7.0 is not supported.
• Mono: Prior to Mono 2.10 is not supported, but may work if you can build against them.

FAQ

• Q. Is there DynamicObject version of message pack object?

  • A. No. I think it is not very useful. But if you want to it, please tell me your opinion.

• Q. Are there 'template' like Java binding?

  • A. No. CLI generics feature works fine. But if you want to it, please tell me your opinion.

Translations

T.B.D.