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

Le mot clé in entraîne le passage des arguments par référence.The in 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 aux mots clés ref ou out, sauf que les arguments in ne peuvent pas être modifiés par la méthode appelée.It is like the ref or out keywords, except that in arguments cannot be modified by the called method. Alors que la modification des arguments ref est facultative, les arguments out doivent être modifiés par la méthode appelée ; ces modifications sont observables dans le contexte d’appel.Whereas ref arguments may be modified, out arguments must be modified by the called method, and those modifications are observable in the calling context.

int readonlyArgument = 44;
InArgExample(readonlyArgument);
Console.WriteLine(readonlyArgument);     // value is still 44

void InArgExample(in int number)
{
    // Uncomment the following line to see error CS8331
    //number = 19;
}

L’exemple précédent montre que le modificateur in n’est généralement pas nécessaire sur le site d’appel.The preceding example demonstrates that the in modifier is usually unnecessary at the call site. Il l’est uniquement dans la déclaration de méthode.It is only required in the method declaration.

Notes

Le mot clé in peut également être utilisé avec un paramètre de type générique pour spécifier que le paramètre de type est contravariant, dans le cadre d’une instruction foreach ou d’une clause join dans une requête LINQ.The in keyword can also be used with a generic type parameter to specify that the type parameter is contravariant, as part of a foreach statement, or as part of a join clause in a LINQ query. Pour plus d’informations sur l’utilisation du mot clé in dans ces contextes, consultez in, qui fournit des liens vers toutes ces utilisations.For more information on the use of the in keyword in these contexts, see in, which provides links to all those uses.

Les variables passées comme des arguments in doivent être initialisées avant d’être passées dans un appel de méthode.Variables passed as in arguments must be initialized before being passed in a method call. Toutefois, la méthode appelée ne peut pas attribuer de valeur ou modifier l’argument.However, the called method may not assign a value or modify the argument.

Le modificateur de paramètre in est disponible dans C# 7.2 et versions ultérieures.The in parameter modifier is available in C# 7.2 and later. Les versions précédentes génèrent une erreur de compilateur CS8107 (« La fonctionnalité "références en lecture seule" n’est pas disponible dans C# 7.0.Previous versions generate compiler error CS8107 ("Feature 'readonly references' is not available in C# 7.0. Utilisez la version 7.2 ou supérieure du langage. » Pour configurer la version du langage du compilateur, consultez Sélectionner la version du langage C#.Please use language version 7.2 or greater.") To configure the compiler language version, see Select the C# language version.

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 in, ref and out".
    public void SampleMethod(in int i) { }
    public void SampleMethod(ref int i) { }
}

Une surcharge basée sur la présence de in est autorisée :Overloading based on the presence of in is allowed:

class InOverloads
{
    public void SampleMethod(in int i) { }
    public void SampleMethod(int i) { }
}

Règles de résolution de surchargeOverload resolution rules

Vous pouvez comprendre les règles de résolution de surcharge pour les méthodes par valeur par rapport à celles qui utilisent des arguments in en comprenant pourquoi on utilise des arguments in.You can understand the overload resolution rules for methods with by value vs. in arguments by understanding the motivation for in arguments. Vous pouvez optimiser les performances en définissant des méthodes à l’aide de paramètres in.Defining methods using in parameters is a potential performance optimization. Certains arguments de type struct peuvent être volumineux et, quand les méthodes sont appelées dans des boucles serrées ou des chemins de code critiques, le coût de la copie de ces structures est crucial.Some struct type arguments may be large in size, and when methods are called in tight loops or critical code paths, the cost of copying those structures is critical. Les méthodes déclarent des paramètres in pour spécifier que des arguments peuvent être passés par référence en toute sécurité, car la méthode appelée ne modifie pas l’état de l’argument.Methods declare in parameters to specify that arguments may be passed by reference safely because the called method does not modify the state of that argument. Le passage de ces arguments par référence permet d’éviter une copie (potentiellement) coûteuse.Passing those arguments by reference avoids the (potentially) expensive copy.

La spécification de in pour des arguments au niveau de l’appel de site est généralement facultative.Specifying in for arguments at the call site is typically optional. Il n’existe aucune différence sémantique entre le passage d’arguments par valeur et leur passage par référence à l’aide du modificateur in.There is no semantic difference between passing arguments by value and passing them by reference using the in modifier. Le modificateur in sur le site d’appel est facultatif, car vous n’avez pas besoin d’indiquer que la valeur de l’argument peut être changée.The in modifier at the call site is optional because you don't need to indicate that the argument's value might be changed. Vous ajoutez explicitement le modificateur in sur le site d’appel pour vérifier que l’argument est passé par référence, non par valeur.You explicitly add the in modifier at the call site to ensure the argument is passed by reference, not by value. L’utilisation explicite de in a les deux effets suivants :Explicitly using in has the following two effects:

Tout d’abord, la spécification de in sur le site d’appel force le compilateur à sélectionner une méthode définie avec un paramètre in correspondant.First, specifying in at the call site forces the compiler to select a method defined with a matching in parameter. Sinon, quand deux méthodes diffèrent uniquement par la présence de in, la surcharge par valeur convient mieux.Otherwise, when two methods differ only in the presence of in, the by value overload is a better match.

Ensuite, la spécification de in déclare votre intention de passer un argument par référence.Second, specifying in declares your intent to pass an argument by reference. L’argument utilisé avec in doit représenter un emplacement directement référençable.The argument used with in must represent a location that can be directly referred to. Les mêmes règles générales pour les arguments out et ref s’appliquent : vous ne pouvez pas utiliser de constantes, de propriétés ordinaires ou d’autres expressions qui produisent des valeurs.The same general rules for out and ref arguments apply: You cannot use constants, ordinary properties, or other expressions that produce values. Sinon, l’omission de in sur le site d’appel informe le compilateur que vous l’autorisez à créer une variable temporaire à passer par référence en lecture seule à la méthode.Otherwise, omitting in at the call site informs the compiler that you will allow it to create a temporary variable to pass by read-only reference to the method. Le compilateur crée une variable temporaire pour surmonter plusieurs restrictions avec les arguments in :The compiler creates a temporary variable to overcome several restrictions with in arguments:

  • Une variable temporaire autorise des constantes au moment de la compilation comme paramètres in.A temporary variable allows compile-time constants as in parameters.
  • Une variable temporaire autorise des propriétés ou d’autres expressions pour les paramètres in.A temporary variable allows properties, or other expressions for in parameters.
  • Une variable temporaire autorise des arguments pour lesquels il existe une conversion implicite de type d’argument en type de paramètre.A temporary variable allows arguments where there is an implicit conversion from the argument type to the parameter type.

Dans toutes les instances précédentes, le compilateur crée une variable temporaire qui stocke la valeur de la constante, la propriété ou une autre expression.In all the preceding instances, the compiler creates a temporary variable that stores the value of the constant, property, or other expression.

Le code suivant illustre ces règles :The following code illustrates these rules:

static void Method(in int argument)
{
    // implementation removed
}

Method(5); // OK, temporary variable created.
Method(5L); // CS1503: no implicit conversion from long to int
short s = 0;
Method(s); // OK, temporary int created with the value 0
Method(in s); // CS1503: cannot convert from in short to in int
int i = 42;
Method(i); // passed by readonly reference
Method(in i); // passed by readonly reference, explicitly using `in`

Supposons à présent qu’une autre méthode utilisant des arguments par valeur est disponible.Now, suppose another method using by value arguments was available. Les résultats changent comme illustré dans le code suivant :The results change as shown in the following code:

static void Method(int argument)
{
    // implementation removed
}

static void Method(in int argument)
{
    // implementation removed
}

Method(5); // Calls overload passed by value
Method(5L); // CS1503: no implicit conversion from long to int
short s = 0;
Method(s); // Calls overload passed by value.
Method(in s); // CS1503: cannot convert from in short to in int
int i = 42;
Method(i); // Calls overload passed by value
Method(in i); // passed by readonly reference, explicitly using `in`

Le seul appel de méthode dans lequel l’argument est passé par référence est le dernier.The only method call where the argument is passed by reference is the final one.

Notes

Le code précédent utilise int comme type d’argument par souci de simplicité.The preceding code uses int as the argument type for simplicity. Comme int n’est pas plus volumineux qu’une référence dans la plupart des ordinateurs modernes, il n’y aucun avantage à passer un seul int comme référence en lecture seule.Because int is no larger than a reference in most modern machines, there is no benefit to passing a single int as a readonly reference.

Limitations sur les paramètres inLimitations on in 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.

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