Partilhar via

Práticas recomendadas para exceções

O tratamento adequado de exceções é essencial para a confiabilidade do aplicativo. Você pode lidar intencionalmente com as exceções esperadas para evitar que seu aplicativo falhe. No entanto, um aplicativo com falha é mais confiável e diagnosticável do que um aplicativo com comportamento indefinido.

Este artigo descreve as práticas recomendadas para lidar e criar exceções.

Tratamento de exceções

As seguintes práticas recomendadas dizem respeito à forma como você lida com exceções:

Utilize estruturas try/catch/finally para recuperar de erros ou libertar recursos

Para código que pode gerar uma exceção e quando a sua aplicação puder se recuperar dessa exceção, use try/catch blocos à volta do código. Em blocos catch, sempre ordene exceções do mais específico para o menos específico. (Todas as exceções derivam da classe Exception. Mais exceções derivadas não são tratadas por uma cláusula catch precedida por uma cláusula catch para uma classe de exceção base.) Quando seu código não puder se recuperar de uma exceção, não detete essa exceção. Habilite métodos mais acima na pilha de chamadas para recuperar, se possível.

Limpe os recursos que são alocados com instruções using ou blocos finally. Prefira declarações using para limpar automaticamente os recursos quando exceções são geradas. Utilize blocos finally para limpar os recursos que não implementam IDisposable. Código em uma cláusula finally é quase sempre executado mesmo quando exceções são lançadas.

Lidar com condições comuns para evitar exceções

Para condições que provavelmente ocorrerão, mas que podem desencadear uma exceção, considere tratá-las de uma forma que evite a exceção. Por exemplo, se tentar fechar uma ligação que já está fechada, obterá um InvalidOperationException. Você pode evitar isso usando uma instrução if para verificar o estado da conexão antes de tentar fechá-la.

if (conn.State != ConnectionState.Closed)
{
    conn.Close();
}

If conn.State <> ConnectionState.Closed Then
    conn.Close()
End IF

Se não verificar o estado da conexão antes de fechar, poderá ocorrer a exceção InvalidOperationException.

try
{
    conn.Close();
}
catch (InvalidOperationException ex)
{
    Console.WriteLine(ex.GetType().FullName);
    Console.WriteLine(ex.Message);
}

Try
    conn.Close()
Catch ex As InvalidOperationException
    Console.WriteLine(ex.GetType().FullName)
    Console.WriteLine(ex.Message)
End Try

A abordagem a escolher depende da frequência com que espera que o evento ocorra.

  • Use o tratamento de exceções se o evento não ocorrer com frequência, ou seja, se o evento for realmente excecional e indicar um erro, como um fim de arquivo inesperado. Quando você usa o tratamento de exceções, menos código é executado em condições normais.

  • Verifique se há condições de erro no código se o evento acontece rotineiramente e pode ser considerado parte da execução normal. Quando você verifica condições de erro comuns, menos código é executado porque você evita exceções.

    Observação

    As verificações iniciais eliminam exceções na maioria das vezes. No entanto, pode haver condições de corrida em que a condição protegida muda entre a verificação e a operação e, nesse caso, você ainda pode incorrer em uma exceção.

Métodos de chamada Try* para evitar exceções

Se o custo de desempenho das exceções for proibitivo, alguns métodos de biblioteca .NET fornecem formas alternativas de tratamento de erros. Por exemplo, Int32.Parse lança um OverflowException se o valor a ser analisado for muito grande para ser representado por Int32. No entanto, Int32.TryParse não lança essa exceção. Em vez disso, ele retorna um Boolean e tem um parâmetro out que contém o inteiro válido analisado após o sucesso. Dictionary<TKey,TValue>.TryGetValue tem um comportamento semelhante para tentar obter um valor de um dicionário.

Cancelamento de capturas e exceções assíncronas

É melhor pegar OperationCanceledException em vez de TaskCanceledException, que deriva de OperationCanceledException, quando você chama um método assíncrono. Muitos métodos assíncronos lançam uma exceção OperationCanceledException se o cancelamento for solicitado. Essas exceções permitem que a execução seja interrompida de forma eficiente e que a pilha de chamadas seja desenrolada assim que uma solicitação de cancelamento for observada.

Os métodos assíncronos armazenam exceções que são lançadas durante a execução na tarefa que retorna. Se uma exceção for armazenada na tarefa retornada, essa exceção será lançada quando a tarefa for esperada. As exceções de uso, como ArgumentException, ainda são lançadas de forma síncrona. Para obter mais informações, consulte Exceções assíncronas.

Projete as classes de modo a evitar exceções

Uma classe pode fornecer métodos ou propriedades que permitem evitar fazer uma chamada que acionaria uma exceção. Por exemplo, a classe FileStream fornece métodos que ajudam a determinar se o final do arquivo foi atingido. Você pode chamar esses métodos para evitar a exceção lançada se você tentar ler além do final do arquivo. O exemplo a seguir mostra como ler até o final de um arquivo sem acionar uma exceção:

class FileRead
{
    public static void ReadAll(FileStream fileToRead)
    {
        ArgumentNullException.ThrowIfNull(fileToRead);

        int b;

        // Set the stream position to the beginning of the file.
        fileToRead.Seek(0, SeekOrigin.Begin);

        // Read each byte to the end of the file.
        for (int i = 0; i < fileToRead.Length; i++)
        {
            b = fileToRead.ReadByte();
            Console.Write(b.ToString());
            // Or do something else with the byte.
        }
    }
}

Class FileRead
    Public Sub ReadAll(fileToRead As FileStream)
        ' This if statement is optional
        ' as it is very unlikely that
        ' the stream would ever be null.
        If fileToRead Is Nothing Then
            Throw New System.ArgumentNullException()
        End If

        Dim b As Integer

        ' Set the stream position to the beginning of the file.
        fileToRead.Seek(0, SeekOrigin.Begin)

        ' Read each byte to the end of the file.
        For i As Integer = 0 To fileToRead.Length - 1
            b = fileToRead.ReadByte()
            Console.Write(b.ToString())
            ' Or do something else with the byte.
        Next i
    End Sub
End Class

Outra maneira de evitar exceções é retornar null (ou padrão) para os casos de erro mais comuns em vez de lançar uma exceção. Um caso de erro comum pode ser considerado um fluxo normal de controle. Ao retornar null (ou padrão) nesses casos, você minimiza o impacto no desempenho de um aplicativo.

Para tipos de valor, considere se deve usar Nullable<T> ou default como o indicador de erro para seu aplicativo. Usando Nullable<Guid>, default torna-se null em vez de Guid.Empty. Às vezes, adicionar Nullable<T> pode deixar mais claro quando um valor está presente ou ausente. Outras vezes, adicionar Nullable<T> pode criar casos extras para verificar que não são necessários e servem apenas para criar potenciais fontes de erros.

Restaurar o estado quando os métodos não são concluídos devido a exceções

Os chamadores devem ser capazes de assumir que não há efeitos colaterais quando uma exceção é lançada de um método. Por exemplo, se você tiver um código que transfere dinheiro sacando de uma conta e depositando em outra conta, e uma exceção for lançada durante a execução do depósito, você não quer que o saque permaneça em vigor.

public void TransferFunds(Account from, Account to, decimal amount)
{
    from.Withdrawal(amount);
    // If the deposit fails, the withdrawal shouldn't remain in effect.
    to.Deposit(amount);
}

Public Sub TransferFunds(from As Account, [to] As Account, amount As Decimal)
    from.Withdrawal(amount)
    ' If the deposit fails, the withdrawal shouldn't remain in effect.
    [to].Deposit(amount)
End Sub

O método anterior não lança diretamente nenhuma exceção. No entanto, você deve escrever o método para que a retirada seja revertida se a operação de depósito falhar.

Uma maneira de lidar com esta situação é interceptar quaisquer exceções lançadas pela transação de depósito e anular o levantamento.

private static void TransferFunds(Account from, Account to, decimal amount)
{
    string withdrawalTrxID = from.Withdrawal(amount);
    try
    {
        to.Deposit(amount);
    }
    catch
    {
        from.RollbackTransaction(withdrawalTrxID);
        throw;
    }
}

Private Shared Sub TransferFunds(from As Account, [to] As Account, amount As Decimal)
    Dim withdrawalTrxID As String = from.Withdrawal(amount)
    Try
        [to].Deposit(amount)
    Catch
        from.RollbackTransaction(withdrawalTrxID)
        Throw
    End Try
End Sub

Este exemplo ilustra o uso de throw para relançar a exceção original, tornando mais fácil para os chamadores verem a causa real do problema sem ter que examinar a propriedade InnerException. Uma alternativa é lançar uma nova exceção e incluir a exceção original como exceção interna.

catch (Exception ex)
{
    from.RollbackTransaction(withdrawalTrxID);
    throw new TransferFundsException("Withdrawal failed.", innerException: ex)
    {
        From = from,
        To = to,
        Amount = amount
    };
}

Catch ex As Exception
    from.RollbackTransaction(withdrawalTrxID)
    Throw New TransferFundsException("Withdrawal failed.", innerException:=ex) With
    {
        .From = from,
        .[To] = [to],
        .Amount = amount
    }
End Try

Capturar e relançar exceções corretamente

Uma vez que uma exceção é lançada, parte das informações que ela carrega é a trilha de execução. O rastreamento de pilha é uma lista da hierarquia de chamada de método que começa com o método que lança a exceção e termina com o método que captura a exceção. Se relançares uma exceção especificando-a na instrução throw, por exemplo, throw e, o rastreamento de pilha reinicia no método atual, e a lista de chamadas de método entre o método original que lançou a exceção e o método atual perde-se. Para manter as informações de rastreamento de pilha originais com a exceção, há duas opções que dependem de onde você está lançando a exceção:

  • Se você voltar a lançar a exceção de dentro do manipulador (blococatch) que capturou a instância de exceção, use a instrução throw sem especificar a exceção. A norma de análise de código CA2200 ajuda o utilizador a identificar locais no seu código onde pode inadvertidamente perder informações de rastreamento do fluxo de execução.
  • Se estiveres a relançar a exceção de outro lugar que não seja o manipulador (blococatch), usa ExceptionDispatchInfo.Capture(Exception) para capturar a exceção no manipulador e ExceptionDispatchInfo.Throw() quando quiseres relançá-la. Você pode usar a propriedade ExceptionDispatchInfo.SourceException para inspecionar a exceção capturada.

O exemplo a seguir mostra como a classe ExceptionDispatchInfo pode ser usada e como a saída pode parecer.

ExceptionDispatchInfo? edi = null;
try
{
    var txt = File.ReadAllText(@"C:\temp\file.txt");
}
catch (FileNotFoundException e)
{
    edi = ExceptionDispatchInfo.Capture(e);
}

// ...

Console.WriteLine("I was here.");

if (edi is not null)
    edi.Throw();

Se o arquivo no código de exemplo não existir, a seguinte saída será produzida:

I was here.
Unhandled exception. System.IO.FileNotFoundException: Could not find file 'C:\temp\file.txt'.
File name: 'C:\temp\file.txt'
   at Microsoft.Win32.SafeHandles.SafeFileHandle.CreateFile(String fullPath, FileMode mode, FileAccess access, FileShare share, FileOptions options)
   at Microsoft.Win32.SafeHandles.SafeFileHandle.Open(String fullPath, FileMode mode, FileAccess access, FileShare share, FileOptions options, Int64 preallocationSize, Nullable`1 unixCreateMode)
   at System.IO.Strategies.OSFileStreamStrategy..ctor(String path, FileMode mode, FileAccess access, FileShare share, FileOptions options, Int64 preallocationSize, Nullable`1 unixCreateMode)
   at System.IO.Strategies.FileStreamHelpers.ChooseStrategyCore(String path, FileMode mode, FileAccess access, FileShare share, FileOptions options, Int64 preallocationSize, Nullable`1 unixCreateMode)
   at System.IO.StreamReader.ValidateArgsAndOpenPath(String path, Encoding encoding, Int32 bufferSize)
   at System.IO.File.ReadAllText(String path, Encoding encoding)
   at Example.ProcessFile.Main() in C:\repos\ConsoleApp1\Program.cs:line 12
--- End of stack trace from previous location ---
   at Example.ProcessFile.Main() in C:\repos\ConsoleApp1\Program.cs:line 24

Lançamento de exceções

As seguintes práticas recomendadas dizem respeito à forma como você lança exceções:

Usar tipos de exceção predefinidos

Introduza uma nova classe de exceção somente quando uma predefinida não se aplicar. Por exemplo:

  • Se um conjunto de propriedades ou chamada de método não for apropriado dado o estado atual do objeto, lance uma exceção InvalidOperationException.
  • Se parâmetros inválidos forem passados, lance uma exceção ArgumentException ou uma das classes predefinidas que derivam de ArgumentException.

Observação

Embora seja melhor usar tipos de exceção predefinidos quando possível, você não deve gerar alguns tipos de exceção reservados, como AccessViolationException, IndexOutOfRangeException, NullReferenceException e StackOverflowException. Para obter mais informações, consulte CA2201: Não lance tipos de exceção reservados.

Usar métodos do construtor de exceções

É comum que uma classe lance a mesma exceção de lugares diferentes em sua implementação. Para evitar código excessivo, crie um método auxiliar que crie a exceção e a retorne. Por exemplo:

class FileReader
{
    private readonly string _fileName;

    public FileReader(string path)
    {
        _fileName = path;
    }

    public byte[] Read(int bytes)
    {
        byte[] results = FileUtils.ReadFromFile(_fileName, bytes) ?? throw NewFileIOException();
        return results;
    }

    static FileReaderException NewFileIOException()
    {
        string description = "My NewFileIOException Description";

        return new FileReaderException(description);
    }
}

Class FileReader
    Private fileName As String


    Public Sub New(path As String)
        fileName = path
    End Sub

    Public Function Read(bytes As Integer) As Byte()
        Dim results() As Byte = FileUtils.ReadFromFile(fileName, bytes)
        If results Is Nothing
            Throw NewFileIOException()
        End If
        Return results
    End Function

    Function NewFileIOException() As FileReaderException
        Dim description As String = "My NewFileIOException Description"

        Return New FileReaderException(description)
    End Function
End Class

Alguns tipos de exceção .NET importantes possuem métodos estáticos auxiliares throw que são responsáveis por alocar e lançar a exceção. Você deve chamar esses métodos em vez de construir e lançar o tipo de exceção correspondente:

Dica

As seguintes regras de análise de código podem ajudá-lo a encontrar locais em seu código onde você pode aproveitar esses auxiliares de throw estáticos: CA1510, CA1511, CA1512e CA1513.

Se estiver a implementar um método assíncrono, chame CancellationToken.ThrowIfCancellationRequested() em vez de verificar se o cancelamento tiver sido solicitado e depois construir e lançar OperationCanceledException. Para obter mais informações, consulte CA2250.

Incluir uma mensagem de cadeia de caracteres localizada

A mensagem de erro que o usuário vê é derivada da propriedade Exception.Message da exceção que foi lançada, e não do nome da classe de exceção. Normalmente, atribui-se um valor à propriedade Exception.Message passando a cadeia de caracteres da mensagem para o argumento message de um construtor Exception.

Para aplicativos localizados, você deve fornecer uma cadeia de caracteres de mensagem localizada para cada exceção que seu aplicativo pode lançar. Você usa arquivos de recursos para fornecer mensagens de erro localizadas. Para obter informações sobre como localizar aplicativos e recuperar cadeias de caracteres localizadas, consulte os seguintes artigos:

Use a gramática adequada

Escreva frases claras e inclua pontuação final. Cada frase na cadeia de caracteres atribuída à propriedade Exception.Message deve terminar em um ponto. Por exemplo, "A tabela de log transbordou." usa gramática e pontuação corretas.

Coloque bem as declarações

Coloque instruções throw onde o rastreamento da pilha será útil. O rastreamento da pilha começa na instrução em que a exceção é gerada e termina na instrução catch que a captura.

Não levante exceções em cláusulas finais

Não levante exceções em cláusulas finally. Para obter mais informações, consulte a regra de análise de código CA2219.

Não levante exceções de lugares inesperados

Alguns métodos, como métodos Equals, GetHashCodee ToString, construtores estáticos e operadores de igualdade, não devem lançar exceções. Para obter mais informações, consulte a regra de análise de código CA1065.

Lançar exceções de validação de argumento de forma síncrona

Em métodos de retorno de tarefas, você deve validar argumentos e lançar quaisquer exceções correspondentes, como ArgumentException e ArgumentNullException, antes de inserir a parte assíncrona do método. As exceções lançadas na parte assíncrona do método são armazenadas na tarefa retornada e não surgem até que, por exemplo, a tarefa seja aguardada. Para obter mais informações, consulte Exceções em métodos de retorno de tarefas.

Tipos de exceção personalizados

As seguintes práticas recomendadas dizem respeito a tipos de exceção personalizados:

Termine os nomes de classe de exceção com Exception

Quando uma exceção personalizada for necessária, nomeie-a apropriadamente e derive-a da classe Exception. Por exemplo:

public class MyFileNotFoundException : Exception
{
}

Public Class MyFileNotFoundException
    Inherits Exception
End Class

Incluir três construtores

Use pelo menos os três construtores comuns ao criar suas próprias classes de exceção: o construtor sem parâmetros, um construtor que usa uma mensagem de cadeia de caracteres e um construtor que usa uma mensagem de cadeia de caracteres e uma exceção interna.

Para obter um exemplo, consulte Como criar exceções definidas pelo usuário.

Forneça propriedades adicionais, conforme necessário

Forneça propriedades adicionais para uma exceção (além da cadeia de caracteres de mensagem personalizada) somente quando houver um cenário programático em que as informações adicionais sejam úteis. Por exemplo, o FileNotFoundException fornece a propriedade FileName.

Ver também