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.
Debug.Assert(items.Count > 0, "The caller must check for empty lists first.");
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
[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.ThrowIfNulland exceptions for public API arguments; use asserts for internal invariants after those checks. - The compile-time symbol matters.
DEBUGis defined by the Debug configuration. Writing#define DEBUGat the very top of a file (before any code) enables it in that file, which is what the second example does. Trace.Assertis the Release-capable cousin. It is conditional onTRACE, which is defined in both configurations by default, so in a normal project it still runs in shipped code (the runner defines neither symbol, soTrace.Assertis skipped there too).- Message first. A message that says why the condition should hold is worth more than the expression text;
Debug.Assertdoes 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.Assertbecomes a failed test instead of a crash.