Awesome
Enum Utilities
A source generator for C# that uses Roslyn to create extensions and parsers for enumerations
🏃 Quickstart | 📗 Guide | 📦 NuGet
<hr />A source generator for C# that uses Roslyn to create extensions and parsers for enumerations, allowing to get a value associated to enum member or parse back from attribute value to enum member. All code generated at compile time thus avoid using reflection or boilerplate code.
Compatibility
Raiqub.Generators.EnumUtilities runs with Roslyn compiler so does not introduce a new dependency to your project besides a library containing the EnumGenerator attribute.
It requires at least the .NET 6 SDK to run, but you can target earlier frameworks.
Quickstart
Add the package to your application using
dotnet add package Raiqub.Generators.EnumUtilities
Adding the package will automatically add a marker attribute, [EnumGenerator]
, to your project.
To use the generator, add the [EnumGenerator]
attribute to an enum. For example:
[EnumGenerator]
public enum Categories
{
Electronics,
Food,
Automotive,
Arts,
BeautyCare,
Fashion
}
This will generate 3 classes with the following methods:
- CategoriesExtensions
- ToStringFast(this Categories)
- GetStringCount(this Categories)
- IsDefined(this Categories)
- InterlockedAdd(this ref Categories, int)
- InterlockedDecrement(this ref Categories)
- InterlockedIncrement(this ref Categories)
- InterlockedCompareExchange(this ref Categories, Categories, Categories)
- InterlockedExchange(this ref Categories, Categories)
- CategoriesFactory
- Parse(string, bool = false)
- Parse(ReadOnlySpan<char>, bool = false)
- ParseOrNull(string?, bool = false)
- TryParse(string?, bool, out Categories)
- TryParse(string?, out Categories)
- TryParse(string?, bool = false)
- TryParse(ReadOnlySpan<char>, bool, out Categories)
- TryParse(ReadOnlySpan<char>, out Categories)
- TryParse(ReadOnlySpan<char>, bool = false)
- GetValues()
- GetNames()
- CategoriesValidation
- IsDefined(Categories)
- IsDefined(string?, StringComparison)
- IsDefinedIgnoreCase(string?)
- IsDefined(string?)
Bit flags enums are supported too:
[Flags]
[EnumGenerator]
public enum Colours
{
Red = 1,
Blue = 2,
Green = 4,
}
Then 3 classes will be generated with the following methods:
- ColoursExtensions
- ToStringFast(this Colours)
- HasFlagFast(this Colours, Colours)
- GetStringCount(this Colours)
- IsDefined(this Colours)
- InterlockedAnd(this ref Colours, Colours)
- InterlockedOr(this ref Colours, Colours)
- InterlockedCompareExchange(this ref Colours, Colours, Colours)
- InterlockedExchange(this ref Colours, Colours)
- ColoursFactory
- Parse(string, bool = false)
- Parse(ReadOnlySpan<char>, bool = false)
- ParseOrNull(string?, bool = false)
- TryParse(string?, bool, out Categories)
- TryParse(string?, out Categories)
- TryParse(string?, bool = false)
- TryParse(ReadOnlySpan<char>, bool, out Categories)
- TryParse(ReadOnlySpan<char>, out Categories)
- TryParse(ReadOnlySpan<char>, bool = false)
- GetValues()
- GetNames()
- ColoursValidation
- IsDefined(Colours)
- IsDefined(string?, StringComparison)
- IsDefinedIgnoreCase(string?)
- IsDefined(string?)
All generated code are properly nullable annotated and removed from code coverage.
Guide
The following attributes are supported:
EnumMemberAttribute
Example:
[EnumGenerator]
public enum PaymentMethod
{
[EnumMember(Value = "Credit card")]
Credit,
[EnumMember(Value = "Debit card")]
Debit,
Cash,
Cheque
}
This will generate the following methods:
- PaymentMethodExtensions
- ToEnumMemberValue(this PaymentMethod)
- PaymentMethodFactory
- TryParseFromEnumMemberValue(string?, StringComparison, out PaymentMethod)
- TryParseFromEnumMemberValue(string?, out PaymentMethod)
- TryParseFromEnumMemberValue(string?, StringComparison)
- TryParseFromEnumMemberValue(string?)
DescriptionAttribute
Example:
[EnumGenerator]
public enum PaymentMethod
{
Credit,
Debit,
[Description("The payment by using physical cash")]
Cash,
Cheque
}
This will generate the following methods:
- PaymentMethodExtensions
- GetDescription(this PaymentMethod)
- PaymentMethodFactory
- TryCreateFromDescription(string?, StringComparison, out PaymentMethod)
- TryCreateFromDescription(string?, out PaymentMethod)
- TryCreateFromDescription(string?, StringComparison)
- TryCreateFromDescription(string?)
DisplayAttribute
Example:
[EnumGenerator]
public enum WeekDays
{
[Display(
Name = nameof(Strings.MondayFull),
ShortName = nameof(Strings.MondayShort),
Description = nameof(Strings.MondayDescription),
ResourceType = typeof(Strings))]
Monday,
[Display(ShortName = "Tue")]
Tuesday,
[Display]
Wednesday,
[Display(Name = "Thursday")]
Thursday,
[Display(Name = "Friday", ShortName = "Fri")]
Friday,
[Display(ShortName = "Sat", Description = "Almost the last day of the week")]
Saturday,
[Display(Description = "The last day of the week")]
Sunday
}
Note that if ResourceType
is provided the generated code will correctly get the value from resource.
This will generate the following methods:
- WeekDaysExtensions
- GetDisplayShortName(this WeekDays)
- GetDisplayName(this WeekDays)
- GetDescription(this WeekDays)
- WeekDaysFactory
- TryCreateFromDisplayShortName(string?, StringComparison, out WeekDays)
- TryCreateFromDisplayShortName(string?, out WeekDays)
- TryCreateFromDisplayShortName(string?, StringComparison)
- TryCreateFromDisplayShortName(string?)
- TryCreateFromDisplayName(string?, StringComparison, out WeekDays)
- TryCreateFromDisplayName(string?, out WeekDays)
- TryCreateFromDisplayName(string?, StringComparison)
- TryCreateFromDisplayName(string?)
- TryCreateFromDescription(string?, StringComparison, out WeekDays)
- TryCreateFromDescription(string?, out WeekDays)
- TryCreateFromDescription(string?, StringComparison)
- TryCreateFromDescription(string?)
JSON Serialization
Besides the member name, supports the EnumMemberAttribute and JsonPropertyNameAttribute attributes.
Example:
[JsonConverterGenerator]
[JsonConverter(typeof(SeasonJsonConverter))]
public enum Season
{
[EnumMember(Value = "\ud83c\udf31")]
Spring = 1,
[EnumMember(Value = "\u2600\ufe0f")]
Summer,
[EnumMember(Value = "\ud83c\udf42")]
Autumn,
[EnumMember(Value = "\u26c4")]
Winter
}
This will generate the following JSON converter: SeasonJsonConverter.
Contributing
If something is not working for you or if you think that the source file should change, feel free to create an issue or Pull Request. I will be happy to discuss and potentially integrate your ideas!
License
See the LICENSE file for details.