Text-to-Object (T2O) Converter: Introduction

Summary


A performant framework/NuGet package for converting Query String parameters, or Form Fields, to .NET class properties.

The purpose of this package is to simplify the life of API developers.  More specifically those needing to support GET type HTTP queries (because the boss said that is what is "required")

A single statement/line in your code, making a call to this package, converts a set of Query String parameters (or Form fields) into a .NET class' properties.  T2O is about converting Text to Objects.  Along the way, T2O also applies ample input data validation.  Optionally, you can decorate the class properties with T2O attributes to enforce further validation -- for instance, decorate a 'double' property with T2O's 'Latitude' attribute and T2O ensures the parameter value cannot be less than -90 nor greater than 90.

Enough talking.  Time for a demonstration.  (Using Visual Studio, C# and MSTest for this illustration.)

Download Package

This package can be downloaded from the download link on the NuGet.org page.

Better yet, install with Nuget Package Manager:

Get Started

Start with this Query String:

What a party making sure the latitude property can be parsed to a double, the isMale parameter to a boolean, etc.  Let alone that a latitude value has to be within a given range.  No need to write such code yourself anymore...

Here is the route you take with T2O.  Create a C# class that represents your expected parameters, like the below:

Then make this call to the package's Convert method:

And a split second later here are your results:

Nice! (You will see more about the other two 'out' parameters shortly.)

Required Parameters

Let's remove the minimumRating and isMale parameters from the Query String:

Then make this (same) call to the package's Convert method:

Here are the results this time round:

Because there were validation errors, the class itself (myClass) did not get instantiated.  Note above that the 'invalidInputItems' collection has an entry for each of the two missing required fields

Optional Parameters

T2O uses the property's' declaration to know if a parameter is required or not.  Let's make those two properties (isMale and minimumRating) nullable:

Then make the same call to the package's Convert method (the same call without the minimumRating and isMale parameters) with the following results:

The isMale and minimumRating properties now have null values in the class instance.

Unrecognized Parameters

Add an unknown parameter, newPropName, to the Query String:

Using the same class as in the step above, make the call to the package's Convert method:

You see above how T2O deals with unexpected parameters.

Non-nullable Reference Types

C# 8 supports annotating a reference type as nullable or non-nullable.  There are different ways to turn this feature on.  This is not a C# class, so please just follow along with the approach taken here:

Feel free to ignore where I override a compiler warning (right below turning on nullability).  This is a topic for another day.

Now the reference type, Name, is non-nullable.

The Query String I am going to use next, does not include the 'name' parameter:

As can be expected, T2O objects:

As you just saw, T2O deals appropriately with non-nullable reference types.

Support for collections

So far we just dealt with a few built-in .NET types.  T2O also supports collection type parameters.  Consider the following class (with the new 'Languages' collection):

This is the Query String I am going to use next:

And the results are:

Now I am adding more items for the collection parameter:

Notice the mixed case above for the 'languages' Query String parameter name.  Yes, T2O treats property/parameter names case insensitive.

Let's first take another look at the parameters being passed into T2O's Convert method:

Here the caller tells T2O to use the '~' character as multi value separator character.

And the conversion results are:

On a side note, if these were parameters for a medical provider search, is the API code supposed to look for a provider that speaks one of the three languages or a provider that speaks all three?  It is up to the API code (that uses T2O) to treat the collections as ANDs or as ORs.

T2O Custom Attributes

T2O provides two types of attributes, namely what it refers to as Designated Type and as Range attributes  The below shows where I am using two Range attributes and also the Designate Type attributes on a few properties:

Expect T2O now to enforce more validations.  The 'name' parameter value must be between 5 and 100 characters in length.  'Latitude' must have a value between -90 and 90, 'Longitude' must have a value between -180 and 180 and 'Radius' a value between 0 and 10.

Next I am going to use the below Query String (with invalid parameter values for 'name', 'longitude' and 'radius'):

And the results are, as can be expected:

Below is the list of Designates Type attributes provided by T2O:


T2O enforces boundary checks for Range attributes.  The number types all have supporting T2O Range attributes.

Language/Locale

T2O is language/locale enabled.  Currently it provides support for US English only though.  To pass in the language, use the optional parameter as shown below:

Note that the InputValidationItem and ClassDefinition.Violation classes each have a set of error text and error code properties.  The code is constant and your code can rely on that value, but the text is free format text that can change any time.





More...

Detailed documentation for T2O is at the T2O details page.


Summary

This page provided a taste of what this package can do for you.  Thank you for your time.