Справочник по MSBuild для проектов пакета SDK для .NET

Эта страница содержит справочные сведения о свойствах и элементах MSBuild, которые вы можете использовать для настройки проектов .NET.

Примечание

Работа над этой страницей еще не завершена, поэтому здесь приведены лишь некоторые полезные свойства MSBuild для пакета SDK для .NET. Список стандартных свойств см. в статье Общие свойства MSBuild.

Свойства платформы

В этом разделе описаны следующие свойства MSBuild:

TargetFramework

Свойство TargetFramework определяет версию целевой платформы для приложения. Список допустимых моникеров целевой платформы см. в статье Целевые платформы в проектах в стиле SDK.

<PropertyGroup>
  <TargetFramework>netcoreapp3.1</TargetFramework>
</PropertyGroup>

Дополнительные сведения см.в статье Целевые платформы в проектах в стиле SDK.

TargetFrameworks

Используйте свойство TargetFrameworks, если приложение должно быть предназначено для нескольких платформ. Список допустимых моникеров целевой платформы см. в статье Целевые платформы в проектах в стиле SDK.

Примечание

Это свойство игнорируется, если указано свойство TargetFramework (в единственном числе).

<PropertyGroup>
  <TargetFrameworks>netcoreapp3.1;net462</TargetFrameworks>
</PropertyGroup>

Дополнительные сведения см.в статье Целевые платформы в проектах в стиле SDK.

NetStandardImplicitPackageVersion

Примечание

Это свойство применяется только к проектам, использующим netstandard1.x. Он не применяется к проектам, использующим netstandard2.x.

Используйте свойство NetStandardImplicitPackageVersion, если вам нужно указать версию платформы ниже версии метапакета. Файл проекта, приведенный в следующем примере, предназначен для netstandard1.3, но использует NETStandard.Library версии 1.6.0.

<PropertyGroup>
  <TargetFramework>netstandard1.3</TargetFramework>
  <NetStandardImplicitPackageVersion>1.6.0</NetStandardImplicitPackageVersion>
</PropertyGroup>

Свойства атрибутов сборки

GenerateAssemblyInfo

Свойство AssemblyInfo управляет созданием атрибута GenerateAssemblyInfo для проекта. Значение по умолчанию — true. Используйте false, чтобы отключить создание файла:

<PropertyGroup>
  <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
</PropertyGroup>

Параметр GeneratedAssemblyInfoFile определяет имя создаваемого файла.

Если значение GenerateAssemblyInfo равно true, связанные с пакетом свойства проекта преобразуются в атрибуты сборки. В таблице ниже перечислены свойства проекта, которые создают атрибуты. В ней также перечислены свойства, которые можно использовать для отключения этого создания на уровне каждого атрибута, например:

<PropertyGroup>
  <GenerateNeutralResourcesLanguageAttribute>false</GenerateNeutralResourcesLanguageAttribute>
</PropertyGroup>
Свойство MSBuild Атрибут сборки Свойство для отключения создания атрибута
Company AssemblyCompanyAttribute GenerateAssemblyCompanyAttribute
Configuration AssemblyConfigurationAttribute GenerateAssemblyConfigurationAttribute
Copyright AssemblyCopyrightAttribute GenerateAssemblyCopyrightAttribute
Description AssemblyDescriptionAttribute GenerateAssemblyDescriptionAttribute
FileVersion AssemblyFileVersionAttribute GenerateAssemblyFileVersionAttribute
InformationalVersion AssemblyInformationalVersionAttribute GenerateAssemblyInformationalVersionAttribute
Product AssemblyProductAttribute GenerateAssemblyProductAttribute
AssemblyTitle AssemblyTitleAttribute GenerateAssemblyTitleAttribute
AssemblyVersion AssemblyVersionAttribute GenerateAssemblyVersionAttribute
NeutralLanguage NeutralResourcesLanguageAttribute GenerateNeutralResourcesLanguageAttribute

Примечания об этих параметрах:

  • AssemblyVersion и FileVersion по умолчанию имеют значение $(Version) без суффикса. Например, если для $(Version) нужно указать 1.2.3-beta.4, то значением будет 1.2.3.
  • По умолчанию для InformationalVersion используется значение $(Version).
  • Если имеется свойство $(SourceRevisionId), оно добавляется к InformationalVersion. Такое поведение можно отключить с помощью IncludeSourceRevisionInInformationalVersion.
  • Свойства Copyright и Description также используются для метаданных NuGet.
  • Свойство Configuration, которое по умолчанию имеет значение Debug, является общим для всех целевых объектов MSBuild. Его можно задать с помощью параметра --configuration команды dotnet (например, dotnet pack).
  • Некоторые свойства используются при создании пакета NuGet. Дополнительные сведения см. в разделе Свойства пакетов.

Миграция из .NET Framework

Шаблоны проектов .NET Framework создают файл кода со следующими заданными атрибутами сведений о сборке. Обычно файл расположен здесь: .\Properties\AssemblyInfo.cs или .\Properties\AssemblyInfo.vb. Проекты в стиле пакета SDK создают этот файл на основе параметров проекта. Оба варианта не поддерживаются. При переносе кода в .NET 5 (и .NET Core 3.1) или более поздней версии выполните одно из следующих действий:

  • Отключите возможность создания временного файла кода, который содержит атрибуты сведений о сборке, задав для GenerateAssemblyInfo значение false в файле проекта. Так вы сохраните свой файл AssemblyInfo.
  • Перенесите параметры из файла AssemblyInfo в файл проекта, а затем удалите файл AssemblyInfo.

GeneratedAssemblyInfoFile

Свойство GeneratedAssemblyInfoFile определяет относительный или абсолютный путь к файлу сведений о созданной сборке. По умолчанию используется файл с именем [имя_проекта].AssemblyInfo.[cs|vb] в каталоге $(IntermediateOutputPath) (обычно это obj).

<PropertyGroup>
  <GeneratedAssemblyInfoFile>assemblyinfo.cs</GeneratedAssemblyInfoFile>
</PropertyGroup>

Свойства пакета

Описательные свойства

Для описания пакета, созданного из проекта, можно указать такие свойства, как PackageId, PackageVersion, PackageIcon, Title и Description. Дополнительные сведения об этих и других свойствах см. в разделе целевой объект пакета.

<PropertyGroup>
  ...
  <PackageId>ClassLibDotNetStandard</PackageId>
  <Version>1.0.0</Version>
  <Authors>John Doe</Authors>
  <Company>Contoso</Company>
</PropertyGroup>

PackRelease

Свойство PackRelease похоже на свойство PublishRelease, только оно изменяет поведение dotnet pack по умолчанию.

<PropertyGroup>
  <PackRelease>true</PackRelease>
</PropertyGroup>

Примечание

Чтобы использовать PackRelease в проекте в рамках решения Visual Studio, необходимо задать переменной среды DOTNET_CLI_ENABLE_PACK_RELEASE_FOR_SOLUTIONS значение true (или любое другое). Задание этой переменной увеличит время, необходимое для упаковки решений со множеством проектов.

В этом разделе описаны следующие свойства MSBuild:

AppendTargetFrameworkToOutputPath

Свойство AppendTargetFrameworkToOutputPath определяет, добавляется ли моникер целевой платформы (TFM) к выходному пути (который определяется свойством OutputPath). Пакет SDK для .NET автоматически добавляет к выходному пути целевую платформу и идентификатор среды выполнения (если он есть). При установке значения false для свойства AppendTargetFrameworkToOutputPath TFM не добавляется к выходному пути. Однако при отсутствии TFM в выходном пути несколько артефактов сборки могут перезаписывать друг друга.

Например, при установке следующего параметра выходной путь для приложения .NET 5 изменяется с bin\Debug\net5.0 на bin\Debug:

<PropertyGroup>
  <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
</PropertyGroup>

AppendRuntimeIdentifierToOutputPath

Свойство AppendRuntimeIdentifierToOutputPath определяет, добавляется ли к выходному пути идентификатор среды выполнения (RID). Пакет SDK для .NET автоматически добавляет к выходному пути целевую платформу и идентификатор среды выполнения (если он есть). При установке значения false для свойства AppendRuntimeIdentifierToOutputPath RID не добавляется к выходному пути.

Например, при установке следующего параметра выходной путь для приложения .NET 5 и идентификатора RID win10-x64 изменяется с bin\Debug\net5.0\win10-x64 на bin\Debug\net5.0:

<PropertyGroup>
  <AppendRuntimeIdentifierToOutputPath>false</AppendRuntimeIdentifierToOutputPath>
</PropertyGroup>

CopyLocalLockFileAssemblies

Свойство CopyLocalLockFileAssemblies полезно для проектов подключаемых модулей, которые имеют зависимости от других библиотек. Если для этого свойства задано значение true, все зависимости пакета NuGet копируются в выходной каталог. Это означает, что вы можете использовать выходные данные dotnet build для запуска подключаемого модуля на любом компьютере.

<PropertyGroup>
  <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
</PropertyGroup>

Совет

Кроме того, можно использовать dotnet publish для публикации библиотеки классов. Дополнительные сведения см. в разделе dotnet publish.

ErrorOnDuplicatePublishOutputFiles

Свойство ErrorOnDuplicatePublishOutputFiles указывает, выдает ли пакет SDK ошибку NETSDK1148, когда MSBuild обнаруживает дубликаты файлов в выходных данных публикации, но не может определить, какие файлы нужно удалить. Задайте для свойства ErrorOnDuplicatePublishOutputFiles значение false, если не нужно выдавать ошибку.

<PropertyGroup>
  <ErrorOnDuplicatePublishOutputFiles>false</ErrorOnDuplicatePublishOutputFiles>
</PropertyGroup>

Это свойство представлено в .NET 6.

EnablePackageValidation

Свойство EnablePackageValidation активирует ряд проверок пакета после задачи pack. Дополнительные сведения см. в статье Проверка пакета.

<PropertyGroup>
  <EnablePackageValidation>true</EnablePackageValidation>
</PropertyGroup>

Это свойство представлено в .NET 6.

GenerateRuntimeConfigDevFile

Начиная с пакета SDK для .NET 6, файл [Appname].runtimesettings.dev.jsonбольше не создается по умолчанию во время компиляции. Если вы по-прежнему хотите создать этот файл, задайте для свойства GenerateRuntimeConfigDevFile значение true.

<PropertyGroup>
  <GenerateRuntimeConfigDevFile>true</GenerateRuntimeConfigDevFile>
</PropertyGroup>

GenerateRuntimeConfigurationFiles

Свойство GenerateRuntimeConfigurationFiles определяет, копируются ли параметры конфигурации среды выполнения из файла runtimeconfig. template.json в файл [имя приложения].runtimeconfig.json. Для приложений, которым требуется файл runtimeconfig.json, т.е. для тех, у которых OutputType имеет значение Exe, это свойство по умолчанию равно true.

<PropertyGroup>
  <GenerateRuntimeConfigurationFiles>true</GenerateRuntimeConfigurationFiles>
</PropertyGroup>

GenerateSatelliteAssembliesForCore

Свойство GenerateSatelliteAssembliesForCore определяет, создаются ли вспомогательные сборки при использовании csc.exe или Al.exe (компоновщик сборок) в проектах платформы .NET Framework. (Проекты .NET Core и .NET 5+ всегда используют csc.exe для создания вспомогательных сборок.) Для проектов платформы .NET Framework вспомогательные сборки по умолчанию создаются средством al.exe. Если для свойства GenerateSatelliteAssembliesForCore задано значение true, вспомогательные сборки создаются в csc.exe. Использование csc.exe может оказаться выгодным в следующих ситуациях:

<PropertyGroup>
  <GenerateSatelliteAssembliesForCore>true</GenerateSatelliteAssembliesForCore>
</PropertyGroup>

IsPublishable

Свойство IsPublishable позволяет запускать целевой объект Publish. Это свойство касается только процессов, использующих файлы .*proj и целевой объект Publish, например команды dotnet publish. Оно не влияет на публикацию в Visual Studio, где используется целевой объект PublishOnly. По умолчанию используется значение true.

Это свойство полезно при запуске dotnet publish в файле решения, так как позволяет автоматически выбирать проекты, которые должны быть опубликованы.

<PropertyGroup>
  <IsPublishable>false</IsPublishable>
</PropertyGroup>

PreserveCompilationContext

Свойство PreserveCompilationContext позволяет собранному или опубликованному приложению компилировать дополнительный код во время выполнения с теми же параметрами, которые использовались во время сборки. Сборки, ссылки на которые были указаны во время сборки, будут скопированы в подкаталог ref выходного каталога. Имена базовых сборок хранятся в файле .deps.json приложения вместе с параметрами, передаваемыми компилятору. Эту информацию можно получить с помощью свойств DependencyContext.CompileLibraries и DependencyContext.CompilationOptions.

Эта функциональность в основном используется внутри системы для поддержки компиляции файлов Razor во время выполнения на страницах MVC и Razor ASP.NET Core.

<PropertyGroup>
  <PreserveCompilationContext>true</PreserveCompilationContext>
</PropertyGroup>

PreserveCompilationReferences

Свойство PreserveCompilationReferences аналогично свойству PreserveCompilationContext за исключением того, что при его использовании в каталог публикации копируются только указанные ссылками сборки, но не копируется файл .deps.json.

<PropertyGroup>
  <PreserveCompilationReferences>true</PreserveCompilationReferences>
</PropertyGroup>

Дополнительные сведения см. в разделе Свойства пакета SDK Razor.

ProduceReferenceAssemblyInOutDir

В .NET 5 и более ранних версиях базовые сборки всегда записываются в каталог OutDir. В .NET 6 и более поздних версиях можно использовать свойство ProduceReferenceAssemblyInOutDir для управления записью базовых сборок в каталог OutDir. По умолчанию используется значение false, и базовые сборки записываются только в каталог IntermediateOutputPath. Задайте значение true, чтобы записывать базовые сборки в каталог OutDir.

<PropertyGroup>
  <ProduceReferenceAssemblyInOutDir>true</ProduceReferenceAssemblyInOutDir>
</PropertyGroup>

Дополнительные сведения: Запись базовых сборок в промежуточный вывод.

PublishDocumentationFile

Если это свойство имеет значение true, XML-файл документации для проекта, если он создан, включается в выходные данные публикации для проекта. По умолчанию свойство имеет значение true.

Совет

Задайте для GenerateDocumentationFile значение , true чтобы создать XML-файл документации во время компиляции.

PublishDocumentationFiles

Это свойство является флагом включения для нескольких других свойств, которые определяют, копируются ли различные типы XML-файлов документации в каталог публикации по умолчанию, а именно PublishDocumentationFile и PublishReferencesDocumentationFiles. Если эти свойства не заданы и это свойство задано, по умолчанию эти свойства будут равны true. По умолчанию свойство имеет значение true.

PublishReferencesDocumentationFiles

Если это свойство имеет значение true, XML-файлы документации для ссылок проекта копируются в каталог публикации, а не только в ресурсы времени выполнения, такие как DLL-файлы. По умолчанию свойство имеет значение true.

PublishRelease

Свойство PublishRelease сообщает dotnet publish о необходимости использовать по умолчанию конфигурацию Release вместо Debug.

<PropertyGroup>
  <PublishRelease>true</PublishRelease>
</PropertyGroup>

Примечание

  • Это свойство не влияет на поведение dotnet build /t:Publish и изменяет конфигурацию только при публикации с помощью .NET CLI.
  • Чтобы использовать PublishRelease в проекте в рамках решения Visual Studio, необходимо задать переменной среды DOTNET_CLI_ENABLE_PUBLISH_RELEASE_FOR_SOLUTIONS значение true (или любое другое). Это увеличит время, необходимое для публикации решений со множеством проектов. Если эта переменная включена при публикации решения, приоритет отдается значению PublishRelease исполняемого проекта, и новая конфигурация по умолчанию задается всем остальным проектам в решении. Если в решении содержится несколько исполняемых проектов или проектов верхнего уровня, значения PublishRelease которых различаются, публикация решения завершится сбоем.

RollForward

Свойство RollForward управляет тем, как приложение выбирает среду выполнения, если доступно несколько версий. Это значение выводится в .runtimeconfig.js в качестве параметра rollForward.

<PropertyGroup>
  <RollForward>LatestMinor</RollForward>
</PropertyGroup>

Задайте для RollForward одно из следующих значений:

Значение Описание
Minor Значение по умолчанию, если не указано.
Накат до дополнительной версии со следующим по порядку возрастания номером, если запрошенная дополнительная версия отсутствует. Если запрошенная дополнительная версия присутствует, используется политика LatestPatch.
Major Накат до следующей доступной основной версии или следующей дополнительной версии с наименьшим номером, если запрошенная дополнительная версия отсутствует. Если запрошенная дополнительная версия присутствует, используется политика Minor.
LatestPatch Накат до версии с наибольшим номером исправления. Это значение отключает накат до дополнительных версий.
LatestMinor Накат до дополнительной версии с наибольшим номером, даже если запрошенная дополнительная версия присутствует.
LatestMajor Накат до основной версии с наибольшим номером и дополнительной версии с наибольшим номером, даже если запрошенная основная версия присутствует.
Disable Не выполнять накат, привязывать только к указанной версии. Эта политика не рекомендуется для общего использования, поскольку отключает возможность наката до последних исправлений. Это значение рекомендуется использовать только для тестирования.

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

RuntimeFrameworkVersion

Свойство RuntimeFrameworkVersion указывает версию среды выполнения, используемую при публикации. Укажите версию среды выполнения:

<PropertyGroup>
  <RuntimeFrameworkVersion>5.0.7</RuntimeFrameworkVersion>
</PropertyGroup>

При публикации приложения, зависящего от платформы, это значение указывает минимальную требуемую версию. При публикации автономного приложения это значение указывает точную требуемую версию.

RuntimeIdentifier

Свойство RuntimeIdentifier позволяет указать для проекта один идентификатор среды выполнения (RID). Идентификатор среды выполнения позволяет опубликовать автономное развертывание.

<PropertyGroup>
  <RuntimeIdentifier>ubuntu.16.04-x64</RuntimeIdentifier>
</PropertyGroup>

RuntimeIdentifiers

Свойство RuntimeIdentifiers позволяет указать для проекта список идентификаторов среды выполнения (RID) (в качестве разделителя используется точка с запятой). Используйте это свойство, если вам нужна публикация для нескольких сред. RuntimeIdentifiers используется во время восстановления для обеспечения наличия в графе нужных ресурсов.

Совет

RuntimeIdentifier (в единственном числе) может ускорить создание сборок, когда требуется только одна среда выполнения.

<PropertyGroup>
  <RuntimeIdentifiers>win10-x64;osx.10.11-x64;ubuntu.16.04-x64</RuntimeIdentifiers>
</PropertyGroup>

SatelliteResourceLanguages

Свойство SatelliteResourceLanguages позволяет указать, какие языки необходимо сохранить для вспомогательных сборок ресурсов во время сборки и публикации. Многие пакеты NuGet содержат локализованные вспомогательные сборки ресурсов в основном пакете. Для проектов, которые ссылаются на эти пакеты NuGet, но не требуют локализованных ресурсов, локализованные сборки могут без необходимости увеличить размер выходных данных сборки и публикации. Если вы добавите свойство SatelliteResourceLanguages в файл проекта, в выходные данные сборки и публикации будут включены только локализованные сборки для указанных вами языков. Например, в указанном ниже файле проекта будут сохранены только вспомогательные сборки ресурсов на английском (США) и немецком (Германия) языках.

<PropertyGroup>
  <SatelliteResourceLanguages>en-US;de-DE</SatelliteResourceLanguages>
</PropertyGroup>

Примечание

  • Это свойство необходимо указать в проекте, который ссылается на пакет NuGet с локализованными вспомогательными сборками ресурсов.

  • Чтобы указать несколько языков в качестве аргумента для dotnet publish, необходимо добавить три пары кавычек вокруг идентификаторов языков. Например:

    dotnet msbuild multi.msbuildproj -p:SatelliteResourceLanguages="""de;en"""

UseAppHost

Свойство UseAppHost контролирует создание собственного исполняемого файла для развертывания. Этот файл требуется для автономных развертываний.

В .NET Core 3.0 и более поздних версиях зависимый от платформы исполняемый файл создается по умолчанию. Задайте свойству UseAppHost значение false, чтобы отключить создание исполняемого файла.

<PropertyGroup>
  <UseAppHost>false</UseAppHost>
</PropertyGroup>

Дополнительные сведения см. в статье о развертывании приложений .NET.

Доступно множество свойств MSBuild, позволяющих тонко настроить обрезку неиспользуемого кода в автономных развертываниях. Они подробно описаны в статье Параметры обрезки. В следующей таблице приводится краткий справочник.

Свойство Значения Описание
PublishTrimmed true или false Определяет, включена ли обрезка во время публикации.
TrimMode full или partial По умолчанию — full. Управляет степенью детализации обрезки.
SuppressTrimAnalysisWarnings true или false Контролирует выдачу предупреждений анализа обрезки.
EnableTrimAnalyzer true или false Контролирует выдачу определенного набора предупреждений анализа обрезки. Вы можете включить анализ, даже если PublishTrimmed имеет значение false.
ILLinkTreatWarningsAsErrors true или false Определяет, рассматривать ли предупреждения об обрезке как ошибки. Например, вы можете задать этому свойству значение false, если для TreatWarningsAsErrors задано true.
TrimmerSingleWarn true или false Определяет, отображать ли по одному предупреждению на сборку или все предупреждения.
TrimmerRemoveSymbols true или false Определяет, удалять ли все символы из приложения с обрезкой.

В этом разделе описаны следующие свойства MSBuild:

Параметры компилятора C#, такие как LangVersion и Nullable, также можно указать в качестве свойств MSBuild в файле проекта. Дополнительные сведения см. в разделе Параметры компилятора C#.

ContinuousIntegrationBuild

Свойство ContinuousIntegrationBuild указывает, выполняется ли сборка на сервере непрерывной интеграции (CI). Если задано значение true, это свойство включает параметры, которые применяются только к официальным сборкам, а не к локальным сборкам на компьютере разработчика. Например, пути к хранимым файлам нормализуются для официальных сборок. Но на локальном компьютере разработки отладчик не сможет найти локальные исходные файлы, если пути к файлам нормализуются.

Для условного ContinuousIntegrationBuild задания свойства можно использовать переменную системы CI. Например, имя переменной для Azure Pipelines — TF_BUILD:

<PropertyGroup Condition="'$(TF_BUILD)' == 'true'">
  <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
</PropertyGroup>

Для GitHub Actions имя переменной равно GITHUB_ACTIONS:

<PropertyGroup Condition="'$(GITHUB_ACTIONS)' == 'true'">
  <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
</PropertyGroup>

CopyDebugSymbolFilesFromPackages

Если этому свойству trueприсвоено значение , все файлы символов (также известные как PDB-файлы) из PackageReference элементов проекта копируются в выходные данные сборки. Эти файлы могут предоставлять более информативные трассировки стека для исключений и упрощают понимание дампов памяти и трассировок запущенного приложения. Однако включение этих файлов приводит к увеличению размера пакета развертывания.

Это свойство появилось в пакете SDK для .NET 7.0.100, хотя по умолчанию оно не указано.

CopyDocumentationFilesFromPackages

Если для этого свойства задано значение true, все созданные XML-файлы документации из PackageReference элементов проекта копируются в выходные данные сборки. Обратите внимание, что включение этой функции приведет к увеличению размера пакета развертывания.

Это свойство появилось в пакете SDK для .NET 7.0.100, хотя по умолчанию оно не указано.

DisableImplicitFrameworkDefines

Свойство DisableImplicitFrameworkDefines определяет, должен ли пакет SDK создавать символы препроцессора для требуемой версии .NET Framework и платформы проекта .NET. Если свойство имеет значение false или не задано (значение по умолчанию), то символы препроцессора создаются для следующего:

  • Framework без версии (NETFRAMEWORK, NETSTANDARD, NET)
  • Framework с версией (NET48, NETSTANDARD2_0, NET6_0)
  • Framework с минимальной границей версии (NET48_OR_GREATER, NETSTANDARD2_0_OR_GREATER, NET6_0_OR_GREATER)

Дополнительные сведения о моникерах целевой платформы и этих неявных символах препроцессора см. в статье Требуемые версии .NET Framework.

Кроме того, если указать в проекте требуемую версию .NET Framework для конкретной операционной системы (например, net6.0-android), то создаются следующие символы препроцессора:

  • Платформа без версии (ANDROID, IOS, WINDOWS)
  • Платформа с версией (IOS15_1)
  • Платформа с минимальной границей версии (IOS15_1_OR_GREATER)

Дополнительные сведения о моникерах целевой платформы для конкретных операционных систем см. в разделе TFM для конкретной ОС.

Наконец, если требуемая версия .NET Framework подразумевает поддержку более старых версий Framework, символы препроцессора создаются для этих версий. Например, net6.0подразумевает поддержку net5.0 и так далее, вплоть до .netcoreapp1.0. Таким образом, для каждой из этих версий .NET Framework будет определен символ Framework с минимальной границей версии.

DocumentationFile

Свойство DocumentationFile позволяет указать имя файла XML, содержащего документацию для библиотеки. Для правильной работы IntelliSense с вашей документацией имя файла должно совпадать с именем сборки и находиться в том же каталоге, что и сборка. Если вы не определили это свойство, но задали для GenerateDocumentationFile значение true, именем файла документации по умолчанию будет имя вашей сборки, но с расширением файла .xml. По этой причине часто проще опустить это свойство и использовать вместо него свойство GenerateDocumentationFile.

Если вы определили это свойство, но для GenerateDocumentationFile задали значение false, компилятор не создаст файл документации. Если вы определили это свойство и опустили GenerateDocumentationFile, компилятор создаст файл документации.

<PropertyGroup>
  <DocumentationFile>path/to/file.xml</DocumentationFile>
</PropertyGroup>

EmbeddedResourceUseDependentUponConvention

Свойство EmbeddedResourceUseDependentUponConvention определяет, будет ли использоваться информация о типах в исходных файлах, расположенных в одной папке с файлами ресурсов, для создания имен файлов манифеста этих ресурсов. Например, если Form1.resx находится в той же папке, что и Form1.cs, а EmbeddedResourceUseDependentUponConvention имеет значение true, то созданному файл .resources присваивается имя на основе имени первого типа, определенного в файле Form1.cs. Например, если первым типом в файле Form1.cs является MyNamespace.Form1, созданному файлу присваивается имя MyNamespace.Form1.resources.

Примечание

Если для EmbeddedResource элемента заданы метаданные LogicalName, ManifestResourceName или DependentUpon, то имя файла манифеста для этого файла ресурсов будет создаваться на основе таких метаданных.

По умолчанию для нового проекта .NET этому свойству задается значение true. Если задано значение false и для элемента EmbeddedResource в файле проекта не указаны метаданные LogicalName, ManifestResourceName или DependentUpon, то имя файла манифеста для этого ресурса будет основано на имени корневого пространства имен проекта и относительном пути к файлу .resx. Дополнительные сведения об определение имени файла манифеста см. здесь.

<PropertyGroup>
  <EmbeddedResourceUseDependentUponConvention>true</EmbeddedResourceUseDependentUponConvention>
</PropertyGroup>

EnablePreviewFeatures

Свойство EnablePreviewFeatures определяет, зависит ли ваш проект от каких-либо API или сборок, снабженных атрибутом RequiresPreviewFeaturesAttribute. Этот атрибут используется для обозначения того, что API или сборка использует функции, которые считаются предварительными версиями для версии пакета SDK, которую вы используете. Предварительные версии функций не поддерживаются и могут быть удалены в будущих версиях. Чтобы включить предварительные версии функций, задайте для свойства значение True.

<PropertyGroup>
  <EnablePreviewFeatures>True</EnablePreviewFeatures>
</PropertyGroup>

Если проект содержит свойство, для которого задано значение True, в файл AssemblyInfo.cs добавляется следующий атрибут уровня сборки:

[assembly: RequiresPreviewFeatures]

Анализатор выдает предупреждение, если этот атрибут имеется в зависимостях для проектов, где для EnablePreviewFeatures не задано значение True.

Авторы библиотек, которые планируют поставлять сборки с предварительными версиями функций, присвойте этому свойству значение True. Если в поставляемую сборку входят как предварительные, так и другие версии API, см. раздел GenerateRequiresPreviewFeaturesAttribute.

EnableWindowsTargeting

Присвойте свойству EnableWindowsTargeting значение , true чтобы создавать приложения Windows (например, Windows Forms или Windows Presentation Foundation приложения) на платформе, отличной от Windows. Если не задать для этого свойства trueзначение , вы получите предупреждение о сборке NETSDK1100. Эта ошибка возникает из-за того, что целевые пакеты и пакеты среды выполнения не загружаются автоматически на неподдерждаемые платформы. Задав это свойство, эти пакеты загружаются при перекрестном нацелии.

<PropertyGroup>
  <EnableWindowsTargeting>true</EnableWindowsTargeting>
</PropertyGroup>

GenerateDocumentationFile

Свойство GenerateDocumentationFile определяет, создаст ли компилятор файл документации XML для вашей библиотеки. Если вы задали для этого свойства значение true и не указали имя файла через свойство DocumentationFile, сгенерированный файл XML будет помещен в тот же выходной каталог, что и ваша сборка, и будет иметь то же имя файла (но с расширением .xml).

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Дополнительные сведения о создании документации из комментариев к коду см. в статьях Комментарии к документации XML (C#), Документирование кода с помощью XML (Visual Basic) или Документирование кода с помощью XML (F#).

GenerateRequiresPreviewFeaturesAttribute

Свойство GenerateRequiresPreviewFeaturesAttribute тесно связано со свойством EnablePreviewFeatures. Если ваша библиотека использует предварительные версии функций, но вы не хотите, чтобы вся сборка была помечена атрибутом RequiresPreviewFeaturesAttribute, что потребует от всех потребителей включения предварительных версий функций, присвойте этому свойству значение False.

<PropertyGroup>
    <EnablePreviewFeatures>True</EnablePreviewFeatures>
    <GenerateRequiresPreviewFeaturesAttribute>False</GenerateRequiresPreviewFeaturesAttribute>
</PropertyGroup>

Важно!

Если свойству GenerateRequiresPreviewFeaturesAttribute задано значение False, вы должны быть уверены в том, что все общедоступные API, использующие предварительные версии функций, будет присвоен атрибут RequiresPreviewFeaturesAttribute.

OptimizeImplicitlyTriggeredBuild

Чтобы сократить время сборки, для неявно активированных Visual Studio сборок пропускается анализ кода, включая анализ типов, допускающих значения NULL. Visual Studio активирует неявную сборку, например, при выполнении тестов. Однако неявные сборки оптимизируются только в том случае, если TreatWarningsAsErrors не имеет значение true. Если для параметра TreatWarningsAsErrors задано значение true, но вы все равно хотите оптимизировать неявно активированные сборки, можно задать для OptimizeImplicitlyTriggeredBuild значение True. Чтобы отключить оптимизацию неявно активированных сборок, присвойте параметру OptimizeImplicitlyTriggeredBuild значение False.

<PropertyGroup>
    <OptimizeImplicitlyTriggeredBuild>True</OptimizeImplicitlyTriggeredBuild>
</PropertyGroup>

Свойства включения элементов по умолчанию

В этом разделе описаны следующие свойства MSBuild:

Дополнительные сведения см. в разделе Включения и исключения по умолчанию.

DefaultItemExcludes

Используйте свойство DefaultItemExcludes, чтобы определить стандартные маски для файлов и папок, которые должны быть исключены из стандартных масок включения, исключения и удаления. По умолчанию папки ./bin и ./obj исключаются из стандартных масок.

<PropertyGroup>
  <DefaultItemExcludes>$(DefaultItemExcludes);**/*.myextension</DefaultItemExcludes>
</PropertyGroup>

DefaultItemExcludesInProjectFolder

Используйте свойство DefaultItemExcludesInProjectFolder, чтобы определить стандартные маски для файлов и папок в папке проекта, которые должны быть исключены из стандартных масок включения, исключения и удаления. По умолчанию папки, начинающиеся с точки (.), такие как .git и .vs, исключаются из стандартных масок.

Это свойство очень похоже на свойство DefaultItemExcludes, за исключением того, что оно учитывает только файлы и папки в папке проекта. Если стандартная маска будет случайно соответствовать элементам за пределами папки проекта с относительным путем, используйте свойство DefaultItemExcludesInProjectFolder вместо свойства DefaultItemExcludes.

<PropertyGroup>
  <DefaultItemExcludesInProjectFolder>$(DefaultItemExcludesInProjectFolder);**/myprefix*/**</DefaultItemExcludesInProjectFolder>
</PropertyGroup>

EnableDefaultItems

Свойство EnableDefaultItems определяет, включаются ли в проект неявным образом элементы компиляции, элементы внедренных ресурсов и элементы None. Значение по умолчанию — true. Задайте значение false для свойства EnableDefaultItems, чтобы отключить все неявные включения файлов.

<PropertyGroup>
  <EnableDefaultItems>false</EnableDefaultItems>
</PropertyGroup>

EnableDefaultCompileItems

Свойство EnableDefaultCompileItems определяет, включаются ли в проект неявным образом элементы компиляции. Значение по умолчанию — true. Задайте значение false для свойства EnableDefaultCompileItems, чтобы отключить неявное включение файлов *.cs и других файлов расширения языка.

<PropertyGroup>
  <EnableDefaultCompileItems>false</EnableDefaultCompileItems>
</PropertyGroup>

EnableDefaultEmbeddedResourceItems

Свойство EnableDefaultEmbeddedResourceItems определяет, включаются ли в проект неявным образом элементы внедренных ресурсов. Значение по умолчанию — true. Задайте значение false для свойства EnableDefaultEmbeddedResourceItems, чтобы отключить неявное включение файлов внедренных ресурсов.

<PropertyGroup>
  <EnableDefaultEmbeddedResourceItems>false</EnableDefaultEmbeddedResourceItems>
</PropertyGroup>

EnableDefaultNoneItems

Свойство EnableDefaultNoneItems определяет, включаются ли в проект неявным образом элементы None (файлы, которые не играют никакой роли в процессе сборки). Значение по умолчанию — true. Задайте значение false для свойства EnableDefaultNoneItems, чтобы отключить неявное включение элементов None.

<PropertyGroup>
  <EnableDefaultNoneItems>false</EnableDefaultNoneItems>
</PropertyGroup>

Свойства анализа кода

В этом разделе описаны следующие свойства MSBuild:

AnalysisLevel

Свойство AnalysisLevel позволяет указать набор выполняемых анализаторов кода в соответствии с выпуском .NET. В каждом выпуске .NET, начиная с .NET 5, есть набор правил анализа кода. Правила из этого набора, которые включены по умолчанию для этого выпуска, будут применяться для анализа кода. Например, если вы выполняете обновление до .NET 7, но не хотите, чтобы набор правил анализа кода по умолчанию изменял, задайте значение AnalysisLevel6.

<PropertyGroup>
  <AnalysisLevel>preview</AnalysisLevel>
</PropertyGroup>

Начиная с версии .NET 6, при необходимости вы можете указать для этого свойства составное значение, которое также определяет, насколько агрессивно будут применяться правила. Составные значения имеют такой вид: <version>-<mode>, где в качестве значения <mode> указано одно из значений AnalysisMode. В следующем примере используется предварительная версия анализаторов кода и включается рекомендуемый набор правил.

<PropertyGroup>
  <AnalysisLevel>preview-recommended</AnalysisLevel>
</PropertyGroup>

Примечание

Если вы присвоите AnalysisLevel значение 5-<mode> или 5.0-<mode>, а затем установите пакет SDK для .NET 6 и выполните повторную компиляцию проекта, могут возникнуть неожиданные новые предупреждения компиляции. Дополнительные сведения см. в справочном документе dotnet/roslyn-analyzers#5679.

Значение по умолчанию:

  • Если проект предназначен для .NET 5 или более поздней версии либо если вы добавили свойство AnalysisMode, значением по умолчанию будет latest.
  • В противном случае это свойство не будет учитываться, если оно явно не добавлено в файл проекта.

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

Значение Значение
latest Используются новейшие анализаторы кода, которые были выпущены. Это значение по умолчанию.
latest-<mode> Используются новейшие анализаторы кода, которые были выпущены. Значение <mode> определяет, какие правила включены.
preview Используются новейшие анализаторы кода, даже если они находятся на этапе предварительной версии.
preview-<mode> Используются новейшие анализаторы кода, даже если они находятся на этапе предварительной версии. Значение <mode> определяет, какие правила включены.
7.0 Используется набор правил, доступных для выпуска .NET 7, даже если доступны более новые правила.
7.0-<mode> Используется набор правил, доступных для выпуска .NET 7, даже если доступны более новые правила. Значение <mode> определяет, какие правила включены.
7 Используется набор правил, доступных для выпуска .NET 7, даже если доступны более новые правила.
7-<mode> Используется набор правил, доступных для выпуска .NET 7, даже если доступны более новые правила. Значение <mode> определяет, какие правила включены.
6.0 Используется набор правил, доступных для выпуска .NET 6, даже если доступны новые правила.
6.0-<mode> Используется набор правил, доступных для выпуска .NET 6, даже если доступны новые правила. Значение <mode> определяет, какие правила включены.
6 Используется набор правил, доступных для выпуска .NET 6, даже если доступны новые правила.
6-<mode> Используется набор правил, доступных для выпуска .NET 6, даже если доступны новые правила. Значение <mode> определяет, какие правила включены.
5.0 Используется набор правил, доступных для выпуска .NET 5, даже если доступны новые правила.
5.0-<mode> Используется набор правил, доступных для выпуска .NET 5, даже если доступны новые правила. Значение <mode> определяет, какие правила включены.
5 Используется набор правил, доступных для выпуска .NET 5, даже если доступны новые правила.
5-<mode> Используется набор правил, доступных для выпуска .NET 5, даже если доступны новые правила. Значение <mode> определяет, какие правила включены.

Примечание

  • В .NET 5 и более ранних версиях это свойство влияло только на правила качества кода (CAXXXX). Начиная с .NET 6, если задать для EnforceCodeStyleInBuild значение true, это свойство будет влиять и на правила стиля кода (IDEXXXX).
  • Если для AnalysisLevel задано составное значение, указывать AnalysisMode не нужно. Иначе AnalysisLevel будет иметь приоритет над AnalysisMode.
  • Это свойство не влияет на анализ кода в проектах, которые не ссылаются на пакет SDK проекта, например, проекты на устаревших платформах .NET Framework, которые ссылаются на пакет NuGet Microsoft.CodeAnalysis.NetAnalyzers.

AnalysisLevel<Категория>

Это свойство появилось в .NET 6 и соответствует свойству AnalysisLevel, за исключением того, что оно применяется только к определенной категории правил анализа кода. Это свойство позволяет применить другую версию анализаторов кода для определенной категории, а также включать и отключать правила на другом уровне для других категорий правил. Если опустить это свойство для определенной категории правил, по умолчанию будет использоваться значение AnalysisLevel. Для этого свойства доступны такие же значения, как для AnalysisLevel.

<PropertyGroup>
  <AnalysisLevelSecurity>preview</AnalysisLevelSecurity>
</PropertyGroup>
<PropertyGroup>
  <AnalysisLevelSecurity>preview-recommended</AnalysisLevelSecurity>
</PropertyGroup>

В следующей таблице указано имя свойства для каждой категории правил.

Имя свойства Категория правил
<AnalysisLevelDesign> Правила разработки
<AnalysisLevelDocumentation> Правила документирования
<AnalysisLevelGlobalization> Правила глобализации
<AnalysisLevelInteroperability> Правила переносимости и взаимодействия
<AnalysisLevelMaintainability> Правила удобства поддержки
<AnalysisLevelNaming> Правила именования
<AnalysisLevelPerformance> Правила производительности
<AnalysisLevelSingleFile> Правила для приложений с одним файлом
<AnalysisLevelReliability> Правила надежности
<AnalysisLevelSecurity> Правила безопасности
<AnalysisLevelStyle> Правила стиля кода (IDEXXXX)
<AnalysisLevelUsage> Правила использования

AnalysisMode

Начиная с .NET 5 пакет SDK для .NET поставляется с полным набором правил качества кода "CA". По умолчанию в каждом выпуске .NET в качестве предупреждений о сборке включены только некоторые правила. Свойство AnalysisMode позволяет настроить набор правил, включенных по умолчанию. Вы можете переключиться в более агрессивный режим анализа с возможностью отказа от правил по отдельности, или более консервативный режим с возможностью выбора определенных правил. Например, если вы хотите включить все правила как предупреждения сборки, задайте значение All.

<PropertyGroup>
  <AnalysisMode>All</AnalysisMode>
</PropertyGroup>

В следующей таблице показаны доступные значения параметров в .NET 5 и более поздних версиях. Эти параметры перечислены в порядке возрастания количества правил, которые они включают.

Значение в .NET 6+ Значение в .NET 5 Значение
None AllDisabledByDefault Все правила отключены. Можно выборочно принять отдельные правила, чтобы включить их.
Default Default Режим по умолчанию, при котором определенные правила включаются в виде предупреждений сборки, некоторые правила включаются в качестве предложений интегрированной среды разработки Visual Studio, а остальные отключаются.
Minimum Н/Д Более агрессивный режим, чем Default режим. Определенные предложения, которые настоятельно рекомендуются для принудительного применения сборки, включены как предупреждения сборки. Чтобы узнать, какие правила это включает, проверьте файл %ProgramFiles%/dotnet/sdk/[версия]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_minimum.editorconfig .
Recommended Н/Д Более агрессивный режим, чем Minimum режим, в котором в качестве предупреждений сборки включается больше правил. Чтобы узнать, какие правила это включает, проверьте файл %ProgramFiles%/dotnet/sdk/[версия]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.editorconfig .
All AllEnabledByDefault Все правила включены как предупреждения сборки. Вы можете выборочно отказаться от отдельных правил, чтобы отключить их.

Примечание

  • В .NET 5 это свойство влияло только на правила качества кода (CAXXXX). Начиная с .NET 6, если задать для EnforceCodeStyleInBuild значение true, это свойство будет влиять и на правила стиля кода (IDEXXXX).
  • Если вы используете составное значение для AnalysisLevel, например <AnalysisLevel>5-recommended</AnalysisLevel>, это свойство можно опустить. Но если указать оба свойства, AnalysisLevel будет иметь приоритет над AnalysisMode.
  • Если вы присвоите AnalysisMode значение AllEnabledByDefault, а AnalysisLevel — значение 5 или 5.0, а затем установите пакет SDK для .NET 6 и выполните повторную компиляцию проекта, могут возникнуть неожиданные новые предупреждения компиляции. Дополнительные сведения см. в справочном документе dotnet/roslyn-analyzers#5679.
  • Это свойство не влияет на анализ кода в проектах, которые не ссылаются на пакет SDK проекта, например, проекты на устаревших платформах .NET Framework, которые ссылаются на пакет NuGet Microsoft.CodeAnalysis.NetAnalyzers.

AnalysisMode<Категория>

Это свойство появилось в .NET 6 и соответствует свойству AnalysisMode, за исключением того, что оно применяется только к определенной категории правил анализа кода. Это свойство позволяет включать и отключать правила на другом уровне для других категорий правил. Если опустить это свойство для определенной категории правил, по умолчанию будет использоваться значение AnalysisMode. Для этого свойства доступны такие же значения, как для AnalysisMode.

<PropertyGroup>
  <AnalysisModeSecurity>All</AnalysisModeSecurity>
</PropertyGroup>

В следующей таблице указано имя свойства для каждой категории правил.

Имя свойства Категория правил
<AnalysisModeDesign> Правила разработки
<AnalysisModeDocumentation> Правила документирования
<AnalysisModeGlobalization> Правила глобализации
<AnalysisModeInteroperability> Правила переносимости и взаимодействия
<AnalysisModeMaintainability> Правила удобства поддержки
<AnalysisModeNaming> Правила именования
<AnalysisModePerformance> Правила производительности
<AnalysisModeSingleFile> Правила для приложений с одним файлом
<AnalysisModeReliability> Правила надежности
<AnalysisModeSecurity> Правила безопасности
<AnalysisModeStyle> Правила стиля кода (IDEXXXX)
<AnalysisModeUsage> Правила использования

CodeAnalysisTreatWarningsAsErrors

Свойство CodeAnalysisTreatWarningsAsErrors позволяет настроить, следует ли обрабатывать предупреждения анализа качества кода (CAxxxx) как предупреждения и прекращать сборку. Если при построении проектов используется флаг -warnaserror, предупреждения анализа качества кода .NET также обрабатываются как ошибки. Если вы не хотите, чтобы предупреждения качества кода обрабатывались как ошибки, можно задать для свойства MSBuild CodeAnalysisTreatWarningsAsErrors значение false в файле проекта.

<PropertyGroup>
  <CodeAnalysisTreatWarningsAsErrors>false</CodeAnalysisTreatWarningsAsErrors>
</PropertyGroup>

EnableNETAnalyzers

Для проектов, предназначенных для .NET 5 или более поздней версии, по умолчанию включен анализ качества кода .NET. Если при разработке вы используете пакет SDK NET 5+, вы можете включить анализ кода .NET для проектов в стиле пакета SDK, предназначенных для более ранних версий .NET, установив для свойства EnableNETAnalyzers значение true. Чтобы отключить анализ кода в любом проекте, присвойте этому свойству значение false.

<PropertyGroup>
  <EnableNETAnalyzers>true</EnableNETAnalyzers>
</PropertyGroup>

Примечание

Это свойство применяется к встроенным анализаторам в пакете SDK для .NET 5+. Его не следует использовать при установке пакета NuGet для анализа кода.

EnforceCodeStyleInBuild

Анализ стиля кода .NET по умолчанию отключен при сборке для всех проектов .NET. Можно включить анализ стиля кода для проектов .NET, задав для свойства EnforceCodeStyleInBuild значение true.

<PropertyGroup>
  <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
</PropertyGroup>

Все правила стиля кода, которые настроены как предупреждения или ошибки, будут выполняться при нарушениях сборки и отчета.

Примечание

Если вы установите .NET 6 (или Visual Studio 2022, куда входит .NET 6), но хотите выполнять сборку проекта в Visual Studio 2019, могут выдаваться новые предупреждения CS8032, если свойству EnforceCodeStyleInBuild задано значение true. Для устранения этих предупреждений вы можете указать версию пакета SDK для .NET, которая будет использоваться для сборки проекта (в данном случае нечто подобное 5.0.404), добавив запись global.json.

_SkipUpgradeNetAnalyzersNuGetWarning

Свойство _SkipUpgradeNetAnalyzersNuGetWarning позволяет настроить выдачу предупреждений, когда используемые анализаторы кода из пакета NuGet имеют устаревшую версию по сравнению с анализаторами из последнего пакета SDK для .NET. Предупреждение выглядит примерно так:

Пакет SDK для .NET включает анализаторы с версией "6.0.0", которая новее, чем "5.0.3" из пакета "Microsoft.CodeAnalysis.NetAnalyzers". Обновите или удалите ссылку на этот пакет.

Чтобы убрать это предупреждение и продолжить использовать версию анализаторов кода из пакета NuGet, задайте для _SkipUpgradeNetAnalyzersNuGetWarning значение true в файле проекта.

<PropertyGroup>
  <_SkipUpgradeNetAnalyzersNuGetWarning>true</_SkipUpgradeNetAnalyzersNuGetWarning>
</PropertyGroup>

Свойства конфигурации среды выполнения

Вы можете настроить некоторые варианты поведения среды выполнения, указав свойства MSBuild в файле проекта приложения. Сведения о других способах настройки поведения среды выполнения см. в статье Параметры конфигурации среды выполнения.

ConcurrentGarbageCollection

Свойство ConcurrentGarbageCollection указывает, включена ли фоновая (параллельная) сборка мусора. Задайте значение false, чтобы отключить фоновую сборку мусора. Дополнительные сведения см. в разделе Сборка мусора в фоновом режиме.

<PropertyGroup>
  <ConcurrentGarbageCollection>false</ConcurrentGarbageCollection>
</PropertyGroup>

InvariantGlobalization

Свойство InvariantGlobalization определяет, выполняется ли приложение в инвариантном режиме глобализации, что означает, что у него нет доступа к данным, относящимся к языку и региональным параметрам. Установите значение true для запуска в инвариантном режиме глобализации. Дополнительные сведения см. в разделе Инвариантный режим.

<PropertyGroup>
  <InvariantGlobalization>true</InvariantGlobalization>
</PropertyGroup>

PredefinedCulturesOnly

В .NET 6 и более поздних версиях свойство PredefinedCulturesOnly определяет, могут ли приложения создавать языки и региональные параметры, отличные от инвариантных, если включен инвариантный режим глобализации. Значение по умолчанию — true. Установите значение false, чтобы разрешить создание языка и региональных параметров в инвариантном режиме глобализации.

<PropertyGroup>
  <PredefinedCulturesOnly>false</PredefinedCulturesOnly>
</PropertyGroup>

Дополнительные сведения см. в разделе Создание языка и региональных параметров и сопоставление регистра в инвариантном режиме глобализации.

RetainVMGarbageCollection

Свойство RetainVMGarbageCollection настраивает сборщик мусора для помещения удаленных сегментов памяти в список ожидания для будущего использования или освобождения. Значение true указывает сборщику мусора разместить сегменты в списке ожидания. Дополнительные сведения см. в разделе Сохранение виртуальной машины.

<PropertyGroup>
  <RetainVMGarbageCollection>true</RetainVMGarbageCollection>
</PropertyGroup>

ServerGarbageCollection

Свойство ServerGarbageCollection указывает, использует ли приложение сборку мусора рабочей станции или сборку мусора сервера. Задайте значение true, чтобы использовать сборку мусора сервера. Дополнительные сведения см. в разделе Рабочая станция и сервер.

<PropertyGroup>
  <ServerGarbageCollection>true</ServerGarbageCollection>
</PropertyGroup>

ThreadPoolMaxThreads

Свойство ThreadPoolMaxThreads указывает максимальное число потоков для пула рабочих потоков. Дополнительные сведения см. в разделе Максимальное число потоков.

<PropertyGroup>
  <ThreadPoolMaxThreads>20</ThreadPoolMaxThreads>
</PropertyGroup>

ThreadPoolMinThreads

Свойство ThreadPoolMinThreads указывает минимальное число потоков для пула рабочих потоков. Дополнительные сведения см. в разделе Минимальное число потоков.

<PropertyGroup>
  <ThreadPoolMinThreads>4</ThreadPoolMinThreads>
</PropertyGroup>

TieredCompilation

Свойство TieredCompilation указывает, использует ли JIT-компилятор многоуровневую компиляцию. Задайте значение false, чтобы отключить многоуровневую компиляцию. Дополнительные сведения см. в разделе Многоуровневая компиляция.

<PropertyGroup>
  <TieredCompilation>false</TieredCompilation>
</PropertyGroup>

TieredCompilationQuickJit

Свойство TieredCompilationQuickJit указывает, использует ли JIT-компилятор быструю JIT-компиляцию. Задайте значение false, чтобы отключить быструю JIT-компиляцию. Дополнительные сведения см. в разделе Быстрая JIT-компиляция.

<PropertyGroup>
  <TieredCompilationQuickJit>false</TieredCompilationQuickJit>
</PropertyGroup>

TieredCompilationQuickJitForLoops

Свойство TieredCompilationQuickJitForLoops указывает, использует ли JIT-компилятор быструю JIT-компиляцию для методов, содержащих циклы. Задайте значение true, чтобы включить быструю JIT-компиляцию для методов, содержащих циклы. Дополнительные сведения см. в разделе Быстрая JIT-компиляция для циклов.

<PropertyGroup>
  <TieredCompilationQuickJitForLoops>true</TieredCompilationQuickJitForLoops>
</PropertyGroup>

В этом разделе описаны следующие свойства MSBuild:

AssetTargetFallback

Свойство AssetTargetFallback позволяет указать дополнительные совместимые версии платформы для ссылок на проекты и пакетов NuGet. Например, если вы указали зависимость пакета с помощью PackageReference, но в этом пакете нет ресурсов, совместимых с TargetFramework вашего проекта, тогда пригодится свойство AssetTargetFallback. Совместимость пакета, на который указывает ссылка, повторно проверяется с помощью каждой целевой платформы, указанной в свойстве AssetTargetFallback. Это свойство заменяет устаревшее свойство PackageTargetFallback.

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

<PropertyGroup>
  <AssetTargetFallback>net461</AssetTargetFallback>
</PropertyGroup>

DisableImplicitFrameworkReferences

Свойство DisableImplicitFrameworkReferences управляет неявными элементами FrameworkReference при разработке для .NET Core 3.0 и более поздних версий. При использовании .NET Core 2.1 или .NET Standard 2.0 и более ранних версий оно управляет неявными элементами PackageReference в пакетах в метапакете. (Метапакет — это пакет на основе платформы, который состоит только из зависимостей от других пакетов.) Это свойство также управляет неявными ссылками, такими как System и System.Core, если оно предназначено для использования на платформе .NET Framework.

Присвойте этому свойству значение true, чтобы отключить неявные элементы FrameworkReference или PackageReference. Если этому свойству присвоено значение true, можно добавить явные ссылки на только необходимые платформы или пакеты.

<PropertyGroup>
  <DisableImplicitFrameworkReferences>true</DisableImplicitFrameworkReferences>
</PropertyGroup>

DisableTransitiveFrameworkReferenceDownloads

Присвойте свойству DisableTransitiveFrameworkReferenceDownloads значение , true чтобы избежать загрузки дополнительных пакетов среды выполнения и целевых пакетов, на которые не ссылается проект напрямую.

<PropertyGroup>
  <DisableTransitiveFrameworkReferenceDownloads>true</DisableTransitiveFrameworkReferenceDownloads>
</PropertyGroup>

DisableTransitiveProjectReferences

Свойство DisableTransitiveProjectReferences управляет неявными ссылками на проекты. Задайте этому свойству значение true, чтобы отключить неявные элементы ProjectReference. Отключение неявных ссылок на проекты вызовет нетранзитивное поведение, аналогичное поведению в устаревшей системе проектов.

Задание этому свойству значения true аналогично заданию PrivateAssets="All" во всех зависимостях главного проекта.

Если этому свойству задано значение true, можно добавить явные ссылки на только необходимые проекты.

<PropertyGroup>
  <DisableTransitiveProjectReferences>true</DisableTransitiveProjectReferences>
</PropertyGroup>

ManagePackageVersionsCentrally

Свойство ManagePackageVersionsCentrally появилось в .NET 7. Задав для него значение true в файле Directory.Packages.props в корне репозитория, вы можете управлять распространенными зависимостями в проектах из одного расположения. Добавьте версии для распространенных зависимостей пакетов с помощью PackageVersion элементов в файле Directory.Packages.props . Затем в отдельных файлах проекта можно опустить Version атрибуты из любых PackageReference элементов, ссылающихся на централизованно управляемые пакеты.

Пример файла Directory.Packages.props :

<PropertyGroup>
  <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
</PropertyGroup>
...
<ItemGroup>
  <PackageVersion Include="Microsoft.Extensions.Configuration" Version="7.0.0" />
</ItemGroup>

Файл отдельного проекта:

<ItemGroup>
  <PackageReference Include="Microsoft.Extensions.Configuration" />
</ItemGroup>

Дополнительные сведения см. в разделе Централизованное управление пакетами (CPM).

При восстановлении пакета, на который указывает ссылка, устанавливаются все его прямые зависимости и все зависимости этих зависимостей. Можно настроить восстановление пакетов, указав такие свойства, как RestorePackagesPath и RestoreIgnoreFailedSources. Дополнительные сведения об этих и других свойствах см. в разделе целевой объект восстановления.

<PropertyGroup>
  <RestoreIgnoreFailedSource>true</RestoreIgnoreFailedSource>
</PropertyGroup>

UseMauiEssentials

Присвойте свойству UseMauiEssentials значение , true чтобы объявить явную ссылку на проект или пакет, зависящий от MAUI Essentials. Этот параметр гарантирует, что проект извлекает правильную ссылку на известную платформу для MAUI Essentials. Если проект ссылается на проект, использующий MAUI Essentials, но вы не задали этому свойству значение true, может возникнуть предупреждение NETSDK1186сборки .

<PropertyGroup>
  <UseMauiEssentials>true</UseMauiEssentials>
</PropertyGroup>

ValidateExecutableReferencesMatchSelfContained

Свойство ValidateExecutableReferencesMatchSelfContained можно использовать для отключения ошибок, связанных с ссылками на исполняемый проект. Если .NET обнаруживает, что автономный исполняемый проект ссылается на зависящий от платформы исполняемый проект или наоборот, он создает ошибки NETSDK1150 и NETSDK1151 соответственно. Чтобы избежать этих ошибок при намеренном создании ссылки, присвойте свойству ValidateExecutableReferencesMatchSelfContained значение false.

<PropertyGroup>
  <ValidateExecutableReferencesMatchSelfContained>false</ValidateExecutableReferencesMatchSelfContained>
</PropertyGroup>

WindowsSdkPackageVersion

Свойство WindowsSdkPackageVersion можно использовать для переопределения версии пакета нацеливания Windows SDK. Это свойство было добавлено в .NET 5 и заменило элемент FrameworkReference для этой цели.

<PropertyGroup>
  <WindowsSdkPackageVersion>10.0.19041.18</WindowsSdkPackageVersion>
</PropertyGroup>

Примечание

Не рекомендуется переопределять версию Windows SDK, так как пакеты нацеливания для Windows SDK включены в пакет SDK для .NET 5+. Вместо этого для ссылки на последний пакет Windows SDK обновите версию пакета SDK для .NET. Это свойство должно использоваться только в редких случаях, например при использовании предварительных версий пакетов или при необходимости переопределения версии C#/WinRT.

Следующие свойства используются для запуска приложения с помощью команды dotnet run:

RunArguments

Свойство RunArguments определяет аргументы, которые передаются в приложение при его запуске.

<PropertyGroup>
  <RunArguments>-mode dryrun</RunArguments>
</PropertyGroup>

Совет

Можно указать дополнительные аргументы для передачи в приложение с помощью параметра -- для dotnet run.

RunWorkingDirectory

Свойство RunWorkingDirectory определяет рабочий каталог для запуска процесса приложения. Это может быть абсолютный путь или путь относительно каталога проекта. Если каталог не указан, в качестве рабочего каталога используется OutDir.

<PropertyGroup>
  <RunWorkingDirectory>c:\temp</RunWorkingDirectory>
</PropertyGroup>

В этом разделе описаны следующие свойства MSBuild:

EnableComHosting

Свойство EnableComHosting указывает, что сборка предоставляет сервер COM. Установка EnableComHosting в true также подразумевает, что EnableDynamicLoading — true.

<PropertyGroup>
  <EnableComHosting>True</EnableComHosting>
</PropertyGroup>

Дополнительные сведения см. в разделе Предоставление компонентов .NET для COM.

EnableDynamicLoading

Свойство EnableDynamicLoading указывает, что сборка является динамически загружаемым компонентом. Компонентом может быть библиотека COM или библиотека, не относящаяся к COM, которую можно использовать из собственного узла или использовать как подключаемый модуль. Если присвоить этому свойству значения true:

  • Создается файл runtimeconfig.json.
  • Параметр RollForward имеет значение LatestMinor.
  • Ссылки NuGet копируются локально.
<PropertyGroup>
  <EnableDynamicLoading>true</EnableDynamicLoading>
</PropertyGroup>

Свойства созданных файлов

Следующие свойства затрагивают код в созданных файлах:

DisableImplicitNamespaceImports

Свойство DisableImplicitNamespaceImports можно использовать для отключения неявных пространств имен в проектах Visual Basic, предназначенных для .NET 6 или более поздней версии. Неявные пространства имен — это пространства имен по умолчанию, которые импортируются глобально в проект Visual Basic. Задайте для этого свойства значение true, чтобы отключить импорт неявных пространств имен.

<PropertyGroup>
  <DisableImplicitNamespaceImports>true</DisableImplicitNamespaceImports>
</PropertyGroup>

ImplicitUsings

Свойство ImplicitUsings можно использовать для включения и отключения неявных директив global using в проектах C#, предназначенных для .NET 6 или более поздней версии, и C# 10 или более поздней версии. Если эта функция включена, пакет SDK для .NET добавляет директивы global using для набора пространств имен по умолчанию на основе типа пакета SDK для проекта. Задайте для этого свойства значение true или enable, чтобы включить неявные директивы global using. Чтобы отключить неявные директивы global using, удалите свойство или присвойте ему значение false или disable.

<PropertyGroup>
  <ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>

Примечание

В шаблонах для новых проектов C#, предназначенных для .NET 6 или более поздней версии, ImplicitUsings имеет значение enable по умолчанию.

Чтобы определить явную директиву global using, добавьте элемент Using.

Элементы

Элементы MSBuild — это входные данные для системы сборки. Элементы указываются в соответствии с их типом, который является именем элемента. Например, Compile и Reference — два распространенных типа элементов. Пакет SDK для .NET предоставляет следующие дополнительные типы элементов:

Для этих элементов можно использовать любой из стандартных атрибутов элемента, например Include и Update. Чтобы добавить новый элемент, используйте Include. Для изменения существующего элемента используйте Update. Например, Update часто используется для изменения элемента, который неявно был добавлен пакетом SDK для .NET.

AssemblyMetadata

Элемент AssemblyMetadata указывает атрибут сборки пары "ключ-значение" AssemblyMetadataAttribute. Метаданные Include становятся ключом, а метаданные Value становятся значением.

<ItemGroup>
  <AssemblyMetadata Include="Serviceable" Value="True" />
</ItemGroup>

InternalsVisibleTo

Элемент InternalsVisibleTo создает атрибут сборки InternalsVisibleToAttribute для указанной дружественной сборки.

<ItemGroup>
  <InternalsVisibleTo Include="MyProject.Tests" />
</ItemGroup>

Если дружественная сборка подписана, можно указать дополнительные метаданные Key, чтобы указать его полный открытый ключ. Если не указать метаданные Key и доступен ключ $(PublicKey), используется этот ключ. В противном случае открытый ключ не добавляется к атрибуту.

PackageReference

Элемент PackageReference определяет ссылку на пакет NuGet.

Атрибут Include указывает идентификатор пакета. Атрибут Version указывает версию или диапазон версий. Сведения о том, как указать минимальную версию, максимальную версию, диапазон или точное соответствие, см. в разделе Диапазоны версий.

Фрагмент файла проекта в следующем примере ссылается на пакет System.Runtime.

<ItemGroup>
  <PackageReference Include="System.Runtime" Version="4.3.0" />
</ItemGroup>

Также можно управлять ресурсами зависимостей с помощью таких метаданных, как PrivateAssets.

<ItemGroup>
  <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0">
    <PrivateAssets>all</PrivateAssets>
  </PackageReference>
</ItemGroup>

Дополнительные сведения см. в статье Ссылки на пакеты в файлах проекта.

TrimmerRootAssembly

Элемент TrimmerRootAssembly позволяет исключить сборку из обрезки. Обрезка — это процесс удаления неиспользуемых частей среды выполнения из упакованного приложения. В некоторых случаях при обрезке могут неправильно удаляться необходимые ссылки.

Следующий код XML исключает сборку System.Security из обрезки.

<ItemGroup>
  <TrimmerRootAssembly Include="System.Security" />
</ItemGroup>

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

Использование

Элемент Using позволяет глобально включать пространство имен в проекте C#, поэтому не нужно добавлять директиву using для пространства имен в верхней части исходных файлов. Этот элемент аналогичен элементу Import, который можно использовать для тех же целей в проектах Visual Basic. Это свойство доступно с версии .NET 6.

<ItemGroup>
  <Using Include="My.Awesome.Namespace" />
</ItemGroup>

Можно также использовать элемент Using для определения глобальных директив using <alias> и using static <type>.

<ItemGroup>
  <Using Include="My.Awesome.Namespace" Alias="Awesome" />
</ItemGroup>

Пример:

  • <Using Include="Microsoft.AspNetCore.Http.Results" Alias="Results" /> выдает global using Results = global::Microsoft.AspNetCore.Http.Results;
  • <Using Include="Microsoft.AspNetCore.Http.Results" Static="True" /> выдает global using static global::Microsoft.AspNetCore.Http.Results;

Дополнительные сведения см. в разделе Директивы с using псевдонимами и using static <type> директивы.

Метаданные элементов

Помимо стандартных атрибутов элемента MSBuild, в пакете SDK для .NET доступны следующие теги метаданных элементов:

CopyToPublishDirectory

Метаданные CopyToPublishDirectory в элементах управления MSBuild, когда элемент копируется в каталог публикации. Допустимые значения: PreserveNewest, при котором копируется только элемент, если он был изменен, Always, при котором всегда копируется элемент, и Never, при котором элемент никогда не копируется. С точки зрения производительности PreserveNewest предпочтительнее, поскольку включает инкрементную сборку.

<ItemGroup>
  <None Update="appsettings.Development.json" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
</ItemGroup>

LinkBase

Для элемента, находящегося за пределами каталога проекта и его подкаталогов, целевой объект публикации использует метаданные Link элемента, чтобы определить, куда копировать элемент. Link также определяет, как элементы за пределами дерева проекта отображаются в окне обозревателя решений Visual Studio.

Если для элемента, находящегося за пределами проекта, Link не указан, по умолчанию используется %(LinkBase)\%(RecursiveDir)%(Filename)%(Extension). LinkBase позволяет указать допустимую базовую папку для элементов за пределами проекта. Иерархия папок в базовой папке обеспечивается с помощью RecursiveDir. Если параметр LinkBase не указан, он опускается в пути Link.

<ItemGroup>
  <Content Include="..\Extras\**\*.cs" LinkBase="Shared"/>
</ItemGroup>

На следующем рисунке показано, как файл, который включен с помощью стандартной маски предыдущего элемента Include, отображается в обозревателе решений.

Обозреватель решений: элемент с метаданными LinkBase.

См. также