Udostępnij za pomocą

Typowe konfiguracje narzędzia NuGet

Zachowanie NuGet jest sterowane przez skumulowane ustawienia w co najmniej jednym pliku konfiguracyjnym (XML), które mogą istnieć na poziomach rozwiązania (lub projektu, jeśli rozwiązanie nie jest używane), użytkownika i komputera.

Konfigurowanie lokalizacji plików i zastosowań

Scope NuGet.Config lokalizacja pliku Description
Rozwiązanie Bieżący folder (znany również jako folder rozwiązania) lub dowolny folder, aż do katalogu głównego dysku. W folderze rozwiązania ustawienia mają zastosowanie do wszystkich projektów w podfolderach. Należy pamiętać, że jeśli plik konfiguracji zostanie umieszczony w folderze projektu, nie ma wpływu na ten projekt. Podczas przywracania projektu w wierszu polecenia katalog projektu jest traktowany jako katalog rozwiązania, co może prowadzić do różnic w zachowaniu podczas przywracania projektu a rozwiązaniem.
User Windows:%appdata%\NuGet\NuGet.Config
Mac/Linux:~/.config/NuGet/NuGet.Config lub ~/.nuget/NuGet/NuGet.Config (różni się w zależności od narzędzi)
Dodatkowe konfiguracje są obsługiwane na wszystkich platformach. Tych konfiguracji nie można edytować za pomocą narzędzi.
Windows:%appdata%\NuGet\config\*.Config
Mac/Linux:~/.config/NuGet/config/*.config lub ~/.nuget/config/*.config		 Ustawienia mają zastosowanie do wszystkich operacji, ale są zastępowane przez dowolne ustawienia na poziomie rozwiązania.
Komputer Windows:%ProgramFiles(x86)%\NuGet\Config
Mac/Linux:/etc/opt/NuGet/Config (Linux) lub /Library/Application Support (Mac) domyślnie. Jeśli $NUGET_COMMON_APPLICATION_DATA nie jest wartością null ani nie jest pusta, $NUGET_COMMON_APPLICATION_DATA/NuGet/Config w przeciwnym razie		 Ustawienia mają zastosowanie do wszystkich operacji na komputerze, ale są zastępowane przez ustawienia na poziomie użytkownika lub rozwiązania.

Uwaga / Notatka

W systemie Mac/Linux lokalizacja pliku konfiguracji użytkownika różni się w zależności od narzędzi. Interfejs wiersza polecenia platformy .NET używa ~/.nuget/NuGet folderu, a mono używa ~/.config/NuGet folderu.

W systemie Mac/Linux lokalizacja pliku konfiguracji na poziomie użytkownika różni się w zależności od narzędzi

W systemie Mac/Linux lokalizacja pliku konfiguracji użytkownika różni się w zależności od narzędzi. Większość użytkowników korzysta z narzędzi, które szukają pliku konfiguracji użytkownika w folderze ~/.nuget/NuGet . Te inne narzędzia szukają pliku konfiguracji użytkownika w folderze ~/.config/NuGet :

  • Mono
  • NuGet.exe
  • Visual Studio 2019 dla komputerów Mac (i starsze wersje)
  • Visual Studio 2022 dla komputerów Mac (i późniejsze jego wersje) jest dostępny wyłącznie w przypadku pracy nad klasycznymi projektami Mono.

Jeśli używane narzędzia obejmują obie lokalizacje, rozważ ich skonsolidowanie, wykonując następujące kroki, aby umożliwić pracę tylko z jednym plikiem konfiguracji na poziomie użytkownika:

  1. Sprawdź zawartość dwóch plików konfiguracji na poziomie użytkownika i zachowaj odpowiedni plik w ~/.nuget/NuGet folderze.
  2. Ustaw łącze symboliczne z ~/.nuget/NuGet na ~/.config/NuGet. Na przykład uruchom polecenie bash: ln -s ~/.nuget/NuGet ~/.config/NuGet.

Uwagi dotyczące wcześniejszych wersji pakietu NuGet:

  • Program NuGet 3.3 i starsze wersje używał .nuget folderu dla ustawień obejmujących całe rozwiązanie. Ten folder nie jest używany w programie NuGet 3.4 lub nowszym.
  • W przypadku pakietów NuGet od 2.6 do 3.x plik konfiguracji na poziomie komputera w systemie Windows znajdował się w lokalizacji %ProgramData%\NuGet\Config[\{IDE}[\{Version}[\{SKU}]]]\NuGet.Config, gdzie {IDE} może być VisualStudio, {Version} jest wersją programu Visual Studio, taką jak 14.0, a {SKU} to Community, Pro lub Enterprise. Aby przeprowadzić migrację ustawień do pakietu NuGet 4.0 lub nowszego, po prostu skopiuj plik konfiguracji do %ProgramFiles(x86)%\NuGet\Config. W systemie Linux poprzednia lokalizacja to /etc/opt, a na komputerze Mac /Library/Application Support.

Zmienianie ustawień konfiguracji

Plik NuGet.Config jest prostym plikiem tekstowym XML zawierającym pary klucz/wartość zgodnie z opisem w temacie Ustawienia konfiguracji NuGet .

Ustawienia są zarządzane przy użyciu polecenia konfiguracji interfejsu wiersza polecenia NuGet:

  • Domyślnie zmiany są wprowadzane do pliku konfiguracji na poziomie użytkownika. (W systemie Mac/Linux lokalizacja pliku konfiguracji na poziomie użytkownika różni się w zależności od narzędzi)
  • Aby zmienić ustawienia w innym pliku, użyj przełącznika -configFile . W takim przypadku pliki mogą używać dowolnej nazwy pliku.
  • Klucze są zawsze rozróżniane pod względem wielkości liter.
  • Podniesienie poziomu uprawnień jest wymagane do zmiany ustawień w pliku ustawień na poziomie całego systemu komputerowego.

Ostrzeżenie

Mimo że plik można zmodyfikować w dowolnym edytorze tekstów, NuGet (wersja 3.4.3 lub nowsza) dyskretnie ignoruje cały plik konfiguracji, jeśli zawiera źle sformułowany kod XML (niedopasowane tagi, nieprawidłowe znaki cudzysłowu itp.). Dlatego preferowane jest zarządzanie ustawieniem przy użyciu polecenia nuget config.

Ustawianie wartości

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

Uwaga / Notatka

W programie NuGet 3.4 lub nowszym można używać zmiennych środowiskowych w dowolnej wartości, tak jak w systemach repositoryPath=%PACKAGEHOME% (Windows) i repositoryPath=$PACKAGEHOME (Mac/Linux).

Usuwanie wartości

Aby usunąć wartość, określ klucz z pustą wartością.

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

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

Tworzenie nowego pliku konfiguracji

Za pomocą interfejsu wiersza polecenia platformy .NET utwórz domyślną nuget.config, uruchamiając polecenie dotnet new nugetconfig. Aby uzyskać więcej informacji, zobacz dotnet CLI commands (Polecenia interfejsu wiersza polecenia dotnet).

Alternatywnie ręcznie skopiuj poniższy szablon do nowego pliku, a następnie użyj polecenia nuget config -configFile <filename> , aby ustawić wartości:

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

Jak są stosowane ustawienia

Wiele NuGet.Config plików umożliwia przechowywanie ustawień w różnych lokalizacjach, tak aby były stosowane do jednego rozwiązania lub grupy rozwiązań. Te ustawienia są stosowane zbiorczo do dowolnej operacji NuGet wywoływanej z wiersza polecenia lub programu Visual Studio z ustawieniami istniejącymi "najbliżej" rozwiązania lub bieżącego folderu, które mają pierwszeństwo. Jeśli narzędzie wiersza polecenia jest używane w pliku projektu, a nie w pliku rozwiązania, katalog projektu jest używany jako "katalog rozwiązania", co może prowadzić do niespójnego zachowania, gdy plik znajduje NuGet.Config się w podkatalogu pliku rozwiązania.

W szczególności, gdy plik konfiguracji nie zostanie jawnie określony w wierszu polecenia, pakiet NuGet ładuje ustawienia z różnych plików konfiguracji w następującej kolejności:

  1. (Nietypowe) NuGetDefaults.Config Plik, który zawiera ustawienia związane tylko ze źródłami pakietów.
  2. Plik na poziomie komputera.
  3. Plik na poziomie użytkownika.
  4. Pliki znalezione w każdym folderze w ścieżce z katalogu głównego dysku do bieżącego folderu (gdzie nuget.exe jest wywoływane lub folder zawierający rozwiązanie programu Visual Studio). Na przykład, jeśli polecenie jest wywoływane w c:\A\B\C, NuGet wyszukuje i ładuje pliki konfiguracji w c:\, następnie c:\A, potem c:\A\B, a na koniec c:\A\B\C.

Jeśli plik konfiguracji jest jawnie określony w wierszu polecenia, na przykład nuget -configFile my.config lub dotnet restore --configfile my.config, będą używane tylko ustawienia z określonego pliku.

Ponieważ program NuGet znajduje ustawienia w tych plikach, są one stosowane w następujący sposób:

  1. W przypadku elementów pojedynczych, NuGet zastąpił każdą wcześniej znalezioną wartość dla tego samego klucza. Oznacza to, że ustawienia znajdujące się "najbliżej" bieżącego folderu lub rozwiązania zastępują wszystkie inne znalezione wcześniej. Na przykład ustawienie defaultPushSource jest zastępowane przez NuGetDefaults.Config, jeśli istnieje w jakimkolwiek innym pliku konfiguracji.
  2. W przypadku elementów kolekcji (takich jak <packageSources>), NuGet łączy wartości ze wszystkich plików konfiguracji w jedną kolekcję.
  3. Gdy <clear /> jest obecny dla danego węzła, NuGet ignoruje wcześniej zdefiniowane wartości konfiguracji dla tego węzła.

Wskazówka

Dodaj plik nuget.config w katalogu głównym repozytorium rozwiązania. Jest to najlepsze rozwiązanie, ponieważ promuje powtarzalność i zapewnia, że różni użytkownicy mają tę samą konfigurację NuGet.

Przewodnik po ustawieniach

Załóżmy, że masz następującą strukturę folderów na dwóch oddzielnych dyskach:

disk_drive_1
    User
disk_drive_2
    Project1
        Source
    Project2
        Source
    tmp

Następnie masz cztery NuGet.Config pliki w następujących lokalizacjach z daną zawartością. (Plik na poziomie komputera nie jest uwzględniony w tym przykładzie, ale zachowuje się podobnie do pliku na poziomie użytkownika).

Plik A. Plik na poziomie użytkownika, (%appdata%\NuGet\NuGet.Config w systemie Windows, ~/.config/NuGet/NuGet.Config na komputerze Mac/Linux):

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

Plik 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>

Plik 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>

Plik 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>

Narzędzie NuGet następnie ładuje i stosuje ustawienia w następujący sposób, w zależności od tego, gdzie jest wywoływany:

  • Wywoływane z disk_drive_1/users: używane jest tylko domyślne repozytorium wymienione w pliku konfiguracji na poziomie użytkownika (A), ponieważ jest to jedyny plik znaleziony na disk_drive_1.

  • Wywoływany z disk_drive_2/ lub disk_drive_/tmp: Plik na poziomie użytkownika (A) jest najpierw ładowany, a następnie NuGet przechodzi do katalogu głównego disk_drive_2 i znajduje plik (B). NuGet wyszukuje również plik konfiguracji w pliku /tmp , ale go nie znajduje. W związku z tym jest używane domyślne repozytorium nuget.org , przywracanie pakietów jest włączone, a pakiety są rozszerzane w programie disk_drive_2/tmp.

  • Wywoływany z disk_drive_2/Project1 lub disk_drive_2/Project1/Source: Plik na poziomie użytkownika (A) jest ładowany najpierw, a następnie NuGet ładuje plik (B) z katalogu głównego disk_drive_2, a następnie plik (C). Ustawienia w (C) zastępują te w ustawieniach (B) i (A), więc repositoryPath miejsce, w którym instalowane są pakiety, to disk_drive_2/Project1/External/Packages zamiast disk_drive_2/tmp. Ponadto, ponieważ (C) czyści <packageSources>, nuget.org nie jest już dostępny jako źródło pozostawiając tylko https://MyPrivateRepo/ES/nuget.

  • Wywoływane z disk_drive_2/Project2 lub disk_drive_2/Project2/Source: Najpierw ładowany jest plik na poziomie użytkownika (A), a następnie pliki (B) i (D). Ponieważ packageSources nie jest czyszczone, oba nuget.org i https://MyPrivateRepo/DQ/nuget są dostępne jako źródła. Pakiety są rozszerzane w disk_drive_2/tmp sposób określony w (B).

Dodatkowa konfiguracja dla całego użytkownika

Począwszy od wersji 5.7, pakiet NuGet dodał obsługę dodatkowych plików konfiguracji dla całego użytkownika. Dzięki temu dostawcy innych firm mogą dodawać dodatkowe pliki konfiguracji użytkownika bez podniesienia uprawnień. Te pliki konfiguracyjne znajdują się w folderze konfiguracji użytkownika o zasięgu ogólnym w podfolderze config. Wszystkie pliki kończące się na .config lub .Config będą brane pod uwagę. Tych plików nie można edytować przy użyciu standardowych narzędzi.

Platforma systemu operacyjnego Dodatkowe konfiguracje
Windows %appdata%\NuGet\config\*.Config
Mac/Linux ~/.config/NuGet/config/*.config lub ~/.nuget/config/*.config

Plik domyślny NuGet

Nie jest powszechne korzystanie z NuGetDefaults.Config, ponieważ może on jedynie określać źródła pakietów, z których pakiety są instalowane i aktualizowane, lub kontrolować domyślną lokację do publikowania pakietów przy użyciu nuget push.

Ponieważ administratorzy mogą wygodnie (na przykład za pomocą zasad grup) wdrażać spójne NuGetDefaults.Config pliki na maszynach deweloperskich i maszynach kompilacyjnych, mogą mieć pewność, że wszyscy w organizacji korzystają ze spójnych źródeł pakietów, niezależnie od tego, czy obejmują one nuget.org.

Ważne

Plik NuGetDefaults.Config nigdy nie powoduje usunięcia źródła pakietu z konfiguracji NuGet dewelopera. Oznacza to, że jeśli deweloper użył już pakietu NuGet i w związku z tym ma zarejestrowane źródło pakietu nuget.org, nie zostanie on usunięty po utworzeniu NuGetDefaults.Config pliku.

Ponadto ani NuGetDefaults.Config żaden inny mechanizm w pakiecie NuGet nie może uniemożliwić dostępu do źródeł pakietów, takich jak nuget.org. Jeśli organizacja chce zablokować taki dostęp, musi użyć innych środków, takich jak zapory, aby to zrobić.

NuGetDefaults.Config lokalizacja

W poniższej tabeli opisano miejsce NuGetDefaults.Config przechowywania pliku w zależności od docelowego systemu operacyjnego:

Platforma systemu operacyjnego NuGetDefaults.Config Lokalizacja
Windows Visual Studio 2017 lub NuGet 4.x+:%ProgramFiles(x86)%\NuGet
Programy Visual Studio 2015 i starsze lub NuGet 3.x i starsze:%PROGRAMDATA%\NuGet
Mac/Linux $XDG_DATA_HOME (zazwyczaj ~/.local/share lub /usr/local/share, w zależności od dystrybucji systemu operacyjnego)

Ustawienia narzędzia NuGetDefaults.Config

  • packageSources: ta kolekcja ma takie samo znaczenie jak packageSources w zwykłych plikach konfiguracji i określa domyślne źródła. Narzędzie NuGet używa źródeł w określonej kolejności podczas instalowania lub aktualizowania pakietów w projektach w formacie zarządzania packages.config. W przypadku projektów korzystających z formatu PackageReference program NuGet najpierw używa lokalnych źródeł, a następnie źródeł w udziałach sieciowych, a następnie źródeł HTTP, niezależnie od kolejności w plikach konfiguracji. NuGet zawsze ignoruje kolejność źródeł przy użyciu operacji przywracania.

  • disabledPackageSources: ta kolekcja ma również takie samo znaczenie jak w NuGet.Config plikach, gdzie każde źródło, którego dotyczy problem, jest wymienione według jego nazwy i true/false wartości wskazującej, czy jest wyłączona. To pozwala nazwie źródła i adresowi URL pozostać w packageSources bez włączania tego ustawienia domyślnie. Następnie poszczególni deweloperzy mogą ponownie włączyć źródło, ustawiając wartość źródła na false w innych plikach NuGet.Config bez konieczności ponownego znajdowania poprawnego adresu URL. Jest to również przydatne w przypadku dostarczania deweloperom pełnej listy wewnętrznych adresów URL źródłowych dla organizacji przy jednoczesnym domyślnie włączeniu źródła tylko pojedynczego zespołu.

  • defaultPushSource: określa domyślny element docelowy dla nuget push operacji, zastępując wbudowaną wartość domyślną nuget.org. Administratorzy mogą wdrożyć to ustawienie, aby uniknąć przypadkowego publikowania pakietów wewnętrznych do ogólnodostępnych nuget.org, ponieważ deweloperzy muszą używać nuget push -Source do publikowania w nuget.org.

Przykład nuGetDefaults.Config i aplikacja

<?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>
  • Last updated on