Text-to-Object (T2O) Converter: Details

An Overview

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

T2O has two public end points the consumer will use.  These are (for query strings):

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)
  • DateTime
  • 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.

Static Properties

T2O does not support classes with static properties.

Required Parameters

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.

Unrecognized Parameters

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 Attributes

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.

DesignatedType

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:
Designated Type
Applicable .NET Type(s)
Data Validations Performed
Latitude
Double
Not less than -90, not more than +90.
Longitude
Double
Not less than -180, not more than +180.
Radius
Single, Double, Int32, Int64
Greater than 0.
Email
String
Data in valid email format.
USAPhoneNumber
String
Data in a valid USA phone number format, optionally with leading +1.
USAStateCode
String
Valid 2-digit USA state code.
Date
DateTime
T2O "trims off" the time portion.
Time
DateTime
T2O "trims off" the date portion.
BirthDate
DateTime
Date is in the last 150 years.


Range Attributes

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.
Range Attribute
Applicable .NET Type(s)
DateRangeAttribute
DateTime
DecimalRangeAttribute
Decimal (decimal)
DoubleRangeAttribute
Double (double)
Int32RangeAttribute
Int32 (int)
Int64RangeAttribute
Int64 (long)
SingleRangeAttribute
Single (float)
StringLengthRangeAttribute
String (string)
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.