ArgumentOutOfRangeException - throw helpers for enum argument

[TheBrambleShark]

Hi all,

Just wanted to start discussion on this. Once we figure out what exactly we're wanting here, I can create a proper API suggestion.

Starting with Net7, we have been adding static helper methods to commonly used exception types to handle common scenarios. It is a very common scenario to accept enum arguments, but the existing InvalidEnumArgumentException only works with enums with backing types that fit into int. You can use a long-backed enum, but you cannot provide the actual value without data loss with the conversion to int.

We could create a new exception type for this, but I think ArgumentOutOfRangeException works well for enums.

I think the most common scenario is likely the case where an enum value is not defined. For instance:

enum Animals
{
    None = 0,
    Dog = 1,
    Cat = 2
}

public void LogAnimal(Person person, Animals animal)
{
    string animalType = animal switch
    {
        Animals.None => "no pets!",
        Animals.Dog => "a dog!",
        Animals.Cat => "a cat!",
        _ => // Throw an exception!
    };
    Console.WriteLine($"{person.Name} has {animalType}");
}

For non-flags enums, I think two extensions will be helpful:

• ThrowIfEnumNotDefined<TEnum>(TEnum enum) - Covers the example scenario above.
• ThrowIfEnumDefined<TEnum>(TEnum enum) - Covers the inverse - the only valid choice is one that's not defined.

For flags enums, we will need to figure out how to handle composite values. For non-composite values, we can use the same logic as above. But for composite values, it may be a good idea to have an argument to indicate whether composite values are automatically invalid (if Animals was a flags enum, 3 is not defined, so it's invalid), or if all of the composite values must be enumerated (Dog | Cat or 3 would be valid, but 4 would not be).

Are there any other enum helpers you might find viable for this? Or is it worth looking into creating a new exception type entirely, like EnumArgumentOutOfRangeException?

[huoyaoyuan]

Related to #118053

[jkotas]

This was discussed and rejected number of times, see e.g. #83107, #92071

[TheBrambleShark]

Thanks for finding those.

I think what I may do is create a static exception helper that throws NotImplementedException. This helper won't have any conditional logic in it, it would just handle consistent (and potentially i18nalized) error messages.

Basic English-only version

public static class ThrowHelpers
{
    [DoesNotReturn]
    public static void ThrowEnumArgumentNotImplementedException<TEnum>(TEnum enum)
    where TEnum : struct, Enum
    {
        throw new NotImplementedException($"No handler for {enum} has been defined.");
    }
}

This could also be an ArgumentOutOfRangeException or maybe a custom exception that is defined as a combination of ArgumentException and NotImplementedException. This should resolve issues surrounding performance and cross-assembly enums as all conditional logic should be handled by the caller.