Распространенные конфигурации NuGet

  • Статья

Поведение NuGet зависит от накопленных параметров в одном или нескольких NuGet.Config XML-файлах, которые могут существовать в решении (проект, если решение не используется), уровней пользователя и компьютера. Кроме того, используется глобальный файл NuGetDefaults.Config, определяющий конфигурацию источников пакетов. Параметры применяются ко всем командам, выполняемым в интерфейсе командной строки, консоли диспетчера пакетов и пользовательском интерфейсе диспетчера пакетов.

Расположение и использование файла конфигурации

Область Расположение файла NuGet.Config Описание
Решение Текущая папка (т. е. папка решения) или любая другая папка вплоть до уровня корня диска. Параметры папки решения применяются ко всем проектам во вложенных папках. Обратите внимание, что если файл конфигурации помещен в папку проекта, он никоим образом не влияет на проект. При восстановлении проекта в командной строке каталог проекта рассматривается как каталог решения, что может привести к различиям в поведении при восстановлении проекта и решения.
User Windows:%appdata%\NuGet\NuGet.Config
Mac/Linux:~/.config/NuGet/NuGet.Config или ~/.nuget/NuGet/NuGet.Config (зависит от инструментов)
Дополнительные конфигурации поддерживаются на всех платформах. Эти конфигурации нельзя изменить с помощью инструментов.
Windows:%appdata%\NuGet\config\*.Config
Mac/Linux:~/.config/NuGet/config/*.config или ~/.nuget/config/*.config		 Параметры применяться ко всем операциям, но переопределяются всеми параметрами уровня решения.
Компьютер Windows:%ProgramFiles(x86)%\NuGet\Config
Mac/Linux:/etc/opt/NuGet/Config (Linux) или /Library/Application Support (Mac) по умолчанию. Если $NUGET_COMMON_APPLICATION_DATA значение не является пустым или пустым, $NUGET_COMMON_APPLICATION_DATA/NuGet/Config вместо этого		 Параметры применяться ко всем операциям на компьютере, но переопределяются любыми параметрами уровня пользователя или решения.

Примечание.

В Mac/Linux расположение файла конфигурации пользователя зависит от инструментов. В .NET CLI используется ~/.nuget/NuGet папка, а в Mono используется ~/.config/NuGet папка.

В Mac/Linux расположение файла конфигурации на уровне пользователя зависит от инструментов

В Mac/Linux расположение файла конфигурации пользователя зависит от инструментов. Большинство пользователей используют средства, которые ищут файл конфигурации пользователя в папке ~/.nuget/NuGet . Эти другие средства ищут файл конфигурации пользователя в папке ~/.config/NuGet :

  • Mono
  • NuGet.exe
  • Visual Studio 2019 для Mac (и более ранних версий)
  • Visual Studio 2022 для Mac (и более поздних версий) только при работе с классическими проектами Mono.

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

  1. Проверьте содержимое двух файлов конфигурации уровня пользователя и сохраните нужный файл в ~/.nuget/NuGet папке.
  2. Задайте символьную ссылку ~/.config/NuGetиз ~/.nuget/NuGet . Например, выполните команду bash: ln -s ~/.nuget/NuGet ~/.config/NuGet

Примечания для более ранних версий NuGet:

  • В NuGet 3.3 и более ранних версий параметры уровня решения располагались в папке .nuget. В NuGet версии 3.4 и более поздних эта папка не используется.
  • В NuGet версий 2.6–3.x файл конфигурации на уровне компьютера в Windows был расположен в папке %ProgramData%\NuGet\Config[\{IDE}[\{Version}[\{SKU}]]]\NuGet.Config, где у {IDE} может быть значение VisualStudio, {Version} — версия Visual Studio, например 14.0, а {SKU} — Community, Pro или Enterprise. Чтобы перенести параметры в NuGet версии 4.0 или более поздней, просто скопируйте файл конфигурации в папку %ProgramFiles(x86)%\NuGet\Config. На Linux использовалось расположение /etc/opt, а на Mac — /Library/Application Support.

Изменение параметров конфигурации

Файл NuGet.Config представляет собой простой текстовый файл в формате XML, который содержит пары ключей и значений, описываемые в разделе Параметры конфигурации NuGet.

Управление параметрами осуществляется с помощью команды config command интерфейса командной строки NuGet:

  • По умолчанию изменения вносятся в файл конфигурации уровня пользователя. (В Mac/Linux расположение файла конфигурации уровня пользователя зависит от инструментов)
  • Для изменения параметров в другом файле используйте параметр -configFile. В таком случае файлы могут иметь любые имена.
  • Ключи всегда задаются с учетом регистра символов.
  • Для изменения параметров в файле уровня компьютера требуется повышение прав.

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

Файл конфигурации можно изменять в любом редакторе, однако если он будет содержать неправильно сформированный код XML (несоответствующие теги, неправильно используемые кавычки и т. д.), NuGet (версии 3.4.3 и более поздней) будет полностью игнорировать его без выдачи каких-либо уведомлений. Поэтому для управления параметрами рекомендуется использовать команду nuget config.

Настройка значения

Windows:

# Set repositoryPath in the user-level config file
nuget config -set repositoryPath=c:\packages 

# Set repositoryPath in solution-level files
nuget config -set repositoryPath=c:\packages -configfile c:\my.Config
nuget config -set repositoryPath=c:\packages -configfile .\myApp\NuGet.Config

# Set repositoryPath in the computer-level file (requires elevation)
nuget config -set repositoryPath=c:\packages -configfile %ProgramFiles(x86)%\NuGet\Config\NuGet.Config

Mac/Linux:

# Set repositoryPath in the user-level config file
nuget config -set repositoryPath=/home/packages 

# Set repositoryPath in solution-level files
nuget config -set repositoryPath=/home/projects/packages -configfile /home/my.Config
nuget config -set repositoryPath=/home/packages -configfile home/myApp/NuGet.Config

# Set repositoryPath in the computer-level file (requires elevation)
nuget config -set repositoryPath=/home/packages -configfile $XDG_DATA_HOME/NuGet.Config

Примечание.

В NuGet 3.4 и более поздних версий можно использовать в любом значении переменные среды, такие как repositoryPath=%PACKAGEHOME% (Windows) и repositoryPath=$PACKAGEHOME (Mac/Linux).

Удаление значения

Чтобы удалить значение, укажите ключ с пустым значением.

# Windows
nuget config -set repositoryPath= -configfile c:\my.Config

# Mac/Linux
nuget config -set repositoryPath= -configfile /home/my.Config

Создание нового файла конфигурации

Скопируйте представленный ниже шаблон в новый файл и затем присвойте значения с помощью nuget config -configFile <filename>:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
</configuration>

Порядок применения параметров

Несколько NuGet.Config файлов позволяют хранить параметры в разных расположениях, чтобы они применялись к одному решению или группе решений. Эти параметры совместно применяются к любой операции NuGet, вызываемой из командной строки или из Visual Studio, с параметрами, которые существуют "ближайшим" к решению или текущей папке с приоритетом. Если средство командной строки используется в файле проекта, а не в файле решения, каталог проекта используется в качестве каталога решения, что может привести к несогласованности поведения при наличии NuGet.Config файла в подкаталоге файла решения.

В частности, NuGet загружает параметры из различных файлов конфигурации в следующем порядке:

  1. Файл NuGetDefaults.Config, который содержит параметры, относящиеся только к источникам пакетов.
  2. Файл уровня компьютера.
  3. Файл уровня пользователя.
  4. Файл, заданный параметром -configFile.
  5. Файлы, найденные в каждой папке в пути от корневого диска к текущей папке (где nuget.exe вызывается или папка, содержащая решение Visual Studio). Например, если команда вызывается в c:\A\B\C, NuGet ищет и загружает файлы конфигурации в c:\, затем в c:\A, в c:\A\B и, наконец, в c:\A\B\C.

Параметры, найденные в этих файлах, NuGet применяет следующим образом:

  1. Для элементов, состоящих из одного компонента, NuGet заменяет любое ранее найденное значение с тем же ключом. Это означает, что параметры, которые являются ближайшими к текущей папке или решению, переопределяют любые другие найденные ранее параметры. Например, параметр defaultPushSource в файле NuGetDefaults.Config будет переопределен аналогичным параметром, найденным в любом другом файле конфигурации.
  2. Для элементов коллекции (таких как <packageSources>) NuGet объединяет значения из всех файлов конфигурации в одну коллекцию.
  3. Если для заданного узла указан параметр <clear />, NuGet игнорирует ранее определенные значения конфигурации для этого узла.

Совет

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

Пошаговое руководство по параметрам

Допустим, у вас есть следующая структура папок на двух отдельных дисках:

disk_drive_1
    User
disk_drive_2
    Project1
        Source
    Project2
        Source
    tmp

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

Файл А. Файл на уровне пользователей (%appdata%\NuGet\NuGet.Config в Windows, ~/.config/NuGet/NuGet.Config в Mac и Linux):

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <activePackageSource>
        <add key="NuGet official package source" value="https://api.nuget.org/v3/index.json" />
    </activePackageSource>
</configuration>

Файл Б. disk_drive_2/NuGet.Config:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <config>
        <add key="repositoryPath" value="disk_drive_2/tmp" />
    </config>
    <packageRestore>
        <add key="enabled" value="True" />
    </packageRestore>
</configuration>

Файл В. disk_drive_2/Project1/NuGet.Config:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <config>
        <add key="repositoryPath" value="External/Packages" />
        <add key="defaultPushSource" value="https://MyPrivateRepo/ES/api/v2/package" />
    </config>
    <packageSources>
        <clear /> <!-- ensure only the sources defined below are used -->
        <add key="MyPrivateRepo - ES" value="https://MyPrivateRepo/ES/nuget" />
    </packageSources>
</configuration>

Файл Г. disk_drive_2/Project2/NuGet.Config:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <packageSources>
        <!-- Add this repository to the list of available repositories -->
        <add key="MyPrivateRepo - DQ" value="https://MyPrivateRepo/DQ/nuget" />
    </packageSources>
</configuration>

Затем NuGet загружает и применяет параметры следующим образом, в зависимости от места вызова:

  • Вызов из disk_drive_1/users. Используется только репозиторий по умолчанию, представленный в файле конфигурации уровня пользователя (А), так как это единственный файл, найденный по пути disk_drive_1.

  • Вызов из disk_drive_2/ или disk_drive_/tmp. Сначала загружается файл уровня пользователя (А), а затем NuGet переходит в корень disk_drive_2 и находит файл (Б). Кроме того, NuGet также ищет файл конфигурации в папке /tmp, но не находит его. В результате используется репозиторий по умолчанию на веб-сайте nuget.org, включается восстановление пакетов и пакеты развертываются в папке disk_drive_2/tmp.

  • Вызов из disk_drive_2/Project1 или disk_drive_2/Project1/Source. Сначала загружается файл уровня пользователя (А), затем NuGet загружает файл (Б) из корня disk_drive_2, после чего загружается файл (В). Настройки в (В) переопределяют настройки в (Б) и (A), поэтому путем repositoryPath, по которому устанавливаются пакеты, будет disk_drive_2/Project1/External/Packages, а не disk_drive_2/tmp. Кроме того, поскольку файл (В) очищает <packageSources>, веб-сайт nuget.org будет недоступен в качестве источника, и останется только https://MyPrivateRepo/ES/nuget.

  • Вызов из disk_drive_2/Project2 или disk_drive_2/Project2/Source. Сначала загружается файл уровня пользователя (А), а затем файл (Б) и файл (Г). Поскольку packageSources не очищается, в качестве источников будут доступны одновременно nuget.org и https://MyPrivateRepo/DQ/nuget. Пакеты развертываются по пути disk_drive_2/tmp, заданному в файле (Б).

Дополнительная конфигурация на уровне пользователя

Начиная с версии 5.7 в NuGet появилась поддержка дополнительных файлов конфигурации на уровне пользователя. Это позволяет сторонним поставщикам добавлять дополнительные пользовательские файлы конфигурации без повышения прав. Эти файлы конфигурации находятся в стандартной пользовательской папке конфигурации в подпапке config. Будут учитываться все файлы, которые имеют расширение .config или .Config. Эти файлы нельзя изменить стандартными инструментами.

Платформа ОС Дополнительные конфигурации
Windows %appdata%\NuGet\config\*.Config
Mac/Linux ~/.config/NuGet/config/*.config или ~/.nuget/config/*.config

Файл параметров по умолчанию NuGet

Файл NuGetDefaults.Config задает источники пакетов, из которых устанавливаются и обновляются пакеты, а также определяет целевой объект по умолчанию для публикации пакетов с использованием команды nuget push. Так как администраторы могут без усилий согласованно развертывать файлы NuGetDefaults.Config на компьютерах разработки и построения (например, с использованием групповой политики), они могут гарантировать то, что все пользователи организации будут иметь правильные источники пакетов вместо веб-сайта nuget.org.

Внимание

Файл NuGetDefaults.Config никогда не вызывает удаление источника пакетов из конфигурации NuGet разработчика. Это означает, что если разработчик уже использовал NuGet и для него зарегистрирован источник пакетов nuget.org, он не будет использован после создания файла NuGetDefaults.Config.

Кроме того, ни ни какой-либо NuGetDefaults.Config другой механизм в NuGet не может запретить доступ к источникам пакетов, таким как nuget.org. Если организация хочет заблокировать такой доступ, она должна использовать другие средства, такие как брандмауэры для этого.

Расположение NuGetDefaults.Config

В следующей таблице указано, где следует хранить файл NuGetDefaults.Config в зависимости от целевой ОС.

Платформа ОС NuGetDefaults.Config Местоположение
Windows Visual Studio 2017 или NuGet 4.x+:%ProgramFiles(x86)%\NuGet
Visual Studio 2015 или более ранней версии либо NuGet 3.x или более ранней версии:%PROGRAMDATA%\NuGet
Mac/Linux $XDG_DATA_HOME (обычно ~/.local/share или /usr/local/share, в зависимости от дистрибутива ОС)

Параметры в файле NuGetDefaults.Config

  • packageSources. Эта коллекция имеет то же значение, что и packageSources в обычных файлах конфигурации и задает источники по умолчанию. NuGet использует эти источники в указанном порядке при установке или обновлении пакетов в проектах с помощью формата управления packages.config. Для проектов, в которых используется формат PackageReference, NuGet сначала использует локальные источники, затем — источники в сетевых папках, а после этого — HTTP-источники, независимо от порядка, заданного в файлах конфигурации. NuGet всегда игнорирует порядок источников при операциях восстановления.

  • disabledPackageSources. Эта коллекция имеет то же значение, что и в файлах NuGet.Config, где каждый затрагиваемый источник перечислен по имени и значению true/false, указывающему, включен он или отключен. Это позволяет сохранять имя и URL-адрес источника в packageSources, не включая его по умолчанию. Отдельные разработчики при необходимости могут повторно включить источник, присвоив параметру источника значение false в других файлах NuGet.Config, не выполняя повторный поиск правильного URL-адреса. Также рекомендуется предоставить разработчикам полный список URL-адресов внутренних источников для организации, но включить по умолчанию только источник для отдельной группы.

  • defaultPushSource задает целевой объект по умолчанию для операций nuget push, переопределяя встроенное значение по умолчанию nuget.org. Администраторы могут развертывать этот параметр, чтобы избежать случайной публикации внутренних пакетов на открытом веб-сайте nuget.org, поскольку разработчикам придется специально использовать команду nuget push -Source для публикации на веб-сайте nuget.org.

Пример файла NuGetDefaults.Config и приложения

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <!-- defaultPushSource key works like the 'defaultPushSource' key of NuGet.Config files. -->
    <!-- This can be used by administrators to prevent accidental publishing of packages to nuget.org. -->
    <config>
        <add key="defaultPushSource" value="https://contoso.com/packages/" />
    </config>

    <!-- Default Package Sources; works like the 'packageSources' section of NuGet.Config files. -->
    <!-- This collection cannot be deleted or modified but can be disabled/enabled by users. -->
    <packageSources>
        <add key="Contoso Package Source" value="https://contoso.com/packages/" />
        <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    </packageSources>

    <!-- Default Package Sources that are disabled by default. -->
    <!-- Works like the 'disabledPackageSources' section of NuGet.Config files. -->
    <!-- Sources cannot be modified or deleted either but can be enabled/disabled by users. -->
    <disabledPackageSources>
        <add key="nuget.org" value="true" />
    </disabledPackageSources>
</configuration>