C# Optional Parameters: Syntax, Behavior, and Pitfalls

When you declare a method in C#, you can mark some parameters as optional by assigning a constant default value in the signature. This lets callers omit those arguments, but the mechanism has some rules that are easy to miss. In this article about C# optional parameters, you'll see how the compiler handles defaults, why named arguments matter, and where optional parameters can cause trouble in real code.

Declaring Optional Parameters

An optional parameter is declared with an equals sign and a constant value in the method signature. The default must be a compile-time constant, such as a number, a string, null, or a const field. You cannot use a non-constant expression like DateTime.Now.

public void SendNotification(string message, bool urgent = false, int retryCount = 3)
{
    // Implementation
}

Here, message is required, while urgent and retryCount are optional. Callers can invoke the method with just the message, or supply any combination of the optional arguments in order. The compiler inserts the default values at the call site when arguments are omitted.

Optional parameters must appear after all required parameters. The following is invalid and will not compile:

public void BadMethod(int a = 5, string name) // Error
{
}

The rule is straightforward: required parameters come first, then optional ones. This restriction exists because positional argument binding relies on the parameter order.

Default Values Are Compiled Into the Caller

A key detail is that the default value is not stored inside the method's body; the compiler bakes the value into the call site. When you write SendNotification("hello"), the compiled IL is effectively SendNotification("hello", false, 3). This has an important consequence: if you later change the default value in the method signature, callers must be recompiled to pick up the change. If you only redeploy the library without rebuilding the calling assembly, the old default is still used.

This behavior differs from optional parameters in some other languages where the default is resolved at runtime. In C#, the caller's code contains the value, so versioning becomes a consideration for shared libraries.

Named Arguments and Optional Parameters

Named arguments let you specify which parameter you are providing without respecting the method's positional order. This is particularly useful when you have several optional parameters and want to skip an earlier one.

SendNotification("System status changed", retryCount: 5);

In this call, urgent remains false (the default) because you did not mention it. The named argument also lets you pass a value to a later optional parameter without supplying earlier ones.

Named arguments are not restricted to optional parameters; you can use them for any method. But they become a practical tool when optional parameters are present, because the call site becomes self-documenting. Instead of SendNotification("hello", false, 5), which forces the reader to count parameters, SendNotification("hello", urgent: false, retryCount: 5) makes the intent clear.

Optional Parameters vs. Method Overloading

Optional parameters are not a replacement for overloading; they are a different tool. Overloading lets you define multiple method signatures with different parameter types or counts. Each overload can have its own body, which is useful when the behavior changes significantly based on the parameters.

public void Log(string message) => Log(message, LogLevel.Info);

public void Log(string message, LogLevel level)
{
    // Real implementation
}

With optional parameters, you can write a single method:

public void Log(string message, LogLevel level = LogLevel.Info)
{
    // Same implementation
}

Which is better depends on the situation. Optional parameters reduce code duplication when the behavior is identical; you only need one method body. Overloading gives you the freedom to execute different logic when certain arguments are supplied, and it also avoids the caller-side default-value issue because each overload is a separate method.

There is also a subtle difference in metadata. Overloads produce separate method entries in the compiled assembly, which can be resolved by reflection tools and versioned independently. An optional parameter is a single method with a default value attribute. If you use reflection to inspect the parameter, you can read the default value via ParameterInfo.DefaultValue.

Runtime Behavior and Reflection

Optional parameters are a compile-time convenience, but they also surface in reflection. When you inspect a method using MethodInfo.GetParameters(), each ParameterInfo has an IsOptional property and a DefaultValue property. This can be used to build dynamic invocation code, but you need to be careful: the default value may be DBNull.Value or Missing.Value in some edge cases, especially when the default is null or when the parameter comes from metadata written in another language.

For example, if you invoke a method dynamically using InvokeMember, you can omit optional parameters, but the binder must know their defaults. That is generally handled by the runtime, but when you use Activator.CreateInstance or reflection to call methods, you must supply a value for every parameter unless you explicitly handle the DefaultValue. The runtime does not automatically inject the default for you in all reflection scenarios; some reflection APIs require you to provide all arguments.

A practical example: when you have an optional parameter with default null, ParameterInfo.DefaultValue is null. But if the default is a value type like 0 or false, the property returns the boxed value. To invoke the method, you can pass that value directly. For a params array that is also optional, the default is null.

Ambiguous Calls and Overload Resolution

Optional parameters can create ambiguity when combined with overloads. Consider:

public void Foo(int a = 1) { }
public void Foo(int a, int b = 2) { }

A call Foo() is ambiguous because both methods could apply without any arguments. The compiler will report an error. Similarly, Foo(1) is ambiguous because the first method can take one argument, and the second can take one required argument. The compiler has no rule to prefer the one with fewer required parameters; it just sees two equally applicable candidates.

This is one reason why mixing optional parameters and overloads requires careful design. When you add an overload that shares the same name and parameter types, you can easily break existing call sites or create ambiguous calls. It is often better to give different names to methods that have distinct behavior, or to avoid overloading when optional parameters suffice.

Another subtlety: default values can affect overload resolution when nullable types are involved. A method with an optional parameter of type int? defaults to null naturally, but a method with int and a default of 0 is a different candidate. The compiler picks the best match based on the rules of overload resolution, which can be non-obvious. The safest approach is to test the specific combination in a small unit to see which method is chosen.

Maintainability and API Design

Optional parameters are easy to add to an existing method, but they are not cheap. Once a method has optional parameters, changing the order of parameters is a breaking change at the source level because callers may rely on positional arguments. Renaming a parameter is also breaking if callers use named arguments. Adding a new optional parameter is safe only if it is placed at the end; otherwise, named callers still need to be updated, and positional callers may break.

For public APIs that ship as a NuGet package, optional parameters can be a trap. Because the default value is compiled into callers, changing the default does not propagate until the consumers recompile. If the default is semantically important, consider using a constant and referencing it in the default value, so that at least the source is clear. But the runtime behavior remains the same: old callers keep the old value.

A common pattern to mitigate this is to avoid optional parameters in public API signatures and instead provide overloads that explicitly forward calls. That way, the default behavior lives in the implementation, not in the caller's compiled code. Overloads also give you the opportunity to change the default without breaking existing compiled clients.

When Optional Parameters Cause Performance Overhead

There is no meaningful runtime cost to optional parameters per se. The compiler generates the same IL as a normal method call with all arguments supplied. The only overhead is the extra arguments that are baked into the call, which are typically constants. There is no conditional branching at runtime to check whether an argument was provided; the default value is always passed.

However, there is a form of hidden overhead in binary size and JIT compilation. Every call site that uses the default needs to embed the constant, which in some cases could be a large string or a complex immutable array (though the latter is not a valid constant). For value types, the constant is inline. For null defaults, the call site includes a null reference. This is negligible in most applications.

The more important performance concern is the versioning issue already noted. If a library is updated and the caller is not recompiled, the caller may pass an outdated default. That can lead to subtle behavior changes or bugs that are hard to diagnose. In high-performance or latency-sensitive systems, such a mismatch could lead to incorrect retry counts or timeouts.

Best Practices for Using Optional Parameters

Use optional parameters when the parameters are truly optional and the behavior is uniform. Prefer named arguments in call sites when you skip optional parameters, for readability. Avoid changing the default value after the method has been published. If you are designing a public API, consider overloads instead, especially if the defaults may evolve.

Avoid combining optional parameters and ref or out because these are not allowed. The compiler will reject such a declaration. Also, params arrays cannot be optional with a non-null default; they default to null when not specified. That is often fine, but you need to handle null in the method body.

A concrete pattern that works well:

public void Configure(string name, int port = 8080, bool useTls = true)
{
    // Validate inputs
    if (port < 1 || port > 65535)
        throw new ArgumentOutOfRangeException(nameof(port));
    // ...
}

This method is clear when called with named arguments:

Configure("core", useTls: false);

Here, the port remains 8080 because you only wanted to change useTls. The named argument keeps the call readable and avoids passing a magic number for port.

In scenarios where you need to distinguish between "not provided" and "explicitly provided null", optional parameters can be limiting. An optional parameter of a reference type defaults to null, so you cannot tell if the caller omitted the argument or passed null. If that distinction matters, you need a nullable sentinel or a separate overload. For value types, you can use Nullable<T> to get three states: omitted, set to a value, or set to null. But that adds complexity and may not be worth it. The decision should be based on the actual API contract requirements.