Work with a type known only at run time
Domain code and the integrations use the typed path — Iban.TryCreate, or the static abstract members of
IValueObject<TSelf, TValue> through a type parameter — which neither boxes nor allocates. Some code only has a
Type: a generic importer, a tool that reads configuration, an integration of your own. That code goes through
the registry, in AdCodicem.ValueObjects.Metadata.
if (ValueObjectRegistry.TryGet(type, out var descriptor)
&& descriptor.TryParse(text, CultureInfo.InvariantCulture, out var boxed, out var validation))
{
// boxed is the value object, as object
}
A descriptor exposes what the type declares and how to build one:
ValueObjectTypeandValueType, the value object and its underlying type;Schema, the declared rules — lengths, pattern, bounds, format, known values — as data;Create,TryCreate,CreateUncheckedandTryParse, which take and return boxed values;GetValueandFormat, to read an instance back;Accept, which hands the type arguments back to code of your own, as the next section shows.
A rejection carries the same ValidationResult as the typed path, with the code of the rule that fired. Create
and TryCreate reject a null as value_object.required whatever the underlying type: a decimal value object
does not read it as zero.
Back to the typed path
A boxed delegate suits a call or two at start-up. An integration that keeps working with the value object — a
formatter, a serializer, a type handler — wants an adapter closed over it, MyFormatter<TSelf, TValue>, which runs on
the typed path. Closing it from a Type with MakeGenericType and Activator.CreateInstance works under the JIT, and
fails under native AOT, which has no code for a generic closed over a struct at run time. The descriptor hands the type
arguments back instead, to an IValueObjectVisitor<TResult>:
sealed class FormatterFor : IValueObjectVisitor<IFormatter>
{
public IFormatter Visit<TSelf, TValue>()
where TSelf : struct, IValueObject<TSelf, TValue>
=> new ValueObjectFormatter<TSelf, TValue>();
}
foreach (var descriptor in ValueObjectRegistry.GetRegistered())
{
formatters.Add(descriptor.ValueObjectType, descriptor.Accept(new FormatterFor()));
}
Accept calls Visit with the type arguments the descriptor was built with, so the adapter is closed at compile time.
Under native AOT, the compiler generates Visit for each value object a descriptor is built for in code: every one the
generator registers, and every one registered by hand, a value object written by hand or a construction of a generic
one. A visitor needing context — a builder, a flag — holds it in fields. Each Visit is compiled once per value
object, since a struct type argument shares no code, and only for the visitors the application creates.
Every integration that closes an adapter over a value object it knows only by its Type does so this way: the Dapper
integration registers its handlers, the MongoDB provider builds the serializer the driver asks it for, the MessagePack
resolver the formatter MessagePack asks it for, protobuf-net's AddValueObjects names the closed serializer type of each
value object it registers, the MVC model binder provider
creates its binders, the minimal API
filter of AdCodicem.ValueObjects.AspNetCore.Http closes the check of each parameter it explains, the Azure Functions
converter closes the conversion of each value object a parameter binds and its middleware the check of each it
explains, the HotChocolate type discovery handler the scalar of each value object a schema meets, the NJsonSchema
package the converter that writes a value object's examples through the Newtonsoft.Json settings of a schema, the Blazor
input the text adapters, plain and nullable, of the value object it binds, through a visitor that is not generic,
DataAnnotations' [NotDefault] its check of the default instance, once per type, the JSON converter factory closes the general-purpose converter it gives a value object written by hand, the test-data sampler's
Next(descriptor) draws a value, the AutoFixture customization answers a request, the Bogus extensions give a member a
rule, FsCheck's MergeValueObjects merges an arbitrary, and the Entity Framework Core conventions map each value object
and each entity identifier, while a model is built. One converter is the exception: that of an optional property,
Iban?, which C# names only under a constraint Visit cannot prove, so the value object conventions close it with
MakeGenericType, over the type arguments the visitor received. Entity Framework Core builds no model under native AOT,
so that never runs there. The JSON Patch adapter of a dictionary keyed by value objects or holding them, which
TryApplyTo closes over the dictionary's two types as JSON Patch closes its own, is the other: a visitor names the value
object, never the dictionary's other type, and MVC's JSON Patch runs in no native binary.
An entity identifier's descriptor, from EntityIdRegistry, has the same way out: EntityIdDescriptor.Accept hands an
IEntityIdVisitor<TResult> the identifier type, constrained to IEntityId<TId>, so the visitor reaches TId.New().
The MongoDB identifiers package registers its id generators that way:
sealed class GeneratorFor : IEntityIdVisitor<IIdGenerator>
{
public IIdGenerator Visit<TId>() where TId : struct, IEntityId<TId> => new EntityIdGenerator<TId>();
}
foreach (var descriptor in EntityIdRegistry.GetRegistered())
{
BsonSerializer.RegisterIdGenerator(descriptor.ValueObjectType, descriptor.Accept(new GeneratorFor()));
}
Inside the adapter, the rules are TSelf.Schema, the static member of IValueObject<TSelf, TValue> that the generator
emits and registers as the descriptor's Schema: TSelf.Schema.MaxLength sizes a column with no registry to ask, as
HasValueObjectConversion does. The Entity Framework Core conventions, which hold the descriptor already, size a column
by its Schema instead, handed to their visitor in a field, so that a value object registered by hand with a schema of
its own is mapped by that schema.
Cheaper questions
ValueObjectRegistry.IsValueObject(type) and ValueObjectRegistry.GetUnderlyingType(type) answer without building
a descriptor. Like TryResolve, they unwrap Nullable<T>, which is what a model binder or a serializer is usually
holding.
A value object is a struct implementing IValueObject<TSelf, TValue> over itself. IsValueObject answers true
exactly for the types TryResolve describes, and false for an interface, a class, or a struct carrying only the
IValueObject marker or IValueObject<TValue>. GetUnderlyingType answers null for the same types, even one that
declares a value through IValueObject<TValue>. The integrations claim a type by the same rule: the JSON converter
factory, the Newtonsoft.Json converter, the MVC model binder, MustParseAs and DataAnnotations' [ParsesAs] and
[NotDefault] leave anything else to the framework, or refuse it, and the argument check of AdCodicem.ValueObjects.AI and AdCodicem.ValueObjects.ModelContextProtocol
tells a value-object parameter by it.
Nullable value objects
TryGet and TryResolve accept Iban? as well as Iban, and return the descriptor of Iban for both: a descriptor
describes the value object itself, never its nullable type, and nothing in it handles a null. An integration built on
it handles both before the descriptor does:
- A converter or a provider that closes a generic type of its own over the value object closes it over
descriptor.ValueObjectType, not over the type it was asked for. Closed overIban?, it fails on the first nullable property, since the value object's constraint refuses aNullable<T>:GenericArguments[0], 'System.Nullable`1[Iban]' … violates the constraint of type 'TSelf'. GetValue,FormatandValidateWritetake an instance, nevernull: thenullof anIban?throws aNullReferenceExceptioninside them. Write thenullyourself, or skip the property.
Where the host has its own wrapper for nullable types, as most serializers do, claim only the value object and let
that wrapper deal with null.
Generic value objects
A generic value object registers its generic definition, since its registration knows none of its constructions:
ValueObjectRegistry.GetRegisteredGenericDefinitions() lists them. TryResolve describes a construction the first time
it is asked for it, from the schema and the converter the generator wrote on it, and caches the descriptor;
TryGet finds it from then on. Describing it takes reflection and dynamic code, and so does visiting the descriptor it
builds, so under native AOT, register each construction you look up, which reads its schema off the type:
ValueObjectRegistry.Register<Code<Order>, string>(static () => new Code<Order>.ValueJsonConverter()).
Value objects written by hand
A value object written by hand implements IValueObject<TSelf, TValue> in full, static ValueObjectSchema Schema
included: the rules its Validate enforces, as data, or ValueObjectSchema.Unconstrained when it publishes none. Its
known values go in KnownValues, and their names, which the OpenAPI document publishes, in KnownValueDetails, one
KnownValueInfo per value, in the same order, which the contract kit
checks. Over text, Comparison states the comparison its Validate looks them up with, which the
MongoDB collection validator and the
EF Core CHECK constraints read before they write a closed set: left
null, they try the other cases of each known value and a trailing soft hyphen, fewer spellings than a culture's
comparison takes. IsUnicode = false maps it to non-Unicode text as the option does.
Nothing registers it, so TryResolve describes it by reflection, the first time it is asked, with that schema, the one
generic code constrained on it reads, whatever [ValueObject<T>] or [KnownValue] annotation it also carries. Where no
generator runs, nothing reads an annotation: state each rule in the schema. Under native AOT, which cannot describe it
by reflection, register it, ValueObjectRegistry.Register<Link, Uri>(Link.Schema): its descriptor is then built in
code, and the JSON converter factory serves it the general-purpose converter through it.
The registry keeps the descriptor TryResolve builds, as it keeps that of a construction: TryGet finds the value
object from then on, and GetRegistered lists it. Whatever asks first, a serializer, a model binder or a validator,
registers it for the rest of the process, and every model built afterwards maps it through ConfigureValueObjects.
ConfigureEntityIds asks for each identifier this way, so an identifier written by hand and registered with
EntityIdRegistry alone joins the value object registry the first time a model is built, as a generated identifier,
which registers itself in both, always has.
When a type is not found
Nothing needs registering by hand: every value object joins the registry through a generated module
initializer. A module initializer only runs once its assembly is loaded, though, so code that looks a type up
before anything else has touched that assembly can call
ValueObjectRegistry.EnsureAssemblyRegistered(assembly) first. The EF Core, Dapper and MongoDB entry points already
do, and so does the Serilog one for each assembly named in its Assemblies option.