Arguments nommés et facultatifs (Guide de programmation C#)

Les arguments nommés vous évitent d'avoir à mémoriser ou à rechercher l'ordre des paramètres dans les listes de paramètres des méthodes appelées. Le paramètre de chaque argument peut être spécifié par son nom. Par exemple, une fonction qui calcule l'indice de masse corporelle (IMC) peut être appelée de la façon standard par l'envoi d'arguments pour le poids et la hauteur par position, dans l'ordre défini par la fonction.

CalculateBMI(123, 64);

Si vous ne vous souvenez pas de l'ordre des paramètres, mais que vous connaissez leur nom, vous pouvez envoyer les arguments dans n'importe quel ordre (le poids ou la hauteur en premier).

CalculateBMI(weight: 123, height: 64);

CalculateBMI(height: 64, weight: 123);

Les arguments nommés améliorent également la lisibilité de votre code en identifiant ce que chaque argument représente.

Un argument nommé peut suivre des arguments de position, comme illustré ici.

CalculateBMI(123, height: 64);

Toutefois, un argument de position ne peut pas suivre un argument nommé. L'instruction suivante entraîne une erreur du compilateur.

//CalculateBMI(weight: 123, 64);

Le code suivant implémente les exemples de cette section.

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

La définition d'une méthode, d'un constructeur, d'un indexeur ou d'un délégué peut spécifier que ses paramètres sont obligatoires ou optionnels. Tout appel doit fournir des arguments pour tous les paramètres obligatoires, mais peut omettre les arguments des paramètres optionnels.

Chaque paramètre optionnel est associé à une valeur par défaut dans le cadre de sa définition. Si aucun argument n'est envoyé pour ce paramètre, la valeur par défaut est utilisée. une valeur par défaut doit être l'un des types suivants d'expressions :

• une expression constante ;

• une expression du formulaire new ValType(), où ValType est un type valeur, tel qu' enum ou struct;

• une expression du formulaire valeur par défaut (ValType), où ValType est un type valeur.

Les paramètres optionnels sont définis à la fin de la liste de paramètres, après tous les paramètres obligatoires. Si l'appelant fournit un argument pour l'un des paramètres d'une suite de paramètres optionnels, il doit spécifier des arguments pour tous les paramètres optionnels précédents. Les intervalles séparés par des virgules ne sont pas pris en charge dans la liste d'arguments. Par exemple, dans le code suivant, la méthode d'instance ExampleMethod est définie avec un paramètre obligatoire et deux paramètres optionnels.

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

L'appel suivant à ExampleMethod provoque une erreur du compilateur, car un argument est fourni pour le troisième paramètre mais pas pour le deuxième.

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

Toutefois, si vous connaissez le nom du troisième paramètre, vous pouvez utiliser un argument nommé pour effectuer la tâche.

anExample.ExampleMethod(3, optionalint: 4);

IntelliSense utilise des parenthèses pour signaler les paramètres optionnels, comme illustré ci-après.

Remarque
Vous pouvez également déclarer des paramètres optionnels à l'aide de la classe OptionalAttribute .NET. Les paramètres OptionalAttribute ne requièrent pas de valeur par défaut.

Dans l'exemple suivant, le constructeur associé à ExampleClass comporte un paramètre, qui est optionnel. La méthode d'instance ExampleMethod comporte un paramètre obligatoire, required, et deux paramètres optionnels, optionalstr et optionalint. Le code de Main illustre les différentes façons dont le constructeur et la méthode peuvent être appelés.

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.

}

Avec la prise en charge des objets dynamiques et d'autres améliorations, les arguments nommés et facultatifs améliorent considérablement l'interopérabilité avec les API COM, telles que les API d'automation Office.

Par exemple, la méthode AutoFormat dans l'interface Microsoft Office Excel Range comporte sept paramètres qui sont tous optionnels. Ces paramètres sont indiqués dans l'illustration suivante.

Dans la version C# 3.0 et les versions antérieures, un argument est obligatoire pour chaque paramètre, comme indiqué dans l'exemple suivant.

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

Toutefois, vous pouvez simplifier considérablement l'appel à AutoFormat à l'aide des arguments nommés et optionnels introduits dans la version C# 4.0. Les arguments nommés et optionnels vous permettent d'omettre l'argument pour un paramètre optionnel si vous ne souhaitez pas modifier la valeur par défaut du paramètre. Dans l'appel suivant, une valeur est spécifiée pour un seul des sept paramètres.

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

Pour plus d'informations et d'exemples, consultez Comment : utiliser des arguments nommés et facultatifs dans la programmation Office (Guide de programmation C#) et Comment : accéder aux objets Office Interop à l'aide des fonctionnalités Visual C# 2010 (Guide de programmation C#).

L'utilisation des arguments nommés et facultatifs affecte la résolution de surcharge de différentes manières :

• Une méthode, un indexeur ou un constructeur est candidat pour l'exécution si d'une part, chacun de ses paramètres est optionnel ou correspond, par nom ou par position, à un argument unique de l'instruction appelante et que d'autre part, cet argument peut être converti vers le type du paramètre.

• Si plusieurs candidats existent, les règles de résolution de surcharge des conversions par défaut sont appliquées aux arguments qui sont explicitement spécifiés. Les arguments omis pour les paramètres optionnels sont ignorés.

• Si deux candidats sont jugés aussi appropriés l'un que l'autre, la préférence va à celui qui ne comporte pas de paramètres optionnels pour lesquels les arguments ont été omis dans l'appel. Cela s'explique par une préférence générale, dans la résolution de surcharge, en faveur des candidats comportant moins de paramètres.

Pour plus d'informations, consultez la Spécification du langage C#. La spécification du langage est la source de référence pour la syntaxe C# et son utilisation.

Tâches

Référence

Autres ressources