Add sample sources.

Author: yfakariya

MsgPack.sln

@@ -0,0 +1,36 @@
+using System.Reflection;
+using System.Runtime.CompilerServices;
+using System.Runtime.InteropServices;
+
+// アセンブリに関する一般情報は以下の属性セットをとおして制御されます。
+// アセンブリに関連付けられている情報を変更するには、
+// これらの属性値を変更してください。
+[assembly: AssemblyTitle("Samples")]
+[assembly: AssemblyDescription("")]
+[assembly: AssemblyConfiguration("")]
+[assembly: AssemblyCompany("")]
+[assembly: AssemblyProduct("Samples")]
+[assembly: AssemblyCopyright("Copyright ©  2014")]
+[assembly: AssemblyTrademark("")]
+[assembly: AssemblyCulture("")]
+
+// ComVisible を false に設定すると、その型はこのアセンブリ内で COM コンポーネントから 
+// 参照不可能になります。COM からこのアセンブリ内の型にアクセスする場合は、
+// その型の ComVisible 属性を true に設定してください。
+[assembly: ComVisible(false)]
+
+// 次の GUID は、このプロジェクトが COM に公開される場合の、typelib の ID です
+[assembly: Guid("d3ba6c47-60c9-4e4e-90c5-45e747bc5dcc")]
+
+// アセンブリのバージョン情報は、以下の 4 つの値で構成されています:
+//
+//      Major Version
+//      Minor Version 
+//      Build Number
+//      Revision
+//
+// すべての値を指定するか、下のように '*' を使ってビルドおよびリビジョン番号を 
+// 既定値にすることができます:
+// [assembly: AssemblyVersion("1.0.*")]
+[assembly: AssemblyVersion("1.0.0.0")]
+[assembly: AssemblyFileVersion("1.0.0.0")]

samples/Samples/Properties/AssemblyInfo.cs

@@ -0,0 +1,90 @@
+#region -- License Terms --
+//
+// MessagePack for CLI
+//
+// Copyright (C) 2010-2012 FUJIWARA, Yusuke
+//
+//    Licensed under the Apache License, Version 2.0 (the "License");
+//    you may not use this file except in compliance with the License.
+//    You may obtain a copy of the License at
+//
+//        http://www.apache.org/licenses/LICENSE-2.0
+//
+//    Unless required by applicable law or agreed to in writing, software
+//    distributed under the License is distributed on an "AS IS" BASIS,
+//    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//    See the License for the specific language governing permissions and
+//    limitations under the License.
+//
+#endregion -- License Terms --
+
+using System;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.IO;
+
+using MsgPack.Serialization;
+
+using NUnit.Framework; // For running checking
+
+namespace Samples
+{
+	/// <summary>
+	///		A simple sample code for basic serialization/deserialization.
+	/// </summary>
+	[TestFixture]
+	public class BasicUsageSample
+	{
+		[Test]
+		public void SerializeThenDeserialize()
+		{
+			// They are object for just description. 
+			var targetObject =
+				new PhotoEntry
+				{
+					Id = 123,
+					Title = "My photo",
+					Date = DateTime.Now,
+					Image = new byte[] { 1, 2, 3, 4 },
+					Comment = "This is test object to be serialize/deserialize using MsgPack."
+				};
+			targetObject.Tags.Add( "Sample" );
+			targetObject.Tags.Add( "Excellent" );
+			var stream = new MemoryStream();
+
+			// 1. Create serializer instance.
+			var serializer = SerializationContext.Default.GetSerializer<PhotoEntry>();
+
+			// 2. Serialize object to the specified stream.
+			serializer.Pack( stream, targetObject );
+
+			// Set position to head of the stream to demonstrate deserialization.
+			stream.Position = 0;
+
+			// 3. Deserialize object from the specified stream.
+			var deserializedObject = serializer.Unpack( stream );
+
+			// Test deserialized value.
+			Debug.WriteLine( "Same object? {0}", Object.ReferenceEquals( targetObject, deserializedObject ) );
+			Debug.WriteLine( "Same Id? {0}", targetObject.Id == deserializedObject.Id );
+			Debug.WriteLine( "Same Title? {0}", targetObject.Title == deserializedObject.Title );
+			// Note that MsgPack defacto-standard is Unix epoc in milliseconds precision, so micro- and nano- seconds will be lost. See sample 04 for workaround.
+			Debug.WriteLine( "Same Date? {0}", targetObject.Date.ToString( "YYYY-MM-DD HH:mm:ss.fff" ) == deserializedObject.Date.ToString( "YYYY-MM-DD HH:mm:ss.fff" ) );
+			// Image and Comment tests are ommitted here.
+			// Collection elements are deserialzed.
+			Debug.WriteLine( "Items count: {0}", deserializedObject.Tags.Count );
+		}
+	}
+
+	public class PhotoEntry
+	{
+		public long Id { get; set; }
+		public string Title { get; set; }
+		public DateTime Date { get; set; }
+		public string Comment { get; set; }
+		public byte[] Image { get; set; }
+		private readonly List<string> _tags = new List<string>();
+		// Note that non-null read-only collection members are OK (of course, collections themselves must not be readonly.)
+		public IList<string> Tags { get { return this._tags; } }
+	}
+}

samples/Samples/Sample01_BasicUsage.cs

@@ -0,0 +1,89 @@
+#region -- License Terms --
+//
+// MessagePack for CLI
+//
+// Copyright (C) 2010-2012 FUJIWARA, Yusuke
+//
+//    Licensed under the Apache License, Version 2.0 (the "License");
+//    you may not use this file except in compliance with the License.
+//    You may obtain a copy of the License at
+//
+//        http://www.apache.org/licenses/LICENSE-2.0
+//
+//    Unless required by applicable law or agreed to in writing, software
+//    distributed under the License is distributed on an "AS IS" BASIS,
+//    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//    See the License for the specific language governing permissions and
+//    limitations under the License.
+//
+#endregion -- License Terms --
+
+using System;
+using System.Diagnostics;
+using System.IO;
+
+using MsgPack;
+using MsgPack.Serialization;
+using NUnit.Framework; // For running checking
+
+namespace Samples
+{
+	/// <summary>
+	///		A sample code for explore MessagePackObject.
+	/// </summary>
+	[TestFixture]
+	public class HandlingDynamicObjectSample
+	{
+		[Test]
+		public void SerializeThenDeserialize()
+		{
+			// They are object for just description. 
+			var targetObject =
+				new PhotoEntry // See Sample01_BasicUsage.cs
+				{
+					Id = 123,
+					Title = "My photo",
+					Date = DateTime.Now,
+					Image = new byte[] { 1, 2, 3, 4 },
+					Comment = "This is test object to be serialize/deserialize using MsgPack."
+				};
+			targetObject.Tags.Add( "Sample" );
+			targetObject.Tags.Add( "Excellent" );
+			var stream = new MemoryStream();
+
+			// Set using Map instead of Array to serialize complex object. See Sample03 for details.
+			SerializationContext.Default.SerializationMethod = SerializationMethod.Map;
+
+			// 1. Create serializer instance.
+			var serializer = SerializationContext.Default.GetSerializer<PhotoEntry>();
+
+			// 2. Serialize object to the specified stream.
+			serializer.Pack( stream, targetObject );
+
+			// Set position to head of the stream to demonstrate deserialization.
+			stream.Position = 0;
+
+			// 3. Unpack MessagePackObject to get raw representation.
+			var rawObject = Unpacking.UnpackObject( stream );
+			// You can read MPO tree via Unpacker
+			// var unpacker = Unpacker.Create( stream );
+
+			// Check its type
+			Debug.WriteLine( "Is array? {0}", rawObject.IsArray ); // IsList is alias
+			Debug.WriteLine( "Is map? {0}", rawObject.IsMap ); // IsDictionary is alias
+			Debug.WriteLine( "Type: {0}", rawObject.UnderlyingType );
+
+			// Gets serialized fields.
+			// Note: When the object was serialized as array instead of map, use index instead.
+			var asDictionary = rawObject.AsDictionary();
+			Debug.WriteLine( "Id : {0}({1})", asDictionary[ "Id" ], asDictionary[ "Id" ].UnderlyingType );
+			// String is encoded as utf-8 by default.
+			Debug.WriteLine( "Title : {0}({1})", asDictionary[ "Title" ], asDictionary[ "Title" ].UnderlyingType );
+			// Non-primitive is serialized as complex type or encoded primitive type.
+			// DateTimeOffset is encoded as array[2]{ticks,offset}
+			Debug.WriteLine( "Date : {0}({1})", asDictionary[ "Date" ], asDictionary[ "Date" ].UnderlyingType );
+			// byte[] is byte[], as you know.
+			Debug.WriteLine( "Image : {0}({1})", asDictionary[ "Image" ], asDictionary[ "Image" ].UnderlyingType );
+		}
+	}
+}

samples/Samples/Sample02_HandlingDynamicObject.cs

@@ -0,0 +1,76 @@
+#region -- License Terms --
+//
+// MessagePack for CLI
+//
+// Copyright (C) 2010-2012 FUJIWARA, Yusuke
+//
+//    Licensed under the Apache License, Version 2.0 (the "License");
+//    you may not use this file except in compliance with the License.
+//    You may obtain a copy of the License at
+//
+//        http://www.apache.org/licenses/LICENSE-2.0
+//
+//    Unless required by applicable law or agreed to in writing, software
+//    distributed under the License is distributed on an "AS IS" BASIS,
+//    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//    See the License for the specific language governing permissions and
+//    limitations under the License.
+//
+#endregion -- License Terms --
+
+using System;
+using System.Collections.Generic;
+using System.Collections.ObjectModel;
+
+using MsgPack;
+using MsgPack.Serialization;
+using NUnit.Framework; // For running checking
+
+namespace Samples
+{
+	/// <summary>
+	///		A sample code to describe SerializationContext usage.
+	/// </summary>
+	[TestFixture]
+	public class SerializationContextAndOptionsSample
+	{
+		[Test]
+		public void CustomizeSerializeBehavior()
+		{
+			// 1. To take advantage of SerializationContext, you should create own context to isolate others.
+			//    Note that SerializationContext is thread safe.
+			//    As you imagine, you can change 'default' settings by modifying properties of SerializationContext.Default.
+			var context = new SerializationContext();
+
+			// 2. Set options.
+
+			// 2-1. SerializationMethod: it changes comple type serialization method as array or map.
+			//     Array(default): Space and time efficient, but depends on member declaration order so less version torrelant.
+			//     Map : Less effitient, but more version torrelant (and easy to traverse as MesasgePackObject).
+			context.SerializationMethod = SerializationMethod.Map;
+
+			// 2-2. EnumSerializationMethod: it changes enum serialization as their name or underlying value.
+			//    ByName(default): More version torrelant and interoperable, and backward compatible prior to 0.5 of MsgPack for CLI.
+			//    ByUnderlyingValue: More efficient, but you should manage their underlying value and specify precise data contract between counterpart systems.
+			context.EnumSerializationMethod = EnumSerializationMethod.ByUnderlyingValue;
+
+			// 2-3. If CompatibilityOptions.OneBoundDataMemberOrder is set, the origin DataMemberAttribute.Order becomes 1.
+			//      It is compatibility options 1 base library like Proto-buf.NET.
+			context.CompatibilityOptions.OneBoundDataMemberOrder = true;
+
+			// 2-4. The CompatibilityOptions.PackerCompatibilityOptions control packer compatibility level.
+			//      If you want to communicate with the library which only supports legacy message pack format spec, use PackerCompatibilityOptions.Classic flag set (default).
+			//      If you want to utilize full feature including tiny string type, binary type, extended type, specify PackerCompatibilityOptions.None explicitly.
+			context.CompatibilityOptions.PackerCompatibilityOptions = PackerCompatibilityOptions.None;
+
+			// 2-5. You can tweak default concrete collection types for collection interfaces including IEnumerable<T>, IList, etc.
+			context.DefaultCollectionTypes.Unregister( typeof( IList<> ) );
+			context.DefaultCollectionTypes.Register( typeof( IList<> ), typeof( Collection<> ) );
+
+			// 3. Get a serializer instance with customized settings.
+			var serializer = context.GetSerializer<PhotoEntry>( context );
+
+			// Following instructions are omitted... see sample 01.
+		}
+	}
+}

samples/Samples/Sample03_SerializationContextAndOptions.cs

@@ -0,0 +1,95 @@
+#region -- License Terms --
+//
+// MessagePack for CLI
+//
+// Copyright (C) 2010-2012 FUJIWARA, Yusuke
+//
+//    Licensed under the Apache License, Version 2.0 (the "License");
+//    you may not use this file except in compliance with the License.
+//    You may obtain a copy of the License at
+//
+//        http://www.apache.org/licenses/LICENSE-2.0
+//
+//    Unless required by applicable law or agreed to in writing, software
+//    distributed under the License is distributed on an "AS IS" BASIS,
+//    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//    See the License for the specific language governing permissions and
+//    limitations under the License.
+//
+#endregion -- License Terms --
+
+using System;
+using System.Diagnostics;
+using System.IO;
+
+using MsgPack;
+using MsgPack.Serialization;
+using NUnit.Framework; // For running checking
+
+namespace Samples
+{
+	/// <summary>
+	///		A sample code to describe SerializationContext usage.
+	/// </summary>
+	[TestFixture]
+	public class CustomSerializerSample
+	{
+		[Test]
+		public void RegisterAndUseCustomSerializer()
+		{
+			var stream = new MemoryStream();
+
+			// 1. To take advantage of SerializationContext, you should create own context to isolate others.
+			//    Note that SerializationContext is thread safe.
+			//    As you imagine, you can change 'default' settings by modifying properties of SerializationContext.Default.
+			var context = new SerializationContext();
+
+			// 2. Register custom serializers.
+			context.Serializers.RegisterOverride( new NetUtcDateTimeSerializer( context ) );
+
+			// 3. Get a serializer instance with customized settings.
+			var serializer = context.GetSerializer<DateTime>( context );
+
+			// Test it.
+			var dateTime = DateTime.Now;
+			serializer.Pack( stream, dateTime );
+			stream.Position = 0;
+			var deserialized = serializer.Unpack( stream );
+
+			Debug.WriteLine( "Ticks are same? {0}", dateTime.Ticks == deserialized.Ticks );
+		}
+	}
+
+	/// <summary>
+	///		A custom serializer sample: Serialize <see cref="System.DateTime"/> as UTC.
+	/// </summary>
+	public class NetUtcDateTimeSerializer : MessagePackSerializer<DateTime>
+	{
+		// CAUTION: You MUST implement your serializer thread safe (usually, you can and you should implement serializer as immutable.)
+
+		// Note: If your type has complex type fields, you want to add read only fields in the custom serializer for each fields complex types.
+		// Note: It is good start point to use mpgen.exe utility to get Code-DOM generated serializer to understand custom serializer.
+		//       Notice that the generated serializer is bit complex because of poor expressiveness of CodeDOM tree and built-in nil-handling (described in sample 06.)
+
+		// ownerContext should be match the context to be registered.
+		public NetUtcDateTimeSerializer( SerializationContext ownerContext ) : base( ownerContext ) { }
+
+		protected override void PackToCore( Packer packer, DateTime objectTree )
+		{
+			packer.Pack( objectTree.Ticks );
+		}
+
+		protected override DateTime UnpackFromCore( Unpacker unpacker )
+		{
+			// Note that unapcker should be in head of the complex type.
+			return new DateTime( unpacker.LastReadData.AsInt64() );
+
+			// Note: if you deserialize following members, call Read() as following:
+			// if ( unpacker.Read() )
+			// {
+			//     throw SerializationExceptions.NewUnexpectedEndOfStream();
+			// }
+			// ...Read next field...
+		}
+	}
+}