[ROOT] / doc / toc / ARCCore / Class / ITypeDescriber

GetSyntaxHelp


Provides a standardized mechanism for describing single-property values (like 'PhoneNumber' of 'Customer' for instance).

(The difference between ITypeDescriber and IP is that the former must be stored 'inside' an IP.
In RDBMS-terms a ITypeDescriber is the Field stored within a IP which is the Post.)

The most important functionality usually provided is validation and parsing in a standardized manner.

This is done by a static method call 'EnrichKey' which is supposed to be available in a class 'implementing' this interface.
In this manner, types implementing this 'interface' is by this principle able to describe themselves to AgoRapide).
For a typical example, see EnrichKey.

Note how this interface in itself is empty
(apart from GetSyntaxHelp which is just a suggestion to use in your implementing classes.)

See Initialize for where this 'interface' is actually used.

EnrichKey should have the following signature:
public static void EnrichKey(PK k)

A typical method will set ValidatorAndParser although other attributes of PK may also be changed (which gives rise to the somewhat strange name for the method 'EnrichKey').

(note that for very common types like string, int, long, bool, DateTime, TimeSpan, Type, Uri and so on PKTypeAttribute provides a StandardValidatorAndParser.)

A typical implementation can look like this:

public static void EnrichKey(PK k) {
k.SetValidatorAndParser(new Func<string, ParseResult>(value =>
TryParse(value, out var retval, out var errorResponse) ?
ParseResult.CreateOK(retval) :
ParseResult.CreateError(errorResponse);
));
}

The typical TryParse method in the implementation class should follow the ordinary .NET pattern with the addition of a 'out string errorResponse' parameter which can communicate WHY the value was not valid for parsing. This helps a lot with error messages, making an API for instance much more user friendly.

Note the the implementation class should also overrride object.ToString() to a format actually understood by the ValidatorAndParser returned. This is necessary for the storage mechanism, like PropertyStream to work (serialization and de-serialization of objects).


See also IP which describes multiple value properties (that is, 'entities' like Customer, Product, Order).
Note that the use of a static method is a practical choice since it avoids AgoRapide having to instantiate the class for what is essential a static one-off operation done only once (for instance at application initialization, or on-demand).
This however means that the compiler is unable to check if your class really implements 'EnrichKey' as 'promised' by the fact of it being marked as implementing this interface. Missing implementations will show up at runtime with a helpful and explanatory error messages.

Note that for some attributes you actually have a choice of where to specify them.
(example below assumes a PKDataAttribute-class with a property called 'InvalidValueExample')
TODO: FIND ETTER EXAMPLES WHEN SOME REAL BasePKAttribute subclasses are defined in AgoRapide

You can specify either by

1) Tagging directly the corresponding 'enum' field (enums of type PropertyKeyEnum) with some PKTypeAttribute like:

enum CustomerP {
...
[PKType(Type=DateOfBirth)]
[PKData(InvalidValueExample = "1968-13-09")]
DateOfBirth,
...
}

(but then you will have to do that everywhere you are using the implementing class (in this example the type 'DateOfBirth') because there will be a separate PK generated for each 'enum' field).
or
2) by setting them when the resulting PK is passed to EnrichKey (from wherever 'DateOfBirth' is used) like (note, code is somewhat simplified):

public class DateOfBirth : ITypeDescriber {
...
public static void EnrichKey(PK k) {
var pkData = new PKDataAttribute();
pkData.AddPV(PKDataAttributeP.InvalidValueExample.A(), "1968-13-09");
k.AddP(IKType.FromType(pkData.GetType()), pkData);
});
}

The latter method is supposedly better.

Note that attributes like ValidatorAndParser can only be set through EnrichKey because they are too complex for the Attribute mechanism


GetSyntaxHelpEnables explanation of syntax in different contexts from one source:

Details

Generated 2024-03-29 00:51:26.479 UTC