A partir de C# 7.0, il est possible d’effectuer des passages d’arguments d’objets de type valeur par référence. En effet, par défaut le passage d’objets de type valeur en argument de fonction se fait par valeur c’est-à-dire que les objets sont copiés lors de l’appel de fonction. L’utilisation du mot-clé ref dans un argument de fonction permet de passer un objet de type valeur par référence.

Techniquement lors du passage d’un objet de type valeur par référence, la référence passée en argument correspond à un objet permettant de pointer vers l’objet dans la pile. Il n’y a pas de boxing.

Par exemple, si on considère l’exemple suivant:

public struct Circle 
{ 
  public int Radius { get; set; } 
} 

private static void ChangeRadius(int newRadius, Circle circle) 
{ 
  circle.Radius = newRadius; 
} 

static void Main() 
{ 
  var circle = new Circle{ Radius = 4 }; 
  Console.WriteLine(circle.Radius); // 4 
  ChangeRadius(2, circle); // circle est dupliquée 
  Console.WriteLine(circle.Radius); // 4 
} 

Cet exemple ne fonctionne pas, la valeur de la propriété Radius est bien modifiée par ChangeRadius() toutefois il modifie la propriété d’une copie de l’objet d’origine. L’instance circle d’origine n’est pas modifiée.

Si on passe l’objet circle par référence, il n’y aura pas de copie et l’instance circle est réellement modifiée:

private static void ChangeRadius(int newRadius, ref Circle circle) 
{ 
  circle.Radius = newRadius; 
} 

static void Main() 
{ 
  var circle = new Circle{ Radius = 4 }; 
  Console.WriteLine(circle.Radius); // 4 
  ChangeRadius(2, ref circle); // circle est passé par référence 
  Console.WriteLine(circle.Radius); // 2 
} 

Si on regarde plus en détails l’implémentation:

• ref désigne un objet permettant de pointer vers un objet de type valeur, ainsi la signature de la méthode ChangeRadius() comprend l’argument ref Circle circle. Le type est donc une référence vers un objet de type valeur Circle.
• L’appel vers la méthode ChangeRadius() doit être modifié puisqu’il faut utiliser une référence et non directement le type valeur: ChangeRadius(2, ref circle).

Lors du passage d’argument, utiliser ref pour des objets de type référence permet d’éviter la copie de la référence vers l’objet. En effet, la plupart du temps, les objets de type référence sont manipulés par référence, ainsi si on considère la classe suivante:

class Square 
{ 
  public int Size { get; set; } 
} 

var square = new Square { Size = 4 }; 

La variable square contient une référence vers un objet de type Square stocké dans le tas managé. La référence est un objet de type valeur bien que l’objet référencé est de type référence. La référence est stockée dans la pile alors que l’objet référencé est stockée dans le tas managé. Si on écrit:

var newSquare = square; // Copie de la référence 

Une nouvelle variable est créée et initialisée avec une copie de la référence vers l’objet newSquare. L’objet référencée n’est pas copié, seule la référence est copiée.

Ainsi si on considère la méthode suivante:

public static void IncreaseSize(Square square) 
{ 
  square.Size++; 
} 

Si on effectue un appel de ce type:

var initialSquare = new Square { Size = 2 }; 
IncreaseSize(initialSquare); 
Console.WriteLine(initialSquare.Size); // 3 

L’argument square contient une référence vers un objet de type Square. Lors de l’appel, la référence initialSquare est copiée dans l’argument square. Lorsqu’on manipule l’objet référencé avec square.Size, on manipule directement l’objet. Si on effectue une affectation à l’intérieur de la fonction sur l’argument square, l’objet initial n’est pas modifié et la variable otherSquare contient une référence vers l’objet initial:

public static void IncreaseSize(Square square) 
{ 
  square  = new Square{ Size = 8 }; // Création d'un nouvel objet et d'une nouvelle référence 
} 

var initialSquare = new Square { Size = 2 }; 
IncreaseSize(initialSquare); 
Console.WriteLine(initialSquare.Size); // 2 

Si on utilise ref dans l’argument de IncreaseSize(), on indique qu’on ne veut pas dupliquer la référence mais passer la référence en argument par référence:

public static void IncreaseSize(ref Square square) 
{ 
  square  = new Square{ Size = 8 }; // Création d'un nouvel objet et affectation à la référence existante 
} 

var initialSquare = new Square { Size = 2 }; 
IncreaseSize(ref initialSquare); // La référence n'est pas copiée 
Console.WriteLine(initialSquare.Size); // 8 

Dans cet exemple, la référence est passée par référence. La référence n’est donc pas copiée lors du passage en argument. Modifier la référence dans le corps de la méthode, va entraîner la modification de la référence à l’extérieur de la méthode.

A chaque nouvelle affectation, les objets de type valeur sont copiés.

Par exemple:

var circle = new Circle { Radius = 4 }; 
var newCircle = circle; // Duplication de l’objet 
circle.Radius = 2; 
Console.WriteLine(circle.Radius); // 2 
Console.WriteLine(newCircle.Radius); // 4 

L’affection, le passage d’argument ou le retour de fonction sont des opérations qui effectuent une copie par valeur d’un objet de type valeur. L’affectation var newCircle = circle crée une nouvelle instance newCircle qui est une copie de l’instance circle.

L’affectation d’une nouvelle propriété Radius sur l’instance circle ne modifie pas l’instance newCircle puisqu’il s’agit d’objets différents.

A partir de C# 7.0, il est possible de manipuler des variables locales d’objet de type valeur par référence. Ainsi, les affectations effectuent une copie de référence au lieu d’effectuer une copie par valeur.

Si on reprends l’exemple précédent, il faut déclarer une référence d’un objet de type valeur:

var circle = new Circle { Radius = 4 }; 
ref var circleRef = ref circle; // On considère la référence de l’objet 
circleRef.Radius = 2; 
Console.WriteLine(circle.Radius); // 2 
Console.WriteLine(circleRef.Radius); // 2 

Si on regarde plus en détails la syntaxe de l’exemple:

• var circle désigne un objet de type valeur Circle.
• ref var circleRef désigne une référence vers un objet de type valeur Circle, ainsi les lignes:
  • var circle = new Circle { Radius = 4 } permet d’instancier un objet de type Circle.
  • ref circle permet de récupérer une référence vers l’objet circle dans la pile (i.e. stack). Plus précisemment, cet objet se trouve dans la stack frame de la méthode. Cette stack frame et les objets qu’elle contient existent tant que la méthode existe.

A chaque fois, qu’on manipule une référence d’un objet de type valeur, il faut penser à utiliser le mot-clé ref, par exemple si on écrit:

Circle firstCircle = new Circle { Radius = 2 }; // Initialisation 
Circle secondCircle = new Circle { Radius = 4 }; // Initialisation 
ref Circle firstCircleRef = ref firstCircle;
ref Circle secondCircleRef = ref secondCircle;
secondCircleRef = firstCircleRef; // Affectation par valeur, une copie est effectuée 

Même si firstCircleRef et secondCircleRef sont définis avec ref Circle, la dernière affectation effectue une copie par valeur. Pour manipuler les références, il faut utiliser ref (disponible à partir de C# 7.3):

secondCircleRef = ref firstCircleRef; // Affectation par référence (C# 7.3) 

Avant C# 7.3, il n’est pas possible d’effectuer l’affectation d’une référence vers un objet de type valeur sur une variable existante, seules les initialisations sont possibles:

ref Circle otherFirstCircleRef = ref firstCircleRef; 

A partir de C# 7.2, il est possible d’indiquer que le membre d’une variable locale manipulée par référence n’est pas modifiable en déclarant la variable avec ref readonly. Ainsi si une variable est déclarée avec ref readonly, ses membres éventuels ne seront utilisables qu’en lecture seule, toute tentative d’affectation d’un membre conduira à une erreur de compilation:

var circle = new Circle { Radius = 4 };
ref readonly var readOnlyCircleRef = ref circle; // Initialisation d'une variable par référence en lecture seule

readOnlyCircleRef.Radius = 2; // ERREUR: modification d'un membre est non autorisée

La variable en lecture seule est, toutefois, réaffectable:

var otherCircle = new Circle { Radius = 2 };

readonlyCircleRef = ref otherCircle; // OK autorisée
readonlyCircleRef.Radius = 4; // ERREUR

Une variable déclarée avec ref readonly ne peut pas être passé en argument d’une méthode par référence. Si on considère la méthode:

void ChangeRadius(ref Circle circleToUpdate) {}

// ...
ChangeRadius(ref readonlyCircleRef); // ERREUR

Lors de l’initialisation de la variable locale avec ref readonly, la valeur d’initialisation utilisée peut aussi correspondre à un paramètre in d’une méthode, par exemple:

static void PrintCircleRadius(in Circle circle)
{
  ref readonly var readOnlyCircle = ref circle; // OK
  Console.WriteLine(readOnlyCircle.Radius);
}

Si une variable déclarée par référence est initialisée avec le membre d’un objet déclaré avec ref readonly ou avec le retour d’une fonction de type ref readonly T alors la variable doit être déclarée avec ref readonly.
Par exemple, si on considère la classe suivante:

class CircleWrapper
{
  private ref readonly circle = new Circle { Radius = 4 };

  public void PrintCircleRadius()
  {
    ref readonly var readOnlyLocalCircle = ref this.circle; // OK

    ref var localCircle = ref this.circle; // ERREUR
  }
}

Si on considère la méthode suivante:

static Circle circle = new Circle { Radius = 4 };
static ref readonly Circle GetCircle()
{
  return ref circle;
}

Une variable initialisée avec le retour de la fonction doit être de type ref readonly Circle:

ref readonly var circle = GetCircle(); // OK

ref var circle = GetCircle();  // ERREUR

Enfin, la valeur d’initialisation d’une variable déclarée avec ref readonly doit être une LValue c’est-à-dire que la variable doit correspondre à la référence d’un objet nommé. La référence d’un objet nommé signifie qu’une variable désigne cet objet en mémoire.

Par exemple si on écrit:

ref readonly var circle = ref default(Circle); // ERREUR

ref default(Circle) ne correspond pas à la référence d’un objet nommé, il n’y a pas une variable appelée default(Circle) correspondant à un objet en mémoire. Il s’agit d’une valeur sans variable associée.

var circle = new Circle();
ref readonly var circleRef = ref circle; // Une copie est effectuée

struct readonly ImmutableCircle
{
  public int Radius { get; }

  void Circle(int radius)
  {
    this.Radius = radius;
  }
}

// ...
var circle = new ImmutableCircle(4);
ref readonly var circleRef = ref circle; // OK, le compilateur effectue une optimisation

A partir de C# 7.0, il est possible de retourner la référence d’un objet de type valeur. Toutefois tout n’est pas possible car techniquement il faut comprendre ce que signifie retourner la référence d’un objet de type valeur.

Ainsi, comme on a pu le voir précédemment, les arguments d’une fonction, ses variables locales et sa valeur de retour sont stockés dans la stack frame de la fonction. Cette stack frame disparaît lorsqu’on quitte la fonction. Par exemple, si on retourne une référence d’une variable locale de type valeur, après exécution de la fonction la référence ne correspondra plus à l’objet retourné puisque la stack frame de la fonction est perdue.

Retourner une référence vers un objet de type valeur est possible si la référence reste disponible à la sortie de la fonction. Ceci est possible si:

• L’objet de type valeur est un membre d’un objet de type référence: dans ce cas il est stockée dans le tas managé et non dans la pile. La référence reste disponible à la sortie de la fonction.
• L’objet de type valeur est statique: il n’est pas stocké dans la pile mais dans un tas particulier (loader heap ou high frequency heap). La référence vers l’objet statique de type valeur reste disponible à la sortie de la fonction.

Par exemple, si on considère l’exemple suivant:

public static ref Circle FindCircle(Circle[] circles, int circleIndex) 
{ 
  return ref circles[circeIndex]; 
} 

static void Main() 
{ 
  Circle[] circles = { 
    new Circle { Radius = 4 }, 
    new Circle { Radius = 2 } 
  }; 
 
  ref Circle foundCircle = ref FindCircle(circles, 1); 
  Console.WriteLine(foundCircle.Radius); // 2 
  foundCircle.Radius = 1; 
  Console.WriteLine(circles[1].Radius); // 1 
} 

C’est bien l’objet se trouvant dans le tableau circles qui est modifié et non une copie de l’objet. En effet, le retour de FindCircle() est une référence d’un objet dans le tableau circles.

Liste générique et LINQ

Dans l’exemple plus haut, l’utilisation du tableau Circle[] n’est pas anodine car cette structure permet de manipuler reéllement une référence de l’objet dans le tableau. Si on utilise une liste ou LINQ on manipulera une copie de l’objet dans la liste et non l’objet se trouvant dans la liste:

public static ref Circle FindCircle(List circles, int circleRadius) 
{ 
  return ref circles.First(c => c.Radius.Equals(circleRadius)); // ERROR: 
  // An expression cannot be used in the context because it may not be passed or 
  // returned by reference 
} 

Dans cet exemple, on obtient une erreur de syntaxe car circles.First() effectue une copie de l’objet et ne permet pas de récupérer une référence de l’objet dans la structure.

Pas de référence nulle

Il n’existe pas de référence nulle vers un objet de type valeur, on ne peut donc pas écrire une fonction de ce type:

public static ref Circle FindCircle(Circle[] circles, int circleRadius) 
{ 
  for (int i = 0; i < circles.Length; i++) 
  { 
    ref var foundCircle = ref circles[i]; 
    if (circles[i].Radius.Equals(circleRadius)) 
      return ref foundCircle; 
  } 

  return null; // ERROR: the return expression must be of type 'Circle' 
  // because the method returns by reference. 
} 

La solution peut consister à définir en avance une objet nul pour l’utiliser si le recherche échoue:

public static ref Circle FindCircle(Circle[] circles, int circleRadius, ref Circle notFoundCircle) 
{ 
  for (int i = 0; i < circles.Length; i++) 
  { 
    ref var foundCircle = ref circles[i]; 
    if (circles[i].Radius.Equals(circleRadius)) 
      return ref foundCircle; 
  } 

  return ref notFoundCircle; 
} 

L’appel peut se faire de cette façon:

static void Main() 
{ 
  Circle[] circles = { 
    new Circle { Radius = 4 }, 
    new Circle { Radius = 2 } 
  }; 

  var notFoundCircle = new Circle { Radius = 0 }; 
  ref var notFoundCircleRef = ref notFoundCircle; 

  ref Circle foundCircle = ref FindCircle(circles, 6, ref notFoundCircleRef); 
  if (foundCircle.Equals(notFoundCircleRef)) 
    Console.WriteLine("Not found"); // Not found 
}

Utilisation d’un objet statique

Un objet de type valeur stocké dans une variable statique se trouve techniquement dans un tas particulier (loader heap ou high frequency heap). Il est donc possible d’utiliser une référence vers cet objet statique sans se préoccuper de la durée de vie de la stack frame d’une fonction.

Par exemple:

private static Circle mediumCircle; 

public static ref Circle GetMediumCircle() 
{ 
  return ref mediumCircle; 
} 

static void Main() 
{ 
  mediumCircle = new Circle { Radius = 5 }; 
  ref var foundCircle = ref GetMediumCircle(); 
} 

L’objet mediumCircle n’est pas stocké dans la pile de la fonction GetMediumCircle(), on peut donc retourner une référence vers cet objet.

Utilisation d’un membre d’un objet de type référence

Un objet de type valeur étant un membre d’un objet de type référence est stocké dans le tas managé. On peut donc utiliser une référence vers cet objet de type valeur en retour d’une fonction.

Par exemple:

internal class CircleRepository 
{ 
  public Circle InnerCircle; 
} 

public static ref Circle SetNewRadius(CircleRepository circleRepository, int newRadius) 
{ 
  ref var circle = ref circleRepository.InnerCircle; 
  circle.Radius = newRadius; 
  return ref circle; 
} 

static void Main() 
{ 
  var circleRepo = new CircleRepository{ 
    InnerCircle = new Circle { Radius = 4 } 
  }; 

  ref var updatedCircle = ref SetNewRadius(circleRepo, 2); 
  Console.WriteLine(circleRepo.InnerCircle.Radius); // 2 
} 

Etant donné que InnerCircle est membre de la classe CircleRepository, même s’il s’agit d’un objet de type valeur, il est stocké dans le tas managé. On peut donc manipuler cet objet par référence et l’utiliser en retour de la fonction SetNewRadius().

A partir de C# 7.2, on peut indiquer qu’un objet retourné par une fonction par référence est en lecture seule en utilisant le type de retour ref readonly T:

ref readonly Circle GetCircle();

Le but d’avoir un objet retournée par référence en lecture seule est de sécuriser le code et éviter des modifications involontaires d’un objet.
Par exemple, si on retourne par référence le membre d’une classe, il est possible de modifier directement ce membre à l’extérieur de la classe, ce qui peut mener à un defaut d’encapsulation. Empêcher la modification du membre en utilisant sa référence permet d’éviter des erreurs.

L’utilisation de ref readonly en retour d’une fonction est simple: tous les objets pour lesquels on peut effectuer un retour par référence avec ref peuvent être retournés par référence en lecture seule:

class CircleRepository
{
  private Circle InnerCircle;

  ref readonly Circle GetCircle()
  {
    return ref this.InnerCircle; // ATTENTION: return ref et non return ref readonly
  }
}

L’inverse n’est pas possible: un objet retourné par référence en lecture ne peut pas être affecté à un variable qui n’est pas en lecture seule:

var circleRepo = new CircleRepository{ InnerCircle = new Circle() };
ref readonly circleRef = ref CircleRepo.GetCircle(); // OK
ref circleRef = ref CircleRepo.GetCircle(); // ERREUR

L’opérateur ternaire permet d’écrire des expressions du type:

<condition> ? <code si condition vraie> : <code si condition fausse> 

On peut effectuer des initialisations de ce type:

Circle[] circules = { 
  new Circle{ Radius = 4 }, 
  new Circle{ Radius = 2 }, 
}; 

var firstCircle = circles.First(); 
var bigCircle = foundCircle.Radius > 2 ? circles[0] : circles[1]; 

Dans la dernière ligne, des copies par valeur des objets sont effectuées car Circle est un objet de type valeur.

Pour effectuer des copies par référence, il est possible à partir de C# 7.2 d’utiliser le mot-clé ref avec l’opérateur ternaire:

ref var bigCircle = ref (foundCircle.Radius > 2 ? ref circles[0] : ref circles[1]); 

L’affectation est, ainsi, effectuée par référence.

Lors d’appel de fonction, le mot-clé ref autorise le passage en argument d’objets de type valeur par référence. La modification de l’objet passé en argument est possible dans le corps de la fonction appelée. Comme pour ref, le mot-clé in permet d’indiquer qu’un objet de type valeur doit être passé par référence toutefois il interdit la modification de l’argument dans le corps de la fonction.

Par rapport à ref, les avantages à utiliser in sont les suivants:

• On indique explicitement que l’objet ne pourra pas être modifié dans le corps de la fonction.
• Le compilateur optimise le code généré en sachant que l’objet n’est pas modifié dans le corps de la fonction. Ainsi l’appel à la fonction est effectué de façon plus rapide qu’avec ref.

Par exemple, si on considère la classe Circle et la fonction suivante

struct Circle  
{ 
  public int Radius { get; set; } 

  public void SetNewRadius(int newRadius)  
  { 
    this.Radius = newRadius; 
  } 
} 

private static void ChangeRadius(int newRadius, ref Circle circle) 
{ 
  circle.Radius = newRadius; 
} 

Si on effectue l’appel suivant:

var circle = new Circle{ Radius = 4 }; 
Console.WriteLine(circle.Radius); // 4 
ChangeRadius(2, ref circle); // circle est passé par référence 
Console.WriteLine(circle.Radius); // 2 

Il n’y a pas de copie de circle lors du passage en argument quand on appelle ChangeRadius(). La même instance est passée en argument et modifiée dans le corps de ChangeRadius().

Si on modifie l’implémentation de ChangeRadius():

private static void ChangeRadius(int newRadius, in Circle circle) 
{ 
  // circle.Radius = newRadius; // ERREUR car on ne peut pas modifier circle dans le corps de la méthode 
  circle.SetNewRadius(newRadius); // Pas d'erreur 
  Console.WriteLine(circle.Radius);  
} 

Si on effectue l’appel suivant:

var circle = new Circle{ Radius = 4 }; 
Console.WriteLine(circle.Radius); // 4 
ChangeRadius(2, circle); // circle est passé par référence 

// Dans le corps de ChangeRadius(), Console.WriteLine(circle.Radius) affiche 4 
Console.WriteLine(circle.Radius); // 4 
Circle.SetNewRadius(3); 
Console.WriteLine(circle.Radius); // 3 

Avec in, l’argument circle est passé par référence toutefois le compilateur effectue des optimisations en sachant que circle ne peut être modifié dans le corps de la fonction. circle.SetNewRadius() ne modifie pas l’objet circle. Le résultat est toujours 4 quand on essaie de modifier circle à l’intérieur de ChangeRadius().

Par exemple dans le cas de l’exemple précédent, les appels suivants ont le même comportement:

ChangeRadius(2, circle); // Passage par référence implicite 
ChangeRadius(2, in circle); // Passage par référence explicite 

Surcharge des méthodes avec in

Les surcharges de méthode avec ref et in ne sont pas possibles, une seule surcharge est possible.

Par exemple, si on crée 2 méthodes de ce type:

private static void ChangeRadius(int newRadius, ref Circle circle) { ... } 
private static void ChangeRadius(int newRadius, in Circle circle) { ... } // ERREUR: généré une erreur de compilation 

Il est possible d’avoir 2 surcharges avec et sans in:

private static void ChangeRadius(int newRadius, Circle circle) { … } 
private static void ChangeRadius(int newRadius, in Circle circle) { … } // OK 

Dans ce dernier cas, l’utilisation de in lors des appels est importante puisqu’elle va permettre d’indiquer quelle surcharge sera utilisée:

ChangeRadius(2, circle); // la surchage ChangeRadius(int newRadius, Circle circle) est appelée => passage par valeur 
ChangeRadius(2, in circle); // la surchage ChangeRadius(int newRadius, in Circle circle) est appelée => passage par référence 

public struct Circle 
{ 
  public Circle(int radius) 
  { 
    this.Radius = radius; 
  } 
 
  public int Radius { get; private set; } 

  public void UpdateRadius(int newRadius) 
  { 
    this.Radius = newRadius; 
  } 
} 

public static void ChangeRadius(int newRadius, in Circle circle) 
{ 
  circle.UpdateRadius(newRadius); 
  Console.WriteLine(circle.Radius); 
} 

var circle = new Circle(4); 
ChangeRadius(3, in circle); // 4 
Console.WriteLine(circle.Radius); // 4 

public readonly struct Circle 
{ 
  // ... 
}