Readme.md

View main readme

---

FluentSerializer.Xml

The FluentSerializer.Xml library is responsible for exposing the XML API and implementing the XML conversion logic.

• XML spec

Configuration

It is possible to configure the defaults of certain aspects the serializer uses. You can override these when configuring the DI injection or when using SerializerFactory.For.Xml().

By default it looks like this:

• Encoding = Encoding.Unicode (utf-16)
• FormatOutput = true
• WriteNull = false
• DefaultClassNamingStrategy = PascalCase
• DefaultPropertyNamingStrategy = camelCase
• DefaultConverters
  • Converter that can handle DateTime objects (XML spec compliant)
  • Converter that can handle IConvertible types
  • Converter to handle collection types (wrapped XML collection)

Using the factory

For basic usage you can use this:

SerializerFactory.For
	.Xml()
	.UseProfilesFromAssembly<TAssemblyMarker>();

This will use the XmlSerializerConfiguration.Default as the applied config. The type parameter of TAssemblyMarker will be used to scan that assembly for the profiles associated with this serializer. Alternatively there are overloads that accept a System.Reflection.Assembly variable.

There are multiple overloads, for changing configuration the lambda approach is recommended:

SerializerFactory.For
	.Xml(static configuration =>
	{
		// Change configuration values
		configuration.NewLine = LineEndings.LineFeed;
	})
	.UseProfilesFromAssembly<TAssemblyMarker>();

This will use a new instance of the XmlSerializerConfiguration as the applied config and allows you to change some properties.

Creating profiles

For the serializer to understand how to map the data structure to and from C# Models, you need to create a profile.
To do so create a class inheriting from FluentSerializer.Xml.Profiles.XmlSerializerProfile.
The profile needs to implement the protected override void Configure() method, which will be called to construct the mappings inside of this profile.

To create a class mapping, use the For<TModel>() method.
This method has the following optional parameters:

• direction: The direction for which this class mapping is valid, defaults to Both
• tagNamingStrategy: A naming strategy for all property to element mappings, overriding the Configuration value
  See: Basic concepts/Naming strategies
• attributeNamingStrategy: A naming strategy for all property to attribute mappings, overriding the Configuration value
  See: Basic concepts/Naming strategies

You can create multiple class mappings per profile if that fits your use-case.

To map the properties of the C# Model, use method chaining on the For<TModel>() method.
Available options: Attribute<TAttribute>(), Child<TElement>(), Text<TText>().

Mapping properties

To create a property to attribute mapping, use the Attribute<TAttribute>() method.
This method has the following optional parameters:

• direction: The direction for which this property mapping is valid, defaults to the class mapping's value.
• namingStrategy: A naming strategy for this property mapping, overriding the Configuration value and the parents strategy
  See: Basic concepts/Naming strategies
• converter: A custom converter for this property mapping, overriding the logic that normally looks up a converter in the default converters
  See: Basic concepts/Converters

To create a property to element mapping, use the Child<TElement>() method.
This method has the following optional parameters:

• direction: The direction for which this property mapping is valid, defaults to the class mapping's value.
• namingStrategy: A naming strategy for this property mapping, overriding the Configuration value and the parents strategy
  See: Basic concepts/Naming strategies
• converter: A custom converter for this property mapping, overriding the logic that normally looks up a converter in the default converters
  See: Basic concepts/Converters

To create a property to element mapping, use the Text<TText>() method.
This method has the following optional parameters:

• direction: The direction for which this property mapping is valid, defaults to the class mapping's value.
• converter: A custom converter for this property mapping, overriding the logic that normally looks up a converter in the default converters
  See: Basic concepts/Converters

The text nodes don't have names, so this mapping has no namingStrategy parameter.

Example

Here is a simple example to illustrate how a profile would be implemented:

<Request>
	<data>
		<List>
			<SomeDataEntity identifier="1">
				<name>someName</name>
				<!-- Some other properties we don't map -->
			</SomeDataEntity>
		</List>
	<data>
</Request>

public sealed class Request<TDataEntity> where TDataEntity: IDataEntity {
	public List<TDataEntity> Data { get; set; }
}

public sealed class SomeDataEntity: IDataEntity {
	public string Id { get; set; }
	public string Name { get; set; }
}

public sealed class RequestProfile : JsonSerializerProfile
{
	protected override void Configure()
	{
		For<Request<IDataEntity>>()
			.Child(request => request.Data);
		
		For<SomeDataEntity>()
			.Attribute(entity => entity.Id,
				namingStrategy: Names.Equal("identifier"))
			.Child(entity => entity.Name);
	}
}