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.
public class InsufficientFundsException : Exception { public InsufficientFundsException(string message) : base(message) { } }
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
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
innerto 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
sealedunless you really expect subclassing. A sealed leaf is easier to evolve. - Do not derive from
ApplicationException. Guidance since .NET 1.1 is to derive fromExceptionor a specific built-in type. - Binary serialization is gone. The old
[Serializable]plusSerializationInfoconstructor 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
NotFoundErrorshows, but remember to forward to the base constructor. - Prefer a result type for expected outcomes. Validation failures that happen every day are not exceptional.