C#-fordító beállításai a nyelvi funkciók szabályaihoz

Az alábbi beállítások szabályozzák, hogy a fordító hogyan értelmezi a nyelvi funkciókat. Az új MSBuild szintaxis félkövér formátumban jelenik meg. A régebbi csc.exe szintaxis a .code style

  • CheckForOverflowUnderflow / -checked: Túlcsordulási ellenőrzések létrehozása.
  • AllowUnsafeBlocks / -unsafe: Kód engedélyezése unsafe .
  • DefineConstants / -define: Feltételes fordítási szimbólumok definiálása.
  • LangVersion / -langversion: Adja meg az olyan nyelvi verziókat, mint default a (legújabb főverzió) vagy latest a (legújabb verzió, beleértve az alverziókat is).
  • Null értékű / -nullable: Null értékű környezet vagy null értékű figyelmeztetések engedélyezése.

Feljegyzés

A projekt beállításainak konfigurálásáról további információt a Fordító beállításai című témakörben talál.

CheckForOverflowUnderflow

A CheckForOverflowUnderflow beállítás szabályozza az alapértelmezett túlcsordulás-ellenőrzési környezetet, amely meghatározza a program viselkedését egész számtani túlcsordulások esetén.

<CheckForOverflowUnderflow>true</CheckForOverflowUnderflow>

Ha a CheckForOverflowUnderflow értéke, trueaz alapértelmezett környezet egy ellenőrzött környezet, és a túlcsordulás ellenőrzése engedélyezve van. Ha a CheckForOverflowUnderflow értéke, falseaz alapértelmezett környezet egy nem ellenőrzött környezet. Ennek a beállításnak az alapértelmezett értéke az false, ami azt jelenti, hogy a túlcsordulás ellenőrzése le van tiltva.

A kód egyes részeinek túlcsordulás-ellenőrzési környezetét is explicit módon szabályozhatja az utasítások és unchecked az checked utasítások használatával.

További információ arról, hogy a túlcsordulás-ellenőrzési környezet milyen hatással van a műveletekre, és milyen műveleteket érint, tekintse meg a cikket checked és unchecked az utasításokat.

AllowUnsafeBlocks

Az AllowUnsafeBlocks fordítóbeállítás lehetővé teszi a nem biztonságos kulcsszót használó kód fordítását. Ennek a beállításnak az alapértelmezett értéke, falsevagyis a nem biztonságos kód nem engedélyezett.

<AllowUnsafeBlocks>true</AllowUnsafeBlocks>

A nem biztonságos kódról további információt a Nem biztonságos kód és a Mutatók című témakörben talál.

A frissített memóriabiztonsági szabályok engedélyezése

A frissített memóriabiztonsági szabályok a C# 15 és .NET 11 előzetes verziója. Két független fordítóbeállítást használnak:

  • A preview nyelvi verzió lehetővé teszi az új szintaxist és a mutató relaxációit.
  • A updated-memory-safety-rules fordító funkció lehetővé teszi a frissített szabályokat, beleértve a nem biztonságos hívói kötelezettségeket is, és emiatt a fordító az attribútummal rögzíti a választást a MemorySafetyRulesAttribute szerelvényben.

Egy jövőbeli stabil SDK-tulajdonságot MemorySafetyRulesharmadik aktiválási szintként tervezünk, amikor a funkció kilép az előzetes verzióból (például <MemorySafetyRules>2</MemorySafetyRules>), de ez a tulajdonság még nincs implementálva.

Projekt esetén használja mindkét beállítást:

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

Fájlalapú program esetén adja hozzá az ezzel egyenértékű irányelveket:

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

Az AllowUnsafeBlocks tulajdonság független. Meghatározza, hogy a forrás használhatja-e a kulcsszót unsafe . Egy projekt nem biztonságos kód engedélyezése nélkül engedélyezheti a frissített szabályokat, ebben az esetben hibaüzenetet kap, amikor nem biztonságos API-kat igényel.

Attól függ, hogy az egyik szerelvény kikényszeríti-e a frissített szabályokat egy másikkal szemben, attól függ, hogy melyik oldal dönti el:

  • Frissített modell hívója, frissített modell hívója: A hívó jelölői unsafe metaadatokon haladnak át. A hívó az egyes hívásokat egy blokk nem biztonságos tagjának unsafe csomagolja.
  • Frissített modell hívója, eredeti modell hívója: A kompatibilitási mód minden olyan hívó tagot kezel, akinek az aláírásában mutatótípus szerepel, nem biztonságos, ezért a híváswebhelynek elzárt unsafe blokkra van szüksége. Ez a mód megakadályozza, hogy a mutatóalapú API csendben elveszítse a követelményét unsafe .
  • Eredeti modell hívója, frissített modell hívója: Az eredeti mutatószabályok továbbra is érvényesek. Egy nem biztonságos tag, amelynek nincs mutatótípusa az aláírásában, biztonságos kódból hívhatóvá válik, mert az eredeti modell hívója nem tudja beolvasni az új jelölőket.

DefineConstants

A DefineConstants beállítás szimbólumokat határoz meg a program összes forráskódfájljában.

<DefineConstants>name;name2</DefineConstants>

Ez a beállítás egy vagy több definiálni kívánt szimbólum nevét adja meg. A DefineConstants beállításnak ugyanaz a hatása, mint a #define előfeldolgozási irányelvnek, azzal a kivételével, hogy a fordító beállítás a projekt összes fájlja esetében érvényben van. A szimbólumok a forrásfájlban maradnak definiálva, amíg a forrásfájlban lévő #undef direktíva el nem távolítja a definíciót. Ha ezt a -define lehetőséget választja, #undef az egyik fájlban lévő direktíva nincs hatással a projekt más forráskódfájljaira. Az ebben a beállításban létrehozott szimbólumokat #if, #else, #elif és #endif használhatja a forrásfájlok feltételes fordításához. Maga a C#-fordító nem definiál szimbólumokat vagy makrókat, amelyeket a forráskódban használhat; minden szimbólumdefiníciónak felhasználó által definiáltnak kell lennie.

Feljegyzés

A C# #define -direktíva nem teszi lehetővé, hogy a szimbólumok értékekkel rendelkezzenek, például a C++-ban. Nem lehet például makrót létrehozni vagy #define állandót definiálni. Ha konstanst szeretne definiálni, használjon egy változót enum . Ha C++-stílusú makrót szeretne létrehozni, fontolja meg az olyan alternatívákat, mint az általánosak. Mivel a makrók közismerten hibalehetőséget jelentenek, a C# letiltja a használatát, de biztonságosabb alternatívákat kínál.

LangVersion

A C# fordító alapértelmezett nyelvi verziója az alkalmazás cél keretrendszerétől és a telepített SDK vagy Visual Studio verziójától függ. Ezek a szabályok a C#-nyelv verziószámozásában vannak definiálva.

Figyelmeztetés

Ne állítsa be az elemet a LangVersion következőre latest: . A latest beállítás azt jelenti, hogy a telepített fordító a legújabb verzióját használja. Ez a verzió gépről gépre változhat, így a buildek megbízhatatlanok lesznek. Emellett olyan nyelvi funkciókat is lehetővé tesz, amelyekhez futtatókörnyezeti vagy tárfunkciók szükségesek, amelyek nem szerepelnek az aktuális SDK-ban.

A LangVersion beállítás hatására a fordító csak a megadott C# nyelvspecifikációban szereplő szintaxist fogadja el, például:

<LangVersion>9.0</LangVersion>

Egyes előzetes verziójú funkciókhoz amellett, hogy külön jóváhagyásra <LangVersion>preview</LangVersion>van szükség. A C# 15 frissített memóriabiztonsági szabályai például a updated-memory-safety-rules fordító funkciót használják. További információ: A frissített memóriabiztonsági szabályok engedélyezése.

A következő értékek érvényesek:

Érték Értelmezés
preview A fordító a legújabb előzetes verzió összes érvényes nyelvszintaxisát elfogadja.
latest A fordító elfogadja a fordító legújabb kiadású verziójának szintaxisát (beleértve az alverziót is).
latestMajor
vagy default		 A fordító elfogadja a fordító legújabb főverziójának szintaxisát.
15.0 A fordító csak a C# 15 vagy annál alacsonyabb szintaxist fogadja el.
14.0 A fordító csak a C# 14 vagy annál alacsonyabb változatokban található szintaxist fogadja el.
13.0 A fordító csak a C# 13 vagy annál alacsonyabb szintaxist fogadja el.
12.0 A fordító csak a C# 12 vagy annál alacsonyabb szintaxist fogadja el.
11.0 A fordító csak a C# 11 vagy annál alacsonyabb szintaxist fogadja el.
10.0 A fordító csak a C# 10 vagy annál alacsonyabb szintaxist fogadja el.
9.0 A fordító csak a C# 9 vagy annál alacsonyabb szintaxist fogadja el.
8.0 A fordító csak a C# 8.0 vagy annál alacsonyabb szintaxist fogadja el.
7.3 A fordító csak a C# 7.3 vagy annál alacsonyabb szintaxist fogadja el.
7.2 A fordító csak a C# 7.2-ben vagy annál alacsonyabb szintaxist fogadja el.
7.1 A fordító csak a C# 7.1 vagy annál alacsonyabb szintaxist fogadja el.
7 A fordító csak a C# 7.0-s vagy újabb verziójában szereplő szintaxist fogadja el.
6 A fordító csak a C# 6.0 vagy annál alacsonyabb szintaxist fogadja el.
5 A fordító csak a C# 5.0-s vagy újabb verziójában szereplő szintaxist fogadja el.
4 A fordító csak a C# 4.0-s vagy újabb verziójában szereplő szintaxist fogadja el.
3 A fordító csak a C# 3.0-s vagy újabb verziójában szereplő szintaxist fogadja el.
ISO-2
vagy 2		 A fordító csak az ISO/IEC 23270:2006 C# (2.0) szabványban foglalt szintaxist fogadja el.
ISO-1
vagy 1		 A fordító csak az ISO/IEC 23270:2003 C# (1.0/1.2) szabványban foglalt szintaxist fogadja el.

Megfontolások

  • Annak érdekében, hogy a projekt a cél-keretrendszerhez ajánlott alapértelmezett fordítóverziót használja, ne használja a LangVersion lehetőséget. Frissítse a cél keretrendszert az újabb nyelvi funkciók eléréséhez.

  • A LangVersion értékének default megadása eltér a LangVersion beállítás kihagyásától. A beállítás default a fordító által támogatott nyelv legújabb verzióját használja, a cél-keretrendszer figyelembe vétele nélkül. Ha például a Visual Studio 17.6-os verziójában a .NET 6-ot célozza meg, a C# 10-et használja, ha a LangVersion nincs megadva, de a C# 11-et használja, ha a LangVersion értéke default.

  • A LangVersion fordítóbeállítás nem befolyásolja a C#-alkalmazás által hivatkozott metaadatokat.

  • Mivel a C#-fordító minden verziója tartalmazza a nyelvi specifikációhoz tartozó bővítményeket, a LangVersion nem biztosítja a fordító egy korábbi verziójának megfelelő funkciókat.

  • Bár a C# verziófrissítései általában egybeesnek a fő .NET-kiadásokkal, az új szintaxis és funkciók nem feltétlenül kapcsolódnak az adott keretrendszerverzióhoz. Minden egyes funkció saját minimális .NET API-val vagy közös nyelvi futtatókörnyezeti követelményekkel rendelkezik, amelyek lehetővé teszik, hogy a NuGet-csomagokat vagy más kódtárakat is beleértve down-level keretrendszereken fusson.

  • Függetlenül attól, hogy melyik LangVersion beállítást használja, használja a közös nyelvi futtatókörnyezet aktuális verzióját a .exe vagy .dll létrehozásához. Az egyik kivétel a barátszerelvények és a ModuleAssemblyName, amelyek a -langversion:ISO-1 alatt működnek.

A C# nyelvi verziójának megadására vonatkozó egyéb módokért tekintse meg a C#-nyelv verziószámozását.

A fordítóprogram programozott beállításáról további információt a következő témakörben talál LanguageVersion: .

C# nyelvspecifikáció

Verzió Hivatkozás Leírás
C# 8.0 és újabb verziók PDF letöltése C# Language Specification Version 7: .NET Foundation
C# 7.3 PDF letöltése Standard ECMA-334 7. kiadás
C# 6.0 PDF letöltése Standard ECMA-334 6. kiadás
C# 5.0 PDF letöltése Standard ECMA-334 5. kiadás
C# 3.0 DOC letöltése C# Language Specification Version 3.0: Microsoft Corporation
C# 2.0 PDF letöltése Standard ECMA-334 4. kiadás
C# 1.2 DOC letöltése Standard ECMA-334 2. kiadás
C# 1.0 DOC letöltése Standard ECMA-334 1st Edition

Az összes nyelvi funkció támogatásához szükséges minimális SDK-verzió

Az alábbi táblázat az SDK minimális verzióit sorolja fel a megfelelő nyelvi verziót támogató C#-fordítóval:

C# verzió Az SDK minimális verziója
C# 12 Microsoft Visual Studio/Build Tools 2022 17.8-es vagy .NET 8 SDK-s verzió
C# 11 Microsoft Visual Studio/Build Tools 2022 17.4-es vagy .NET 7 SDK-s verzió
C# 10 Microsoft Visual Studio/Build Tools 2022 vagy .NET 6 SDK
C# 9.0 Microsoft Visual Studio/Build Tools 2019 16.8-es vagy .NET 5 SDK-s verzió
C# 8.0 Microsoft Visual Studio/Build Tools 2019, 16.3 vagy .NET Core 3.0 SDK
C# 7.3 Microsoft Visual Studio/Build Tools 2017, 15.7-es verzió
C# 7.2 Microsoft Visual Studio/Build Tools 2017, 15.5-ös verzió
C# 7.1 Microsoft Visual Studio/Build Tools 2017, 15.3-os verzió
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 vagy csomagolt .NET-keretrendszer 4.5-ös fordító
C# 4 Microsoft Visual Studio/Build Tools 2010 vagy csomagolt .NET-keretrendszer 4.0 fordító
C# 3 Microsoft Visual Studio/Build Tools 2008 vagy csomagolt .NET-keretrendszer 3.5-ös fordító
C# 2 Microsoft Visual Studio/Build Tools 2005 vagy csomagolt .NET-keretrendszer 2.0 fordító
C# 1.0/1.2 Microsoft Visual Studio/Build Tools .NET 2002 vagy csomagolt .NET-keretrendszer 1.0 fordító

Nullázható

A null értékű környezet megadásához használja a Nullable beállítást. Állítsa be a projekt konfigurációjába a <Nullable> következő címkével:

<Nullable>enable</Nullable>

Az argumentumnak az egyiknek enablekell lennie , disablewarningsvagy annotations. Az enable argumentum bekapcsolja a null értékű környezetet. Az disable argumentum kikapcsolja a null értékű környezetet. Az warnings argumentum bekapcsolja a null értékű figyelmeztető környezetet. Az annotations argumentum bekapcsolja a null értékű jegyzetkörnyezetet. További információ ezekről az értékekről: Null értékű környezetek. A null értékű hivatkozástípusok meglévő kódbázisban való engedélyezéséről további információt a null értékű migrálási stratégiákban talál.

Feljegyzés

Ha nem állít be értéket, az alapértelmezett érték az disable. A .NET 6-os és újabb sablonok azonban alapértelmezés szerint a Nullable értéket enable állítják be.

A folyamatelemzés a végrehajtható kódban lévő változók nullságát jelzi. A változók kikövetkezett nullabilitása független a változó deklarált nullképességétől. A fordító akkor is elemzi a metódushívásokat, ha a hívás feltételesen hiányzik a lefordított kimenetből. A fordító például továbbra is elemzi a null értékű hívásokat annak ellenére, hogy Debug.Assert a hívás feltételes, és nem kiadási buildekké van fordítva.

A következő attribútumokkal jegyzett metódusok meghívása a folyamatelemzésre is hatással van:

Fontos

A globális null értékű környezet nem vonatkozik a létrehozott kódfájlokra. Ettől a beállítástól függetlenül a null értékű környezet minden létrehozottként megjelölt forrásfájl esetében le van tiltva . A rendszer az alábbi módokon jelöli meg a fájlokat generáltként:

  1. A .editorconfig fájlban adja meg generated_code = true az adott fájlra vonatkozó szakaszt.
  2. A fájl tetején lévő megjegyzésbe belefoglalhatja <auto-generated> vagy <auto-generated/> megjegyzésbe foglalhatja. A megjegyzés bármely sorára elhelyezheti, de a megjegyzésblokknak kell lennie a fájl első elemének.
  3. Indítsa el a fájlnevet TemporaryGeneratedFile_
  4. Fejezze be a fájlnevet .designer.cs, .generated.cs, .g.cs vagy .g.i.cs.

A generátorok az előfeldolgozási #nullable irányelv használatával választhatnak.

  • Utolsó frissítés időpontja: