throw (C#-Referenz)

Signalisiert das Auftreten einer Ausnahme während der Programmausführung.

Hinweise

Die Syntax von throw lautet:

throw [e]

Wo e eine Instanz einer Klasse ist, die von <xref:System.Exception?displayProperty=nameWithType> abgeleitet wird. Im folgenden Beispiel wird die throw-Anweisung verwendet, um eine @System.IndexOutOfRangeException auszulösen, wenn das Argument, das an eine Methode mit dem Namen GetNumber übergeben wurde, nicht auf einen gültigen Index eines internen Arrays reagiert.

using System;

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];
   }
}

Methodenaufrufer verwenden anschließend einen try-catch- oder try-catch-finally-Block, um die ausgelöste Ausnahme zu behandeln. Im folgenden Beispiel wird die Ausnahme behandelt, die von der Methode GetNumber ausgelöst wurde.

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

Erneutes Auslösen einer Ausnahme

throw kann auch in einem catch-Block verwendet werden, um eine Ausnahme erneut auszulösen, die in einem catch-Block behandelt wurde. In diesem Fall verwendet throw keinen Operanden für die Ausnahme. Es ist besonders hilfreich, wenn eine Methode ein Argument in einer aufrufenden Funktion an eine andere Bibliotheksmethode übergibt, und die Bibliotheksmethode eine Ausnahme auslöst, die an den Aufrufer übergeben werden muss. Im folgenden Beispiel wird z.B. eine @System.NullReferenceException erneut ausgelöst, die beim Versuch, das erste Zeichen einer deinitialisierten Zeichenfolge abzurufen, ausgelöst wird.

using System;

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()
Wichtig

Sie können auch die throw e-Syntax in einem catch-Block verwenden, um eine neue Ausnahme zu instanziieren, die Sie an den Aufrufer übergeben. In diesem Fall wird die Stapelüberwachung der ursprünglichen Ausnahme, die von der Eigenschaft @System.Exception.Stacktrace abrufbar ist, nicht beibehalten.

Der throw-Ausdruck

Ab C# 7 kann throw als Ausdruck sowie als Anweisung verwendet werden. Dadurch wird eine Ausnahme in Kontexten ausgelöst, die zuvor nicht unterstützt wurden. Dazu gehören:

  • Der bedingte Operator. Im folgenden Beispiel wird ein throw-Ausdruck verwendet, um eine @System.ArgumentException auszulösen, wenn eine Methode an ein leeres Zeichenfolgenarray übergeben wird. Diese Logik müsste vor C# 7 in einer if/else-Anweisung erscheinen.

    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.");                            
      
    }
    
  • Der NULL-Sammeloperator. Im folgenden Beispiel wird eine throw-Anweisung mit einem NULL-Sammeloperator verwendet, um eine Ausnahme auszulösen, wenn die Zeichenfolge, die einer Eigenschaft Name zugewiesen wurde, null ist.

    public string Name
    {
        get => name;
        set => name = value ?? 
            throw new ArgumentNullException("Name cannot be null", nameof(value));
    }   
    
  • Ein Ausdruckskörperlambda oder eine Ausdruckskörpermethode. Das folgende Beispiel veranschaulicht eine Ausdruckskörpermethode, die eine @System.InvalidCastException auslöst, da eine Konvertierung in einen @System.DateTime-Wert nicht unterstützt wird.

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

C#-Programmiersprachenspezifikation

Weitere Informationen erhalten Sie unter C#-Sprachspezifikation. Die Sprachspezifikation ist die verbindliche Quelle für die Syntax und Verwendung von C#.

Siehe auch

C#-Referenz
C#-Programmierhandbuch
try-catch
Die try-, catch- und throw-Anweisung in C++
C#-Schlüsselwörter
Ausnahmebehandlungsanweisungen
Vorgehensweise: Explizites Auslösen von Ausnahmen