C#-Compileroptionen für Sprachfeatureregeln

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: Allow unsafe code.
• DefineConstants / -define: Definieren von Symbolen für die 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 CheckForOverflowUnderflow ist, ist trueder Standardkontext ein aktivierter Kontext und die Überlaufüberprüfung ist aktiviert. Wenn CheckForOverflowUnderflow ist, ist falseder Standardkontext ein deaktivierter Kontext. Der Standardwert für diese Option lautet false, was bedeutet, dass die Überlaufüberprüfung deaktiviert ist.

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

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

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.

Aktivieren der aktualisierten Speichersicherheitsregeln

Die aktualisierten Speichersicherheitsregeln sind ein Vorschaufeature in C# 15 und .NET 11. Sie verwenden zwei unabhängige Compilereinstellungen:

• Die preview Sprachversion ermöglicht die neue Syntax und Zeigerentspannungen.
• Das updated-memory-safety-rules Compilerfeature ermöglicht die aktualisierten Regeln, einschließlich nicht unsicherer Aufruferverpflichtungen, und bewirkt, dass der Compiler die Auswahl in der Assembly mit dem MemorySafetyRulesAttribute Attribut aufzeichnen kann.

Eine zukünftige stabile SDK-Eigenschaft ist als dritte Aktivierungsstufe geplant, MemorySafetyRuleswenn das Feature die Vorschau beendet (z. B <MemorySafetyRules>2</MemorySafetyRules>. ), aber diese Eigenschaft noch nicht implementiert ist.

Verwenden Sie für ein Projekt beide Einstellungen:

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

Fügen Sie für ein dateibasiertes Programm die entsprechenden Direktiven hinzu:

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

Die AllowUnsafeBlocks-Eigenschaft ist unabhängig. Sie steuert, ob die Quelle das unsafe Schlüsselwort verwenden kann. Ein Projekt kann die aktualisierten Regeln aktivieren, ohne unsicheren Code zuzulassen, in diesem Fall empfängt es Fehler, wenn es aufruft, unsichere APIs.

Gibt an, ob eine Assembly die aktualisierten Regeln gegen eine andere erzwingt, hängt davon ab, welche Seite sich für Folgendes entscheidet:

• Aufrufer des aktualisierten Modells, Angerufener mit aktualisiertem Modell: Die Marker des unsafe Angerufenen durchlaufen Metadaten. Der Aufrufer umschließt jeden Aufruf an ein erfordertes unsicheres Element in einem unsafe Block.
• Aufrufer des Originalmodells, angerufener Originalmodell:Ein Kompatibilitätsmodus behandelt alle Angerufenen mit einem Zeigertyp in seiner Signatur als erforderlich unsicher, sodass die Anrufwebsite einen eingeschlossenen unsafe Block benötigt. Dieser Modus verhindert, dass eine zeigerbasierte API ihre unsafe Anforderung im Hintergrund verliert.
• Originalmodellanrufer, Angerufener mit aktualisiertem Modell: Die ursprünglichen Zeigerregeln gelten weiterhin. Ein unsicheres Element ohne Zeigertyp in seiner Signatur wird aus sicherem Code aufgerufen, da der ursprüngliche Modellaufrufer die neuen Markierungen nicht lesen kann.

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 LangVersion-Option bewirkt, dass der Compiler nur syntax akzeptiert, die in der angegebenen C#-Sprachspezifikation enthalten ist, z. B.:

<LangVersion>9.0</LangVersion>

Einige Vorschaufeatures erfordern zusätzlich zu <LangVersion>preview</LangVersion>. Beispielsweise verwenden die aktualisierten C# 15 Speichersicherheitsregeln das updated-memory-safety-rules Compilerfeature. Weitere Informationen finden Sie unter Aktivieren der aktualisierten Speichersicherheitsregeln.

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. Aktualisieren Sie das Zielframework, 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.

• Die Compileroption LangVersion wirkt sich nicht auf Metadaten aus, auf die von Ihrer C#-Anwendung verwiesen wird.

• 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 bestimmte Feature verfügt über eine eigene mindeste .NET API oder allgemeine Sprachlaufzeitanforderungen, mit denen es unter Umständen auf Frameworks auf Down-Level-Frameworks ausgeführt werden kann, indem NuGet-Pakete oder andere Bibliotheken eingeschlossen 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

Verwenden Sie die Nullable-Option , um den nullfähigen Kontext anzugeben. Legen Sie sie in der Konfiguration des Projekts mithilfe des <Nullable> Tags fest:

<Nullable>enable</Nullable>

Eines der folgenden Argumente muss verwendet werden: enable, disable, warnings oder annotations. Das enable Argument aktiviert den nullfähigen Kontext. Das disable Argument deaktiviert den nullfähigen Kontext. Das warnings Argument aktiviert den Kontext der NULL-Warnung. Das annotations Argument aktiviert den Kontext mit nullablen Anmerkungen. Weitere Informationen zu diesen Werten finden Sie unter Nullwerte.For more information about these values, see Nullable contexts. Weitere Informationen zum Aktivieren nullfähiger Verweistypen in einer vorhandenen Codebasis finden Sie unter Null-Migrationsstrategien.

Die Flussanalyse leitet die Nullierbarkeit von Variablen innerhalb von ausführbarem Code ab. Die abgeleitete NULL-Zulässigkeit einer Variable ist unabhängig von der deklarierten NULL-Zulässigkeit der Variable. Der Compiler analysiert Methodenaufrufe, auch wenn der Aufruf bedingt aus der kompilierten Ausgabe weggelassen wird. Beispielsweise analysiert der Compiler weiterhin einen Aufruf zur Debug.Assert Nullierbarkeit, obwohl der Aufruf bedingt ist und nicht in Releasebuilds kompiliert wird.

Der Aufruf von Methoden, die mit den folgenden Attributen versehen sind, wirkt sich auch auf die Flussanalyse aus:

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