Skip to content
Tutorials Center
My learning

Topics

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.

C#
void Save(string name, int count)
{
    ArgumentException.ThrowIfNullOrWhiteSpace(name);
    ArgumentOutOfRangeException.ThrowIfNegative(count);
}

Try it

C# Guards at the top of a method

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.

C# Messages and ObjectDisposedException

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

C#
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. ThrowIfNull arrived in .NET 6; ThrowIfNullOrEmpty in .NET 7; ThrowIfNullOrWhiteSpace and the ArgumentOutOfRangeException relational family in .NET 8.
  • Nullable flow analysis understands them. After ThrowIfNull(x), the compiler treats x as 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 null string 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, TimeSpan and any other IComparable<T>.
  • Own helpers. Wrap repeated checks in a method with [DoesNotReturn] and a separate throw helper to keep callers small.