Параметры компилятора C# для правил функций языка

Следующие параметры определяют, как компилятор интерпретирует языковые функции. Новый синтаксис MSBuild выделен полужирным шрифтом. Для старого синтаксиса csc.exe используется формат code style.

• CheckForOverflowUnderflow / -checked: создание проверок на переполнение.
• AllowUnsafeBlocks / -unsafe: разрешить unsafe код.
• DefineConstants / -define: определение символов условной компиляции.
• LangVersion / -langversion: указание версии языка, например default (последняя основная версия) или latest (последняя версия, включая дополнительные версии).
• Nullable / -nullable: включение контекста, допускающего значение NULL, или предупреждений, допускающих значение NULL.

Примечание.

Дополнительные сведения о настройке этих параметров для проекта см. в разделе "Параметры компилятора".

CheckForOverflowUnderflow

Параметр CheckForOverflowUnderflow управляет контекстом проверки переполнения по умолчанию, определяющим поведение программы, если целочисленные арифметические переполнения.

<CheckForOverflowUnderflow>true</CheckForOverflowUnderflow>

При использовании CheckForOverflowUnderflowtrueконтекст по умолчанию является проверенным контекстом и включена проверка переполнения. Если установлен falseфлажок CheckForOverflowUnderflow, контекст по умолчанию — это неконтролируемый контекст. Значением по умолчанию для этого параметра является falseто, что проверка переполнения отключена.

Вы также можете явно контролировать контекст проверки переполнения для частей кода с помощью checked инструкций и unchecked инструкций.

Сведения о том, как контекст проверки переполнения влияет на операции и какие операции он влияет, см. в статье о checked и unchecked инструкциях.

AllowUnsafeBlocks

Параметр AllowUnsafeBlocks разрешает компилировать код, в котором используется ключевое слово unsafe. Значение по умолчанию для этого параметра означает false, что небезопасный код не разрешен.

<AllowUnsafeBlocks>true</AllowUnsafeBlocks>

Дополнительные сведения см. в разделе Небезопасный код и указатели.

Включение обновленных правил безопасности памяти

Обновленные правила безопасности памяти — это предварительная версия функции в C# 15 и .NET 11. Они используют два независимых параметра компилятора:

• Версия preview языка включает новый синтаксис и расслабление указателя.
• Функция updated-memory-safety-rules компилятора позволяет обновленным правилам, включая небезопасные обязательства вызывающего абонента, и заставляет компилятор записать выбор в сборке с помощью атрибута MemorySafetyRulesAttribute .

Будущее стабильное свойство MemorySafetyRulesSDK планируется в качестве третьего уровня активации, если функция выходит из предварительной версии (например, <MemorySafetyRules>2</MemorySafetyRules>), но это свойство еще не реализовано.

Для проекта используйте оба параметра:

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

Для файловой программы добавьте эквивалентные директивы:

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

Свойство AllowUnsafeBlocks является независимым. Он определяет, может ли источник использовать ключевое unsafe слово. Проект может включить обновленные правила, не разрешая небезопасный код, в этом случае он получает ошибки при вызове небезопасных API.

Если одна сборка применяет обновленные правила к другой, зависит от того, какая сторона выбирает:

• Обновленный вызывающий объект модели, обновленный вызывающий объект модели: маркеры вызываемого абонента unsafe перемещают метаданные. Вызывающий объект упаковывает каждый вызов к небезопасным членам в блоке unsafe .
• Обновленный вызывающий объект модели, вызываемый исходной моделью: режим совместимости обрабатывает любой член вызываемого объекта с типом указателя в подписи, так как требует небезопасности, поэтому сайт вызова нуждается в заключительный unsafe блок. Этот режим позволяет api на основе указателя автоматически потерять свое unsafe требование.
• Вызывающий объект исходной модели, обновленный вызывающий объект модели: исходные правила указателя по-прежнему применяются. Небезопасный член, не имеющий типа указателя в подписи, становится вызываемым из безопасного кода, так как вызывающий объект исходной модели не может считывать новые маркеры.

DefineConstants

Параметр DefineConstants определяет символы в файлах исходного кода вашей программы.

<DefineConstants>name;name2</DefineConstants>

Этот параметр задает имена одного или нескольких символов, которые необходимо определить. Параметр DefineConstants действует так же, как директива препроцессора #define, но применяется ко всем файлам проекта. Символ остается определенным в файле исходного кода до тех пор, пока определение не будет отменено с помощью директивы #undef в файле исходного кода. При использовании параметра -define директива #undef в одном файле не действует для других файлов исходного кода в проекте. Вы можете использовать символы, созданные этим параметром, с директивами #if, #else, #elif и #endif для условной компиляции исходных файлов. Компилятор C# сам по себе не определяет символы и макросы, которые можно использовать в исходном коде. Все такие определения задаются пользователем.

Примечание.

Директива C# #define не позволяет символу иметь значение, например на языках, таких как C++. Например, #define не удается создать макрос или определить константу. Чтобы определить константу, используйте переменную enum. Если вы хотите создать макрос в стиле C++, рассмотрите варианты, такие как универсальные. Поскольку макросы по своей природе подвержены ошибкам, в C# они запрещены, однако вместо них предлагаются более безопасные альтернативы.

LangVersion

Версия языка по умолчанию для компилятора C# зависит от целевой платформы для приложения и установленной версии пакета SDK или Visual Studio. Такие правила определены в статье Управление версиями языка C#.

Предупреждение

Не устанавливайте LangVersion для элемента latestзначение . Параметр означает, latest что установленный компилятор использует последнюю версию. Эта версия может измениться с компьютера на компьютер, что делает сборки ненадежными. Кроме того, он включает функции языка, которые могут требовать функции среды выполнения или библиотеки, которые не включены в текущий пакет SDK.

Параметр LangVersion приводит к тому, что компилятор принимает только синтаксис, включенный в указанную спецификацию языка C#, например:

<LangVersion>9.0</LangVersion>

Для некоторых функций предварительной версии требуется отдельное согласие в дополнение <LangVersion>preview</LangVersion>к . Например, обновленные правила безопасности памяти C# 15 используют функцию компилятора updated-memory-safety-rules . Дополнительные сведения см. в разделе "Включить обновленные правила безопасности памяти".

Допустимы следующие значения:

Значение	Значение
preview	Компилятор допускает использование любого допустимого синтаксиса языка из последней предварительной версии.
latest	Компилятор принимает синтаксис из последней выпущенной версии компилятора (включая дополнительный номер версии).
latestMajor или default	Компилятор принимает синтаксис из последней основной версии компилятора.
15.0	Компилятор принимает только синтаксис, включенный в C# 15 или более поздней версии.
14.0	Компилятор принимает только синтаксис, включенный в C# 14 или более поздней версии.
13.0	Компилятор принимает только синтаксис, включенный в C# 13 или более поздней версии.
12.0	Компилятор принимает только синтаксис, включенный в C# 12 или ниже.
11.0	Компилятор принимает только синтаксис, включенный в C# 11 или ниже.
10.0	Компилятор принимает только синтаксис, включенный в спецификацию C# 10 или более ранних версий.
9.0	Компилятор принимает только синтаксис, включенный в спецификацию C# 9 или более ранних версий.
8.0	Компилятор принимает только синтаксис, включенный в спецификацию C# 8.0 или более ранней версии.
7.3	Компилятор принимает только синтаксис, включенный в спецификацию C# 7.3 или более ранней версии.
7.2	Компилятор принимает только синтаксис, включенный в спецификацию C# 7.2 или более ранней версии.
7.1	Компилятор принимает только синтаксис, включенный в спецификацию C# 7.1 или более ранней версии.
7	Компилятор принимает только синтаксис, включенный в спецификацию C# 7.0 или более ранней версии.
6	Компилятор принимает только синтаксис, включенный в спецификацию C# 6.0 или более ранней версии.
5	Компилятор принимает только синтаксис, включенный в спецификацию C# 5.0 или более ранней версии.
4	Компилятор принимает только синтаксис, включенный в спецификацию C# 4.0 или более ранней версии.
3	Компилятор принимает только синтаксис, включенный в спецификацию C# 3.0 или более ранней версии.
ISO-2 или 2	Компилятор принимает только синтаксис, включенный в спецификацию ISO/IEC 23270:2006 C# (2.0).
ISO-1 или 1	Компилятор принимает только синтаксис, включенный в спецификацию ISO/IEC 23270:2003 C# (1.0/1.2).

Рекомендации

• Чтобы убедиться, что проект использует версию компилятора по умолчанию, рекомендуемую для целевой платформы, не используйте параметр LangVersion . Обновите целевую платформу, чтобы получить доступ к новым функциям языка.

• Указание LangVersion со значением отличается от пропуска параметра LangVersion.default Указание default последней версии языка, который поддерживает компилятор, без учета целевой платформы. Например, создание проекта, предназначенного для .NET 6 из Visual Studio версии 17.6, использует C# 10, если LangVersion не указан, но использует C# 11, если LangVersion

• Параметр компилятора LangVersion не влияет на метаданные, на которые ссылается приложение C#.

• Так как каждая версия компилятора C# содержит расширения для спецификации языка, параметр LangVersion не позволяет использовать возможности, аналогичные возможностям более ранней версии компилятора.

• Хотя обновления версий C# обычно совпадают с основными выпусками .NET, новые синтаксис и функции не обязательно привязаны к этой конкретной версии платформы. Каждая конкретная функция имеет собственные минимальные .NET API или требования среды CLR, которые могут позволить ему работать на платформах нижнего уровня, включая пакеты NuGet или другие библиотеки.

• Независимо от того, какой параметр LangVersion используется, используйте текущую версию среды CLR для создания .exe или .dll. Единственным исключением являются дружественные сборки и ModuleAssemblyName, которые работают при установке параметра -langversion:ISO-1.

Другие способы указания версии языка C# см. в статье Управление версиями языка C#.

Дополнительные сведения об установке этого параметра компилятора программным путем см. в разделе LanguageVersion.

Спецификация языка C#

Версия	Ссылка	Description
C# 8.0 и более поздних версий	скачивание PDF	Спецификация языка C# версии 7: .NET Foundation
C# 7.3	скачивание PDF	Стандартный выпуск ECMA-334 7-го выпуска
C# 6.0	скачивание PDF	Стандартный выпуск ECMA-334 6-го выпуска
C# 5.0	Скачать в формате PDF	Стандарт ECMA-334, 5-й выпуск
C# 3.0	Загрузить DOC-файл	Спецификация языка C# версии 3.0: корпорация Майкрософт
C# 2.0	Скачать в формате PDF	Стандарт ECMA-334, 4-й выпуск
C# 1.2	Загрузить DOC-файл	Стандартный выпуск ECMA-334 2nd
C# 1.0	Загрузить DOC-файл	Стандартный выпуск ECMA-334 1st

Минимальная версия пакета SDK, необходимая для поддержки всех возможностей языка

В следующей таблице перечислены минимальные версии пакета SDK с компилятором C#, поддерживающим соответствующую версию языка:

Версия C#	Минимальная версия пакета SDK
C# 12	Microsoft Visual Studio/Build Tools 2022 версии 17.8 или пакет SDK для .NET 8
C# 11	Microsoft Visual Studio/Build Tools 2022 версии 17.4 или пакет SDK для .NET 7
C# 10	Microsoft Visual Studio/Build Tools 2022 или пакет SDK для .NET 6
C# 9.0	Microsoft Visual Studio/Build Tools 2019 версии 16.8 или пакет SDK для .NET 5
C# 8.0	Microsoft Visual Studio/Build Tools 2019, версия 16.3 или пакет SDK .NET Core 3.0
C# 7.3	Microsoft Visual Studio/Build Tools 2017, версия 15.7
C# 7.2	Microsoft Visual Studio/Build Tools 2017, версия 15.5
C# 7.1	Microsoft Visual Studio/Build Tools 2017, версия 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 или встроенный компилятор .NET Framework 4.5
C# 4	Microsoft Visual Studio/Build Tools 2010 или встроенный компилятор .NET Framework 4.0
C# 3	Microsoft Visual Studio/Build Tools 2008 или встроенный компилятор .NET Framework 3.5
C# 2	Microsoft Visual Studio/Build Tools 2005 или встроенный компилятор .NET Framework 2.0
C# 1.0/1.2	Microsoft Visual Studio/Build Tools .NET 2002 или встроенный компилятор .NET Framework 1.0

Допускает значение NULL

Используйте параметр NULL, чтобы указать контекст, допускающий значение NULL. Задайте его в конфигурации проекта с помощью тега <Nullable> :

<Nullable>enable</Nullable>

Аргумент должен иметь одно из следующих значений: enable, disable, warnings или annotations. Аргумент enable включает контекст, допускающий значение NULL. Аргумент disable отключает контекст, допускающий значение NULL. Аргумент warnings включает контекст предупреждения, допускающего значение NULL. Аргумент annotations включает контекст заметки, допускающий значение NULL. Дополнительные сведения об этих значениях см. в контекстах, допускающих значение NULL. Дополнительные сведения о включении ссылочных типов, допускающих значение NULL, в существующей базе кода см. в стратегиях миграции, допускающих значение NULL.

Примечание.

Если значение не задано, значение по умолчанию равно disable. Однако .NET 6 и более новых шаблонов задайте значение NULL по enable умолчанию.

Анализ потока определяет допустимость значений NULL переменных в исполняемом коде. Выводимая допустимость переменной значения NULL не зависит от объявленной в переменной допустимости значения NULL. Компилятор анализирует вызовы метода, даже если вызов условно опущен из скомпилированных выходных данных. Например, компилятор по-прежнему анализирует вызов Debug.Assert nullability, даже если вызов является условным и не компилируется в сборки выпуска.

Вызов методов, аннотированных со следующими атрибутами, также влияет на анализ потока:

• Простые предварительные условия: AllowNullAttribute и DisallowNullAttribute
• Простые посткондиции: MaybeNullAttribute и NotNullAttribute
• Условные посткондиции: MaybeNullWhenAttributeNotNullWhenAttribute
• DoesNotReturnIfAttribute (например, DoesNotReturnIf(false) для Debug.Assert) и DoesNotReturnAttribute
• NotNullIfNotNullAttribute
• Элементы postconditions: MemberNotNullAttribute(String) и MemberNotNullAttribute(String[])

Внимание

Глобальный контекст, допускающий значение NULL, не применяется к созданным файлам кода. Независимо от этого параметра, контекст, допускающий значение NULL, отключен для любого исходного файла, помеченного как созданный. Файл помечается как созданный одним из следующих способов:

1. В файле. editorconfig укажите generated_code = true в разделе, который применяется к этому файлу.
2. Включите <auto-generated> или <auto-generated/> в комментарий в верхней части файла. Его можно разместить в любой строке комментария, но блок комментариев должен быть первым элементом в файле.
3. Имя файла следует начинать с TemporaryGeneratedFile_
4. В конце имени файла следует указать .designer.cs, .generated.cs, .g.cs или .g.i.cs.

Генераторы могут принять участие с помощью #nullable директивы препроцессора.