This project is read-only.

Project Description

A fast, powerful, customizable, easy to use xml serializer for .Net that works out of the box with 99% of objects, no changes required.

Beta disclaimer

I'm still writing all the documentation and it will likely take some time. That said, the usage documentation that 90% of you will need is already in the documentation section. Given that the project is Beta, I would not recommend using this in critical production code as yet. There will be occasional bugs, so please report any issues as you find them and I will fix them asap.

Why Another Xml Serializer?

There already exist a number of options for serializing objects to xml in .Net, so why build another serializer? The reason is quite simple, all the existing serializers have a number of limitations involving polymorphism, public constructors or other issues. I wanted an xml serializer that would simply work without requiring special changes to my objects. DotSerialize is designed to be extremely simple to use so that in most cases people can use it to serialize/deserialize objects with one line of code. That doesn't mean however that DotSerialize can't be customized. The library is designed to allow for as little or as much customization as someone desires (though heavy customization can get a bit complex).

How Does DotSerialize Work?

DotSerialize is unlike most serializers in that it serializes fields and not properties by default. This is by design to allow it to work with any object by default. Property getters and setters may be customized to do unexpected operations, but a field simply holds data. By recreating the object and insuring its fields have their original values I ensure the object is recreated in its original state when it was serialized. Some of you may ask "What if my class has no fields and is made up of auto-properties?". The answer is quite simple, all auto-properties still have backing fields behind them that are automatically created, so DotSerialize will still function as expected. By default DotSerialize will use a field's name as the element or attribute name when serialized. If the field is an automatically generated backing field, then DotSerialize uses the name of the encapsulating auto-property. DotSerialize embeds a type attribute in all nodes requiring it (such as reference types and structs) as well as an id property in all reference type nodes. The type attribute allows DotSerialize to automatically accomodate any polymorphism issues that might arise otherwise. The id attribute is used to identify unique reference instances. This allows DotSerialize to maintain referential integrity and deal with all reference issues (such as circular references).

Customization

If you wish to customize the xml output of DotSerialize then you have three options. One is to decorate your data classes with custom attributes. Using these attributes you can instruct DotSerialize to ignore fields, add properties, use custom names, custom ordering and include your own namespace, as well as a custom root node. For most circumstances this is the option a person would want to use.
However, if you do not wish to decorate your data class or you can't (perhaps you don't have access), you can create a custom serializer or create your own xml class map. The latter solution is much easier than creating a custom serializer and will be the most common solution of the second two options. Creating an xml class map is very simple. You simply create a class that inherits from XmlClassMap<T> where T is the data type you are creating the custom layout for. You then describe the layout using fluent syntax (this will be covered in depth later). Lastly you can create a custom serializer to control the serialization and deserialization of the object. This can get quite complex in execution but the concept is fairly simple. Let's assume you have a class called Document that you wish to customize. You create a class that implements ITypeSerializer<Document>, then register the Document type and your custom TypeSerializer class to the main Serializer instance you have created. From that point forward DotSerialize will use your custom TypeSerializer instead of the default whenever it encounters a value of type Document. It is important to note that DotSerialize looks at the actual data type when determining what TypeSerializer to use, not the type of the property/field storing the data. This means if you were serializing an object with a field of type Document, but the instance stored in the field was actually of type LegalDocument (which inherits Document), The Serializer will look for a custom serializer that implements ITypeSerializer<LegalDocument>. The below example shows how easy it is to register the custom ITypeSerializer discussed and use it.
Document doc = new Document();
Serializer.Instance.RegisterType<Document>().ToTypeSerializer<DocTypeSerializer>();
Serializer.SerializeToFile("C:\Document.xml", doc);
The advanced customization section in the documentation will address this in much further detail.

Benchmarks

If speed of serialization or size of the resulting xml are key concerns for you, then DotSerialize is likely not the library for you. While DotSerialize is incredibly easy to use and highly customizable, it is not the fastest xml serializer out there, nor is its output the smallest. This is not to say that DotSerialize is at all slow, simply slower than some alternatives. As far as the size goes, it is really flexible since it depends on your xml format and you can customize the format as you see fit with DotSerialize.
Results of serializing a List of 8,985 decent sized class instances to disk
Serializer Time Elapsed Size of Resulting File
.Net Framework XmlSerializer 247 miliseconds 23,441.92kb
.Net Framework DataContracts Serializer 158 miliseconds 13,559.29kb
SharpSerializer 533 miliseconds 19,903.37kb
DotSerialize 1200 miliseconds 14,289.89kb

The file used to populate the object structure in this benchmark was 6,596kb in csv format on disk. I hope to improve execution speed in the future, but speed is not the main focus of this library, ease of use and flexibility are. Frankly, if you are very concerned about speed and size of data, xml is likely not the format you should be using for your task. If you are concerned with sending serialized data over network connections at high speed, I recommend protobuff-net https://github.com/mgravell/protobuf-net.
The SharpSerializer library listed in the benchmarks may be found at http://www.sharpserializer.com/en/index.html.

Have Questions? Check the FAQ

Usage Summary

Last edited Dec 30, 2015 at 10:25 PM by WiredWiz, version 42