Freigeben über

about_Pwsh

  • Artikel

Kurze Beschreibung

Erläutert die Verwendung der pwsh Befehlsschnittstelle-l. Zeigt die Befehlsparameter-lan und beschreibt die Syntax.

Lange Beschreibung

Informationen zu den Befehlsoptionen-lfür Windows PowerShell 5.1 finden Sie unter about_PowerShell_exe.

Syntax

Usage: pwsh[.exe]
    [-Login]
    [[-File] <filePath> [args]]
    [-Command { - | <script-block> [-args <arg-array>]
                  | <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 | -? | /?

Parameter

Bei allen Parametern wird die Groß-/-iKleinschreibung nicht beachtet.

-File | -f

Wenn der Wert von File ist -, wird der Befehlstext aus der Standardeingabe gelesen. Die Ausführung pwsh -File - ohne umgeleitete Standardeingabe startet eine reguläre Sitzung. Dies entspricht der Angabe des File Parameters überhaupt nicht.

Dies ist der Standardparameter, wenn keine Parameter vorhanden sind, aber Werte in der Befehlszeile vorhanden sind. Das angegebene Skript wird im lokalen Bereich ("dot-sourced") der neuen Sitzung ausgeführt, sodass die Funktionen und Variablen, die das Skript erstellt, in der neuen Sitzung verfügbar sind. Geben Sie den Skriptdateipfad und alle Parameter ein. File muss der letzte Parameter im Befehl sein, da alle Zeichen, die nach dem File-Parameternamen eingegeben werden, als Skriptdateipfad gefolgt von den Skriptparametern interpretiert werden.

Die Switch-Parameter eines Skripts werden in der Regel entweder einbezogen oder ausgelassen. Der folgende Befehl verwendet beispielsweise den All-Parameter der Get-Script.ps1-Skriptdatei: -File .\Get-Script.ps1 -All

In seltenen Fällen müssen Sie möglicherweise einen booleschen Wert für einen switch-Parameter angeben. Um einen booleschen Wert für einen switch-Parameter im Wert des File-Parameters bereitzustellen, verwenden Sie den Parameter normalerweise, gefolgt von einem Doppelpunkt und dem booleschen Wert, z. B.: -File .\Get-Script.ps1 -All:$False.

Parameter, die an das Skript übergeben werden, werden als Zeichenfolgenliterale übergeben (nach der Interpretation durch die aktuelle Shell). Wenn Sie sich beispielsweise in cmd.exe befinden und einen Umgebungsvariablenwert übergeben möchten, verwenden Sie die cmd.exe Syntax: pwsh -File .\test.ps1 -TestParam %windir%

Im Gegensatz dazu führt die Ausführung pwsh -File .\test.ps1 -TestParam $env:windir in cmd.exe dazu, dass das Skript die Literalzeichenfolge $env:windir empfängt, da es für die aktuelle cmd.exe Shell keine besondere Bedeutung hat. Der $env:windir Stil des Verweises auf Umgebungsvariablen kann innerhalb eines Command-Parameters verwendet werden, da er dort als PowerShell-Code interpretiert wird.

Wenn Sie denselben Befehl aus einem Batch-Skript ausführen möchten, verwenden %~dp0 Sie anstelle von .\ oder $PSScriptRoot , um das aktuelle Ausführungsverzeichnis darzustellen: pwsh -File %~dp0test.ps1 -TestParam %windir%. Wenn Sie stattdessen verwendet .\test.ps1haben, löst PowerShell einen Fehler aus, da der Literalpfad nicht gefunden werden kann. .\test.ps1

Hinweis

Der File-Parameter kann keine Skripts unterstützen, die einen Parameter verwenden, der ein Array von Argumentwerten erwartet. Dies ist leider eine Einschränkung, wie ein nativer Befehl Argumentwerte abruft. Wenn Sie eine native ausführbare Datei (z powershell . B. oder pwsh) aufrufen, weiß sie nicht, was mit einem Array zu tun ist, und wird daher als Zeichenfolge übergeben.

Wenn die Skriptdatei mit einem exit Befehl beendet wird, wird der Prozessausgangscode auf das numerische Argument festgelegt, das mit dem exit Befehl verwendet wird. Bei normaler Beendigung lautet der Exitcode immer 0.

Weitere Informationen finden Sie $LASTEXITCODE unter about_Automatic_Variables.

-CommandÄhnlich wie wird bei einem Skriptabschlussfehler der Exitcode auf 1festgelegt. Anders als bei -Commandist der Exitcode jedoch , wenn die Ausführung mit STRG+C unterbrochen wird 0.

Hinweis

Ab PowerShell 7.2 akzeptiert .ps1 der File-Parameter nur Dateien unter Windows. Wenn ein anderer Dateityp angegeben wird, wird ein Fehler ausgelöst. Dieses Verhalten ist Windows-spezifisch. Auf anderen Plattformen versucht PowerShell, andere Dateitypen auszuführen.

-Command | -c

Führt die angegebenen Befehle (und alle Parameter) so aus, als ob sie an der PowerShell-Eingabeaufforderung eingegeben wurden, und beendet dann, es sei denn, der NoExit Parameter ist angegeben.

Der Wert von Command kann , ein Skriptblock oder eine Zeichenfolge sein -. Wenn der Wert von Command ist -, wird der Befehlstext aus der Standardeingabe gelesen.

Der Command-Parameter akzeptiert nur einen Skriptblock für die Ausführung, wenn er den an Command übergebenen Wert als ScriptBlock-Typ erkennen kann. Dies ist nur möglich, wenn sie von einem anderen PowerShell-Host aus ausgeführt pwsh wird. Der ScriptBlock-Typ kann in einer vorhandenen Variablen enthalten sein, von einem Ausdruck zurückgegeben oder vom PowerShell-Host als Literalskriptblock analysiert werden, der in geschweifte Klammern ({}) eingeschlossen wird, bevor an pwshübergeben wird.

pwsh -Command {Get-WinEvent -LogName security}

In cmd.exegibt es keinen Skriptblock (oder ScriptBlock-Typ ), sodass der an Command übergebene Wert immer eine Zeichenfolge ist. Sie können einen Skriptblock in die Zeichenfolge schreiben, aber anstatt ausgeführt zu werden, verhält er sich genau so, als ob Sie ihn an einer typischen PowerShell-Eingabeaufforderung eingegeben haben und den Inhalt des Skriptblocks wieder auf Sie drucken.

Eine an Command übergebene Zeichenfolge wird weiterhin als PowerShell-Code ausgeführt, sodass die geschweiften Klammern des Skriptblocks bei der Ausführung von cmd.exehäufig nicht erforderlich sind. Um einen in einer Zeichenfolge definierten Inlineskriptblock auszuführen, kann der Aufrufoperator& verwendet werden:

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

Wenn der Wert von Command eine Zeichenfolge ist, muss Command der letzte Parameter für pwsh sein, da alle darauf folgenden Argumente als Teil des auszuführenden Befehls interpretiert werden.

Beim Aufruf innerhalb einer vorhandenen PowerShell-Sitzung werden die Ergebnisse als deserialisierte XML-Objekte und nicht als Liveobjekte an die übergeordnete Shell zurückgegeben. Bei anderen Shells werden die Ergebnisse als Zeichenfolgen zurückgegeben.

Wenn der Wert von Command ist -, wird der Befehlstext aus der Standardeingabe gelesen. Sie müssen die Standardeingabe umleiten, wenn Sie den Command-Parameter mit der Standardeingabe verwenden. Beispiel:

@'
"in"

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

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

Dieses Beispiel erzeugt die folgende Ausgabe:

in
hi there
out

Der Prozessausgangscode wird durch status des letzten (ausgeführten) Befehls innerhalb des Skriptblocks bestimmt. Der Exitcode lautet0, wenn $true$? oder 1 ist $?$false. Wenn der letzte Befehl ein externes Programm oder ein PowerShell-Skript ist, das explizit einen anderen Exitcode als 0 oder 1festlegt, wird dieser Exitcode für den Prozessausgangscode in 1 konvertiert. Um den spezifischen Exitcode beizubehalten, fügen Sie der Befehlszeichenfolge oder dem Skriptblock hinzu exit $LASTEXITCODE .

Weitere Informationen finden Sie $LASTEXITCODE unter about_Automatic_Variables.

Ebenso wird der Wert 1 zurückgegeben, wenn ein Skriptabschlussfehler (runspace-terminating) auftritt, z. B. oder throw-ErrorAction Stop, wenn die Ausführung mit STRG+C unterbrochen wird.

-ConfigurationName | -config

Gibt einen Konfigurationsendpunkt an, in dem PowerShell ausgeführt wird. Dies kann ein beliebiger Endpunkt sein, der auf dem lokalen Computer registriert ist, einschließlich der PowerShell-Standardremotingendpunkte oder ein benutzerdefinierter Endpunkt mit bestimmten Benutzerrollenfunktionen.

Beispiel: pwsh -ConfigurationName AdminRoles

-ConfigurationFile

Gibt einen Sitzungskonfigurationsdateipfad (.pssc) an. Die in der Konfigurationsdatei enthaltene Konfiguration wird auf die PowerShell-Sitzung angewendet.

Beispiel: pwsh -ConfigurationFile "C:\ProgramData\PowerShell\MyConfig.pssc"

-CustomPipeName

Gibt den Namen an, der für einen zusätzlichen IPC-Server (Named Pipe) verwendet werden soll, der für das Debuggen und andere prozessübergreifende Kommunikation verwendet wird. Dies bietet einen vorhersagbaren Mechanismus zum Herstellen einer Verbindung mit anderen PowerShell-Instanzen. Wird in der Regel mit dem Parameter CustomPipeName auf Enter-PSHostProcessverwendet.

Dieser Parameter wurde in PowerShell 6.2 eingeführt.

Beispiel:

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

-EncodedCommand | -e | -ec

Akzeptiert eine Base64-encodierte Zeichenfolgenversion eines Befehls. Verwenden Sie diesen Parameter, um Befehle an PowerShell zu übermitteln, die komplexe, geschachtelte Anführungszeichen erfordern. Die Base64-Darstellung muss eine UTF-16LE-codierte Zeichenfolge sein.

Beispiel:

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

-ExecutionPolicy | -ex | -ep

Legt die Standardausführungsrichtlinie für die aktuelle Sitzung fest und speichert sie in der $env:PSExecutionPolicyPreference Umgebungsvariablen. Dieser Parameter ändert die persistent konfigurierten Ausführungsrichtlinien nicht.

Dieser Parameter gilt nur für Windows-Computer. Auf Nicht-Windows-Plattformen werden der Parameter und der angegebene Wert ignoriert.

-InputFormat | -inp | -if

Beschreibt das Format der Daten, die an PowerShell übermittelt werden. Gültige Werte sind "Text" (Textzeichenfolgen) oder "XML" (serialisiertes CLIXML-Format).

-Interactive | -i

Präsentieren Sie dem Benutzer eine interaktive Eingabeaufforderung. Umgekehrt für den NonInteractive-Parameter.

-Login | -l

Unter Linux und macOS startet PowerShell als Anmeldeshell, wobei /bin/sh verwendet wird, um Anmeldeprofile wie "/etc/profile" und "~/.profile" auszuführen. Unter Windows bewirkt dieser Schalter nichts.

Wichtig

Dieser Parameter muss zuerst verwendet werden, um PowerShell als Anmeldeshell zu starten. Dieser Parameter wird ignoriert, wenn er an einer anderen Position übergeben wird.

So richten Sie pwsh unter UNIX-ike-Betriebssystemen-lals Anmeldeshell ein:

  • Vergewissern Sie sich, dass der vollständige absolute Pfad zu pwsh unter /etc/shells

    • Dieser Pfad ist in der Regel etwa unter /usr/bin/pwsh Linux oder /usr/local/bin/pwsh macOS.
    • Bei einigen Installationsmethoden wird dieser Eintrag automatisch zum Zeitpunkt der Installation hinzugefügt.
    • Wenn pwsh in /etc/shellsnicht vorhanden ist, verwenden Sie einen Editor, um pwsh den Pfad in der letzten Zeile anzufügen. Dies erfordert erhöhte Berechtigungen zum Bearbeiten.

  • Verwenden Sie das Hilfsprogramm chsh , um die Shell Ihres aktuellen Benutzers auf festzulegen pwsh:

    chsh -s /usr/bin/pwsh

Warnung

Das Festlegen pwsh der Anmeldeshell wird derzeit auf Windows-Subsystem für Linux (WSL) nicht unterstützt, und der Versuch, dort als Anmeldeshell festzulegenpwsh, kann dazu führen, dass WSL nicht interaktiv gestartet werden kann.

-MTA

Starten Sie PowerShell mit einem Multithread-Apartment. Dieser Switch ist nur unter Windows verfügbar. Die Verwendung dieses Parameters auf Nicht-Windows-Plattformen führt zu einem Fehler.

-NoExit | -noe

Nach dem Ausführen der Startbefehle erfolgt kein Beenden.

Beispiel: pwsh -NoExit -Command Get-Date

-NoLogo | -nol

Blendet das Banner beim Start interaktiver Sitzungen aus.

-NonInteractive | -noni

Dieser Schalter wird verwendet, um Sitzungen zu erstellen, die keine Benutzereingabe erfordern sollten. Dies ist nützlich für Skripts, die in geplanten Aufgaben oder CI/CD-Pipelines ausgeführt werden. Alle Versuche, interaktive Features zu verwenden, wie z. B Read-Host . Bestätigungsaufforderungen, führen dazu, dass Die Anweisung Fehler beendet, anstatt zu hängen.

-NoProfile | -nop

Lädt die PowerShell-Profile nicht.

-NoProfileLoadTime

Blendet den Beim Start angezeigten PowerShell-Profilladezeittext aus, wenn die Ladezeit 500 Millisekunden überschreitet.

-OutputFormat | -o | -of

Bestimmt, wie die Ausgabe von PowerShell formatiert ist. Gültige Werte sind "Text" (Textzeichenfolgen) oder "XML" (serialisiertes CLIXML-Format).

Beispiel: pwsh -o XML -c Get-Date

Wenn Sie innerhalb einer PowerShell-Sitzung aufgerufen werden, erhalten Sie deserialisierte Objekte als Ausgabe, eher einfache Zeichenfolgen. Wenn die Ausgabe von anderen Shells aufgerufen wird, handelt es sich um Zeichenfolgendaten, die als CLIXML-Text formatiert sind.

-SettingsFile | -settings

Überschreibt die Systemide-Einstellungsdatei-wpowershell.config.json für die Sitzung. Standardmäßig werden systemide-Einstellungen-waus dem powershell.config.json im $PSHOME Verzeichnis gelesen.

Beachten Sie, dass diese Einstellungen nicht von dem vom -ConfigurationName Argument angegebenen Endpunkt verwendet werden.

Beispiel: pwsh -SettingsFile c:\myproject\powershell.config.json

-SSHServerMode | -sshs

Wird in sshd_config zum Ausführen von PowerShell als SSH-Subsystem verwendet. Es ist nicht für eine andere Verwendung vorgesehen oder unterstützt.

-STA

Starten Sie PowerShell mit einem Singlethread-Apartment. Dies ist die Standardoption. Dieser Switch ist nur auf der Windows-Plattform verfügbar. Die Verwendung dieses Parameters auf Nicht-Windows-Plattformen führt zu einem Fehler.

-Version | -v

Zeigt die Version von PowerShell an. Zusätzliche Parameter werden ignoriert.

-WindowStyle | -w

Legt den Fensterstil für die Sitzung fest. Gültige Werte sind „Normal“, „Minimized“, „Maximized“ und „Hidden“. Dieser Parameter gilt nur für Windows. Die Verwendung dieses Parameters auf Nicht-Windows-Plattformen führt zu einem Fehler.

-WorkingDirectory | -wd | -wO

Legt das anfängliche Arbeitsverzeichnis fest, indem beim Start ausgeführt wird. Jeder gültige PowerShell-Dateipfad wird unterstützt.

Verwenden Sie Zum Starten von PowerShell in Ihrem Basisverzeichnis Folgendes: pwsh -WorkingDirectory ~

-Help, -?, /?

Zeigt Hilfe zu pwshan. Wenn Sie einen pwsh-Befehl in PowerShell eingeben, stellen Sie den Befehlsparametern einen Bindestrich (-) und keinen Schrägstrich (/) voran.