Szablony .NET niedziałające po aktualizacji wskazują na niekompatybilność wersji SDK z docelowym frameworkiem projektu.
Dlaczego szablon .NET przestaje działać po aktualizacji
Problem z niedziałającym szablonem .NET po aktualizacji najczęściej wynika z rozbieżności między zainstalowanym zestawem .NET SDK, wersją używanego szablonu oraz docelowym frameworkiem projektu. Szablon jest mechanizmem dostarczanym przez SDK lub dodatkowy pakiet szablonów i służy do wygenerowania początkowej struktury aplikacji. Polecenie dotnet new korzysta z SDK wybranego przez środowisko uruchomieniowe, dlatego aktualizacja może zmienić dostępne szablony, ich parametry albo sposób interpretowania pliku projektu.
Nie każda aktualizacja .NET usuwa istniejące projekty, ale może zmienić domyślną wersję SDK używaną przy tworzeniu nowych. Jeżeli projekt lub skrypt oczekuje określonego parametru szablonu, a nowsza wersja go nie obsługuje albo zastąpiła go inną opcją, polecenie może zakończyć się komunikatem o nieznanym przełączniku. Innym przypadkiem jest brak szablonu na liście, mimo że wcześniej był dostępny. Przyczyną może być usunięcie nieaktualnego pakietu, zmiana kanału instalacji SDK albo użycie innego środowiska systemowego niż przed aktualizacją.
Wersja SDK, global.json i framework docelowy
Podstawowym miejscem weryfikacji jest wynik polecenia dotnet --info. Pokazuje on aktywną wersję SDK, środowisko uruchomieniowe oraz lokalizacje instalacji. Polecenie dotnet --list-sdks pozwala sprawdzić, jakie zestawy SDK są faktycznie zainstalowane, natomiast dotnet new list wyświetla szablony widoczne dla bieżącego środowiska. Te informacje trzeba odnosić do pliku projektu, zwłaszcza wartości TargetFramework albo TargetFrameworks, ponieważ wersja kompilatora i wersja docelowego frameworka pełnią różne funkcje.
Wybór SDK może być kontrolowany przez plik global.json. Jeśli taki plik znajduje się w katalogu projektu albo jednym z jego katalogów nadrzędnych, .NET próbuje użyć wskazanej wersji SDK. Gdy po aktualizacji wskazana wersja nie jest już zainstalowana, polecenie może zgłosić brak zgodnego SDK zamiast uruchomić najnowsze dostępne wydanie. Znaczenie mają również ustawienia wyboru wersji, takie jak reguła dopuszczająca nowsze poprawki lub kolejne wersje funkcji. Sam fakt zainstalowania nowego SDK nie gwarantuje więc zgodności z konfiguracją projektu.
Rozpoznawanie błędu bez zmiany projektu w ciemno
Diagnostykę warto rozpocząć od odtworzenia problemu w katalogu projektu i zapisania pełnego komunikatu z polecenia dotnet new, dotnet restore albo dotnet build. Komunikat o braku szablonu wskazuje na problem z rejestracją lub instalacją szablonu. Informacja o nieobsługiwanej wersji frameworka może oznaczać, że zainstalowany SDK nie potrafi utworzyć projektu dla wskazanego celu. Z kolei błąd dotyczący pakietu NuGet, przywracania zależności albo pliku projektu pojawia się już po wygenerowaniu szablonu i nie musi oznaczać awarii samego mechanizmu szablonów.
Przed usunięciem lub ponowną instalacją elementów środowiska należy sprawdzić, czy polecenie jest wykonywane z właściwego katalogu, czy zmienna środowiskowa PATH nie wskazuje na starszą instalację oraz czy używany terminal widzi tę samą wersję dotnet co narzędzie programistyczne. Pomocne jest również polecenie dotnet new search, jeżeli szablon pochodzi z repozytorium NuGet, oraz sprawdzenie zainstalowanych pakietów szablonów. Wygenerowanie pustego projektu z wbudowanego szablonu pozwala oddzielić problem globalny, dotyczący SDK, od problemu ograniczonego do konkretnego pakietu lub konfiguracji rozwiązania.
Przywrócenie zgodności szablonu z projektem
Naprawa powinna polegać na ustaleniu jednej zgodnej kombinacji: wersji SDK, wersji pakietu szablonu i frameworka docelowego. Jeżeli projekt wymaga starszego SDK, można zainstalować odpowiednią wersję obok nowszej i jawnie określić ją w global.json, o ile pozostaje dostępna dla danego systemu. Jeżeli szablon jest dostarczany jako pakiet, należy zweryfikować jego wersję oraz sposób instalacji zgodny z dokumentacją tego pakietu. Nie powinno się automatycznie zmieniać TargetFramework, ponieważ taka zmiana może wpłynąć na zależności, kod źródłowy i obsługiwane funkcje aplikacji.
Po korekcie konfiguracji trzeba ponownie wyświetlić listę szablonów, utworzyć próbny projekt, wykonać dotnet restore i uruchomić kompilację. Jeśli projekt buduje się lokalnie, ale nie w środowisku ciągłej integracji, należy porównać wersję SDK, obecność pliku global.json oraz sposób instalowania narzędzi w obu miejscach. Warszawskie Pogotowie Komputerowe wykonuje profesjonalną naprawę laptopów i komputerów PC, w tym diagnostykę problemów z oprogramowaniem deweloperskim oraz konfiguracją środowiska .NET na komputerze użytkownika.
