Skip to content
Tutorials Center
My learning

Topics

C# Reference ยท Exceptions and Diagnostics

Debug.Assert

Reference for Debug.Assert in C#: check assumptions in debug builds, how failures behave, the [Conditional] rule for release builds and when to use exceptions instead.

Debug.Assert(condition) states something that must be true if your code is correct. In a Debug build, a false condition reports a failure (by default it breaks into the debugger or stops the program). In a Release build the call is removed by the compiler: it is marked [Conditional("DEBUG")], so neither the call nor the evaluation of its arguments happens.

Assertions document internal assumptions and catch your own bugs early. They are not input validation. Anything that can go wrong because of user input, files, networks or a caller's mistake must throw an exception, since an assert disappears when you ship.

C#
Debug.Assert(items.Count > 0, "The caller must check for empty lists first.");

Try it

C# Assertions are skipped in a Release build

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# Turning assertions on and handling the failure

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#
[Conditional("DEBUG")] public static void Debug.Assert(bool condition);
[Conditional("DEBUG")] public static void Debug.Assert(bool condition, string? message);
[Conditional("DEBUG")] public static void Debug.Assert(bool condition, string? message, string? detailMessage);
[Conditional("DEBUG")] public static void Debug.Assert(bool condition,
    [InterpolatedStringHandlerArgument("condition")] ref AssertInterpolatedStringHandler message);

[Conditional("DEBUG")] public static void Debug.Fail(string? message);
[Conditional("DEBUG")] public static void Debug.Fail(string? message, string? detailMessage);
Name Description
condition The expression that should be true. Nothing happens when it is.
message Text shown when the assertion fails.
detailMessage Extra detail shown with the message.
Debug.Fail Reports a failure unconditionally, for code paths that must never run.

Returns: nothing. Errors / undefined behavior: on failure the active TraceListeners are asked to handle it via Fail. The default listener shows a message in an attached debugger (or an assert dialog in some hosts) and, without a debugger on .NET, terminates the process. You can control this with a custom listener, as above.

Usage notes

  • No side effects in the condition. Because the whole call vanishes in Release, Debug.Assert(list.RemoveAt(0) ...)-style code behaves differently between builds.
  • Not for validation. Use ArgumentNullException.ThrowIfNull and exceptions for public API arguments; use asserts for internal invariants after those checks.
  • The compile-time symbol matters. DEBUG is defined by the Debug configuration. Writing #define DEBUG at the very top of a file (before any code) enables it in that file, which is what the second example does.
  • Trace.Assert is the Release-capable cousin. It is conditional on TRACE, which is defined in both configurations by default, so in a normal project it still runs in shipped code (the runner defines neither symbol, so Trace.Assert is skipped there too).
  • Message first. A message that says why the condition should hold is worth more than the expression text; Debug.Assert does not capture the expression for you.
  • Interpolated messages are lazy (.NET 6+): the message string is only built when the assertion fails.
  • Prefer tests for behavior. Assertions do not replace unit tests; they help locate bugs while the program runs under a debugger.
  • Assertions in tests. Test runners often install a listener that throws, so a failing Debug.Assert becomes a failed test instead of a crash.