Moduł niekompatybilny z daną wersją PowerShell

Moduł niekompatybilny z daną wersją PowerShell wskazuje na różnicę między PowerShell 5.1 (Windows) a PowerShell 7+ (wieloplatformowy) w obsłudze niektórych cmdletów.

Na czym polega niekompatybilność modułu z wersją PowerShell

Komunikat o niekompatybilności modułu z daną wersją PowerShell oznacza, że dodatek przeznaczony do rozszerzania powłoki nie może poprawnie współpracować z aktualnie uruchomionym środowiskiem. Moduł może zawierać polecenia, funkcje, klasy, biblioteki lub mechanizmy uwierzytelniania wymagające określonej generacji PowerShell, konkretnego systemu operacyjnego albo wskazanej wersji platformy .NET. Sam fakt, że moduł został zainstalowany, nie przesądza więc o tym, że będzie można go zaimportować i używać bez dodatkowych zmian.

Najczęściej porównuje się Windows PowerShell 5.1 z nowszym PowerShell 7.x. Pierwsze środowisko jest związane przede wszystkim z systemem Windows i starszym sposobem ładowania rozszerzeń, natomiast PowerShell 7 rozwija nowocześniejszy, wieloplatformowy model działania. Część modułów działa w obu środowiskach, część korzysta z mechanizmu zgodności, a pozostałe wymagają aktualizacji, zastąpienia innym dodatkiem albo uruchomienia w odpowiedniej wersji powłoki. Niezgodność może zostać zgłoszona już przy imporcie modułu lub dopiero po wywołaniu konkretnego polecenia.

Dlaczego wersja PowerShell ma znaczenie

Każdy moduł deklaruje lub pośrednio zakłada określone warunki uruchomienia. W pliku manifestu może znajdować się informacja o minimalnej wersji PowerShell, wymaganej wersji środowiska wykonawczego, systemie operacyjnym albo zależnościach od innych modułów. Jeżeli bieżąca powłoka nie spełnia któregoś z tych warunków, import może zakończyć się błędem. Problem może również wynikać z tego, że moduł używa poleceń dostępnych tylko w jednym wydaniu albo odwołuje się do bibliotek, których nie ma w danym środowisku.

Warto rozróżnić kilka sytuacji:

• moduł przeznaczony wyłącznie dla Windows PowerShell 5.1 może wymagać uruchomienia starszej powłoki zamiast PowerShell 7;
• moduł przygotowany dla PowerShell 7 może nie działać w wersji 5.1, zwłaszcza gdy wykorzystuje nowsze polecenia lub biblioteki;
• moduł może być formalnie zgodny, ale wymagać określonego systemu operacyjnego albo dodatkowych zależności;
• moduł może działać częściowo, gdy tylko niektóre cmdlety lub funkcje zostały zaprojektowane dla innej wersji;
• niezgodność może dotyczyć również architektury środowiska, sposobu instalacji dodatku lub konfliktu kilku jego wydań.

Przydatne jest sprawdzenie uruchomionej wersji poleceniem $PSVersionTable, a następnie odczytanie informacji o module za pomocą Get-Module -ListAvailable. W zależności od potrzeb można też zweryfikować manifest modułu, jego wymagania oraz miejsce instalacji. Sama reinstalacja bez ustalenia przyczyny często nie rozwiązuje problemu, ponieważ ponownie instalowany jest ten sam niepasujący wariant.

Typowe objawy i błędy - Moduł niekompatybilny z daną wersją PowerShell

Niekompatybilność może objawiać się na kilka sposobów. Podczas wykonywania Import-Module może pojawić się informacja, że moduł wymaga innej wersji PowerShell, nie znaleziono wymaganej biblioteki albo nie można załadować określonego typu. Innym sygnałem jest brak poleceń po pozornie prawidłowym zaimportowaniu dodatku. W takim przypadku Get-Command nie zwraca oczekiwanych cmdletów lub wskazuje, że funkcja nie jest rozpoznawana.

Częste są także błędy dotyczące zależności. Moduł może wymagać innego dodatku w określonej wersji, a nowsze wydanie zależności może zmieniać sposób działania poleceń. W środowisku Windows mogą wystąpić ograniczenia związane ze starszymi bibliotekami, polityką wykonywania skryptów albo sposobem ładowania komponentów. W PowerShell 7 problemem bywa z kolei użycie poleceń lub interfejsów dostępnych wyłącznie w Windows PowerShell. Zdarza się również, że w systemie znajdują się dwie kopie modułu w różnych katalogach, przez co ładowana jest wersja inna niż oczekiwana.

Przed zmianą konfiguracji warto zapisać pełną treść błędu, sprawdzić wynik Get-Module -ListAvailable NazwaModułu oraz ustalić, z której powłoki uruchamiany jest skrypt. Należy również zweryfikować, czy moduł ma wydanie przeznaczone dla bieżącej wersji PowerShell. Pomocne może być uruchomienie go w środowisku wskazanym przez autora, ale nie powinno się automatycznie usuwać działających modułów ani zmieniać globalnych ustawień systemowych bez kopii konfiguracji.

Kiedy zgłosić problem do serwisu - Moduł niekompatybilny z daną wersją PowerShell

Zgłoszenie do serwisu jest uzasadnione, gdy komunikat o niekompatybilności powtarza się mimo użycia właściwej wersji modułu, gdy skrypt przestał działać po aktualizacji systemu lub gdy nie wiadomo, która z kilku zainstalowanych powłok jest uruchamiana. Wymaga to czasem uporządkowania ścieżek modułów, sprawdzenia zależności, odtworzenia konfiguracji oraz rozdzielenia środowiska potrzebnego dla starszych i nowszych skryptów. Szczególnej ostrożności wymaga sytuacja, w której PowerShell jest używany do automatyzacji zadań systemowych, obsługi kont użytkowników lub wykonywania skryptów pobieranych z zewnętrznych źródeł.

W Warszawie takie problemy można przekazać do Warszawskiego Pogotowia Komputerowego 24/7, opisując wersję PowerShell, nazwę modułu, pełny tekst błędu i moment, w którym pojawia się nieprawidłowość. Pozwala to rozpocząć diagnostykę od sprawdzenia środowiska, zamiast ograniczać się do ponownej instalacji dodatku. Naprawy są zazwyczaj realizowane w ciągu trzech dni roboczych, zależnie od zakresu koniecznych czynności i dostępności informacji o używanej konfiguracji.