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

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 unsafe kod.
• DefineConstants / -define: Zdefiniuj symbole 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.

Uwaga

Aby uzyskać więcej informacji na temat konfigurowania tych opcji dla projektu, zobacz Opcje kompilatora.

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 parametr CheckForOverflowUnderflow to true, domyślny kontekst to zaznaczony kontekst, a sprawdzanie przepełnienia jest włączone. Gdy właściwość CheckForOverflowUnderflow to false, domyślny kontekst jest nieznakowanym kontekstem. Wartość domyślna dla tej opcji to false, co oznacza, że 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 i unchecked .

Aby uzyskać informacje o tym, jak kontekst sprawdzania przepełnienia wpływa na operacje i jakie operacje ma to 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.

Włączanie zaktualizowanych reguł bezpieczeństwa pamięci

Zaktualizowane reguły bezpieczeństwa pamięci to funkcja w wersji zapoznawczej w języku C# 15 i .NET 11. Używają dwóch niezależnych ustawień kompilatora:

• Wersja preview języka umożliwia złagodzenie nowej składni i wskaźnika.
• Funkcja updated-memory-safety-rules kompilatora umożliwia zaktualizowane reguły, w tym wymagania dotyczące niebezpiecznych zobowiązań wywołujących i powoduje, że kompilator rejestruje wybór w zestawie za pomocą atrybutu MemorySafetyRulesAttribute .

Przyszła stabilna właściwość zestawu SDK, MemorySafetyRules, jest planowana jako trzecia warstwa aktywacji, gdy funkcja kończy pracę w wersji zapoznawczej (na przykład <MemorySafetyRules>2</MemorySafetyRules>), ale ta właściwość nie została jeszcze zaimplementowana.

W przypadku projektu użyj obu ustawień:

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

W przypadku programu opartego na plikach dodaj dyrektywy równoważne:

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

Właściwość AllowUnsafeBlocks jest niezależna. Określa, czy źródło może używać słowa kluczowego unsafe . Projekt może włączyć zaktualizowane reguły bez zezwalania na niebezpieczny kod, w którym przypadku otrzymuje błędy, gdy wywołuje interfejsy API wymagające niebezpiecznego.

To, czy jeden zestaw wymusza zaktualizowane reguły względem innego, zależy od tego, która strona wyrazi zgodę:

• Obiekt wywołujący zaktualizowany model, obiekt wywoływany przez zaktualizowany model: znaczniki wywoływanego unsafe przechodzą przez metadane. Obiekt wywołujący opakowuje każde wywołanie elementu członkowskiego wymagającego niebezpiecznego unsafe w bloku.
• Obiekt wywołujący zaktualizowany model, wywoływany w oryginalnym modelu: tryb zgodności traktuje dowolny element członkowski wywoływany z typem wskaźnika w podpisie, ponieważ wymaga niebezpieczne, więc lokacja wywołania wymaga otaczającego unsafe bloku. Ten tryb utrzymuje interfejs API oparty na wskaźniku z dyskretnego utraty wymagań unsafe .
• Obiekt wywołujący oryginalny model, wywoływany przez zaktualizowany model: oryginalne reguły wskaźnika nadal mają zastosowanie. Element członkowski wymagający, który nie ma typu wskaźnika w podpisie, staje się wywoływany z bezpiecznego kodu, ponieważ obiekt wywołujący oryginalny model nie może odczytać nowych znaczników.

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 symbolowi na posiadanie wartości, tak jak w językach takich jak C++. Na przykład #define nie można utworzyć makra ani zdefiniować stałej. Jeśli musisz zdefiniować stałą, użyj zmiennej enum . Jeśli chcesz utworzyć makro w stylu 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#.

Ostrzeżenie

Nie ustawiaj LangVersion elementu na latest. Ustawienie latest oznacza, że zainstalowany kompilator używa najnowszej wersji. Ta wersja może ulec zmianie z komputera na maszynę, co sprawia, że kompilacje są zawodne. Ponadto włącza funkcje językowe, które mogą wymagać funkcji środowiska uruchomieniowego lub biblioteki, które nie są uwzględnione w bieżącym zestawie SDK.

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>

Niektóre funkcje w wersji zapoznawczej wymagają oddzielnego wyrażenia zgody oprócz <LangVersion>preview</LangVersion>funkcji . Na przykład zaktualizowane reguły bezpieczeństwa pamięci w języku C# 15 używają funkcji kompilatora updated-memory-safety-rules . Aby uzyskać więcej informacji, zobacz Włączanie zaktualizowanych reguł bezpieczeństwa pamięci.

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.
15.0	Kompilator akceptuje tylko składnię zawartą w języku C# 15 lub niższym.
14.0	Kompilator akceptuje tylko składnię zawartą w języku C# 14 lub niższym.
13.0	Kompilator akceptuje tylko składnię zawartą w języku C# 13 lub niższym.
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).

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 . Zaktualizuj 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.

• Opcja kompilatora LangVersion nie ma wpływu na metadane, do których odwołuje się aplikacja języka C#.

• 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 interfejsu API .NET lub środowiska uruchomieniowego języka wspólnego, które mogą umożliwić uruchamianie ich na platformach na poziomie podrzędnym przez dołączenie 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

Użyj opcji Dopuszczaj wartość null , aby określić kontekst dopuszczalny do wartości null. Ustaw ją w konfiguracji projektu przy użyciu tagu <Nullable> :

<Nullable>enable</Nullable>

Argument musi być jednym z enable, disable, warningslub annotations. Argument enable włącza kontekst dopuszczany do wartości null. Argument disable wyłącza kontekst dopuszczany do wartości null. Argument warnings włącza kontekst ostrzeżenia dopuszczający wartość null. Argument annotations włącza kontekst adnotacji dopuszczania wartości null. Aby uzyskać więcej informacji na temat tych wartości, zobacz Konteksty dopuszczane do wartości null. Aby dowiedzieć się więcej na temat włączania typów referencyjnych dopuszczających wartości null w istniejącej bazie kodu, zobacz Strategie migracji dopuszczające wartość null.

Uwaga

Jeśli nie ustawisz wartości, wartość domyślna to disable. Jednak .NET 6 i nowszych szablonów ustawić wartość null na enable wartość domyślną.

Analiza przepływu umożliwia wnioskowanie o wartości null zmiennych w kodzie wykonywalny. Wnioskowana wartość null zmiennej jest niezależna od zadeklarowanej wartości null zmiennej. Kompilator analizuje wywołania metody nawet wtedy, gdy wywołanie zostanie warunkowo pominięte z skompilowanych danych wyjściowych. Na przykład kompilator nadal analizuje wywołanie Debug.Assert funkcji null, mimo że wywołanie jest warunkowe i nie jest kompilowane w kompilacjach wydania.

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

• Proste warunki wstępne: AllowNullAttribute i DisallowNullAttribute
• Proste postconditions: MaybeNullAttribute i NotNullAttribute
• Warunkowe wersje końcowe: MaybeNullWhenAttribute i NotNullWhenAttribute
• DoesNotReturnIfAttribute (na przykład DoesNotReturnIf(false) dla Debug.Assert) i DoesNotReturnAttribute
• NotNullIfNotNullAttribute
• Postconditions składowych: MemberNotNullAttribute(String) i MemberNotNullAttribute(String[])

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. Plik jest oznaczony jako wygenerowany w jeden z następujących sposobów:

1. W pliku .editorconfig określ generated_code = true w sekcji, która ma zastosowanie do tego pliku.
2. Dołącz <auto-generated> lub <auto-generated/> w komentarzu w górnej części pliku. Można umieścić go w dowolnym wierszu w 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ą wyrazić zgodę przy użyciu #nullable dyrektywy preprocesora.