Exceptions

What it is and why it exists

An exception is .NET’s typed control flow for reporting a failed operation. An exception object has at least a type and message, and it normally carries a stack trace . A wrapper can retain a lower-level cause through InnerException. The caller can use the type to decide whether to recover, translate, or keep propagating the failure.

Ordinary return values are better for expected outcomes in a method’s contract, such as “not found” or “invalid input.” Exceptions fit when the current operation can’t fulfill its contract and the current layer can’t handle that result through a normal branch. A failed file read, an operation forbidden by an object’s current state, or a violated public-parameter constraint can fall into this category.

throw transfers control from the ordinary path to a matching handler. That transfer can cross several method calls, so the discovery site doesn’t have to turn a failure immediately into a log entry, status code, or user message. Lower layers describe the technical failure; a boundary with business context decides how to present it or recover.

Exceptions aren’t a mechanism that makes every error recoverable. After catching one, the program needs a defined next step: retry an operation known to be retryable, use a valid fallback, translate the failure into a more suitable abstraction, or let it continue after cleanup. Without such an action, catching usually loses information.

How it works

The thrown value is an object

A C# throw expression must produce an object derived from System.Exception. Framework exception types describe common failure categories: use ArgumentNullException for a null argument, ArgumentOutOfRangeException for an argument outside its allowed range, and often InvalidOperationException when an object’s current state forbids an operation.

The exception type is part of the API contract. Callers select catch clauses with it, and monitoring systems group failures by it. The message explains a particular instance to a person; it isn’t a machine-readable error code. Branching on message text makes code depend on wording, locale, and changes in lower-level libraries.

An exception object can carry structured context. Standard properties include Message, StackTrace, InnerException, and Data. A custom exception may expose a stable field such as an order ID, but don’t put passwords, access tokens, or personal data in messages or properties: exceptions commonly reach logs and telemetry.

Handler selection

The runtime searches outward from the throw site along the call stack. After one try, handlers are checked in source order. A handler runs when the exception type is compatible with the declared type and its optional filter evaluates to true. Put specific types before general ones; otherwise the specific branch is unreachable, and the compiler rejects that order.

An exception filter has the form catch (SomeException error) when (condition). It narrows a handler using stable exception properties, such as a parameter name or status code. When the filter returns false, the search continues. If the filter itself throws, its exception is treated as a false result and doesn’t replace the exception whose handler is being sought.

A filter is evaluated before the stack is unwound for its corresponding catch. That lets a debugger see the original state at the throw site. It also explains why a filter shouldn’t modify business state, increment a retry counter, or perform fallible I/O. Keep it fast and free of side effects.

“Matching” in the diagram includes inheritance. ArgumentNullException is also an ArgumentException, and regular .NET exceptions ultimately derive from Exception. catch (Exception) therefore matches almost everything. It usually belongs at an application boundary, at a site that records and rethrows, or at a boundary that can genuinely translate every failure into one external result.

Stack unwinding and cleanup

After finding a handler, the runtime leaves the active scopes between the throw site and that handler, a process called stack unwinding. finally blocks on that path run, so they can release resources, restore a lock, or undo temporary state. The associated finally also runs when the try completes normally, returns, or exits because of an exception.

finally isn’t a durability guarantee. It might not run if the process is forcibly terminated, the runtime calls Environment.FailFast, or the machine loses power. Data that must survive process failure needs transactions, atomic writes, or external coordination, not hope placed in finally.

Prefer using for resources that implement IDisposable and await using for IAsyncDisposable. The compiler lowers these constructs to protected cleanup paths, which are harder to get wrong than handwritten null checks and finally blocks. A resource’s Dispose or DisposeAsync can still fail, so the cleanup method’s contract also deserves review.

Catch boundaries

A useful catch site normally knows both how to recover and what semantics the next layer should see. A repository can wrap a database-driver exception in a domain-visible data-access exception. An HTTP boundary can map known domain exceptions into responses, while a background-task boundary can record one final failure. Catching and logging the same exception in every layer only creates duplicate logs.

If the current method can’t recover, add stable context, or perform required cleanup, let the exception propagate. The absence of a throws declaration doesn’t mean a method can’t fail; C# doesn’t require checked-exception lists. Public APIs should still document the exceptions that callers can reasonably handle.

Examples

Select by type and property

The first example keeps argument validation inside the method that performs the operation. The calling boundary catches only the parameter failure it recognizes and uses a filter to confirm that quantity failed. finally records that every request has left the protected region.

For quantity 2, no exception occurs and the catch doesn’t run, but finally still does. For quantity 0, an ArgumentOutOfRangeException carries the parameter name past the ordinary path, the filter accepts it, and the same finally performs the final step.

The filter reads ParamName instead of matching Message. The parameter name is a structured property in the exception’s contract. The message primarily serves readers and can vary with the runtime locale.

Wrap an exception and retain its cause

The import layer knows which order supplied a string, but FormatException doesn’t. The next example wraps the lower-level parsing failure in OrderImportException and stores the original as an inner exception .

using System;
using System.Globalization;

try
{
    decimal total = ReadTotal("B-42", "not-a-price");
    Console.WriteLine(total);
}
catch (OrderImportException error)
{
    Console.WriteLine($"order: {error.OrderId}");
    Console.WriteLine($"failure: {error.Message}");
    Console.WriteLine($"cause: {error.InnerException?.GetType().Name}");
}

static decimal ReadTotal(string orderId, string text)
{
    try
    {
        return decimal.Parse(text, CultureInfo.InvariantCulture);
    }
    catch (FormatException error)
    {
        throw new OrderImportException(
            orderId, $"Invalid total for order {orderId}.", error);
    }
}

public sealed class OrderImportException : Exception
{
    public OrderImportException(
        string orderId, string message, Exception innerException)
        : base(message, innerException)
    {
        OrderId = orderId;
    }

    public string OrderId { get; }
}

# not executed here: the .NET SDK and C# compilers are unavailable

The custom type gives callers a stable catch target, while OrderId avoids parsing context from the message. Passing innerException to the base constructor retains the original failure type and stack, so diagnostic tools can show the complete chain of causes.

Add an exception type only when callers need to handle it differently. If an existing ArgumentException, InvalidOperationException, or IOException already states the contract accurately, a project-specific name adds cognitive cost without a useful distinction.

Let using clean up before an outer handler

Keep a resource’s scope as small as possible. The next example creates an ImportSession inside the try. When Run() fails, using calls Dispose() before the exception reaches the outer catch.

using System;

try
{
    using var session = new ImportSession();
    session.Run();
}
catch (InvalidOperationException error)
{
    Console.WriteLine($"caught: {error.Message}");
}

public sealed class ImportSession : IDisposable
{
    private bool _disposed;

    public void Run()
    {
        if (_disposed)
            throw new ObjectDisposedException(nameof(ImportSession));

        Console.WriteLine("import started");
        throw new InvalidOperationException("source rejected");
    }

    public void Dispose()
    {
        _disposed = true;
        Console.WriteLine("session disposed");
    }
}

# not executed here: the .NET SDK and C# compilers are unavailable

The session has already been released when the outer handler starts. This ordering supports a clean division of responsibility: the lower scope always owns cleanup, while the upper layer decides how to report the failure.

If Dispose() also throws, the outer layer might see the cleanup failure instead of the original failure from Run(). Keep custom disposal logic predictable, and use tests to pin down the policy when a primary failure and cleanup failure occur together.

Observe several concurrent failures

await rethrows a task’s recorded failure at the await point. A combined task returned by Task.WhenAll stores the exceptions from all input tasks. Directly awaiting it throws only one of them, so code that needs complete diagnostics must also inspect the combined task’s Exception.InnerExceptions.

using System;
using System.IO;
using System.Threading.Tasks;

Task inventory = Task.FromException(
    new InvalidOperationException("inventory unavailable"));
Task invoice = Task.FromException(
    new IOException("invoice store unavailable"));

Task all = Task.WhenAll(inventory, invoice);

try
{
    await all;
}
catch (Exception error)
{
    Console.WriteLine($"await observed: {error.GetType().Name}");

    foreach (Exception failure in all.Exception!.InnerExceptions)
    {
        Console.WriteLine(
            $"stored: {failure.GetType().Name}: {failure.Message}");
    }
}

# not executed here: the .NET SDK and C# compilers are unavailable

The example saves all so the catch can inspect that same combined task. Writing await Task.WhenAll(...) directly still lets you catch one exception, but it leaves no variable from which to read the combined task’s properties.

Production code shouldn’t depend on which failure await chooses to throw. Keep the input tasks and inspect their states when each result matters. If you report a set of failures, define its ordering, deduplication, and external representation.

Pitfalls

Swallowing an unknown exception

Fix: Catch only specific types from which this layer can recover. An outer application boundary can catch Exception to record a final failure or translate it into a protocol response, but it should end that unit of work after fulfilling the boundary’s responsibility instead of continuing with possibly corrupted state.

Using exceptions for expected branches

Fix: Use explicit APIs such as TryParse and TryGetValue for common failures, and return the states the caller must distinguish. Absence and malformed input should throw only when the method contract says that a value must exist or be valid.

Rethrowing with throw ex

Fix: Write throw; to propagate the current exception unchanged. To change abstraction, throw a new exception with innerException. To resume propagation elsewhere after leaving the current catch, use ExceptionDispatchInfo.Capture(error).Throw().

Replacing the original failure during cleanup

Fix: Prefer tested resource types and using. Custom cleanup needs an explicit policy for primary and secondary failures: record a cleanup failure this layer can handle, or use a deliberate aggregate result or exception type when both must reach the caller. Don’t let incidental replacement define the policy.

Logging cancellation as a system error

Fix: Define cancellation separately. For expected cancellation of the same unit of work, usually let OperationCanceledException reach the task scheduler boundary. If only timeouts are handled, distinguish timeout from caller cancellation using stable conditions and preserve token semantics.

Further reading

• Exception-handling statements - C# reference
• Best practices for exceptions
• How to create user-defined exceptions
• System.Exception API
• ExceptionDispatchInfo API
• Task.WhenAll API