Benannte und optionale Argumente (C#-Programmierhandbuch)

Visual C# 2010 stellt erstmals benannte und optionale Argumente bereit. Benannte Argumente ermöglichen Ihnen, ein Argument für einen bestimmten Parameter anzugeben, indem Sie das Argument dem Parameternamen statt der Position des Parameters in der Parameterliste zuordnen. Optionale Argumente ermöglichen Ihnen, Argumente für einige Parameter wegzulassen. Beide Techniken können mit Methoden, Indexern, Konstruktoren und Delegaten verwendet werden.

Bei der Verwendung von benannten und optionalen Argumenten werden die Argumente in der Reihenfolge ausgewertet, die die Argumentliste vorgibt, nicht die Parameterliste.

Wenn Sie benannte und optionale Argumente zusammen verwenden, haben Sie die Möglichkeit, Argumente für nur einige Parameter aus einer Liste mit optionalen Parametern anzugeben. Durch diese Funktion werden Aufrufe von COM-Schnittstellen, wie z. B. Microsoft Office-Automatisierungs-APIs, enorm vereinfacht.

Benannte Argumente

Wenn Sie benannte Argumente nutzen, müssen Sie sich nicht mehr um die Reihenfolge der Parameter in den Parameterlisten aufgerufener Methoden kümmern. Sie können die Parameter für die einzelnen Argumente anhand des Parameternamens angeben. Beispiel: Eine Funktion zur Berechnung des Body-Mass-Index (BMI) kann mit dem Standardverfahren aufgerufen werden, indem die Argumente für Gewicht und Größe nach Position in der von der Funktion definierten Reihenfolge gesendet werden.

CalculateBMI(123, 64);

Wenn Sie sich nicht an die Reihenfolge der Parameter, wohl aber an ihre Namen erinnern, können Sie die Argumente in beliebiger Reihenfolge senden (Gewicht zuerst oder Größe zuerst).

CalculateBMI(weight: 123, height: 64);

CalculateBMI(height: 64, weight: 123);

Durch benannte Argumente wird außerdem die Lesbarkeit des Codes verbessert, indem identifiziert wird, welchen Wert die einzelnen Argumente darstellen.

Ein benanntes Argument kann auf Positionsargumente folgen, wie hier gezeigt.

CalculateBMI(123, height: 64);

Ein Positionsargument kann jedoch nicht auf ein benanntes Argument folgen. Die folgende Anweisung verursacht einen Compilerfehler.

//CalculateBMI(weight: 123, 64);

Beispiel

Mit dem folgenden Code werden die Beispiele aus diesem Abschnitt implementiert.

class NamedExample
{
    static void Main(string[] args)
    {
        // The method can be called in the normal way, by using positional arguments.
        Console.WriteLine(CalculateBMI(123, 64));

        // Named arguments can be supplied for the parameters in either order.
        Console.WriteLine(CalculateBMI(weight: 123, height: 64));
        Console.WriteLine(CalculateBMI(height: 64, weight: 123));

        // Positional arguments cannot follow named arguments.
        // The following statement causes a compiler error.
        //Console.WriteLine(CalculateBMI(weight: 123, 64));

        // Named arguments can follow positional arguments.
        Console.WriteLine(CalculateBMI(123, height: 64));
    }

    static int CalculateBMI(int weight, int height)
    {
        return (weight * 703) / (height * height);
    }
}

Optionale Argumente

In der Definition einer Methode, eines Konstruktors, eines Indexers oder eines Delegaten kann angegeben sein, ob die Parameter erforderlich oder optional sind. Bei jedem Aufruf müssen Argumente für alle erforderlichen Parameter bereitgestellt werden, Argumente für optionale Parameter können jedoch weggelassen werden.

Ein Standardwert ist Teil der Definition jedes optionalen Parameters. Dieser Standardwert wird verwendet, wenn für einen Parameter kein Argument gesendet wird. Standardwerte müssen Konstanten sein.

Optionale Parameter werden am Ende der Parameterliste nach den erforderlichen Parametern definiert. Wenn der Aufrufer ein Argument für einen Parameter in einer Folge von optionalen Parametern bereitstellt, müssen auch Argumente für alle vorangehenden optionalen Parameter bereitgestellt werden. Durch Trennzeichen getrennte Lücken in der Argumentliste werden nicht unterstützt. Im folgenden Code z. B. ist die ExampleMethod-Instanzmethode durch einen erforderlichen und zwei optionale Parameter definiert.

public void ExampleMethod(int required, string optionalstr = "default string",
    int optionalint = 10)

Der folgende Aufruf von ExampleMethod verursacht einen Compilerfehler, da ein Argument zwar für den dritten, aber nicht für den zweiten Parameter bereitgestellt wird.

//anExample.ExampleMethod(3, ,4);

Wenn Sie jedoch den Namen des dritten Parameters kennen, können Sie die Aufgabe mithilfe eines benannten Arguments lösen.

anExample.ExampleMethod(3, optionalint: 4);

IntelliSense zeigt optionale Parameter in Klammern an, wie in der folgenden Abbildung dargestellt.

Optionale Parameter in ExampleMethod

Beispiel

Der Konstruktor für ExampleClass im folgenden Beispiel weist einen Parameter auf, der optional ist. Die Instanzmethode ExampleMethod weist einen erforderlichen Parameter (required) und zwei optionale Parameter (optionalstr und optionalint) auf. Der Code in Main veranschaulicht die unterschiedlichen Methoden, mit denen der Konstruktor und die Methode aufgerufen werden können.

namespace OptionalNamespace
{
    class OptionalExample
    {
        static void Main(string[] args)
        {
            // Instance anExample does not send an argument for the constructor's
            // optional parameter.
            ExampleClass anExample = new ExampleClass();
            anExample.ExampleMethod(1, "One", 1);
            anExample.ExampleMethod(2, "Two");
            anExample.ExampleMethod(3);

            // Instance anotherExample sends an argument for the constructor's
            // optional parameter.
            ExampleClass anotherExample = new ExampleClass("Provided name");
            anotherExample.ExampleMethod(1, "One", 1);
            anotherExample.ExampleMethod(2, "Two");
            anotherExample.ExampleMethod(3);

            // The following statements produce compiler errors.

            // An argument must be supplied for the first parameter, and it
            // must be an integer.
            //anExample.ExampleMethod("One", 1);
            //anExample.ExampleMethod();

            // You cannot leave a gap in the provided arguments. 
            //anExample.ExampleMethod(3, ,4);
            //anExample.ExampleMethod(3, 4);

            // You can use a named parameter to make the previous 
            // statement work.
            anExample.ExampleMethod(3, optionalint: 4);
        }
    }

    class ExampleClass
    {
        private string _name;

        // Because the parameter for the constructor, name, has a default
        // value assigned to it, it is optional.
        public ExampleClass(string name = "Default name")
        {
            _name = name;
        }

        // The first parameter, required, has no default value assigned
        // to it. Therefore, it is not optional. Both optionalstr and 
        // optionalint have default values assigned to them. They are optional.
        public void ExampleMethod(int required, string optionalstr = "default string",
            int optionalint = 10)
        {
            Console.WriteLine("{0}: {1}, {2}, and {3}.", _name, required, optionalstr,
                optionalint);
        }
    }

    // The output from this example is the following:
    // Default name: 1, One, and 1.
    // Default name: 2, Two, and 10.
    // Default name: 3, default string, and 10.
    // Provided name: 1, One, and 1.
    // Provided name: 2, Two, and 10.
    // Provided name: 3, default string, and 10.
    // Default name: 3, default string, and 4.

}

COM-Schnittstellen

Benannte und optionale Argumente sorgen wie auch die Unterstützung für dynamische Objekte und andere Erweiterungen für eine erhebliche Verbesserung der Interoperabilität mit COM-APIs, wie z. B. Office-Automatisierungs-APIs.

Beispiel: Die AutoFormat-Methode in der Microsoft Office Excel Range-Schnittstelle verfügt über sieben Parameter, die alle optional sind. Diese Parameter sind in der folgenden Abbildung enthalten.

AutoFormat-Parameter

In C# 3.0 und früheren Versionen ist ein Argument für jeden Parameter erforderlich, wie im folgenden Beispiel gezeigt.

// In C# 3.0 and earlier versions, you need to supply an argument for
// every parameter. The following call specifies a value for the first
// parameter, and sends a placeholder value for the other six. The
// default values are used for those parameters.
var excelApp = new Microsoft.Office.Interop.Excel.Application();
excelApp.Workbooks.Add();
excelApp.Visible = true;

var myFormat = 
    Microsoft.Office.Interop.Excel.XlRangeAutoFormat.xlRangeAutoFormatAccounting1;

excelApp.get_Range("A1", "B4").AutoFormat(myFormat, Type.Missing, 
    Type.Missing, Type.Missing, Type.Missing, Type.Missing, Type.Missing);

Sie können den Aufruf von AutoFormat jedoch sehr vereinfachen, indem Sie benannte und optionale Argumente verwenden, die in C# 4.0 eingeführt wurden. Benannte und optionale Argumente ermöglichen Ihnen, das Argument für einen optionalen Parameter wegzulassen, wenn Sie den Standardwert des Parameters nicht ändern möchten. Im folgenden Aufruf wird für nur einen der sieben Parameter ein Wert angegeben.

// The following code shows the same call to AutoFormat in C# 4.0. Only
// the argument for which you want to provide a specific value is listed.
excelApp.Range["A1", "B4"].AutoFormat( Format: myFormat );

Weitere Informationen und Beispiele finden Sie unter Gewusst wie: Verwenden von benannten und optionalen Argumenten in der Office-Programmierung (C#-Programmierhandbuch) und Gewusst wie: Zugreifen auf Office-Interop-Objekte mithilfe von Visual C# 2010-Funktionen (C#-Programmierhandbuch).

Überladungsauflösung

Die Verwendung von benannten und optionalen Argumenten wirkt sich wie folgt auf die Überladungsauflösung aus:

• Eine Methode, ein Indexer oder ein Konstruktor kommt für die Ausführung in Frage, wenn jeder der zugehörigen Parameter entweder optional ist oder anhand von Name oder Position einem einzelnen Argument in der aufrufenden Anweisung zugewiesen ist, das in den Typ des Parameters konvertiert werden kann.

• Bei mehreren möglichen Kandidaten werden die Überladungsauflösungsregeln für bevorzugte Konvertierungen auf die explizit angegebenen Argumente angewendet. Weggelassene Argumente für optionale Parameter werden ignoriert.

• Wenn zwei Kandidaten gleich gut geeignet sind, wird der Kandidat bevorzugt, der keine optionalen Parameter aufweist, für die Argumente weggelassen wurden. Die Ursache hierfür ist eine allgemeine Einstellung für die Überladungsauflösung für Kandidaten mit weniger Parametern.

C#-Programmiersprachenspezifikation

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

Siehe auch

Aufgaben

Gewusst wie: Verwenden von benannten und optionalen Argumenten in der Office-Programmierung (C#-Programmierhandbuch)

Referenz

Verwenden von Konstruktoren (C#-Programmierhandbuch)

Verwenden von Indexern (C#-Programmierhandbuch)

Weitere Ressourcen

Verwenden des Typs dynamic (C#-Programmierhandbuch)