out, modificateur de paramètre (référence C#)out parameter modifier (C# Reference)

Le mot clé out entraîne le passage des arguments par référence.The out keyword causes arguments to be passed by reference. Il fait du paramètre formel un alias de l’argument, qui doit être une variable.It makes the formal parameter an alias for the argument, which must be a variable. En d’autres termes, toute opération portant sur le paramètre est effectuée sur l’argument.In other words, any operation on the parameter is made on the argument. Il est similaire au mot clé ref, à la différence que ref nécessite que la variable soit initialisée avant d’être passée.It is like the ref keyword, except that ref requires that the variable be initialized before it is passed. Il est également similaire au mot clé in, à la différence que in n’autorise pas la méthode appelée à modifier la valeur d’argument.It is also like the in keyword, except that in does not allow the called method to modify the argument value. Pour utiliser un paramètre out, la définition de la méthode et la méthode d'appel doivent utiliser explicitement le mot clé out.To use an out parameter, both the method definition and the calling method must explicitly use the out keyword. Par exemple :For example:

int initializeInMethod;
OutArgExample(out initializeInMethod);
Console.WriteLine(initializeInMethod);     // value is now 44

void OutArgExample(out int number)
{
    number = 44;
}

Notes

Le mot clé out peut également être utilisé avec un paramètre de type générique pour spécifier que le paramètre de type est covariant.The out keyword can also be used with a generic type parameter to specify that the type parameter is covariant. Pour plus d’informations sur l’utilisation du mot clé out dans ce contexte, consultez out, modificateur générique.For more information on the use of the out keyword in this context, see out (Generic Modifier).

Les variables passées comme arguments out n’ont pas à être initialisées avant d’être passées dans un appel de méthode.Variables passed as out arguments do not have to be initialized before being passed in a method call. Toutefois, la méthode appelée doit assigner une valeur avant le retour de la méthode.However, the called method is required to assign a value before the method returns.

Les mots clés in, ref et out ne sont pas considérés comme faisant partie de la signature de méthode à des fins de résolution de surcharge.The in, ref, and out keywords are not considered part of the method signature for the purpose of overload resolution. Par conséquent, les méthodes ne peuvent pas être surchargées si la seule différence est que l’une d’elles accepte un argument ref ou in et que l’autre accepte un argument out.Therefore, methods cannot be overloaded if the only difference is that one method takes a ref or in argument and the other takes an out argument. Le code suivant, par exemple, ne se compilera pas :The following code, for example, will not compile:

class CS0663_Example
{
    // Compiler error CS0663: "Cannot define overloaded 
    // methods that differ only on ref and out".
    public void SampleMethod(out int i) { }
    public void SampleMethod(ref int i) { }
}

Toutefois, la surcharge est autorisée si une méthode prend un argument ref, in ou out, et que l’autre méthode n’a aucun de ces modificateurs, comme suit :Overloading is legal, however, if one method takes a ref, in, or out argument and the other has none of those modifiers, like this:

class OutOverloadExample
{
    public void SampleMethod(int i) { }
    public void SampleMethod(out int i) => i = 5;
}

Le compilateur choisit la meilleure surcharge en mettant en correspondance les modificateurs de paramètre sur le site d’appel et les modificateurs de paramètre utilisés dans l’appel de méthode.The compiler chooses the best overload by matching the parameter modifiers at the call site to the parameter modifiers used in the method call.

Les propriétés ne sont pas des variables et, par conséquent, ne peuvent pas être passées en tant que paramètres out.Properties are not variables and therefore cannot be passed as out parameters.

Vous ne pouvez pas utiliser les mots clés in, ref ou out pour les types de méthodes suivants :You can't use the in, ref, and out keywords for the following kinds of methods:

  • Méthodes async, que vous définissez à l’aide du modificateur async.Async methods, which you define by using the async modifier.

  • Les méthodes Iterator, qui incluent une instruction yield return ou yield break.Iterator methods, which include a yield return or yield break statement.

Déclarer des paramètres outDeclaring out parameters

Il arrive souvent que l’on déclare une méthode avec des arguments out pour qu’elle retourne plusieurs valeurs.Declaring a method with out arguments is a classic workaround to return multiple values. À compter de C# 7.0, vous pouvez recourir aux tuples dans ce type de scénario.Beginning with C# 7.0, consider tuples for similar scenarios. L'exemple suivant utilise out pour retourner trois variables avec un seul appel de méthode.The following example uses out to return three variables with a single method call. Notez que le troisième argument reçoit la valeur null.Note that the third argument is assigned to null. Cela permet aux méthodes de retourner des valeurs le cas échéant.This enables methods to return values optionally.

void Method(out int answer, out string message, out string stillNull)
{
    answer = 44;
    message = "I've been returned";
    stillNull = null;
}

int argNumber;
string argMessage, argDefault;
Method(out argNumber, out argMessage, out argDefault);
Console.WriteLine(argNumber);
Console.WriteLine(argMessage);
Console.WriteLine(argDefault == null);

// The example displays the following output:
//      44
//      I've been returned
//      True

Appel d’une méthode avec un argument outCalling a method with an out argument

Dans C# 6 et les versions antérieures, vous devez déclarer une variable dans une instruction distincte avant de la passer comme argument out.In C# 6 and earlier, you must declare a variable in a separate statement before you pass it as an out argument. L’exemple suivant déclare une variable nommée number avant de la passer à la méthode Int32.TryParse, qui tente de convertir une chaîne en nombre.The following example declares a variable named number before it is passed to the Int32.TryParse method, which attempts to convert a string to a number.

string numberAsString = "1640";

int number;
if (Int32.TryParse(numberAsString, out number))
    Console.WriteLine($"Converted '{numberAsString}' to {number}");
else
    Console.WriteLine($"Unable to convert '{numberAsString}'");
// The example displays the following output:
//       Converted '1640' to 1640

À compter de C# 7.0, vous pouvez déclarer la variable out dans la liste d’arguments de l’appel de méthode au lieu de le faire dans une déclaration de variable distincte.Starting with C# 7.0, you can declare the out variable in the argument list of the method call, rather than in a separate variable declaration. Cette technique rend le code plus simple et plus lisible, et vous empêche également d’assigner par inadvertance une valeur à la variable avant l’appel de méthode.This produces more compact, readable code, and also prevents you from inadvertently assigning a value to the variable before the method call. L’exemple suivant est semblable au précédent, sauf qu’il définit la variable number dans l’appel de la méthode Int32.TryParse.The following example is like the previous example, except that it defines the number variable in the call to the Int32.TryParse method.

string numberAsString = "1640";

if (Int32.TryParse(numberAsString, out int number))
    Console.WriteLine($"Converted '{numberAsString}' to {number}");
else
    Console.WriteLine($"Unable to convert '{numberAsString}'");
// The example displays the following output:
//       Converted '1640' to 1640

Dans l’exemple précédent, la variable number est fortement typée en int.In the previous example, the number variable is strongly typed as an int. Vous pouvez également déclarer une variable locale implicitement typée, comme dans l’exemple suivant.You can also declare an implicitly typed local variable, as the following example does.

string numberAsString = "1640";

if (Int32.TryParse(numberAsString, out var number))
    Console.WriteLine($"Converted '{numberAsString}' to {number}");
else
    Console.WriteLine($"Unable to convert '{numberAsString}'");
// The example displays the following output:
//       Converted '1640' to 1640

Spécification du langage C#C# Language Specification

Pour plus d'informations, voir la spécification du langage C#.For more information, see the C# Language Specification. La spécification du langage est la source de référence pour la syntaxe C# et son utilisation.The language specification is the definitive source for C# syntax and usage.

Voir aussiSee also