Harvzor.Optional.SystemTextJson 0.0.6

Harvzor.Optional

NuGet Package	Version
Harvzor.Optional
Harvzor.Optional.SystemTextJson
Harvzor.Optional.NewtonsoftJson

The problem

// The JSON would normally come from some external data source:
string json = "{}";

Foo foo = JsonSerializer.Deserialize<Foo>(json);

// This will print an empty string because C# will hydrate the model with the default value.
// There's no way to check if the model used a default value.
Console.WriteLine(foo.MyProperty); // ""    

public class Foo
{
    public string MyProperty { get; set; }
}

So just use a nullable value? (string?)

In the above example, you could make the string nullable (with string?), but now you're explicitly saying that null is value you want to accept (which you'll have to handle in your code).

What if you want to allow a client to explicitly set null ("{ "myProperty": null }"), and want to handle this in your code, while also knowing if the client didn't send anything?

The solution: Optional<T>

Basic example

You can use Optional<T> to know if a property or variable has been explicitly instantiated:

using Harvzor.Optional;

Foo foo = new Foo
{
    DefinedProperty = "Bar"
};

Console.WriteLine(foo.DefinedProperty.IsDefined); // True
Console.WriteLine(foo.UndefinedProperty.IsDefined); // False

// Now I can check if a value was explicitly instantiated:
if (foo.DefinedProperty.IsDefined) // True
    Console.WriteLine(foo.DefinedProperty.Value); // "Bar" 
    
if (foo.UndefinedProperty.IsDefined) // False
    Console.WriteLine(foo.UndefinedProperty.Value); // Won't print as the value wasn't explicitly instantiated.

Console.WriteLine(foo.UndefinedProperty.Value); // Will print the default value.

public class Foo
{
    public Optional<string> DefinedProperty { get; set; }
    public Optional<string> UndefinedProperty { get; set; }
}

Use it with JSON

This example uses System.Text.Json:

using System.Text.Json;
using Harvzor.Optional;

JsonSerializerOptions jsonSerializerOptions = new JsonSerializerOptions();
jsonSerializerOptions.Converters.Add(new Harvzor.Optional.SystemTextJson.OptionalJsonConverter());
jsonSerializerOptions.TypeInfoResolver = new DefaultJsonTypeInfoResolver
{
    Modifiers = { OptionalTypeInfoResolverModifiers.IgnoreUndefinedOptionals }
};

// The JSON would normally come from some external data source:
string json = "{\"DefinedProperty\":\"Bar\"}";

Foo foo = JsonSerializer.Deserialize<Foo>(json, jsonSerializerOptions)!;

Console.WriteLine(foo.DefinedProperty.IsDefined); // True
Console.WriteLine(foo.UndefinedProperty.IsDefined); // False

// Now I can check if a value was defined before I try using it:
if (foo.DefinedProperty.IsDefined) // True
    Console.WriteLine(foo.DefinedProperty.Value); // "Bar" 
    
if (foo.UndefinedProperty.IsDefined) // False
    Console.WriteLine(foo.UndefinedProperty.Value); // Won't print as the value wasn't defined.

public class Foo
{
    public Optional<string> DefinedProperty { get; set; }
    public Optional<string> UndefinedProperty { get; set; }
}

Use in an API

To use it in your controller models, simply register in your startup:

Harvzor.Optional.SystemTextJson

using Harvzor.Optional.SystemTextJson;

services
    .AddJsonOptions(options =>
    {
        options.JsonSerializerOptions.Converters.Add(new OptionalJsonConverter());
        options.JsonSerializerOptions.TypeInfoResolver = new DefaultJsonTypeInfoResolver
        {
            Modifiers = { OptionalTypeInfoResolverModifiers.IgnoreUndefinedOptionals }
        };
    });

Harvzor.Optional.NewtonsoftJson

using Harvzor.Optional.NewtonsoftJson;

services
    .AddNewtonsoftJson(options =>
    {
        options.SerializerSettings.Converters.Add(new OptionalJsonConverter());
        options.SerializerSettings.ContractResolver = new IgnoreUndefinedOptionalsContractResolver();
    });

Swagger support

If you're using Swashbuckle Swagger, you'll also need to tell it how your types should look:

services.AddSwaggerGen(options =>
{ 
    options.MapType<Optional<string>>(() => new OpenApiSchema
    {
        Type = "string"
    });
    
    options.MapType<Optional<int>>(() => new OpenApiSchema
    {
        Type = "integer"
    });
    
    options.MapType<Optional<float>>(() => new OpenApiSchema
    {
        Type = "number"
    });
    
    options.MapType<Optional<double>>(() => new OpenApiSchema
    {
        Type = "number"
    });
    
    options.MapType<Optional<bool>>(() => new OpenApiSchema
    {
        Type = "boolean"
    });
    
    // todo: array, object?
});

You can see what basic types are available here: https://swagger.io/docs/specification/data-models/data-types/

Use case: JSON Merge PATCH

... need docs ...

Releasing

GitLab CI

1. Create a new release with a semver release name

Manual release

In case the CI doesn't work:

1. Get an API key from https://www.nuget.org/account/apikeys

docker-compose build --build-arg version="{version}" push-nuget
docker-compose run --rm push-nuget --api-key {key}

Further reading

• https://stackoverflow.com/questions/63418549/custom-json-serializer-for-optional-property-with-system-text-json
• https://stackoverflow.com/questions/12522000/optionally-serialize-a-property-based-on-its-runtime-value