Udostępnij za pośrednictwem

Typowe konfiguracje narzędzia NuGet

  • Artykuł

Zachowanie narzędzia NuGet jest spowodowane przez skumulowane ustawienia w co najmniej jednym pliku konfiguracji (XML), które mogą istnieć w rozwiązaniu — (projekt, jeśli nie jest używane rozwiązanie), poziomach użytkownika i komputera.

Konfigurowanie lokalizacji plików i zastosowań

Scope Lokalizacja pliku NuGet.Config opis
Rozwiązanie Bieżący folder (folder rozwiązania) lub dowolny folder 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 wartość nie ma wartości null ani nie jest pusta, $NUGET_COMMON_APPLICATION_DATA/NuGet/Config zamiast tego		 Ustawienia mają zastosowanie do wszystkich operacji na komputerze, ale są zastępowane przez ustawienia na poziomie użytkownika lub rozwiązania.

Uwaga

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)
  • Program Visual Studio 2022 dla komputerów Mac (i jego nowsze wersje) działa tylko podczas 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 powłoki 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 %ProgramData%\NuGet\Config[\{IDE}[\{Version}[\{SKU}]]]\NuGet.Configlokalizacji , gdzie {IDE} może być {Version} VisualStudiowersją programu Visual Studio, taką jak 14.0, i {SKU} ma Communitywartość , Prolub 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, i 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 uwzględniane wielkości liter.
  • Podniesienie uprawnień jest wymagane do zmiany ustawień w pliku ustawień na poziomie komputera.

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

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ą konfigurację 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\Cprogramie , NuGet wyszukuje i ładuje pliki konfiguracji w c:\pliku , , c:\A, i c:\A\Bna 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 pojedynczego elementu pakiet NuGet zamienił dowolną 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 w NuGetDefaults.Config pliku jest zastępowane, defaultPushSource jeśli istnieje w 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.

Napiwek

nuget.config Dodaj plik 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/usersprogramu : używane jest tylko domyślne repozytorium wymienione w pliku konfiguracji na poziomie użytkownika (A), ponieważ jest to jedyny plik znaleziony w pliku disk_drive_1.

  • Wywoływany z disk_drive_2/ pliku 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 elementach (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ływany z disk_drive_2/Project2 pliku lub disk_drive_2/Project2/Source: Plik na poziomie użytkownika (A) jest ładowany najpierw, a następnie plik (B) i plik (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 konfiguracji znajdują się w folderze konfiguracji całego użytkownika standardowego config w podfolderze. 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
System Mac/Linux ~/.config/NuGet/config/*.config lub ~/.nuget/config/*.config

Plik domyślny nuGet

Jest NuGetDefaults.Config rzadkością i może określać tylko źródła pakietów, z których pakiety są instalowane i aktualizowane, lub kontrolować domyślny element docelowy dla pakietów publikowania za pomocą polecenia nuget push.

Ponieważ administratorzy mogą wygodnie (na przykład za pomocą zasad grupy) wdrażać spójne NuGetDefaults.Config pliki na maszynach deweloperskich i kompilacji, mogą mieć pewność, że wszyscy w organizacji korzystają ze spójnych źródeł pakietów, niezależnie od tego, czy zawierają 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
System 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 kolejności podczas instalowania lub aktualizowania pakietów w projektach przy użyciu packages.config formatu zarządzania. 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. Dzięki temu nazwa źródła i adres URL mogą pozostać bez packageSources włączenia go domyślnie. Następnie indywidualni deweloperzy mogą ponownie włączyć źródło, ustawiając wartość źródła na false wartość w innych NuGet.Config plikach 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, przesłaniając wbudowaną wartość domyślną .nuget.org Administratorzy mogą wdrożyć to ustawienie, aby uniknąć przypadkowego publikowania pakietów wewnętrznych do publicznej wiadomości nuget.org , ponieważ deweloperzy muszą używać nuget push -Source ich do publikowania w nuget.orgprogramie .

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>