Projekty crashują po zmianie wersji .NET

Projekty crashujące po zmianie wersji .NET wskazują na niekompatybilność pakietów NuGet z nowym docelowym frameworkiem.

Dlaczego zmiana wersji .NET może zakończyć się awarią projektu

Komunikat „projekt crashuje po zmianie wersji .NET” nie opisuje jednej konkretnej usterki. Zmiana może dotyczyć docelowego frameworka wpisanego w pliku projektu, zainstalowanego środowiska uruchomieniowego albo wersji zestawu .NET SDK używanego przez polecenia dotnet. Każdy z tych elementów wpływa na sposób przywracania pakietów NuGet, kompilowania kodu i uruchamiania aplikacji. Przykładowo projekt może być kierowany na net6.0, podczas gdy na komputerze znajduje się tylko runtime .NET 8.0. Taka konfiguracja nie zawsze jest równoważna, ponieważ nowszy runtime nie musi zastępować starszego środowiska dla każdej aplikacji i każdego typu projektu.

Objaw może pojawić się na różnych etapach. Podczas kompilacji występują błędy braku przestrzeni nazw, typów lub metod, gdy pakiet nie udostępnia wersji zgodnej z nowym frameworkiem. Podczas uruchamiania pojawiają się między innymi wyjątki FileNotFoundException, TypeLoadException, MissingMethodException albo komunikat o niemożności załadowania zestawu. W aplikacji graficznej lub usłudze taki wyjątek może zostać odebrany jako nagłe zamknięcie programu, choć rzeczywistą przyczyną jest nieudane ładowanie zależności.

Kompatybilność pakietów NuGet z Target Framework Moniker

Najważniejszym punktem porównania jest wartość TargetFramework lub TargetFrameworks w pliku .csproj. Jest to deklaracja platformy, dla której projekt ma zostać zbudowany, na przykład net6.0, net8.0 albo netstandard2.0. Pakiet NuGet może zawierać biblioteki przeznaczone dla kilku frameworków albo tylko dla wybranych. Przy przywracaniu zależności mechanizm NuGet wybiera zgodną grupę plików, a jeśli jej nie znajdzie, może użyć zgodności zastępczej lub zgłosić ostrzeżenie. Ostrzeżenie nie zawsze kończy proces, ale może oznaczać, że biblioteka została zbudowana dla innego zestawu API.

Szczególnej uwagi wymagają pakiety zależne od konkretnego modelu hostingu, serializacji, dostępu do bazy danych, interfejsu graficznego lub natywnych bibliotek systemowych. Aktualizacja frameworka może zmienić wersję zależności tranzytywnych, czyli pakietów instalowanych pośrednio przez inne pakiety. Dwa bezpośrednie odwołania zapisane w projekcie mogą więc doprowadzić do innego drzewa zależności po zmianie SDK lub usunięciu pliku packages.lock.json. Jeżeli jedna biblioteka wymaga starszej wersji wspólnego komponentu, a druga nowszej, konflikt może ujawnić się dopiero przy uruchomieniu.

Ślad diagnostyczny: od pliku projektu do rzeczywistego wyjątku

Analizę warto rozpocząć od zapisania stanu środowiska poleceniem dotnet --info. Wynik pokazuje między innymi wersję SDK, zainstalowane runtime’y oraz system operacyjny. Następnie można użyć dotnet list package --include-transitive, aby zobaczyć także zależności pośrednie, oraz dotnet list package --outdated, aby sprawdzić dostępne aktualizacje. Samo podniesienie wszystkich pakietów do najnowszych wersji nie jest jednak bezpieczną metodą naprawy, ponieważ może wprowadzić kolejne zmiany API. Lepiej ustalić, który pakiet przestał być zgodny i dobrać jego wersję do docelowego frameworka.

Po zmianie pliku projektu należy wykonać kontrolowane przywrócenie i kompilację, na przykład dotnet restore, a następnie dotnet build. Jeżeli podejrzewane są stare artefakty, można usunąć katalogi bin i obj, po czym powtórzyć te operacje. Wygenerowany plik obj/project.assets.json pozwala sprawdzić, jakie wersje bibliotek zostały faktycznie wybrane. Przy awarii po uruchomieniu trzeba odczytać pełny wyjątek wraz ze stosu wywołań, a nie tylko ostatnią linię komunikatu. Należy też porównać konfigurację uruchomieniową, architekturę procesu x86 lub x64 oraz obecność wymaganych bibliotek natywnych.

Przywrócenie działania projektu i sprawdzenie komputera

Naprawa powinna zaczynać się od ustalenia ostatniej działającej kombinacji: wersji SDK, wartości docelowego frameworka, pliku blokady zależności i wersji pakietów. Jeżeli problem pojawił się po zmianie z jednego frameworka na drugi, pomocne bywa tymczasowe przywrócenie poprzedniego TargetFramework i potwierdzenie, że aplikacja znów się buduje. Następnie można aktualizować pojedyncze pakiety, sprawdzając dokumentację ich wersji oraz ostrzeżenia kompilatora. W przypadku aplikacji korzystającej z kilku projektów należy zweryfikować, czy wszystkie projekty rozwiązania używają zgodnych frameworków i czy biblioteka klas nie wymaga platformy niedostępnej dla projektu startowego.

Warszawskie Pogotowie Komputerowe zajmuje się profesjonalną naprawą laptopów, komputerów PC i ich podzespołów, dlatego w przypadku awarii środowiska programistycznego można sprawdzić także stan systemu, instalację wymaganych komponentów .NET, konfigurację użytkownika oraz poprawność działania samego komputera. Taka kontrola pomaga odróżnić błąd zgodności projektu od problemu lokalnego, takiego jak uszkodzone pliki narzędzi, niepełne przywrócenie pakietów, niewłaściwa architektura procesu albo brak konkretnego runtime’u. Ostateczny wniosek powinien wynikać z powtarzalnego testu: ta sama wersja kodu, ta sama konfiguracja projektu, zapisany wynik kompilacji i pełny komunikat wyjątku.