PodNet.EnumValues 1.0.2

PodNet.EnumValues

A simple and powerful C# code generator that lets you define string values for your enums to implement 🔥🔥🔥 lookups. Greatly inspired by Andrew Lock's NetEscapades.EnumGenerators.

Lookups 👆 for Your Enums!

Did you ever need to get down to the nitty-gritty of trying to extract a DisplayAttribute's Name property for your enum values using reflection? It feels quite weird to reference System.ComponentModel objects in modern code, doesn't it? No more! 🛑 With PodNet.EnumValues you can simply create your enums as usual, and decorate the type with the provided [Values<T>], the enum members with [Value] (or your own custom descendant of it), and you'll get magic extension methods that implement the lookup logic.

• 🚀 Simple.
• 🆓 Free.
• ⚙️ Configurable.
• 🔥 Fast.
• ✨ Awesome.

Support and Features

• Supports your C# 11+ codebase (generic attribute support required)
• .NET Standard 2.0, .NET Core 2.0+, .NET Framework 4.6.1+, .NET 5+ etc.
• Any IDE: Visual Studio, Rider or VS Code
  • ...or no IDE, because it works from the command line using dotnet CLI
• This is an efficient incremental Roslyn source generator
• Supports trimming for small file sizes
• Highly configurable code generation
• Immediate feedback on your generated methods with helpful auto-generated IntelliSense comments
• Supports enums with ⛳ [Flags] ⛳
• Great for simple (or complex) DIY localization scenarios, UI lookups for icons, colors, resources, cross-references, alternative keying, and lots more!

Usage

1. Install the NuGet package to the project you want to use it in.

2. Define your enums like you would normally.

   public enum Sentiment
   {
       Happy,
       Neutral,
       Sad
   }
   

3. Add [Values<ValueAttribute>] to the enum type and decorate the enum values with [Value]:

   [Values<ValueAttribute>]
   public enum Sentiment
   {
       [Value("Green")]  Happy,
       [Value("Yellow")] Neutral,
       [Value("Red")]    Sad
   }
   

4. As the magic happens in the background as you type, an extension method will get generated — by default, in the same namespace as the enum type, so you don't need to add any additional usings —, which you can simply call using enum.GetValue(): <br> <br> There is interactive documentation generated for the methods as well. Parametrization of [Values] and changing the enum type's shape also changes the generated documentation accordingly (as well as the generated code, obviously).

5. You also get an analyzer and code fix if you miss a value: <br> <br> You can also configure this warning (or any other generated warnings) to appear as an error, or silence them individually or globally (although the latter is not recommended).

   [!NOTE] Unfortunately, it's not currently possible to offer a "rename" or "replace" functionality when generating code for string literal values, so you'll have to inspect and overwrite the generated name yourself (which defaults to the name of the enum member).

[!IMPORTANT] Sometimes (mostly when doing file operations like renaming/moving files or directories, but rarely even when only editing the file contents), Visual Studio tends to not run the generator when typing, even though it should. The generator will run when executing Build or Rebuild in this case (or when it feels it's got enough time to in the background). This means you might not see the generated code, types, methods and reported diagnostics like warnings until you eventually build the project.

You can also try restarting Visual Studio or unloading and then reloading the project.

VS Code seems to have this issue more rarely than fat Visual Studio does.

[!IMPORTANT] If you rename, move, delete or create some files/folders in Visual Studio, always check if VS did some unintended modifications to the *.csproj file, like modifying some of your <AdditionalFiles> ItemGroup elements.

You can also inspect (but not modify) the generated code by navigating to {Project}/Dependencies/Analyzers/PodNet.EnumValues in Visual Studio: <br> <br>

For reference and your viewing pleasure, we'll supply the code here as well (implementation details might change across package versions):

// <auto-generated />
#nullable enable

using PodNet.EnumValues;

namespace App.Users;
public static partial class SentimentValueExtensions
{
   /// <summary>
   /// Gets the associated <see cref="ValueAttribute"/> value for the <see cref="Sentiment"/> as follows:
   /// <code>
   /// [Unknown] = 0 => 💥 MissingEnumValueException 💥
   ///   [Happy] = 1 => "Green"
   /// [Neutral] = 2 => "Yellow"
   ///     [Sad] = 3 => "Red"
   ///
   ///       [(int)] => (int).ToString()
   /// </code>
   /// </summary>
   /// <remarks>Uses <see cref="UndefinedValueHandling.RawValueToString"/> for undefined values and <see cref="MissingValueHandling.ThrowMissingValueException"/> for missing values.</remarks>
   /// <param name="value">The <see cref="Sentiment"/> value.</param>
   /// <returns>A constant, deterministic string value representing the given <paramref name="value"/>.</returns>
   /// <exception cref="MissingEnumValueException">Thrown when the provided <paramref name="value"/> is declared as a named enum member but has no corresponding marker attribute of type <see cref="ValueAttribute"/> assigned to it.</exception>
   public static string GetValue(this Sentiment value)
       => value switch
       {
           Sentiment.Unknown => throw new MissingEnumValueException(typeof(Sentiment), value),
           Sentiment.Happy => "Green",
           Sentiment.Neutral => "Yellow",
           Sentiment.Sad => "Red",
           _ => ((int)value).ToString()
       };
}
#nullable restore

[!NOTE] The generated code now also accounts for the Unknown value throwing a MissingValueException, and this is also reflected in the generated documentation. This is the case when you miss annotating a value with is corresponding ValueAttribute (or descendant, see below), and don't configure the ValuesAttribute further (see below as well).

Advanced Examples

You can see that the generator's basic functions are as easy as pie to use.

However, there are some advanced scenarios as well.

Supplying Your Own ValueAttribute to Customize the Extension Name

You can simply derive from ValueAttribute similarly to:

public class ColorAttribute(string value) : ValueAttribute(value);

[!IMPORTANT] It's a requirement for your custom descendant to have its first constructor argument be the string value (but it can also be a referenced constant, not just inline). No other requirements, so you can supply more arguments if it suits your needs.

[!NOTE] If you're on C# 11.0, single declarations using primary constructors and bodyless types are unavailable, so you have to declare the attribute like so:

public class ColorAttribute : ValueAttribute
{
    public ColorAttribute(string value) : base(value) { }
}

[!NOTE] C# is awesome.

Then, apply your own derived ValueAttribute as the type parameter to [Values<T>]:

[Values<ColorAttribute>] // 👈 "ColorAttribute" instead of "ValueAttribute"
public enum Sentiment
{
    [Color("Green")]  Happy,   // 👈 \
    [Color("Yellow")] Neutral, // 👈  | [Color] instead of [Value]
    [Color("Red")]    Sad      // 👈 /
}

public static void PrintSentiment(Sentiment sentiment)
    => Console.WriteLine(sentiment.GetColor()); // 🙌 "GetColor()" instead of "GetValue()"

Define multiple lookups

You can simply provide multiple attributes (and configure each separately) to generate multiple lookups for a single enum type.

public class SpanishAttribute(string value) : ValueAttribute(value);
public class FrenchAttribute(string value) : ValueAttribute(value);

// Supply both 👇 "SpanishAttribute" and 👇 "FrenchAttribute" to the type
[Values<SpanishAttribute>, Values<FrenchAttribute>]

/*
  You could use multiple attribute lists as well, naturally:
  [Values<SpanishAttribute>]
  [Values<FrenchAttribute>]
  Also note that you can configure all instances differently
*/
public enum Greeting
{
    // 👇 Supply both translations 👇 to each value
    [Spanish("Hola"),          French("Salut")]   Hi,
    [Spanish("Buenos días"),   French("Bonjour")] GoodMorning,
    [Spanish("Buenas noches"), French("Bonsoir")] GoodEvening
}

Console.WriteLine($"| English (raw name) | Spanish | French | {Environment.NewLine} | --- | --- | --- |");
foreach (var greeting in Greeting.GetValues<Greeting>())
{
    Console.WriteLine($"| {greeting} | {greeting.GetSpanish()} | {greeting.GetFrench()}");
}

The above renders the following markdown table:

English (raw name)	Spanish	French
Hi	Hola	Salut
GoodMorning	Buenos días	Bonjour
GoodEvening	Buenas noches	Bonsoir

Parameterizing [Values]

Using the previous method, you can simply customize the name of the extension method generated, and clarify the intent of the lookup by configuring its generated method name. However, you can also supply any other name for the method, and have other options as well. You have to configure ⚙️ the [Values] to do so.

The [Values<T>] you can apply to enum types works out of the box as is with sensible defaults. You can override them if you wish as described in this section. The descriptions below are also available via the in-IDE IntelliSense.

<details>

<summary><code>Accessibility</code> values</summary>

Describes the possible accessibility level of the type.

Values are the same as defined in the type Microsoft.CodeAnalysis.Accessibility (only the C# aliases). The only allowed values for an extension method are internal and public, as they need to be static, so defining inheritance behavior is not possible.

</details>

<details>

<summary><code>UndefinedValueHandling</code> values</summary>

Defines what should happen when an undefined enum value is encountered (often resulting from unsanitized/invalid user input or an invalid cast from a raw value). Not to be confused with MissingValueHandling, which handles values that are defined, but have no associated ValueAttribute.

</details>

<details>

<summary><code>MissingValueHandling</code> values</summary>

Defines the behavior that is executed when a defined enum value has no associated ValueAttribute defined to it.

</details>

Additional arguments are provided to configure the [Flags] behavior.

You can also apply multiple [Values<T>] instances to the same enum type, but the configurations have to be different (a sensible idea is to have different type parameters supplied).

Let's see an example.

namespace App.Comments;

[Values<ColorAttribute>]                    // 👈 All defaults
[Values<EmojiAttribute>(                    // 👈 All parameters are optional
    Accessibility = Accessibility.Internal, // 👈 Defaults to the enum's visibility, but can be public or internal
    Namespace = "App.Helpers",              // 👈 Defaults to the enum's namespace (would be "App.Comments" here), overriding this implies you'll need to import the namespace yourself at the usage sites
    ClassName = "EmojiExtensions",          // 👈 The default is "{EnumName}ValueExtensions"
    MethodName = "GetEmojiForSentiment",    // 👈 The default is "Get{TValue}", in this case would be "GetEmoji"
    MissingValueHandling = MissingValueHandling.EmptyString, // 👈 Default is to throw when you forget to add [Emoji] to a member (also warns if a value is missing when this is set to throw)
    UndefinedValueHandling = UndefinedValueHandling.ThrowMissingValueException // 👈 Default is "RawValueToString", which would return the raw int value if it wasn't Happy (0), Neutral (1) or Sad (2)
)]
public enum Sentiment
{
    [Emoji("😄"), Color("Green")]  Happy,
    [Emoji("🙄"), Color("Yellow")] Neutral,
    [Emoji("😔"), Color("Red")]    Sad
}

public static void PrintSentiment(Sentiment sentiment)
    => Console.WriteLine($"{sentiment.GetColor()} - {sentiment.GetEmojiForSentiment()}");

PrintSentiment(Sentiment.Happy);            // "Green - 😄"

⛳ Flags ⛳ support

And finally, you can also use this with enums that are used as binary (bit) flags.

You'll get a warning if you miss a binary flag value (a power of two or the 0 value).

You can supply any non-flag value an override. You can do this for performance (if you have some common combinations), custom overrides, or special negative values (which throw an ArgumentOutOfRangeException otherwise).

[Flags] // 👈 Either add the [Flags]...
[Values<ValueAttribute>(
    IsFlags = true, // ...or set IsFlags = true
    FlagsSeparator = "" // The default is " | ", which represents a binary OR operation (the default in .NET's default Enum.ToString() as well).
)]
public enum Permissions
{
    [Value("!")]  Invalid = -1,                   // 👈 You *can* supply any non-flag values, even negative values, as normal. Undefined negative values will throw an ArgumentOutOfRangeException, however.
    [Value("-")]  None = 0,
    [Value("R")]  Read = 1,
    [Value("W")]  Write = 2,
                  ReadWrite = Read | Write,       // 👈 You don't need to supply the value if you use shorthands...
    [Value("X")]  Execute = 4,
    [Value("RX")] ReadExecute = Read | Execute,   // 👈 ...but you CAN, if you want. The provided value is only used if you don't supply your own separator.
                  WriteExecute = Write | Execute, // 👈 You don't have to define all possible flag combinations, but it's shown here for completeness.
    [Value("A")]  All = Read | Write | Execute    // 👈 You can override the output with any custom values you like.
}

public static class PermissionPrinter
{
    public static void PrintFlags(Permissions permissions)
    {
        Console.WriteLine(permissions.GetValue());
        Console.WriteLine(permissions.GetValue("|")); // You can individually override the default separator (which would be " - ", but we've already overridden it in the [Values<>] configuration for Permissions
    }

    public static void PrintSome()
    {
        PrintFlags(Permissions.ReadWrite); // 👈 Same as `(Permissions)3` or `Permissions.Read | Permissions.Write`
        // 👆 prints:
        // RW         // 👈 Iterates through all binary flags: 1 (Read = R) and 2 (Write = W), and concatenates them using the configured empty ("") FlagsSeparator
        // R|W        // 👈 GetValue("|") iterates and joins the values with the provided separator instead

        PrintFlags(Permissions.Read | Permissions.Write | Permissions.Execute); // Same as "(Permissions)7" or "Permissions.All"
        // 👆 prints:
        // A          // 👈 Get the ValueAttribute's value directly, if it is defined.
        // R|W|X      // 👈 GetValue("|") iterates and joins the values with the provided separator, and ignores the [Value("A")] value.

        PrintFlags((Permissions)15); // 👈 This contains Read (1) | Write (2) | Execute (4) and an undefined 8
        // 👆 prints:
        // RWX8       // 👈 If you want to disallow this behavior, you can set UndefinedValueHandling to ThrowMissingValueException or EmptyString.
        // R|W|X|8
    }
}

[!TIP] Because the logic for enumerating the flag values is generated, you can go to the implementation (<kbd>F12</kbd>) and take a look yourself!

Warnings and Code Fixes

Known Limitations

This project aims to make it clean to define lookups for enum values. There are some known limitations, however, that are good to know about.

• No support for System.ComponentModel.DisplayNameAttribute, System.ComponentModel.DataAnnotations.DisplayAttribute, or similar built-in or satellite attributes. This is intentional. The current implementation would blow up in size and complexity if we were to support multiple attribute types with varying semantics. However, if you think there should be some kind of additional support for this, we're all ears [Discussions].
  • There are other alternatives that target similar scenarios, including the awesome NetEscapades.EnumGenerators by the brilliant Andrew Lock. You should take a look at that package anyways!
• Enum types nested in generic class structures (for example, MyNamespace.MyClass<T>.MyEnum) are not supported (and produce the warning PN1602: Enum types declared in generic types are not supported). It is possible to support this scenario, so let us know if you really want this implemented. Even better, send a pull request if you have it in you! 😃 The thing about this is that the generic type constraints have to be copied to the extension method declaration, which is quite cumbersome and finicky to implement. If you encounter this issue, it's recommended to move the enum type out of the generic structure, if possible. You can create a holder type with no type arguments, or just move it to the containing namespace or up the class hiererachy until no types are left.
• If you reuse generated partial classes (override the Namespace and/or ClassName pairs to match in multiple declarations) for whatever reason, you have to match the provided Accessibility values, as it is not possible to locate all partial declarations inside the generator. You'll get a compiler error CS0262: Partial declarations of '{YourExtensionClass}' have conflicting accessibility modifiers if this is the case.
• The value can only be a string value at the moment. Integral values are inherently supported by the enum types themselves (although not multiple values), and I saw no other viable scenarios that suggest other values (as Attributes, these are constrained to a few constant types anyways) should be reasonable. Although it would be possible to supply another variant of the generator that generates the values using inversion of control (you could supply your custom class that takes the given enum type as a type parameter), it's not immediately obvious what purpose this would serve. If you want a similar feature, feel free to jump into the [Discussions].

Troubleshooting

My project cannot see the [ValuesAttribute] type, what's up?

Check if your PackageReference is correct in the csproj file. If you set the PackageReference manually to exclude (or don't include) the compile asset, the project you want to use the generator in won't see the assembly containing the attributes and enumerations you need to use the generator. It just won't fire up, because it's looking for the attribute on enum types.

The following are CORRECT references after installation:

<PackageReference Include="PodNet.EnumValues" Version="1.0.1" 
    PrivateAssets="all" />


<PackageReference Include="PodNet.EnumValues" Version="1.0.1" />

[!NOTE] In version 1.0.0, the NuGet package was set up as a DevelopmentDependency (as it should for analyzer packages), but this resulted in the compile-time assemblies not being correctly referenced. If you managed to somehow install 1.0.0 of the package, please upgrade to 1.0.1 to see the required attributes.

Contributing and Support

This project is intended to be widely usable, but no warranties are provided. If you want to contact us, feel free to do so in the org's [Discussions] or the project's topic, at our website at podnet.hu, or find us anywhere from LinkedIn to Meetup, YouTube or X.

Any kinds of contributions from issues to PRs and open discussions are welcome!

Don't forget to give us a ⭐ if you like this repo (it's free to give kudos!) or share it on socials!

Sponsorship

If you're using our work or like what you see, consider supporting us. Every bit counts. 🙏 See here for more info.