C#-Compileroptionen für Sprachfunktionsregeln

  • Artikel

Mit den folgenden Optionen wird gesteuert, wie der Compiler Sprachfunktionen interpretiert. Die neue MSBuild-Syntax wird fett formatiert dargestellt. Die ältere csc.exe-Syntax wird in code style dargestellt.

  • CheckForOverflowUnderflow / -checked: Generiert Überlaufüberprüfungen.
  • AllowUnsafeBlocks / -unsafe: Lässt „unsicheren“ Code zu.
  • DefineConstants / -define: Definiert Symbole für bedingte Kompilierung.
  • LangVersion / -langversion: Gibt die Sprachversion an, z. B. default (letzte Hauptversion) oder latest (neueste Version, einschließlich Nebenversionen).
  • Nullable / -nullable: Lässt Kontext mit Nullwerten oder Warnungen mit Nullwerten zu.

CheckForOverflowUnderflow

Die Option CheckForOverflowUnderflow steuert den standardmäßigen Überlaufüberprüfungskontext, der das Programmverhalten definiert, wenn ganzzahlige arithmetische Überläufe auftreten.

<CheckForOverflowUnderflow>true</CheckForOverflowUnderflow>

Wenn CheckForOverflowUnderflowtrue ist, ist der Standardkontext ein überprüfter Kontext, und die Überlaufüberprüfung ist aktiviert. Andernfalls ist der Standardkontext ein nicht überprüfter Kontext. Der Standardwert für diese Option lautet false, d. h. die Überlaufüberprüfung ist deaktiviert.

Sie können den Überlaufüberprüfungskontext für die Teile Ihres Codes mit den Anweisungen checked und unchecked auch explizit steuern.

Informationen dazu, wie sich der Überlaufüberprüfungskontext auf Vorgänge auswirkt, und welche Vorgänge betroffen sind, finden Sie im Artikel zu den Anweisungen checked und unchecked.

AllowUnsafeBlocks

Die Compileroption AllowUnsafeBlocks ermöglicht das Kompilieren von Code, der das Schlüsselwort unsafe verwendet. Der Standardwert für diese Option ist false, d. h. unsicherer Code ist unzulässig.

<AllowUnsafeBlocks>true</AllowUnsafeBlocks>

Weitere Informationen zu unsicherem Code finden Sie unter Unsicherer Code und Zeiger.

DefineConstants

Die Option DefineConstants definiert Symbole in allen Quellcodedateien Ihres Programms.

<DefineConstants>name;name2</DefineConstants>

Diese Option gibt die Namen eines oder mehrerer Symbole an, die Sie definieren möchten. Die Option DefineConstants hat dieselbe Auswirkung wie die Verwendung einer #define-Präprozessoranweisung, außer dass die Compileroption für alle Dateien im Projekt gültig ist. Ein Symbol bleibt in einer Quelldatei definiert, bis eine #undef-Anweisung in der Quelldatei die Definition entfernt. Wenn Sie die Option -define verwenden, hat eine #undef-Anweisung in einer Datei keinerlei Auswirkung auf andere Quellcodedateien im Projekt. Sie können die durch diese Option erstellten Symbole in Verbindung mit #if, #else, #elif, und #endif verwenden, um Quelldateien bedingt zu kompilieren. Der C#-Compiler selbst definiert keine Symbole oder Makros, die Sie in Ihrem Quellcode verwenden können. Alle Symboldefinitionen müssen benutzerdefiniert sein.

Hinweis

Die C#-Direktive #define erlaubt es nicht, einem Symbol wie in Sprachen wie C++ einen Wert zuzuweisen. Beispielsweise kann #define nicht zum Erstellen eines Makros oder zum Definieren einer Konstante verwendet werden. Falls Sie eine Konstante definieren müssen, verwenden Sie eine enum-Variable. Wenn Sie ein C++-übliches Makro erstellen möchten, erwägen Sie Alternativen wie Generics. Da Makros sehr fehleranfällig sind, ist ihre Verwendung in C# nicht zugelassen. Es stehen jedoch sicherere Alternativen zur Verfügung.

LangVersion

Die Standardsprachversion für den C#-Compiler ist vom Zielframework für Ihre Anwendung und der installierten SDK- oder Visual Studio-Version abhängig. Diese Regeln werden in der C#-Sprachversionsverwaltung definiert.

Die Option LangVersion bewirkt, dass der Compiler nur Syntax akzeptiert, die in der angegebenen C#-Sprachspezifikation enthalten ist, z. B.:

<LangVersion>9.0</LangVersion>

Folgende Werte sind gültig:

Wert Bedeutung
preview Der Compiler akzeptiert jede gültige Sprachsyntax der letzten Vorschauversion.
latest Der Compiler akzeptiert die Syntax der neuesten veröffentlichte Version des Compilers (einschließlich Nebenversionen).
latestMajor
oder default		 Der Compiler akzeptiert die Syntax der neuesten veröffentlichte Hauptversion des Compilers.
12.0 Der Compiler akzeptiert nur Syntax von C# 12 oder niedriger.
11.0 Der Compiler akzeptiert nur Syntax von C# 11 oder niedriger.
10.0 Der Compiler akzeptiert nur Syntax, die in C# 10 oder niedriger enthalten ist.
9.0 Der Compiler akzeptiert nur Syntax, die in C# 9 oder niedriger enthalten ist.
8.0 Der Compiler akzeptiert nur Syntax, die in C# 8.0 oder niedriger enthalten ist.
7.3 Der Compiler akzeptiert nur Syntax, die in C# 7.3 oder früher enthalten ist.
7.2 Der Compiler akzeptiert nur Syntax, die in C# 7.2 oder früher enthalten ist.
7.1 Der Compiler akzeptiert nur Syntax, die in C# 7.1 oder früher enthalten ist.
7 Der Compiler akzeptiert nur Syntax, die in C# 7.0 oder früher enthalten ist.
6 Der Compiler akzeptiert nur Syntax, die in C# 6.0 oder früher enthalten ist.
5 Der Compiler akzeptiert nur Syntax, die in C# 5.0 oder früher enthalten ist.
4 Der Compiler akzeptiert nur Syntax, die in C# 4.0 oder früher enthalten ist.
3 Der Compiler akzeptiert nur Syntax, die in C# 3.0 oder früher enthalten ist.
ISO-2
oder 2		 Der Compiler akzeptiert nur Syntax, die in ISO/IEC 23270:2006 C# (2.0) enthalten ist.
ISO-1
oder 1		 Der Compiler akzeptiert nur Syntax, die in ISO/IEC 23270:2003 C# (1.0/1.2) enthalten ist.

Wichtig

Der latest-Wert wird im Allgemeinen nicht empfohlen. Mit latest aktiviert der Compiler die neuesten Features, auch wenn diese Features von Updates abhängen, die im konfigurierten Zielframework nicht enthalten sind.

Überlegungen

  • Um sicherzustellen, dass Ihr Projekt die für Ihr Zielframework empfohlene Standardcompilerversion verwendet, verwenden Sie nicht die Option LangVersion. Sie können das Zielframework aktualisieren, um auf neuere Sprachfeatures zuzugreifen.

  • Die Angabe von LangVersion mit dem Wert default entspricht nicht dem Weglassen der Option LangVersion. Bei der Angabe von default wird die neueste Version der Sprache verwendet, die der Compiler unterstützt, ohne das Zielframework zu berücksichtigen. Beispielsweise wird beim Erstellen eines Projekts für .NET 6 über Visual Studio-Version 17.6 C# 10 verwendet, wenn LangVersion nicht angegeben ist. Wenn LangVersion auf default festgelegt ist, wird hingegen C# 11 verwendet.

  • Metadaten, auf die von Ihrer C#-Anwendung verwiesen wird, unterliegen nicht der Compileroption LangVersion.

  • Da jede Version des C#-Compilers Erweiterungen der Sprachspezifikation enthält, bietet LangVersion Ihnen nicht die gleiche Funktionalität wie die einer früheren Compilerversion.

  • Die neue Syntax und die neuen Features sind nicht unbedingt an die spezifische Framework-Version gebunden, während C#-Versionsupdates für gewöhnlich mit den .NET-Hauptversionen übereinstimmen. Jedes Feature hat seine eigenen mindestens erforderlichen .NET-API- oder CLR-Anforderungen, durch die es auf abwärtskompatiblen Frameworks ausgeführt werden kann, indem NuGet-Pakete oder andere Bibliotheken einbezogen werden.

  • Unabhängig von der verwendeten LangVersion-Einstellung verwenden Sie die aktuelle Version der CLR, um Ihre EXE- oder DLL-Dateien zu erstellen. Davon ausgenommen sind Friend-Assemblys und ModuleAssemblyName, die unter -langversion:ISO-1 ausgeführt werden.

Weitere Möglichkeiten zum Angeben der C#-Sprachversion finden Sie unter C#-Sprachversionsverwaltung.

Informationen zum programmgesteuerten Festlegen dieser Compileroption finden Sie unter LanguageVersion.

C#-Sprachspezifikation

Version Link Beschreibung
C# 8.0 und höher PDF herunterladen C#-Sprachspezifikation Version 7: .NET Foundation
C# 7.3 PDF herunterladen Standard ECMA-334, 7. Edition
C# 6.0 PDF herunterladen Standard ECMA-334, 6. Edition
C# 5.0 PDF herunterladen Standard ECMA-334, 5. Edition
C# 3.0 DOC herunterladen C#-Programmiersprachenspezifikation Version 3.0: Microsoft Corporation
C# 2.0 PDF herunterladen Standard ECMA-334, 4. Edition
C# 1.2 DOC herunterladen Standard ECMA-334, 2. Edition
C# 1.0 DOC herunterladen Standard ECMA-334, 1. Edition

Mindestens erforderliche SDK-Version, die erforderlich ist, um alle Sprachfeatures zu unterstützen

In der folgenden Tabelle sind die Mindestversionen des SDK mit dem C#-Compiler aufgeführt, der die entsprechende Sprachversion unterstützt:

C#-Version Mindestversion des SDK
C# 12 Microsoft Visual Studio/Build Tools 2022, Version 17.8 oder .NET 8 SDK
C# 11 Microsoft Visual Studio/Build Tools 2022, Version 17.4 oder .NET 7 SDK
C# 10 Microsoft Visual Studio/Build Tools 2022 oder .NET SDK 6
C# 9.0 Microsoft Visual Studio/Build Tools 2019, Version 16.8 oder .NET 5 SDK
C# 8.0 Microsoft Visual Studio/Build Tools 2019, Version 16.3, oder .NET Core 3.0 SDK
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 oder gebündelter .NET Framework 4.5-Compiler
C# 4 Microsoft Visual Studio/Build Tools 2010 oder gebündelter .NET Framework 4.0-Compiler
C# 3 Microsoft Visual Studio/Build Tools 2008 oder gebündelter .NET Framework 3.5-Compiler
C# 2 Microsoft Visual Studio/Build Tools 2005 oder gebündelter .NET Framework 2.0-Compiler
C# 1.0/1.2 Microsoft Visual Studio/Build Tools .NET 2002 oder gebündelter .NET Framework 1.0-Compiler

Nullwerte zulässig

Mit der Option Nullable können Sie den Kontext festlegen, der Nullwerte zulässt. Sie kann in der Konfiguration des Projekts mithilfe des <Nullable>-Tags festgelegt werden:

<Nullable>enable</Nullable>

Eines der folgenden Argumente muss verwendet werden: enable, disable, warnings oder annotations. Das Argument enable aktiviert den Nullwerte zulassenden Kontext. Durch Angeben von disable wird der Nullwerte zulassende Kontext deaktiviert. Wenn Sie das warnings-Argument angeben, wird der Nullwerte zulassende Warnungskontext aktiviert. Wenn Sie das annotations-Argument angeben, wird der Nullwerte zulassende Anmerkungskontext aktiviert. Die Werte werden im Artikel zu Nullwerte zulassenden Kontexten beschrieben und erläutert. Weitere Informationen zu den Aufgaben, die beim Aktivieren von Nullwerte zulassenden Verweistypen in einer vorhandenen Codebasis erforderlich sind, finden Sie in unserem Artikel zu Nullwerte zulassenden Migrationsstrategien.

Hinweis

Wenn kein Wert festgelegt ist, wird der Standardwert disable angewendet, die .NET 6-Vorlagen werden jedoch standardmäßig mit dem Nullwerte zulassenden Wert bereitgestellt, der auf enable festgelegt ist.

Die Ablaufsteuerungsanalyse wird dazu verwendet, die NULL-Zulässigkeit von Variablen in ausführbarem Code abzuleiten. Die abgeleitete NULL-Zulässigkeit einer Variable ist unabhängig von der deklarierten NULL-Zulässigkeit der Variable. Methodenaufrufe werden auch analysiert, wenn sie bedingt ausgelassen werden. Dies gilt beispielsweise für die Methode Debug.Assert im Releasemodus.

Das Aufrufen von Methoden, die mit den folgenden Attributen versehen sind, wirken sich auf die Ablaufsteuerungsanalyse aus:

Wichtig

Der globale Nullable-Kontext gilt nicht für generierte Codedateien. Der Nullable-Kontext ist unabhängig von dieser Einstellung für alle als generiert gekennzeichneten Quelldateien deaktiviert. Es gibt viel Möglichkeiten, eine Datei als generiert zu markieren:

  1. Geben Sie in der EDITORCONFIG-Datei generated_code = true in einem Abschnitt an, der für diese Datei gilt.
  2. Fügen Sie <auto-generated> oder <auto-generated/> ganz oben in der Datei in einem Kommentar ein. Dabei kann es sich um eine beliebige Zeile des Kommentars handeln, jedoch muss es sich beim Kommentarblock um das erste Element in der Datei handeln.
  3. Beginnen Sie den Dateinamen mit TemporaryGeneratedFile_ .
  4. Enden Sie den Dateinamen mit .designer.cs, .generated.cs, .g.cs oder .g.i.cs.

Generatoren können die Präprozessoranweisung #nullable verwenden.