C#-Compileroptionen für Sprachfunktionsregeln

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.

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:

Ü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

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:

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.

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:

• Einfache Vorbedingungen: AllowNullAttribute und DisallowNullAttribute
• Einfache Nachbedingungen: MaybeNullAttribute und NotNullAttribute
• Bedingte Nachbedingungen: MaybeNullWhenAttribute und NotNullWhenAttribute
• DoesNotReturnIfAttribute (z. B. DoesNotReturnIf(false) für Debug.Assert) und DoesNotReturnAttribute
• NotNullIfNotNullAttribute
• Nachbedingungen für Member: MemberNotNullAttribute(String) und MemberNotNullAttribute(String[])