[API Proposal]: Add InvalidEnumArgumentException.ThrowIfUndefined

[Abrynos]

Background and motivation

In the past years we've received multiple new methods such as ArgumentNullException.ThrowIfNull, ArgumentException.ThrowIfNullOrEmpty, ArgumentOutOfRangeException.ThrowIfNegative and many more, but there is none available on InvalidEnumArgumentException.

API Proposal

namespace System.ComponentModel;

public class InvalidEnumArgumentException  : ArgumentException
{
+    public static void ThrowIfUndefined<T>(T argument, [CallerArgumentExpression("argument")] string? argumentName = null) where T : struct, System.Enum
+    {
+        ArgumentException.ThrowIfNullOrEmpty(argumentName);
+        if (!Enum.IsDefined(argument))
+        {
+            throw new InvalidEnumArgumentException(argumentName, (int)(object)argument, typeof(T));
+        }
+    }
}

API Usage

public enum SomeEnumeration {
    SomeValue,
    SomeOtherValue,
}

public void SomeMethod(string str, SomeEnumeration value) {
    ArgumentException.ThrowIfNullOrEmpty(str);
    InvalidEnumArgumentException.ThrowIfUndefined(value);
}

Alternative Designs

No response

Risks

No response

[stephentoub]

We've had requests for variations on this in the past, and have decided against them.

We don't want developers writing code like:

public void SomeMethod(SomeEnumeration value)
{
    ThrowIfNotDefined(value);
    ...
}

if SomeEnumeration is defined in a different library. In such a case, this method could end up being shipped, then SomeEnumeration gets an additional value in a new version of whatever library it's defined in, and that then changes the behavior of this library. It's why the API design guidelines venture into implementation territory to say not to use Enum.IsDefined as part of argument validation, and instead say the validation should be done based on known values.

Even with perf improvements to IsDefined, it's also still generally faster to do the check explicitly based on knowledge of the enum's possible values, and in many cases, it naturally falls out of the work being done, anyway, e.g. with code like:

switch (value)
{
    case SomeEnumeration.A:
        HandleA();
        break;

    case SomeEnumeration.B:
        HandleB();
        break;

    default:
        throw new ArgumentOutOfRangeException(...);
}

Tagging subscribers to this area: @dotnet/area-system-runtime
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

In the past years we've received multiple new methods such as ArgumentNullException.ThrowIfNull, ArgumentException.ThrowIfNullOrEmpty, ArgumentOutOfRangeException.ThrowIfNegative and many more, but there is none available on InvalidEnumArgumentException.

API Proposal

namespace System.ComponentModel;

public class InvalidEnumArgumentException  : ArgumentException
{
+    public static void ThrowIfUndefined<T>(T argument, [CallerArgumentExpression("argument")] string? argumentName = null) where T : struct, System.Enum
+    {
+        ArgumentException.ThrowIfNullOrEmpty(argumentName);
+        if (!Enum.IsDefined(argument))
+        {
+            throw new InvalidEnumArgumentException(argumentName, (int)(object)argument, typeof(T));
+        }
+    }
}

API Usage

public enum SomeEnumeration {
    SomeValue,
    SomeOtherValue,
}

public void SomeMethod(string str, SomeEnumeration value) {
    ArgumentException.ThrowIfNullOrEmpty(str);
    InvalidEnumArgumentException.ThrowIfUndefined(value);
}

Alternative Designs

No response

Risks

No response

Author:	Abrynos
Assignees:	-
Labels:	api-suggestion, area-System.Runtime, untriaged, needs-area-label
Milestone:	-

[Abrynos]

@stephentoub Thank you for your quick answer. How about some variations of InvalidEnumArgumentException.ThrowIfInvalid<T>(T value, T min, T max)? This way the caller can forward their knowledge of known values to the implementation.

[stephentoub]

@stephentoub Thank you for your quick answer. How about some variations of InvalidEnumArgumentException.ThrowIfInvalid<T>(T value, T min, T max)? This way the caller can forward their knowledge of known values to the implementation.

As part of adding the various throw methods to ArgumentOutOfRangeException, we discussed at length and ultimately dismissed range-based methods, e.g. ThrowIfOutOfBounds, that would effectively be what you're asking for, albeit what your asking for is still more complicated / expensive as the implementation would need to fish out the underlying type of the enum in order to do the comparison. I think this is a case where currently the best answer is to just do it manually.