Benannte und optionale Argumente (C#-Programmierhandbuch)Named and Optional Arguments (C# Programming Guide)

C# 4C# 4 führt benannte und optionale Argumente ein. introduces named and optional arguments. Benannte Argumente ermöglichen es Ihnen, ein Argument für einen bestimmten Parameter anzugeben, indem Sie das Argument dem Parameternamen anstatt der Position des Parameters in der Parameterliste zuordnen.Named arguments enable you to specify an argument for a particular parameter by associating the argument with the parameter's name rather than with the parameter's position in the parameter list. Optionale Argumente ermöglichen es Ihnen, Argumente für einige Parameter auszulassen.Optional arguments enable you to omit arguments for some parameters. Beide Techniken können mit Methoden, Indexern, Konstruktoren und Delegaten verwendet werden.Both techniques can be used with methods, indexers, constructors, and delegates.

Wenn Sie benannte und optionale Argumente verwenden, werden die Argumente in der Reihenfolge ausgewertet, in der sie in der Argumentliste, nicht in der Parameterliste, erscheinen.When you use named and optional arguments, the arguments are evaluated in the order in which they appear in the argument list, not the parameter list.

Wenn Sie benannte und optionale Parameter zusammen verwenden, können Sie Argumente für nur ein paar Parameter aus einer Liste von optionalen Parametern bereitstellen.Named and optional parameters, when used together, enable you to supply arguments for only a few parameters from a list of optional parameters. Diese Funktion erleichtert den Zugriff auf COM-Schnittstellen wie etwa die Automatisierungs-APIs in Microsoft Office erheblich.This capability greatly facilitates calls to COM interfaces such as the Microsoft Office Automation APIs.

Benannte ArgumenteNamed Arguments

Bei Verwendung benannter Argumente bleibt es Ihnen erspart, sich an die Reihenfolge von Parametern in den Parameterlisten von aufgerufenen Methoden zu erinnern oder sie nachzuschauen.Named arguments free you from the need to remember or to look up the order of parameters in the parameter lists of called methods. Der Parameter für jedes Argument kann vom Parameternamen angegeben werden.The parameter for each argument can be specified by parameter name. Eine Funktion, die beispielsweise Details zu einer Bestellung ausgibt (z.B. Verkäufername, Bestellnummer und Produktname), kann standardmäßig aufgerufen werden, indem anhand der Position Argumente in der Reihenfolge gesendet werden, die von der Funktion definiert wurde.For example, a function that prints order details (such as, seller name, order number & product name) can be called in the standard way by sending arguments by position, in the order defined by the function.

PrintOrderDetails("Gift Shop", 31, "Red Mug");

Wenn Sie sich nicht an die Reihenfolge der Parameter erinnern, aber deren Namen wissen, können Sie die Argumente in einer beliebigen Reihenfolge senden.If you do not remember the order of the parameters but know their names, you can send the arguments in any order.

PrintOrderDetails(orderNum: 31, productName: "Red Mug", sellerName: "Gift Shop");

PrintOrderDetails(productName: "Red Mug", sellerName: "Gift Shop", orderNum: 31);

Benannte Argumente verbessern auch die Lesbarkeit des Codes, indem sie identifizieren, was jedes Argument darstellt.Named arguments also improve the readability of your code by identifying what each argument represents. In der folgenden Beispielmethode darf sellerName nicht NULL sein oder Leerraum enthalten.In the example method below, the sellerName cannot be null or white space. Da es sich bei sellerName und productName um Zeichenfolgentypen handelt, sollten Sie benannte Argumente verwenden, anstatt Argumente nach Position zu senden, um die beiden Parameter zu unterscheiden und die Leser des Codes nicht zu verwirren.As both sellerName and productName are string types, instead of sending arguments by position, it makes sense to use named arguments to disambiguate the two and reduce confusion for anyone reading the code.

Benannte Argumente sind länger gültig, wenn sie mit positionellen Argumenten verwendet werden, daNamed arguments, when used with positional arguments, are valid as long as

  • ihnen keine positionellen Argumente folgen, bzw. dathey're not followed by any positional arguments, or

PrintOrderDetails("Gift Shop", 31, productName: "Red Mug");

  • sie ab C# 7.2 in der richtigen Position verwendet werden.starting with C# 7.2, they're used in the correct position. Im folgenden Beispiel befindet sich der Parameter orderNum in der richtigen Position, ist jedoch nicht explizit benannt.In the example below, the parameter orderNum is in the correct position but isn't explicitly named.

PrintOrderDetails(sellerName: "Gift Shop", 31, productName: "Red Mug");

Benannte Argumente, die sich außerhalb der Reihenfolge befinden, sind jedoch ungültig, wenn diesen positionelle Argumente folgen.However, out-of-order named arguments are invalid if they're followed by positional arguments.

// This generates CS1738: Named argument specifications must appear after all fixed arguments have been specified.
PrintOrderDetails(productName: "Red Mug", 31, "Gift Shop");

BeispielExample

Der folgende Code implementiert die Beispiele in diesem Abschnitt sowie einige zusätzliche Beispiele.The following code implements the examples from this section along with some additional ones.

class NamedExample
{
    static void Main(string[] args)
    {
        // The method can be called in the normal way, by using positional arguments.
        PrintOrderDetails("Gift Shop", 31, "Red Mug");

        // Named arguments can be supplied for the parameters in any order.
        PrintOrderDetails(orderNum: 31, productName: "Red Mug", sellerName: "Gift Shop");
        PrintOrderDetails(productName: "Red Mug", sellerName: "Gift Shop", orderNum: 31);

        // Named arguments mixed with positional arguments are valid
        // as long as they are used in their correct position.
        PrintOrderDetails("Gift Shop", 31, productName: "Red Mug");
        PrintOrderDetails(sellerName: "Gift Shop", 31, productName: "Red Mug");    // C# 7.2 onwards
        PrintOrderDetails("Gift Shop", orderNum: 31, "Red Mug");                   // C# 7.2 onwards

        // However, mixed arguments are invalid if used out-of-order.
        // The following statements will cause a compiler error.
        // PrintOrderDetails(productName: "Red Mug", 31, "Gift Shop");
        // PrintOrderDetails(31, sellerName: "Gift Shop", "Red Mug");
        // PrintOrderDetails(31, "Red Mug", sellerName: "Gift Shop");
    }

    static void PrintOrderDetails(string sellerName, int orderNum, string productName)
    {
        if (string.IsNullOrWhiteSpace(sellerName))
        {
            throw new ArgumentException(message: "Seller name cannot be null or empty.", paramName: nameof(sellerName));
        }

        Console.WriteLine($"Seller: {sellerName}, Order #: {orderNum}, Product: {productName}");
    }
}

Optionale ArgumenteOptional Arguments

Die Definition einer Methode, eines Konstruktors, eines Indexers oder Delegaten kann angeben, dass deren Parameter benötigt werden oder optional sind.The definition of a method, constructor, indexer, or delegate can specify that its parameters are required or that they are optional. Jeder Aufruf muss Argumente für alle benötigten Parameter bereitstellen, kann aber Argumente für optionale Parameter auslassen.Any call must provide arguments for all required parameters, but can omit arguments for optional parameters.

Jeder optionale Parameter hat einen Standardwert als Teil seiner Definition.Each optional parameter has a default value as part of its definition. Wenn für diesen Parameter kein Argument gesendet wird, wird der Standardwert verwendet.If no argument is sent for that parameter, the default value is used. Ein Standardwert muss einer der folgenden Typen von Ausdrücken sein:A default value must be one of the following types of expressions:

  • Ein konstanter Ausdrucka constant expression;

  • Ein Ausdruck der Form new ValType(), wobei ValType ein Werttyp wie enum oder struct istan expression of the form new ValType(), where ValType is a value type, such as an enum or a struct;

  • Ein Ausdruck in Form von default(ValType), wobei ValType ein Werttyp istan expression of the form default(ValType), where ValType is a value type.

Optionale Parameter werden am Ende der Parameterliste nach den erforderlichen Parametern definiert.Optional parameters are defined at the end of the parameter list, after any required parameters. Wenn der Aufrufer ein Argument für einen beliebigen Parameter aus einer Folge von optionalen Parametern bereitstellt, muss er Argumente für alle vorherigen optionalen Parameter bereitstellen.If the caller provides an argument for any one of a succession of optional parameters, it must provide arguments for all preceding optional parameters. Durch Trennzeichen getrennte Lücken in der Argumentliste werden nicht unterstützt.Comma-separated gaps in the argument list are not supported. Im folgenden Code wird z.B. die Instanzmethode ExampleMethod mit einem erforderlichen und zwei optionalen Parametern definiert.For example, in the following code, instance method ExampleMethod is defined with one required and two optional parameters.

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

Der folgende Aufruf von ExampleMethod verursacht einen Compilerfehler, da ein Argument für den dritten Parameter, aber nicht für den zweiten, bereitgestellt wird.The following call to ExampleMethod causes a compiler error, because an argument is provided for the third parameter but not for the second.

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

Wenn Sie den Namen des dritten Parameters kennen, können Sie ein benanntes Argument zum Ausführen der Aufgabe verwenden.However, if you know the name of the third parameter, you can use a named argument to accomplish the task.

anExample.ExampleMethod(3, optionalint: 4);

IntelliSense verwendet zum Anzeigen von optionalen Parametern Klammern, wie in folgender Abbildung veranschaulicht wird.IntelliSense uses brackets to indicate optional parameters, as shown in the following illustration.

IntelliSense-QuickInfo für die Methode „ExampleMethod.“IntelliSense Quick Info for method ExampleMethod.
Optionale Parameter in ExampleMethodOptional parameters in ExampleMethod

Hinweis

Sie können auch optionale Parameter mit der .NET-Klasse OptionalAttribute deklarieren.You can also declare optional parameters by using the .NET OptionalAttribute class. OptionalAttribute-Parameter erfordern keinen Standardwert.OptionalAttribute parameters do not require a default value.

BeispielExample

Im folgenden Beispiel hat der Konstruktor für ExampleClass einen Parameter, der optional ist.In the following example, the constructor for ExampleClass has one parameter, which is optional. Instanzmethode ExampleMethod hat einen erforderlichen Parameter (required) und zwei optionale Parameter (optionalstr und optionalint).Instance method ExampleMethod has one required parameter, required, and two optional parameters, optionalstr and optionalint. Der Code in Main veranschaulicht die unterschiedlichen Methoden, in denen der Konstruktor und die Methode aufgerufen werden können.The code in Main shows the different ways in which the constructor and method can be invoked.

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-SchnittstellenCOM Interfaces

Benannte und optionale Argumente verbessern zusammen mit der Unterstützung von dynamischen Objekten und anderen Verbesserungen deutlich die Interoperabilität mit COM-APIs wie Office-Automatisierungs-APIs.Named and optional arguments, along with support for dynamic objects and other enhancements, greatly improve interoperability with COM APIs, such as Office Automation APIs.

Die Methode AutoFormat hat z.B. in der Schnittstelle Bereich von Microsoft Office Excel sieben Parameter, von denen alle optional sind.For example, the AutoFormat method in the Microsoft Office Excel Range interface has seven parameters, all of which are optional. Diese Parameter sind in der folgenden Abbildung dargestellt.These parameters are shown in the following illustration.

IntelliSense-QuickInfo für die AutoFormat-Methode.IntelliSense Quick Info for the AutoFormat method.
AutoFormat-ParameterAutoFormat parameters

In C# 3.0 und früheren Versionen wird ein Argument für jeden Parameter benötigt, wie im folgenden Beispiel gezeigt wird.In C# 3.0 and earlier versions, an argument is required for each parameter, as shown in the following example.

// 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 jedoch den Aufruf an AutoFormat erheblich vereinfachen, indem Sie benannte und optionale Argumente verwenden, die in C# 4.0 eingeführt wurden.However, you can greatly simplify the call to AutoFormat by using named and optional arguments, introduced in C# 4.0. Benannte und optionale Parameter helfen Ihnen dabei, das Argument für einen optionalen Parameter auszulassen, wenn Sie den Standardwert des Parameters nicht ändern möchten.Named and optional arguments enable you to omit the argument for an optional parameter if you do not want to change the parameter's default value. Im folgenden Aufruf wird ein Wert für nur einen der sieben Parameter angegeben.In the following call, a value is specified for only one of the seven parameters.

// 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 Vorgehensweise: Verwenden von benannten und optionalen Argumenten in der Office-Programmierung und Vorgehensweise: Zugreifen auf Office Interop-Objekte mithilfe von Visual C#-Funktionen.For more information and examples, see How to: Use Named and Optional Arguments in Office Programming and How to: Access Office Interop Objects by Using Visual C# Features.

Overload ResolutionOverload Resolution

Das Verwenden von benannten und optionalen Argumenten wirkt sich auf die Überladungsauflösung folgendermaßen aus:Use of named and optional arguments affects overload resolution in the following ways:

  • Eine Methode, ein Indexer oder ein Konstruktor ist ein Kandidat für die Ausführung, wenn jeder der Parameter entweder optional ist oder über Namen oder Position auf ein einzelnes Argument in der aufrufenden Anweisung reagiert. Dieses Argument kann in dem Typ des Parameters konvertiert werden.A method, indexer, or constructor is a candidate for execution if each of its parameters either is optional or corresponds, by name or by position, to a single argument in the calling statement, and that argument can be converted to the type of the parameter.

  • Wenn mehr als ein Kandidat gefunden wird, werden die Regeln der Überladungsauflösung als bevorzugte Konvertierungen auf die Argumente angewandt, die ausdrücklich angegeben sind.If more than one candidate is found, overload resolution rules for preferred conversions are applied to the arguments that are explicitly specified. Ausgelassene Argumente für optionale Parameter werden ignoriert.Omitted arguments for optional parameters are ignored.

  • Wenn zwei Kandidaten gleich gut geeignet sind, wird ein Kandidat bevorzugt, der keine optionalen Parameter besitzt, für die Argumente im Aufruf ausgelassen wurden.If two candidates are judged to be equally good, preference goes to a candidate that does not have optional parameters for which arguments were omitted in the call. Dies ist die Folge einer allgemeinen Präferenz bei der Überladungsauflösung für Kandidaten, die weniger Parameter besitzen.This is a consequence of a general preference in overload resolution for candidates that have fewer parameters.

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

Gewusst wie: Verwenden von benannten und optionalen Argumenten in der Office-ProgrammierungHow to: Use Named and Optional Arguments in Office Programming
Verwenden von dynamischen TypenUsing Type dynamic
Verwenden von KonstruktorenUsing Constructors
Verwenden von IndexernUsing Indexers