Skip to content
Tutorials Center
My learning

Topics

C# Reference ยท Exceptions and Diagnostics

Custom exceptions

Reference for writing custom exception classes in C#: naming, constructors, extra properties, inner exceptions, hierarchies and when not to create one.

A custom exception is a class that derives from Exception (directly or through a more specific type) and describes a failure that is meaningful in your domain. It lets callers catch exactly that failure, and it can carry structured data such as an order number or a status code instead of burying it in a message string.

Create one only when callers will handle it differently from the built-in types. If the only difference is the message, throw InvalidOperationException or ArgumentException with a good message instead.

C#
public class InsufficientFundsException : Exception
{
    public InsufficientFundsException(string message) : base(message) { }
}

Try it

C# An exception with data and a cause

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# A small hierarchy

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#
public class MyException : Exception
{
    public MyException() { }
    public MyException(string message) : base(message) { }
    public MyException(string message, Exception inner) : base(message, inner) { }
}
Part Description
Name End with Exception (for example PaymentDeclinedException). The short names in the second example only keep the output compact.
Base class Exception, or a closer match such as InvalidOperationException or IOException. Never ApplicationException.
Constructors The three standard ones: none, message, message plus inner. Add more only when they carry real data.
Properties Read-only values that explain the failure. Set them in the constructor.

Errors / undefined behavior: none special. Remember that every public constructor you add becomes API.

Usage notes

  • Keep the three standard constructors so the type works with generic code, and always forward inner to the base class to keep the chain.
  • Put the data in properties, not only in the message, so handlers can react without parsing text. The message is for people.
  • Do not build deep hierarchies. One base type per library or feature (ApiError) with a few leaves is plenty. Callers can then catch the whole family or one case.
  • Make them sealed unless you really expect subclassing. A sealed leaf is easier to evolve.
  • Do not derive from ApplicationException. Guidance since .NET 1.1 is to derive from Exception or a specific built-in type.
  • Binary serialization is gone. The old [Serializable] plus SerializationInfo constructor pattern is not needed on modern .NET.
  • Do not put secrets in messages or properties: exception text ends up in logs and error pages.
  • Primary constructors (C# 12) shorten simple types, as NotFoundError shows, but remember to forward to the base constructor.
  • Prefer a result type for expected outcomes. Validation failures that happen every day are not exceptional.