Converters - Happi-cat/Untech.SharePoint GitHub Wiki

Converters

Each field converter should implement Untech.SharePoint.Common.Converters.IFieldConverter interface. This interface exposes next members:

Method	Meaning
void Initialize(MetaField field)	Initializes field converter with specified instance of SP field metadata.
object FromSpValue(object value)	Converts SP value to member type.
object ToSpValue(object value)	Converts instance of member type to SP value.
string ToCamlValue(object value)	Converts instance of member type to CAML string value.

Built-In Converters

These libraries have built-in field converters for next field types:

• Boolean
• DateTime
• Guid
• Integer, Counter
• Number, Currency
• Text, Note, Choice
• Calculated. Client Server
• Content Type Id. Client Server
• Geolocation. Client Server
• Lookup, MultiLookup. Client Server
• MultiChoice. Client Server
• Url. Client Server
• User, UserMulti. Client Server

Custom Converters

All custom converters can be found in Untech.SharePoint.Common.Converters.Custom namespace.

Name	Alias *	Description	Source
Xml	_Xml_	This converter uses XmlSerializer from System.Xml.Serialization namespace.	Source
Json	_Json_	It uses Newtonsoft.Json.JsonConvert.	Source
Enum	_Enum_	Allows to convert text value into Enum value and vice versa. Text value should match with enum name and/or with value that was specified in EnumMemberAttribute (attribute from System.ComponentModel namespace).	Source
Key-Value	_KeyValue_	Converts Dictionary<string, string> from/to string with format: Key1:Value1;Key2:Value2. Where : - key-value delimiter; ; - items delimiter.	Source
Numeric Range	_NumericRange_	Converts Tuple<double, double> from/to string with format: Value1..Value2.	Source

* - Alias - can be specified in field type instead of Custom Converter configuration (introduced in ver. 1.1).

Writing own converter

It's pretty simple: just implement Untech.SharePoint.Common.Converters.IFieldConverter interface.

NOTE: Don't throw FieldConverterException as library itself will wrap any exception into proper FieldConverterException.

Usage 1.

You can mark yours converter with SpFieldConverterAttribute and specify FieldType that can be used for converter selection. Register field converter with ConfigBuilder.

	[SpFieldConverter("SomeType")]
	public class SomeConverter: IFieldConverter {  }


	public class SomeEntity {
		[SpField(FieldType = "SomeType")]
		public string Field { get; set; }
	}

	public Config BuildConfig()  {
		return ClientConfig.Begin()
			.RegisterConverters(n => n.AddFromAssembly(/* pass assembly info */))
			.Build();
	}

NOTE: This solution can be used to override built-in converters.

Usage 2.

No comments, just an example:

	public class SomeConverter: IFieldConverter {  }

	public class SomeEntity {
		[SpField(CustomConverterType = typeof(SomeConverter))]
		public string Field { get; set; }
	}