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

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

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

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

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

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

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

1. Проверьте содержимое двух файлов конфигурации уровня пользователя и сохраните нужный файл в ~/.nuget/NuGet папке.
2. Установите символьную ссылку от ~/.nuget/NuGet к ~/.config/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 ".

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

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

Установка значения

Виндоус:

# 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

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

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

# 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 загружает параметры из разных файлов конфигурации в следующем порядке:

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

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

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

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

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

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

disk_drive_1
    User
disk_drive_2
    Project1
        Source
    Project2
        Source
    tmp

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

Файл A. Файл уровня пользователя (%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>

Файл B. 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>

Файл C. 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>

Файл D. 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: используется только репозиторий по умолчанию, указанный в файле конфигурации уровня пользователя (A), так как это единственный файл, найденный в disk_drive_1.

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

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

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

Дополнительная конфигурация, общая для всех пользователей

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

Файл NuGet по умолчанию

Редко используемый NuGetDefaults.Config может только указывать источники пакетов, из которых устанавливаются и обновляются пакеты, или управлять целевым объектом по умолчанию для публикации пакетов с помощью nuget push.

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

NuGetDefaults.Config местоположение

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

Параметры конфигурации 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>