Options du compilateur C# pour les règles de fonctionnalité de langage

Les options suivantes contrôlent la façon dont le compilateur interprète les fonctionnalités du langage. La nouvelle syntaxe MSBuild est affichée en gras. La syntaxe csc.exe plus ancienne est indiquée en code style.

  • CheckForOverflowUnderflow / -checked : Générer des vérifications de dépassement de capacité.
  • AllowUnsafeBlocks / -unsafe : Autoriser unsafe le code.
  • DefineConstants / -define : définir des symboles de compilation conditionnelle.
  • LangVersion / -langversion : spécifier la version de langue telle que default (dernière version majeure) ou latest (dernière version, y compris les versions mineures).
  • Nullable / -nullable : activer le contexte nullable ou les avertissements nullables.

Remarque

Pour plus d’informations sur la configuration de ces options pour votre projet, consultez les options du compilateur.

CheckForOverflowUnderflow

L’option CheckForOverflowUnderflow contrôle le contexte de vérification de dépassement de capacité par défaut qui définit le comportement du programme si les dépassements arithmétiques entiers.

<CheckForOverflowUnderflow>true</CheckForOverflowUnderflow>

Lorsque CheckForOverflowUnderflow est true, le contexte par défaut est un contexte vérifié et la vérification du dépassement de capacité est activée. Lorsque CheckForOverflowUnderflow est false, le contexte par défaut est un contexte non vérifié. La valeur par défaut de cette option est false, ce qui signifie que la vérification du dépassement de capacité est désactivée.

Vous pouvez également contrôler explicitement le contexte de vérification de dépassement de capacité pour certaines parties de votre code à l’aide des instructions et unchecked des checked instructions.

Pour plus d’informations sur la façon dont le contexte de contrôle de dépassement de capacité affecte les opérations et les opérations qu’il affecte, consultez l’article sur checked et unchecked les instructions.

AllowUnsafeBlocks

L’option de compilateur AllowUnsafeBlocks permet la compilation de code utilisant le mot clé unsafe. La valeur par défaut de cette option est false, ce qui signifie que le code non sécurisé n’est pas autorisé.

<AllowUnsafeBlocks>true</AllowUnsafeBlocks>

Pour plus d’informations sur le code unsafe, consultez Pointeurs et code unsafe.

Activer les règles de sécurité de la mémoire mises à jour

Les règles de sécurité de la mémoire mises à jour sont une fonctionnalité en préversion en C# 15 et .NET 11. Ils utilisent deux paramètres de compilateur indépendants :

  • La preview version du langage active la nouvelle syntaxe et les relaxations de pointeur.
  • La updated-memory-safety-rules fonctionnalité du compilateur active les règles mises à jour, notamment les obligations d’appelants non sécurisés et provoque l’enregistrement du compilateur dans l’assembly avec l’attribut MemorySafetyRulesAttribute .

Une future propriété du SDK stable, MemorySafetyRulesest planifiée comme troisième niveau d’activation pour le moment où la fonctionnalité quitte la préversion (par exemple), <MemorySafetyRules>2</MemorySafetyRules>mais cette propriété n’est pas encore implémentée.

Pour un projet, utilisez les deux paramètres :

<PropertyGroup>
  <LangVersion>preview</LangVersion>
  <Features>$(Features);updated-memory-safety-rules</Features>
</PropertyGroup>

Pour un programme basé sur des fichiers, ajoutez les directives équivalentes :

#:property Features=$(Features);updated-memory-safety-rules
#:property LangVersion=preview

La propriété AllowUnsafeBlocks est indépendante. Elle contrôle si la source peut utiliser le unsafe mot clé. Un projet peut activer les règles mises à jour sans autoriser le code non sécurisé, auquel cas il reçoit des erreurs lorsqu’il appelle des API non sécurisées.

Si un assembly applique les règles mises à jour contre une autre dépend de l’option de choix du côté :

  • Appelant de modèle mis à jour, appelé de modèle mis à jour : les marqueurs de l’appelé unsafe transitent par les métadonnées. L’appelant encapsule chaque appel à un membre non sécurisé dans un unsafe bloc.
  • Appelant de modèle mis à jour, appelé de modèle d’origine : un mode de compatibilité traite n’importe quel membre appelé avec un type de pointeur dans sa signature comme nécessitant une sécurité, de sorte que le site d’appel a besoin d’un bloc englobant unsafe . Ce mode empêche une API basée sur un pointeur de perdre silencieusement ses unsafe besoins.
  • Appelant de modèle d’origine, appelé de modèle mis à jour : les règles de pointeur d’origine s’appliquent toujours. Un membre non sécurisé qui n’a aucun type de pointeur dans sa signature devient pouvant être appelé à partir du code sécurisé, car l’appelant du modèle d’origine ne peut pas lire les nouveaux marqueurs.

DefineConstants

L’option DefineConstants définit des symboles dans tous les fichiers de code source de votre programme.

<DefineConstants>name;name2</DefineConstants>

Cette option spécifie les noms d’un ou plusieurs symboles que vous souhaitez définir. L’option DefineConstants revient à utiliser une directive de préprocesseur #define, sauf que l’option de compilateur est appliquée à tous les fichiers du projet. Un symbole reste défini dans un fichier source jusqu’à ce qu’une directive #undef dans le fichier source en supprime la définition. Quand vous utilisez l’option -define, une directive #undef dans un fichier n’a aucun effet sur les autres fichiers de code source du projet. Vous pouvez utiliser les symboles créés par cette option avec #if, #else, #elif et #endif pour effectuer une compilation conditionnelle des fichiers sources. Le compilateur C# lui-même ne définit aucun symbole ni aucune macro que vous pouvez utiliser dans votre code source ; toutes les définitions de symbole doivent être définies par l’utilisateur.

Remarque

La directive C# #define n’autorise pas un symbole à avoir une valeur, comme dans les langages tels que C++. Par exemple, #define ne peut pas créer de macro ni définir une constante. Si vous devez définir une constante, utilisez une variable enum. Si vous souhaitez créer une macro de style C++, envisagez d’utiliser des alternatives telles que des génériques. Comme les macros sont notoirement sujettes aux erreurs, C# n’autorise pas leur utilisation, mais fournit des solutions plus sûres.

LangVersion

La version du langage par défaut du compilateur C# dépend de la version cible de .Net Framework de votre application et de la version du kit de développement logiciel (SDK) ou de Visual Studio installée. Ces règles sont définies dans le contrôle de version du langage C#.

Avertissement

Ne définissez pas l’élément LangVersion sur latest. Le paramètre latest signifie que le compilateur installé utilise sa dernière version. Cette version peut passer de l’ordinateur à l’ordinateur, ce qui rend les builds non fiables. En outre, il active les fonctionnalités de langage qui peuvent nécessiter des fonctionnalités d’exécution ou de bibliothèque qui ne sont pas incluses dans le Kit de développement logiciel (SDK) actuel.

L’option LangVersion oblige le compilateur à accepter uniquement la syntaxe incluse dans la spécification du langage C# spécifiée, par exemple :

<LangVersion>9.0</LangVersion>

Certaines fonctionnalités en préversion nécessitent un opt-in distinct en plus de <LangVersion>preview</LangVersion>. Par exemple, les règles de sécurité de mémoire mises à jour C# 15 utilisent la fonctionnalité du updated-memory-safety-rules compilateur. Pour plus d’informations, consultez Activer les règles de sécurité de mémoire mises à jour.

Les valeurs suivantes sont valides :

Value Signification
preview Le compilateur accepte toute la syntaxe de langage valide de la dernière préversion.
latest Le compilateur accepte la syntaxe de la dernière version publiée du compilateur (versions mineures incluses).
latestMajor
ou default		 Le compilateur accepte la syntaxe de la dernière version principale publiée du compilateur.
15.0 Le compilateur accepte uniquement la syntaxe incluse dans C# 15 ou inférieur.
14.0 Le compilateur accepte uniquement la syntaxe incluse dans C# 14 ou inférieur.
13.0 Le compilateur accepte uniquement la syntaxe incluse dans C# 13 ou une version antérieure.
12.0 Le compilateur accepte uniquement la syntaxe incluse dans C# 12 ou inférieur.
11.0 Le compilateur accepte uniquement la syntaxe incluse dans C# 11 ou une version antérieure.
10.0 Le compilateur accepte uniquement la syntaxe incluse dans C# 10 ou une version antérieure.
9.0 Le compilateur accepte uniquement la syntaxe incluse dans C# 9 ou une version antérieure.
8.0 Le compilateur accepte uniquement la syntaxe incluse dans C# 8.0 ou une version antérieure.
7.3 Le compilateur accepte uniquement la syntaxe incluse dans C# 7.3 ou une version antérieure.
7.2 Le compilateur accepte uniquement la syntaxe incluse dans C# 7.2 ou une version antérieure.
7.1 Le compilateur accepte uniquement la syntaxe incluse dans C# 7.1 ou une version antérieure.
7 Le compilateur accepte uniquement la syntaxe incluse dans C# 7.0 ou une version antérieure.
6 Le compilateur accepte uniquement la syntaxe incluse dans C# 6.0 ou une version antérieure.
5 Le compilateur accepte uniquement la syntaxe incluse dans C# 5.0 ou une version antérieure.
4 Le compilateur accepte uniquement la syntaxe incluse dans C# 4.0 ou une version antérieure.
3 Le compilateur accepte uniquement la syntaxe incluse dans C# 3.0 ou une version antérieure.
ISO-2
ou 2		 Le compilateur accepte uniquement la syntaxe incluse dans ISO/IEC 23270:2006 C# (2.0)
ISO-1
ou 1		 Le compilateur accepte uniquement la syntaxe incluse dans ISO/IEC 23270:2003 C# (1.0/1.2)

À propos de l’installation

  • Pour vous assurer que votre projet utilise la version du compilateur par défaut recommandée pour votre version cible de .Net Framework, n’utilisez pas l’option LangVersion. Mettez à jour l’infrastructure cible pour accéder aux fonctionnalités de langage plus récentes.

  • Spécifier LangVersionavec la valeur default est différent d’omettre l’option LangVersion. Spécifier default utilise la version du langage pris en charge par le compilateur la plus récente, sans tenir compte de la version cible de .Net Framework. Par exemple, générer un projet qui cible .NET 6 depuis Visual Studio version 17.6 utilise C# 10 si LangVersion n’est pas spécifié, mais utilise C# 11 si LangVersion est défini sur default.

  • L’option du compilateur LangVersion n’affecte pas les métadonnées référencées par votre application C#.

  • Sachant que chaque version du compilateur C# contient des extensions de la spécification du langage, LangVersion ne vous offre pas les fonctionnalités équivalentes d’une version antérieure du compilateur.

  • Si les mises à jour de la version de C# coïncident généralement avec les versions principales de .NET, la nouvelle syntaxe et les nouvelles fonctionnalités ne sont pas nécessairement liées à cette version spécifique d’infrastructure. Chaque fonctionnalité spécifique possède ses propres exigences minimales en matière d’API .NET ou de common language runtime qui peuvent lui permettre de s’exécuter sur des infrastructures de bas niveau en incluant des packages NuGet ou d’autres bibliothèques.

  • Quel que soit le paramètre LangVersion que vous utilisez, utilisez la version active du common language runtime pour créer votre fichier .exe ou .dll. Les assemblys friend et ModuleAssemblyName, qui fonctionnent sous -langversion:ISO-1 est une exception.

Pour obtenir d’autres façons de spécifier la version du langage C#, consultez Contrôle de version du langage C#.

Pour plus d'informations sur la façon de définir cette option du compilateur par programme, consultez LanguageVersion.

spécification du langage C#

Version Lien Description
C# 8.0 et versions ultérieures Télécharger le PDF Spécification du langage C# version 7 : .NET Foundation
C# 7.3 Télécharger le PDF Norme ECMA-334 7e édition
C# 6.0 Télécharger le PDF Norme ECMA-334 6e édition
C# 5.0 Télécharger le PDF Norme ECMA-334 5e édition
C# 3.0 Télécharger DOC Spécification du langage C# version 3.0 : Microsoft Corporation
C# 2.0 Télécharger le PDF Norme ECMA-334 4e édition
C# 1.2 Télécharger DOC Norme ECMA-334 2e édition
C# 1.0 Télécharger DOC Norme ECMA-334 1re édition

Version minimale du SDK nécessaire pour prendre en charge toutes les fonctionnalités linguistiques

Le tableau suivant répertorie les versions minimales du SDK avec le compilateur C# qui prend en charge la version de langue correspondante :

Version de C# SDK logiciel minimum
C# 12 Microsoft Visual Studio/Build Tools 2022 version 17.8, ou Kit de développement logiciel (SDK) .NET 8
C# 11 SDK Microsoft Visual Studio/Build Tools 2022 version 17.4 ou .NET 7
C# 10 SDK Microsoft Visual Studio/Build Tools 2022 ou .NET 6
C# 9.0 SDK Microsoft Visual Studio/Build Tools 2019 version 16.8 ou .NET 5
C# 8.0 Microsoft Visual Studio/Build Tools 2019, version 16.3 ou SDK .NET Core 3.0
C# 7.3 Microsoft Visual Studio/Build Tools 2017, version 15.7
C# 7.2 Microsoft Visual Studio/Build Tools 2017, version 15.5
C# 7.1 Microsoft Visual Studio/Build Tools 2017, version 15.3
C# 7.0 Microsoft Visual Studio/Build Tools 2017
C# 6 Microsoft Visual Studio/Build Tools 2015
C# 5 Microsoft Visual Studio/Build Tools 2012 ou compilateur .NET Framework 4.5 groupé
C# 4 Microsoft Visual Studio/Build Tools 2010 ou compilateur .NET Framework 4.0 groupé
C# 3 Microsoft Visual Studio/Build Tools 2008 ou compilateur .NET Framework 3.5 groupé
C# 2 Microsoft Visual Studio/Build Tools 2005 ou compilateur .NET Framework 2.0 groupé
C# 1.0/1.2 Compilateur Microsoft Visual Studio/Build Tools .NET 2002 ou groupé .NET Framework 1.0

Nullable

Utilisez l’option Nullable pour spécifier le contexte nullable. Définissez-le dans la configuration du projet à l’aide de la <Nullable> balise :

<Nullable>enable</Nullable>

L’argument doit être l’un des arguments enable, disable, warnings ou annotations. L’argument enable active le contexte nullable. L’argument disable désactive le contexte nullable. L’argument warnings active le contexte d’avertissement nullable. L’argument annotations active le contexte d’annotation nullable. Pour plus d’informations sur ces valeurs, consultez contextes Nullables. Pour en savoir plus sur l’activation des types de référence nullables dans une base de code existante, consultez les stratégies de migration nullables.

Remarque

Si vous ne définissez pas de valeur, la valeur par défaut est disable. Toutefois, .NET modèles 6 et plus récents définissent la valeur enableNullable par défaut.

L’analyse de flux déduit la nullabilité des variables dans le code exécutable. La nullabilité déduite d’une variable est indépendante de la capacité null déclarée de la variable. Le compilateur analyse les appels de méthode même lorsque l’appel est omis de manière conditionnelle à partir de la sortie compilée. Par exemple, le compilateur analyse toujours un appel à Debug.Assert la possibilité de nullabilité, même si l’appel est conditionnel et n’est pas compilé dans les builds de mise en production.

L’appel de méthodes annotées avec les attributs suivants affecte également l’analyse des flux :

Important

Le contexte nullable global ne s’applique pas aux fichiers de code générés. Quel que soit ce paramètre, le contexte nullable est désactivé pour tout fichier source marqué comme généré. Un fichier est marqué comme généré de l’une des manières suivantes :

  1. Dans .editorconfig, spécifiez generated_code = true dans une section qui s’applique à ce fichier.
  2. Incluez <auto-generated> ou <auto-generated/> dans un commentaire en haut du fichier. Vous pouvez le placer sur n’importe quelle ligne du commentaire, mais le bloc de commentaires doit être le premier élément du fichier.
  3. Le nom du fichier doit commencer par TemporaryGeneratedFile_.
  4. Le nom du fichier doit se terminer par .designer.cs, .generated.cs, .g.cs ou .g.i.cs.

Les générateurs peuvent choisir à l’aide de la #nullable directive de préprocesseur.

  • Last updated on