[API Proposal]: ArgumentOutOfRangeException constructor with actualValue and system message

[OwnageIsMagic]

Background and motivation

ArgumentOutOfRangeException have read-only ActualValue property which is settable only from constructor that also requires user provided message.

API Proposal

Unfortunately .ctor(string paramName, object actualValue) is ambiguous if actualValue is string (because of existing .ctor(string paramName, string message)), so I instead suggest new throw helper

namespace System;

public class ArgumentOutOfRangeException
{
    [DoesNotReturn]
    public static void Throw(object/*?*/ actualValue, [CallerArgumentExpression(nameof(actualValue))] string? paramName = null);
}

API Usage

void CheckEven(int i)
{
    if (i % 2 != 0)
        ArgumentOutOfRangeException.Throw(i);
}

Alternative Designs

Add factory method instead, this will allow creation of object without throwing (useful for testing).

Current workaround:

namespace System;

/// <inheritdoc />
public sealed class ArgumentOutOfRangeExceptionEx : ArgumentOutOfRangeException
{
    private static readonly string Arg_ArgumentOutOfRangeException = (string)(typeof(ArgumentOutOfRangeException) // TODO: test on net40
                                                                              .Assembly.GetType("System.SR")?
                                                                              .GetProperty("Arg_ArgumentOutOfRangeException", // net core
                                                                                  BindingFlags.Static | BindingFlags.NonPublic | BindingFlags.Public)
                                                                              ?.GetValue(null, null)
                                                                              ?? typeof(ArgumentOutOfRangeException)
                                                                                 .GetProperty("RangeMessage", // net fx
                                                                                     BindingFlags.Static | BindingFlags.NonPublic)
                                                                                 ?.GetValue(null, null)
                                                                              ?? "Arg_ArgumentOutOfRangeException");

    /// <summary>
    /// Create <see cref="ArgumentOutOfRangeException"/> with default message
    /// AND specifying <see cref="ArgumentOutOfRangeException.ActualValue"/>.
    /// </summary>
    /// <inheritdoc path='/param/[@name="paramName"]'/>
    /// <inheritdoc path='/param/[@name="actualValue"]'/>
    public ArgumentOutOfRangeExceptionEx(string paramName, object? actualValue)
        : base(paramName, actualValue, Arg_ArgumentOutOfRangeException) { }
}

Risks

No response

[stephentoub]

You can always just pass null as the message. The downside of that is the current implementation then doesn't use the ArgumentOutOfRangeException's default message and instead uses Exception's default message. I suggest this doesn't warrant a new constructor or Throw method, and we instead just change this:

        public ArgumentOutOfRangeException(string? paramName, object? actualValue, string? message)
            : base(message, paramName)

to be this:

        public ArgumentOutOfRangeException(string? paramName, object? actualValue, string? message)
            : base(message ?? SR.Arg_ArgumentOutOfRangeException, paramName)

and the same for the other ctor(s) that take a string? message.

[OwnageIsMagic]

@stephentoub

runtime/src/libraries/System.Private.CoreLib/src/System/ArgumentOutOfRangeException.cs

Line 24 in 3e6f2ed

public ArgumentOutOfRangeException()

        // Creates a new ArgumentOutOfRangeException with its message
        // string set to a default message explaining an argument was out of range.
        public ArgumentOutOfRangeException()
            : this(null, null, null) {}

        public ArgumentOutOfRangeException(string? paramName)
            : this(paramName, null, null) {}
 
        public ArgumentOutOfRangeException(string? paramName, string? message)
            : this(paramName, null, message) {}
 
        public ArgumentOutOfRangeException(string? message, Exception? innerException)
            : base(message, innerException)
        {
            HResult = HResults.COR_E_ARGUMENTOUTOFRANGE;
        }
 
        public ArgumentOutOfRangeException(string? paramName, object? actualValue, string? message)
            : base(message ?? SR.Arg_ArgumentOutOfRangeException, paramName)
        {
            _actualValue = actualValue;
            HResult = HResults.COR_E_ARGUMENTOUTOFRANGE;
        }

Create PR?

[stephentoub]

Create PR?

Sure, thanks.

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

ArgumentOutOfRangeException have read-only ActualValue property which is settable only from constructor that also requires user provided message.

API Proposal

Unfortunately .ctor(string paramName, object actualValue) is ambiguous if actualValue is string (because of existing .ctor(string paramName, string message)), so I instead suggest new throw helper

namespace System;

public class ArgumentOutOfRangeException
{
    [DoesNotReturn]
    public static void Throw(object/*?*/ actualValue, [CallerArgumentExpression(nameof(actualValue))] string? paramName = null);
}

API Usage

void CheckEven(int i)
{
    if (i % 2 != 0)
        ArgumentOutOfRangeException.Throw(i);
}

Alternative Designs

Add factory method instead, this will allow creation of object without throwing (useful for testing).

Current workaround:

namespace System;

/// <inheritdoc />
public sealed class ArgumentOutOfRangeExceptionEx : ArgumentOutOfRangeException
{
    private static readonly string Arg_ArgumentOutOfRangeException = (string)(typeof(ArgumentOutOfRangeException) // TODO: test on net40
                                                                              .Assembly.GetType("System.SR")?
                                                                              .GetProperty("Arg_ArgumentOutOfRangeException", // net core
                                                                                  BindingFlags.Static | BindingFlags.NonPublic | BindingFlags.Public)
                                                                              ?.GetValue(null, null)
                                                                              ?? typeof(ArgumentOutOfRangeException)
                                                                                 .GetProperty("RangeMessage", // net fx
                                                                                     BindingFlags.Static | BindingFlags.NonPublic)
                                                                                 ?.GetValue(null, null)
                                                                              ?? "Arg_ArgumentOutOfRangeException");

    /// <summary>
    /// Create <see cref="ArgumentOutOfRangeException"/> with default message
    /// AND specifying <see cref="ArgumentOutOfRangeException.ActualValue"/>.
    /// </summary>
    /// <inheritdoc path='/param/[@name="paramName"]'/>
    /// <inheritdoc path='/param/[@name="actualValue"]'/>
    public ArgumentOutOfRangeExceptionEx(string paramName, object? actualValue)
        : base(paramName, actualValue, Arg_ArgumentOutOfRangeException) { }
}

Risks

No response

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