Bender is a highly configurable xml, json, CSV and form url encoded serialization library for .NET. Unlike other serializers, Bender gives you complete control over the serialization process though a simple API.

• Not strongly named.
• One serializer for json, XML, CSV and form url encoded.
• Readers, writers and visitors give you full control of serialization and deserialization.
• Naming conventions give you full control over naming.
• Friendly deserialization error messages allow you to give valuable feedback to consumers of your API.
• Supports enums, nullable types, String, Char, Boolean, SByte, Byte, Int16, UInt16, Int32, UInt32, Int64, UInt64, Single, Double, Decimal, DateTime, Guid, TimeSpan, Uri, IntPtr, UIntPtr, Array, ArrayList (Serialization only), IEnumerable (Serialization only), IEnumerable<T>, IDictionary (Serialization only), IDictionary<TKey, TValue>, byte[] (As Base64), MailAddress, Version, IPAddress out of the box.
• Supports XmlAttributeAttribute, and XmlIgnoreAttribute attributes.
• Supports XmlArrayAttribute and XmlArrayItemAttribute attributes, name properties.
• Supports XmlRootAttribute, XmlTypeAttribute and XmlElementAttribute attributes, name and namespace properties.
• Extensibility point to override object creation during deserialization with your own implementation.
• Filtering options for types, members and visibility.
• Options for name comparison and ignoring names of certain elements altogether.
• Options for failing on unmatched members or elements.
• Ability to serialize and deserialize members of enumerable and dictionary implementations.

Bender can be found on nuget:

PM> Install-Package Bender

The Serialize and Deserialize convenience methods allow you to easily serialize or deserialize:

public class Model
{
    public string Property { get; set; } 
}

var model = Deserialize.Json<Model>("{\"Property\":\"value\"}");
var model = Deserialize.Xml<Model>("<Model><Property>value</Property></Model>");

var json = Serialize.Json(new Model { Property = "value" });
var xml = Serialize.Xml(new Model { Property = "value" });

Additional convenience methods take or return a byte[], Stream, file path, XDocument, XElement and INode.

Bender can be configured in a number of different ways depending on your needs. First, the configuration DSL is available on all convenience and factory methods:

var model = Deserialize.Json<Model>("{ ... }", x => { ... });
var serializer = Serializer.Create(x => { ... });
var deserializer = Deserializer.Create(x => { ... });

Second, you can create options with the options factory method and pass those in later:

var options = Options.Create(x => { ... });

var model = Deserialize.Json<Model>("{ ... }", options);
var serializer = new Serializer(options);
var deserializer = new Deserializer(options);

Bender has a number of extensibility points. The following covers these in more detail.

Bender ships with some common naming conventions out of the box: camelCase, snake_case, spinal-case and Train-Case. You can add your own naming conventions with the With*NamingConvention() options. There are options to override naming for fields, properties, members (fields and properties), array items, types or all of the above. Each option method has an overload that applies to all and one that takes a predicate to limit its application. Naming conventions form a pipeline where a name is modified by one convention and then passed to the next convention to be modified further. This allows you to define multiple conventions that work together. The order that the conventions are defined is the order they will execute.

Lets take a look at an arbitrary example where we create a couple of naming conventions.

Options.Create(x => x
    .WithPropertyNamingConvention(
        (name, member) => name + "EmailAddress",
        (name, member) => member.Type == typeof(MailAddress))
    .WithNamingConvention(name => "_" + name));

In the first convention we append EmailAddress to the name when the property is of type MailAddress. Next we define a convention that prepends an _ to every name. If we had a property named Support of type MailAddress the name would end up being _SupportEmailAddress.

Visitors enable you to operate on each node in the target graph. Both serialization and deserialization options contain methods for adding visitors. Each option method has an overload that applies to all and one that takes a predicate to limit its application. There are also convenience methods that apply visitors to either xml or json or specific types.

Lets take a look at an xml visitor for serialization that adds a nil attribute when a value is null.

Options.Create(x => x
    .Serialization(s => s
        .AddXmlNamespace("xsi", "http://www.w3.org/2001/XMLSchema-instance")
        .AddXmlVisitor(
            (source, target, options) => 
                target.Element.Add(new XAttribute("xsi:nil", "true")),
            (source, target, options) => source.NodeType.IsValue() && 
                         source.Value == null)));

Readers read values from a source like xml or json during deserialization. Each option method has an overload that applies to all and one that takes a predicate to limit its application. There are also convenience methods that apply readers to specific types.

Lets look at an example where we read an IP address.

Options.Create(x => x
    .Deserialization(s => s
        .AddReader((value, source, target, options) => 
            IPAddress.Parse(value.ToString()))));

You can also define readers for nullable and non-nullable types separately if you want to have fine grained control, for example if you wanted to override how bool's are parsed:

Options.Create(x => x
    .Deserialization(s => s
        .AddReader<bool>(
            (value, source, target, options) => bool.Parse(value.ToString()))
        .AddReader<bool?>(
            (value, source, target, options) => 
                !string.IsNullOrEmpty(value.ToString()) ? 
                    (bool?)bool.Parse(value.ToString()) : null)));

But most of the time the functionality will be the same for nullable and non nullable readers and writers, save the boilerplate null checking logic. So you can define one writer for both nullable and non-nullable types by passing true to the handleNullable parameter:

Options.Create(x => x
    .Deserialization(s => s
        .AddReader<bool>(
            (value, source, target, options) => 
                bool.Parse(value.ToString()), true)));

Writers write values to a target like xml or json during serialization. Each option method has an overload that applies to all and one that takes a predicate to limit its application. There are also convenience methods that apply readers to specific types and indicate if nullable types are included.

Lets look at an example where we write an IP address.

Options.Create(x => x
    .Serialization(s => s
        .AddWriter<IPAddress>((value, source, target, options) => 
            value.ToString())));

Errors during deserialization can result from issues with the source or with your code and configuration. In an API consumed by others, the former can likely be addressed by your end users if they have good feedback. With that in mind, all Bender deserialization exceptions that are caused by a problem with the source inherit from FriendlyBenderException. This exception has a property named FriendlyMessage that can be displayed to end users and give them information to help them resolve the problem. Unlike the raw error messages, no internal information is included.

Bender also has default friendly messages for parsing simple types and these can be overridden by calling the WithFriendlyParseErrorMessage<T>(string message) method in the deserialization options. Also, when creating readers you can make use of friendly parse error messages by specifying one for the type your reader handles:

var deserializer = Deserializer.Create(x => x
    .Deserialization(d => d
        .WithFriendlyParseErrorMessage<IPAddress>(
            "IP addresss not formatted correctly, must be formatted as '1.2.3.4'.")
        .AddReader((v, s, t, o) => IPAddress.Parse(v.ToString()))));

Any errors resulting from the reader will be wrapped in a FriendlyBenderException with the friendly error specified.

Bender has traded some performance for flexibility so does not match the speed of other serializers. It averages ~.05 ms/KB (2.8 GHz i7) so would be more than enough for most applications. But if raw speed is a requirement you might want to look at the ServiceStack serializers or fastJSON.

MIT License.