Benoemde en optionele argumenten (C#-programmeerhandleiding)

Artikel
03/20/2024

Met benoemde argumenten kunt u een argument voor een parameter opgeven door het argument te koppelen aan de naam in plaats van de positie in de parameterlijst. Met optionele argumenten kunt u argumenten weglaten voor sommige parameters. Beide technieken kunnen worden gebruikt met methoden, indexeerfuncties, constructors en gemachtigden.

Wanneer u benoemde en optionele argumenten gebruikt, worden de argumenten geëvalueerd in de volgorde waarin ze worden weergegeven in de lijst met argumenten, niet in de parameterlijst.

Met benoemde en optionele parameters kunt u argumenten opgeven voor geselecteerde parameters. Deze mogelijkheid vereenvoudigt het aanroepen van COM-interfaces, zoals de Microsoft Office Automation-API's.

Benoemde argumenten

Benoemde argumenten maken het mogelijk om de volgorde van argumenten te koppelen aan de volgorde van parameters in de parameterlijsten met aangeroepen methoden. Het argument voor elke parameter kan worden opgegeven met de parameternaam. Een functie die bijvoorbeeld ordergegevens afdrukt (zoals verkopernaam, ordernummer en productnaam) kan worden aangeroepen door argumenten te verzenden op positie, in de volgorde die is gedefinieerd door de functie.

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

Als u de volgorde van de parameters niet meer weet, maar hun namen kent, kunt u de argumenten in elke volgorde verzenden.

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

Benoemde argumenten verbeteren ook de leesbaarheid van uw code door te bepalen wat elk argument vertegenwoordigt. In de onderstaande voorbeeldmethode kan de sellerName waarde niet null of witruimte zijn. Aangezien beide sellerName en productName tekenreekstypen zijn, is het logisch om benoemde argumenten te gebruiken om de twee te ondubbelzinnig te maken en verwarring te verminderen voor iedereen die de code leest.

Benoemde argumenten, wanneer deze worden gebruikt met positionele argumenten, zijn geldig zolang

ze worden niet gevolgd door positionele argumenten of

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

ze worden in de juiste positie gebruikt. In het onderstaande voorbeeld bevindt de parameter orderNum zich op de juiste positie, maar is deze niet expliciet benoemd.
```
PrintOrderDetails(sellerName: "Gift Shop", 31, productName: "Red Mug");
```

Positionele argumenten die volgen op niet-op-volgorde benoemde argumenten zijn ongeldig.

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

Opmerking

Met de volgende code worden de voorbeelden uit deze sectie samen met een aantal extra geïmplementeerd.

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"); 
        PrintOrderDetails("Gift Shop", orderNum: 31, "Red Mug");

        // 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}");
    }
}

Optionele argumenten

De definitie van een methode, constructor, indexeerfunctie of gemachtigde kan de parameters opgeven, zijn vereist of optioneel. Een aanroep moet argumenten opgeven voor alle vereiste parameters, maar kan argumenten weglaten voor optionele parameters.

Elke optionele parameter heeft een standaardwaarde als onderdeel van de definitie. Als er geen argument voor die parameter wordt verzonden, wordt de standaardwaarde gebruikt. Een standaardwaarde moet een van de volgende typen expressies zijn:

een constante expressie;
een expressie van het formulier new ValType(), waarbij ValType een waardetype is, zoals een enum of een struct;
een expressie van de standaardwaarde van het formulier (ValType), waarbij ValType een waardetype is.

Optionele parameters worden aan het einde van de lijst met parameters gedefinieerd, na de vereiste parameters. Als de aanroeper een argument voor een van de optionele parameters opvolgt, moet deze argumenten opgeven voor alle voorgaande optionele parameters. Door komma's gescheiden hiaten in de lijst met argumenten worden niet ondersteund. In de volgende code wordt bijvoorbeeld de instantiemethode ExampleMethod gedefinieerd met één vereiste en twee optionele parameters.

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

De volgende aanroep om een compilerfout te ExampleMethod veroorzaken, omdat er een argument wordt opgegeven voor de derde parameter, maar niet voor de tweede.

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

Als u echter de naam van de derde parameter kent, kunt u een benoemd argument gebruiken om de taak uit te voeren.

anExample.ExampleMethod(3, optionalint: 4);

IntelliSense gebruikt vierkante haken om optionele parameters aan te geven, zoals wordt weergegeven in de volgende afbeelding:

Schermopname van Snelle informatie over IntelliSense voor de methode ExampleMethod.

Notitie

U kunt ook optionele parameters declareren met behulp van de .NET-klasse OptionalAttribute . OptionalAttribute voor parameters is geen standaardwaarde vereist. Als u echter een standaardwaarde wilt, bekijkt DefaultParameterValueAttribute u de klasse.

Opmerking

In het volgende voorbeeld heeft de constructor voor één ExampleClass parameter, wat optioneel is. De instantiemethode ExampleMethod heeft één vereiste parameter, requireden twee optionele parameters, optionalstr en optionalint. De code in Main toont de verschillende manieren waarop de constructor en methode kunnen worden aangeroepen.

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(
                $"{_name}: {required}, {optionalstr}, and {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.
}

In de voorgaande code ziet u een aantal voorbeelden waarbij optionele parameters niet correct worden toegepast. Het eerste voorbeeld laat zien dat een argument moet worden opgegeven voor de eerste parameter, die vereist is.

Kenmerken van nummerweergave

Aanroepergegevenskenmerken, zoals CallerFilePathAttribute, CallerLineNumberAttribute, CallerMemberNameAttributeen CallerArgumentExpressionAttribute, worden gebruikt om informatie over de aanroeper naar een methode te verkrijgen. Deze kenmerken zijn vooral handig wanneer u fouten opspoort of wanneer u informatie over methodeaanroepen moet vastleggen.

Deze kenmerken zijn optionele parameters met standaardwaarden die door de compiler worden geleverd. De aanroeper mag niet expliciet een waarde voor deze parameters opgeven.

COM-interfaces

Benoemde en optionele argumenten, samen met ondersteuning voor dynamische objecten, verbeteren de interoperabiliteit met COM-API's, zoals Office Automation-API's, aanzienlijk.

De AutoFormat methode in de Microsoft Office Excel-interface Range heeft bijvoorbeeld zeven parameters, die allemaal optioneel zijn. Deze parameters worden weergegeven in de volgende afbeelding:

Schermopname van Snelle informatie over IntelliSense voor de methode AutoOpmaak.

U kunt de aanroep AutoFormat echter aanzienlijk vereenvoudigen met behulp van benoemde en optionele argumenten. Met benoemde en optionele argumenten kunt u het argument voor een optionele parameter weglaten als u de standaardwaarde van de parameter niet wilt wijzigen. In de volgende aanroep wordt een waarde opgegeven voor slechts één van de zeven parameters.

var excelApp = new Microsoft.Office.Interop.Excel.Application();
excelApp.Workbooks.Add();
excelApp.Visible = true;

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

excelApp.Range["A1", "B4"].AutoFormat( Format: myFormat );

Zie Voor meer informatie en voorbeelden het gebruik van benoemde en optionele argumenten in Het programmeren van Office en het openen van Office-interop-objecten met behulp van C#-functies.

Overbelastingsresolutie

Het gebruik van benoemde en optionele argumenten is op de volgende manieren van invloed op overbelastingsresolutie:

Een methode, indexeerfunctie of constructor is een kandidaat voor uitvoering als elk van de parameters optioneel is of op naam of op positie overeenkomt met één argument in de aanroepinstructie en dat argument kan worden geconverteerd naar het type van de parameter.
Als er meer dan één kandidaat wordt gevonden, worden overbelastingsoplossingsregels voor voorkeursconversies toegepast op de argumenten die expliciet zijn opgegeven. Weggelaten argumenten voor optionele parameters worden genegeerd.
Als twee kandidaten even goed worden beoordeeld, gaat de voorkeur naar een kandidaat die geen optionele parameters heeft waarvoor argumenten zijn weggelaten in de aanroep. Over het algemeen geeft overbelastingsresolutie de voorkeur aan kandidaten die minder parameters hebben.

C#-taalspecificatie

Zie de C#-taalspecificatie voor meer informatie. De taalspecificatie is de definitieve bron voor de C#-syntaxis en het gebruik.

Delen via

Benoemde en optionele argumenten (C#-programmeerhandleiding)

Benoemde argumenten

Opmerking

Optionele argumenten

Opmerking

Kenmerken van nummerweergave

COM-interfaces

Overbelastingsresolutie

C#-taalspecificatie

Aanvullende resources