dotnet / dotnet/csharplang

[Proposal]: Overload Resolution Priority (VS 17.12, .NET 9)

Open
#7,706 61 comments 35 reactions 1 assignee Claimed by @333fred View on GitHub
Implemented Needs ECMA Spec Proposal Proposal champion
Dominant language
C#
Stars
12.7k
Forks
1.1k
Avg merge
11h 1m
Merged PRs (30d)
3

Description

* [x] Proposed
* [ ] Prototype: Not Started
* [ ] Implementation: Not Started
* [x] Specification: https://github.com/dotnet/csharplang/blob/main/proposals/overload-resolution-priority.md

## Summary
[summary]: #summary

We introduce a new attribute, `System.Runtime.CompilerServices.OverloadResolutionPriority`, that can be used by API authors to adjust the relative priority of
overloads within a single type as a means of steering API consumers to use specific APIs, even if those APIs would normally be considered ambiguous or otherwise
not be chosen by C#'s overload resolution rules.

## Motivation
[motivation]: #motivation

API authors often run into an issue of what to do with a member after it has been obsoleted. For backwards compatibility purposes, many will keep the existing member around
with `ObsoleteAttribute` set to error in perpetuity, in order to avoid breaking consumers who upgrade binaries at runtime. This particularly hits plugin systems, where the
author of a plugin does not control the environment in which the plugin runs. The creator of the environment may want to keep an older method present, but block access to it
for any newly developed code. However, `ObsoleteAttribute` by itself is not enough. The type or member is still visible in overload resolution, and may cause unwanted overload
resolution failures when there is a perfectly good alternative, but that alternative is either ambiguous with the obsoleted member, or the presence of the obsoleted member causes
overload resolution to end early without ever considering the good member. For this purpose, we want to have a way for API authors to guide overload resolution on resolving the
ambiguity, so that they can evolve their API surface areas and steer users towards performant APIs without having to compromise the user experience.

## Design Meetings

* https://github.com/dotnet/csharplang/blob/main/meetings/2023/LDM-2023-12-04.md#binarycompatonlyattribute
* https://github.com/dotnet/csharplang/blob/main/meetings/2024/LDM-2024-03-04.md#overload-resolution-priority
* https://github.com/dotnet/csharplang/blob/main/meetings/2024/LDM-2024-05-13.md#overload-resolution-priority-questions
* https://github.com/dotnet/csharplang/blob/main/meetings/2024/LDM-2024-06-17.md#overload-resolution-priority-questions
* https://github.com/dotnet/csharplang/blob/main/meetings/2024/LDM-2024-07-17.md#overload-resolution-priority-open-questions

## Related Issues

- #4984

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.