Opcje kompilatora języka C# dla reguł funkcji języka

  • Artykuł

Poniższe opcje określają, jak kompilator interpretuje funkcje języka. Nowa składnia programu MSBuild jest wyświetlana w obszarze Pogrubienie. Starsza składnia csc.exe jest wyświetlana w pliku code style.

  • CheckForOverflowUnderflow / -checked: generowanie kontroli przepełnienia.
  • AllowUnsafeBlocks / -unsafe: zezwalaj na kod "niebezpieczny".
  • DefineConstants / -define: Definiowanie symboli kompilacji warunkowej.
  • LangVersion / -langversion: określ wersję języka, taką jak default (najnowsza wersja główna) lub latest (najnowsza wersja, w tym wersje pomocnicze).
  • Dopuszczające wartość null: włącz kontekst dopuszczający / -nullable wartość null lub ostrzeżenia dopuszczające wartość null.

CheckForOverflowUnderflow

Opcja CheckForOverflowUnderflow steruje domyślnym kontekstem sprawdzania przepełnienia, który definiuje zachowanie programu, jeśli przepełnienie arytmetyczne liczby całkowitej.

<CheckForOverflowUnderflow>true</CheckForOverflowUnderflow>

Gdy właściwość CheckForOverflowUnderflow to true, domyślny kontekst jest kontekstem sprawdzanym, a sprawdzanie przepełnienia jest włączone. W przeciwnym razie kontekst domyślny jest kontekstem niezaznakowanym. Wartość domyślna dla tej opcji to false, czyli sprawdzanie przepełnienia jest wyłączone.

Możesz również jawnie kontrolować kontekst sprawdzania przepełnienia dla części kodu przy użyciu instrukcji checked and unchecked .

Aby uzyskać informacje o tym, jak kontekst sprawdzania przepełnienia wpływa na operacje i jakie operacje mają wpływ, zobacz artykuł na temat checked instrukcji i unchecked .

AllowUnsafeBlocks

Opcja kompilatora AllowUnsafeBlocks umożliwia kompilowanie kodu używającego niebezpiecznego słowa kluczowego. Wartość domyślna dla tej opcji to false, co oznacza, że niebezpieczny kod nie jest dozwolony.

<AllowUnsafeBlocks>true</AllowUnsafeBlocks>

Aby uzyskać więcej informacji na temat niebezpiecznego kodu, zobacz Niebezpieczny kod i wskaźniki.

DefineConstants

Opcja DefineConstants definiuje symbole we wszystkich plikach kodu źródłowego programu.

<DefineConstants>name;name2</DefineConstants>

Ta opcja określa nazwy co najmniej jednego symbolu, który chcesz zdefiniować. Opcja DefineConstants ma taki sam efekt jak dyrektywa preprocesora #define , z tą różnicą, że opcja kompilatora jest w mocy dla wszystkich plików w projekcie. Symbol pozostaje zdefiniowany w pliku źródłowym do momentu usunięcia definicji przez dyrektywę #undef w pliku źródłowym. Jeśli używasz -define opcji, #undef dyrektywa w jednym pliku nie ma wpływu na inne pliki kodu źródłowego w projekcie. Symbole utworzone przez tę opcję można używać z #if, #else, #elif i #endif do warunkowego kompilowania plików źródłowych. Sam kompilator języka C# nie definiuje żadnych symboli ani makr, których można użyć w kodzie źródłowym; wszystkie definicje symboli muszą być zdefiniowane przez użytkownika.

Uwaga

Dyrektywa języka C# #define nie zezwala na nadane wartości symbolu, tak jak w językach takich jak C++. Na przykład #define nie można użyć do utworzenia makra lub zdefiniowania stałej. Jeśli musisz zdefiniować stałą, użyj zmiennej enum . Jeśli chcesz utworzyć makro stylu języka C++, rozważ alternatywy, takie jak typy ogólne. Ponieważ makra są notorycznie podatne na błędy, język C# nie zezwala na ich użycie, ale zapewnia bezpieczniejsze alternatywy.

LangVersion

Domyślna wersja języka kompilatora języka C# zależy od platformy docelowej aplikacji i zainstalowanej wersji zestawu SDK lub programu Visual Studio. Te reguły są definiowane w wersji języka C#.

Opcja LangVersion powoduje, że kompilator akceptuje tylko składnię uwzględniną w określonej specyfikacji języka C#, na przykład:

<LangVersion>9.0</LangVersion>

Następujące wartości są prawidłowe:

Wartość Znaczenie
preview Kompilator akceptuje całą prawidłową składnię języka z najnowszej wersji zapoznawczej.
latest Kompilator akceptuje składnię z najnowszej wydanej wersji kompilatora (w tym wersji pomocniczej).
latestMajor
lub default		 Kompilator akceptuje składnię z najnowszej wydanej wersji głównej kompilatora.
12.0 Kompilator akceptuje tylko składnię zawartą w języku C# 12 lub niższym.
11.0 Kompilator akceptuje tylko składnię zawartą w języku C# 11 lub niższym.
10.0 Kompilator akceptuje tylko składnię zawartą w języku C# 10 lub niższym.
9.0 Kompilator akceptuje tylko składnię zawartą w języku C# 9 lub niższym.
8.0 Kompilator akceptuje tylko składnię zawartą w języku C# 8.0 lub niższym.
7.3 Kompilator akceptuje tylko składnię zawartą w języku C# 7.3 lub niższym.
7.2 Kompilator akceptuje tylko składnię zawartą w języku C# 7.2 lub niższym.
7.1 Kompilator akceptuje tylko składnię zawartą w języku C# 7.1 lub niższym.
7 Kompilator akceptuje tylko składnię zawartą w języku C# 7.0 lub niższym.
6 Kompilator akceptuje tylko składnię zawartą w języku C# 6.0 lub niższym.
5 Kompilator akceptuje tylko składnię zawartą w języku C# 5.0 lub niższym.
4 Kompilator akceptuje tylko składnię zawartą w języku C# 4.0 lub niższym.
3 Kompilator akceptuje tylko składnię zawartą w języku C# 3.0 lub niższym.
ISO-2
lub 2		 Kompilator akceptuje tylko składnię zawartą w iso/IEC 23270:2006 C# (2.0).
ISO-1
lub 1		 Kompilator akceptuje tylko składnię zawartą w iso/IEC 23270:2003 C# (1.0/1.2).

Ważne

Wartość jest zwykle nie zalecana latest . W programie latestkompilator włącza najnowsze funkcje, nawet jeśli te funkcje zależą od aktualizacji nieuwzględnianych w skonfigurowanej strukturze docelowej.

Kwestie wymagające rozważenia

  • Aby upewnić się, że projekt używa domyślnej wersji kompilatora zalecanej dla platformy docelowej, nie używaj opcji LangVersion . Możesz zaktualizować platformę docelową, aby uzyskać dostęp do nowszych funkcji językowych.

  • Określanie elementu LangVersion z wartością default różni się od pominięcia opcji LangVersion . Określenie default używa najnowszej wersji języka obsługiwanego przez kompilator bez uwzględniania platformy docelowej. Na przykład kompilowanie projektu przeznaczonego dla platformy .NET 6 z programu Visual Studio w wersji 17.6 używa języka C# 10, jeśli parametr LangVersion nie został określony, ale używa języka C# 11, jeśli parametr LangVersion ma wartość default.

  • Metadane, do których odwołuje się aplikacja języka C#, nie podlegają opcji kompilatora LangVersion .

  • Ponieważ każda wersja kompilatora języka C# zawiera rozszerzenia specyfikacji języka, LangVersion nie zapewnia równoważnych funkcji starszej wersji kompilatora.

  • Chociaż aktualizacje wersji języka C# zwykle pokrywają się z głównymi wersjami platformy .NET, nowa składnia i funkcje nie muszą być powiązane z daną wersją platformy. Każda konkretna funkcja ma własne minimalne wymagania dotyczące interfejsu API platformy .NET lub środowiska uruchomieniowego języka wspólnego, które mogą pozwolić na uruchamianie ich na platformach w dół przez uwzględnienie pakietów NuGet lub innych bibliotek.

  • Niezależnie od używanego ustawienia LangVersion użyj bieżącej wersji środowiska uruchomieniowego języka wspólnego, aby utworzyć .exe lub .dll. Jednym z wyjątków są przyjazne zestawy i ModuleAssemblyName, które działają w obszarze -langversion:ISO-1.

Aby uzyskać inne sposoby określania wersji języka C#, zobacz Przechowywanie wersji języka C#.

Aby uzyskać informacje na temat programowego ustawiania tej opcji kompilatora, zobacz LanguageVersion.

specyfikacja języka C#

Wersja Link opis
C# 8.0 i nowsze pobierz plik PDF Specyfikacja języka C# w wersji 7: .NET Foundation
C# 7.3 pobierz plik PDF Standardowa ECMA-334 7 edycja
C# 6.0 pobierz plik PDF Standardowa ECMA-334 6 edycja
C# 5.0 Pobierz plik PDF Standardowa ECMA-334 5 edycja
C# 3.0 Pobierz dokument Specyfikacja języka C# w wersji 3.0: Microsoft Corporation
C# 2.0 Pobierz plik PDF Standardowa ECMA-334 4 wydanie
C# 1.2 Pobierz dokument Standardowa ECMA-334 2 wydanie
C# 1.0 Pobierz dokument Standardowa ECMA-334 1. wydanie

Minimalna wersja zestawu SDK wymagana do obsługi wszystkich funkcji językowych

W poniższej tabeli wymieniono minimalne wersje zestawu SDK z kompilatorem języka C#, który obsługuje odpowiednią wersję języka:

Wersja języka C# Minimalna wersja zestawu SDK
C# 12 Microsoft Visual Studio/Build Tools 2022 w wersji 17.8 lub .NET 8 SDK
C# 11 Microsoft Visual Studio/Build Tools 2022 w wersji 17.4 lub .NET 7 SDK
C# 10 Microsoft Visual Studio/Build Tools 2022 lub .NET 6 SDK
C# 9.0 Microsoft Visual Studio/Build Tools 2019 w wersji 16.8 lub .NET 5 SDK
C# 8.0 Microsoft Visual Studio/Build Tools 2019, wersja 16.3 lub zestaw .NET Core 3.0 SDK
C# 7.3 Microsoft Visual Studio/Build Tools 2017, wersja 15.7
C# 7.2 Microsoft Visual Studio/Build Tools 2017, wersja 15.5
C# 7.1 Microsoft Visual Studio/Build Tools 2017, wersja 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 lub kompilator programu .NET Framework 4.5
C# 4 Kompilator programu Microsoft Visual Studio/Build Tools 2010 lub kompilator programu .NET Framework 4.0
C# 3 Microsoft Visual Studio/Build Tools 2008 lub kompilator programu .NET Framework 3.5
C# 2 Microsoft Visual Studio/Build Tools 2005 lub kompilator programu .NET Framework 2.0
C# 1.0/1.2 Microsoft Visual Studio/Build Tools .NET 2002 lub kompilator programu .NET Framework 1.0

Dopuszczający wartość null

Opcja Dopuszczana do wartości null umożliwia określenie kontekstu dopuszczanego do wartości null. Można go ustawić w konfiguracji projektu przy użyciu tagu <Nullable> :

<Nullable>enable</Nullable>

Argument musi być jednym z enable, disable, warningslub annotations. enable Argument umożliwia kontekst dopuszczany do wartości null. Określenie disable spowoduje wyłączenie kontekstu dopuszczającego wartość null. Po określeniu argumentu warnings jest włączony kontekst ostrzeżenia dopuszczający wartość null. Po określeniu argumentu annotations jest włączony kontekst adnotacji z możliwością wartości null. Wartości zostały opisane i wyjaśnione w artykule dotyczącym kontekstów dopuszczanych do wartości null. Więcej informacji na temat zadań związanych z włączaniem typów odwołań dopuszczających wartość null w istniejącej bazie kodu można dowiedzieć się w naszym artykule na temat strategii migracji dopuszczających wartości null.

Uwaga

Jeśli nie ma ustawionej wartości, zostanie zastosowana wartość disable domyślna, jednak szablony platformy .NET 6 są domyślnie dostarczane z wartością null ustawioną na enablewartość .

Analiza przepływu służy do wnioskowania o wartości null zmiennych w kodzie wykonywalny. Wnioskowana wartość null zmiennej jest niezależna od zadeklarowanej wartości null zmiennej. Wywołania metod są analizowane nawet wtedy, gdy zostaną pominięte warunkowo. Na przykład Debug.Assert w trybie wydania.

Wywołanie metod z adnotacjami z następującymi atrybutami będzie również miało wpływ na analizę przepływu:

Ważne

Globalny kontekst dopuszczania wartości null nie ma zastosowania do wygenerowanych plików kodu. Niezależnie od tego ustawienia kontekst dopuszczalny do wartości null jest wyłączony dla dowolnego pliku źródłowego oznaczonego jako wygenerowany. Istnieją cztery sposoby oznaczania pliku jako wygenerowanego:

  1. W pliku .editorconfig określ generated_code = true w sekcji, która ma zastosowanie do tego pliku.
  2. Umieść <auto-generated> lub <auto-generated/> w komentarzu w górnej części pliku. Może on znajdować się w dowolnym wierszu w tym komentarzu, ale blok komentarza musi być pierwszym elementem w pliku.
  3. Uruchom nazwę pliku przy użyciu TemporaryGeneratedFile_
  4. Zakończ nazwę pliku .designer.cs, .generated.cs, .g.cs lub .g.i.cs.

Generatory mogą korzystać z #nullable dyrektywy preprocesora.