Fluxera.Enumeration.SystemTextJson 8.2.4

Prefix Reserved
There is a newer version of this package available.
See the version list below for details.
dotnet add package Fluxera.Enumeration.SystemTextJson --version 8.2.4                
NuGet\Install-Package Fluxera.Enumeration.SystemTextJson -Version 8.2.4                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Fluxera.Enumeration.SystemTextJson" Version="8.2.4" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Fluxera.Enumeration.SystemTextJson --version 8.2.4                
#r "nuget: Fluxera.Enumeration.SystemTextJson, 8.2.4"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Fluxera.Enumeration.SystemTextJson as a Cake Addin
#addin nuget:?package=Fluxera.Enumeration.SystemTextJson&version=8.2.4

// Install Fluxera.Enumeration.SystemTextJson as a Cake Tool
#tool nuget:?package=Fluxera.Enumeration.SystemTextJson&version=8.2.4                

Build Status

Fluxera.Enumeration

An object-oriented enumeration library.

Usage

Define an enumerable as C# class that inherits from the Enumeration<TEnum> base class. Add the enumeration options as public static readonly fields to the new enumerable class.

public sealed class Color : Enumeration<Color>
{
    public static readonly Color Red = new Color(0, "FF0000");
    public static readonly Color Green = new Color(1, "00FF00");
    public static readonly Color Blue = new Color(2, "0000FF");
    public static readonly Color White = new Color(3, "FFFFFF");
    public static readonly Color Black = new Color(4, "000000");

    /// <inheritdoc />
    private Color(int value, string hexValue, [CallerMemberName] string name = null!) 
        : base(value, name)
    {
        this.HexValue = hexValue;
    }

    public string HexValue { get; }
}
public class MessageType : Enumeration<MessageType>
{
    public static readonly MessageType Email = new EmailType();
    public static readonly MessageType Postal = new PostalType();
    public static readonly MessageType TextMessage  = new TextMessageType();

    /// <inheritdoc />
    private MessageType(int value, string name) 
        : base(value, name)
    {
    }

    private sealed class EmailType : MessageType
    {
        /// <inheritdoc />
        public EmailType() : base(0, "Email")
        {
        }
    }

    private sealed class PostalType : MessageType
    {
        /// <inheritdoc />
        public PostalType() : base(1, "Postal")
        {
        }
    }

    private sealed class TextMessageType : MessageType
    {
        /// <inheritdoc />
        public TextMessageType() : base(2, "TextMessage")
        {
        }
    }
}
public abstract class Animal : Enumeration<Animal>
{
    /// <inheritdoc />
    protected Animal(int value, string name) 
        : base(value, name)
    {
    }
}

public sealed class Mammal : Animal
{
    public static readonly Mammal Tiger = new Mammal(0);
    public static readonly Mammal Elephant = new Mammal(1);

    /// <inheritdoc />
    private Mammal(int value, [CallerMemberName] string name = null!) 
        : base(value, name)
    {
    }
}

public sealed class Reptile : Animal
{
    public static readonly Reptile Iguana = new Reptile(2);
    public static readonly Reptile Python = new Reptile(3);

    /// <inheritdoc />
    private Reptile(int value, [CallerMemberName] string name = null!) 
        : base(value, name)
    {
    }
}

The default type for the value is int, but several other types can be used as the value: byte, short,int,long,decimal,float,double,string and Guid.

public class GuidEnum : Enumeration<GuidEnum, Guid>
{
    public static readonly GuidEnum One = new GuidEnum(Guid.Parse("7a524c5a-7724-442d-a906-8219bce4a0fd"), "One");

    /// <inheritdoc />
    public GuidEnum(Guid value, string name) 
        : base(value, name)
    {
    }
}

public class LongEnum : Enumeration<LongEnum, long>
{
    public static readonly LongEnum One = new LongEnum(999999999999999999, "One");

    /// <inheritdoc />
    public LongEnum(long value, string name) 
        : base(value, name)
    {
    }
}

The Enumeration<TEnum> provides a fluent API to configure switch-case like structures to simplify the execution of action for specific cases.

public void PrintColorInfo(Color color)
{
    color
        .When(Color.Red).Then(() => SetConsoleColor(ConsoleColor.Red))
        .When(Color.Blue).Then(() => SetConsoleColor(ConsoleColor.Blue))
        .When(Color.Green).Then(() => SetConsoleColor(ConsoleColor.Green))
        .Default(() => SetConsoleColor(ConsoleColor.White));

    Console.WriteLine($"{color}({color.Value}) => #{color.HexValue}");
}

Serialization Support

At the moment serialization support is available for:

Entity Framework Core

To support Enumeration<TEnum> in EFCore use one of the available extension methods on the ModelBuilder.

// Store the name in the database.
modelBuilder.ApplyEnumerationNameConversions();

// Store the value in the database.
modelBuilder.ApplyEnumerationValueConversions();

Newtonsoft.Json (JSON.NET)

To support Enumeration<TEnum> in JSON.NET use one of the available extensions methods on the JsonSerializerSettings.

JsonSerializerSettings settings = new JsonSerializerSettings();

// Use the name to serialize all enumerations.
settings.UseEnumerationNameConverter();

// Use the value to serialize all enumerations.
settings.UseEnumerationValueConverter();

// Use the name to serialize just the Color enumeration.
settings.UseEnumerationNameConverter<Color>();

// Use the value to serialize just the Color enumeration.
settings.UseEnumerationValueConverter<Color>();

JsonConvert.DefaultSettings = () => settings;

LiteDB

To support Enumeration<TEnum> in LiteDB use one of the available extensions methods on the BsonMapper.

// Store the name in the database for all enumerations available in the given assembly.
BsonMapper.Global.UseEnumerationName(Assembly.GetExecutingAssembly());

// Store the value in the database for all enumerations available in the given assembly.
BsonMapper.Global.UseEnumerationValue(Assembly.GetExecutingAssembly());

// Store the name in the database just for the Color enumeration.
BsonMapper.Global.UseEnumerationName<Color>();

// Store the value in the database just for the Color enumeration.
BsonMapper.Global.UseEnumerationName<Color>();

MongoDB

To support Enumeration<TEnum> in MongoDB use one of the available extensions methods on the ConventionPack.

ConventionPack pack = new ConventionPack();

// Store the name in the database.
pack.AddEnumerationNameConvention();

// Store the value in the database.
pack.AddEnumerationValueConvention();

ConventionRegistry.Register("ConventionPack", pack, t => true);

System.Text.Json

To support Enumeration<TEnum> in System.Text.Json use one of the available extensions methods on the JsonSerializerOptions.

JsonSerializerOptions options = new JsonSerializerOptions();

// Use the name to serialize all enumerations.
options.UseEnumerationNameConverter();

// Use the value to serialize all enumerations.
options.UseEnumerationValueConverter();

// Use the name to serialize just the Color enumeration.
settings.UseEnumerationNameConverter<Color>();

// Use the value to serialize just the Color enumeration.
settings.UseEnumerationValueConverter<Color>();

Future

We plan to implement support for OData server- and client-side to enable queries on Enumeration like is was an simple C# enum. An Enumeration should generate an EdmEnumType in the metadata for an OData feed.

The simple way would be to add the enumeraions as complex type, but that feels wrong because the object-oriented enumeration should work like an enum and the EDM model would not reflect the available options.

EdmEnumType color = new EdmEnumType("Default", "Color");
color.AddMember(new EdmEnumMember(color, "Red", new EdmIntegerConstant(0)));
color.AddMember(new EdmEnumMember(color, "Blue", new EdmIntegerConstant(1)));
color.AddMember(new EdmEnumMember(color, "Green", new EdmIntegerConstant(2)));
model.AddElement(color);

This cannot be achieved using the model builder because the enum methods are tightly bound to C# enum.

<EnumType Name="Color">
   <Member Name="Red" Value="0" />
   <Member Name="Blue" Value="1" />
   <Member Name="Green" Value="2" />
</EnumType>

We want to support filter queries like so:

https://localhost:5001/odata/Cars?$filter=Color eq 'Blue'
https://localhost:5001/odata/Cars?$filter=Color eq 1

https://github.com/OData/WebApi/issues/1186 https://github.com/OData/WebApi/blob/master/src/Microsoft.AspNet.OData.Shared/UnqualifiedCallAndEnumPrefixFreeResolver.cs

We also plan to support Swagger documentation in ASP.NET Core applications.

References

This library was inspired by:

Søren Pedersen - Enumeration

Steve Smith - SmartEnum

Kyle Herzog - ExtendableEnums

MakoLab S.A. - SpecializedEnum

Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (4)

Showing the top 4 NuGet packages that depend on Fluxera.Enumeration.SystemTextJson:

Package Downloads
Fluxera.Extensions.Hosting.Modules.AspNetCore

A module that enables ASP.NET Core.

Fluxera.Extensions.Hosting.Modules.Messaging

A module that enables messaging based on MassTransit.

Fluxera.Extensions.Hosting.Modules.HttpClient

A module that enables HTTP client services.

Fluxera.Queries.AspNetCore

An OData v4 query parser and runtime for ASP.NET Core controllers and minimal APIs.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
9.0.1 305 11/16/2024
9.0.0 100 11/14/2024
8.2.4 407 11/1/2024
8.2.3 104 7/9/2024
8.2.2 1,316 6/15/2024
8.2.1 102 6/12/2024
8.2.0 105 6/12/2024
8.1.1 512 6/2/2024
8.1.0 562 5/26/2024
8.0.8 136 5/24/2024
8.0.7 105 5/24/2024
8.0.6 5,678 4/13/2024
8.0.5 168 4/13/2024
8.0.4 671 3/19/2024
8.0.3 1,958 2/22/2024
8.0.2 4,844 1/4/2024
8.0.1 856 11/23/2023
8.0.0 1,095 11/15/2023
7.1.6 792 7/23/2023
7.1.5 218 7/20/2023
7.1.4 718 6/21/2023
7.1.3 3,488 4/13/2023
7.1.2 937 3/16/2023
7.1.1 1,482 2/24/2023
7.1.0 2,109 1/18/2023
7.0.7 2,729 12/22/2022
7.0.6 328 12/13/2022
7.0.5 933 12/13/2022
7.0.4 1,426 12/9/2022
7.0.3 369 11/15/2022
7.0.2 340 11/12/2022
7.0.0 347 11/9/2022
6.1.6 3,226 10/12/2022
6.1.5 13,921 9/15/2022
6.1.4 2,404 7/30/2022
6.1.3 2,399 6/30/2022
6.1.2 2,424 6/15/2022
6.1.1 2,497 6/7/2022
6.1.0 453 6/1/2022
6.0.13 447 5/28/2022
6.0.12 466 5/5/2022
6.0.11 472 4/20/2022
6.0.10 448 3/26/2022
6.0.9 452 3/24/2022
6.0.8 466 2/17/2022
6.0.7 361 12/17/2021
6.0.6 554 12/11/2021
6.0.3 343 12/9/2021