Get-Help nie działa w PowerShell Core

Get-Help nie działa w PowerShell Core wskazuje na brak pobranych plików pomocy — trzeba je zainstalować poleceniem Update-Help, ponieważ nie są dołączone domyślnie.

Get-Help nie działa w PowerShell Core — co oznacza ten problem

Komunikat sugerujący, że polecenie Get-Help nie działa w PowerShell Core, najczęściej nie oznacza uszkodzenia samego interpretera ani błędnej instalacji powłoki. Zwykle problem wynika z tego, że lokalny system nie ma jeszcze pobranych plików pomocy dla używanych poleceń, modułów i dostawców. W przeciwieństwie do starszych środowisk, w których część dokumentacji mogła być dostępna od razu, PowerShell Core korzysta z oddzielnego mechanizmu aktualizowania materiałów pomocy.

Podstawowym poleceniem służącym do pobrania dokumentacji jest Update-Help. Można je uruchomić w konsoli PowerShell:

Update-Help

Po zakończeniu operacji polecenie Get-Help powinno zacząć zwracać opisy składni, parametrów, przykładów oraz sposobu używania dostępnych komend. Do sprawdzenia konkretnego polecenia można użyć na przykład:

Get-Help Get-Process
Get-Help Get-Process -Examples
Get-Help Get-Process -Full

Jeżeli dokumentacja została pobrana, ale nadal nie jest wyświetlana w oczekiwany sposób, przyczyną może być niepełna instalacja materiałów dla konkretnego modułu, uruchomienie innej wersji PowerShell niż ta, w której wykonano aktualizację, albo ograniczony dostęp do zasobów internetowych. Warto pamiętać, że pomoc jest powiązana z modułami oraz ich wersjami. Zainstalowanie nowego modułu nie zawsze oznacza automatyczne pobranie jego pełnej dokumentacji.

Kontekst techniczny: PowerShell Core, moduły i lokalna dokumentacja

PowerShell Core, rozwijany obecnie jako wieloplatformowy PowerShell, działa na Windows, Linuxie i macOS, ale w tym materiale analizowany jest wyłącznie problem związany z działaniem powłoki i jej modułów, bez traktowania systemu jako usługi serwisowej dla urządzeń Apple. Polecenie Get-Help jest elementem środowiska PowerShell odpowiedzialnym za odczytywanie lokalnych plików pomocy. Nie pobiera ono automatycznie całej dokumentacji przy każdym użyciu, ponieważ takie rozwiązanie zwiększałoby zależność od połączenia z internetem i spowalniało codzienną pracę.

W praktyce można rozróżnić kilka warstw dokumentacji:

• pomoc dotycząca poleceń wbudowanych w środowisko PowerShell,
• dokumentacja dostarczana razem z określonym modułem,
• przykłady i pełne opisy parametrów,
• zewnętrzne materiały internetowe, do których można przejść za pomocą -Online.

Przykładowo, polecenie:

Get-Help Get-Service

może zwrócić jedynie podstawowy komunikat albo informację o braku zainstalowanej pomocy, podczas gdy:

Get-Help Get-Service -Online

próbuje otworzyć dokumentację internetową. Druga forma nie zastępuje jednak lokalnego Update-Help. Do działania wariantu online wymagane jest prawidłowe połączenie z siecią, dostęp do przeglądarki oraz możliwość dotarcia do wskazanej witryny. Dokumentacja lokalna jest przydatna także wtedy, gdy praca odbywa się bez dostępu do internetu.

W niektórych przypadkach aktualizację trzeba wykonać z podwyższonymi uprawnieniami, szczególnie gdy pliki pomocy mają zostać zapisane w katalogu wymagającym praw administratora. Można wtedy uruchomić PowerShell jako administrator i powtórzyć:

Update-Help

Jeżeli występują błędy dotyczące niezgodności języka, można wskazać dostępne kultury pomocy lub zaktualizować dokumentację dla modułów, które mają ją udostępniać. Warto również sprawdzić, z jakiej wersji powłoki korzysta bieżąca sesja:

$PSVersionTable
$PSHOME
Get-Module -ListAvailable

Takie informacje pozwalają ustalić, czy aktualizacja została wykonana w tym samym środowisku, w którym później używane jest Get-Help. Częstym źródłem nieporozumień jest równoczesna obecność Windows PowerShell oraz PowerShell Core. Obie powłoki mogą mieć osobne katalogi, moduły i pliki dokumentacji, dlatego wykonanie polecenia w jednej z nich nie musi naprawić sytuacji w drugiej.

Typowe problemy, błędy i sposoby ich rozpoznania - Get-Help nie działa w PowerShell Core

Najczęstszy scenariusz polega na uruchomieniu Get-Help bez wcześniejszego wykonania Update-Help. Wtedy można zobaczyć informację o braku plików pomocy albo ograniczony opis polecenia. Jest to stan konfiguracyjny, a niekoniecznie awaria programu. Połączenie z internetem może być potrzebne wyłącznie na etapie pobierania dokumentacji, natomiast samo odczytywanie pobranych plików odbywa się lokalnie.

Drugą grupę przyczyn stanowią problemy sieciowe. Aktualizacja może nie dojść do skutku, gdy połączenie jest filtrowane przez zaporę, serwer proxy, ochronę DNS albo reguły obowiązujące w danej sieci. W takiej sytuacji warto zwrócić uwagę na pełny komunikat błędu, ponieważ sam tekst informujący o niedziałającym Get-Help może ukrywać właściwą przyczynę. Pomocne bywa także sprawdzenie, czy inne polecenia wymagające dostępu do sieci działają poprawnie.

Możliwe jest również wystąpienie błędu uprawnień. Jeżeli aktualizacja nie może zapisać plików w wybranej lokalizacji, należy sprawdzić, czy bieżące konto ma odpowiednie prawa, albo wykonać operację w sesji uruchomionej z uprawnieniami administratora. Nie powinno się jednak automatycznie nadawać szerokich uprawnień wszystkim użytkownikom ani zmieniać zabezpieczeń systemu bez rozpoznania komunikatu.

Problem może dotyczyć wyłącznie jednego modułu. Jeżeli:

Get-Help Get-Process

zwraca informacje, ale pomoc dla polecenia pochodzącego z dodatkowego modułu jest niedostępna, należy sprawdzić, czy moduł jest zainstalowany i załadowany:

Get-Module
Get-Module -ListAvailable
Get-Command -Name Nazwa-Polecenia

Warto zweryfikować także poprawność nazwy polecenia. Literówka, pomylenie aliasu z nazwą pełną albo użycie komendy dostępnej tylko w innym module może wyglądać jak awaria systemu pomocy. Przydatne są wtedy polecenia wyszukujące dostępne komendy:

Get-Command *process*
Get-Command -Module Nazwa-Modułu

Inny przypadek dotyczy komunikatów o braku pasującego tematu pomocy. Może to oznaczać, że dokumentacja dla danego polecenia nie została dostarczona przez autora modułu, a nie że mechanizm Get-Help przestał działać. Przydatne jest wówczas sprawdzenie polecenia z parametrem -Online, przejrzenie dokumentacji modułu albo zweryfikowanie jego aktualnej wersji.

Do diagnostyki można użyć także bardziej szczegółowych wariantów:

Get-Help Update-Help -Detailed
Get-Help about_*
Get-Help Nazwa-Polecenia -ShowWindow

Tematy zaczynające się od about_ opisują ogólne zagadnienia języka i środowiska, takie jak potoki, zmienne, zakresy, formatowanie czy obsługa błędów. Jeżeli nie działają również te tematy, problem może mieć szerszy charakter i dotyczyć lokalizacji plików pomocy, instalacji PowerShell albo bieżącej sesji.

Kiedy trzeba zlecić diagnozę specjalistom - Get-Help nie działa w PowerShell Core

Sam brak wyników z Get-Help zwykle można usunąć przez aktualizację dokumentacji, jednak zgłoszenie do serwisu staje się zasadne, gdy problem występuje razem z innymi objawami. Dotyczy to między innymi nieuruchamiania PowerShell Core, zamykania konsoli bez komunikatu, błędów odczytu wielu modułów, niemożności instalowania aktualizacji, uszkodzeń profilu użytkownika albo powtarzających się problemów z uprawnieniami i połączeniem sieciowym.

Przed przekazaniem sprzętu do sprawdzenia warto zanotować pełną treść komunikatu, używaną wersję PowerShell, polecenie, które wywołało błąd, oraz informację, czy problem występuje na jednym koncie, czy na wszystkich kontach systemu. Takie dane ułatwiają rozdzielenie usterki samego środowiska PowerShell od problemu z konfiguracją systemu, profilem użytkownika, ochroną sieciową lub modułem zewnętrznym.

W przypadku laptopa w Warszawie można skorzystać z serwisu Warszawskie Pogotowie Komputerowe 24/7, gdzie przewidziano darmową diagnozę laptopa. Podczas takiej weryfikacji można sprawdzić nie tylko konfigurację PowerShell Core, lecz także stan systemu, działanie usług, uprawnienia użytkownika, profile powłoki oraz zależności modułów. Przydatne jest przekazanie informacji, czy Update-Help kończy się błędem, czy tylko nie przynosi widocznego rezultatu, ponieważ oba przypadki mogą wymagać innego sposobu postępowania.

Jeżeli po aktualizacji dokumentacji nadal wyświetlany jest błąd, nie powinno się usuwać przypadkowych katalogów PowerShell ani modyfikować zmiennych środowiskowych bez kopii ustawień i rozpoznania zależności. Bezpieczniejsze jest najpierw ustalenie wersji powłoki, lokalizacji modułów, poziomu uprawnień i rodzaju komunikatu. Dopiero na tej podstawie można zdecydować, czy wystarczy ponowne pobranie pomocy, naprawa konfiguracji, reinstalacja konkretnego modułu, czy szersza diagnostyka systemu.