Параметры компилятора C# для правил языковых функций
Следующие параметры определяют, как компилятор интерпретирует языковые функции. Новый синтаксис MSBuild выделен полужирным шрифтом. Для старого синтаксиса csc.exe используется формат code style.
- CheckForOverflowUnderflow /
-checked: создание проверок на переполнение. - AllowUnsafeBlocks /
-unsafe: разрешение использовать небезопасный код. - DefineConstants /
-define: определение символов условной компиляции. - LangVersion /
-langversion: указание версии языка, напримерdefault(последняя основная версия) илиlatest(последняя версия, включая дополнительные версии). - Nullable /
-nullable: включение контекста, допускающего значение NULL, или предупреждений, допускающих значение NULL.
Примечание.
Дополнительные сведения о настройке этих параметров для проекта см. в параметрах компилятора.
CheckForOverflowUnderflow
Параметр CheckForOverflowUnderflow управляет контекстом проверки переполнения по умолчанию, определяющим поведение программы, если целочисленные арифметические переполнения.
<CheckForOverflowUnderflow>true</CheckForOverflowUnderflow>
Если установлен флажок CheckForOverflowUnderflowtrue, контекст по умолчанию является проверенным контекстом и включена проверка переполнения. В противном случае контекст по умолчанию является неконтролируемым контекстом. Значением по умолчанию для этого параметра является falseто, что проверка переполнения отключена.
Вы также можете явно контролировать контекст проверки переполнения для частей кода с помощью checked инструкций и unchecked инструкций.
Сведения о том, как контекст проверки переполнения влияет на операции и какие операции затронуты, см. в статье о checked и unchecked инструкциях.
AllowUnsafeBlocks
Параметр AllowUnsafeBlocks разрешает компилировать код, в котором используется ключевое слово unsafe. Значение по умолчанию для этого параметра означает false, что небезопасный код не разрешен.
<AllowUnsafeBlocks>true</AllowUnsafeBlocks>
Дополнительные сведения см. в разделе Небезопасный код и указатели.
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>
Допустимы следующие значения:
| Значение | Значение |
|---|---|
preview |
Компилятор допускает использование любого допустимого синтаксиса языка из последней предварительной версии. |
latest |
Компилятор принимает синтаксис из последней выпущенной версии компилятора (включая дополнительный номер версии). |
latestMajorили default |
Компилятор принимает синтаксис из последней основной версии компилятора. |
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 имеет значениеdefault.Параметр компилятора LangVersion не влияет на метаданные, на которые ссылается ваше приложение C#.
Так как каждая версия компилятора C# содержит расширения для спецификации языка, параметр LangVersion не позволяет использовать возможности, аналогичные возможностям более ранней версии компилятора.
Хотя обновления версий C# обычно совпадают с основными выпусками .NET, новые синтаксис и функции не обязательно привязаны к этой конкретной версии платформы. Каждая конкретная функция имеет собственные минимальные требования к API .NET или среде 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
Параметр Nullable позволяет указать контекст, допускающий значение NULL. Его можно задать в конфигурации проекта с помощью тега <Nullable> :
<Nullable>enable</Nullable>
Аргумент должен иметь одно из следующих значений: enable, disable, warnings или annotations. Аргумент enable разрешает контекст, допускающий значение NULL. При указании disable контекст, допускающий значение NULL, будет отключен. При указании аргумента warnings включен контекст предупреждения, допускающий значение NULL. При указании аргумента annotations включен контекст заметки, допускающий значение NULL. Эти значения описаны и описаны в статье о контекстах, допускающих значение NULL. Дополнительные сведения о задачах, связанных с включением ссылочных типов, допускающих значение NULL, в существующей базе кода в нашей статье о стратегиях миграции, допускающих значение NULL.
Примечание.
Если значения не заданы, применяется значение disable по умолчанию, однако шаблоны .NET 6 по умолчанию предоставляются значением NULLenable.
Анализ потока используется для определения допустимости значений NULL в переменных в исполняемом коде. Выводимая допустимость переменной значения NULL не зависит от объявленной в переменной допустимости значения NULL. Вызовы методов анализируются, даже если они условно опущены. Например, Debug.Assert в режиме выпуска.
Вызов методов, снабженных следующими атрибутами, также повлияет на анализ потока:
- Простые предварительные условия: AllowNullAttribute и DisallowNullAttribute
- Простые постусловия: MaybeNullAttribute и NotNullAttribute
- Условные постусловия: MaybeNullWhenAttribute и NotNullWhenAttribute
- DoesNotReturnIfAttribute (например,
DoesNotReturnIf(false)для Debug.Assert) и DoesNotReturnAttribute - NotNullIfNotNullAttribute
- Постусловия элемента: MemberNotNullAttribute(String) и MemberNotNullAttribute(String[])
Внимание
Глобальный контекст, допускающий значения NULL, не применяется для созданных файлов кода. Независимо от этого параметра, контекст, допускающий значение NULL, отключен для любого исходного файла, помеченного как созданный. Существует четыре способа пометки файла как созданного:
- В файле. editorconfig укажите
generated_code = trueв разделе, который применяется к этому файлу. - Вставьте
<auto-generated>или<auto-generated/>в комментарий в верхней части файла. Он может находиться в любой строке комментария, однако блок комментариев должен быть первым элементом в файле. - Имя файла следует начинать с TemporaryGeneratedFile_
- В конце имени файла следует указать .designer.cs, .generated.cs, .g.cs или .g.i.cs.
Генераторы могут явно использовать директиву препроцессора #nullable.
