Справочник по 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>

В этом разделе описаны следующие свойства 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.

GenerateRuntimeConfigurationFiles

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

<PropertyGroup>
  <GenerateRuntimeConfigurationFiles>true</GenerateRuntimeConfigurationFiles>
</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.

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</SatelliteResourceLanguages>
</PropertyGroup>

Примечание

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

UseAppHost

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

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

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

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

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

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

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.

DocumentationFile

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

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

<PropertyGroup>
  <DocumentationFile>path/to/file.xml</DocumentationFile>
</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>

DefaultExcludesInProjectFolder

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

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

<PropertyGroup>
  <DefaultExcludesInProjectFolder>$(DefaultExcludesInProjectFolder);**/myprefix*/**</DefaultExcludesInProjectFolder>
</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 6 и хотите оставить стандартный набор правил анализа кода без изменений, задайте для AnalysisLevel значение 5.

<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> определяет, какие правила включены.
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<Category>

Это свойство появилось в .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 6+ Значение в .NET 5 Значение
None AllDisabledByDefault Все правила отключены. Можно выборочно принять отдельные правила, чтобы включить их.
Default Default Режим по умолчанию, при котором определенные правила включаются в виде предупреждений сборки, некоторые правила включаются в качестве предложений интегрированной среды разработки Visual Studio, а остальные отключаются.
Minimum Н/Д Более агрессивный режим, чем Default. Определенные предложения, которые настоятельно рекомендуются для принудительного применения сборки, включены как предупреждения сборки.
Recommended Н/Д Более агрессивный режим, чем Minimum. В этот режиме больше правил включено как предупреждения сборки.
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<Category>

Это свойство появилось в .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>

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

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

Вы можете настроить некоторые варианты поведения среды выполнения, указав свойства 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>

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

<PropertyGroup>
  <RestoreIgnoreFailedSource>true</RestoreIgnoreFailedSource>
</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> с псевдонимами см. в разделе директива using.

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

Помимо стандартных атрибутов элемента 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.

См. также