Text-to-Object (T2O) Converter: Details
T2O's publicly exposed classes, methods and properties have ample XML documentation. Please take advantage of the powers of Intellisense.
This page contains supplemental documentation on T2O. Please make sure to go over T2O's Introduction first.
Table of Contents
- T2O's Converter API
- .NET vs C# Type Names
- Supported Built-in .NET Types
- Property Access Modifiers
- Static Properties
- Required Parameters
- Unrecognized Parameters
- T2O Attributes
T2O's Converter API
T2O has two public end points the consumer will use. These are (for query strings):
and (for name/values):
and (for name/values):
On return, if any of the two 'out' collections have items in them, the received class instance will be null.
Where possible, T2O relies on the compiler to guide the developer with using T2O in the intended way. But there are limitations as to what the compiler can do for us.
'violations' contain error information about the class (<T>) as defined in the consumer's code. These violation messages basically tell you how not to use T2O. Each of the entries in the 'violations' collection also contains one or more links. Follow these links to get more information relevant to the usage violation. See below example:
Notice the relevant ''DocumentationLinks'' above.
On the other hand, the 'invalidInputItems' collection contains errors about the data passed into the Convert method. These would be like data not parsable to the relevant data type.
.NET vs C# Type Names
As you start using this package, you will see that the T2O package references the built-in .NET type names, supplemented with C# type names. .Net type names, because this is a .NET offering and not a language specific offering. The C# type names, since a lot of .NET developers are comfortable with C#.
Supported .NET Types
What we are talking about, are query string parameters or form fields we need to convert to .NET built-in property types. It does not make sense to support all .NET built-in types like IntPtr for instance. T2O supports the following built-in types:
- Boolean (bool)
- Decimal (decimal)
- Double (double)
- Int32 (int)
- Int64 (long)
- Single (float)
- String (string)
On top of the above built-in types, T2O supports Arrays or List<> collections of (only) the above built-in types.
Property Access Modifiers
T2O maps query string parameters and their values to the properties of the provided class. T2O expects all properties of that class to be public (publicly accessible). That goes for both the getter and setter of each property. Refer to this class discussion for more information about such classes.
Should you have the need to have non-public properties in the class, you can derive another class from the one sent to T2O and maintain the non-public properties in the derived class.
Note too that the provided class should have at least one public property.
T2O does not support classes with static properties.
Use the nullability of the properties to convey to T2O which properties are required and which ones are optional.
Refer to this required/optional parameter discussion for more information in this regard.
T2O regards parameters in the query string, that are not in the provided class, as unrecognized parameters. The parameters/property names are compared case insensitive, but these 'unexpected parameters' usually are spelling mistakes at the consumer end.
Refer to this unrecognized parameter discussion for more information in this regard.
T2O comes with a set of custom attributes which the consumer can apply to properties to have T2O perform additional data validation checks on the consumer's behalf. These are the DesignatedType and a set of 'Range' attributes as explained next.
The constructor for T2O's DesignatedType attribute takes one of the below enumeration values shown together with the .NET types they can be applied to, plus a brief description of the validation being conducted by T2O:
Applicable .NET Type(s)
Data Validations Performed
Not less than -90, not more than +90.
Not less than -180, not more than +180.
Single, Double, Int32, Int64
Greater than 0.
Data in valid email format.
Data in a valid USA phone number format, optionally with leading +1.
Valid 2-digit USA state code.
T2O "trims off" the time portion.
T2O "trims off" the date portion.
Date is in the last 150 years.
T2O has a list of Range attributes that can be applied to particular .NET types as shown next. Use these attributes to have T2O enforce range value boundaries as coded in attribute on the class property.
See also the Custom Attribute discussion on the Introduction page.
Applicable .NET Type(s)
The range values injected with the Range Attribute property decoration must have the minimum value being less than the maximum value.
On the DateRangeAttribute, the parameter values must either be in ISO 8601 format or in a valid locale format for specified locale.
You can only decorate a class property with one Range Attribute and not with both a Range and a Designated Type attribute.