Erstellen und Auslösen von Ausnahmen (C#-Programmierhandbuch)Creating and Throwing Exceptions (C# Programming Guide)

Ausnahmen werden verwendet, um anzugeben, dass während der Ausführung des Programms ein Fehler aufgetreten ist.Exceptions are used to indicate that an error has occurred while running the program. Ausnahmeobjekte, die einen Fehler beschreiben, werden erstellt und dann mit dem Schlüsselwort throw (auslösen) ausgelöst.Exception objects that describe an error are created and then thrown with the throw keyword. Die Laufzeit sucht dann nach dem kompatibelsten Ausnahmehandler.The runtime then searches for the most compatible exception handler.

Programmierer sollten Ausnahmen auslösen, wenn eine oder mehrere der folgenden Bedingungen wahr sind:Programmers should throw exceptions when one or more of the following conditions are true:

  • Die Methode kann deren definierte Funktionalität nicht abschließen.The method cannot complete its defined functionality.

    Wenn beispielsweise ein Parameter einer Methode einen ungültigen Wert hat:For example, if a parameter to a method has an invalid value:

    static void CopyObject(SampleClass original)
    {
        if (original == null)
        {
            throw new System.ArgumentException("Parameter cannot be null", "original");
        }
    
    }
    
  • Ein unpassender Aufruf eines Objekts erfolgt, basierend auf dem Objektzustand.An inappropriate call to an object is made, based on the object state.

    Ein Beispiel wäre ein Versuch, in eine schreibgeschützte Datei zu schreiben.One example might be trying to write to a read-only file. Lösen Sie in Fällen, in denen ein Objektzustand keinen Vorgang erlaubt, eine Instanz von InvalidOperationException oder ein Objekt aus, das auf einer Ableitung dieser Klasse basiert.In cases where an object state does not allow an operation, throw an instance of InvalidOperationException or an object based on a derivation of this class. Dies ist ein Beispiel für eine Methode, die eine InvalidOperationException auslöst:This is an example of a method that throws an InvalidOperationException object:

    class ProgramLog
    {
        System.IO.FileStream logFile = null;
        void OpenLog(System.IO.FileInfo fileName, System.IO.FileMode mode) {}
    
        void WriteLog()
        {
            if (!this.logFile.CanWrite)
            {
                throw new System.InvalidOperationException("Logfile cannot be read-only");
            }
            // Else write data to the log and return.
        }
    }
    
  • Wenn ein Argument an eine Methode eine Ausnahme auslöst.When an argument to a method causes an exception.

    In diesem Fall muss die ursprüngliche Ausnahme abgefangen und eine ArgumentException-Instanz erstellt werden.In this case, the original exception should be caught and an ArgumentException instance should be created. Die ursprüngliche Ausnahme sollte an den Konstruktor der ArgumentException als InnerException-Parameter übergeben werden:The original exception should be passed to the constructor of the ArgumentException as the InnerException parameter:

    static int GetValueFromArray(int[] array, int index)
    {
        try
        {
            return array[index];
        }
        catch (System.IndexOutOfRangeException ex)
        {
            System.ArgumentException argEx = new System.ArgumentException("Index is out of range", "index", ex);
            throw argEx;
        }
    }
    

Ausnahmen enthalten eine Eigenschaft mit dem Namen StackTrace.Exceptions contain a property named StackTrace. Diese Zeichenfolge enthält den Namen der Methoden für die aktuelle Aufrufliste, zusammen mit dem Dateinamen und der Zeilennummer, in der die Ausnahme für jede Methode ausgelöst wurde.This string contains the name of the methods on the current call stack, together with the file name and line number where the exception was thrown for each method. Ein StackTrace-Objekt wird automatisch von der Common Language Runtime (CLR) ab der throw-Anweisung erstellt, sodass Ausnahmen ab dem Punkt ausgelöst werden müssen, an dem die Stapelüberwachung beginnen soll.A StackTrace object is created automatically by the common language runtime (CLR) from the point of the throw statement, so that exceptions must be thrown from the point where the stack trace should begin.

Alle Ausnahmen enthalten eine Eigenschaft mit dem Namen Message.All exceptions contain a property named Message. Diese Zeichenfolge sollte festgelegt werden, um die Gründe für die Ausnahme zu erklären.This string should be set to explain the reason for the exception. Beachten Sie, dass vertrauliche Informationen aus Sicherheitsgründen nicht im E-Mail-Text eingefügt werden dürfen.Note that information that is sensitive to security should not be put in the message text. Zusätzlich zu Message enthält ArgumentException eine Eigenschaft mit dem Namen ParamName, die auf den Namen des Arguments festgelegt werden sollte, das die Ausnahme ausgelöst hat.In addition to Message, ArgumentException contains a property named ParamName that should be set to the name of the argument that caused the exception to be thrown. Im Falle eines Eigenschaftensetters sollte ParamName auf value festgelegt werden.In the case of a property setter, ParamName should be set to value.

Öffentliche und geschützte Methodenmember sollten Ausnahmen auslösen, wann immer sie ihre beabsichtigten Funktionen nicht auslösen können.Public and protected methods members should throw exceptions whenever they cannot complete their intended functions. Die Ausnahmeklasse, die ausgelöst wird, muss die möglichst genaueste verfügbare Ausnahme sein, die zu den Fehlerbedingungen passt.The exception class that is thrown should be the most specific exception available that fits the error conditions. Diese Ausnahmen sollten als Teil der Klassenfunktionalität dokumentiert werden, und abgeleitete Klassen oder Updates an der ursprünglichen Klasse müssen das gleiche Verhalten für die Abwärtskompatibilität beibehalten.These exceptions should be documented as part of the class functionality, and derived classes or updates to the original class should retain the same behavior for backward compatibility.

Was Sie beim Auslösen von Ausnahmen vermeiden solltenThings to Avoid When Throwing Exceptions

Die folgende Liste enthält Vorgehensweisen, die beim Auslösen von Ausnahmen zu vermeiden sind:The following list identifies practices to avoid when throwing exceptions:

  • Ausnahmen dürfen nicht zum Ändern des Flusses eines Programms als Teil der normalen Ausführung verwendet werden.Exceptions should not be used to change the flow of a program as part of ordinary execution. Ausnahmen dürfen nur zum Melden und Behandeln von Fehlerzuständen verwendet werden.Exceptions should only be used to report and handle error conditions.

  • Ausnahmen dürfen nicht als Rückgabewert oder Parameter zurückgegeben werden, anstatt ausgelöst zu werden.Exceptions should not be returned as a return value or parameter instead of being thrown.

  • Lösen Sie System.Exception, System.SystemException, System.NullReferenceException oder System.IndexOutOfRangeException nicht mit Absicht über Ihren eigenen Quellcode aus.Do not throw System.Exception, System.SystemException, System.NullReferenceException, or System.IndexOutOfRangeException intentionally from your own source code.

  • Erstellen Sie keine Ausnahmen, die im Debugmodus, aber nicht im Releasemodus ausgelöst werden können.Do not create exceptions that can be thrown in debug mode but not release mode. Um Laufzeitfehler während der Entwicklungsphase zu identifizieren, verwenden Sie stattdessen die Debugassertion.To identify run-time errors during the development phase, use Debug Assert instead.

Definieren von AusnahmeklassenDefining Exception Classes

Programme können eine zuvor definierte Ausnahmeklasse im System-Namespace auslösen (mit Ausnahme der eben beschriebenen Fälle) oder ihre eigenen Ausnahmeklassen durch Ableitung von Exception erstellen.Programs can throw a predefined exception class in the System namespace (except where previously noted), or create their own exception classes by deriving from Exception. Die abgeleiteten Klassen müssen zumindest vier Konstruktoren definieren: einen Standardkonstruktor, einen, der die message-Eigenschaft festlegt, und einen, der jeweils die Eigenschaften Message und InnerException festlegt.The derived classes should define at least four constructors: one default constructor, one that sets the message property, and one that sets both the Message and InnerException properties. Der vierte Konstruktor wird verwendet, um die Ausnahme zu serialisieren.The fourth constructor is used to serialize the exception. Neue Ausnahmeklassen sollten serialisierbar sein.New exception classes should be serializable. Zum Beispiel:For example:

[Serializable()]
public class InvalidDepartmentException : System.Exception
{
    public InvalidDepartmentException() : base() { }
    public InvalidDepartmentException(string message) : base(message) { }
    public InvalidDepartmentException(string message, System.Exception inner) : base(message, inner) { }

    // A constructor is needed for serialization when an
    // exception propagates from a remoting server to the client. 
    protected InvalidDepartmentException(System.Runtime.Serialization.SerializationInfo info,
        System.Runtime.Serialization.StreamingContext context) { }
}

Neue Eigenschaften sollten nur zur Ausnahmeklasse hinzugefügt werden, wenn die Daten, die sie bereitstellen, zur Auflösung der Ausnahme nützlich sind.New properties should only be added to the exception class when the data they provide is useful to resolving the exception. Wenn der abgeleiteten Ausnahmeklasse neue Eigenschaften hinzugefügt werden, muss ToString() überschrieben werden, um die hinzugefügten Informationen zurückzugeben.If new properties are added to the derived exception class, ToString() should be overridden to return the added information.

C#-ProgrammiersprachenspezifikationC# Language Specification

Weitere Informationen erhalten Sie unter C#-Sprachspezifikation.For more information, see the C# Language Specification. Die Sprachspezifikation ist die verbindliche Quelle für die Syntax und Verwendung von C#.The language specification is the definitive source for C# syntax and usage.

Siehe auchSee Also

C#-ProgrammierhandbuchC# Programming Guide
Ausnahmen und AusnahmebehandlungExceptions and Exception Handling
AusnahmenhierarchieException Hierarchy
AusnahmebehandlungException Handling