Namngivna och valfria argument (C#-programmeringsguide)

Med namngivna argument kan du ange ett argument för en parameter genom att matcha argumentet med dess namn i stället för dess position i parameterlistan. Med valfria argument kan du utelämna argument för vissa parametrar. Båda teknikerna kan användas med metoder, indexerare, konstruktorer och ombud.

När du använder namngivna och valfria argument utvärderas argumenten i den ordning de visas i argumentlistan, inte i parameterlistan.

Med namngivna och valfria parametrar kan du ange argument för valda parametrar. Den här funktionen underlättar i hög grad anrop till COM-gränssnitt, till exempel Api:er för Microsoft Office Automation.

Namngivna argument

Namngivna argument gör att du inte kan matcha argumentordningen med parametrarnas ordning i parameterlistorna för de metoder som kallas. Argumentet för varje parameter kan anges med parameternamnet. Till exempel kan en funktion som skriver ut orderinformation (till exempel säljarnamn, ordernummer och produktnamn) anropas genom att skicka argument efter position, i den ordning som definieras av funktionen.

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

Om du inte kommer ihåg parametrarnas ordning men känner till deras namn kan du skicka argumenten i valfri ordning.

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

Namngivna argument förbättrar också kodens läsbarhet genom att identifiera vad varje argument representerar. I exempelmetoden nedan sellerName får inte vara null eller tomt utrymme. Eftersom både sellerName och productName är strängtyper, i stället för att skicka argument efter position, är det klokt att använda namngivna argument för att skilja de två och minska förvirringen för alla som läser koden.

Namngivna argument, när de används med positionsargument, är giltiga så länge som

• de följs inte av några positionsargument, eller

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

• de används i rätt läge. I exemplet nedan är parametern orderNum i rätt position men heter inte uttryckligen.

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

Positionsargument som följer eventuella namngivna argument i fel ordning är ogiltiga.

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

Exempel

Följande kod implementerar exemplen från det här avsnittet tillsammans med några ytterligare.

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

Valfria argument

Definitionen av en metod, konstruktor, indexerare eller ombud kan ange att dess parametrar krävs eller är valfria. Alla anrop måste ange argument för alla obligatoriska parametrar, men kan utelämna argument för valfria parametrar.

Varje valfri parameter har ett standardvärde som en del av definitionen. Om inget argument skickas för den parametern används standardvärdet. Ett standardvärde måste vara en av följande typer av uttryck:

• ett konstant uttryck.
• ett uttryck för formuläret new ValType(), där ValType är en värdetyp, till exempel en uppräkning eller en struct.
• ett uttryck för formuläret default(ValType), där ValType är en värdetyp.

Valfria parametrar definieras i slutet av parameterlistan efter eventuella obligatoriska parametrar. Om anroparen tillhandahåller ett argument för någon av en följd av valfria parametrar måste den ange argument för alla föregående valfria parametrar. Kommaavgränsade luckor i argumentlistan stöds inte. I följande kod definieras till exempel instansmetoden ExampleMethod med en obligatorisk och två valfria parametrar.

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

Följande anrop till ExampleMethod orsakar ett kompilatorfel, eftersom ett argument anges för den tredje parametern men inte för den andra.

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

Men om du känner till namnet på den tredje parametern kan du använda ett namngivet argument för att utföra uppgiften.

anExample.ExampleMethod(3, optionalint: 4);

IntelliSense använder hakparenteser för att ange valfria parametrar, enligt följande bild:

Kommentar

Du kan också deklarera valfria parametrar med hjälp av .NET-klassen OptionalAttribute . OptionalAttribute parametrar kräver inget standardvärde. Men om du vill ha ett standardvärde kan du ta en titt på DefaultParameterValueAttribute klassen.

Exempel

I följande exempel har konstruktorn för ExampleClass en parameter, vilket är valfritt. Instansmetoden ExampleMethod har en obligatorisk parameter, required, och två valfria parametrar och optionalstroptionalint. Koden i Main visar de olika sätt på vilka konstruktorn och metoden kan anropas.

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.
}

Föregående kod visar ett antal exempel där valfria parametrar inte tillämpas korrekt. Den första visar att ett argument måste anges för den första parametern, vilket krävs.

Informationsattribut för uppringare

Informationsattribut för uppringare, till exempel CallerFilePathAttribute, CallerLineNumberAttribute, CallerMemberNameAttributeoch CallerArgumentExpressionAttribute, används för att hämta information om anroparen till en metod. Dessa attribut är särskilt användbara när du felsöker eller när du behöver logga information om metodanrop.

Dessa attribut är valfria parametrar med standardvärden som tillhandahålls av kompilatorn. Anroparen bör inte uttryckligen ange ett värde för dessa parametrar.

COM-gränssnitt

Namngivna och valfria argument, tillsammans med stöd för dynamiska objekt, förbättrar avsevärt samverkan med COM-API:er, till exempel Office Automation-API:er.

Metoden i Microsoft Office Excel-gränssnittet Range har till exempel AutoFormat sju parametrar, som alla är valfria. Dessa parametrar visas i följande bild:

Du kan dock förenkla anropet till AutoFormat avsevärt med hjälp av namngivna och valfria argument. Med namngivna och valfria argument kan du utelämna argumentet för en valfri parameter om du inte vill ändra parameterns standardvärde. I följande anrop anges ett värde för endast en av de sju parametrarna.

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 );

Mer information och exempel finns i Använda namngivna och valfria argument i Office-programmering och Så här får du åtkomst till Office-interop-objekt med hjälp av C#-funktioner.

Överbelastningsupplösning

Användning av namngivna och valfria argument påverkar överbelastningsmatchning på följande sätt:

• En metod, indexerare eller konstruktor är en kandidat för körning om var och en av dess parametrar antingen är valfria eller motsvarar, efter namn eller position, ett enda argument i anropande instruktion, och det argumentet kan konverteras till parametertypen.
• Om fler än en kandidat hittas tillämpas regler för överbelastningsmatchning för föredragna konverteringar på de argument som uttryckligen anges. Utelämnade argument för valfria parametrar ignoreras.
• Om två kandidater bedöms vara lika bra går preferensen till en kandidat som inte har valfria parametrar för vilka argument utelämnades i anropet. Överbelastningsmatchning föredrar vanligtvis kandidater som har färre parametrar.

Språkspecifikation för C#

Mer information finns i C#-språkspecifikationen. Språkspecifikationen är den slutgiltiga källan för C#-syntax och -användning.