From 0b0d6f36c2bcbaa95eb0c4b1fb5ab432d0389483 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Tue, 18 Aug 2026 11:47:19 -0400 Subject: [PATCH 1/2] [alpha-v13] Alpha feature preview PR #1774: Feature support for Overload resolution priority Source: https://github.com/dotnet/csharpstandard/pull/1774 Head SHA: 17e8aacd1264e3ad7560458fdf81968c79dfd066 Apply overload resolution priority feature patch from PR #1774 to alpha-v13. 3 files modified: attributes.md, expressions.md, standard-library.md --- standard/attributes.md | 64 +++++++++++++++++++++++++++++++++++- standard/expressions.md | 6 ++++ standard/standard-library.md | 9 +++++ 3 files changed, 78 insertions(+), 1 deletion(-) diff --git a/standard/attributes.md b/standard/attributes.md index ab1ff4569..3cb0f6f78 100644 --- a/standard/attributes.md +++ b/standard/attributes.md @@ -514,6 +514,7 @@ A number of attributes affect the language in some way. These attributes include - `System.Diagnostics.CodeAnalysis.SetsRequiredMembersAttribute` ([§23.5.12.1](attributes.md#235121-the-setsrequiredmembers-attribute)) and `System.Runtime.CompilerServices.RequiredMemberAttribute` ([§23.5.12.2](attributes.md#235122-the-requiredmember-attribute)), which are used in required-member contexts ([§15.7.1](classes.md#1571-general)). - `System.Runtime.CompilerServices.CollectionBuilderAttribute` (§collection-builder-attr), which designates a collection type as having a collection-creation method. - `System.Runtime.CompilerServices.InlineArrayAttribute` (§InlineArrayAttribute), which marks a struct type as an inline array type (§InlineArray). +- `System.Runtime.CompilerServices.OverloadResolutionPriorityAttribute` (§OvrldResPriAttribute), which specifies the priority of a member during overload resolution. The Nullable static analysis attributes ([§23.5.7](attributes.md#2357-code-analysis-attributes)) can improve the correctness of warnings generated for nullabilities and null states ([§8.9.5](types.md#895-nullabilities-and-null-states)). @@ -1588,11 +1589,72 @@ The constructor takes a builder type and the name of the method to be invoked to The attribute can be applied to a class, struct, ref struct, or interface. The attribute is not inherited although it can be applied to a base class or an abstract class. The builder type shall be a non-generic class or struct. - ### §InlineArrayAttribute The InlineArray attribute This attribute is used to identify a non-record struct as an inline array type. For further information and examples of its use, see §InlineArray. +### §OvrldResPriAttribute The OverloadResolutionPriority attribute + +The attribute `OverloadResolutionPriority` is used to specify the priority of a member during overload resolution, as an `int` argument to the constructor. The absence of this attribute is equivalent to its presence with an argument of `0`. The higher the number, the higher the priority. All overloads with a lower priority than the highest overload priority are removed from the set of applicable matches. + +A library author might use this attribute to ensure that a new, better overload is preferred over an existing one, to reduce memory allocation, for example. This attribute informs the compiler which overload should be preferred. + +> +> *Example*: Consider the following: +> +> ```csharp +> class Program +> { +> static void Main() +> { +> var c = new C(); +> int[] arr = [1, 2, 3]; +> c.M(arr); // Prints "Span" +> } +> } +> class C +> { +> [OverloadResolutionPriority(1)] +> public void M(params ReadOnlySpan s) => Console.WriteLine("Span"); +> public void M(params int[] a) => Console.WriteLine("Array"); +> } +> ``` +> +> The second method has an implicit priority of zero, and in the absence of the explicit attribute, the second of the overloads would be invoked. However, with the attribute present, the first is invoked instead. +> +> +> Certain uses of this attribute can make a member uncallable, as follows: +> +> ```csharp +> class Program +> { +> static void Main() +> { +> var c = new C(); +> c.M1(1); // Calls C3.M1(long), not M1(int) +> c.M2(1); // Calls C3.M2(int, string), not M2(int) +> c.M3("abc"); // Calls C3.M3(object), not M3(string) +> } +> } +> class C +> { +> public void M1(int i) { } +> [OverloadResolutionPriority(1)] +> public void M1(long l) { } +> +> [Conditional("DEBUG")] +> public void M2(int i) { } +> [OverloadResolutionPriority(1), Conditional("DEBUG")] +> public void M2(int i, [CallerArgumentExpression(nameof(i))] string s = "") { } +> +> public void M3(string s) { } +> [OverloadResolutionPriority(1)] +> public void M3(object o) { } +> } +> ``` +> +> *end example* + ## 23.6 Attributes for interoperation For interoperation with other languages, an indexer may be implemented using indexed properties. If the indexer is not decorated with `IndexerNameAttribute`, then the name `Item` is used by default. `IndexerNameAttribute` enables a developer to override this default and specify a different name. diff --git a/standard/expressions.md b/standard/expressions.md index 63750adbe..4eb57324c 100644 --- a/standard/expressions.md +++ b/standard/expressions.md @@ -1064,9 +1064,15 @@ Overload resolution is a binding-time mechanism for selecting the best function Each of these contexts defines the set of candidate function members and the list of arguments in its own unique way. For instance, the set of candidates for a method invocation does not include methods marked override ([§12.5](expressions.md#125-member-lookup)), and methods in a base class are not candidates if any method in a derived class is applicable ([§12.8.10.2](expressions.md#128102-method-invocations)). +Each method has an ***overload resolution priority*** of type `int` that is used during the process of resolving a method group. By default, that priority is zero. Its value can be set via `OverloadResolutionPriorityAttribute` (§OvrldResPriAttribute). The overload resolution priority of a member comes from the least-derived declaration of that member. Overload resolution priority is not inherited or inferred from any interface members a type member may implement, and given a member `Mx` that implements an interface member `Mi`, no warning is issued if `Mx` and `Mi` have different overload resolution priorities. + Once the candidate function members and the argument list have been identified, the selection of the best function member is the same in all cases: - First, the set of candidate function members is reduced to those function members that are applicable with respect to the given argument list ([§12.6.4.2](expressions.md#12642-applicable-function-member)). If this reduced set is empty, a compile-time error occurs. +- Then, the reduced set of candidate members is grouped by declaring type. Within each group: + - Candidate function members are ordered by overload resolution priority. If the member is an override, the overload resolution priority comes from the least-derived declaration of that member. + - All members that have a lower overload resolution priority than the highest found within its declaring type group are removed. +- The reduced groups are then recombined into the final set of applicable candidate function members. - Then, the best function member from the set of applicable candidate function members is located. If the set contains only one function member, then that function member is the best function member. Otherwise, the best function member is the one function member that is better than all other function members with respect to the given argument list, provided that each function member is compared to all other function members using the rules in [§12.6.4.3](expressions.md#12643-better-function-member). If there is not exactly one function member that is better than all other function members, then the function member invocation is ambiguous and a binding-time error occurs. The following subclauses define the exact meanings of the terms *applicable function member* and *better function member*. diff --git a/standard/standard-library.md b/standard/standard-library.md index 955427a35..9332b0b2b 100644 --- a/standard/standard-library.md +++ b/standard/standard-library.md @@ -977,6 +977,14 @@ namespace System.Runtime.CompilerServices public ModuleInitializerAttribute() { } } + [System.AttributeUsage(System.AttributeTargets.Constructor + | System.AttributeTargets.Method | System.AttributeTargets.Property, + AllowMultiple=false, Inherited=false)] + public sealed class OverloadResolutionPriorityAttribute : Attribute + { + public OverloadResolutionPriorityAttribute(int priority) {} + } + [System.AttributeUsage(System.AttributeTargets.Class | System.AttributeTargets.Field | System.AttributeTargets.Property | System.AttributeTargets.Struct, AllowMultiple=false, Inherited=false)] @@ -1557,6 +1565,7 @@ The following library types are referenced in this specification. The full names - `global::System.Runtime.CompilerServices.InterpolatedStringHandlerAttribute` - `global::System.Runtime.CompilerServices.ITuple` - `global::System.Runtime.CompilerServices.ModuleInitializerAttribute` +- `global::System.Runtime.CompilerServices.OverloadResolutionPriorityAttribute` - `global::System.Runtime.CompilerServices.RequiredMemberAttribute` - `global::System.Runtime.CompilerServices.TaskAwaiter` - `global::System.Runtime.CompilerServices.TaskAwaiter` From 8337db2f3a7fee81ce4cf8503bee72f354361dbb Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Tue, 22 Sep 2026 10:48:55 -0400 Subject: [PATCH 2/2] Separate reserved attribute headings Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: bce5e82a-89fd-4655-bc08-6d6ba97f0cc6 --- standard/attributes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/standard/attributes.md b/standard/attributes.md index 3cb0f6f78..83313ea06 100644 --- a/standard/attributes.md +++ b/standard/attributes.md @@ -1589,6 +1589,7 @@ The constructor takes a builder type and the name of the method to be invoked to The attribute can be applied to a class, struct, ref struct, or interface. The attribute is not inherited although it can be applied to a base class or an abstract class. The builder type shall be a non-generic class or struct. + ### §InlineArrayAttribute The InlineArray attribute This attribute is used to identify a non-record struct as an inline array type. For further information and examples of its use, see §InlineArray.