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

Статья
07/17/2024

Поведение NuGet зависит от накопленных параметров в одном или нескольких ФАЙЛАх конфигурации (XML), которые могут существовать в решении ( проект, если решение не используется), уровней пользователей и компьютеров.

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

Область	Расположение файла `NuGet.Config`	Описание
Решение	Текущая папка (т. е. папка решения) или любая другая папка вплоть до уровня корня диска.	Параметры папки решения применяются ко всем проектам во вложенных папках. Обратите внимание, что если файл конфигурации помещен в папку проекта, он никоим образом не влияет на проект. При восстановлении проекта в командной строке каталог проекта рассматривается как каталог решения, что может привести к различиям в поведении при восстановлении проекта и решения.
User	Windows: `%appdata%\NuGet\NuGet.Config` Mac/Linux: `~/.config/NuGet/NuGet.Config` или `~/.nuget/NuGet/NuGet.Config` (зависит от инструментов) Дополнительные конфигурации поддерживаются на всех платформах. Эти конфигурации нельзя изменить с помощью инструментов. Виндоус: `%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.

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

Проверьте содержимое двух файлов конфигурации уровня пользователя и сохраните нужный файл в ~/.nuget/NuGet папке.
Задайте символьную ссылку ~/.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 globalPackagesFolder in the user-level config file
dotnet nuget config set globalPackagesFolder "C:\packages"

# Set repositoryPath (available for packages.config only) in the user-level config file
dotnet nuget config set repositoryPath "C:\packages"

# Set repositoryPath in solution-level files
dotnet nuget config set repositoryPath "C:\packages" --configfile "C:\my.config"
dotnet nuget config set repositoryPath "c:\packages" --configfile "..\..\my.config"

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

Mac/Linux:

# Set globalPackagesFolder in the user-level config file
dotnet nuget config set globalPackagesFolder /home/packages

# Set repositoryPath (available for packages.config only) in the user-level config file
dotnet nuget config set repositoryPath /home/packages

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

# Set repositoryPath in the computer-level file (requires elevation)
dotnet 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

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

С помощью .NET CLI создайте конфигурацию nuget.config по умолчанию, выполнив команду dotnet new nugetconfig. Дополнительные сведения см. в командах dotnet CLI.

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

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

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

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

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

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

Если файл конфигурации явно указан в командной строке, например nuget -configFile my.config или dotnet restore --configfile my.configтолько параметры из указанного файла будут использоваться.

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

Для элементов, состоящих из одного компонента, NuGet заменяет любое ранее найденное значение с тем же ключом. Это означает, что параметры, которые являются ближайшими к текущей папке или решению, переопределяют любые другие найденные ранее параметры. Например, параметр defaultPushSource в файле NuGetDefaults.Config будет переопределен аналогичным параметром, найденным в любом другом файле конфигурации.
Для элементов коллекции (таких как <packageSources>) NuGet объединяет значения из всех файлов конфигурации в одну коллекцию.
Если для заданного узла указан параметр <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>
  <packageSources>
    <add key="nuget" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
</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>

Поделиться через

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Обратная связь

Дополнительные ресурсы

Поделиться через

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Обратная связь

Дополнительные ресурсы

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