Using Blueprints

Installation

Blueprints is a managed library which requires .NET 4.0. No installation is required.

When running the BlueprintEditor, make sure to pick the same platform version (x86 or x64) as the application for which you are editing a blueprint.

BlueprintContext

Before you can serialize or deserialize anything, you need to create a BlueprintContext:

using (BlueprintContext context = new BlueprintContext())
{
    ...
}

The context allows you to control how objects are (de)serialized, and caches lookups to improve performance.

Serializing an object

Serialization is done by providing a destination blueprint location and the object to serialize:

using (BlueprintContext context = new BlueprintContext())
{
    context.Serialize("test.xml", testObj);
}

Deserializing an object

Similar to serialization, an object is deserialized by providing the blueprint location:

using (BlueprintContext context = new BlueprintContext())
{
    Test testObj = context.Deserialize<Test>("test.xml");
}

Besides local paths, you can also provide a stream, a Uri or implement a reader/writer yourself to access the blueprint document

Cross-document linking

By default, if an object has multiple references within a blueprint document, subsequent references cause links to the initially serialized node. To allow documents to link to previously serialized documents, you have to Register() the object. The following code serializes the Person pete in a separate pete.xml file, and lets fido.xml link to it:

using (BlueprintContext context = new BlueprintContext())
{
    context.Register(fido.Owner);
    context.Serialize("pete.xml", fido.Owner);
    context.Serialize("fixo.xml", fido);
}

The order in which you create the files implicitly determines where the registered object is serialized.

Custom constructors

For blueprints, a type can only have one constructor. By default it looks for a parameterless constructor, but you can override this behavior by:

Adding a [BlueprintConstructor] attribute to the type
Editing the Blueprints.Config.xml file

Attributes

BlueprintConstructorAttribute

This attribute is placed on the Type level, and allows you to specify the names of the properties that match the constructor parameters. Although the assumption was made that any constructor parameter maps to a property, it is possible to supply custom arguments - but such a type can only be deserialized, not serialized. An attempt to serialize such an object will throw an exception.

Example:

[BlueprintConstructor("Name")]
public sealed class Person
{
    public Person(string name)
    {
        Name = name;
    }

    public string Name { get; private set; }
}

BlueprintTypeAttribute

This attribute, placed on the assembly level, indicates which type(s) an application will (de)serialize. In the editor these types are highlighted. Optionally a filename can be supplied:

[assembly:BlueprintType(typeof(Settings), "Settings.xml")]

Attribute Support

The default type resolver can support additional sets of attributes. This can be configured in the Blueprints.Config.xml file or supplied as a parameter when creating the context:

Attribute Set	Supported Attributes
Basic	DefaultValue, NonSerialized, the ShouldSerializeXxx() method
Xml	XmlRoot, XmlElement, XmlIgnore
ComponentModel	DesignerSerializationVisibility, TypeConverter and includes the Basic set