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.
Install one or more of the available NuGet packages in your project.
Use your IDE or the command:
dotnet add package <package name>
Usage
An Enumeration is a class that holds a value of type string. Each Enumeration class should have declared one or more static instances to set the available enumeration members.
Create a new enumeration class by extending Enumeration<T>, where T is the class itself.
Add a private constructor, as in the bellow example.
Create a public static readonly instance of the class for each enumeration member.
Or you can use the Generator in PMart.Enumeration.Generator package to generate the code for you!
The Enumeration classes enables the several features described bellow.
For instance, you can add behavior, and/or you can use dynamic enumerations (created in runtime), etc.
Value
It is the string value that the enumeration class holds:
Get all the enumerations from an enumeration class:
var allCommunicationTypes = CommunicationType.GetMembers(); // returns an IEnumerable<CommunicationType> with CommunicationType.Email, CommunicationType.Sms and CommunicationType.PushNotification
var communicationTypesCount = CommunicationType.GetMembers().Count(); // returns 3
The list of possible enumerations is a Lazy object behind the scene, and it is evaluated only if needed.
GetValues
Get all the possible values of an enumeration class:
var allCommunicationTypeValues = CommunicationType.GetValues(); // returns an IEnumerable<string> with "Email", "SMS" and "PushNotification"
var communicationTypeValuesCount = CommunicationType.GetValues().Count(); // returns 3
HasValue
Find out if there is any enumeration member with a specific value (ignoring letters case):
Get an enumeration instance from a string that matches the value of the enumeration (ignoring letters case), or null when there isn't any enumeration with that value:
// Parse the string to Enumeration:
var communicationType = CommunicationType.GetFromValueOrDefault("email"); // returns CommunicationType.Email
// Verify if exists an enumeration with the value (GetFromValueOrDefault returns null if there isn't any enumeration with the value).
var isValid = communicationType is not null; // true
Note: When there's instances with equivalent values (same value ignoring case), the GetValueOrDefault can return any of the instances (is nondeterministic). Therefore, enumeration members with equivalent values are not recommended.
// Let's imagine we have these two members:
// public static readonly CommunicationType Email = new("Email");
// public static readonly CommunicationType EmailWithDifferentCase = new("EMAIL"); // same value, different case (this is not recommended)
var emailType = CommunicationType.GetFromValueOrDefault("Email"); // this may return CommunicationType.Email or CommunicationType.EmailWithDifferentCase (they have equivalent values)
var isSame = ReferenceEquals(emailType, CommunicationType.Email); // sometimes is true, sometimes is false, is nondeterministic
var isEqual = emailType == EmailWithDifferentCase; // always true. Even if they are different instances, they are equal. Check the Equality section bellow.
Equality
Two different instances of a type derived from Enumeration are equal if they are from the same enumeration type
and if the value of both is equivalent, ignoring letters case.
// Let's imagine we have these two members:
// public static readonly CommunicationType Email = new("Email");
// public static readonly CommunicationType EmailWithDifferentCase = new("EMAIL"); // same value, different case (this is not recommended)
var isSame = ReferenceEquals(CommunicationType.Email, CommunicationType.EmailWithDifferentCase); // false (they are different instances)
var isEqual = CommunicationType.Email == CommunicationType.EmailWithDifferentCase; // true (they are different instances, but they have the same value, ignoring case)
It is also possible to test the equality between a string and an Enumeration. It also ignores the letters case. The string must be on the left side of the equality operator:
Since you have objects and not constant values (like in a enum), the switch statement can't be constructed the same way as for an enum, but you can, for example, use pattern matching this way:
private ISender? GetCommunicationSenderForCommunicationType(CommunicationType communicationType)
{
// A switch statement for pattern matching
return communicationType switch
{
_ when communicationType == CommunicationType.Email => _emailSender,
_ when communicationType == CommunicationType.PushNotification => _pushNotificationSender,
_ when communicationType == CommunicationType.Sms => _smsSender,
_ => null
};
}
Enumeration with Behavior
We can add custom methods to the Enumeration class (it's an object, after all).
Here is a simple example, with a method ParseMessage and with a property IsPhoneNumberRequired:
using PMart.Enumeration;
namespace Enumeration.Sample.Enumerations;
/// <summary>
/// The communication type enumeration.
/// </summary>
public class CommunicationTypeWithBehaviour : Enumeration<CommunicationTypeWithBehaviour>
{
public static readonly CommunicationTypeWithBehaviour Email = new("Email");
public static readonly CommunicationTypeWithBehaviour Sms = new("SMS");
public static readonly CommunicationTypeWithBehaviour PushNotification = new("PushNotification");
/// <summary>
/// Parses the message.
/// </summary>
/// <param name="message">The message content.</param>
/// <returns>The parsed message.</returns>
public string ParseMessage(string message)
{
return $"Message parsed by the communication type {this}: {message}";
}
/// <summary>
/// Gets a value indicating if this communication type requires phone number.
/// </summary>
/// <returns><c>true</c> if this communication type requires phone number; <c>false</c> otherwise.</returns>
public bool IsPhoneNumberRequired => this switch
{
_ when this == Sms => true,
_ when this == PushNotification => true,
_ => false
};
private CommunicationTypeWithBehaviour(string value) : base(value)
{
}
}
We can also use inheritance to add specific behavior or properties for each enumeration member in an Enumeration class.
Check this example, where the communication type has subclasses with a specific implementation of ParseMessage() and IsPhoneNumberRequired:
using PMart.Enumeration;
namespace Enumeration.Sample.Enumerations;
/// <summary>
/// The communication type enumeration.
/// </summary>
public abstract class CommunicationTypeWithSpecificBehaviour : Enumeration<CommunicationTypeWithSpecificBehaviour>
{
public static readonly CommunicationTypeWithSpecificBehaviour Email = new EmailType();
public static readonly CommunicationTypeWithSpecificBehaviour Sms = new SmsType();
public static readonly CommunicationTypeWithSpecificBehaviour PushNotification = new PushNotificationType();
/// <summary>
/// Parses the message.
/// </summary>
/// <remarks>Each communication type, implements its own way of parsing the message.</remarks>
/// <param name="message">The message content.</param>
/// <returns>The parsed message.</returns>
public abstract string ParseMessage(string message);
/// <summary>
/// Gets a value indicating if this communication type requires phone number.
/// </summary>
/// <returns><c>true</c> if this communication type requires phone number; <c>false</c> otherwise.</returns>
public abstract bool IsPhoneNumberRequired { get; }
private CommunicationTypeWithSpecificBehaviour(string value) : base(value)
{
}
private sealed class EmailType : CommunicationTypeWithSpecificBehaviour
{
public EmailType() : base("Email")
{
}
/// <inheritdoc />
public override string ParseMessage(string message)
{
return $"<html>{message}</html>";
}
/// <inheritdoc />
public override bool IsPhoneNumberRequired => false;
}
private sealed class SmsType : CommunicationTypeWithSpecificBehaviour
{
public SmsType() : base("Sms")
{
}
/// <inheritdoc />
public override string ParseMessage(string message)
{
return $"Message encoded for SMS: {message}";
}
/// <inheritdoc />
public override bool IsPhoneNumberRequired => true;
}
private sealed class PushNotificationType : CommunicationTypeWithSpecificBehaviour
{
public PushNotificationType() : base("PushNotification")
{
}
/// <inheritdoc />
public override string ParseMessage(string message)
{
return $"Message encoded for push notification: {message}";
}
/// <inheritdoc />
public override bool IsPhoneNumberRequired => true;
}
}
Dynamic Enumerations
Instead of extending Enumeration class, you can extend the EnumerationDynamic class.
The EnumerationDynamic class extends the Enumeration class, therefore, it has the same features.
With this type, you will have an extra method that adds the possibility to create new EnumerationDynamic instances at runtime, if there isn't any enumeration member with a specific value.
To create an EnumerationDynamic is the same as Enumeration, but it requires a public empty constructor, in addition to the private constructor.
You can use the Generator in PMart.Enumeration.Generator package, that generates the code for you, and therefore you don't need to worry about the constructors.
Continuing with the communication types, here is an example using EnumerationDynamic:
using PMart.Enumeration;
namespace Enumeration.Sample.Enumerations;
/// <summary>
/// The communication type enumeration.
/// </summary>
public class CommunicationTypeDynamic : EnumerationDynamic<CommunicationTypeDynamic>
{
public static readonly CommunicationTypeDynamic Email = new("Email");
public static readonly CommunicationTypeDynamic Sms = new("SMS");
public static readonly CommunicationTypeDynamic PushNotification = new("PushNotification");
public CommunicationTypeDynamic()
{
}
private CommunicationTypeDynamic(string value) : base(value)
{
}
}
Now, you can use the method GetFromValueOrNew(string? value), that returns an instance of the enumeration type, or null if the provided value is null.
If there is an enumeration with the provided value (ignoring letters case), it will return that instance, else it will create a new instance with the provided value and return it (or null if the provided value is null).
var a = CommunicationTypeDynamic.GetFromValueOrNew("Email"); // returns CommunicationTypeDynamic.Email
var b = CommunicationTypeDynamic.GetFromValueOrNew("EMAIL"); // returns CommunicationTypeDynamic.Email
var c = CommunicationTypeDynamic.GetFromValueOrNew("someUnknownType"); // returns new instance of CommunicationTypeDynamic, with value = "someUnknownType"
var d = CommunicationTypeDynamic.GetFromValueOrNew(null); // returns null
var aValue = a?.Value; // "Email"
var bValue = b?.Value; // "Email"
var cValue = c?.Value; // "someUnknownValue"
var dValue = d?.Value; // null
Note: Instances created with equivalent values are equal (check section Equality), but different instances:
var a = CommunicationTypeDynamic.GetFromValueOrNew("someUnknownType"); // returns a new instance of CommunicationTypeDynamic, with value = "someUnknownType"
var b = CommunicationTypeDynamic.GetFromValueOrNew("someUnknownType"); // returns another new instance of CommunicationTypeDynamic, with value = "someUnknownType"
var c = CommunicationTypeDynamic.GetFromValueOrNew("SOMEuNKNOWtTYPE"); // returns another new instance of CommunicationTypeDynamic, with value = "SOMEuNKNOWtTYPE"
var isAEqualToB = a == b; // true
var isAEqualToC = a == c; // true
var isBEqualToC = b == c; // true
var isASameInstanceThanB = ReferenceEquals(a, b); // false
var isASameInstanceThanC = ReferenceEquals(a, c); // false
var isBSameInstanceThanC = ReferenceEquals(b, c); // false
Note: when you create a new enumeration with EnumerationDynamic, that enumeration will not be added to the list of existent enumeration members:
var newCommunicationType = CommunicationTypeDynamic.GetFromValueOrNew("someUnknownType"); // returns a new instance of CommunicationTypeDynamic, with value = "someUnknownType"
var existsTheNewTypeOnCommunicationTypes = CommunicationTypeDynamic
.GetMembers()
.Any(ct => ct == newCommunicationType); // false
Why Dynamic Enumerations?
The EnumerationDynamic class can be useful when you want to accept values that are not in the declared enumerations or when you want to have the possibility to create new enumerations at runtime.
For example, an API A sends data to API B that then redirects the data to API C.
All these APIs use enumeration classes, but API B don't care about the value, it just sends it to API C. So, using EnumerationDynamic on API B you don't need to deploy API B every time you had a new value to the enumeration on API A.
Other way, using Enumeration instead of EnumerationDynamic, you would need to update API B in order to recognize the new enumeration member and send it to the API C.
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. Check this sample:
For this entity:
public class CommunicationRecord
{
public Guid Id { get; set; }
public DateTime SentAt { get; set; }
public string To { get; set; } = null!;
public CommunicationType? Type { get; set; }
public CommunicationTypeDynamic? TypeDynamic { get; set; }
}
You need to configure it on model creating this way on your DbContext:
public async Task<IEnumerable<CommunicationRecord>> GetCommunicationRecordsByType(CommunicationType communicationType)
{
var records = await _context.CommunicationRecords
.Where(r => r.Type == communicationType)
.ToListAsync();
return records;
}
Note: In a query, the case sensitivity is determined by the database provider.
E.g., if you save the record using an EnumerationDynamic with value "Email", and then query the database using another instance of EnumerationDynamic with value "EMAIL", it is possible you get no results, depending on the database.
For example, MS SQL Server is, by default, case-insensitive, so you would get the result.
Newtonsoft Json.NET Support
Using Newtonsoft Json.NET, if you need to serialize/deserialize objects that contain properties of type Enumeration, without any converters, the enumeration property would act like a regular object.
For example, using this model:
public class CommunicationRecord
{
public DateTime SentAt { get; set; }
public string To { get; set; } = null!;
public CommunicationType Type { get; set; } = null!;
}
The JSON without any custom JSON converters would be like:
For that, you just need to use the custom converters available on the NuGet package PMart.Enumeration.JsonNet.
An example where the converter is added by attribute:
public class CommunicationRecord
{
public DateTime SentAt { get; set; }
public string To { get; set; } = null!;
[JsonConverter(typeof(EnumerationConverter<CommunicationType>))]
public CommunicationType Type { get; set; } = null!;
}
An example where the converter is added on the serializer converters:
public string SerializeCommunicationRecord(CommunicationRecord communicationRecord)
{
var json = JsonConvert.SerializeObject(communicationRecord, new EnumerationConverter<CommunicationType>());
return json;
}
For enumerations of type EnumerationDynamic, you can use the generic converter EnumerationDynamicConverter<T>.
When you have several enumeration types that you would like to register globally, instead of registering all the converters of type EnumerationConverter<T> (or EnumerationDynamicConverter<T>), one for each enumeration type, you can use the non-generic converter EnumerationConverter.
This converter evaluates if the object is derived from Enumeration or EnumerationDynamic and handles it accordingly. It might be a little less performant.
public string SerializeCommunicationRecord(CommunicationRecord communicationRecord)
{
var json = JsonConvert.SerializeObject(communicationRecord, new EnumerationConverter());
return json;
}
System.Text.Json Support
Using System.Text.Json, if you need to serialize/deserialize objects that contain properties of type Enumeration, without any converters, the enumeration property would act like a regular object.
Again, for the same model example:
public class CommunicationRecord
{
public DateTime SentAt { get; set; }
public string To { get; set; } = null!;
public CommunicationType Type { get; set; } = null!;
}
The JSON without any custom JSON converters would be like:
For that, you just need to use the JSON converter EnumerationConverterFactory available on the NuGet package PMart.Enumeration.SystemTextJson.
An example where the converter is added by attribute:
public class CommunicationRecord
{
public DateTime SentAt { get; set; }
public string To { get; set; } = null!;
[JsonConverter(typeof(EnumerationConverterFactory))]
public CommunicationType Type { get; set; } = null!;
}
An example where the converter is added on the serializer options:
public string SerializeCommunicationRecord(CommunicationRecord communicationRecord)
{
var serializerOptions = GetSerializerOptions();
var json = JsonSerializer.Serialize(communicationRecord, serializerOptions);
return json;
}
private JsonSerializerOptions GetSerializerOptions()
{
return new JsonSerializerOptions
{
Converters = { new EnumerationConverterFactory() }
};
}
Swagger Support
If you would like to add an enumeration property to a model from an API and would like to document it on Swagger like an enum, you should install the NuGet package PMart.Enumeration.SwaggerGen and add the schema filter EnumerationSchemaFilter to the Swagger options on your Program.cs (or Startup.cs), like in this example:
builder.Services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1", new OpenApiInfo {Version = "v1", Title = "Sample API"});
options.SchemaFilter<EnumerationSchemaFilter>();
});
Here's an example of the result:
Mapping
Map using built-in features
To map from a Enumeration or EnumerationDynamic to a string, it is very easy, as explained in the section Features:
var stringValue = CommunicationType.Email.Value; // "Email"
// Or:
var stringValue = CommunicationType.Email.ToString(); // "Email"
To map from a string to a Enumeration, is also straightforward, as explained in the section Features:
var enumeration = CommunicationType.GetFromValueOrDefault("Email"); // returns CommunicationType.Email
To benefit from the EnumerationDynamic features and map from a string to a EnumerationDynamic, as explained in the section Dynamic Enumerations, just use:
var enumeration = CommunicationTypeDynamic.GetFromValueOrNew("someUnknownType"); // returns a new CommunicationTypeDynamic with value "someUnknownType"
To map between different types of Enumeration or EnumerationDynamic, you can do it like this for Enumeration types:
var enumeration = OtherCommunicationType.GetFromValueOrDefault(communicationType.Value);
Or like this for EnumerationDynamic types:
var enumeration = OtherCommunicationTypeDynamic.GetFromValueOrNew(communicationType.Value);
Map using Extensions or Mappers
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.
And they are prepared for null values.
Here is an example using the extensions and the mappers to map between Enumeration and string:
public string? MapCommunicationTypeToStringUsingExtensions(CommunicationType communicationType)
{
return communicationType.MapToString();
}
public CommunicationType? MapStringToCommunicationTypeUsingExtensions(string communicationType)
{
return communicationType.MapToEnumeration<CommunicationType>();
}
public string MapCommunicationTypeToStringUsingMapper(CommunicationType communicationType)
{
return StringEnumerationMapper<CommunicationType>.MapToString(communicationType);
}
public CommunicationType MapStringToCommunicationTypeUsingMapper(string communicationType)
{
return StringEnumerationMapper<CommunicationType>.MapToEnumeration(communicationType);
}
Here is an example using the extensions and the mappers to map between EnumerationDynamic and string:
public string? MapCommunicationTypeToStringUsingExtensions(CommunicationTypeDynamic communicationType)
{
return communicationType.MapToString();
}
public CommunicationTypeDynamic? MapStringToCommunicationTypeUsingExtensions(string communicationType)
{
return communicationType.MapToEnumerationDynamic<CommunicationTypeDynamic>();
}
public string MapCommunicationTypeToStringUsingMapper(CommunicationTypeDynamic communicationType)
{
return StringEnumerationDynamicMapper<CommunicationTypeDynamic>.MapToString(communicationType);
}
public CommunicationTypeDynamic MapStringToCommunicationTypeUsingMapper(string communicationType)
{
return StringEnumerationDynamicMapper<CommunicationTypeDynamic>.MapToEnumerationDynamic(communicationType);
}
To map between different types of Enumeration, you can follow this example:
public OtherCommunicationType? MapToOtherTypeOfEnumeration(CommunicationType communicationType)
{
return OtherCommunicationType.GetFromValueOrDefault(communicationType.Value);
}
public OtherCommunicationType? MapToOtherTypeOfEnumerationUsingExtensions(CommunicationType communicationType)
{
// Usage: ...MapToEnumeration<the source type, the destination type>();
return communicationType.MapToEnumeration<CommunicationType, OtherCommunicationType>();
}
public OtherCommunicationType MapToOtherTypeOfEnumerationTypeUsingMapper(CommunicationType communicationType)
{
// Usage: EnumerationMapper<the source type, the destination type>.MapToEnumeration(...);
return EnumerationMapper<CommunicationType, OtherCommunicationType>.MapToEnumeration(communicationType);
}
And finally, to map between different types of Enumeration where the destination is an EnumerationDynamic, you can follow this example:
public OtherCommunicationTypeDynamic? MapToOtherTypeOfEnumeration(CommunicationType communicationType)
{
return OtherCommunicationTypeDynamic.GetFromValueOrNew(communicationType.Value);
}
public OtherCommunicationTypeDynamic? MapToOtherTypeOfEnumerationUsingExtensions(
CommunicationType communicationType)
{
// Usage: ...MapToEnumerationDynamic<the source type, the destination type>();
return communicationType.MapToEnumerationDynamic<CommunicationType, OtherCommunicationTypeDynamic>();
}
public OtherCommunicationTypeDynamic MapToOtherTypeOfEnumerationTypeUsingMapper(CommunicationType communicationType)
{
// Usage: EnumerationDynamicMapper<the source type, the destination type>.MapToEnumerationDynamic(...);
return EnumerationDynamicMapper<CommunicationType, OtherCommunicationTypeDynamic>.MapToEnumerationDynamic(
communicationType);
}
Using Mapperly
The Mapperly is a source generator for generating object mappings. To map objects that have properties of type Enumeration or EnumerationDynamic with Mapperly, you need to implement the mapping in the object mapper.
The NuGet package PMart.Enumeration.Mappers provides a set of mappers that can be used in Mapperly mappers, without the need to implement the mapping manually.
In this example, we have a source object that is mapped to a destination object, which requires mapping from Enumeration to string (from CommunicationType to string) and between different types of Enumeration (from CommunicationType to OtherCommunicationType):
public class SourceObject
{
public CommunicationType CommunicationType { get; set; } = null!;
public CommunicationType OtherCommunicationType { get; set; } = null!;
}
public class DestinationObject
{
public string CommunicationType { get; set; } = null!;
public OtherCommunicationType OtherCommunicationType { get; set; } = null!;
}
For this example, we need to create a Mapperly mapper, and we can use the mappers as external mappings, using the attribute [UseStaticMapper]:
// ...
using Riok.Mapperly.Abstractions;
namespace Enumeration.Mappers.Sample.Samples.Mapperly.Mappers;
[Mapper]
[UseStaticMapper(typeof(StringEnumerationMapper<CommunicationType>))]
[UseStaticMapper(typeof(EnumerationMapper<CommunicationType, OtherCommunicationType>))]
internal partial class SampleMapper
{
public partial DestinationObject SourceToDestination(SourceObject sourceModel);
}
Creating a new Enumeration class is a little bit verbose. For instance, you can't forget to extend Enumeration<T> and to create the private constructor (else, it wouldn't compile anyway).
Therefore, the package PMart.Enumeration.Generator was added to help on that. It is an incremental generator.
Generator Installation
Add the package to your project:
dotnet add package PMart.Enumeration.Generator
You need to keep the package PMart.Enumeration installed.
To any project referring that project don't get a reference to the PMart.Enumeration.Generator, you can add PrivateAssets="all" to the package reference.
And you can also add ExcludeAssets="runtime", to avoid the PMart.Enumeration.Generator.dll file being copied to your build output (it is not required at runtime, it is a generator, so it works in compile time only):
To create a new Enumeration with the generator, it is easy:
Create a partial class, for the Enumeration class.
Add the EnumerationAttribute (namespace PMart.Enumeration.Generator.Attributes) on the class.
Add fields of type private static readonly string named with the prefix ValueFor (this prefix is one of the ways of doing it, as you can check next), that hold the values that will be used to create the enumeration members (check the bellow examples).
The non-fields or fields that are not private static readonly string are ignored.
For example, without the generator, the communication type enumeration was like this:
using PMart.Enumeration;
namespace Enumeration.Sample.Enumerations;
/// <summary>
/// The communication type enumeration.
/// </summary>
public class CommunicationType : Enumeration<CommunicationType>
{
public static readonly CommunicationType Email = new("Email");
public static readonly CommunicationType Sms = new("SMS");
public static readonly CommunicationType PushNotification = new("PushNotification");
private CommunicationType(string value) : base(value)
{
}
}
Using the generator and the prefix ValueFor (this prefix is one of the ways of doing it, as you can check next), it is just like this:
using PMart.Enumeration.Generator.Attributes;
namespace Enumeration.Generator.Sample.Enumerations;
/// <summary>
/// The communication type enumeration.
/// </summary>
[Enumeration]
public partial class CommunicationType
{
private static readonly string ValueForEmail = "Email";
private static readonly string ValueForSms = "SMS";
private static readonly string ValueForPushNotification = "PushNotification";
}
And the generated code will be something like this:
// <auto-generated />
namespace Enumeration.Generator.Sample.Enumerations
{
public partial class CommunicationType : Enumeration<CommunicationType>
{
public static readonly CommunicationType Email = new CommunicationType(ValueForEmail!);
public static readonly CommunicationType Sms = new CommunicationType(ValueForSms!);
public static readonly CommunicationType PushNotification = new CommunicationType(ValueForPushNotification!);
private CommunicationType(string value) : base(value)
{
}
}
}
If you don't worry about instantiating the enumeration members and your only concern is about the inheritance from Enumeration<T> and constructors, you can use the generator to build just that parts:
[Enumeration]
public partial class CommunicationType
{
public static readonly CommunicationType Email = new("Email");
public static readonly CommunicationType Sms = new("SMS");
public static readonly CommunicationType PushNotification = new("PushNotification");
}
If you don't like the use of the prefix ValueFor to define the member names, you can use the EnumerationMemberAttribute to define the name of the enumeration member
(but remember, it is not possible two fields have the same name, it will return a compilation error if you try to do that):
If, for some reason, you already have a field private static readonly string named ValueFor..., but you don't want it to be used to generate a new enumeration member, use the EnumerationIgnoreAttribute:
// <auto-generated />
namespace Enumeration.Generator.Sample.Enumerations
{
public partial class CommunicationTypeDynamic : EnumerationDynamic<CommunicationTypeDynamic>
{
public static readonly CommunicationTypeDynamic Email = new CommunicationTypeDynamic(ValueForEmail!);
public static readonly CommunicationTypeDynamic Sms = new CommunicationTypeDynamic(ValueForSms!);
public static readonly CommunicationTypeDynamic PushNotification = new CommunicationTypeDynamic(ValueForPushNotification!);
public CommunicationTypeDynamic()
{
}
private CommunicationTypeDynamic(string value) : base(value)
{
}
}
}
Generator Diagnostics
The generator tries to report errors when the user does common mistakes, namely about naming the enumeration members with names already in use.
In some cases, there are no compilation errors on the user code. Without the diagnostics from the generator, the user would not know why the generator doesn't work.
For instance, assigning the same name for the enumeration member and for the field, the Enumeration class will not be generated and an error is reported:
[Enumeration]
public partial class CommunicationType
{
[EnumerationMember("Email")]
private static readonly string Email = "Email";
^^^^^ // Error ENUM0002: The name 'Email' of the Enumeration member is the same as the field name
}
Or, defining an invalid name for the enumeration member:
[Enumeration]
public partial class CommunicationType
{
// 123 is not a valid name for a class member in C#
[EnumerationMember("123")]
private static readonly string Email = "Email";
^^^^^ // Error ENUM0001: Invalid name for the Enumeration member in the EnumerationMemberAttribute
}
There are other diagnostics reported for different cases. All are of type Error with an ID like ENUMXXXX and with a descriptive message.
Generator Limitations
The .NET versions restrictions are:
.NET SDK: >= 8.0.100
MSBuild/Visual Studio: >= 17.8.
It does not work for abstract classes. In the example provided in Enumeration with behavior, we use an abstract class and subclasses. When using the generator, you can do the same without being abstract, check this sample.
It does not support nested classes (the usage of the EnumerationAttribute in a nested class does not have effect). But it supports nested namespaces.
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.
