Compartilhar via

Práticas recomendadas para exceções

O tratamento adequado de exceções é essencial para a confiabilidade do aplicativo. Você pode manipular intencionalmente 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 à maneira como você lida com exceções:

Usar blocos try/catch/finally para se recuperar de erros ou liberar recursos

Para o código que pode potencialmente gerar uma exceção e quando a sua aplicação puder se recuperar dessa exceção, use blocos try/catch ao redor do código. Em catch blocos, sempre ordene exceções das mais derivadas para as menos derivadas. (Todas as exceções derivam da classe Exception. Exceções mais específicas não são cobertas por uma cláusula catch que é precedida por uma cláusula catch para uma classe de exceção base.) Se o seu código não conseguir se recuperar de uma exceção, não capture essa exceção. Habilite métodos adicionais na pilha de chamadas para se recuperar se possível.

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

Gerenciar condições comuns para evitar exceções

Para condições que provavelmente ocorrerão, mas podem disparar uma exceção, considere tratá-las de uma maneira que evite a exceção. Por exemplo, se você tentar fechar uma conexão já fechada, obterá uma 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 você não verificar o estado da conexão antes de fechar, você poderá capturar 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 ser escolhida depende da frequência com que você espera que o evento ocorra.

  • Use o tratamento de exceção se o evento não ocorrer com frequência, ou seja, se o evento for realmente excepcional 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 se há condições de erro comuns, menos código é executado porque você evita exceções.

    Observação

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

Chamar métodos Try* para evitar exceções

Se o custo de desempenho das exceções for proibitivo, alguns métodos de biblioteca do .NET fornecerão formas alternativas de tratamento de erros. Por exemplo, Int32.Parse gera um OverflowException se o valor a ser parseado for muito grande para ser representado por Int32. No entanto, Int32.TryParse não gera essa exceção. Em vez disso, ele retorna um booliano 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.

Capturar cancelamento e exceções assíncronas

É melhor capturar OperationCanceledException em vez de TaskCanceledException, que deriva de OperationCanceledException, quando você chama um método assíncrono. Muitos métodos assíncronos geram uma exceção OperationCanceledException se o cancelamento for solicitado. Essas exceções permitem que a execução seja interrompida com eficiência e a pilha de chamadas seja desenrolada quando uma solicitação de cancelamento for detectada.

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

Projete as classes de forma que exceções sejam evitadas

Uma classe pode fornecer métodos ou propriedades que permitem que você evite fazer uma chamada que dispare uma exceção. Por exemplo, a FileStream classe 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 que ocorre se você tentar ler além do final do arquivo. O exemplo a seguir mostra como ler até o final de um arquivo sem disparar 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 a maioria dos casos de erro comuns em vez de gerar 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 para um aplicativo.

Para tipos de valor, considere se deve ser usado Nullable<T> ou default como o indicador de erro para seu aplicativo. Ao usar 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 se não são necessários e servir apenas para criar possíveis fontes de erros.

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

Os chamadores devem ser capazes de pressupor que não haverá efeitos colaterais quando uma exceção for gerada de um método. Por exemplo, se você tiver um código que transfere dinheiro retirando 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 deseja 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 gera diretamente exceções. 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 essa situação é capturar todas as exceções geradas pela transação do depósito e reverter a retirada.

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 precisar 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

Quando uma exceção é lançada, parte das informações que ela carrega consistem no rastreamento de pilha. O rastreamento de pilha é uma lista da hierarquia de chamadas de método que começa com o método que lança a exceção e termina com o método que a captura. Se uma exceção for lançada novamente pela especificação da exceção na instrução throw, por exemplo, throw e, o rastreamento de pilha será reiniciado 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 será perdida. Para manter as informações de rastreamento de pilha originais com a exceção, há duas opções que dependem da origem de onde você está relançando a exceção:

  • Se você relançar a exceção de dentro do manipulador (bloco catch) que capturou a instância da exceção, use a instrução throw sem especificar a exceção. A regra de análise de código CA2200 ajuda você a encontrar locais em seu código em que você pode perder inadvertidamente as informações de rastreamento de pilha.
  • Se você estiver lançando novamente a exceção de algum lugar diferente do manipulador (bloco catch), use ExceptionDispatchInfo.Capture(Exception) para capturar a exceção no manipulador e ExceptionDispatchInfo.Throw() quando quiser lançar novamente. Você pode usar a ExceptionDispatchInfo.SourceException propriedade para inspecionar a exceção capturada.

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

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çando exceções

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

Usar tipos de exceção predefinidos

Introduza uma nova classe de exceção somente quando uma predefinida não for aplicável. Por exemplo:

  • Se uma chamada de método ou conjunto de propriedades não for apropriada dado o estado atual do objeto, gere uma exceção InvalidOperationException .
  • Se forem passados parâmetros inválidos, 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, IndexOutOfRangeExceptionNullReferenceException e StackOverflowException. Para obter mais informações, consulte CA2201: Não gerar tipos de exceção reservados.

Usar métodos para criação de exceções

É comum que uma classe gere a mesma exceção a partir de diferentes locais 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 dos principais tipos de exceção do .NET têm métodos auxiliares estáticos throw que alocam e geram 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 em que você pode aproveitar esses auxiliares estáticos throw : CA1510, CA1511, CA1512 e CA1513.

Se você estiver implementando um método assíncrono, chame CancellationToken.ThrowIfCancellationRequested() em vez de verificar se o cancelamento foi solicitado e, em seguida, 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 Exception.Message propriedade da exceção que foi gerada e não do nome da classe de exceção. Normalmente, você atribui um valor à Exception.Message propriedade passando a cadeia de caracteres de mensagem para o message argumento de um construtor de exceção.

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

Usar gramática adequada

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

Posicionar instruções throw corretamente

Coloque instruções de lançamento em que o rastreamento de pilha seja útil. O rastreamento de pilha começa na instrução na qual a exceção é lançada e termina na instrução catch que captura a exceção.

Não gerar exceções em cláusulas finally

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

Não gerar exceções de lugares inesperados

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

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

Em métodos de retorno de tarefa, você deve validar argumentos e gerar exceções correspondentes, como ArgumentException e ArgumentNullException, antes de inserir a parte assíncrona do método. As exceções geradas em uma 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 tarefa.

Tipos de exceção personalizados

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

Terminar os nomes das classes de exceção com Exception

Quando uma exceção personalizada for necessária, nomeie-a adequadamente e derive-a da Exception classe. 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.

Fornecer mais propriedades conforme necessário

Forneça mais propriedades 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, a FileNotFoundException fornece a propriedade FileName.

Consulte também

  • Last updated on