Use CallerArgumentExpression for easier calling conventions

Author: AArnott

src/Microsoft.VisualStudio.Validation/Assumes.cs

@@ -6,6 +6,7 @@
 using System.Diagnostics.CodeAnalysis;
 using System.Globalization;
 using System.Runtime;
+using System.Runtime.CompilerServices;
 
 namespace Microsoft;
 
@@ -128,7 +129,7 @@ public static void Is<T>([NotNull] object? value)
     /// </summary>
     [DebuggerStepThrough]
     [TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")]
-    public static void False([DoesNotReturnIf(true)] bool condition, [Localizable(false)] string? message = null)
+    public static void False([DoesNotReturnIf(true)] bool condition, [CallerArgumentExpression(nameof(condition)), Localizable(false)] string? message = null)
     {
         if (condition)
         {
@@ -167,7 +168,7 @@ public static void False([DoesNotReturnIf(true)] bool condition, [Localizable(fa
     /// </summary>
     [DebuggerStepThrough]
     [TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")]
-    public static void True([DoesNotReturnIf(false)] bool condition, [Localizable(false)] string? message = null)
+    public static void True([DoesNotReturnIf(false)] bool condition, [CallerArgumentExpression(nameof(condition)), Localizable(false)] string? message = null)
     {
         if (!condition)
         {

src/Microsoft.VisualStudio.Validation/Polyfill.cs

@@ -0,0 +1,20 @@
+// Copyright (c) Microsoft. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+#if !NET5_0_OR_GREATER
+
+#pragma warning disable SA1649 // File name should match first type name
+#pragma warning disable SA1600 // Elements should be documented
+
+namespace System.Runtime.CompilerServices
+{
+    [AttributeUsage(AttributeTargets.Parameter, AllowMultiple = false, Inherited = false)]
+    internal sealed class CallerArgumentExpressionAttribute : Attribute
+    {
+        internal CallerArgumentExpressionAttribute(string parameterName)
+        {
+        }
+    }
+}
+
+#endif

src/Microsoft.VisualStudio.Validation/Requires.cs

@@ -8,6 +8,7 @@
 using System.Globalization;
 using System.Resources;
 using System.Runtime;
+using System.Runtime.CompilerServices;
 
 namespace Microsoft;
 
@@ -21,12 +22,12 @@ public static class Requires
     /// </summary>
     /// <typeparam name="T">The type of the parameter.</typeparam>
     /// <param name="value">The value of the argument.</param>
-    /// <param name="parameterName">The name of the parameter to include in any thrown exception.</param>
+    /// <param name="parameterName">The name of the parameter to include in any thrown exception. If this argument is omitted (explicitly writing <see langword="null" /> does not qualify), the expression used in the first argument will be used as the parameter name.</param>
     /// <returns>The value of the parameter.</returns>
     /// <exception cref="ArgumentNullException">Thrown if <paramref name="value"/> is <see langword="null"/>.</exception>
     [DebuggerStepThrough]
     [TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")]
-    public static T NotNull<T>([ValidatedNotNull, NotNull] T value, string? parameterName)
+    public static T NotNull<T>([ValidatedNotNull, NotNull] T value, [CallerArgumentExpression(nameof(value))] string? parameterName = null)
         where T : class // ensures value-types aren't passed to a null checking method
     {
         if (value is null)
@@ -41,12 +42,12 @@ public static T NotNull<T>([ValidatedNotNull, NotNull] T value, string? paramete
     /// Throws an exception if the specified parameter's value is IntPtr.Zero.
     /// </summary>
     /// <param name="value">The value of the argument.</param>
-    /// <param name="parameterName">The name of the parameter to include in any thrown exception.</param>
+    /// <param name="parameterName">The name of the parameter to include in any thrown exception. If this argument is omitted (explicitly writing <see langword="null" /> does not qualify), the expression used in the first argument will be used as the parameter name.</param>
     /// <returns>The value of the parameter.</returns>
     /// <exception cref="ArgumentNullException">Thrown if <paramref name="value"/> is <see cref="IntPtr.Zero"/>.</exception>
     [DebuggerStepThrough]
     [TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")]
-    public static IntPtr NotNull(IntPtr value, string? parameterName)
+    public static IntPtr NotNull(IntPtr value, [CallerArgumentExpression(nameof(value))] string? parameterName = null)
     {
         if (value == IntPtr.Zero)
         {
@@ -60,15 +61,15 @@ public static IntPtr NotNull(IntPtr value, string? parameterName)
     /// Throws an exception if the specified parameter's value is null.
     /// </summary>
     /// <param name="value">The value of the argument.</param>
-    /// <param name="parameterName">The name of the parameter to include in any thrown exception.</param>
+    /// <param name="parameterName">The name of the parameter to include in any thrown exception. If this argument is omitted (explicitly writing <see langword="null" /> does not qualify), the expression used in the first argument will be used as the parameter name.</param>
     /// <exception cref="ArgumentNullException">Thrown if <paramref name="value"/> is <see langword="null"/>.</exception>
     /// <remarks>
     /// This method allows async methods to use Requires.NotNull without having to assign the result
     /// to local variables to avoid C# warnings.
     /// </remarks>
     [DebuggerStepThrough]
     [TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")]
-    public static void NotNull([ValidatedNotNull, NotNull] Task value, string? parameterName)
+    public static void NotNull([ValidatedNotNull, NotNull] Task value, [CallerArgumentExpression(nameof(value))] string? parameterName = null)
     {
         if (value is null)
         {
@@ -81,15 +82,15 @@ public static void NotNull([ValidatedNotNull, NotNull] Task value, string? param
     /// </summary>
     /// <typeparam name="T">The type of the return value of the task.</typeparam>
     /// <param name="value">The value of the argument.</param>
-    /// <param name="parameterName">The name of the parameter to include in any thrown exception.</param>
+    /// <param name="parameterName">The name of the parameter to include in any thrown exception. If this argument is omitted (explicitly writing <see langword="null" /> does not qualify), the expression used in the first argument will be used as the parameter name.</param>
     /// <exception cref="ArgumentNullException">Thrown if <paramref name="value"/> is <see langword="null"/>.</exception>
     /// <remarks>
     /// This method allows async methods to use Requires.NotNull without having to assign the result
     /// to local variables to avoid C# warnings.
     /// </remarks>
     [DebuggerStepThrough]
     [TargetedPatchingOptOut("Performance critical to inline across NGen image boundaries")]
-    public static void NotNull<T>([ValidatedNotNull, NotNull] Task<T> value, string? parameterName)
+    public static void NotNull<T>([ValidatedNotNull, NotNull] Task<T> value, [CallerArgumentExpression(nameof(value))] string? parameterName = null)
     {
         if (value is null)
         {
@@ -102,15 +103,15 @@ public static void NotNull<T>([ValidatedNotNull, NotNull] Task<T> value, string?
     /// </summary>
     /// <typeparam name="T">The type of the parameter.</typeparam>
     /// <param name="value">The value of the argument.</param>
-    /// <param name="parameterName">The name of the parameter to include in any thrown exception.</param>
+    /// <param name="parameterName">The name of the parameter to include in any thrown exception. If this argument is omitted (explicitly writing <see langword="null" /> does not qualify), the expression used in the first argument will be used as the parameter name.</param>
     /// <returns>The value of the parameter.</returns>
     /// <exception cref="ArgumentNullException">Thrown if <paramref name="value"/> is <see langword="null"/>.</exception>
     /// <remarks>
     /// This method exists for callers who themselves only know the type as a generic parameter which
     /// may or may not be a class, but certainly cannot be null.
     /// </remarks>
     [DebuggerStepThrough]
-    public static T NotNullAllowStructs<T>([ValidatedNotNull, NotNull] T value, string? parameterName)
+    public static T NotNullAllowStructs<T>([ValidatedNotNull, NotNull] T value, [CallerArgumentExpression(nameof(value))] string? parameterName = null)
     {
         if (value is null)
         {
@@ -124,10 +125,10 @@ public static T NotNullAllowStructs<T>([ValidatedNotNull, NotNull] T value, stri
     /// Throws an exception if the specified parameter's value is null or empty.
     /// </summary>
     /// <param name="value">The value of the argument.</param>
-    /// <param name="parameterName">The name of the parameter to include in any thrown exception.</param>
+    /// <param name="parameterName">The name of the parameter to include in any thrown exception. If this argument is omitted (explicitly writing <see langword="null" /> does not qualify), the expression used in the first argument will be used as the parameter name.</param>
     /// <exception cref="ArgumentException">Thrown if <paramref name="value"/> is <see langword="null"/> or empty.</exception>
     [DebuggerStepThrough]
-    public static void NotNullOrEmpty([ValidatedNotNull, NotNull] string value, string? parameterName)
+    public static void NotNullOrEmpty([ValidatedNotNull, NotNull] string value, [CallerArgumentExpression(nameof(value))] string? parameterName = null)
     {
         // To whoever is doing random code cleaning:
         // Consider the performance when changing the code to delegate to NotNull.
@@ -147,10 +148,10 @@ public static void NotNullOrEmpty([ValidatedNotNull, NotNull] string value, stri
     /// Throws an exception if the specified parameter's value is null, empty, or whitespace.
     /// </summary>
     /// <param name="value">The value of the argument.</param>
-    /// <param name="parameterName">The name of the parameter to include in any thrown exception.</param>
+    /// <param name="parameterName">The name of the parameter to include in any thrown exception. If this argument is omitted (explicitly writing <see langword="null" /> does not qualify), the expression used in the first argument will be used as the parameter name.</param>
     /// <exception cref="ArgumentException">Thrown if <paramref name="value"/> is <see langword="null"/> or empty.</exception>
     [DebuggerStepThrough]
-    public static void NotNullOrWhiteSpace([ValidatedNotNull, NotNull] string value, string? parameterName)
+    public static void NotNullOrWhiteSpace([ValidatedNotNull, NotNull] string value, [CallerArgumentExpression(nameof(value))] string? parameterName = null)
     {
         // To whoever is doing random code cleaning:
         // Consider the performance when changing the code to delegate to NotNull.
@@ -176,10 +177,10 @@ public static void NotNullOrWhiteSpace([ValidatedNotNull, NotNull] string value,
     /// has no elements.
     /// </summary>
     /// <param name="values">The value of the argument.</param>
-    /// <param name="parameterName">The name of the parameter to include in any thrown exception.</param>
+    /// <param name="parameterName">The name of the parameter to include in any thrown exception. If this argument is omitted (explicitly writing <see langword="null" /> does not qualify), the expression used in the first argument will be used as the parameter name.</param>
     /// <exception cref="ArgumentException">Thrown if the tested condition is false.</exception>
     [DebuggerStepThrough]
-    public static void NotNullOrEmpty([ValidatedNotNull, NotNull] IEnumerable values, string? parameterName)
+    public static void NotNullOrEmpty([ValidatedNotNull, NotNull] IEnumerable values, [CallerArgumentExpression(nameof(values))] string? parameterName = null)
     {
         // To whoever is doing random code cleaning:
         // Consider the performance when changing the code to delegate to NotNull.
@@ -205,10 +206,10 @@ public static void NotNullOrEmpty([ValidatedNotNull, NotNull] IEnumerable values
     /// </summary>
     /// <typeparam name="T">The type produced by the enumeration.</typeparam>
     /// <param name="values">The value of the argument.</param>
-    /// <param name="parameterName">The name of the parameter to include in any thrown exception.</param>
+    /// <param name="parameterName">The name of the parameter to include in any thrown exception. If this argument is omitted (explicitly writing <see langword="null" /> does not qualify), the expression used in the first argument will be used as the parameter name.</param>
     /// <exception cref="ArgumentException">Thrown if the tested condition is false.</exception>
     [DebuggerStepThrough]
-    public static void NotNullOrEmpty<T>([ValidatedNotNull, NotNull] IEnumerable<T> values, string? parameterName)
+    public static void NotNullOrEmpty<T>([ValidatedNotNull, NotNull] IEnumerable<T> values, [CallerArgumentExpression(nameof(values))] string? parameterName = null)
     {
         // To whoever is doing random code cleaning:
         // Consider the performance when changing the code to delegate to NotNull.
@@ -245,10 +246,10 @@ public static void NotNullOrEmpty<T>([ValidatedNotNull, NotNull] IEnumerable<T>
     /// </summary>
     /// <typeparam name="T">The type of value in the collection.</typeparam>
     /// <param name="values">The value of the argument.</param>
-    /// <param name="parameterName">The name of the parameter to include in any thrown exception.</param>
+    /// <param name="parameterName">The name of the parameter to include in any thrown exception. If this argument is omitted (explicitly writing <see langword="null" /> does not qualify), the expression used in the first argument will be used as the parameter name.</param>
     /// <exception cref="ArgumentException">Thrown if the tested condition is false.</exception>
     [DebuggerStepThrough]
-    public static void NotNullOrEmpty<T>([ValidatedNotNull, NotNull] ICollection<T> values, string? parameterName)
+    public static void NotNullOrEmpty<T>([ValidatedNotNull, NotNull] ICollection<T> values, [CallerArgumentExpression(nameof(values))] string? parameterName = null)
     {
         // To whoever is doing random code cleaning:
         // Consider the performance when changing the code to delegate to NotNull.
@@ -270,10 +271,10 @@ public static void NotNullOrEmpty<T>([ValidatedNotNull, NotNull] ICollection<T>
     /// </summary>
     /// <typeparam name="T">The type of the elements in the sequence.</typeparam>
     /// <param name="values">The value of the argument.</param>
-    /// <param name="parameterName">The name of the parameter to include in any thrown exception.</param>
+    /// <param name="parameterName">The name of the parameter to include in any thrown exception. If this argument is omitted (explicitly writing <see langword="null" /> does not qualify), the expression used in the first argument will be used as the parameter name.</param>
     /// <exception cref="ArgumentException">Thrown if the tested condition is false.</exception>
     [DebuggerStepThrough]
-    public static void NotNullEmptyOrNullElements<T>([ValidatedNotNull, NotNull] IEnumerable<T> values, string? parameterName)
+    public static void NotNullEmptyOrNullElements<T>([ValidatedNotNull, NotNull] IEnumerable<T> values, [CallerArgumentExpression(nameof(values))] string? parameterName = null)
         where T : class // ensures value-types aren't passed to a null checking method
     {
         // To whoever is doing random code cleaning:
@@ -307,10 +308,10 @@ public static void NotNullEmptyOrNullElements<T>([ValidatedNotNull, NotNull] IEn
     /// </summary>
     /// <typeparam name="T">The type of the elements in the sequence.</typeparam>
     /// <param name="values">The value of the argument.</param>
-    /// <param name="parameterName">The name of the parameter to include in any thrown exception.</param>
+    /// <param name="parameterName">The name of the parameter to include in any thrown exception. If this argument is omitted (explicitly writing <see langword="null" /> does not qualify), the expression used in the first argument will be used as the parameter name.</param>
     /// <exception cref="ArgumentException">Thrown if the tested condition is false.</exception>
     [DebuggerStepThrough]
-    public static void NullOrNotNullElements<T>(IEnumerable<T> values, string? parameterName)
+    public static void NullOrNotNullElements<T>(IEnumerable<T> values, [CallerArgumentExpression(nameof(values))] string? parameterName = null)
     {
         if (values is object)
         {
@@ -328,10 +329,10 @@ public static void NullOrNotNullElements<T>(IEnumerable<T> values, string? param
     /// Throws an exception if the specified parameter's value is <see cref="Guid.Empty"/>.
     /// </summary>
     /// <param name="value">The value of the argument.</param>
-    /// <param name="parameterName">The name of the parameter to include in any thrown exception.</param>
+    /// <param name="parameterName">The name of the parameter to include in any thrown exception. If this argument is omitted (explicitly writing <see langword="null" /> does not qualify), the expression used in the first argument will be used as the parameter name.</param>
     /// <exception cref="ArgumentException">Thrown if <paramref name="value"/> is an empty guid (<see cref="Guid.Empty"/>.)</exception>
     [DebuggerStepThrough]
-    public static void NotEmpty(Guid value, string? parameterName)
+    public static void NotEmpty(Guid value, [CallerArgumentExpression(nameof(value))] string? parameterName = null)
     {
         if (value == Guid.Empty)
         {
@@ -521,9 +522,9 @@ public static Exception Fail(Exception? innerException, string unformattedMessag
     /// </summary>
     /// <typeparam name="TEnum">The type of enum that may define the <paramref name="value"/>.</typeparam>
     /// <param name="value">The value that may be named by <typeparamref name="TEnum"/>.</param>
-    /// <param name="parameterName">The name of the parameter to include in the exception, if thrown.</param>
+    /// <param name="parameterName">The name of the parameter to include in any thrown exception. If this argument is omitted (explicitly writing <see langword="null" /> does not qualify), the expression used in the first argument will be used as the parameter name.</param>
     [DebuggerStepThrough]
-    public static void Defined<TEnum>(TEnum value, string parameterName)
+    public static void Defined<TEnum>(TEnum value, [CallerArgumentExpression(nameof(value))] string? parameterName = null)
         where TEnum : struct, Enum
     {
         if (!Enum.IsDefined(typeof(TEnum), value))
@@ -545,10 +546,10 @@ public static void Defined<TEnum>(TEnum value, string parameterName)
     /// </summary>
     /// <typeparam name="T">The type of the parameter.</typeparam>
     /// <param name="value">The value of the argument.</param>
-    /// <param name="parameterName">The name of the parameter to include in any thrown exception.</param>
+    /// <param name="parameterName">The name of the parameter to include in any thrown exception. If this argument is omitted (explicitly writing <see langword="null" /> does not qualify), the expression used in the first argument will be used as the parameter name.</param>
     /// <exception cref="ArgumentException">Thrown if <paramref name="value"/> is <see langword="null"/> or empty.</exception>
     [DebuggerStepThrough]
-    public static void NotDefault<T>(T value, string parameterName)
+    public static void NotDefault<T>(T value, [CallerArgumentExpression(nameof(value))] string? parameterName = null)
         where T : struct
     {
         var defaultValue = default(T);