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 le code « non sécurisé ». - DefineConstants /
-define: définir des symboles de compilation conditionnelle. - LangVersion /
-langversion: spécifier la version de langue telle quedefault(dernière version majeure) oulatest(dernière version, y compris les versions mineures). - Nullable /
-nullable: activer le contexte nullable ou les avertissements nullables.
Remarque
Reportez-vous à la section Options du compilateur pour plus d'informations sur la configuration de ces options pour votre projet.
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. Sinon, le contexte par défaut est un contexte non vérifié. La valeur par défaut de cette option est false. C’est-à-dire 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 les parties de votre code à l’aide des instructions checked et unchecked.
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 affectées, consultez l’article sur les instructions checked et unchecked.
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.
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.
Notes
La directive C# #define ne permet de donner une valeur à un symbole, comme dans les langages tels que C++. Par exemple, l’option #define ne peut pas être utilisée pour créer une 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 l’alternative que constituent les 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
Il est déconseillé d'attribuer à l'élément LangVersion la valeur latest. Le paramètre latest signifie que le compilateur installé utilise sa dernière version. Cette version peut changer d'une machine à l'autre, ce qui rend les compilations peu fiables. En outre, il active des fonctionnalités du langage qui peuvent nécessiter des fonctionnalités d'exécution ou de bibliothèque qui ne sont pas incluses dans le SDK actuel.
L’option LangVersion permet au compilateur d’accepter uniquement la syntaxe incluse dans la spécification du langage C# spécifiée, par exemple :
<LangVersion>9.0</LangVersion>
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). |
latestMajorou default |
Le compilateur accepte la syntaxe de la dernière version principale publiée du compilateur. |
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-2ou 2 |
Le compilateur accepte uniquement la syntaxe incluse dans ISO/IEC 23270:2006 C# (2.0) |
ISO-1ou 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. Vous pouvez mettre à jour le framework cible pour accéder aux fonctionnalités de langage plus récentes.
Spécifier LangVersionavec la valeur
defaultest différent d’omettre l’option LangVersion. Spécifierdefaultutilise 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 surdefault.Les métadonnées référencées par votre application C# ne sont pas visées par l’option de compilateur LangVersion.
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 a ses propres exigences minimales relatives à l’API .NET ou au Common Language Runtime pour pouvoir s’exécuter sur des frameworks 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
L’option Nullable vous permet de spécifier le contexte nullable. Elle peut être définie dans la configuration du projet à l’aide de la balise <Nullable> :
<Nullable>enable</Nullable>
L’argument doit être l’un des arguments enable, disable, warnings ou annotations. L’argument enable active le contexte nullable. La spécification disable désactive le contexte nullable. Lorsque vous spécifiez l’argument warnings, le contexte d’avertissement nullable est activé. Lorsque vous spécifiez l’argument annotations, le contexte d’annotation nullable est activé. Les valeurs sont décrites et expliquées dans l’article sur les contextes nullables. Vous pouvez en savoir plus sur les tâches impliquées dans l’activation des types de référence Nullable dans une base de code existante dans notre article sur les stratégies de migration nullables.
Notes
Quand aucune valeur n’est définie, la valeur disable par défaut est appliquée, mais les modèles .NET 6 sont fournis par défaut avec la valeur Nullable définie sur enable.
L’analyse de flux est utilisée pour déduire 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. Les appels de méthode sont analysés même lorsqu’ils sont omis de manière conditionnelle. Par exemple, Debug.Assert en mode mise en production.
L’appel de méthodes annotées avec les attributs suivants affecte également l’analyse des flux :
- Conditions préalables simples : AllowNullAttribute et DisallowNullAttribute
- Conditions post-conditions simples : MaybeNullAttribute et NotNullAttribute
- Conditions post-conditions conditionnelles : MaybeNullWhenAttribute et NotNullWhenAttribute
- DoesNotReturnIfAttribute (par exemple,
DoesNotReturnIf(false)pour Debug.Assert) et DoesNotReturnAttribute - NotNullIfNotNullAttribute
- Conditions post-membres : MemberNotNullAttribute(String) et MemberNotNullAttribute(String[])
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 quatre façons :
- Dans .editorconfig, spécifiez
generated_code = truedans une section qui s’applique à ce fichier. - Placez
<auto-generated/>ou<auto-generated>dans un commentaire en haut du fichier. Il peut se trouver sur n’importe quelle ligne de ce commentaire, mais le bloc de commentaires doit être le premier élément du fichier. - Le nom du fichier doit commencer par TemporaryGeneratedFile_.
- Le nom du fichier doit se terminer par .designer.cs, .generated.cs, .g.cs ou .g.i.cs.
Les générateurs peuvent opter pour l’utilisation de la directive de préprocesseur #nullable.
