Przywracanie pakietów za pomocą przywracania pakietów NuGet

  • Artykuł

Przywracanie pakietu NuGet przywraca wszystkie zależności projektu wymienione w pliku projektu lub pliku packages.config . Pakiety można przywrócić ręcznie za pomocą programu nuget restore, dotnet restore, msbuild -t:restorelub za pomocą programu Visual Studio. Polecenia dotnet build i dotnet run automatycznie przywracają pakiety i można skonfigurować program Visual Studio do automatycznego przywracania pakietów podczas kompilowania projektu.

Aby promować czystsze środowisko programistyczne i zmniejszyć rozmiar repozytorium, przywracanie pakietów sprawia, że wszystkie zależności projektu są dostępne bez konieczności przechowywania ich w kontroli źródła. Aby skonfigurować repozytorium kontroli źródła w celu wykluczenia plików binarnych pakietów, zobacz Pakiety i kontrola źródła.

Zachowanie przywracania pakietów

Przywracanie pakietów próbuje zainstalować wszystkie zależności pakietów do stanu zgodnego <PackageReference>z s w pliku projektu, takim jak csproj, lub <package>s w pliku packages.config . Funkcja Przywracania pakietów najpierw instaluje bezpośrednie zależności projektu zgodnie z potrzebami, a następnie instaluje wszystkie zależności tych pakietów w całym grafie zależności.

Jeśli wymagany pakiet nie jest jeszcze zainstalowany, program NuGet najpierw próbuje pobrać go z lokalnych pakietów globalnych lub folderów pamięci podręcznej HTTP. Jeśli pakiet nie znajduje się w folderach lokalnych, pakiet NuGet próbuje pobrać go ze wszystkich źródeł skonfigurowanych w programie Visual Studio w obszarze Narzędzia>Opcje>narzędzia NuGet Menedżer pakietów> Package Sources.

Podczas przywracania nuGet ignoruje kolejność źródeł pakietów i używa pakietu z pierwszego źródła, które odpowiada na żądania. Jeśli przywracanie nie powiedzie się, narzędzie NuGet nie wskazuje błędu, dopóki nie sprawdzi wszystkich źródeł. Następnie narzędzie NuGet zgłasza błąd tylko dla ostatniego źródła na liście. Błąd oznacza, że pakiet nie był obecny w żadnym ze źródeł, mimo że nie wyświetla pojedynczej listy innych błędów.

Aby uzyskać więcej informacji na temat zachowania narzędzia NuGet, zobacz Typowe konfiguracje nuGet.

Przywracanie pakietów

Jeśli odwołania do pakietu w pliku projektu lub pliku packages.config są poprawne, użyj preferowanego narzędzia, aby przywrócić pakiety:

Po pomyślnym przywróceniu:

  • W przypadku projektów korzystających z <PackageReference>programu pakiet znajduje się w lokalnym folderze global-packages, a plik obj/project.assets.json projektu zostanie utworzony ponownie.
  • W przypadku projektów korzystających z pliku packages.config pakiet jest wyświetlany w folderze packages projektu.
  • Projekt powinien teraz pomyślnie skompilować.

Jeśli odwołania do pakietu w pliku projektu lub pliku packages.config są nieprawidłowe i nie są zgodne z żądanym stanem, zainstaluj lub zaktualizuj odpowiednie pakiety zamiast przy użyciu przywracania pakietów.

Jeśli brakuje pakietów lub błędów związanych z pakietem po uruchomieniu przywracania pakietów, takich jak ikony błędów w Eksplorator rozwiązań, postępuj zgodnie z instrukcjami w temacie Rozwiązywanie problemów z błędami przywracania pakietów lub zainstaluj lub zaktualizuj pakiety. W programie Visual Studio konsola Menedżer pakietów udostępnia kilka opcji ponownego instalowania pakietów. Aby uzyskać więcej informacji, zobacz Use Package-Update (Używanie aktualizacji pakietu).

Przywracanie pakietów w programie Visual Studio

W programie Visual Studio w systemie Windows można automatycznie lub ręcznie przywracać pakiety. Najpierw skonfiguruj przywracanie pakietów za pomocą opcji>narzędzi>NuGet Menedżer pakietów.

Konfigurowanie opcji przywracania pakietów programu Visual Studio

Skonfiguruj następujące opcje przywracania pakietów w obszarze Narzędzia>Opcje>NuGet Menedżer pakietów> Ogólne.

Screenshot that shows the NuGet Package Manager options.

Zezwalaj nuGet na pobieranie brakujących pakietów

Wybierz pozycję Zezwalaj nuGet na pobieranie brakujących pakietów , aby włączyć przywracanie pakietów i polecenie Przywróć pakiety NuGet. Ten wybór ustawia packageRestore/enabled ustawienie na True wartość w sekcji packageRestore globalnego pliku NuGet.Config w lokalizacji %AppData%\Roaming\NuGet w systemie Windows lub ~/.nuget/NuGet/ na komputerach Mac lub Linux.

<configuration>
    <packageRestore>
        <add key="enabled" value="True" />
    </packageRestore>
</configuration>

Uwaga

Aby globalnie zastąpić packageRestore/enabled ustawienie, możesz ustawić zmienną środowiskową EnableNuGetPackageRestore na true lub False przed otwarciem programu Visual Studio lub uruchomieniem kompilacji.

Aby włączyć lub wyłączyć przywracanie pakietów dla wszystkich użytkowników na komputerze, możesz dodać ustawienia konfiguracji do globalnego pliku NuGet.Config w systemie Windows w lokalizacji %ProgramData%\NuGet\Config, czasami w określonym< folderze IDE>\Version>\<<SKU> Visual Studio lub w systemie Mac/Linux w lokalizacji ~/.local/share. Użytkownicy indywidualni mogą następnie selektywnie włączać przywracanie zgodnie z potrzebami na poziomie projektu. Aby uzyskać więcej informacji na temat określania priorytetów wielu plików konfiguracji nuGet, zobacz Typowe konfiguracje NuGet.

Ważne

Jeśli edytujesz packageRestore ustawienia bezpośrednio w pliku NuGet.Config, uruchom ponownie program Visual Studio, aby opcjezawierały bieżące wartości.

Automatyczne sprawdzanie brakujących pakietów podczas kompilacji

Wybierz pozycję Automatycznie sprawdź brakujące pakiety podczas kompilacji w programie Visual Studio , aby automatycznie przywrócić brakujące pakiety podczas uruchamiania kompilacji z poziomu programu Visual Studio. To ustawienie nie ma wpływu na kompilacje uruchamiane z poziomu wiersza polecenia MSBuild. Ten wybór ustawia ustawienie na True wartość packageRestore/automatic w packageRestore sekcji pliku NuGet.Config.

<configuration>
    <packageRestore>
        <add key="automatic" value="True" />
    </packageRestore>
</configuration>

W przypadku projektów innych niż zestaw SDK należy wybrać pozycję Zezwalaj nuGet na pobieranie brakujących pakietów, a także automatycznie sprawdzać brakujące pakiety podczas kompilacji w programie Visual Studio w opcjach, aby włączyć automatyczne przywracanie.

Wybieranie domyślnego formatu zarządzania pakietami

Pakiet NuGet ma dwa formaty zarządzania pakietami: PackageReference i packages.config. Wybierz format, którego chcesz użyć z listy rozwijanej w obszarze Zarządzanie pakietami. Możesz również wybrać, czy zezwolić na wybór formatu podczas pierwszej instalacji pakietu.

Uwaga

  • Jeśli projekt nie obsługuje obu formatów zarządzania pakietami, pakiet NuGet używa formatu zarządzania pakietami zgodnego z projektem, co może nie być ustawieniem domyślnym ustawionym w opcjach. Narzędzie NuGet nie wyświetli monitu o wybranie opcji podczas pierwszej instalacji, nawet jeśli została wybrana ta opcja.

  • Jeśli do zainstalowania pierwszego pakietu w projekcie używasz konsoli Menedżer pakietów, program NuGet nie wyświetla monitu o wybór formatu, nawet jeśli ta opcja jest zaznaczona w obszarze Opcje.

Ręczne lub automatyczne przywracanie pakietów

Po włączeniu przywracania pakietów w obszarze Opcje możesz kliknąć rozwiązanie prawym przyciskiem myszy w Eksplorator rozwiązań i wybrać polecenie Przywróć pakiety NuGet w dowolnym momencie.

Jeśli włączono automatyczne przywracanie w obszarze Opcje, przywracanie pakietów odbywa się automatycznie podczas tworzenia projektu na podstawie szablonu lub kompilowania projektu. W przypadku pakietu NuGet 4.0 lub nowszego przywracanie odbywa się również automatycznie po wprowadzeniu zmian w projekcie w stylu zestawu SDK.

W przypadku projektów korzystających z programu <PackageReference>można wyświetlić odwołania do pakietów w programie Visual Studio Eksplorator rozwiązań w obszarze Pakiety zależności>. Pakiety, które nie są prawidłowo instalowane podczas ręcznego przywracania lub uruchamiania ikon błędów wyświetlania kompilacji w Eksplorator rozwiązań. Kliknij prawym przyciskiem myszy projekt, wybierz pozycję Zarządzaj pakietami NuGet i użyj Menedżer pakietów NuGet, aby odinstalować i ponownie zainstalować objęte pakiety. Aby uzyskać więcej informacji, zobacz Ponowne instalowanie i aktualizowanie pakietów.

Jeśli zostanie wyświetlony błąd Ten projekt odwołuje się do pakietów NuGet, których brakuje na tym komputerze, lub należy przywrócić co najmniej jeden pakiet NuGet, ale nie można go przywrócić, ponieważ nie udzielono zgody, upewnij się, że włączono automatyczne przywracanie. W przypadku starszych projektów zobacz Migrowanie do automatycznego przywracania pakietów. Zobacz również Rozwiązywanie problemów z błędami przywracania pakietów.

Przywracanie przy użyciu interfejsu wiersza polecenia dotnet

Polecenie dotnet restore przywraca pakiety zawierające listę plików projektu za pomocą <PackageReference>polecenia . Aby uzyskać więcej informacji, zobacz PackageReference w plikach projektu.

Program .NET Core 2.0 lub nowszy dotnet build oraz dotnet run polecenia automatycznie przywracają pakiety. Od wersji NuGet 4.0 dotnet restore program uruchamia ten sam kod co nuget restore.

Aby przywrócić pakiet za pomocą polecenia dotnet restore:

  1. Otwórz wiersz polecenia i przejdź do katalogu zawierającego plik projektu.
  2. Uruchom program dotnet restore.

Ważne

Aby dodać brakujące odwołanie do pakietu do pliku projektu, użyj polecenia dotnet add package, który również uruchamia polecenie restore.

Przywracanie przy użyciu interfejsu wiersza polecenia Narzędzia NuGet

Polecenie przywracania interfejsu wiersza polecenia NuGet pobiera i instaluje wszystkie brakujące pakiety. Polecenie działa w projektach, które używają odwołania do pakietów PackageReference lub packages.config .

Podobnie jak installpolecenie restore , dodaje tylko pakiety na dysku, ale nie modyfikuje pliku projektu ani packages.config. Aby dodać zależności projektu, użyj interfejsu użytkownika lub konsoli programu Visual Studio Menedżer pakietów.

Aby przywrócić pakiety, uruchom następujące polecenie:

nuget restore <projectPath>

Polecenie restore używa pliku rozwiązania lub pliku package.config w określonej ścieżce projektu.

Aby na przykład przywrócić wszystkie pakiety dla MySolution.sln w bieżącym katalogu, uruchom polecenie:

nuget restore MySolution.sln

Uwaga

W przypadku projektów innych niż zestaw SDK korzystających z programu PackageReferenceużyj polecenia msbuild -t:restore , aby przywrócić pakiety.

Przywracanie przy użyciu programu MSBuild

Możesz użyć narzędzia msbuild -t:restore , aby przywrócić pakiety w pakietach NuGet 4.x+ i MSBuild 15.1 lub nowszych, które są dołączone do programu Visual Studio 2017 i nowszych.

To polecenie przywraca pakiety w projektach korzystających z funkcji PackageReference na potrzeby odwołań do pakietów. Począwszy od programu MSBuild 16.5 lub nowszego, polecenie obsługuje również odwołania do pakietów packages.config , jeśli są używane z -p:RestorePackagesConfig=trueprogramem .

Aby użyć przywracania programu MSBuild:

  1. Otwórz wiersz polecenia dla deweloperów, wyszukując wiersz polecenia dla deweloperów i uruchamiając wiersz polecenia z menu Start systemu Windows, który konfiguruje wszystkie niezbędne ścieżki programu MSBuild.

  2. Przejdź do folderu projektu i wprowadź polecenie msbuild -t:restore.

  3. Po zakończeniu przywracania wprowadź polecenie msbuild , aby ponownie skompilować projekt. Upewnij się, że dane wyjściowe programu MSBuild wskazują, że kompilacja została ukończona pomyślnie.

Uwaga

Możesz użyć msbuild -restore polecenia , aby uruchomić restorepolecenie , ponownie załadować projekt i skompilować, ponieważ kompilacja jest domyślnym elementem docelowym. Aby uzyskać więcej informacji, zobacz Przywracanie i kompilowanie za pomocą jednego polecenia MSBuild.

Przywracanie za pomocą usługi Azure Pipelines lub usługi Azure DevOps Server

Podczas tworzenia definicji kompilacji w usłudze Azure Pipelines można dołączyć zadanie przywracania interfejsu wiersza polecenia NuGet lub przywracanie interfejsu wiersza polecenia dotnet w definicji przed wszystkimi zadaniami kompilacji. Niektóre szablony kompilacji domyślnie obejmują zadanie przywracania.

Usługi Azure DevOps Server i TFS 2013 i nowsze automatycznie przywracają pakiety podczas kompilacji, jeśli używasz szablonu TFS 2013 lub nowszej kompilacji zespołowej. Możesz również dołączyć krok kompilacji, aby uruchomić opcję przywracania wiersza polecenia lub opcjonalnie zmigrować szablon kompilacji do nowszej wersji. Aby uzyskać więcej informacji, zobacz Konfigurowanie przywracania pakietów za pomocą kompilacji team foundation.

Wersje pakietów ograniczeń

Przywracanie nuGet za pomocą dowolnej metody honoruje wszelkie ograniczenia wersji określone w pliku packages.config lub pliku projektu.

  • W pliku packages.config można określić allowedVersions zakres w zależności. Aby uzyskać więcej informacji, zobacz Ograniczenia dotyczące wersji uaktualnienia. Na przykład:

    <package id="Newtonsoft.json" version="6.0.4" allowedVersions="[6,7)" />

  • W pliku projektu można określić zakres wersji we Version właściwości zależności. Na przykład:

    <PackageReference Include="Newtonsoft.json" Version="[6,7)" />

W obu przypadkach użyj notacji opisanej w temacie Przechowywanie wersji pakietów.

Wymuszanie przywracania ze zdalnych źródeł pakietów

Domyślnie operacje przywracania nuGet używają pakietów z lokalnych folderów globalnych i http-cache , zgodnie z opisem w temacie Zarządzanie pakietami globalnymi i folderami pamięci podręcznej. Aby uniknąć korzystania z tych pakietów lokalnych, użyj następujących opcji.

Aby wyczyścić wszystkie lokalne pamięci podręczne:

  • W programie Visual Studio wybierz przycisk Wyczyść wszystkie pamięci podręczne NuGet w obszarze Opcje>narzędzi>NuGet Menedżer pakietów> Ogólne.
  • W interfejsie wiersza polecenia dotnet użyj polecenia dotnet nuget locals all --clear.
  • W interfejsie wiersza polecenia narzędzia NuGet użyj polecenia nuget locals all -clear.

Aby uniknąć używania pakietów w folderze global-packages :

  • Wyczyść folder przy użyciu polecenia nuget locals global-packages -clear lub dotnet nuget locals global-packages --clear.
  • Tymczasowo ustaw zmienną środowiskową NUGET_PACKAGES na inny folder.
  • Utwórz plik NuGet.Config, który ustawia wartość globalPackagesFolder , PackageReferencelub repositoryPath dla pliku packages.config, do innego folderu. Aby uzyskać więcej informacji, zobacz ustawienia konfiguracji.
  • Tylko w przypadku programu MSBuild określ inny folder z właściwością RestorePackagesPath .

Aby uniknąć używania pakietów w pamięci podręcznej HTTP:

  • Wyczyść pamięć podręczną przy użyciu polecenia nuget locals http-cache -clear lub dotnet nuget locals http-cache --clear.
  • Tymczasowo ustaw zmienną środowiskową NUGET_HTTP_CACHE_PATH na inny folder.
  • W przypadku nuget restoreprogramu użyj -NoHttpCache opcji lub dla dotnet restorepolecenia , użyj --no-http-cache opcji . Te opcje nie mają wpływu na operacje przywracania za pośrednictwem programu Visual Studio Menedżer pakietów ani konsoli.

Migrowanie do automatycznego przywracania pakietów

Wcześniejsze wersje pakietu NuGet obsługują przywracanie pakietów zintegrowanych z narzędziem MSBuild. Projekty korzystające z przestarzałego przywracania pakietu zintegrowanego z programem MSBuild powinny zostać zmigrowane do automatycznego przywracania pakietów.

Te projekty zazwyczaj zawierają folder nuget z trzema plikami: NuGet.config, nuget.exe i NuGet.targets. Plik NuGet.targets powoduje, że program NuGet używa zintegrowanego podejścia MSBuild, dlatego należy go usunąć.

Aby przeprowadzić migrację do automatycznego przywracania pakietów:

  1. Włącz automatyczne przywracanie pakietów.
  2. Zamknij program Visual Studio.
  3. Usuń pliki .nuget/nuget.exe i .nuget/NuGet.targets.
  4. Dla każdego pliku projektu usuń <RestorePackages> element i usuń wszystkie odwołania do pliku NuGet.targets.

Aby przetestować automatyczne przywracanie pakietów:

  1. Usuń folder packages z rozwiązania.
  2. Otwórz rozwiązanie w programie Visual Studio i uruchom kompilację. Automatyczne przywracanie pakietów powinno pobierać i instalować każdy pakiet zależności bez dodawania go do kontroli źródła.

Następne kroki