Restore NuGet nie działa

Restore NuGet niedziałające wskazuje na niedostępne źródło pakietów lub uszkodzony plik konfiguracyjny nuget.config projektu.

Restore NuGet nie działa — czym jest ten problem

Komunikat „Restore NuGet nie działa” pojawia się wtedy, gdy środowisko programistyczne nie potrafi przygotować zależności wymaganych przez projekt .NET. Operacja przywracania pakietów NuGet ma za zadanie odczytać informacje z plików projektu, sprawdzić listę wymaganych bibliotek, skontaktować się ze skonfigurowanymi repozytoriami i pobrać odpowiednie wersje komponentów. Jeżeli którykolwiek z tych etapów zostanie przerwany, kompilacja może zakończyć się błędem, a edytor może oznaczać przestrzenie nazw jako nierozpoznane.

Nie jest to jeden konkretny błąd, lecz wspólna nazwa kilku sytuacji. Przyczyną może być niepoprawna konfiguracja źródeł pakietów, brak dostępu do sieci, wygasłe uwierzytelnienie, konflikt wersji, zablokowany katalog pamięci podręcznej albo niezgodność między używanym zestawem SDK a projektem. W wielu przypadkach sam kod aplikacji pozostaje poprawny, a problem dotyczy wyłącznie sposobu, w jaki narzędzia próbują odnaleźć i pobrać zależności.

Znaczenie ma również rodzaj projektu. Inaczej przebiega przywracanie dla klasycznego pliku z rozszerzeniem .csproj, inaczej dla rozwiązania zawierającego wiele projektów, a jeszcze inaczej dla aplikacji korzystającej z centralnego zarządzania wersjami pakietów. Dlatego skuteczna diagnoza powinna obejmować nie tylko treść komunikatu, ale również strukturę katalogów, używaną wersję SDK oraz źródła wskazane w ustawieniach NuGet.

Restore NuGet a źródła pakietów i konfiguracja

Najczęstszym punktem kontroli jest lista źródeł pakietów. NuGet może korzystać z publicznego repozytorium, prywatnego repozytorium firmowego albo lokalnego katalogu z paczkami. Gdy źródło zostało wyłączone, zmieniło adres, wymaga logowania lub przestało odpowiadać, przywracanie może zgłaszać brak pakietu, błąd połączenia albo niemożność odczytania metadanych. Warto sprawdzić, czy nazwa źródła jest właściwa, czy adres zaczyna się od prawidłowego protokołu oraz czy nie występują literówki.

Konfiguracja może być przechowywana w kilku miejscach. Pod uwagę bierze się ustawienia globalne użytkownika, plik nuget.config znajdujący się w katalogu projektu oraz pliki obecne w katalogach nadrzędnych. NuGet odczytuje je według określonej hierarchii, a ustawienie zapisane wyżej może zostać zmodyfikowane lub nadpisane przez ustawienie lokalne. W efekcie narzędzie uruchamiane z jednego katalogu może działać inaczej niż to samo polecenie uruchomione z innej lokalizacji.

Przydatne jest porównanie konfiguracji z prostym projektem testowym. Jeżeli nowy projekt przywraca zależności bez trudności, podejrzenie kieruje się na pliki rozwiązania, lokalne reguły lub wpisy specyficzne dla danego repozytorium. Jeżeli problem występuje wszędzie, należy sprawdzić ustawienia użytkownika, dostęp do źródeł oraz instalację SDK. W przypadku prywatnych repozytoriów należy również zweryfikować, czy token lub poświadczenia są nadal ważne i czy zostały zapisane w sposób akceptowany przez używane narzędzie.

Nie powinno się bezrefleksyjnie usuwać wszystkich plików konfiguracyjnych. Mogą one zawierać wymagane źródła, reguły wersjonowania, ustawienia proxy albo informacje potrzebne innym projektom. Bezpieczniejsze jest wykonanie kopii, odnotowanie zawartości i zmiana pojedynczego elementu, po której można sprawdzić rezultat.

Restore NuGet nie działa przy konflikcie wersji i pamięci podręcznej

Drugą grupę przyczyn stanowią konflikty zależności. Jeden pakiet może wymagać konkretnej wersji innej biblioteki, podczas gdy projekt lub kolejna paczka wskazuje zakres wzajemnie się wykluczający. Komunikat o niezgodnych zależnościach może być długi, dlatego warto znaleźć w nim pierwszą wskazaną paczkę oraz fragment opisujący wymagany zakres wersji. Ostatnia linia błędu często jest tylko skutkiem wcześniejszego konfliktu.

Znaczenie ma format zapisu zależności. W starszych projektach informacje mogą znajdować się bezpośrednio w pliku projektu lub w osobnym pliku z listą pakietów. W nowszych rozwiązaniach wersje bywają zarządzane centralnie, a reguły mogą być zapisane w pliku obejmującym wiele projektów. Mieszanie tych metod bez zrozumienia ich kolejności może prowadzić do sytuacji, w której jedna część rozwiązania korzysta z innej wersji niż pozostałe.

Pomocne bywa wyczyszczenie pamięci podręcznej NuGet, ale powinno być traktowane jako działanie diagnostyczne, a nie uniwersalne lekarstwo. Pamięć podręczna może zawierać pobrane paczki, metadane i informacje o błędach. Jej uszkodzenie albo niepełny zapis może powodować powtarzające się niepowodzenia. Po wyczyszczeniu konieczne staje się ponowne pobranie składników, więc rezultat zależy również od dostępności źródeł i stabilności połączenia.

Przed zmianą zależności warto zachować pliki projektu oraz zanotować wersję środowiska, z której korzystano. Aktualizacja wszystkich pakietów naraz utrudnia ustalenie, co usunęło błąd, a co wprowadziło następny. Lepszym podejściem jest ustalenie paczki powodującej konflikt, sprawdzenie jej wymagań i dopiero wtedy dobranie zgodnej wersji.

Restore NuGet nie działa — typowe objawy i testy

Objawem może być czerwone podkreślenie nazw klas, brak podpowiedzi w edytorze, komunikat o nieodnalezionym pliku projektu lub zatrzymanie procesu na etapie pobierania. Czasem przywracanie kończy się pozornie poprawnie, lecz kompilacja nadal nie widzi bibliotek. W takiej sytuacji warto odróżnić problem samego NuGet od problemu indeksowania projektu przez środowisko programistyczne. Zamknięcie edytora, usunięcie tymczasowych danych rozwiązania i ponowne otwarcie projektu może ujawnić, czy zależności zostały faktycznie pobrane.

Podstawowe testy powinny być wykonywane w ustalonej kolejności. Najpierw sprawdza się, czy polecenie jest uruchamiane w katalogu zawierającym właściwy plik rozwiązania lub projektu. Następnie należy odczytać pełny log, a nie tylko skrócony komunikat pokazany w interfejsie. Kolejnym krokiem jest sprawdzenie wersji SDK, aktywnego profilu środowiska oraz źródeł pakietów. Warto także zweryfikować, czy katalog projektu nie znajduje się w lokalizacji objętej ograniczeniami zapisu.

Przy problemach sieciowych trzeba rozważyć działanie zapory, serwera pośredniczącego, kontroli certyfikatów oraz oprogramowania zabezpieczającego. Błąd certyfikatu może wyglądać podobnie do niedostępnego źródła, ale jego przyczyna leży w zaufaniu do połączenia lub nieprawidłowej dacie systemowej. Z kolei kod odpowiedzi wskazujący brak autoryzacji sugeruje problem z logowaniem, a nie z samą paczką.

Warto zachować dokładny komunikat, fragment pliku projektu, zawartość istotnych ustawień oraz wynik polecenia uruchomionego z pełnym logowaniem. Takie informacje pozwalają szybciej rozdzielić błąd konfiguracji od błędu sieci, uszkodzonej pamięci podręcznej lub konfliktu wersji.

Kiedy zgłosić Restore NuGet do serwisu komputerowego

Do serwisu można zgłosić się wtedy, gdy przywracanie pakietów nie działa mimo sprawdzenia źródeł, konfiguracji, dostępu do sieci i wersji SDK, a sam komunikat jest niejednoznaczny lub zmienia się po kolejnych próbach. Wskazaniem do konsultacji jest także sytuacja, w której problem występuje w kilku projektach, narzędzia nie zapisują zmian, system zgłasza błędy dostępu do katalogów albo instalacja środowiska programistycznego zachowuje się niestabilnie.

W Warszawskim Pogotowiu Komputerowym 24/7 można rozpocząć od darmowej diagnozy laptopa, podczas której analizuje się objawy, konfigurację, logi oraz zachowanie narzędzi. Przed przekazaniem urządzenia dobrze przygotować kopię projektu, listę wykonywanych poleceń i informację, czy rozwiązanie działało wcześniej. Nie należy udostępniać haseł ani kluczy dostępowych w plikach przesyłanych do analizy; w razie potrzeby można zastąpić je bezpiecznymi przykładami.

Jeżeli błąd pojawił się po aktualizacji, warto wskazać przybliżony moment zmiany i wersję zainstalowanych składników. Jeżeli występuje wyłącznie w jednym projekcie, pomocne będzie przekazanie minimalnego przykładu reprodukującego problem. Jeżeli natomiast nie działa także tworzenie i przywracanie nowego, pustego projektu, większą uwagę należy skierować na środowisko systemowe, ustawienia sieciowe i instalację narzędzi.

Po usunięciu przyczyny zaleca się wykonanie ponownego przywracania, kompilacji oraz uruchomienia testów projektu. Warto również zapisać działającą konfigurację i odnotować wersje SDK oraz pakietów. Ułatwia to późniejsze odtworzenie środowiska i ogranicza ryzyko powrotu problemu po kolejnej zmianie ustawień.