about_Pwsh

  • Artykuł

Krótki opis

W tym artykule wyjaśniono, jak używać interfejsu pwsh ine polecenia-l. Wyświetla parametry ine polecenia-li opisuje składnię.

Długi opis

Aby uzyskać informacje o opcjach ine polecenia-ldla programu Windows PowerShell 5.1, zobacz about_PowerShell_exe.

Składnia

Usage: pwsh[.exe]
    [-Login]
    [[-File] <filePath> [args]]
    [-Command { - | <script-block> [-args <arg-array>]
                  | <string> [<CommandParameters>] } ]
    [[-CommandWithArgs <string>] [<CommandParameters>]]
    [-ConfigurationFile <filePath>]
    [-ConfigurationName <string>]
    [-CustomPipeName <string>]
    [-EncodedCommand <Base64EncodedCommand>]
    [-ExecutionPolicy <ExecutionPolicy>]
    [-InputFormat {Text | XML}]
    [-Interactive]
    [-MTA]
    [-NoExit]
    [-NoLogo]
    [-NonInteractive]
    [-NoProfile]
    [-NoProfileLoadTime]
    [-OutputFormat {Text | XML}]
    [-SettingsFile <filePath>]
    [-SSHServerMode]
    [-STA]
    [-Version]
    [-WindowStyle <style>]
    [-WorkingDirectory <directoryPath>]

pwsh[.exe] -h | -Help | -? | /?

Parametry

Wszystkie parametry są bez uwzględniania wielkości liter-i.

-File | -f

Jeśli wartość File to -, tekst polecenia jest odczytywany ze standardowych danych wejściowych. Uruchamianie pwsh -File - bez przekierowanych standardowych danych wejściowych uruchamia zwykłą sesję. Jest to takie samo, jak nie określa parametru File w ogóle.

Jest to parametr domyślny, jeśli nie ma żadnych parametrów, ale wartości są obecne w wierszu polecenia. Określony skrypt jest uruchamiany w zakresie lokalnym ("dot-sourced") nowej sesji, dzięki czemu funkcje i zmienne tworzone przez skrypt są dostępne w nowej sesji. Wprowadź ścieżkę pliku skryptu i wszystkie parametry. Plik musi być ostatnim parametrem w poleceniu, ponieważ wszystkie znaki wpisane po nazwie parametru pliku są interpretowane jako ścieżka pliku skryptu, a następnie parametry skryptu.

Zazwyczaj parametry przełącznika skryptu są dołączane lub pomijane. Na przykład następujące polecenie używa parametru All w pliku skryptu Get-Script.ps1: -File .\Get-Script.ps1 -All

W rzadkich przypadkach może być konieczne podanie wartości logicznej dla parametru przełącznika. Aby podać wartość logiczną parametru przełącznika w wartości parametru File , użyj parametru zwykle, po którym następuje dwukropek i wartość logiczna, na przykład: -File .\Get-Script.ps1 -All:$False.

Parametry przekazywane do skryptu są przekazywane jako ciągi literału po interpretacji przez bieżącą powłokę. Jeśli na przykład jesteś w cmd.exe lokalizacji i chcesz przekazać wartość zmiennej środowiskowej, użyj cmd.exe składni : pwsh -File .\test.ps1 -TestParam %windir%

Z kolei uruchomienie pwsh -File .\test.ps1 -TestParam $env:windir w cmd.exe wynikach skryptu odbiera ciąg $env:windir literału, ponieważ nie ma specjalnego znaczenia dla bieżącej cmd.exe powłoki. Styl $env:windir odwołania do zmiennej środowiskowej może być używany wewnątrz parametru Command , ponieważ jest on interpretowany jako kod programu PowerShell.

Podobnie, jeśli chcesz wykonać to samo polecenie ze skryptu usługi Batch, użyj polecenia %~dp0 zamiast .\ lub $PSScriptRoot do reprezentowania bieżącego katalogu wykonawczego: pwsh -File %~dp0test.ps1 -TestParam %windir%. Jeśli zamiast tego użyto .\test.ps1polecenia , program PowerShell zgłosi błąd, ponieważ nie może znaleźć ścieżki literału .\test.ps1

Uwaga

Parametr File nie może obsługiwać skryptów przy użyciu parametru, który oczekuje tablicy wartości argumentów. Niestety, jest to ograniczenie sposobu, w jaki natywne polecenie pobiera wartości argumentów. Wywołanie natywnego pliku wykonywalnego (takiego jak powershell lub pwsh) nie wie, co należy zrobić z tablicą, więc jest przekazywane jako ciąg.

Po zakończeniu pliku skryptu za exit pomocą polecenia kod zakończenia procesu jest ustawiony na argument liczbowy używany z poleceniem exit . W przypadku normalnego zakończenia kod zakończenia jest zawsze 0.

Aby uzyskać więcej informacji, zobacz $LASTEXITCODE w about_Automatic_Variables.

Podobnie jak w przypadku -Commandwystąpienia błędu zakończenia skryptu kod zakończenia jest ustawiony na 1wartość . Jednak w przeciwieństwie do metody w przypadku -Commandprzerwania wykonywania za pomocą klawiszy Ctrl+C kod zakończenia to .0

Uwaga

Od programu PowerShell 7.2 parametr File akceptuje .ps1 tylko pliki w systemie Windows. Jeśli zostanie podany inny typ pliku, zostanie zgłoszony błąd. To zachowanie jest specyficzne dla systemu Windows. Na innych platformach program PowerShell próbuje uruchomić inne typy plików.

-Command | -c

Wykonuje określone polecenia (i wszystkie parametry), tak jakby zostały wpisane w wierszu polecenia programu PowerShell, a następnie kończy działanie, chyba że NoExit określono parametr.

Wartością polecenia może być -blok skryptu lub ciąg. Jeśli wartość command to -, tekst polecenia jest odczytywany ze standardowych danych wejściowych.

Parametr Command akceptuje tylko blok skryptu do wykonania, gdy może rozpoznać wartość przekazaną do polecenia jako typ ScriptBlock. Jest to możliwe tylko w przypadku uruchamiania pwsh z innego hosta programu PowerShell. Typ ScriptBlock może być zawarty w istniejącej zmiennej, zwracanej z wyrażenia lub analizowany przez hosta programu PowerShell jako blok skryptu literału ujęty w nawiasy klamrowe ({}), przed przekazaniem do pwshelementu .

pwsh -Command {Get-WinEvent -LogName security}

W cmd.exesystemie nie ma czegoś takiego jak blok skryptu (lub typ ScriptBlock ), więc wartość przekazana do polecenia jest zawsze ciągiem. Blok skryptu można napisać wewnątrz ciągu, ale zamiast wykonywać działa dokładnie tak, jakby został wpisany w typowym wierszu programu PowerShell, wyświetlając zawartość bloku skryptu.

Ciąg przekazany do polecenia jest nadal wykonywany jako kod programu PowerShell, więc blok skryptu nawiasy klamrowe nie są często wymagane w pierwszej kolejności podczas uruchamiania z cmd.exe. Aby wykonać wbudowany blok skryptu zdefiniowany wewnątrz ciągu, można użyć operatora& wywołania:

pwsh -Command "& {Get-WinEvent -LogName security}"

Jeśli wartość Command jest ciągiem, polecenie musi być ostatnim parametrem dla programu pwsh, ponieważ wszystkie argumenty następujące po nim są interpretowane jako część polecenia do wykonania.

Po wywołaniu z istniejącej sesji programu PowerShell wyniki są zwracane do powłoki nadrzędnej jako zdeserializowane obiekty XML, a nie obiekty aktywne. W przypadku innych powłok wyniki są zwracane jako ciągi.

Jeśli wartość command to -, tekst polecenia jest odczytywany ze standardowych danych wejściowych. Podczas korzystania z parametru Command ze standardowymi danymi wejściowymi należy przekierować standardowe dane wejściowe. Na przykład:

@'
"in"

"hi" |
  % { "$_ there" }

"out"
'@ | powershell -NoProfile -Command -

Ten przykład generuje następujące wyniki:

in
hi there
out

Kod zakończenia procesu jest określany przez stan ostatniego (wykonanego) polecenia w bloku skryptu. Kod zakończenia jest w przypadku, gdy element 0 jest $true lub 1 ma $? wartość $false.$? Jeśli ostatnie polecenie jest programem zewnętrznym lub skryptem programu PowerShell, który jawnie ustawia kod zakończenia inny niż 0 lub 1, kod zakończenia jest konwertowany na 1 dla kodu zakończenia procesu. Aby zachować określony kod zakończenia, dodaj exit $LASTEXITCODE do ciągu polecenia lub bloku skryptu.

Aby uzyskać więcej informacji, zobacz $LASTEXITCODE w about_Automatic_Variables.

Podobnie wartość 1 jest zwracana, gdy występuje błąd zakończenia skryptu (runspace-terminating), taki jak throw lub -ErrorAction Stop, lub po przerwaniu wykonywania za pomocą klawisza Ctrl+C.

-CommandWithArgs | -cWa

Jest to funkcja eksperymentalna dodana w wersji 7.4.

Wykonuje polecenie programu PowerShell z argumentami. W przeciwieństwie do -Commandparametru , ten parametr wypełnia skompilowany $args-in zmiennej, która może być używana przez polecenie .

Pierwszy ciąg to polecenie . Argumenty są dodatkowymi ciągami rozdzielanymi odstępami.

Na przykład:

pwsh -CommandWithArgs '$args | % { "arg: $_" }' arg1 arg2

Ten przykład generuje następujące wyniki:

arg: arg1
arg: arg2

-ConfigurationName | -config

Określa punkt końcowy konfiguracji, w którym jest uruchamiany program PowerShell. Może to być dowolny punkt końcowy zarejestrowany na komputerze lokalnym, w tym domyślne punkty końcowe komunikacji zdalnej programu PowerShell lub niestandardowy punkt końcowy, który ma określone możliwości roli użytkownika.

Przykład: pwsh -ConfigurationName AdminRoles

-Configurationfile

Określa ścieżkę pliku konfiguracji sesji (.pssc). Konfiguracja zawarta w pliku konfiguracji zostanie zastosowana do sesji programu PowerShell.

Przykład: pwsh -ConfigurationFile "C:\ProgramData\PowerShell\MyConfig.pssc"

-CustomPipeName

Określa nazwę używaną dla dodatkowego serwera IPC (nazwanego potoku) używanego do debugowania i innej komunikacji między procesami. Zapewnia to przewidywalny mechanizm łączenia się z innymi wystąpieniami programu PowerShell. Zazwyczaj używany z parametrem CustomPipeName w pliku Enter-PSHostProcess.

Ten parametr został wprowadzony w programie PowerShell 6.2.

Na przykład:

# PowerShell instance 1
pwsh -CustomPipeName mydebugpipe
# PowerShell instance 2
Enter-PSHostProcess -CustomPipeName mydebugpipe

-EncodedCommand | -e | -ec

Akceptuje wersję ciągu base64-encoded polecenia. Użyj tego parametru, aby przesłać polecenia do programu PowerShell, które wymagają złożonego, zagnieżdżonego cudzysłów. Reprezentacja Base64 musi być ciągiem zakodowanym w formacie UTF-16LE.

Na przykład:

$command = 'dir "c:\program files" '
$bytes = [System.Text.Encoding]::Unicode.GetBytes($command)
$encodedCommand = [Convert]::ToBase64String($bytes)
pwsh -encodedcommand $encodedCommand

-ExecutionPolicy | -ex | -ep

Ustawia domyślne zasady wykonywania dla bieżącej sesji i zapisuje je w zmiennej środowiskowej $env:PSExecutionPolicyPreference . Ten parametr nie zmienia trwale skonfigurowanych zasad wykonywania.

Ten parametr dotyczy tylko komputerów z systemem Windows. Na platformach innych niż Windows parametr i podana wartość są ignorowane.

-InputFormat | -inp | -if

Opisuje format danych wysyłanych do programu PowerShell. Prawidłowe wartości to "Text" (ciągi tekstowe) lub "XML" (serializowany format CLIXML).

-Interactive | -i

Przedstawia użytkownikowi interakcyjny monit. Odwrotność parametru NonInteractive.

-Login | -l

W systemach Linux i macOS program PowerShell uruchamia program PowerShell jako powłokę logowania, używając /bin/sh do wykonywania profilów logowania, takich jak /etc/profile i ~/.profile. W systemie Windows ten przełącznik nic nie robi.

Ważne

Ten parametr musi najpierw uruchomić program PowerShell jako powłokę logowania. Ten parametr jest ignorowany, jeśli jest przekazywany w innej pozycji.

Aby skonfigurować pwsh jako powłokę logowania w systemach operacyjnych system UNIX-l ike:

  • Sprawdź, czy w obszarze znajduje się pełna ścieżka bezwzględna do pwsh/etc/shells

    • Ta ścieżka jest zwykle podobna /usr/bin/pwsh do w systemie Linux lub /usr/local/bin/pwsh w systemie macOS
    • W przypadku niektórych metod instalacji ten wpis zostanie dodany automatycznie w czasie instalacji
    • Jeśli pwsh nie ma elementu w programie /etc/shells, użyj edytora, aby dołączyć ścieżkę do pwsh w ostatnim wierszu. Wymaga to uprawnień z podwyższonym poziomem uprawnień do edycji.

  • Użyj narzędzia chsh, aby ustawić powłokę bieżącego użytkownika na :pwsh

    chsh -s /usr/bin/pwsh

Ostrzeżenie

Ustawienie pwsh jako powłoka logowania nie jest obecnie obsługiwane w Podsystem Windows dla systemu Linux (WSL) i próba ustawienia pwsh jako powłoki logowania może prowadzić do niemożność interaktywnego uruchomienia programu WSL.

-MTA

Uruchom program PowerShell przy użyciu apartamentu wielowątkowego. Ten przełącznik jest dostępny tylko w systemie Windows. Użycie tego parametru na platformach innych niż Windows powoduje wystąpienie błędu.

-NoExit | -noe

Nie kończy się po uruchomieniu poleceń uruchamiania.

Przykład: pwsh -NoExit -Command Get-Date

-NoLogo | -nol

Ukrywa transparent podczas uruchamiania sesji interakcyjnych.

-NonInteractive | -noni

Ten przełącznik służy do tworzenia sesji, które nie powinny wymagać danych wejściowych użytkownika. Jest to przydatne w przypadku skryptów uruchamianych w zaplanowanych zadaniach lub potokach ciągłej integracji/ciągłego wdrażania. Wszelkie próby użycia funkcji interaktywnych, takich jak Read-Host lub monity o potwierdzenie, powodują zakończenie instrukcji błędy, a nie zawieszają się.

-NoProfile | -nop

Nie ładuje profilów programu PowerShell.

-NoProfileLoadTime

Ukrywa tekst czasu ładowania profilu programu PowerShell wyświetlany podczas uruchamiania, gdy czas ładowania przekracza 500 milisekund.

-OutputFormat | -o | -of

Określa sposób formatowania danych wyjściowych z programu PowerShell. Prawidłowe wartości to "Text" (ciągi tekstowe) lub "XML" (serializowany format CLIXML).

Przykład: pwsh -o XML -c Get-Date

Po wywołaniu w ramach sesji programu PowerShell obiekty deserializowane są jako dane wyjściowe, a nie zwykłe ciągi. Po wywołaniu z innych powłok dane wyjściowe są ciągami sformatowanymi jako tekst CLIXML.

-SettingsFile | -settings

Zastępuje plik ustawień środowiska IDE powershell.config.json systemu-wdla sesji. Domyślnie ustawienia środowiska IDE systemu-wsą odczytywane z powershell.config.json katalogu .$PSHOME

Należy pamiętać, że te ustawienia nie są używane przez punkt końcowy określony przez -ConfigurationName argument.

Przykład: pwsh -SettingsFile c:\myproject\powershell.config.json

-SSHServerMode | -sshs

Używany w sshd_config do uruchamiania programu PowerShell jako podsystemu SSH. Nie jest ona przeznaczona ani obsługiwana w przypadku żadnego innego użycia.

-STA

Uruchom program PowerShell przy użyciu apartamentu jednowątkowego. Jest to opcja domyślna. Ten przełącznik jest dostępny tylko na platformie Windows. Użycie tego parametru na platformach innych niż Windows powoduje wystąpienie błędu.

-Version | -v

Wyświetla wersję programu PowerShell. Dodatkowe parametry są ignorowane.

-WindowStyle | -w

Ustawia styl okna dla sesji. Prawidłowe wartości to Normalne, Zminimalizowane, Zmaksymalizowane i Ukryte. Ten parametr dotyczy tylko systemu Windows. Użycie tego parametru na platformach innych niż Windows powoduje wystąpienie błędu.

-WorkingDirectory | -wd | -wo

Ustawia początkowy katalog roboczy, wykonując polecenie podczas uruchamiania. Obsługiwana jest dowolna prawidłowa ścieżka pliku programu PowerShell.

Aby uruchomić program PowerShell w katalogu głównym, użyj: pwsh -WorkingDirectory ~

-Help, -?, /?

Wyświetla pomoc dotyczącą elementu pwsh. Jeśli piszesz polecenie pwsh w programie PowerShell, poprzedzając parametry polecenia łącznikiem (-), a nie ukośnikiem (/).