C#-kompilatoralternativ för språkfunktionsregler

Följande alternativ styr hur kompilatorn tolkar språkfunktioner. Den nya MSBuild-syntaxen visas i Fetstil. Den äldre csc.exe syntaxen visas i code style.

• CheckForOverflowUnderflow / -checked: Generera spillkontroller.
• AllowUnsafeBlocks / -unsafe: Tillåt unsafe kod.
• DefineConstants: Definiera villkorsstyrda kompileringssymboler / -define.
• LangVersion / -langversion: Ange språkversion som default (senaste huvudversion) eller latest (senaste version, inklusive delversioner).
• Nullbar / -nullable: Aktivera nullbar kontext eller nullbara varningar.

Kommentar

Mer information om hur du konfigurerar de här alternativen för projektet finns i Kompilatoralternativ.

CheckForOverflowUnderflow

Alternativet CheckForOverflowUnderflow styr standardkontexten för spillkontroll som definierar programmets beteende om heltalsaritmetiska spill.

<CheckForOverflowUnderflow>true</CheckForOverflowUnderflow>

När CheckForOverflowUnderflow är trueär standardkontexten en markerad kontext och spillkontroll är aktiverad. När CheckForOverflowUnderflow är falseär standardkontexten en omarkerad kontext. Standardvärdet för det här alternativet är false, vilket innebär att spillkontroll är inaktiverat.

Du kan också uttryckligen styra överflödeskontrollkontexten för delar av koden med hjälp av instruktionen checked och unchecked .

Information om hur överflödeskontrollkontexten påverkar åtgärder och vilka åtgärder den påverkar finns i artikeln om checked och unchecked -instruktioner.

AllowUnsafeBlocks

Kompileringsalternativet AllowUnsafeBlocks tillåter kod som använder det osäkra nyckelordet för kompilering. Standardvärdet för det här alternativet är false, vilket innebär att osäker kod inte tillåts.

<AllowUnsafeBlocks>true</AllowUnsafeBlocks>

Mer information om osäker kod finns i Osäker kod och pekare.

Aktivera de uppdaterade minnessäkerhetsreglerna

De uppdaterade reglerna för minnessäkerhet är en förhandsversionsfunktion i C# 15 och .NET 11. De använder två oberoende kompilatorinställningar:

• Språkversionen preview aktiverar den nya syntaxen och pekaravslappningar.
• Kompileringsfunktionen updated-memory-safety-rules aktiverar de uppdaterade reglerna, inklusive krav på osäkra uppringare, och gör att kompilatorn registrerar valet i sammansättningen med MemorySafetyRulesAttribute attributet .

En framtida stabil SDK-egenskap, MemorySafetyRules, planeras som en tredje aktiveringsnivå för när funktionen avslutar förhandsversionen (till exempel <MemorySafetyRules>2</MemorySafetyRules>), men den egenskapen har inte implementerats ännu.

Använd båda inställningarna för ett projekt:

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

För ett filbaserat program lägger du till motsvarande direktiv:

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

Egenskapen AllowUnsafeBlocks är oberoende. Den styr om källan kan använda nyckelordet unsafe . Ett projekt kan aktivera de uppdaterade reglerna utan att tillåta osäker kod, i vilket fall det får fel när det anropar kräver osäkra API:er.

Om en sammansättning tillämpar de uppdaterade reglerna mot en annan beror på vilken sida som väljer:

• Uppringare för uppdaterad modell, uppringare av uppdaterad modell: Anroparens markörer färdas unsafe genom metadata. Anroparen omsluter varje anrop till en medlem som kräver osäkert i ett unsafe block.
• Anroparen för den uppdaterade modellen, den ursprungliga modellens anropare: Ett kompatibilitetsläge behandlar alla samtalsmedlemmar med en pekartyp i signaturen som kräver osäkert, så anropswebbplatsen behöver ett omslutande unsafe block. Det här läget hindrar ett pekarbaserat API från att tyst förlora sina unsafe krav.
• Anropare för ursprunglig modell, anropare för uppdaterad modell: De ursprungliga pekarreglerna gäller fortfarande. En kräver osäker medlem som inte har någon pekartyp i sin signatur blir anropsbar från säker kod, eftersom den ursprungliga modellens anropare inte kan läsa de nya markörer.

DefineConstants

Alternativet DefineConstants definierar symboler i alla källkodsfiler i ditt program.

<DefineConstants>name;name2</DefineConstants>

Det här alternativet anger namnen på en eller flera symboler som du vill definiera. Alternativet DefineConstants har samma effekt som det #define förprocessordirektivet, förutom att kompilatoralternativet gäller för alla filer i projektet. En symbol förblir definierad i en källfil tills ett #undef-direktiv i källfilen tar bort definitionen. När du använder -define alternativet har ett #undef direktiv i en fil ingen effekt på andra källkodsfiler i projektet. Du kan använda symboler som skapats med det här alternativet med #if, #else, #elif och #endif för att kompilera källfiler villkorligt. Själva C#-kompilatorn definierar inga symboler eller makron som du kan använda i källkoden. alla symboldefinitioner måste vara användardefinierade.

Kommentar

C#- #define direktivet tillåter inte att en symbol har ett värde, som på språk som C++. Det går till exempel #define inte att skapa ett makro eller definiera en konstant. Om du behöver definiera en konstant använder du en enum variabel. Om du vill skapa ett C++-liknande makro bör du överväga alternativ som generiska objekt. Eftersom makron är notoriskt felbenägna tillåter C# inte användning men ger säkrare alternativ.

LangVersion

Standardspråkversionen för C#-kompilatorn beror på målramverket för ditt program och vilken version av SDK eller Visual Studio som är installerad. Dessa regler definieras i C#-språkversioner.

Varning

Ställ inte in elementet på LangVersionlatest. Inställningen latest innebär att den installerade kompilatorn använder sin senaste version. Den versionen kan ändras från dator till dator, vilket gör byggen otillförlitliga. Dessutom möjliggör den språkfunktioner som kan kräva körnings- eller biblioteksfunktioner som inte ingår i den aktuella SDK:t.

Alternativet LangVersion gör att kompilatorn endast accepterar syntax som ingår i den angivna C#-språkspecifikationen, till exempel:

<LangVersion>9.0</LangVersion>

Vissa förhandsgranskningsfunktioner kräver en separat anmälning utöver <LangVersion>preview</LangVersion>. Till exempel använder C# 15 uppdaterade minnessäkerhetsregler kompileringsfunktionen updated-memory-safety-rules . Mer information finns i Aktivera de uppdaterade minnessäkerhetsreglerna.

Följande värden är giltiga:

Värde	Innebörd
preview	Kompilatorn accepterar alla giltiga språksyntaxer från den senaste förhandsversionen.
latest	Kompilatorn accepterar syntax från den senaste versionen av kompilatorn (inklusive delversion).
latestMajor eller default	Kompilatorn accepterar syntax från den senaste versionen av huvudversionen av kompilatorn.
15.0	Kompilatorn accepterar endast syntax som ingår i C# 15 eller lägre.
14.0	Kompilatorn accepterar endast syntax som ingår i C# 14 eller lägre.
13.0	Kompilatorn accepterar endast syntax som ingår i C# 13 eller lägre.
12.0	Kompilatorn accepterar endast syntax som ingår i C# 12 eller lägre.
11.0	Kompilatorn accepterar endast syntax som ingår i C# 11 eller lägre.
10.0	Kompilatorn accepterar endast syntax som ingår i C# 10 eller lägre.
9.0	Kompilatorn accepterar endast syntax som ingår i C# 9 eller lägre.
8.0	Kompilatorn accepterar endast syntax som ingår i C# 8.0 eller lägre.
7.3	Kompilatorn accepterar endast syntax som ingår i C# 7.3 eller lägre.
7.2	Kompilatorn accepterar endast syntax som ingår i C# 7.2 eller lägre.
7.1	Kompilatorn accepterar endast syntax som ingår i C# 7.1 eller lägre.
7	Kompilatorn accepterar endast syntax som ingår i C# 7.0 eller lägre.
6	Kompilatorn accepterar endast syntax som ingår i C# 6.0 eller lägre.
5	Kompilatorn accepterar endast syntax som ingår i C# 5.0 eller lägre.
4	Kompilatorn accepterar endast syntax som ingår i C# 4.0 eller lägre.
3	Kompilatorn accepterar endast syntax som ingår i C# 3.0 eller lägre.
ISO-2 eller 2	Kompilatorn accepterar endast syntax som ingår i ISO/IEC 23270:2006 C# (2.0).
ISO-1 eller 1	Kompilatorn accepterar endast syntax som ingår i ISO/IEC 23270:2003 C# (1.0/1.2).

Att tänka på

• Använd inte alternativet LangVersion för att säkerställa att ditt projekt använder den standardkompilatorversion som rekommenderas för ditt målramverk. Uppdatera målramverket för att få åtkomst till nyare språkfunktioner.

• Att ange LangVersion med default värdet skiljer sig från att utelämna alternativet LangVersion . När du anger default används den senaste versionen av språket som kompilatorn stöder, utan att ta hänsyn till målramverket. Om du till exempel skapar ett projekt som riktar sig mot .NET 6 från Visual Studio version 17.6 används C# 10 om LangVersion inte har angetts, men använder C# 11 om LangVersion är inställt på default.

• Alternativet LangVersion-kompilator påverkar inte metadata som refereras av C#-programmet.

• Eftersom varje version av C#-kompilatorn innehåller tillägg till språkspecifikationen ger LangVersion inte motsvarande funktioner i en tidigare version av kompilatorn.

• Även om C#-versionsuppdateringar vanligtvis sammanfaller med större .NET-versioner, är den nya syntaxen och funktionerna inte nödvändigtvis knutna till den specifika ramverksversionen. Varje specifik funktion har sitt eget minsta .NET API eller vanliga språkkörningskrav som kan göra att den kan köras på ramverk på nednivå genom att inkludera NuGet-paket eller andra bibliotek.

• Oavsett vilken LangVersion-inställning du använder använder du den aktuella versionen av den vanliga språkkörningen för att skapa .exe eller .dll. Ett undantag är vänsammansättningar och ModuleAssemblyName, som fungerar under -langversion:ISO-1.

Andra sätt att ange C#-språkversionen finns i C#-språkversioner.

Information om hur du ställer in det här kompilatoralternativet programmatiskt finns i LanguageVersion.

Språkspecifikation för C#

Version	Länk	beskrivning
C# 8.0 och senare	ladda ned PDF	C#-språkspecifikation version 7: .NET Foundation
C# 7.3	ladda ned PDF	Standard ECMA-334 7th Edition
C# 6.0	ladda ned PDF	Standard ECMA-334 6th Edition
C# 5.0	Ladda ned PDF	Standard ECMA-334 5th Edition
C# 3.0	Ladda ned DOC	C# Language Specification Version 3.0: Microsoft Corporation
C# 2.0	Ladda ned PDF	Standard ECMA-334 4th Edition
C# 1.2	Ladda ned DOC	Standard ECMA-334 2nd Edition
C# 1.0	Ladda ned DOC	Standard ECMA-334 1st Edition

Lägsta SDK-version som krävs för att stödja alla språkfunktioner

I följande tabell visas de lägsta versionerna av SDK:t med C#-kompilatorn som stöder motsvarande språkversion:

C#-version	Minimum SDK-version
C# 12	Microsoft Visual Studio/Build Tools 2022 version 17.8 eller .NET 8 SDK
C# 11	Microsoft Visual Studio/Build Tools 2022 version 17.4 eller .NET 7 SDK
C# 10	Microsoft Visual Studio/Build Tools 2022 eller .NET 6 SDK
C# 9.0	Microsoft Visual Studio/Build Tools 2019 version 16.8 eller .NET 5 SDK
C# 8.0	Microsoft Visual Studio/Build Tools 2019, version 16.3 eller .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 eller en paketerad .NET Framework 4.5-kompilator
C# 4	Microsoft Visual Studio/Build Tools 2010 eller en paketerad .NET Framework 4.0-kompilator
C# 3	Microsoft Visual Studio/Build Tools 2008 eller en paketerad .NET Framework 3.5-kompilator
C# 2	Microsoft Visual Studio/Build Tools 2005 eller en paketerad .NET Framework 2.0-kompilator
C# 1.0/1.2	Microsoft Visual Studio/Build Tools .NET 2002 eller en paketerad .NET Framework 1.0-kompilator

Kan ha värdet null

Använd alternativet Nullable för att ange den nullbara kontexten. Ange den i projektets konfiguration med hjälp av taggen <Nullable> :

<Nullable>enable</Nullable>

Argumentet måste vara ett av enable, disable, warningseller annotations. Argumentet enable aktiverar den nullbara kontexten. Argumentet disable inaktiverar den nullbara kontexten. Argumentet warnings aktiverar den nullbara varningskontexten. Argumentet annotations aktiverar den nullbara anteckningskontexten. Mer information om dessa värden finns i Null-kontexter. Mer information om hur du aktiverar nullbara referenstyper i en befintlig kodbas finns i migreringsstrategier som kan upphävas.

Kommentar

Om du inte anger något värde är disablestandardvärdet . Men .NET 6 och senare mallar anger värdet Nullable till enable som standard.

Flödesanalysen härleder nullbarheten för variabler i körbar kod. Den härledda nullabiliteten för en variabel är oberoende av variabelns deklarerade nullabilitet. Kompilatorn analyserar metodanrop även när anropet utelämnas villkorligt från kompilerade utdata. Kompilatorn analyserar till exempel fortfarande ett anrop till Debug.Assert för nullabilitet även om anropet är villkorligt och inte kompileras till versionsversioner.

Anrop av metoder som kommenterats med följande attribut påverkar också flödesanalysen:

• Enkla förutsättningar: AllowNullAttribute och DisallowNullAttribute
• Enkla postconditions: MaybeNullAttribute och NotNullAttribute
• Villkorsstyrda postkonditioner: MaybeNullWhenAttribute och NotNullWhenAttribute
• DoesNotReturnIfAttribute (till exempel DoesNotReturnIf(false) för Debug.Assert) och DoesNotReturnAttribute
• NotNullIfNotNullAttribute
• Medlemspostkonditioner: MemberNotNullAttribute(String) och MemberNotNullAttribute(String[])

Viktigt!

Den globala nullbara kontexten gäller inte för genererade kodfiler. Oavsett den här inställningen inaktiveras den nullbara kontexten för alla källfiler som har markerats som genererade. En fil markeras som genererad på något av följande sätt:

1. I .editorconfig anger du generated_code = true i ett avsnitt som gäller för filen.
2. Inkludera <auto-generated> eller <auto-generated/> i en kommentar överst i filen. Du kan placera den på valfri rad i kommentaren, men kommentarsblocket måste vara det första elementet i filen.
3. Starta filnamnet med TemporaryGeneratedFile_
4. Avsluta filnamnet med .designer.cs, .generated.cs, .g.cs eller .g.i.cs.

Generatorer kan välja att delta med hjälp #nullable av förprocessordirektivet.