Skip to content

Latest commit

 

History

History
154 lines (104 loc) · 7.82 KB

README.md

File metadata and controls

154 lines (104 loc) · 7.82 KB
Raw

ExtendedXmlSerializer

Build status Nuget

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:

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

Known Issues

While ExtendedXmlSerializer is very nice, it does have some known issues that have been identified by its owners. These issues are considered too significant to address and have been consolidated under a dedicated label for your review here:

known issue An identified defect, usually one that is significant and not easily fixed.

Please review these issues before submitting a new issue and/or trialing ExtendedXmlSerializer.

Additionally, please note that ExtendedXmlSerializer is now essentially in maintenance mode as of March 2020. We will continue to monitor for any major bugs, so feel free to post an issue if you find one. However, major tasks and/or feature requests and the like will be deferred to the community.

Featured Documentation

(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.

Keep Calm and Code

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

Mentions

ExtendedXmlSerializer is proudly developed and maintained with ReSharper Ultimate.