Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

C# Method Overloading: Syntax, Rules, and Practical Use

Learn how C# method overloading works: signature rules, compiler resolution, common mistakes, and when generics or optional parameters fit better.

~5 min readC#
#method overloading#C# syntax#overload resolution#optional parameters
Diagram showing multiple C# method signature cards converging into a single resolved overloaded method call

C# method overloading lets you define multiple methods with the same name in a class, as long as each version has a distinct parameter list. The compiler decides which overload to call based on the arguments you pass at the call site.

csharp
public class Calculator { public int Add(int left, int right) { return left + right; } public double Add(double left, double right) { return left + right; } }

Here, Add is defined twice. The first version accepts two integers; the second accepts two doubles. When you call calculator.Add(2, 3), the compiler selects the integer version. When you call calculator.Add(2.5, 3.5), it selects the double version. The return type is not part of the overload signature, so you cannot distinguish overloads by return type alone.

What Counts as a Valid Overload

The C# compiler identifies an overload by its method name and parameter list. The parameter list includes the types of the parameters, their order, and whether they are declared ref, out, or in. Two methods with the same name and parameter types but different return types produce a compile error.

csharp
// Compile error: cannot overload solely by return type public int GetValue() { return 1; } public string GetValue() { return "one"; }

Parameter names do not matter for overload resolution. The following two declarations conflict:

csharp
public void SetPoint(int x, int y) { } public void SetPoint(int left, int right) { } // CS0111: type already defines a member

The order of parameters does matter. SetPoint(int, string) and SetPoint(string, int) are distinct overloads, even though both contain the same two types.

How the Compiler Resolves Overloads

When you call an overloaded method, the compiler evaluates each candidate against the argument types and applies a set of rules defined by the C# language specification to pick the best match. The most important rule is that the compiler prefers the candidate requiring the least costly conversion. An exact match wins over an implicit numeric conversion, which is preferred over a boxing conversion.

csharp
public void Process(int value) { } public void Process(long value) { } Process(42); // picks Process(int) - exact match Process(42L); // picks Process(long) - exact match

If you call Process(42) and only the long version exists, the compiler uses the implicit conversion from int to long. If both versions exist, the exact match wins.

When multiple candidates are equally good, the compiler reports an ambiguity error. This commonly happens with null arguments or when mixing optional parameters.

csharp
public void Handle(string input) { } public void Handle(object input) { } Handle(null); // CS0121: ambiguous call

Both string and object can accept null, and neither conversion is better than the other, so the call is ambiguous.

Overloading with Optional and Default Parameters

C# also supports optional parameters, which interact with overloading in ways that can surprise developers. When a method declares a default value, the compiler fills in that default when a call omits the corresponding argument.

csharp
public void Log(string message, string level = "info") { Console.WriteLine($"[{level}] {message}"); } Log("started"); // level defaults to "info" Log("failed", "error"); // explicit level

Optional parameters do not add overloads to the method group. When another overload can handle the shorter call without using a default, the compiler generally prefers it when the conversions are otherwise equally good. Ambiguity is more likely when two optional-parameter methods are equally applicable and both require a default substitution.

For example, the following call is ambiguous because both methods require filling in a default:

csharp
public void Open(string path = "config.json") { } public void Open(int mode = 0) { } Open(); // CS0121: ambiguous call

A cleaner approach is to use explicit overloads instead of optional parameters when the number of arguments is small and the behavior differs meaningfully between versions.

csharp
public void Send(string message) { Send(message, TimeSpan.FromSeconds(30)); } public void Send(string message, TimeSpan timeout) { // actual implementation }

This pattern keeps the implementation in one place while exposing a convenient one-argument entry point.

Common Mistakes and Edge Cases

One frequent mistake is assuming that overloading works with params arrays the same way it works with fixed parameters. A params parameter is treated as an array for overload resolution, so calls with multiple arguments may not match the way you expect.

csharp
public void Join(params string[] parts) { } public void Join(string separator, params string[] parts) { } Join("a", "b", "c"); // picks the second overload: separator = "a", parts = { "b", "c" }

Another edge case involves inheritance. A method declared in a derived class with the same name as a base-class method does not add an overload; it hides the base methods with that name for calls through the derived type.

csharp
public class Base { public void Execute(int value) { } } public class Derived : Base { public void Execute(string value) { } } var d = new Derived(); d.Execute(5); // compile error: only Execute(string) is visible on Derived, so int does not match

For calls through a Derived reference, only Execute(string) is considered. The base integer version is hidden. Calling through a Base-typed reference, or using base.Execute from inside the derived class, reaches the integer version. The new modifier suppresses the compiler warning about hiding, but it does not bring the base overloads into the derived type's callable set.

Performance and Maintainability Considerations

Method overloading itself adds no runtime dispatch cost for ordinary statically typed calls. The compiler resolves which overload to call at compile time, so the generated IL calls that method directly. If the selected method is virtual, the normal virtual dispatch rules still apply. If an argument is dynamic, overload resolution is deferred until runtime, and the call uses the dynamic dispatch machinery.

The real cost of overloading is maintainability. Each overload adds surface area to a class, and callers must understand which version applies to their arguments. When overloads grow to more than a handful, consider whether the differences between them are better expressed through a single method that accepts a configuration object.

For example, a method that accepts either a file path or a stream can reasonably be modeled as two overloads:

csharp
public void Load(string filePath) { } public void Load(Stream stream) { }

This is reasonable because the two inputs are genuinely different types. But if the overloads differ only by a flag or a default value, a single method with an optional parameter is usually clearer.

When to Prefer Alternatives

Overloading is not always the best tool. C# offers several alternatives that can be more expressive depending on the situation.

Optional parameters work well when the difference between calls is a simple default value. Generic methods are better when the overloads differ only by the type of a single parameter and the body is identical.

csharp
public T Max<T>(T left, T right) where T : IComparable<T> { return left.CompareTo(right) >= 0 ? left : right; }

This replaces what would otherwise be a series of near-identical overloads for int, double, string, and so on. The generic version is type-safe and requires no duplication.

Overloading remains the right choice when the method bodies genuinely differ, or when you need to accept unrelated types that do not share a common interface. The decision comes down to whether the variations are about the type of the input or the behavior of the method. If the behavior changes, overload. If only the type changes, consider a generic. If only a default changes, use an optional parameter.

Try matching browser tools

All tools

Small utilities that fit C# work — they run entirely in this browser tab, so nothing you paste leaves your device.

All C# guides

More in C#

All C# guides

The guides filed next to this one in C#, in library order.