Proposal: Convenience API for throwing exceptions

[jamesqo]

Background

It's quite verbose to validate arguments because you have to write an if-statement and throw new XXXException for each validation. Even with C# 7's new throw-expressions, you still have to write out the latter part. This makes people write their own helper classes for validating arguments, e.g. here or here. It would be nice if we had such a helper class as part of the framework.

Proposal

namespace System
{
    public static class Verify
    {
        public static void Argument(bool condition, string message, string argumentName);

        public static void InRange(bool condition, string argumentName);
        public static void InRange(string s, int index, int count, string sName, string indexName, string countName);
        public static void InRange<T>(T[] array, int index, int count, string arrayName, string indexName, string countName);

        public static void NotEmpty<T>(IEnumerable<T> source, string sourceName);

        public static void NotNegative(int argument, string argumentName);

        public static void NotNull(bool condition, string argumentName);
        public static void NotNull<T>(T argument, string argumentName) where T : class;

        public static void Positive(int argument, string argumentName);
    }
}

// Sample usage:
T MyGenericMethod<T>(T[] array, int index, int count)
{
    // Note: All of this is equivalent to Verify.InRange(array, index, count, nameof(array), nameof(index), nameof(count)).
    // The arguments are validated manually for demo purposes.
    Verify.NotNull(array, nameof(array));
    Verify.NotNegative(index, nameof(index));
    Verify.NotNegative(count, nameof(count));
    Verify.InRange(array.Length - index >= count, nameof(index));
}

A sample implementation can be found here.

Remarks

• In my experience, it's common to validate things like a signed integer being positive/nonnegative, so those patterns will get their own Positive / NotNegative methods. This will enable us to provide a better error message if such a check fails. These methods throw the same exception type as InRange.

  • Same applies for InRange, NotEmpty

• The class will work nicely with using static:

using static System.Verify;

T MyGenericMethod<T>(T[] array, int index, int count)
{
    NotNull(array, nameof(array));
    NotNegative(index, nameof(index));
    NotNegative(count, nameof(count));
    InRange(array.Length - index >= count, nameof(index));
}

• The extra NotNull overload taking a bool covers the rare cases when people are writing generic code, and the parameter might be null but the compiler can't guarantee that it's a class. e.g. Like here. It also covers the rare times when someone would want to verify a nullable is non-null.
  • I didn't include a NotNull<T>(T?, string) where T : struct nullable overload since if someone thinks a nullable is non-null they would likely 1) not accept a nullable parameter in the first place, or 2) if they're calling some method they know returns a non-null nullable, they're likely to cast the T? to a T or call .Value, which do the validation automatically, instead of bothering to validate themselves.

---

This is a follow-up to https://github.com/dotnet/corefx/issues/12509 after putting some thought into the API.

[jamesqo]

/cc @KrzysztofCwalina; would such an API be a good idea for corefxlab?

[karelz]

BTW: I don't think using corefxlab would bring too much benefit in this case.

[jamesqo]

@karelz Why not?

[karelz]

Let me turn it around: What kind of benefits do you expect from corefxlab?

[KrzysztofCwalina]

There is a need for APIs like that in corfxlab and in the platfrom. For example, System.Slices already duplicates this: https://github.com/dotnet/corefxlab/blob/master/src/System.Slices/System/Runtime/Contract.cs

I never turned the Contract.cs APIs into a package as there are several interesting trade-offs here, and I did not have time to think how to resolve them.

Also, I think this is related to a feature that @justinvp was pushing at some point (and I liked a lot), i.e. the ability to throw various common exceptions conveniently without the need to deal with message resources.

Lastly, I would love to have a set of attributes for identifying exceptions that propagate out of APIs. The attributes would divide errors into usage errors (roughly preconditions) and runtime errors (errors that need to be handled). Usage errors would show in VS tooltips and runtime error attributes would be used by analyzers to detect code that does not handle them properly.

[jamesqo]

Also, I think this is related to a feature that @justinvp was pushing at some point (and I liked a lot), i.e. the ability to throw various common exceptions conveniently without the need to deal with message resources.

Nice. Do you or @justinvp have a link to the discussion?

Lastly, I would love to have a set of attributes for identifying exceptions that propagate out of APIs. The attributes would divide errors into usage errors (roughly preconditions) and runtime errors (errors that need to be handled).

You mean things like annotating parameters with [NotNull] like in EF Core for usage errors, and Java-style checked exceptions for runtime errors?

[jamesqo]

There is a need for APIs like that in corfxlab and in the platfrom.

@KrzysztofCwalina BTW, if you like the shape of this API, there is something that would make it even sweeter. A C# language proposal that I neglected to mention earlier is related to this API: dotnet/csharplang#205. If that were implemented, it would allow users to forego having to pass in the argument names at all, and still get descriptive error strings.

static class Verify
{
    public static void NotNull<T>(T argument, [CallerArgumentExpression("argument")] string argumentName = null)
    {
        if (argument == null) throw new ArgumentNullException(argumentName);
    }

    public static void NotNegative(int argument, [CallerArgumentExpression("argument")] string argumentName = null)
    {
        if (argument < 0) throw new ArgumentOutOfRangeException(argumentName);
    }
}

T MyGenericMethod<T>(T[] array, int index, int count)
{
    // No nameof, the names of each param are passed to the methods by the compiler.
    Verify.NotNull(array);
    Verify.NotNegative(index);
    Verify.NotNegative(count);
    Verify.InRange(array.Length - index >= count);
}

Note that if we added the API in its current shape to the framework and then that language feature was implemented, it would not be breaking to use the new feature because we'd just mark the last parameter of each method optional.

[justinvp]

Do you or @justinvp have a link to the discussion?

#14487

[svick]

public static void InRange(string s, int index, int count, string sName, string indexName, string countName);
public static void InRange<T>(T[] array, int index, int count, string arrayName, string indexName, string countName);

What is the point of all those name parameters here? I get how specifying the string/array name is useful, but I think the index and count parameters might be obvious or they might not be parameters at all. So I think this mostly just makes the API harder to use.

---

public static void NotNegative(int argument, string argumentName);
public static void Positive(int argument, string argumentName);

Should there be overloads for other numeric types, at least long?

[PhilipDaniels]

This is a common need, I have a similar class, though the names are different. One suggestion: the Verify method should return the object being verified, because this value often gets assigned to a member variable. This enables compact statements of the form

this.foo = NotNull(foo, nameof(foo));

[jamesqo]

@svick

What is the point of all those name parameters here? I get how specifying the string/array name is useful, but I think the index and count parameters might be obvious or they might not be parameters at all. So I think this mostly just makes the API harder to use.

Not everyone uses the same index/count names; some places in the framework it's offset, some arrayIndex, and some destinationIndex. IMO, it would be confusing if an exception was thrown with a different parameter name. We should wait to see the fate of dotnet/csharplang#287; if that is approved, then we can receive all of the argument names for free.

Should there be overloads for other numeric types, at least long?

Depends on how common that would be. I do think long would be a reasonable addition here because it is used in IO APIs, but I wanted to leave that to another proposal to not scare reviewers off.

@PhilipDaniels

This is a common need, I have a similar class, though the names are different. One suggestion: the Verify method should return the object being verified, because this value often gets assigned to a member variable

I had thought of that too. I have mixed feelings about that because it would lead to inconsistencies where some people would write NotNull(foo, nameof(foo)); this.foo = foo; and others would do it your way. However, my main concern is perf-- I think it could lead to poorer code being generated by the JIT, even when the value isn't actually used.

[wekempf]

I think everyone has a version of this, so having an "official" one to use would certainly be nice. In my own, I use [MethodImpl(MethodImplOptions.AggressiveInlining)] for performance. Also, as constructive feedback, I think the naming here is poor. Verify sounds like a generic assertion class (plus, it's a verb and the FDG tells us classes should be nouns). I can see people using Verify.InRange(...) with non-arguments, in which case the exception thrown would be confusing. My own class is called Argument for these reasons, so it's Argument.InRange(...). That said, I also then turn around and use a static using, so all my code says is InRange(...) which has it's own set of problems (it's not a verb and has lost the Argument name at the call site). Naming is hard, to say the least, but I still see people being confused by the exception types being thrown by this helper class without some naming changes.

There's also other argument assertions that are missing here that should be considered. For instance, NotNullOrEmpty and ValidEnumValue are common ones I've used. I've got some others but would have to look them up, but I bet searching in GitHub would find you several more. In fact, this seems to be the only valid reason to reject a proposal like this... there's no way to include assertions for all argument validation needs. I don't think that's enough of a reason not to move forward with this, but is something worth thinking about during design.

[jamesqo]

@wekempf Concerning the naming, do you think calling the class Require or Requires would be more acceptable? e.g. Require.NotNull, Requires.NotNull

[benaadams]

It would likely need to be something like NuGet "source" package when used; rather than a built in to runtime as assembly, so the tests will inline across assembly boundaries when compiled AoT/R2R

[wekempf]

@jamesqo For someone familiar with contracts, probably. For the "masses", I honestly don't know. There are two hard things in programming....

Edit: Oh, forgot this bit. Require/Requires is still not a noun, and thus in violation of the FDG. No idea how rigid that should be followed, however. There's the same problem with the methods in that case, where the methods should be verbs, like IsNotNull.

@benaadams For the inline suggestion, probably, yes. There's several of these already available in NuGet, like https://www.nuget.org/packages/netfx-Guard/. I use source links in my projects for this very reason. Provided as part of the BCL, this obviously wouldn't work. And maybe it's not a big concern? I actually do it not just for the perf, though, it also produces better stack traces when it gets inlined. Maybe there's another solution for that, though?