Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

C# Named Arguments: Syntax and Usage

Learn how to use C# named arguments, including syntax, placement rules, optional parameters, and readability tradeoffs.

~6 min readC#
#C##named arguments#method parameters#optional parameters
Diagram showing named arguments mapping parameter names to values in a C# method call.

Named arguments let you pass arguments to a C# method by specifying the parameter name instead of relying only on position. This article covers the syntax, placement rules, optional parameters, common compiler errors, overload resolution, and maintainability tradeoffs.

What Named Arguments Are and Why They Exist

In C#, a method call normally passes arguments positionally: the first argument goes to the first parameter, the second to the second, and so on. Named arguments break that coupling by allowing you to write parameterName: value in the call. The compiler then matches the argument to the parameter with that name, even if the argument is not in the same position in the call.

The feature exists primarily for readability. When a method has several parameters of the same type, or when a boolean or numeric value is passed without context, a positional call can be opaque. Named arguments let the call document itself.

csharp
public void Configure(string host, int port, bool useTls) { // ... } // Positional call Configure("example.com", 443, true); // Named call Configure(host: "example.com", port: 443, useTls: true);

The named version makes it clear which value corresponds to which parameter. It also reduces the risk of accidentally swapping two arguments of the same type.

Basic Syntax and Placement Rules

The syntax for a named argument is parameterName: argumentValue. The parameter name must match the name of a parameter in the method signature, and the argument value must be implicitly convertible to that parameter's type.

Named arguments can appear in any order relative to each other. The compiler resolves them by name, not by position.

csharp
Configure(useTls: true, host: "example.com", port: 443);

This is valid and behaves identically to the previous call.

Positional arguments may appear before named arguments. Since C# 7.2, a named argument may also appear before positional arguments when it is in its correct position in the parameter list. If a named argument is out of position, all following arguments must be named. For older language versions, keep positional arguments before named arguments.

csharp
// Valid: positional first, then named Configure("example.com", port: 443, useTls: true); // Valid in C# 7.2+: host is in its correct first position Configure(host: "example.com", 443, useTls: true); // Invalid: useTls is out of position and followed by positional arguments Configure(useTls: true, "example.com", 443); // CS8323

The compiler error CS8323 states: "Named argument 'useTls' is used out-of-position but is followed by an unnamed argument." This is a compile-time error.

Mixing Positional and Named Arguments

When you mix positional and named arguments, the rule is not simply "named arguments must come last." The compiler allows a named argument before positional arguments when the named argument is in the same position it would occupy in the parameter list. If a named argument is out of position, every subsequent argument must be named.

csharp
// Allowed: positional then named Configure("example.com", useTls: true, port: 443); // Allowed in C# 7.2+: host is in correct first position Configure(host: "example.com", 443, useTls: true); // Not allowed: useTls is out of position and followed by a positional argument Configure(useTls: true, "example.com", port: 443); // Compiler error

In practice, mixing is useful when you want to name only the less obvious parameters while leaving the common ones positional. For example, a method with a long parameter list might have a few parameters that are always passed in the same order, and a few that are optional or rarely changed.

Named Arguments with Optional Parameters

Named arguments become especially valuable when a method has optional parameters. Without named arguments, you must supply values for all preceding optional parameters if you want to set a later one. With named arguments, you can skip any optional parameter and set only the ones you need.

csharp
public void Log(string message, string level = "Info", bool includeTimestamp = true) { // ... } // Positional: must provide level to set includeTimestamp Log("Server started", "Info", false); // Named: set only includeTimestamp Log("Server started", includeTimestamp: false);

This eliminates the need to pass default values explicitly and makes the call more readable. It also reduces the risk of passing a value to the wrong optional parameter when several have the same type.

One thing to keep in mind: when you use named arguments with optional parameters, the compiler still requires that all required parameters are supplied. You cannot skip a required parameter, even with a name.

Common Mistakes and Compiler Errors

The most common mistake is misspelling a parameter name. The compiler reports an error like CS1739: "The best overload for 'X' does not have a parameter named 'Y'." This is caught at compile time, but it can be confusing when you are using a library and the parameter names are not what you expect.

Another common mistake is placing a positional argument after a named argument that is out of position. That produces CS8323, as shown earlier. It is a compile-time error.

Named arguments also do not let you overload a method based only on parameter names. C# method signatures include parameter types and count but not parameter names. These two declarations are the same signature and cannot coexist in one type:

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

Readability and Maintainability Tradeoffs

Named arguments improve readability when a method has many parameters, especially when several are of the same type. They also make the intent of boolean or numeric arguments clear. For example, Configure(useTls: true) is more informative than Configure(true).

However, named arguments add verbosity. A call with five named arguments is longer than the same call with positional arguments. In a codebase where method calls are frequent, this can make the code harder to scan quickly. The tradeoff is between self-documenting code and conciseness.

There is also a maintainability concern: if a method's parameter names change, every call that uses named arguments must be updated. This is a form of coupling that does not exist with positional arguments. When you control the method signature, renaming a parameter is a breaking change for all callers that use named arguments. With positional arguments, renaming a parameter has no effect on callers.

This is not a reason to avoid named arguments entirely, but it is a reason to use them deliberately. For internal methods where the signature is stable, named arguments can be a good choice. For public APIs, consider whether parameter names are part of the contract you want to maintain.

The table below summarizes the key differences between positional and named arguments.

AspectPositionalNamed
Readability with many same-type paramsLowHigh
Risk of swapping argumentsHighLow
Coupling to parameter namesNoneStrong
Call verbosityLowHigher
Overload disambiguationLimitedCan resolve some ambiguous overloads

When to Avoid Named Arguments

Named arguments are not always the best choice. If a method has a single parameter, naming it adds no value. If a method has two parameters with clearly different types, positional arguments are usually fine. For example, MoveTo(10, 20) is clear enough if the method is documented as taking x and y coordinates.

Named arguments have no runtime performance cost; they are resolved at compile time and produce the same kind of method call as positional arguments. The real cost is source-level code churn and readability. If a method call is short and the parameter names are obvious from the method name, named arguments add noise. Use them when the call would otherwise be ambiguous.

Named Arguments in Overload Resolution

Named arguments participate in overload resolution: the compiler only considers overloads whose parameters include the supplied argument names. This can select one overload when a positional call would be ambiguous, but it does not allow two methods with identical parameter types but different names.

csharp
public void Draw(int x, double y) { } public void Draw(double left, int top) { } // Ambiguous positional call Draw(10, 20); // Selects only the first overload by name Draw(x: 10, y: 20);

The two Draw overloads are valid because their parameter types differ. The positional call Draw(10, 20) is ambiguous because 10 and 20 each convert to both int and double; the first overload is better for the first argument, and the second is better for the second, so neither overload wins. The named call removes the ambiguity by matching x and y to the first overload.

This also means parameter names are part of the source contract for callers that use named arguments. Adding an overload with different parameter names can change which method a named call binds to, and renaming a public parameter is a source-breaking change for named callers.

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.