Integrations

edit

An ID is read and written as its underlying value everywhere: a number or a string in JSON, a value in a BSON document or a database column, a segment of a URL. The generator writes a converter for each serializer, nested in the ID and registered by an attribute on it, so most libraries use them without configuration.

LibraryWhat the generator providesConfiguration
System.Text.JsonA JsonConverter<T>, also for dictionary keysNone, except with a source-generated JsonSerializerContext: register the converters in its options
Newtonsoft.JsonA JsonConverter, when the project references Newtonsoft.JsonNone
MongoDBA BSON serializer, when the project references MongoDB.BsonNone
TypeConverter and configurationA TypeConverter, used by Microsoft.Extensions.Configuration and UI frameworksNone
ASP.NET CoreTryParse and IParsable<T> for route and query values, and the JSON converter for bodiesNone
Entity Framework CoreNothing specificA value converter that you write once per ID type
YAMLA YamlConverter<T>, when the project references Meziantou.Framework.YamlNone, except with a source-generated YamlSerializerContext: register the converters in its options
TOMLA TomlConverter<T>, when the project references Meziantou.Framework.TomlNone, except with a source-generated TomlSerializerContext: register the converters in options that use it

Each converter can be turned off with an option.

Use a converter directly

The converters are public classes nested in the ID, named after it: ProjectId.ProjectIdJsonConverter, ProjectId.ProjectIdNewtonsoftJsonConverter, ProjectId.ProjectIdBsonConverter, ProjectId.ProjectIdYamlConverter, ProjectId.ProjectIdTomlConverter and ProjectId.ProjectIdTypeConverter. Create one when a library does not read the attributes, for instance to add it to JsonSerializerOptions.Converters for a source-generated context, to wrap it in your own converter, or to register it in another type.

To choose another accessibility, declare the converter in the ID with the accessibility you want. The generator writes the rest of the class and keeps your modifiers:

[StronglyTypedId<int>]
public partial struct WarehouseId
{
    // Declare the converter to choose its accessibility. The generator writes the rest of the type.
    internal sealed partial class WarehouseIdJsonConverter;
}