For a public C# library on NuGet, should `Export` grow through optional parameters or overloads, and how do you add a parameter in v2 without breaking compiled callers?
answer
- source compatible is not binary compatible
- keep the old signature
- one overload carries the defaults
- defaults freeze in callers
- options type past a few settings
basics
~20 sAppending an optional parameter keeps source compatibility but removes the old signature, so compiled callers hit MissingMethodException. Keep the v1 signature as an overload without defaults that forwards to the new method, and put defaults on one longest overload only.
solid answer
~50 sFor a published library the deciding fact is that optional parameters are resolved in the caller. Appending `bool compress = false` changes the signature from `Export(string, bool, int)` to `Export(string, bool, int, bool)`: recompiled callers are fine, already-compiled ones throw `MissingMethodException`. The fix keeps the old signature as an overload **without** defaults that forwards to the new method, and leaves defaults only on the longest overload; two overloads that both carry defaults make `Export("q3.csv")` ambiguous (CS0121) on recompilation. Defaults also freeze in callers, so I keep them to values that will never change, or use a nullable sentinel. Inside one application, where everything recompiles together, optional parameters are fine. In a public surface I prefer overloads for the common shapes and an options type once there are more than a few settings, and I let package validation catch removed signatures.
code
csharp · 14 linesConsole.WriteLine(Report.Export("q3.csv"));
Console.WriteLine(Report.Export("q3.csv", true, 8192));
Console.WriteLine(Report.Export("q3.csv", compress: true));
public static class Report
{
// v2: the one overload with optional parameters, and the longest
public static string Export(string path, bool overwrite = false, int bufferSize = 4096, bool compress = false) =>
$"4-parameter Export({path}, {overwrite}, {bufferSize}, compress: {compress})";
// v1 signature kept for callers compiled against v1; no optional parameters
public static string Export(string path, bool overwrite, int bufferSize) =>
"v1 overload -> " + Export(path, overwrite, bufferSize, compress: false);
}go deeper
Recall that adding a parameter to a public method can break programs that use the library, even when it has a default.
Explain source versus binary compatibility and why an appended optional parameter changes the method signature that compiled callers reference.
Apply the back-compat overload pattern, keep one defaults-bearing overload, and recognise CS0121 and MissingMethodException as the two failure modes.
Own the API policy: when the team uses overloads, optional parameters or options types, which defaults are permanent, and how package validation enforces it.
## Two kinds of compatibility A library on NuGet has callers it never sees. Two properties decide whether a new version is safe for them: - **Source compatibility**: code written against v1 still compiles against v2. - **Binary compatibility**: an application compiled against v1 still runs, without being rebuilt, when v2's DLL is deployed. Optional parameters are a **compile-time** feature: the compiler fills in missing arguments at each call site and emits a call to one exact signature. That makes them excellent for source compatibility and dangerous for binary compatibility. The C# versioning guide states that adding an optional parameter to an existing method is source compatible but binary breaking, and that many libraries make such a change only in a major version. A third property, **behavioural compatibility**, asks whether old binaries still do what the new version intends; a changed default fails that one silently, with no exception to notice. ## What each change does to existing callers Take v1's `Export(string path, bool overwrite = false, int bufferSize = 4096)` and an application built against it: | v2 change | Callers rebuilt against v2 | Callers compiled against v1 | |---|---|---| | Change a default value | get the new value | keep the old value silently | | Append `bool compress = false` | compile unchanged | `MissingMethodException` | | Append it and keep the v1 signature without defaults | compile unchanged | run unchanged | | Keep v1's method **with** its defaults beside the new one | CS0121 ambiguous on `Export("q3.csv")` | run unchanged | | Rename a parameter | CS1739 where callers named it | run unchanged | | Make a required parameter optional | compile unchanged | run unchanged | The third row is the pattern the C# compiler team documents for its own public API: copy the existing method, make its optional parameters required, have it call the new method, and mark it as a back-compat overload. The result has **exactly one overload with optional parameters, and it is the one with the most parameters**. Every older signature remains, with only required parameters. ## A rule set for a public surface 1. **Never remove or reshape a shipped signature** in a minor release; add an overload instead. 2. **Add new parameters at the end** of the defaults-bearing overload, never in the middle, so existing named and positional calls keep binding. 3. **Allow only one overload with optional parameters** per method group; two make the shortest calls ambiguous. 4. **Treat every default as frozen.** Use constants that will never change (`false`, `null`, `CancellationToken cancellationToken = default`), or a nullable sentinel resolved inside the method. 5. **Treat parameter names as API.** Named arguments make a rename a source-breaking change. 6. **Put a `CancellationToken` last.** Code-analysis rule CA1068 asks for it, and makes an exception when optional parameters follow a required token. ## Overloads, optional parameters or an options type There is no single right answer; it depends on who calls the API and how it will evolve. - **Overloads** are what the older .NET Framework Design Guidelines recommend over default arguments. They keep defaults inside the library, so a default can change without stranding old binaries, and they work for every .NET language. The cost is a growing method group, which becomes hard to document and to choose from. - **Optional parameters** keep the surface small and read well with named arguments. They suit internal code and applications, where every caller is rebuilt with the library, and public methods whose defaults are truly permanent. - **An options type**, such as a record `ExportOptions` with `init` properties, scales best once a method has more than a few settings. New settings become new properties, which never change the method's signature. A pragmatic lead usually combines them: a short overload for the common call, one overload taking an options object for everything else, and optional parameters only for permanent values such as a cancellation token. ## Enforcing the decision Rules on a wiki are forgotten, so make the build check them. The .NET SDK's package validation, enabled with `EnablePackageValidation` and a `PackageValidationBaselineVersion`, compares the package with the previous release and fails the pack with CP0002 when a member that existed in the baseline is missing. A public API baseline file reviewed in pull requests makes every signature change visible before it ships.
- Why not keep v1's Export with its defaults next to the new four-parameter Export with defaults?Old binaries would run, but recompiled callers break: for `Export("q3.csv")` both overloads are applicable and both omit defaults, so neither is better and the compiler reports CS0121. Keeping the old signature without defaults avoids that, because it is then applicable only when all three arguments are given.
- When are optional parameters the better choice for a C# method despite these risks?When every caller is compiled together with the method, as inside one application or solution, binary compatibility does not arise and optional parameters keep the code short. In public APIs they fit permanent defaults such as `CancellationToken cancellationToken = default` or `null`, which no future version will want to change.
- Appending an optional parameter is a non-breaking minor change for every caller.
- Old binaries will simply use the new parameter's default value.
- Keeping the old overload with its defaults beside the new one is the safest move.
- Parameter names can change freely because they are not part of the signature.