Contraintes sur les paramètres de type (Guide de programmation C#)

Les contraintes informent le compilateur sur les fonctionnalités que doit avoir un argument de type. Sans contrainte, l’argument de type peut être n’importe quel type. Le compilateur peut seulement deviner les membres de System.Object, qui est la classe de base par excellence de tous les types .NET. Pour plus d’informations, consultez Pourquoi utiliser des contraintes. Si le code client utilise un type qui ne satisfait pas à une contrainte, le compilateur émet une erreur. Les contraintes sont spécifiées à l’aide du mot clé contextuel where. Le tableau suivant liste plusieurs types de contrainte :

Certaines contraintes sont incompatibles et certaines contraintes doivent être dans un ordre spécifié :

• Vous pouvez appliquer au maximum une des contraintes struct, class, class?, notnull, et unmanaged. Si vous fournissez une de ces contraintes, il doit s’agir de la première contrainte spécifiée pour ce paramètre de type.
• La contrainte de classe de base, (where T : Base ou where T : Base?), ne peut pas être associée à l’une des contraintes struct, class, class?, notnull ou unmanaged.
• Vous pouvez appliquer au maximum une contrainte de classe de base dans l’un des formulaires. Si vous souhaitez prendre en charge le type de base pouvant accepter la valeur Null, utilisez Base?.
• Vous ne pouvez pas nommer en tant que contrainte le formulaire non-nullable et le formulaire pouvant accepter la valeur Null d’une interface.
• La contrainte new() ne peut pas être combinée avec la contrainte struct ou unmanaged. Si vous spécifiez la contrainte new(), il doit s’agir de la dernière contrainte pour ce paramètre de type. Les anti-contraintes, le cas échéant, peuvent suivre la contrainte new().
• Vous pouvez appliquer uniquement la contrainte default sur des implémentations d'interface explicite ou de remplacement. Elle ne peut pas être associée aux contraintes struct ou class.
• L’anti-contrainte allows ref struct ne peut pas être combinée avec la contrainte class ou class?.
• L’anti-contrainte allows ref struct doit suivre toutes les contraintes pour ce paramètre de type.

Pourquoi utiliser des contraintes

Les contraintes spécifient les fonctionnalités et les attentes d’un paramètre de type. La déclaration de ces contraintes signifie que vous pouvez utiliser les opérations et les appels de méthode du type de contrainte. Vous appliquez des contraintes au paramètre de type lorsque votre classe ou votre méthode générique utilise une opération sur les membres génériques au-delà de l’assignation simple, ce qui inclut l’appel de toute méthode non prise en charge par System.Object. Par exemple, la contrainte de classe de base indique au compilateur que seuls les objets de ce type ou dérivés de ce type peuvent remplacer cet argument de type. Une fois que le compilateur a cette garantie, il peut autoriser les méthodes de ce type à être appelées dans la classe générique. L’exemple de code suivant illustre la fonctionnalité que vous pouvez ajouter à la classe GenericList<T> (dans Introduction aux génériques) en appliquant une contrainte de classe de base.

public class Employee
{
    public Employee(string name, int id) => (Name, ID) = (name, id);
    public string Name { get; set; }
    public int ID { get; set; }
}

public class GenericList<T> where T : Employee
{
    private class Node
    {
        public Node(T t) => (Next, Data) = (null, t);

        public Node? Next { get; set; }
        public T Data { get; set; }
    }

    private Node? head;

    public void AddHead(T t)
    {
        Node n = new Node(t) { Next = head };
        head = n;
    }

    public IEnumerator<T> GetEnumerator()
    {
        Node? current = head;

        while (current != null)
        {
            yield return current.Data;
            current = current.Next;
        }
    }

    public T? FindFirstOccurrence(string s)
    {
        Node? current = head;
        T? t = null;

        while (current != null)
        {
            //The constraint enables access to the Name property.
            if (current.Data.Name == s)
            {
                t = current.Data;
                break;
            }
            else
            {
                current = current.Next;
            }
        }
        return t;
    }
}

La contrainte permet à la classe générique d’utiliser la propriété Employee.Name. La contrainte spécifie que tous les éléments de type T sont soit un objet Employee, soit un objet qui hérite de Employee, et rien d’autre.

Plusieurs contraintes peuvent être appliquées au même paramètre de type, et les contraintes elles-mêmes peuvent être des types génériques, comme suit :

class EmployeeList<T> where T : notnull, Employee, IComparable<T>, new()
{
    // ...
    public void AddDefault()
    {
        T t = new T();
        // ...
    }
}

Lorsque vous appliquez la contrainte where T : class, évitez d’utiliser les opérateurs == et != sur le paramètre de type, car ces opérateurs testent uniquement l’identité des références, et non l’égalité des valeurs. Ce comportement se produit même si ces opérateurs sont surchargés dans un type qui est utilisé comme argument. Le code suivant illustre ce point ; la sortie a la valeur false même si la classe String surcharge l’opérateur ==.

public static void OpEqualsTest<T>(T s, T t) where T : class
{
    System.Console.WriteLine(s == t);
}

private static void TestStringEquality()
{
    string s1 = "target";
    System.Text.StringBuilder sb = new System.Text.StringBuilder("target");
    string s2 = sb.ToString();
    OpEqualsTest<string>(s1, s2);
}

Au moment de la compilation, le compilateur sait uniquement que T est un type référence et doit utiliser les opérateurs par défaut qui sont valides pour tous les types référence. Si vous devez tester l’égalité des valeurs, appliquez la contrainte where T : IEquatable<T> ou where T : IComparable<T> et implémentez l’interface sur toute classe utilisée pour construire la classe générique.

Utilisation de contraintes dans plusieurs paramètres

Vous pouvez appliquer des contraintes à plusieurs paramètres et plusieurs contraintes à un seul paramètre, comme indiqué dans l’exemple suivant :

class Base { }
class Test<T, U>
    where U : struct
    where T : Base, new()
{ }

Paramètres de type unbounded

Les paramètres de type qui n’ont aucune contrainte, tels que T dans la classe publique SampleClass<T>{}, sont appelés paramètres de type unbounded. Les paramètres de type unbounded obéissent aux règles suivantes :

• Les opérateurs != et == ne peuvent pas être utilisés, car il n’est pas garanti que l’argument de type concret les prend en charge.
• Ils peuvent être convertis vers et depuis System.Object ou être explicitement convertis vers tout type d’interface.
• Vous pouvez les comparer à null. Si un paramètre illimité est comparé à null, la comparaison retourne toujours la valeur false si l’argument de type est un type valeur.

Paramètres de type en tant que contraintes

L’utilisation d’un paramètre de type générique comme contrainte est utile quand une fonction membre dotée de son propre paramètre de type doit contraindre ce paramètre au paramètre du type conteneur, comme le montre l’exemple suivant :

public class List<T>
{
    public void Add<U>(List<U> items) where U : T {/*...*/}
}

Dans l’exemple précédent, T est une contrainte de type dans le contexte de la méthode Add et un paramètre de type unbounded dans le contexte de la classe List.

Les paramètres de type peuvent également être utilisés comme contraintes dans les définitions de classes génériques. Le paramètre de type doit être déclaré entre crochets pointus, ainsi que tous les autres paramètres de type :

//Type parameter V is used as a type constraint.
public class SampleClass<T, U, V> where T : V { }

L’utilité des paramètres de type en tant que contraintes avec les classes génériques est limitée, car le compilateur ne peut rien deviner à propos du paramètre de type en dehors du fait qu’il dérive de System.Object. Utilisez des paramètres de type en tant que contraintes sur les classes génériques dans les scénarios dans lesquels vous souhaitez mettre en application une relation d’héritage entre deux paramètres de type.

Contrainte notnull

Vous pouvez utiliser la contrainte notnull pour spécifier que l’argument de type doit être un type valeur non nullable ou un type référence non nullable. Contrairement à la plupart d’autres contraintes, si un argument de type enfreint la contrainte notnull, le compilateur génère un avertissement au lieu d’une erreur.

La contrainte notnull a un effet uniquement lorsqu’elle est utilisée dans un contexte pouvant accepter la valeur Null. Si vous ajoutez la contrainte notnull dans un contexte inconscient pouvant accepter la valeur Null, le compilateur ne génère pas d’avertissements ou d’erreurs pour les violations de la contrainte.

Contrainte class

La contrainte class dans un contexte pouvant accepter la valeur Null spécifie que l’argument de type doit être un type référence non nullable. Dans un contexte pouvant accepter la valeur Null, lorsqu’un argument de type est un type référence pouvant accepter la valeur Null, le compilateur génère un avertissement.

Contrainte default

L’ajout de types référence pouvant accepter la valeur Null complique l’utilisation de T? dans un type ou une méthode générique. T? peut être utilisé avec la contrainte struct ou class, mais l’une d’elles doit être présente. Lorsque la contrainte class a été utilisée, T? fait référence au type de référence pouvant accepter la valeur nulle pour T. T? peut être utilisé lorsqu’aucune contrainte n’est appliquée. Dans ce cas, T? est interprété comme T? pour les types valeur et les types référence. Toutefois, si T est une instance de Nullable<T>, T? est identique à T. En d’autres termes, il ne devient pas T??.

Étant donné que T? peut désormais être utilisé sans contrainte class ou struct, des ambiguïtés peuvent survenir dans les remplacements ou les implémentations d’interface explicites. Dans ces deux cas, le remplacement n’inclut pas les contraintes, mais les hérite de la classe de base. Lorsque la classe de base n’applique pas la contrainte class ou struct, les classes dérivées doivent spécifier un remplacement qui s’applique à la méthode de base sans l’une ou l’autre contrainte. La méthode dérivée applique la contrainte default. La contrainte default ne clarifie ni la contrainte class ni la contrainte struct.

Contrainte non managée

Vous pouvez utiliser la contrainte unmanaged pour spécifier que le paramètre de type doit être un type non managé non-nullable. La contrainte unmanaged vous permet d’écrire des routines réutilisables à appliquer aux types qui peuvent être manipulés comme blocs de mémoire, comme illustré dans l’exemple suivant :

unsafe public static byte[] ToByteArray<T>(this T argument) where T : unmanaged
{
    var size = sizeof(T);
    var result = new Byte[size];
    Byte* p = (byte*)&argument;
    for (var i = 0; i < size; i++)
        result[i] = *p++;
    return result;
}

La méthode précédente doit être compilée dans un contexte unsafe, car elle utilise l’opérateur sizeof sur un type qui n’est pas connu pour être un type intégré. Sans la contrainte unmanaged, l’opérateur sizeof n’est pas disponible.

La contrainte unmanaged implique la contrainte struct et ne peut pas être combinée avec. Étant donné que la contrainte struct implique la contrainte new(), mais la contrainte unmanaged ne peut pas être combinée avec la contrainte new().

Contraintes de délégué

Vous pouvez utiliser System.Delegate ou System.MulticastDelegate comme contrainte de classe de base. Le CLR a toujours autorisé cette contrainte, contrairement au langage C#. La contrainte System.Delegate vous permet d’écrire du code qui fonctionne avec les délégués en mode type sécurisé. Le code suivant définit une méthode d’extension qui combine deux délégués du moment qu’ils sont du même type :

public static TDelegate? TypeSafeCombine<TDelegate>(this TDelegate source, TDelegate target)
    where TDelegate : System.Delegate
    => Delegate.Combine(source, target) as TDelegate;

Vous pouvez utiliser la méthode précédente pour combiner des délégués du même type :

Action first = () => Console.WriteLine("this");
Action second = () => Console.WriteLine("that");

var combined = first.TypeSafeCombine(second);
combined!();

Func<bool> test = () => true;
// Combine signature ensures combined delegates must
// have the same type.
//var badCombined = first.TypeSafeCombine(test);

Si vous supprimez les commentaires de la dernière ligne, la compilation n’a pas lieu. first et test sont tous deux des types délégués, mais des types délégués différents.

Contraintes d’enum

Vous pouvez également spécifier le type System.Enum comme contrainte de classe de base. Le CLR a toujours autorisé cette contrainte, contrairement au langage C#. Les génériques utilisant System.Enum fournissent une programmation de type sécurisé aux résultats de cache issus de l’utilisation de méthodes statiques dans System.Enum. L’exemple suivant recherche toutes les valeurs valides d’un type enum, puis génère un dictionnaire qui mappe ces valeurs à sa représentation sous forme de chaîne.

public static Dictionary<int, string> EnumNamedValues<T>() where T : System.Enum
{
    var result = new Dictionary<int, string>();
    var values = Enum.GetValues(typeof(T));

    foreach (int item in values)
        result.Add(item, Enum.GetName(typeof(T), item)!);
    return result;
}

Enum.GetValues et Enum.GetName utilisent la réflexion, ce qui a des répercussions sur les performances. Vous pouvez appeler EnumNamedValues pour générer une collection qui est mise en cache et réutilisée, plutôt que de répéter les appels qui nécessitent la réflexion.

Vous pouvez l’utiliser comme montré dans l’exemple suivant pour créer un enum et générer un dictionnaire de ses valeurs et de ses noms :

enum Rainbow
{
    Red,
    Orange,
    Yellow,
    Green,
    Blue,
    Indigo,
    Violet
}

var map = EnumNamedValues<Rainbow>();

foreach (var pair in map)
    Console.WriteLine($"{pair.Key}:\t{pair.Value}");

Arguments de type implémentant l’interface déclarée

Certains scénarios nécessitent qu’un argument fourni pour un paramètre de type implémente cette interface. Par exemple :

public interface IAdditionSubtraction<T> where T : IAdditionSubtraction<T>
{
    static abstract T operator +(T left, T right);
    static abstract T operator -(T left, T right);
}

Ce modèle permet au compilateur C# de déterminer le type contenant pour les opérateurs surchargés, ou toute static virtual méthode ou static abstract. Il fournit la syntaxe afin que les opérateurs d’addition et de soustraction puissent être définis sur un type contenant. Sans cette contrainte, les paramètres et les arguments doivent être déclarés comme interface, plutôt que comme paramètre de type :

public interface IAdditionSubtraction<T> where T : IAdditionSubtraction<T>
{
    static abstract IAdditionSubtraction<T> operator +(
        IAdditionSubtraction<T> left,
        IAdditionSubtraction<T> right);

    static abstract IAdditionSubtraction<T> operator -(
        IAdditionSubtraction<T> left,
        IAdditionSubtraction<T> right);
}

La syntaxe précédente exigerait que les implémenteurs utilisent l’implémentation d’interface explicite pour ces méthodes. La fourniture de la contrainte supplémentaire permet à l’interface de définir les opérateurs en termes de paramètres de type. Les types qui implémentent l’interface peuvent implémenter implicitement les méthodes d’interface.

Autorise le struct ref

L’anti-contrainte allows ref struct déclare que l’argument de type correspondant peut être un type ref struct. Les instances de ce paramètre de type doivent respecter les règles suivantes :

• Ne peut pas être boxed.
• Participe aux règles de sécurité de ref.
• Les instances ne peuvent pas être utilisées lorsqu’un type ref struct n’est pas autorisé, tel que les champs static.
• Les instances peuvent être marquées avec le modificateur scoped.

La clause allows ref struct n’est pas héritée. Dans le code suivant :

class SomeClass<T, S>
    where T : allows ref struct
    where S : T
{
    // etc
}

L’argument de S ne peut pas être un ref struct, car S ne présente pas la clause allows ref struct.

Un paramètre de type qui présente la clause allows ref struct ne peut pas être utilisé comme argument de type, sauf si le paramètre de type correspondant a également la clause allows ref struct. Cette règle est illustrée par l’exemple suivant :

public class Allow<T> where T : allows ref struct
{

}

public class Disallow<T>
{
}

public class Example<T> where T : allows ref struct
{
    private Allow<T> fieldOne; // Allowed. T is allowed to be a ref struct

    private Disallow<T> fieldTwo; // Error. T is not allowed to be a ref struct
}

L’exemple précédent montre qu’un argument de type qui peut être un type ref struct ne peut pas être substitué à un paramètre de type qui ne peut pas être un type ref struct.

Voir aussi

• System.Collections.Generic
• Introduction aux génériques
• Classes génériques
• new, contrainte