Środowisko .NET nie działa w WSL

Środowisko .NET niedziałające w WSL wskazuje na brak zainstalowanego SDK dla Linuksa wewnątrz dystrybucji, niezależnego od wersji Windows.

Środowisko .NET w WSL — czym jest problem

Komunikat „Środowisko .NET nie działa w WSL” oznacza zwykle, że polecenia związane z platformą .NET nie są dostępne albo nie uruchamiają się poprawnie wewnątrz dystrybucji Linuksa działającej przez Windows Subsystem for Linux. WSL tworzy odrębne środowisko użytkownika, z własnym systemem plików, menedżerem pakietów, zmiennymi środowiskowymi i zestawem programów. Sam fakt, że w systemie Windows zainstalowano narzędzia .NET, nie gwarantuje ich obecności w WSL. Windows i dystrybucja linuksowa mogą korzystać z innych katalogów, innych wersji bibliotek oraz odmiennych ustawień powłoki.

W praktyce problem może objawiać się komunikatem o nierozpoznaniu polecenia dotnet, błędem braku odpowiedniego SDK, nieudaną kompilacją projektu albo informacją, że wymagany runtime nie został znaleziony. Znaczenie ma także rodzaj używanego projektu. Do tworzenia i budowania aplikacji potrzebne jest SDK, natomiast do uruchamiania gotowej aplikacji wystarczający może być odpowiedni runtime. Te składniki nie są zamienne, dlatego zainstalowanie samego środowiska uruchomieniowego nie zawsze rozwiązuje problem.

Środowisko .NET i WSL — różnice między Windows a Linuksem

WSL należy traktować jako osobny obszar roboczy. Polecenie wpisane w terminalu Windows może zwracać poprawną wersję .NET, podczas gdy identyczne polecenie wykonane w powłoce Ubuntu lub innej dystrybucji WSL zakończy się błędem. Wynika to z odrębnego mechanizmu wyszukiwania programów. Każdy proces korzysta ze zmiennej PATH, która określa katalogi przeszukiwane podczas uruchamiania polecenia. Wartość tej zmiennej w Windows nie musi odpowiadać wartości dostępnej w Linuksie.

Istotna jest również architektura instalacji. Pakiety przeznaczone dla Windows nie są tym samym co pakiety dla Linuksa. W dystrybucji WSL można użyć menedżera pakietów, skryptu instalacyjnego dostawcy platformy albo repozytorium dopasowanego do konkretnej wersji dystrybucji. Przy wyborze instrukcji należy sprawdzić nazwę dystrybucji, jej wydanie oraz architekturę procesora. Skopiowanie przypadkowej komendy z poradnika dla innego wydania systemu może doprowadzić do konfliktu pakietów, niepełnej instalacji lub problemów z aktualizacją.

Różnice dotyczą także ścieżek. Pliki Windows są widoczne w WSL zwykle pod katalogiem /mnt, natomiast projekty przechowywane w linuksowym systemie plików mają inną ścieżkę i inne zasady dostępu. Projekt umieszczony na zamontowanym dysku Windows może działać wolniej lub zachowywać się inaczej niż projekt znajdujący się w katalogu domowym użytkownika WSL. Przy pracy z narzędziami .NET korzystne bywa uporządkowanie położenia kodu, plików zależności i katalogów wynikowych, aby ograniczyć problemy z uprawnieniami oraz wielkością liter w nazwach.

Środowisko .NET nie działa w WSL — typowe przyczyny

• Brak pakietu SDK w dystrybucji WSL. W takim przypadku próba wykonania dotnet --info może zakończyć się komunikatem o nieznanym poleceniu albo wskazywać, że dostępny jest tylko inny składnik środowiska.

• Nieprawidłowa wersja SDK. Plik projektu może wymagać konkretnej głównej wersji platformy, a zainstalowana wersja może być starsza lub nowsza. Warto sprawdzić plik global.json, ponieważ może on wymuszać określone SDK.

• Błędna zmienna PATH. Program może znajdować się na dysku, ale jego katalog nie został dodany do ścieżki wyszukiwania. Czasem przyczyną jest ręczna modyfikacja plików powłoki, takich jak .bashrc lub .profile.

• Niekompletna instalacja zależności. Projekt może wymagać narzędzi systemowych, bibliotek natywnych albo pakietów używanych podczas kompilacji. Brak jednego z nich może być widoczny dopiero przy poleceniu dotnet restore lub dotnet build.

• Konflikt kilku instalacji .NET. Pozostałości po starszym sposobie instalacji mogą kierować polecenie do innego katalogu niż oczekiwany. Wtedy wersja wyświetlana w terminalu nie musi odpowiadać wersji, z której korzysta projekt.

• Problem z uprawnieniami do katalogu projektu. Pliki utworzone wcześniej z podwyższonymi uprawnieniami mogą nie być możliwe do zmodyfikowania przez zwykłego użytkownika.

• Niepoprawna konfiguracja narzędzia edytora kodu. Edytor uruchomiony w Windows może korzystać z innego środowiska niż terminal otwarty wewnątrz WSL. Dotyczy to zwłaszcza wyboru zestawu SDK, ścieżki projektu oraz automatycznego uruchamiania poleceń.

Do rozpoznania przyczyny przydatne są polecenia which dotnet, dotnet --info, dotnet --list-sdks oraz dotnet --list-runtimes. Pierwsze pokazuje, z jakiej lokalizacji jest uruchamiany program, a kolejne dostarczają informacji o zainstalowanych składnikach i ich wersjach. Należy wykonywać je bezpośrednio w tej dystrybucji WSL, w której ma działać projekt.

Środowisko .NET w WSL — praktyczne wskazówki diagnostyczne

Najpierw warto ustalić, czy problem dotyczy samego polecenia, projektu czy konkretnego procesu uruchamiania. Po otwarciu dystrybucji należy sprawdzić wersję systemu, aktualnego użytkownika oraz bieżący katalog. Następnie można wykonać dotnet --info i zapisać pełny wynik, ponieważ zawiera on informacje o systemie operacyjnym, architekturze, ścieżkach oraz wykrytych wersjach SDK i runtime. Sam skrócony komunikat z końca błędu często nie wystarcza do odróżnienia brakującego pakietu od błędnej konfiguracji.

Jeżeli polecenie nie jest rozpoznawane, należy zweryfikować sposób instalacji przeznaczony dla Linuksa i konkretnej dystrybucji WSL. Przed ponowną instalacją dobrze jest ustalić, czy nie istnieje już druga kopia programu. Wielokrotne instalowanie bez sprawdzenia ścieżek może utrudnić ustalenie, z którego katalogu system pobiera plik wykonywalny. W razie potrzeby należy uporządkować wpisy w PATH, uruchomić ponownie powłokę i ponowić test wersji.

Gdy polecenie działa, ale projekt nadal się nie buduje, warto przejść do kontroli pliku projektu oraz pliku global.json. Należy sprawdzić, czy wskazana wersja SDK jest obecna w WSL i czy projekt nie korzysta z zależności wymagających dodatkowych bibliotek. Pomocne może być wyczyszczenie katalogów wynikowych projektu, ponowne przywrócenie pakietów oraz uruchomienie budowania z większą ilością informacji diagnostycznych. Nie powinno się jednak usuwać plików konfiguracyjnych ani zmieniać wersji platformy bez kopii zapasowej i sprawdzenia wymagań projektu.

Ważne jest rozdzielenie problemów środowiskowych od problemów aplikacji. Jeżeli prosty projekt utworzony poleceniem dotnet new buduje się prawidłowo, przyczyny należy szukać w konfiguracji konkretnego projektu, dodatkowych paczkach, ścieżkach lub uprawnieniach. Jeżeli nie działa także prosty test, większe znaczenie ma instalacja SDK, konfiguracja dystrybucji WSL albo integracja terminala z systemem Windows.

Środowisko .NET nie działa w WSL — kiedy zgłosić się do serwisu

Pomoc serwisowa jest uzasadniona, gdy problem powtarza się po sprawdzeniu wersji SDK, ścieżek i konfiguracji dystrybucji, a komunikaty wskazują na szersze nieprawidłowości systemu. Dotyczy to również sytuacji, w której WSL nie uruchamia dystrybucji, nie można zaktualizować pakietów, terminal zamyka się podczas wykonywania poleceń albo występują równoczesne błędy w kilku narzędziach programistycznych. Przed przekazaniem urządzenia warto przygotować nazwę używanej dystrybucji, wynik polecenia dotnet --info, treść błędu oraz informację, czy problem pojawia się w Windows, w WSL, czy w obu środowiskach.

W Warszawie diagnozę i naprawę sprzętu oraz konfigurację oprogramowania można zgłosić do Warszawskiego Pogotowia Komputerowego 24/7 pod numerem +48 22 100 48 29. Przy analizie takiego przypadku sprawdza się między innymi stan systemu Windows, działanie WSL, dostępność dystrybucji, ścieżki do plików .NET, zgodność wersji SDK z projektem oraz uprawnienia do katalogów roboczych. Takie uporządkowane rozpoznanie pozwala ustalić, czy wystarczy korekta konfiguracji, czy potrzebne jest szersze uporządkowanie środowiska systemowego.