README.markdown

JsonFx v2.0 - JSON serialization framework for .NET

Distributed under the terms of an MIT-style license

Compatible Runtimes:

• .NET Framework 2.0, 3.0, 3.5, and 4.0
• Silverlight 3.0, 4.0
• Windows Phone 7
• Mono Framework 2.6

Serialization Features:

• Unified interface for reading / writing JSON, BSON, XML, JsonML
• Implements true LINQ-to-JSON (not simply LINQ-to-Objects over JSON types)
• Naturally deserializes to standard CLR types, not JSON/XML-specific types
• Supports reading/writing POCO classes
• Supports reading/writing using DataContract, XmlSerialization, JsonName, attributes
• Supports reading/writing using convention-based property renaming
• Supports reading/writing C# 4.0 dynamic types
• Supports reading/writing C# 3.0 Anonymous objects
• Supports reading/writing LINQ queries
• Supports custom reading/writing extensions & name resolution strategies
• Dependency-injection-friendly for extremely flexible custom configurations
• Stream-based serialization for reading/writing right off the wire
• Provider allows automatic selection of serializer from Content-Type and Accept-Types HTTP headers

Basic Examples:

Serialize to/from dynamic types (default for .NET 4.0):

var reader = new JsonReader(); var writer = new JsonWriter();

string input = @"{ ""foo"": true, ""array"": [ 42, false, ""Hello!"", null ] }";
dynamic output = reader.Read(input);
Console.WriteLine(output.array[0]); // 42
string json = writer.Write(output);
Console.WriteLine(json); // {"foo":true,"array":[42,false,"Hello!",null]}

Serialize to/from standard CLR types (default for .NET 2.0/3.5):

string input = @"{ ""first"": ""Foo"", ""last"": ""Bar"" }";
var output = reader.Read<Dictionary<string, object>>(input);
Console.WriteLine(output["first"]); // Foo
output["middle"] = "Blah";
string json = writer.Write(output);
Console.WriteLine(json); // {"first":"Foo","last":"Bar","middle":"Blah"}

Serialize to/from Anonymous types

string input = @"{ ""first"": ""Foo"", ""last"": ""Bar"" }";
var template = new { first=String.Empty, middle=String.Empty, last=String.Empty };
var output = reader.Read(input, template);
Console.WriteLine(output.first); // Foo
output = new { output.first, middle="Blah", output.last };
string json = writer.Write(output);
Console.WriteLine(json); // {"first":"Foo","middle":"Blah","last":"Bar"}

Serialize to/from custom types and LINQ queries

[DataContract]
public class Person
{
	[DataMember(Name="id")] public long PersonID { get; set; }
	[DataMember(Name="first")] public string FirstName { get; set; }
	[DataMember(Name="last")] public string LastName { get; set; }
}

// respect DataContracts on the way in
var reader = new JsonReader(new DataReaderSettings(new DataContractResolverStrategy()));
// use convention over configuration on the way out
var writer = new JsonWriter(new DataWriterSettings(new ConventionResolverStrategy(ConventionResolverStrategy.WordCasing.Lowercase, "-")));

string input =
@"[
	{ ""id"": 1, ""first"": ""Foo"", ""last"": ""Bar"" },
	{ ""id"": 2, ""first"": ""etc."", ""last"": ""et al."" },
	{ ""id"": 3, ""first"": ""Blah"", ""last"": ""Yada"" }
]";

var people = reader.Query<Person>(input);
var query =
	from person in people.ArrayItems()
	where person.PersonID == 1 || person.FirstName == "Blah"
	orderby person.PersonID
	select person;

Console.WriteLine(query.Last().LastName); // Yada
string json = writer.Write(query);
Console.WriteLine(json); // [{"person-id":1,"first-name":"Foo","last-name":"Bar"},{"person-id":3,"first-name":"Blah","last-name":"Yada"}]

Serialize to/from TCP socket:

TcpClient tcpClient = new TcpClient(server, port);
NetworkStream tcpStream = tcpClient.GetStream();

// read incrementally from incoming stream
TextReader tcpReader = new StreamReader(tcpStream);
Foo myFoo = new JsonReader.Read<Foo>(tcpReader);

// write directly to output stream
TextWriter tcpWriter = new StreamWriter(tcpStream);
new JsonWriter.Write(myFoo, tcpWriter);

Fully customizable name resolution strategies

// accept all variations! list in order of priority
var resolver = new CombinedResolverStrategy(
	new JsonResolverStrategy(),   															// simple JSON attributes
	new DataContractResolverStrategy(),   													// DataContract attributes
	new XmlResolverStrategy(),   															// XmlSerializer attributes
	new ConventionResolverStrategy(ConventionResolverStrategy.WordCasing.PascalCase),		// DotNetStyle
	new ConventionResolverStrategy(ConventionResolverStrategy.WordCasing.CamelCase),		// jsonStyle
	new ConventionResolverStrategy(ConventionResolverStrategy.WordCasing.Lowercase, "-"),	// xml-style
	new ConventionResolverStrategy(ConventionResolverStrategy.WordCasing.Uppercase, "_"));	// CONST_STYLE

// pass the combined resolver strategy into the settings object
var reader = new JsonReader(new DataReaderSettings(resolver));

// link the settings objects to share resolver strategies and name lookup cache
var writer = new JsonWriter(new DataWriterSettings(reader.Settings) { PrettyPrint=true });

Build REST services using dependency injection to configure auto-serializer selection

// setup once for the lifespan of the application

// POCO name resolution, share lookups among all instances
var readerSettings = new DataReaderSettings();				
var writerSettings = new DataWriterSettings(readerSettings);

var jsonReader = new JsonFx.Json.JsonReader(readerSettings);
var jsonWriter = new JsonFx.Json.JsonWriter(writerSettings);

var xmlReader = new JsonFx.Xml.XmlReader(readerSettings);
var xmlWriter = new JsonFx.Xml.XmlWriter(writerSettings);

// list all the readers
var readerProvider = new DataReaderProvider(
	jsonReader,
	xmlReader);

// list all the writers
var writerProvider = new DataWriterProvider(
	jsonWriter,
	xmlWriter);

// ...later on a request comes in

// incoming HTTP request headers
string contentTypeHeader = myRequest.Headers[HttpRequestHeader.ContentType];
string acceptHeader = myRequest.Headers[HttpRequestHeader.Accept];

IDataReader deserializer = readerProvider.Find(contentTypeHeader);

var requestData;
using (var textReader = new StreamReader(myRequest.GetRequestStream()))
{
	requestData = deserializer.Read(textReader);
}

// ...consume the data, generate a response
var myResponse = ...;
var responseData = ...;

IDataWriter serializer = writerProvider.Find(acceptHeader, contentTypeHeader);
using (var textWriter = new StreamWriter(myResponse.GetResponseStream()))
{
	serializer.Write(responseData);
}