Névvel ellátott és választható argumentumok (C# programozási útmutató)

Az elnevezett argumentumok lehetővé teszik egy paraméter argumentumának megadását úgy, hogy az argumentumot a nevével egyezteti meg, nem pedig a paraméterlistában elfoglalt helyével. Az opcionális argumentumok lehetővé teszik, hogy bizonyos paraméterek argumentumait kihagyja. Mindkét módszer használható metódusokkal, indexelőkkel, konstruktorokkal és meghatalmazottakkal.

Névvel ellátott és nem kötelező argumentumok használata esetén az argumentumok kiértékelése az argumentumlistában való megjelenítés sorrendjében történik, nem pedig a paraméterlistában.

Az elnevezett és választható paraméterek lehetővé teszik a kiválasztott paraméterek argumentumainak megadását. Ez a funkció jelentősen megkönnyíti a COM-felületekre irányuló hívásokat, például a Microsoft Office Automation API-kat.

Nevesített argumentumok

Az elnevezett argumentumok lehetővé teszi az argumentumok sorrendjének és a paraméterek sorrendjének egyeztetését az úgynevezett metódusok paraméterlistáiban. Az egyes paraméterek argumentuma paraméternév alapján adható meg. A rendelés részleteit (például eladó nevét, rendelésszámát és terméknevét) kinyomó függvény meghívható például az argumentumok pozíció szerinti elküldésével a függvény által meghatározott sorrendben.

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

Ha nem emlékszik a paraméterek sorrendjére, de ismeri a nevüket, az argumentumokat bármilyen sorrendben elküldheti.

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

Az elnevezett argumentumok a kód olvashatóságát is javítják az egyes argumentumok jelölőinek azonosításával. Az alábbi példametódusban a sellerName szóköz nem lehet null vagy üres. Mivel mindkettő sellerName sztringtípus productName , az argumentumok pozíció szerinti elküldése helyett érdemes elnevezett argumentumokat használni a kettő egyértelműsítéséhez, és csökkenteni a kód olvasói számára a keveredést.

A névvel ellátott argumentumok pozícióargumentumokkal való használata esetén mindaddig érvényesek, amíg

• nem követik őket pozícióargumentumok, vagy

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

• a megfelelő pozícióban használják őket. Az alábbi példában a paraméter orderNum a megfelelő pozícióban van, de nincs explicit módon elnevezve.

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

A sorrenden kívüli névvel ellátott argumentumokat követő pozícióargumentumok érvénytelenek.

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

Példa

Az alábbi kód az ebből a szakaszból származó példákat és néhány továbbiat implementálja.

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

Választható argumentumok

A metódusok, konstruktorok, indexelők vagy delegáltak definíciója megadhatja, hogy milyen paraméterek szükségesek vagy nem kötelezőek. Minden hívásnak argumentumokat kell megadnia az összes szükséges paraméterhez, de kihagyhatja az opcionális paraméterek argumentumait.

Minden választható paraméternek van egy alapértelmezett értéke a definíció részeként. Ha nem küld argumentumot a paraméterhez, a rendszer az alapértelmezett értéket használja. Az alapértelmezett értéknek a következő típusú kifejezések egyikének kell lennie:

• állandó kifejezés;
• az űrlap new ValType()kifejezése, ahol ValType értéktípus, például szám vagy struktúra;
• az alapértelmezett (ValType) űrlap kifejezése, ahol ValType egy értéktípus van.

A választható paraméterek a paraméterlista végén, a szükséges paraméterek után vannak definiálva. Ha a hívó argumentumot ad meg az opcionális paraméterek bármelyik sorozatához, az összes előző opcionális paraméterhez meg kell adnia argumentumokat. Az argumentumlistában lévő vesszővel tagolt rések nem támogatottak. A következő kódban például a példánymetódus ExampleMethod egy kötelező és két választható paraméterrel van definiálva.

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

A következő hívás ExampleMethod fordítóhibát okoz, mert a harmadik paraméter argumentumot ad meg, a másodikhoz nem.

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

Ha azonban ismeri a harmadik paraméter nevét, egy elnevezett argumentumot használhat a feladat végrehajtásához.

anExample.ExampleMethod(3, optionalint: 4);

Az IntelliSense zárójelekkel jelzi a választható paramétereket, ahogy az az alábbi ábrán is látható:

Feljegyzés

Az opcionális paramétereket a .NET-osztály OptionalAttribute használatával is deklarálhatja. OptionalAttribute a paraméterek nem igényelnek alapértelmezett értéket. Ha azonban alapértelmezett értékre van szükség, tekintse meg az osztályt DefaultParameterValueAttribute .

Példa

Az alábbi példában a konstruktornak ExampleClass egy paramétere van, ami nem kötelező. A példánymetódus ExampleMethod egy kötelező paramétert és requiredkét választható paramétert optionalstr és optionalint. A kód a Main konstruktor és a metódus meghívásának különböző módjait mutatja be.

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

Az előző kód számos példát mutat be, ahol a választható paraméterek nem megfelelően vannak alkalmazva. Az első szemlélteti, hogy az első paraméterhez argumentumot kell megadni, ami szükséges.

Hívóinformációs attribútumok

Az olyan hívóinformációs attribútumok, mint például CallerFilePathAttributea , CallerLineNumberAttribute, CallerMemberNameAttributeés CallerArgumentExpressionAttribute, a hívóval kapcsolatos információk egy metódushoz való lekérésére szolgálnak. Ezek az attribútumok különösen hasznosak a hibakeresés során, vagy ha naplóznia kell a metódushívásokkal kapcsolatos információkat.

Ezek az attribútumok választható paraméterek, amelyek alapértelmezett értékeit a fordító adja meg. A hívó nem adhat meg explicit módon értéket ezekhez a paraméterekhez.

COM-felületek

A nevesített és választható argumentumok, valamint a dinamikus objektumok támogatása jelentősen javítja a COM API-kkal, például az Office Automation API-kkal való interoperabilitást.

A Microsoft Office Excel Range felületén például AutoFormat hét paraméter található, amelyek mindegyike nem kötelező. Ezek a paraméterek az alábbi ábrán láthatók:

A meghívást AutoFormat azonban jelentősen leegyszerűsítheti nevesített és választható argumentumok használatával. Az elnevezett és nem kötelező argumentumok lehetővé teszik, hogy kihagyja az opcionális paraméter argumentumát, ha nem szeretné módosítani a paraméter alapértelmezett értékét. A következő hívásban a hét paraméter közül csak egyhez van megadva érték.

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

További információkért és példákért lásd : Elnevezett és választható argumentumok használata az Office-programozásban és az Office-objektumok elérése A C#-funkciók használatával.

Túlterhelés feloldás

Az elnevezett és választható argumentumok használata az alábbi módokon befolyásolja a túlterhelés feloldását:

• A metódusok, indexelők vagy konstruktorok akkor használhatók végrehajtásra, ha az egyes paraméterek nem kötelezőek, vagy név vagy pozíció szerint egy argumentumnak felelnek meg a hívó utasításban, és az argumentum átalakítható a paraméter típusára.
• Ha egynél több jelöltet talál, a rendszer a kifejezetten megadott argumentumokra alkalmazza az előnyben részesített konverziók túlterhelés-feloldási szabályait. Az opcionális paraméterek kihagyott argumentumai figyelmen kívül lesznek hagyva.
• Ha két jelöltet egyformán jónak ítélnek, előnyben részesítik azokat a jelölteket, akik nem rendelkeznek olyan választható paraméterekkel, amelyek argumentumait kihagyták a hívásban. A túlterhelés feloldása általában a kevesebb paramétert tartalmazó jelölteket részesíti előnyben.

C# nyelvspecifikáció

További információkért lásd a C# nyelvi specifikációját. A nyelvi specifikáció a C#-szintaxis és -használat végleges forrása.