Mettre à jour un code base avec des types référence pouvant accepter la valeur Null pour améliorer les avertissements de diagnostics Null

Les types de référence nullables vous permettent de déclarer si les variables d’un type de référence doivent ou ne doivent pas être affectées à une null valeur. L’analyse statique et les avertissements du compilateur lorsque votre code peut déréférer null sont les avantages les plus importants de cette fonctionnalité. Une fois activé, le compilateur génère des avertissements qui vous aident à éviter de lever une System.NullReferenceException fois votre code exécuté.

Si votre codebase est relativement petit, vous pouvez activer la fonctionnalité dans votre projet, traiter les avertissements et profiter des avantages des diagnostics améliorés. Les bases de code plus volumineuses peuvent nécessiter une approche plus structurée pour traiter les avertissements au fil du temps, ce qui permet d’activer la fonctionnalité pour certains lorsque vous adressez des avertissements dans différents types ou fichiers. Cet article décrit différentes stratégies pour mettre à jour une base de code et les compromis associés à ces stratégies. Avant de commencer votre migration, lisez la vue d’ensemble conceptuelle des types de référence nullables. Il couvre l’analyse statique du compilateur, les valeurs d’état null de peut-être null et non null et les annotations nullables. Une fois que vous êtes familiarisé avec ces concepts et termes, vous êtes prêt à migrer votre code.

Planifier votre migration

Quelle que soit la façon dont vous mettez à jour votre codebase, l’objectif est que les avertissements nullables et les annotations nullables sont activés dans votre projet. Une fois que vous atteignez cet objectif, vous aurez le <nullable>Enable</nullable> paramètre dans votre projet. Vous n’avez pas besoin des directives de préprocesseur pour ajuster les paramètres ailleurs.

Le premier choix consiste à définir la valeur par défaut du projet. Les choix sont les suivants :

  1. Désactiver nullable comme valeur par défaut : désactiver est la valeur par défaut si vous n’ajoutez pas d’élément Nullable à votre fichier projet. Utilisez cette valeur par défaut lorsque vous n’ajoutez pas activement de nouveaux fichiers à la base de code. L’activité principale consiste à mettre à jour la bibliothèque pour utiliser des types de référence nullables. L’utilisation de cette valeur par défaut signifie que vous ajoutez une directive de préprocesseur nullable à chaque fichier lorsque vous mettez à jour son code.
  2. Nullable activez comme valeur par défaut : définissez cette valeur par défaut lorsque vous développez activement de nouvelles fonctionnalités. Vous souhaitez que tout nouveau code tire parti des types de référence nullables et de l’analyse statique nullable. L’utilisation de cette valeur par défaut signifie que vous devez ajouter un #nullable disable en haut de chaque fichier. Vous allez supprimer ces directives de préprocesseur lorsque vous adressez les avertissements dans chaque fichier.
  3. Avertissements nullables comme valeur par défaut : choisissez cette valeur par défaut pour une migration en deux phases. Dans la première phase, adressez les avertissements. Dans la deuxième phase, activez les annotations pour déclarer l’état null attendu d’une variable. L’utilisation de cette valeur par défaut signifie que vous devez ajouter un #nullable disable en haut de chaque fichier.
  4. Annotations nullables comme valeur par défaut. Annotez le code avant de traiter les avertissements.

L’activation de nullable comme valeur par défaut crée un travail plus frontal pour ajouter les directives de préprocesseur à chaque fichier. L’avantage est que chaque nouveau fichier de code ajouté au projet sera nullable. Tout nouveau travail est nullable ; seul le code existant doit être mis à jour. La désactivation de nullable comme la valeur par défaut fonctionne mieux si la bibliothèque est stable et que le principal objectif du développement est d’adopter des types de référence nullables. Vous activez les types de référence nullables lorsque vous annotez les API. Lorsque vous avez terminé, vous activez les types de référence nullables pour l’ensemble du projet. Lorsque vous créez un fichier, vous devez ajouter les directives de préprocesseur et la rendre nullable. Si des développeurs de votre équipe oublient, ce nouveau code est maintenant dans le backlog de travail pour rendre tout code nullable.

Parmi ces stratégies, vous choisissez dépend de la quantité de développement actif qui se déroule dans votre projet. Plus votre projet est mature et stable, mieux la deuxième stratégie est améliorée. Plus les fonctionnalités sont développées, plus la première stratégie est améliorée.

Important

Le contexte nullable global ne s’applique pas aux fichiers de code générés. Sous l’une ou l’autre stratégie, le contexte nullable est désactivé pour tout fichier source marqué comme généré. Cela signifie que toutes les API dans les fichiers générés ne sont pas annotées. Il existe quatre façons qu’un fichier soit marqué comme généré :

  1. Dans .editorconfig, spécifiez generated_code = true dans une section qui s’applique à ce fichier.
  2. Placez ou <auto-generated/> insérez <auto-generated> un commentaire en haut du fichier. Il peut se trouver sur n’importe quelle ligne de ce commentaire, mais le bloc de commentaire doit être le premier élément du fichier.
  3. Démarrez le nom du fichier avec TemporaryGeneratedFile_
  4. Terminez le nom de fichier avec .designer.cs, .generated.cs, .g.cs ou .g.i.cs.

Les générateurs peuvent opter pour l’utilisation de la #nullable directive de préprocesseur.

Comprendre les contextes et les avertissements

L’activation des avertissements et des annotations contrôle la façon dont le compilateur affiche les types de référence et la nullabilité. Chaque type a l’une des trois capacités null :

  • oubli : tous les types de références sont insurables nullables lorsque le contexte d’annotation est désactivé.
  • non inutilisable : un type de référence non annoté n’est Cpas disponible lorsque le contexte d’annotation est activé.
  • Nullable : type de référence annoté, est nullable, C?mais un avertissement peut être émis lorsque le contexte d’annotation est désactivé. Les variables déclarées avec var sont nullables lorsque le contexte d’annotation est activé.

Le compilateur génère des avertissements basés sur cette nullabilité :

  • les types non inullables provoquent des avertissements si une valeur potentielle null est affectée à eux.
  • Les types nullables provoquent des avertissements s’ils sont déréférés lorsqu’ils sont peut-être null.
  • les types inconscients provoquent des avertissements s’ils sont déréférés lorsqu’ils sont peut-être null et que le contexte d’avertissement est activé.

Chaque variable a un état nullable par défaut qui dépend de sa nullabilité :

  • Les variables nullables ont un état null par défaut de peut-être null.
  • Les variables non nullables ont un état null par défaut non null.
  • Les variables insuables nullables ont un état null par défaut non null.

Avant d’activer les types de référence nullables, toutes les déclarations de votre codebase sont insouptenables. Cela est important, car cela signifie que tous les types de référence ont un état null par défaut non null.

Avertissements d’adresse

Si votre projet utilise Entity Framework Core, vous devez lire leurs conseils sur l’utilisation de types de référence nullables.

Lorsque vous démarrez votre migration, vous devez commencer par activer les avertissements uniquement. Toutes les déclarations restent insociables nullables, mais vous verrez des avertissements lorsque vous déréférez une valeur après que son état null change en valeur peut-être null. Lorsque vous répondez à ces avertissements, vous allez vérifier la valeur Null dans d’autres emplacements, et votre codebase devient plus résilient. Pour découvrir des techniques spécifiques pour différentes situations, consultez l’article sur techniques pour résoudre les avertissements nullables.

Vous pouvez traiter les avertissements et activer les annotations dans chaque fichier ou classe avant de continuer avec d’autres codes. Toutefois, il est souvent plus efficace d’aborder les avertissements générés pendant que le contexte est des avertissements avant d’activer les annotations de type. De cette façon, tous les types sont oubliés jusqu’à ce que vous ayez traité le premier ensemble d’avertissements.

Activer les annotations de type

Après avoir adressé le premier ensemble d’avertissements, vous pouvez activer le contexte d’annotation. Cela change les types de référence de l’inconcurisable à l’autre. Toutes les variables déclarées avec var sont nullables. Ce changement introduit souvent de nouveaux avertissements. La première étape de l’adressage des avertissements du compilateur consiste à utiliser ? des annotations sur les types de paramètres et de retour pour indiquer quand des arguments ou des valeurs de retour peuvent être null. Comme vous effectuez cette tâche, votre objectif n’est pas seulement de corriger les avertissements. L’objectif le plus important est de comprendre votre intention pour les valeurs null potentielles.

Les attributs étendent les annotations de type

Plusieurs attributs ont été ajoutés pour exprimer des informations supplémentaires sur l’état null des variables. Les règles de vos API sont probablement plus compliquées que nonnull ou peut-être null pour tous les paramètres et valeurs de retour. La plupart de vos API ont des règles plus complexes pour le moment où les variables peuvent ou ne peuvent pas être null. Dans ces cas, vous allez utiliser des attributs pour exprimer ces règles. Les attributs qui décrivent la sémantique de votre API sont trouvés dans l’article sur les attributs qui affectent l’analyse nullable.

Étapes suivantes

Une fois que vous avez traité tous les avertissements après l’activation des annotations, vous pouvez définir le contexte par défaut pour que votre projet soit activé. Si vous avez ajouté des pragmas dans votre code pour l’annotation nullable ou le contexte d’avertissement, vous pouvez les supprimer. Au fil du temps, vous pouvez voir de nouveaux avertissements. Vous pouvez écrire du code qui introduit des avertissements. Une dépendance de bibliothèque peut être mise à jour pour les types de référence nullables. Ces mises à jour remplacent les types de cette bibliothèque par des éléments nullables qui n’ont pas la valeur nullable ou nullable.

Vous pouvez également explorer ces concepts dans notre module d’apprentissage sur la sécurité Nullable en C#.