about_Pwsh

Krótki opis

W tym artykule wyjaśniono, jak używać interfejsupwsh-l polecenia . Wyświetla polecenie-lparametry ine i opisuje składnię.

Długi opis

Aby uzyskać informacje o poleceniach-lopcji ine dla 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 to wielkość liter-ibez uwzględniania.

-File | -f

Wartość File może być - lub ścieżka pliku i parametry opcjonalne. Jeśli wartość File jest -, polecenia są odczytywane ze standardowych danych wejściowych.

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 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ą dla parametru przełącznika w wartości parametru File, użyj parametru, po którym następuje zwykle 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 i chcesz przekazać wartość zmiennej środowiskowej, użyj składni cmd.exe: pwsh -File .\test.ps1 -TestParam %windir%

Natomiast uruchomienie pwsh -File .\test.ps1 -TestParam $Env:windir w cmd.exe powoduje, że skrypt odbiera ciąg literału $Env:windir, ponieważ nie ma specjalnego znaczenia dla bieżącej powłoki cmd.exe. 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 %~dp0 zamiast .\ lub $PSScriptRoot do reprezentowania bieżącego katalogu wykonywania: pwsh -File %~dp0test.ps1 -TestParam %windir%. Jeśli zamiast tego używasz .\test.ps1, program PowerShell zgłasza błąd, ponieważ nie może znaleźć ścieżki literału .\test.ps1

Nuta

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. Podczas wywoływania natywnego pliku wykonywalnego (takiego jak powershell lub pwsh) nie wiadomo, co zrobić z tablicą, więc jest przekazywany jako ciąg.

Jeśli wartość File jest -, polecenia są odczytywane ze standardowych danych wejściowych. Uruchamianie pwsh -File - bez przekierowania standardowych danych wejściowych rozpoczyna zwykłą sesję. Jest to takie samo, jak nie określa parametru File w ogóle. Podczas odczytywania ze standardowych danych wejściowych instrukcje wejściowe są wykonywane pojedynczo tak, jakby były wpisywane w wierszu polecenia programu PowerShell. Jeśli instrukcja nie analizuje się poprawnie, instrukcja nie jest wykonywana. Kod zakończenia procesu jest określany przez stan ostatniego (wykonanego) polecenia w danych wejściowych. W przypadku normalnego zakończenia kod zakończenia jest zawsze 0. Po zakończeniu pliku skryptu za pomocą polecenia exit kod zakończenia procesu jest ustawiony na argument liczbowy używany z exit polecenia.

Podobnie jak -Command, gdy wystąpi błąd zakończenia skryptu, kod zakończenia jest ustawiony na 1. Jednak w przeciwieństwie do -Command, gdy wykonanie zostanie przerwane za pomocą Ctrl+C kod zakończenia jest 0. Aby uzyskać więcej informacji, zobacz $LASTEXITCODE w about_Automatic_Variables.

Nuta

Od programu PowerShell 7.2 parametr File akceptuje tylko pliki .ps1 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

Wartością polecenia może być -, blok skryptu lub ciąg. Jeśli wartość Command jest -, 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 tylko możliwe podczas 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 scriptblock (lub typ ScriptBlock ), więc wartość przekazana do polecenia jest zawsze ciągiem. Możesz napisać blok skryptu wewnątrz ciągu, ale zamiast wykonywać zachowuje się dokładnie tak, jakby został wpisany w typowym wierszu programu PowerShell, wyświetlając zawartość skryptu odblokuj do Ciebie.

Ciąg przekazany do polecenia jest nadal wykonywany jako kod programu PowerShell, więc nawiasy klamrowe scriptblock nie są często wymagane w pierwszej kolejności podczas uruchamiania z cmd.exeprogramu . Aby wykonać wbudowany skryptblock 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, Command musi być ostatnim parametrem dla programu pwsh, ponieważ wszystkie argumenty wykonywane za nim są interpretowane jako część polecenia.

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 jest -, polecenia są odczytywane ze standardowych danych wejściowych. Podczas korzystania z parametru command należy przekierować standardowe dane wejściowe. Na przykład:

@'
"in"

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

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

W tym przykładzie są generowane następujące dane wyjściowe:

in
hi there
out

Podczas odczytywania ze standardowych danych wejściowych dane wejściowe są analizowane i wykonywane pojedynczo, tak jakby zostały wpisane w wierszu polecenia programu PowerShell. Jeśli kod wejściowy nie jest poprawnie analizowany, instrukcja nie jest wykonywana. Jeśli nie używasz parametru -NoExit, sesja programu PowerShell kończy się, gdy nie ma więcej danych wejściowych do odczytu ze standardowych danych wejściowych.

Kod zakończenia procesu jest określany przez stan ostatniego (wykonanego) polecenia w danych wejściowych. Kod zakończenia jest 0, gdy $? jest $true lub 1, gdy $? jest $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. Podobnie wartość 1 jest zwracana w przypadku błędu zakończenia skryptu (runspace-terminating), takiego jak throw lub -ErrorAction Stop, występuje lub gdy wykonanie zostanie przerwane za pomocą Ctrl+C.

Aby zachować określony kod zakończenia, dodaj exit $LASTEXITCODE do ciągu polecenia lub skryptblock. Aby uzyskać więcej informacji, zobacz $LASTEXITCODE w about_Automatic_Variables.

-CommandWithArgs | -cwa

Jest to funkcja eksperymentalna dodana w wersji 7.4 i stała się podstawowa w programie PowerShell 7.5-preview.5.

Wykonuje polecenie programu PowerShell z argumentami. W przeciwieństwie do -Commandten parametr wypełnia $args skompilowany-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

W tym przykładzie są generowane następujące dane wyjściowe:

arg: arg1
arg: arg2

Nuta

analizowanie argumentów z cudzysłowami powoduje niepowodzenie przykładu w przypadku uruchomienia z cmd.exe lub powershell.exe. Aby uruchomić z tych elementów, możesz użyć polecenia

REM Quoting required when run from cmd.exe
pwsh -CommandWithArgs "$args | % { ""arg: $_"" }" arg1 arg2

# Quoting required when run from powershell.exe
pwsh -CommandWithArgs '"$args | % { ""arg: $_"" }"' arg1 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 konfigurację sesji (.pssc) ścieżkę pliku. 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 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 ciągu 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żny

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 Unix-like:

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

  • Ta ścieżka jest zwykle podobna do /usr/bin/pwsh 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 istnieje w /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, ponieważ powłoka logowania nie jest obecnie obsługiwana w podsystemie Windows dla systemu Linux (WSL) i próba ustawienia pwsh, ponieważ powłoka 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 zawieszanie 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ń-wide powershell.config.json systemu dla sesji. Domyślnie ustawienia systemu-wide są odczytywane z powershell.config.json w katalogu $PSHOME.

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

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 wartość 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ę tego pliku wykonywalnego 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 polecenia: pwsh -WorkingDirectory ~

-Help, -?, /?

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