PackageReference в файлах проектов

Ссылки на пакеты, использующие элементы MSBuild <PackageReference>, указывают зависимости пакетов NuGet непосредственно в файлах проекта, а не в отдельных файлах packages.config. Использование PackageReference не влияет на другие аспекты NuGet. Например, параметры в файлах NuGet.Config (включая источники пакетов) по-прежнему применяются, как описано в разделе Распространенные конфигурации NuGet.

PackageReference также позволяет использовать условия MSBuild для выбора ссылок на пакеты в соответствии с целевой платформой и другими признаками. Он также обеспечивает детальный контроль над зависимостями и потоком содержимого. (Дополнительные сведения см. в разделе "Пакет NuGet" и восстановление в качестве целевых объектов MSBuild.)

Поддержка типов проектов

По умолчанию PackageReference используется для проектов .NET, проектов .NET Standard и проектов UWP, предназначенных для Windows 10 сборки 15063 (Creators Update) и более поздних версий, за исключением проектов UWP C++. Проекты .NET Framework поддерживают PackageReference, но сейчас по умолчанию используют packages.config. Чтобы использовать PackageReference в проекте .NET Framework, перенесите зависимости из packages.config файла проекта, а затем удалите packages.config.

ASP.NET приложения, предназначенные для полной платформы .NET Framework, включают только ограниченную поддержку PackageReference. Типы проектов C++и JavaScript не поддерживаются.

Добавление PackageReference

Добавьте зависимость в файл проекта, используя следующий синтаксис:

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0" />
    <!-- ... -->
</ItemGroup>

Управление версией зависимости

При указании версии пакета действует то же соглашение, что и при использовании файла packages.config.

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0" />
    <!-- ... -->
</ItemGroup>

В приведенном выше примере 3.6.0 означает любую версию, которая имеет >значение =3.6.0 с предпочтением самой низкой версии, как описано в разделе "Управление версиями пакетов".

Использование PackageReference для проекта без зависимостей пакета

Дополнительно: если в проекте нет установленных пакетов (нет объектов PackageReference в файле, а также файла packages.config), но вы хотите восстанавливать проект в стиле PackageReference, можно задать для свойства RestoreProjectStyle проекта значение PackageReference в файле проекта.

<PropertyGroup>
    <!--- ... -->
    <RestoreProjectStyle>PackageReference</RestoreProjectStyle>
    <!--- ... -->
</PropertyGroup>    

Это может быть полезно, если вы ссылаетесь на проекты, стили PackageReference (существующие проекты в стиле csproj или SDK). Это позволит вашему проекту транзитивно ссылаться на пакеты, на которые ссылаются эти проекты.

PackageReference и источники

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

Плавающие версии

Гибкие версии можно использовать с PackageReference:

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.*" />
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0-beta.*" />
    <!-- ... -->
</ItemGroup>

Управление ресурсами зависимости

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

<ItemGroup>
    <!-- ... -->

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

    <!-- ... -->
</ItemGroup>

Ниже перечислены теги метаданных, управляющие ресурсами зависимостей.

Допустимые значения для этих тегов приведены следующим образом: несколько значений, разделенных точкой с запятой, за исключением all и noneкоторые должны отображаться сами по себе:

<ItemGroup>
    <!-- ... -->
    <!-- Everything except the content files will be consumed by the project -->
    <!-- Everything except content files and analyzers will flow to the parent project-->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0">
        <IncludeAssets>all</IncludeAssets> <!-- Default is `all`, can be omitted-->
        <ExcludeAssets>contentFiles</ExcludeAssets>
        <PrivateAssets>contentFiles;analyzers</PrivateAssets>
    </PackageReference>
    <!-- ... -->
    <!-- Everything except the compile will be consumed by the project -->
    <!-- Everything except contentFiles will flow to the parent project-->
    <PackageReference Include="Contoso.Utility.SomeOtherUsefulStuff" Version="3.6.0">
        <ExcludeAssets>compile</ExcludeAssets>
        <PrivateAssets>contentFiles</PrivateAssets>
    </PackageReference>
    <!-- ... -->
</ItemGroup>

Обратите внимание: так как папка build не включена в PrivateAssets, цели и свойства будут передаваться в родительский проект. Предположим, что приведенная выше ссылка используется в проекте, в рамках которого выполняется сборка пакета NuGet с именем AppLogger. Пакет AppLogger может использовать цели и свойства из Contoso.Utility.UsefulStuff, так же как и проекты, использующие AppLogger.

Добавление условия PackageReference

Условие можно использовать для управления включением пакета. Условия могут использовать любую переменную MSBuild или переменную, определенную в целевом или props-файле. Однако в настоящее время поддерживается только TargetFramework переменная.

Например, предположим, что вы нацелены netstandard1.4 , а также net452 имеете зависимость, которая применима только для net452. В этом случае вы не хотите, netstandard1.4 чтобы проект, используюющий пакет, добавлял эту ненужную зависимость. В этом случае в узле PackageReference можно указать следующее условие:

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Newtonsoft.Json" Version="9.0.1" Condition="'$(TargetFramework)' == 'net452'" />
    <!-- ... -->
</ItemGroup>

При сборке пакета с использованием этого проекта файл Newtonsoft.Json будет отображаться как включенный только в виде зависимости для целевого объекта net452:

Результат применения условия к PackageReference в Visual Studio 2017

Условия можно также применять на уровне ItemGroup. В этом случае они применяются ко всем дочерним элементам PackageReference.

<ItemGroup Condition = "'$(TargetFramework)' == 'net452'">
    <!-- ... -->
    <PackageReference Include="Newtonsoft.Json" Version="9.0.1" />
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0" />
    <!-- ... -->
</ItemGroup>

GeneratePathProperty

Эта функция доступна в NuGet 5.0 или более поздней версии и в Visual Studio 2019 16.0 или более поздней версии.

Иногда требуется ссылаться на файлы в пакете из целевого объекта MSBuild. В проектах на основе packages.config пакеты устанавливаются в папку относительно файла проекта. Однако в PackageReference пакеты используются из папки global-packages, которая может отличаться на разных компьютерах.

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

Example:

  <ItemGroup>
      <PackageReference Include="Some.Package" Version="1.0.0" GeneratePathProperty="true" />
  </ItemGroup>

  <Target Name="TakeAction" AfterTargets="Build">
    <Exec Command="$(PkgSome_Package)\something.exe" />
  </Target>

Кроме того, NuGet автоматически создает свойства для пакетов, содержащих папку инструментов.

  <ItemGroup>
      <PackageReference Include="Package.With.Tools" Version="1.0.0" />
  </ItemGroup>

  <Target Name="TakeAction" AfterTargets="Build">
    <Exec Command="$(PkgPackage_With_Tools)\tools\tool.exe" />
  </Target>

Свойства MSBuild и удостоверения пакетов не имеют одинаковых ограничений, поэтому удостоверение пакета необходимо изменить на понятное имя MSBuild с префиксом в виде слова Pkg. Чтобы проверить точное имя создаваемого свойства, изучите созданный файл nuget.g.props.

Псевдонимы PackageReference

В некоторых редких случаях разные пакеты будут содержать классы в одном пространстве имен. Начиная с NuGet версии 5.7 и обновления 7 для Visual Studio 2019 PackageReference поддерживает Aliases, аналогично ProjectReference. По умолчанию псевдонимы не предоставляются. При указании псевдонима все сборки, поступающие из аннотированного пакета, должны ссылаться на псевдоним.

Пример использования можно просмотреть в NuGet\Samples.

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

  <ItemGroup>
    <PackageReference Include="NuGet.Versioning" Version="5.8.0" Aliases="ExampleAlias" />
  </ItemGroup>

И в коде используйте его следующим образом:

extern alias ExampleAlias;

namespace PackageReferenceAliasesExample
{
...
        {
            var version = ExampleAlias.NuGet.Versioning.NuGetVersion.Parse("5.0.0");
            Console.WriteLine($"Version : {version}");
        }
...
}

Предупреждения и ошибки NuGet

Эта функция доступна в NuGet 4.3 или более поздней версии и в Visual Studio 2017 15.3 или более поздней версии.

Для многих сценариев упаковки и восстановления все предупреждения и ошибки NuGet кодируются и начинаются с NU****. Все предупреждения и ошибки NuGet перечислены в справочной документации.

NuGet следит за следующими свойствами предупреждения:

• TreatWarningsAsErrors, обрабатывайте все предупреждения как ошибки.
• WarningsAsErrors, обрабатывайте определенные предупреждения как ошибки.
• NoWarn — скрытие определенных предупреждений в масштабе проекта или пакета.

Examples:

<PropertyGroup>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>
...
<PropertyGroup>
    <WarningsAsErrors>$(WarningsAsErrors);NU1603;NU1605</WarningsAsErrors>
</PropertyGroup>
...
<PropertyGroup>
    <NoWarn>$(NoWarn);NU5124</NoWarn>
</PropertyGroup>
...
<ItemGroup>
    <PackageReference Include="Contoso.Package" Version="1.0.0" NoWarn="NU1605" />
</ItemGroup>

Подавление предупреждений NuGet

Хотя рекомендуется разрешать все предупреждения NuGet во время выполнения операций упаковки и восстановления, в некоторых ситуациях их подавление гарантируется. Чтобы подавить предупреждение в масштабе проекта, рекомендуется сделать следующее:

<PropertyGroup>
    <PackageVersion>5.0.0</PackageVersion>
    <NoWarn>$(NoWarn);NU5104</NoWarn>
</PropertyGroup>
<ItemGroup>
    <PackageReference Include="Contoso.Package" Version="1.0.0-beta.1"/>
</ItemGroup>

Иногда предупреждения применяются только к определенному пакету в графе. Вы можете отключить это предупреждение более выборочно, добавив NoWarn элемент PackageReference.

<PropertyGroup>
    <PackageVersion>5.0.0</PackageVersion>
</PropertyGroup>
<ItemGroup>
    <PackageReference Include="Contoso.Package" Version="1.0.0-beta.1" NoWarn="NU1603" />
</ItemGroup>

Подавление предупреждений пакета NuGet в Visual Studio

В Visual Studio можно также подавить предупреждения в интегрированной среде разработки.

Блокировка зависимостей

Эта функция доступна в NuGet 4.9 или более поздней версии и в Visual Studio 2017 15.9 или более поздней версии.

Входные данные для восстановления в NuGet — это набор элементов PackageReference из файла проекта (зависимости верхнего уровня или прямые зависимости). Выходные данные — это полный набор всех зависимостей пакета, включая транзитивные зависимости. NuGet всегда пытается создать одну и ту же полную систему зависимостей пакета, если входной список PackageReference не был изменен. Но в некоторых случаях это нельзя осуществить. Рассмотрим пример.

• При использовании гибких версий, таких как <PackageReference Include="My.Sample.Lib" Version="4.*"/>. При каждом восстановлении пакетов предполагается перейти к последней версии. Но иногда пользователям требуется, чтобы граф был закреплен за определенной последней версией, а переход к более поздней версии, если она доступна, происходил при явном указании.

• Опубликована более новая версия пакета PackageReference, которая соответствует требованиям к версии. Рассмотрим пример.

  • День 1. Если вы указали <PackageReference Include="My.Sample.Lib" Version="4.0.0"/> , но версии, доступные в репозиториях NuGet, были 4.1.0, 4.2.0 и 4.3.0. В этом случае NuGet будет разрешено до версии 4.1.0 (ближайшей минимальной версии).

  • День 2. Публикуется версия 4.0.0. Теперь NuGet найдет точное совпадение и начнет разрешение до 4.0.0.

• Указанная версия пакета будет удалена из репозитория. Хотя на сайте nuget.org нельзя удалять пакеты, не все репозитории пакетов имеют такие ограничения. В результате этого в NuGet выполняется поиск наиболее соответствующей версии, если не удается разрешить удаленную версию.

Включение функции файла блокировки

Чтобы сохранить полное закрытие зависимостей пакета, вы можете отказаться от функции файла блокировки, задав свойство RestorePackagesWithLockFile MSBuild для проекта:

<PropertyGroup>
    <!--- ... -->
    <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
    <!--- ... -->
</PropertyGroup>    

Если это свойство задано, восстановление NuGet создаст файл блокировки (packages.lock.json) в корневом каталоге проекта, который перечисляет все зависимости пакета.

Поведение restore при использовании файла блокировки

Если файл блокировки присутствует для проекта, NuGet использует этот файл блокировки для запуска restore. NuGet выполняет быструю проверку, чтобы узнать, были ли изменения в зависимостях пакета, как упоминалось в файле проекта (или зависимых файлах проектов), и если изменения не были, он просто восстанавливает пакеты, упомянутые в файле блокировки. Повторная проверка зависимостей пакета не выполняется.

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

В сценариях CI/CD и других сценариях, не требующих изменения зависимостей пакета во время выполнения, это можно сделать, задав для lockedmode значение true:

Для dotnet.exe выполните следующую команду:

> dotnet.exe restore --locked-mode

Для msbuild.exe выполните такую команду:

> msbuild.exe -t:restore -p:RestoreLockedMode=true

Вы также можете задать это условное свойство MSBuild в файле проекта:

<PropertyGroup>
    <!--- ... -->
    <RestoreLockedMode>true</RestoreLockedMode>
    <!--- ... -->
</PropertyGroup> 

Если для режима блокировки задано значение true, восстановятся именно те пакеты, которые перечислены в файле блокировки. Либо восстановление завершится ошибкой, если вы обновили определенные зависимости пакетов для проекта после создания файла блокировки.

Блокировка файлов и PrunePackageReference

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

Добавление файла блокировки в исходный репозиторий

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

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

Example:

ProjectA
  |------> PackageX 2.0.0
  |------> ProjectB
             |------>PackageX 1.0.0

Если ProjectA зависит от PackageX версии 2.0.0 и ссылается на проект ProjectB, который зависит от PackageX версии 1.0.0, файл блокировки для ProjectB будет содержать зависимость от PackageX версии 1.0.0. Но при создании проекта ProjectA его файл блокировки будет содержать зависимость от PackageX версии 2.0.0, а не1.0.0, как указано в файле блокировки для ProjectB. Таким образом, файл блокировки проекта общего кода играет незначительную роль для разрешенных пакетов, от которых зависят проекты.

Расширяемость файла блокировки

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

Сопоставитель зависимостей NuGet

Сопоставитель зависимостей NuGet следует четырем правилам, как описано в документе разрешения зависимостей.

Чтобы повысить производительность и масштабируемость операции восстановления, алгоритм восстановления был перезаписан в выпуске 6.12. По состоянию на выпуск 6.12 новый алгоритм восстановления включен по умолчанию для всех проектов PackageReference. Хотя новый алгоритм восстановления функционально эквивалентен предыдущему, как и в любом программном обеспечении, возможны ошибки. Чтобы вернуться к предыдущей реализации, задайте для свойства RestoreUseLegacyDependencyResolver MSBuild значение true.

Если вы столкнулись с ошибками восстановления в версии 6.12, .NET 9 или 17.12, которые не воспроизводились в более ранних версиях, отправьте сообщение о проблеме на сайте GitHub. Любые различия между старыми и новыми алгоритмами могут иметь различные последствия, например во время компиляции или во время выполнения. Есть также вероятность того, что изменения не приводят к сбоям, но восстановление различных версий пакетов. Если вы считаете, что вы можете повлиять на любые изменения, ниже приведены шаги, которые можно предпринять, чтобы проверить, являются ли изменения в алгоритме восстановления NuGet первопричиной.

Восстановление записывает результаты в MSBuildProjectExtensionsPath каталог, который можно сравнить с новыми и старыми алгоритмами для поиска различий. Обычно это obj папка сборки. Вы можете использовать msbuild.exe или dotnet.exe выполнить следующие действия.

1. Удалите папку obj для проекта.

2. Выполнить msbuild -t:restore

3. Сохраните содержимое obj расположения, указывающее, что это new поведение.

4. Выполните msbuild -t:restore -p:RestoreUseLegacyDependencyResolver="true".

5. Сохраните содержимое obj расположения, указывающее, что это new поведение.

6. Сравните файлы в двух каталогах, особенно project.assets.json.

   Средства, которые могут выделить различия, особенно полезны для этого (например, в Visual Studio Code, откройте оба файла и используйте правой кнопкой мыши пункт "Выбрать для сравнения" и "сравнить с выбранным").

При выполнении приведенного выше метода должно быть ровно 1 разность между файлами project.assets.json :

      "projectStyle": "PackageReference",
+     "restoreUseLegacyDependencyResolver": true,
      "fallbackFolders": [

Если есть дополнительные различия, отправьте проблему на GitHub со всеми сведениями.

AssetTargetFallback

Свойство AssetTargetFallback позволяет указать дополнительные совместимые версии платформы для проектов, на которые ссылается ваш проект, и пакеты NuGet, используемые в проекте.

Если вы указали зависимость пакета с помощью PackageReference, но в этом пакете нет ресурсов, совместимых с целевой платформой вашего проекта, тогда пригодится свойство AssetTargetFallback. Совместимость пакета, на который указывает ссылка, повторно проверяется с помощью каждой целевой платформы, указанной в свойстве AssetTargetFallback. При обращении к project или package через AssetTargetFallback вызывается предупреждение NU1701.

Примеры того, как AssetTargetFallback влияет на совместимость, приводятся в следующей таблице.

Чтобы указать несколько платформ, можно использовать разделитель ;. Чтобы добавить резервную платформу, можно выполнить следующие действия:

<AssetTargetFallback Condition=" '$(TargetFramework)'=='netcoreapp3.1' ">
    $(AssetTargetFallback);net472;net471
</AssetTargetFallback>

Оставьте $(AssetTargetFallback), если требуется перезаписать вместо добавления к существующим значениям AssetTargetFallback.

PrunePackageReference

Среда выполнения .NET постоянно развивается: с каждым релизом она получает улучшения производительности и новые API. Новые функции, добавленные в .NET, также иногда предоставляются в виде пакетов, чтобы разработчики, использующие старые целевые платформы, могли использовать библиотеку, например System.Text.Json. Это часто может привести к System.Text.Json 8.0.0 в проекте, нацеленном на .NET 9 или .NET 8. Эта зависимость не требуется, и разрешение конфликтов сборки не будет использовать сборку, полученную из пакета, так как она уже доступна в среде выполнения .NET. Начиная с NuGet версии 6.13 и пакета SDK для .NET 9.0.200, PrunePackageReference позволяет выполнять очистку этих пакетов во время восстановления для проектов на основе пакета SDK для .NET. Первая итерация обрезки затрагивала только транзитивные пакеты, но начиная с .NET SDK 10, обрезка пакетов затрагивает также прямые пакеты.

Обрезка пакетов доступна в качестве функции согласия с пакетом SDK для .NET 9 и включена по умолчанию для всех платформ проекта, предназначенного >= .NET 10.0 для пакета SDK для .NET 10.

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

Спецификация PrunePackageReference

Список пакетов, подлежащих удалению, определяется пунктом PrunePackageReference.

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

.NET SDK заранее определяет, какие пакеты следует удалить за вас.

Как работает PrunePackageReference

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

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

Для прямых пакетов PrivateAssets='all' и IncludeAssets='none' неявно применяются.

• IncludeAssets='none' гарантирует, что сборки из этого пакета не используются во время сборки. До появления процесса сокращения, разрешение конфликтов во время сборки обеспечивало, что сборки платформы предпочитались перед теми, которые поступали из пакетов.
• PrivateAssets='all' гарантирует, что пакеты не включаются в сборки или через ссылки на проекты.

Example:

Проект, как показано ниже:

  <PropertyGroup>
    <TargetFrameworks>net9.0;netstandard2.0</TargetFrameworks>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="System.Text.Json" Version="9.0.4" />
  </ItemGroup>

будет иметь nuspec со следующими зависимостями:

<dependencies>
    <group targetFramework=".NETFramework4.7.2">
        <dependency id="System.Text.Json" version="9.0.4" />
    </group>
    <group targetFramework="net9.0">
    </group>
</dependencies>

Если прямая функция PackageReference может быть полностью удалена из проекта, а одна из платформ проектов — .NET 10 или более поздней версии, nu1510 будет вызвана запросом на удаление пакета. После этого предложения будет снижена сложность графа проекта.

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

Приложения PrunePackageReference

Преимущества обрезки пакета двоякие:

• Преимущества производительности благодаря сокращению количества пакетов в графе зависимостей
• Уменьшение ложноположительных срабатываний сканерами компонентов, такими как NuGetAudit

Обрезка особенно важна при аудите пакетов с заданным NuGetAuditMode значением all. Если вы используете .NET 9, рекомендуется попробовать обрезку, установив для этого значение RestoreEnablePackagePruningtrue.