[API Proposal]: Add InvalidEnumArgumentException.ThrowIfNotDefined

[RichardRobertson]

Background and motivation

Checking enum arguments for validity requires some boilerplate and would benefit from a convenience method similar to ArgumentNullException.ThrowIfNull.

API Proposal

using System;
using System.Runtime.CompilerServices;

namespace System.ComponentModel;

public class InvalidEnumArgumentException : ArgumentException
{
    // existing class body

    public static void ThrowIfNotDefined<TEnum>(TEnum argument, [CallerArgumentExpression(nameof(argument))] string? paramName = default) where TEnum : struct
    {
        if (!Enum.IsDefined(argument))
        {
            throw new InvalidEnumArgumentException(paramName, (int)argument, typeof(TEnum));
        }
    }
}

API Usage

public enum MyEnum
{
    Value1 = 0,
    Value2 = 1
}

public void MyMethod(MyEnum myEnum)
{
    InvalidEnumArgumentException.ThrowIfNotDefined(myEnum);
    // do something with myEnum
}

public void Main()
{
    MyMethod(MyEnum.Value1); // ok
    MyMethod((MyEnum)2); // InvalidEnumArgumentException
}

Alternative Designs

Current practice is to call Enum.IsDefined, and if necessary, throw a new exception. This already works but requires boilerplate code that could be eliminated.

Risks

This new method proposed should not affect any existing API.

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

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

Checking enum arguments for validity requires some boilerplate and would benefit from a convenience method similar to ArgumentNullException.ThrowIfNull.

API Proposal

using System;
using System.Runtime.CompilerServices;

namespace System.ComponentModel;

public class InvalidEnumArgumentException : ArgumentException
{
    // existing class body

    public static void ThrowIfNotDefined<TEnum>(TEnum argument, [CallerArgumentExpression(nameof(argument))] string? paramName = default) where TEnum : struct
    {
        if (!Enum.IsDefined(argument))
        {
            throw new InvalidEnumArgumentException(paramName, (int)argument, typeof(TEnum));
        }
    }
}

API Usage

public enum MyEnum
{
    Value1 = 0,
    Value2 = 1
}

public void MyMethod(MyEnum myEnum)
{
    InvalidEnumArgumentException.ThrowIfNotDefined(myEnum);
    // do something with myEnum
}

public void Main()
{
    MyMethod(MyEnum.Value1); // ok
    MyMethod((MyEnum)2); // InvalidEnumArgumentException
}

Alternative Designs

Current practice is to call Enum.IsDefined, and if necessary, throw a new exception. This already works but requires boilerplate code that could be eliminated.

Risks

This new method proposed should not affect any existing API.

Author:	RichardRobertson
Assignees:	-
Labels:	api-suggestion, area-System.Runtime, untriaged
Milestone:	-

[stephentoub]

Thanks. We've discussed variants of this in the past, but have avoided adding them for two reasons.

First, performance. In many situations, the check you can often do manually is typically faster than what Enum.IsDefined will be able to do, e.g.

using BenchmarkDotNet.Attributes;
using BenchmarkDotNet.Running;
using System;

public partial class Program
{
    static void Main(string[] args) => BenchmarkSwitcher.FromAssembly(typeof(Program).Assembly).Run(args);

    [Params(DayOfWeek.Wednesday)]
    public DayOfWeek _dow { get; set; }

    [Benchmark]
    public bool IsDefined() => Enum.IsDefined(_dow);

    [Benchmark]
    public bool SimpleComparison() => (uint)_dow <= (uint)DayOfWeek.Saturday;
}

Method	Runtime	_dow	Mean
IsDefined	.NET 7.0	Wednesday	13.0305 ns
IsDefined	.NET 8.0	Wednesday	2.0572 ns
SimpleComparison	.NET 7.0	Wednesday	0.0025 ns
SimpleComparison	.NET 8.0	Wednesday	0.0001 ns

Second, reliability/maintainability. Such an API can make sense if the enum being checked is defined in the same assembly as the API doing the validation. But if the enum is defined in a separate assembly, you really want the method doing the validation to validate with a known set of values rather than what the enum happens to define in whatever version of it gets loaded. For example, you write your API against enum Colors { Red, Blue }, and you only implement support for Red and Blue. Then the enum gets Yellow added in a new version of it, and someone passes Yellow into your method: the validation won't throw for the Yellow input even though your implementation only knows how to handle Red and Blue. This is why the .NET design guidelines warn against using Enum.IsDefined in such cases.

[RichardRobertson]

I had never benchmarked IsDefined but wow that's a noticeable difference. I will have to reconsider using that method.

You make a great point about new members on the enum though. I guess that makes my proposal unnecessary because I just didn't think about the issue well enough.

I appreciate your time and input.