PMart.Enumeration

This set of libraries provides base classes to implement Enumeration classes, based on string values. It enables the strongly typed advantages, while using string enumerations.

It has, also, the possibility to create new enumerations at runtime (let's call it Dynamic Enumerations).

What are Enumeration Classes?

Enumeration classes are alternatives to enum type in C#. They enable features of an object-oriented language without the limitations of the enum type.

They are useful, for instance, for business related enumerations on Domain-Driven Design (DDD).

For more information about Enumeration classes, check the links on the section References.

NuGet Packages

PMart.Enumeration: The Enumeration base classes.

PMart.Enumeration.EFCore: The Entity Framework Core support for PMart.Enumeration.

PMart.Enumeration.JsonNet: The Newtonsoft Json.NET support for PMart.Enumeration.

PMart.Enumeration.SystemTextJson: The System.Text.Json support for PMart.Enumeration.

PMart.Enumeration.SwaggerGen: Support to generate Swagger documentation when using PMart.Enumeration.

PMart.Enumeration.Mappers: Mappers and mapping extensions for Enumerations (includes mapper for Mapperly).

PMart.Enumeration.Generator: A source generator to generate Enumeration classes from few lines of code.

Installation

Install one or more of the available NuGet packages in your project.

Use your IDE or the command:

dotnet add package <package name>

Usage

Read the documentation of the core package PMart.Enumeration here, to learn how to use the Enumeration and EnumerationDynamic classes.

EFCore Support

In EF Core, adding a property of type Enumeration or EnumerationDynamic to an entity requires setting the conversion to store the value of the enumeration on the database. The NuGet package PMart.Enumeration.EFCore has the required converters, you just need to add them to your model configuration.

Read the documentation for the package PMart.Enumeration.EFCore here.

Newtonsoft Json.NET Support

Using Newtonsoft Json.NET, if you need to serialize/deserialize objects that contain properties of type Enumeration or EnumerationDynamic, without any converters, the enumeration property would act like a regular object. The NuGet package PMart.Enumeration.JsonNet has the required converters to serialize the Enumeration classes like an enum or a string value.

Read the documentation for the package PMart.Enumeration.JsonNet here.

System.Text.Json Support

Using System.Text.Json, if you need to serialize/deserialize objects that contain properties of type Enumeration or EnumerationDynamic, without any converters, the enumeration property would act like a regular object. The NuGet package PMart.Enumeration.SystemTextJson has the required converters to serialize the Enumeration classes like an enum or a string value.

Read the documentation for the package PMart.Enumeration.SystemTextJson here.

Swagger Support

In an API with Swagger, if you would like to document on an enumeration property like an enum, you should use the NuGet package PMart.Enumeration.SwaggerGen.

Read the documentation for the package PMart.Enumeration.SwaggerGen here.

Mapping

To map between Enumeration classes or between Enumeration classes and string, you can use built-in features, like explained in the section Features.

Anyway, the NuGet package PMart.Enumeration.Mappers includes a set of extensions and mappers to help the mapping to/from string and between different types of Enumeration or EnumerationDynamic.

They are useful, for instance, to add support for mappers like Mapperly (check how to map enumeration classes with Mapperly here).

Read the documentation for the package PMart.Enumeration.Mappers here.

Enumeration Generator

Creating a new Enumeration class is a little bit verbose. Therefore, the package PMart.Enumeration.Generator was added to help on that. It is an incremental generator.

Read the documentation for the package PMart.Enumeration.Generator here.

Disclaimer

While the Enumeration class is a good alternative to enum type, it is more complex and also .NET doesn't handle it as it handles enum (e.g. JSON des/serialization, model binding, etc.), requiring custom code. Please be aware that Enumeration class may not fit your needs.

References

• Enumeration Classes:
  • Microsoft Docs: Using enumeration classes instead of enum types
  • Jimmy Bogard: Enumeration Classes
  • Ardalis: Enum Alternatives in C#
  • Ardalis: SmartEnum
  • Ankit Vijay: Enumeration Classes – DDD and beyond
  • Ankit Vijay: Enumeration
  • eShopOnContainers: Enumeration.cs
• Incremental Generators:
  • Roslyn Documentation: Incremental Generators
  • Roslyn Documentation: Incremental Generators Cookbook
  • Andrew Lock: Creating a source generator
  • Andrew Lock: NetEscapades.EnumGenerators