lançamento (Referência C#)

Sinaliza a ocorrência de uma exceção durante a execução do programa.

Observações

A sintaxe de throw :

throw [e];

onde e é um exemplo de uma classe derivada de System.Exception. O exemplo a seguir utiliza a throw declaração para lançar um IndexOutOfRangeException se o argumento passado para um método nomeado GetNumber não corresponder a um índice válido de uma matriz interna.

using System;

namespace Throw2
{
public class NumberGenerator
{
   int[] numbers = { 2, 4, 6, 8, 10, 12, 14, 16, 18, 20 };

   public int GetNumber(int index)
   {
      if (index < 0 || index >= numbers.Length)
      {
         throw new IndexOutOfRangeException();
      }
      return numbers[index];
   }
}

Os chamadores de métodos então usam um try-catch ou try-catch-finally bloco para lidar com a exceção lançada. O exemplo a seguir lida com a exceção lançada pelo GetNumber método.

using System;

public class Example
{
   public static void Main()
   {
      var gen = new NumberGenerator();
      int index = 10;
      try
      {
          int value = gen.GetNumber(index);
          Console.WriteLine($"Retrieved {value}");
      }
      catch (IndexOutOfRangeException e)
      {
         Console.WriteLine($"{e.GetType().Name}: {index} is outside the bounds of the array");
      }
   }
}
// The example displays the following output:
//        IndexOutOfRangeException: 10 is outside the bounds of the array

Relançar uma exceção

throw também pode ser usado num catch bloco para relançar uma exceção manuseada num catch bloco. Neste caso, throw não se deve a uma exceção. É mais útil quando um método passa um argumento de um chamador para outro método de biblioteca, e o método da biblioteca lança uma exceção que deve ser transmitida ao chamador. Por exemplo, o exemplo seguinte relança um NullReferenceException que é lançado quando se tenta recuperar o primeiro carácter de uma corda não iniializada.

using System;

namespace Throw
{
public class Sentence
{
   public Sentence(string s)
   {
      Value = s;
   }

   public string Value { get; set; }

   public char GetFirstCharacter()
   {
      try
      {
         return Value[0];
      }
      catch (NullReferenceException e)
      {
         throw;
      }
   }
}

public class Example
{
   public static void Main()
   {
      var s = new Sentence(null);
      Console.WriteLine($"The first character is {s.GetFirstCharacter()}");
   }
}
// The example displays the following output:
//    Unhandled Exception: System.NullReferenceException: Object reference not set to an instance of an object.
//       at Sentence.GetFirstCharacter()
//       at Example.Main()

Importante

Também pode utilizar a throw e sintaxe num catch bloco para instantanear uma nova exceção que transmite ao ouvinte. Neste caso, o traço de pilha da exceção original, que está disponível a StackTrace partir da propriedade, não é preservado.

A throw expressão

A partir de C# 7.0, throw pode ser usado como expressão, bem como como uma declaração. Isto permite que uma exceção seja lançada em contextos que anteriormente não eram apoiados. Incluem-se:

  • o operador condicional. O exemplo a seguir usa uma throw expressão para lançar um ArgumentException método se um método é passado uma matriz de corda vazia. Antes de C# 7.0, esta lógica teria de aparecer em comunicado if/else .

    private static void DisplayFirstNumber(string[] args)
    {
       string arg = args.Length >= 1 ? args[0] :
                                  throw new ArgumentException("You must supply an argument");
       if (Int64.TryParse(arg, out var number))
          Console.WriteLine($"You entered {number:F0}");
       else
          Console.WriteLine($"{arg} is not a number.");
    }
    
  • o operador de nulo. No exemplo seguinte, é utilizada uma throw expressão com um operador de nulo para lançar uma exceção se a cadeia atribuída a uma Name propriedade for null.

    public string Name
    {
        get => name;
        set => name = value ??
            throw new ArgumentNullException(paramName: nameof(value), message: "Name cannot be null");
    }
    
  • um lambda ou método de expressão encorpado. O exemplo a seguir ilustra um método de expressão encorpado que lança um InvalidCastException porque uma conversão para um DateTime valor não é suportada.

    DateTime ToDateTime(IFormatProvider provider) =>
             throw new InvalidCastException("Conversion to a DateTime is not supported.");
    

Especificação linguística C#

Para mais informações, consulte a Especificação de Idioma C. A especificação linguística é a fonte definitiva para a sintaxe e utilização C#.

Ver também