When should you create a custom exception in .NET, and how do you design one properly? Cover naming, base class, constructors, extra properties, serialisation in modern .NET, and when built-in exceptions or result types are a better choice.

1. What System.Exception contains

Custom exceptions add typed properties rather than putting structured data in Data or the message. Override Message only if you need to compute it lazily from properties.

2. Exception hierarchies: depth and catchability

Good hierarchies are shallow and organised by how callers react, not by which component threw:

Exception
 └── ExternalServiceException          (catch to degrade gracefully / circuit-break)
      ├── ExternalServiceUnavailableException   (retryable)
      └── ExternalServiceRejectedException      (not retryable)

Callers can catch the base for general handling or a specific type for specific handling. Deep, component-based hierarchies (OrderModuleException → OrderRepositoryException → ...) don't help anyone decide what to do.

A useful property on a base type: bool IsTransient or TimeSpan? RetryAfter, which a resilience policy can read.

3. Mapping exceptions to HTTP responses

In ASP.NET Core 8+:

public sealed class PaymentExceptionHandler(IProblemDetailsService problemDetails) : IExceptionHandler
{
    public async ValueTask<bool> TryHandleAsync(HttpContext ctx, Exception ex, CancellationToken ct)
    {
        if (ex is not PaymentDeclinedException declined) return false;
        ctx.Response.StatusCode = StatusCodes.Status402PaymentRequired;
        return await problemDetails.TryWriteAsync(new()
        {
            HttpContext = ctx,
            ProblemDetails =
            {
                Type = "https://errors.example.com.au/payment-declined",
                Title = "Payment declined",
                Status = 402,
                Extensions = { ["declineCode"] = declined.DeclineCode }
            },
            Exception = ex
        });
    }
}

Register with builder.Services.AddExceptionHandler<PaymentExceptionHandler>(); builder.Services.AddProblemDetails(); and app.UseExceptionHandler();. Domain exception types become a stable contract between layers; the HTTP contract is the type URI and status.

4. Result types vs exceptions: trade-offs

Many teams use both: result types inside the domain/application layer for expected outcomes, exceptions for everything unexpected, and a global handler as the safety net.

5. Serialisation history

• .NET Framework: [Serializable] + ISerializable constructor needed for remoting, AppDomains and BinaryFormatter.
• .NET Core 2.0–7: still supported for compatibility; analysers suggested adding them.
• .NET 8: Exception(SerializationInfo, StreamingContext) and GetObjectData marked obsolete (SYSLIB0051).
• .NET 9: BinaryFormatter removed from the runtime (throws PlatformNotSupportedException).

If a library still targets .NET Framework/netstandard, you may keep the serialisation constructor under #if NETFRAMEWORK. For new .NET 10 code, omit it.

6. Exceptions and logging

• Structured logging with logger.LogError(ex, "Payment {PaymentId} declined", id) records type, message, stack and inner exceptions.
• OpenTelemetry records exceptions as span events (exception.type, exception.message, exception.stacktrace), so custom exception type names become searchable dimensions — another reason for meaningful names.
• Avoid personal data (card numbers, emails, TFNs) in messages and Data; the Privacy Act and PCI DSS both apply to logs.

Try it yourself

1. Write a custom exception with typed properties, throw it with an inner exception, and inspect ToString().
2. Add an IExceptionHandler that maps it to ProblemDetails and call the endpoint.
3. Refactor one expected failure (e.g. "customer not found") from an exception to a result type and compare the calling code.
4. Enable CA1032 and CA2201 and see what they report.

// Base for all domain errors, mapped centrally to 4xx responses
public abstract class DomainException : Exception
{
    protected DomainException(string code, string message, Exception? inner = null)
        : base(message, inner) => Code = code;

    public string Code { get; }
}

public sealed class InsufficientStockException : DomainException
{
    public InsufficientStockException(string sku, int requested, int available, Exception? inner = null)
        : base("stock.insufficient",
               $"Requested {requested} of {sku} but only {available} available.", inner)
    {
        Sku = sku;
        Requested = requested;
        Available = available;
    }

    public string Sku { get; }
    public int Requested { get; }
    public int Available { get; }
}

// Standard-shape exception for a library (three constructors)
public sealed class ConfigurationLoadException : Exception
{
    public ConfigurationLoadException() { }
    public ConfigurationLoadException(string message) : base(message) { }
    public ConfigurationLoadException(string message, Exception inner) : base(message, inner) { }
}

// Expected outcome: a result instead of an exception
public readonly record struct RegisterResult(bool Succeeded, string? Error)
{
    public static RegisterResult Ok() => new(true, null);
    public static RegisterResult Fail(string error) => new(false, error);
}