modificateur requis (référence C#)

Le required modificateur indique que le champ ou la propriété auquel il s’applique doit être initialisé par un initialiseur d’objet. Toute expression qui initialise une nouvelle instance du type doit initialiser tous les membres requis. Le required modificateur est disponible à partir de C# 11.

La documentation de référence du langage C# décrit la version la plus récente du langage C#. Il contient également la documentation initiale des fonctionnalités dans les préversions publiques pour la prochaine version du langage.

La documentation identifie toute fonctionnalité introduite en premier dans les trois dernières versions de la langue ou dans les préversions publiques actuelles.

Conseil / Astuce

Pour savoir quand une fonctionnalité a été introduite en C#, consultez l’article sur l’historique des versions du langage C#.

En utilisant le required modificateur, les développeurs peuvent créer des types où les propriétés ou les champs doivent être correctement initialisés, mais encore autoriser l’initialisation par le biais d’initialiseurs d’objets. Plusieurs règles garantissent ce comportement :

• Appliquez le required modificateur aux champs et propriétés déclarés dans et class typesstruct, y compris record et record struct types. Vous ne pouvez pas appliquer le required modificateur aux membres d’un interface.
• Vous ne pouvez pas marquer les implémentations d’interface explicites comme required. Vous ne pouvez pas les définir dans les initialiseurs d’objets.
• Vous devez initialiser les membres requis, mais vous pouvez les nullinitialiser . Si le type est un type de référence non nullable, le compilateur émet un avertissement si vous initialisez le membre à null. Le compilateur émet une erreur si le membre n’est pas initialisé du tout.
• Les membres obligatoires doivent être au moins aussi visibles que le type qu'ils contiennent. Par exemple, une classe public ne peut pas contenir un champ required qui est protected. En outre, les propriétés requises doivent avoir des setters (set ou des accesseurs init) qui sont au moins aussi visibles que leurs types contenants. Le code qui crée une instance ne peut pas définir les membres qui ne sont pas accessibles.
• Les classes dérivées ne peuvent pas masquer un membre required déclaré dans la classe de base. Le masquage d’un membre requis empêche les appelants d’utiliser des initialiseurs d’objet pour ce membre. En outre, les types dérivés qui remplacent une propriété requise doivent inclure le modificateur required. Le type dérivé ne peut pas supprimer l’état required. Les types dérivés peuvent ajouter le modificateur required lors de la substitution d’une propriété.
• Vous ne pouvez pas utiliser de type avec des required membres comme argument de type lorsque le paramètre de type inclut la new() contrainte. Le compilateur ne peut pas appliquer que tous les membres requis sont initialisés dans le code générique.
• Vous ne pouvez pas utiliser le required modificateur sur la déclaration pour les paramètres positionnels d’un enregistrement. Vous pouvez ajouter une déclaration explicite pour une propriété positionnelle qui inclut le modificateur required.

Certains types, tels que enregistrements positionnels, utilisent un constructeur principal pour initialiser les propriétés positionnelles. Si l’une de ces propriétés inclut le modificateur required, le constructeur principal ajoute l’attribut SetsRequiredMembers. Cet attribut indique que le constructeur principal initialise tous les membres requis. Vous pouvez écrire votre propre constructeur avec l’attribut System.Diagnostics.CodeAnalysis.SetsRequiredMembersAttribute. Toutefois, le compilateur ne vérifie pas que ces constructeurs initialisent tous les membres requis. Au lieu de cela, l’attribut affirme au compilateur que le constructeur initialise tous les membres requis. L’attribut SetsRequiredMembers ajoute ces règles aux constructeurs :

• Un constructeur qui se chaîne à un autre constructeur annoté avec l’attribut SetsRequiredMembers, this()ou base(), doit également inclure l’attribut SetsRequiredMembers. Cela garantit que les appelants peuvent utiliser correctement tous les constructeurs appropriés.
• Les constructeurs de copies générés pour les types record ont l'attribut SetsRequiredMembers appliqué si l'un des membres est required.

Avertissement

L’attribut SetsRequiredMembers désactive les vérifications du compilateur que tous les required membres sont initialisés lors de la création d’un objet. Utilisez-le avec précaution.

Le code suivant montre une hiérarchie de classes qui utilise le modificateur required pour les propriétés FirstName et LastName :

public class Person
{
    public Person() { }

    [SetsRequiredMembers]
    public Person(string firstName, string lastName) =>
        (FirstName, LastName) = (firstName, lastName);

    public required string FirstName { get; init; }
    public required string LastName { get; init; }

    public int? Age { get; set; }
}

public class Student : Person
{
    public Student() : base()
    {
    }

    [SetsRequiredMembers]
    public Student(string firstName, string lastName) :
        base(firstName, lastName)
    {
    }

    public double GPA { get; set; }
}

Pour plus d’informations sur les membres requis, consultez la spécification de la fonctionnalité C#11 - Membres obligatoires.