Lançar exceções em C#: guard clauses, throw expressions e exceções próprias

Capturar exceções é metade do tratamento de erros; a outra metade é lançar a exceção certa. Uma exceção bem escolhida diz a quem chama exatamente o que deu errado e se foi erro de quem chamou ou do estado do programa. Esta página cobre o lado do lançamento; try catch cobre o tratamento.

A instrução throw e as guard clauses

throw recebe um objeto de exceção. A execução do método para ali, e a exceção procura um tratador subindo pela pilha de chamadas. O uso mais comum é uma guard clause: verificações no topo de um método que rejeitam entradas inválidas antes de qualquer trabalho ser feito.

using System;

class Account
{
    public decimal Balance { get; private set; }
    public bool Frozen { get; set; }

    public void Withdraw(decimal amount)
    {
        if (amount <= 0)
            throw new ArgumentOutOfRangeException(nameof(amount), "Amount must be positive.");
        if (Frozen)
            throw new InvalidOperationException("The account is frozen.");
        if (amount > Balance)
            throw new InvalidOperationException("Insufficient funds.");

        Balance -= amount;
    }

    public void Deposit(decimal amount)
    {
        if (amount <= 0)
            throw new ArgumentOutOfRangeException(nameof(amount), "Amount must be positive.");
        Balance += amount;
    }
}

class Program
{
    static void Main()
    {
        var acct = new Account();
        acct.Deposit(100m);

        try
        {
            acct.Withdraw(-5m);
        }
        catch (ArgumentOutOfRangeException e)
        {
            Console.WriteLine(e.GetType().Name + " for parameter '" + e.ParamName + "'");
        }

        acct.Frozen = true;
        try
        {
            acct.Withdraw(20m);
        }
        catch (InvalidOperationException e)
        {
            Console.WriteLine(e.GetType().Name + ": " + e.Message);
        }

        Console.WriteLine("Balance: " + acct.Balance);
    }
}

Saída:

ArgumentOutOfRangeException for parameter 'amount'
InvalidOperationException: The account is frozen.
Balance: 100

nameof(amount) produz a string "amount" e continua correto se o parâmetro for renomeado. As exceções de argumento a guardam em ParamName, que ferramentas e logs usam para apontar o argumento inválido.

Guard clauses mantêm o resto do método simples: depois das verificações, o código pode supor que a entrada é válida. Elas também falham no ponto do erro, em vez de deixar um valor inválido seguir adiante e causar uma NullReferenceException confusa três métodos depois.

Qual tipo de exceção lançar

Reutilize um tipo embutido quando ele descreve a situação; quem chama já sabe tratá-lo.

A linha entre as três primeiras linhas e InvalidOperationException é quem precisa mudar alguma coisa. Uma exceção de argumento diz "chame isto de outro jeito". InvalidOperationException diz "a chamada estava certa, mas não agora".

Não lance Exception, SystemException nem ApplicationException diretamente: quem chama não consegue capturá-las sem capturar também todo o resto. Também não lance você mesmo NullReferenceException, IndexOutOfRangeException nem StackOverflowException; o runtime as reserva para bugs de verdade.

Throw expressions

Antes do C# 7, throw era só uma instrução. Desde o C# 7, ele também pode aparecer como expressão em três lugares, o que transforma verificações comuns em uma linha:

using System;

class Customer
{
    private readonly string name;
    private readonly string email;

    public Customer(string name, string email)
    {
        this.name = name ?? throw new ArgumentNullException(nameof(name));       // after ??
        this.email = email.Contains("@")
            ? email
            : throw new ArgumentException("Not an email address.", nameof(email)); // in ?:
    }

    public string Name => name;

    public string Nickname => throw new NotImplementedException();                // expression body

    public override string ToString() => name + " <" + email + ">";
}

class Program
{
    static void Main()
    {
        Console.WriteLine(new Customer("Ana", "ana@example.com"));

        try
        {
            new Customer(null, "x@example.com");
        }
        catch (ArgumentNullException e)
        {
            Console.WriteLine("Null: " + e.ParamName);
        }

        try
        {
            new Customer("Ben", "ben.example.com");
        }
        catch (ArgumentException e)
        {
            Console.WriteLine(e.GetType().Name + ": " + e.ParamName);
        }
    }
}

Saída:

Ana <ana@example.com>
Null: name
ArgumentException: email

Repare que ArgumentNullException deriva de ArgumentException, então um catch (ArgumentException) colocado primeiro também capturaria o caso de null. A ordem das cláusulas catch importa pelo mesmo motivo quando você trata as duas.

ThrowIfNull e parecidos (.NET 6 em diante)

O .NET moderno adiciona auxiliares static que escrevem a verificação e o lançamento para você, com o nome do parâmetro capturado automaticamente:

public void Ship(Order order, int quantity, string address)
{
    ArgumentNullException.ThrowIfNull(order);                   // .NET 6
    ArgumentOutOfRangeException.ThrowIfNegativeOrZero(quantity); // .NET 8
    ArgumentException.ThrowIfNullOrWhiteSpace(address);          // .NET 8
    ObjectDisposedException.ThrowIf(disposed, this);             // .NET 7

    // ...
}

Eles se comportam igual ao if com throw escrito à mão, e mantêm cada guard clause em uma linha. Em plataformas mais antigas, escreva a forma com if mostrada antes.

Escrevendo uma classe de exceção própria

Crie seu próprio tipo de exceção quando quem chama precisa capturar essa falha específica separadamente, ou quando o tratador precisa de dados que uma string de mensagem não carrega bem.

using System;

class InsufficientFundsException : Exception
{
    public decimal Balance { get; }
    public decimal Requested { get; }

    public InsufficientFundsException() { }

    public InsufficientFundsException(string message) : base(message) { }

    public InsufficientFundsException(string message, Exception inner) : base(message, inner) { }

    public InsufficientFundsException(decimal balance, decimal requested)
        : base("Cannot withdraw " + requested + " from a balance of " + balance + ".")
    {
        Balance = balance;
        Requested = requested;
    }
}

class Program
{
    static decimal balance = 40m;

    static void Withdraw(decimal amount)
    {
        if (amount > balance) throw new InsufficientFundsException(balance, amount);
        balance -= amount;
    }

    static void Main()
    {
        try
        {
            Withdraw(25m);
            Withdraw(25m);
        }
        catch (InsufficientFundsException e)
        {
            Console.WriteLine(e.Message);
            Console.WriteLine("Short by " + (e.Requested - e.Balance));
        }
    }
}

Saída:

Cannot withdraw 25 from a balance of 15.
Short by 10

As convenções:

• O nome termina em Exception.
• Ela deriva de Exception (ou de um tipo embutido mais específico quando é um caso especial dele, como InvalidOperationException).
• Ela tem os três construtores padrão: sem argumentos, com mensagem e com mensagem mais inner exception. Adicione seus próprios construtores por cima.
• Dados extras vão em propriedades somente leitura, definidas no construtor. Um tratador pode então agir sobre e.Requested em vez de interpretar a mensagem.

Envolvendo com uma inner exception

Quando uma falha de baixo nível deve aparecer como uma de nível mais alto, envolva-a. A original fica guardada como InnerException, então nenhuma informação se perde:

using System;

class ConfigException : Exception
{
    public ConfigException(string message, Exception inner) : base(message, inner) { }
}

class Program
{
    static int ReadPort(string text)
    {
        try
        {
            return int.Parse(text);
        }
        catch (FormatException e)
        {
            throw new ConfigException("Setting 'port' must be a number, got '" + text + "'.", e);
        }
    }

    static void Main()
    {
        try
        {
            ReadPort("80a");
        }
        catch (ConfigException e)
        {
            Console.WriteLine(e.Message);
            Console.WriteLine("Caused by: " + e.InnerException.GetType().Name);
        }
    }
}

Saída:

Setting 'port' must be a number, got '80a'.
Caused by: FormatException

Quem chama agora lida com termos de configuração, que entende, e registrar e.ToString() imprime a cadeia inteira, incluindo a FormatException e o stack trace dela. Só envolva quando você acrescenta significado; envolver toda exceção em uma MyAppException genérica só obriga os tratadores a cavar pela InnerException.

Lançar versus retornar um resultado

Exceções são para falhas que quem chama não espera na operação normal. Para resultados rotineiros, como uma consulta que muitas vezes não encontra nada ou uma entrada de usuário que muitas vezes é inválida, a convenção do .NET é o padrão Try: retornar bool e devolver o valor por um parâmetro out.

public bool TryWithdraw(decimal amount, out string error)
{
    if (amount > Balance) { error = "Insufficient funds."; return false; }
    Balance -= amount;
    error = null;
    return true;
}

Muitos tipos oferecem os dois: int.Parse lança exceção, int.TryParse retorna false; dict[key] lança exceção, dict.TryGetValue retorna false. Lançar uma exceção custa muito mais que retornar um valor, então isso não deve ficar em um caminho que executa milhares de vezes por segundo. Veja ref e out sobre parâmetros out.

Escrevendo boas mensagens

A mensagem de uma exceção é lida por um desenvolvedor olhando um log. Faça-a dizer o que estava errado e, quando for seguro, o valor problemático: "Quantity must be between 1 and 99, got 0." é melhor que "Invalid input.". Escreva frases completas e mantenha segredos como senhas e tokens fora das mensagens, já que elas acabam em arquivos de log.

Erros comuns

• Lançar a própria Exception. Quem chama não consegue capturá-la de forma seletiva; use um tipo específico.
• Passar a mensagem no lugar do nome do parâmetro. new ArgumentNullException("name") recebe o nome do parâmetro; a mensagem vem em segundo lugar.
• Nomes de parâmetro escritos à mão. Use nameof(param) para que renomeações os mantenham corretos.
• Exceções próprias sem significado extra. Se um tipo embutido serve, use-o.
• Perder o erro original ao envolver. Sempre o passe como inner exception.