README.md

ExtendedXmlSerializer

Welcome!

Welcome to ExtendedXMLSerializer's GitHub repository. Here you will find a .NET serializer that:

• Specializes in POCO-based object graph serialization
• Features a powerful extension model
• Operates in the tried-and-trusted dependable XML format. 💖

"But why?"

The classic System.Xml.XmlSerializer poses some challenges:

• Does not support properties that are defined with interface types
• Does not support read-only collection properties (like Xaml does)
• Does not support parameterized constructors (immutable objects)
• Does not support private constructors
• Does not support serialization of class with circular reference or class with interface property
• If you want create custom serializer, your class must inherit from IXmlSerializable or ISerializable. This takes the "plain" out of POCO. 😁
• No migration mechanism for XML based on older code model

ExtendedXmlSerializer addresses a lot of these problems and much much more!

• Serializes and deserializes pretty much any POCO you throw at it*: class, struct, generics, primitives, generic List and Dictionary, Array, Enum and much much more! If you find a class that doesn't get serialized, let us know and we'll take a look at it.
• Custom serializer registration by type or member
• Serialization of references, handling circular references without endlessly looping
• All configurations (migrations, custom serializer...) are outside the class and not coupled to attributes or messy, arcane conventions
• Migrate old XML based on an older schema to a current schema
• Property encryption
• Support XmlElementAttribute, XmlRootAttribute, and XmlTypeAttribute for identity resolution
• Additional attribute support: XmlIgnoreAttribute, XmlAttributeAttribute, and XmlEnumAttribute
• Deserialization xml from classic XmlSerializer (mostly, details in FAQ)

(*Yes, this even -- and especially -- means classes with properties that have an interface property type!)

Supported platforms:

• .NET Standard 2.0
• .NET 4.5.2 (as of #273)

Usage

ExtendedXmlSerializer uses a ConfigurationContainer to store configurations and extensions. Once this container is configured as desired, call its Create method to create a serializer and serialize!

Example class:

class Subject {
    public int Number { get; set; }
    public string Message { get; set; }
}

Configure, create, and serialize:

IExtendedXmlSerializer serializer = new ConfigurationContainer().UseAutoFormatting()
                                                                .UseOptimizedNamespaces()
                                                                .EnableImplicitTyping(typeof(Subject))
                                                                // Additional configurations...
                                                                .Create();

var instance = new Subject {Message = "Hello World!", Number = 42};
var document = serializer.Serialize(new XmlWriterSettings {Indent = true},
                                    instance);

MAKE THE PRETTY XML!!! 😁😁😁

(contents of the document variable above:)

<?xml version="1.0" encoding="utf-8"?>
<Subject Number="42" Message="Hello World!" />

The above demonstrated code can be found in the form of a passing test within our test suite here.

Installation

From your favorite Package Manager Console:

Install-Package ExtendedXmlSerializer

Or if you are brave and want to try out our preview feed:

Install-Package ExtendedXmlSerializer -Source https://ci.appveyor.com/nuget/extendedxmlserializer-preview

Featured Documentation

• FAQs - Probably the first place to go if you have a question.

• Conceptual Topics - From our wiki.

  • The Basics
  • Features
  • API Overview
  • Example Scenarios

• Documentation Site - A resource deployed on every release.

  • API Reference
  • Concepts and Topics (Mirror of our wiki above)

(Looking to upgrade from 1.x? We got you covered here.)

Want to Contribute?

We are a smaller project and are open to any contributions or questions. We do not have a formal code of conduct and would like to keep it that way.

If you view our FAQs and still have a question, open up a new issue! We'll do our best to meet you there with sample code to help get you on your way.

Notable Contributors

• Wojciech Nagórski - v1.x Author.
• Mike-EEE - v2.x Author.

Mentions

ExtendedXmlSerializer is proudly developed and maintained with ReSharper Ultimate.

Magical debugging is courtesy of OzCode.