C# Reference ยท Exceptions and Diagnostics
ThrowIfNull and the throw helpers
Reference for C# guard clauses: ArgumentNullException.ThrowIfNull, ThrowIfNullOrEmpty, ArgumentOutOfRangeException.ThrowIfNegative and ObjectDisposedException.ThrowIf.
The throw helpers are static methods that check a condition and throw the matching exception in one line. They replace the repetitive if (x is null) throw new ArgumentNullException(nameof(x)); blocks at the top of methods. The most common is ArgumentNullException.ThrowIfNull(value), available since .NET 6; the family grew in .NET 7 and 8.
Each helper uses [CallerArgumentExpression] to find the name of the argument automatically, so the exception reports the right parameter name without nameof. The throwing code lives in a separate method, which keeps the guarded method small and lets the JIT inline it.
void Save(string name, int count) { ArgumentException.ThrowIfNullOrWhiteSpace(name); ArgumentOutOfRangeException.ThrowIfNegative(count); }
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Syntax
ArgumentNullException.ThrowIfNull(object? argument, string? paramName = null); ArgumentException.ThrowIfNullOrEmpty(string? argument, string? paramName = null); ArgumentException.ThrowIfNullOrWhiteSpace(string? argument, string? paramName = null); ArgumentOutOfRangeException.ThrowIfNegative<T>(T value, string? paramName = null); ArgumentOutOfRangeException.ThrowIfNegativeOrZero<T>(T value, string? paramName = null); ArgumentOutOfRangeException.ThrowIfZero<T>(T value, string? paramName = null); ArgumentOutOfRangeException.ThrowIfGreaterThan<T>(T value, T other, string? paramName = null); ArgumentOutOfRangeException.ThrowIfGreaterThanOrEqual<T>(T value, T other, string? paramName = null); ArgumentOutOfRangeException.ThrowIfLessThan<T>(T value, T other, string? paramName = null); ArgumentOutOfRangeException.ThrowIfLessThanOrEqual<T>(T value, T other, string? paramName = null); ArgumentOutOfRangeException.ThrowIfEqual<T>(T value, T other, string? paramName = null); ArgumentOutOfRangeException.ThrowIfNotEqual<T>(T value, T other, string? paramName = null); ObjectDisposedException.ThrowIf(bool condition, object instance); ObjectDisposedException.ThrowIf(bool condition, Type type);
| Name | Description |
|---|---|
argument, value |
The value to test. |
other |
The comparison value for the relational helpers. T must implement IComparable<T>. |
paramName |
Filled in automatically from the caller's expression; pass it only for a different name. |
condition |
For ObjectDisposedException.ThrowIf: true means the object is disposed. |
Errors: ArgumentNullException for null (ThrowIfNullOrEmpty and ThrowIfNullOrWhiteSpace throw it for null, and plain ArgumentException for empty or blank text). ArgumentOutOfRangeException for range checks. ObjectDisposedException for disposed instances.
Usage notes
- Version availability.
ThrowIfNullarrived in .NET 6;ThrowIfNullOrEmptyin .NET 7;ThrowIfNullOrWhiteSpaceand theArgumentOutOfRangeExceptionrelational family in .NET 8. - Nullable flow analysis understands them. After
ThrowIfNull(x), the compiler treatsxas non-null, so no warning follows. - They guard arguments, not state. A wrong object state is
InvalidOperationException; there is no helper for it. - Do not guard private details twice. Check public entry points; internal helpers can rely on their callers.
- Keep the order sensible. Null checks first, then ranges. A check on a
nullstring would otherwise throw something less helpful. - Messages are framework text. The exact wording comes from runtime resources (English with the invariant culture), so assert on the exception type and
ParamName, not on the message. - Primary constructors. Parameters are not guarded automatically; call a helper in a field initializer, for example
private readonly Foo _foo = Check(foo);, or use?? throw. - Generic math types work. The relational helpers accept
int,long,double,decimal,TimeSpanand any otherIComparable<T>. - Own helpers. Wrap repeated checks in a method with
[DoesNotReturn]and a separatethrowhelper to keep callers small.