Overload Resolution Priority in .NET 9

Introduction

The .NET 9 framework introduced a new feature named overload_resolution_priority, which plays a crucial role in resolving method groups. This priority is represented as a 32-bit integer. By default, all methods have an overload_resolution_priority of 0, but this value can be modified by applying the OverloadResolutionPriorityAttribute to a method.

Simple Syntax: [OverloadResolutionPriority(<integer>)]

OverloadResolutionPriority

This attribute is part of the System.Runtime.CompilerServices namespace in .NET 9, and this can be applied to constructors, methods, and properties. The motive of this attribute introduction in .NET9 is to overcome some of the inabilities of the "Obsolete" attribute, which is usually used for backward compatibility in our APIs.

We can understand this by taking one of the easy scenarios to apply the methods below.

Scenario

Let's understand more by taking a simple scenario of overloads with Numeric Types (Ex. converting an int to double etc). By assigning priorities, we can control which method takes precedence without changing the call of the method. It reduces the risk of unintended conversions.

For example, we have the following simple methods to add by taking two numbers as input. However, one has int data type parameters, and the other has double data type parameters.

public static class ExploreFeatures
{
    public static void SumOfNumbers(int num1, int num2)
    {
        Console.WriteLine("Integer Numbers Sum is: " + (num1 + num2));
    }

    public static void SumOfNumbers(double num1, double num2)
    {
        Console.WriteLine("Double Numbers Sum is: " + (num1 + num2));
    }
}

Let's try to call the method just like the one below.

ExploreFeatures.SumOfNumbers(3, 5);

Then, the output is as follows as very much expected.

Let's apply the OverloadResolutionPriority attribute to our methods, as shown below.

public static class ExploreFeatures
{
    public static void SumOfNumbers(int num1, int num2)
    {
        Console.WriteLine("Integer Numbers Sum is: " + (num1 + num2));
    }

    //As, we set with Overload resoultion priority as 1 to this method and other 
    // overload method as not defined any. This takes as precdence.
    // we can try by adding priority in other method or vice versa.
    [OverloadResolutionPriority(1)]
    public static void SumOfNumbers(double num1, double num2)
    {
        Console.WriteLine("Double Numbers Sum is: " + (num1 + num2));
    }
}

Now, execute our program again and see the result. You can see that the SumOfNumbers method with double data type parameters is called without any changes while calling the method. That indicates the compiler itself indicates the priority of which method to be considered based on our attribute defined.

It's really cool. Right...!!

The aforesaid source code is attached to this article for reference.

Other Benefits

Enhancing APIs with Flexible Parameters: APIs that support multiple overloads for various input types (e.g., string, int, or custom classes) can use this attribute to specify a preferred overload for common scenarios while keeping alternative overloads available for flexibility.

Ensuring Backward Compatibility: Whenever adding a new overload to an existing API, assigning it a lower priority helps preserve backward compatibility by favoring older methods in overload resolution.

Limitations

Priority Conflicts: For example, When multiple overloads share the same priority, the compiler defaults to its standard resolution rules. This can sometimes result in ambiguity warnings or errors.

Excessive usage may lead to poor code clarity, so It's best to apply OverloadResolutionPriorityAttribute only when it enhances clarity and suitable scenarios (Ex, aforesaid scenarios) to improve overall usability.

Reference: https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/proposals/csharp-13.0/overload-resolution-priority

Summary

This OverloadResolutionPriorityAttribute definitely provides powerful additions to method overloading in C#. It gives enhanced code readability, complete control of which method to be overloaded, and especially backward compatibility in APIs.