about_Pwsh

  • Artikel

Kurze Beschreibung

Erläutert, wie der pwsh Befehl-line-Schnittstelle verwendet wird. Zeigt den Befehl-line-Parameter an und beschreibt die Syntax.

Lange Beschreibung

Informationen zu den Befehl-line-Optionen fü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>] } ]
    [-ConfigurationName <string>]
    [-CustomPipeName <string>]
    [-EncodedCommand <Base64EncodedCommand>]
    [-ExecutionPolicy <ExecutionPolicy>]
    [-InputFormat {Text | XML}]
    [-Interactive]
    [-Login]
    [-MTA]
    [-NoExit]
    [-NoLogo]
    [-NonInteractive]
    [-NoProfile]
    [-OutputFormat {Text | XML}]
    [-SettingsFile <filePath>]
    [-SSHServerMode]
    [-STA]
    [-Version]
    [-WindowStyle <style>]
    [-WorkingDirectory <directoryPath>]

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

Parameter

Bei allen Parametern wird die Groß-/Kleinschreibung-ibeachtet.

-File | -f

Wenn der Wert File lautet -, wird der Befehlstext aus der Standardeingabe gelesen. Wird pwsh -File - ohne umgeleitete Standardeingabe ausgeführt, wird eine normale Sitzung gestartet. Dies ist identisch mit 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 vom Skript erstellten Funktionen und Variablen in einer neuen Sitzung verfügbar sind. Geben Sie den Skriptdateipfad und alle Parameter ein. Die Datei muss der letzte Parameter im Befehl sein, da alle Zeichen, die nach dem Dateinamen des Dateiparameters eingegeben wurden, als Skriptdateipfad interpretiert werden, gefolgt von den Skriptparametern.

Die Switch-Parameter eines Skripts werden in der Regel entweder einbezogen oder ausgelassen. Der folgende Befehl verwendet beispielsweise den Parameter "All" der Skriptdatei "Get-Script.ps1": -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 unmittelbar gefolgt von einem Doppelpunkt und dem booleschen Wert, z. B. den folgenden: -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 cmd.exe beispielsweise 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 dem Skript, das die Literalzeichenfolge $env:windir empfängt, da sie keine besondere Bedeutung für die aktuelle cmd.exe Shell hat. Der $env:windir Stil des Umgebungsvariablenverweises kann in einem Command-Parameter verwendet werden, da er als PowerShell-Code interpretiert wird.

Wenn Sie denselben Befehl aus einem Batchskript ausführen möchten, verwenden %~dp0 Sie anstelle oder $PSScriptRoot.\ zum Darstellen des aktuellen Ausführungsverzeichnisses: pwsh -File %~dp0test.ps1 -TestParam %windir% Wenn Sie stattdessen verwendet haben .\test.ps1, löst PowerShell einen Fehler aus, da er den Literalpfad nicht finden kann. .\test.ps1

Hinweis

Der File-Parameter kann Skripts nicht mit einem Parameter unterstützen, der ein Array von Argumentwerten erwartet. Dies ist leider eine Einschränkung, wie ein systemeigener Befehl Argumentwerte abruft. Wenn Sie eine systemeigene ausführbare Datei (z powershell . B. oder pwsh) aufrufen, wissen Sie nicht, was mit einem Array zu tun ist, sodass sie als Zeichenfolge übergeben wird.

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

Weitere Informationen finden Sie in $LASTEXITCODEabout_Automatic_Variables.

Ähnlich wie -Command, wenn ein Skriptbeendfehler auftritt, wird der Beendigungscode auf 1festgelegt. Anders als bei -Command, wenn die Ausführung mit STRG+C unterbrochen wird, lautet 0der Ausgangscode .

Hinweis

Ab PowerShell 7.2 akzeptiert .ps1 der Dateiparameter nur Dateien unter Windows. Wenn ein anderer Dateityp angezeigt wird, wird ein Fehler ausgelöst. Dieses Verhalten ist windowsspezifisch. 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 sie 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 lautet -, 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 ausgeführt wird pwsh . Der ScriptBlock-Typ kann in einer vorhandenen Variablen enthalten sein, von einem Ausdruck zurückgegeben oder vom PowerShell-Host als literaler Skriptblock analysiert werden, der in geschweifte Klammern () eingeschlossen ist,{} bevor er an pwsh.

pwsh -Command {Get-WinEvent -LogName security}

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

Eine an Command übergebene Zeichenfolge wird weiterhin als PowerShell-Code ausgeführt, sodass die geschweiften Klammern des Skriptblocks häufig nicht an erster Stelle benötigt werden, wenn sie von cmd.exe. Zum Ausführen eines Inlineskriptblocks, der in einer Zeichenfolge definiert ist, 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 folgenden Argumente als Teil des auszuführenden Befehls interpretiert werden.

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

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

@'
"in"

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

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

Dieses Beispiel erzeugt die folgende Ausgabe:

in
hi there
out

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

Weitere Informationen finden Sie in $LASTEXITCODEabout_Automatic_Variables.

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

-ConfigurationName | -config

Gibt einen Konfigurationsendpunkt an, in dem PowerShell ausgeführt wird. Dies kann jeder auf dem lokalen Computer registrierte Endpunkt sein, einschließlich der standardmäßigen PowerShell-Remotingendpunkte oder eines benutzerdefinierten Endpunkts mit bestimmten Benutzerrollenfunktionen.

Beispiel: pwsh -ConfigurationName AdminRoles

-CustomPipeName

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

Dieser Parameter wurde in PowerShell 6.2 eingeführt.

Zum 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 Quoten erfordern. Die Base64-Darstellung muss eine UTF-16LE-codierte Zeichenfolge sein.

Zum 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 Umgebungsvariable. Dieser Parameter ändert nicht die dauerhaft konfigurierten Ausführungsrichtlinien.

Dieser Parameter gilt nur für Windows-Computer. Auf Nicht-Windows-Plattformen werden der Parameter und der bereitgestellte 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

Stellen Sie dem Benutzer eine interaktive Eingabeaufforderung vor. Umkehrung für NonInteractive-Parameter.

-Login | -l

Unter Linux und macOS startet PowerShell als Anmeldeshell, wobei /bin/sh zum Ausführen von Anmeldeprofilen wie /etc/profile und ~/.profile verwendet wird. Unter Windows führt dieser Schalter nichts aus.

Wichtig

Dieser Parameter muss zuerst gestartet werden, um PowerShell als Anmeldeshell zu starten. Dieser Parameter wird ignoriert, wenn er an eine andere Position übergeben wird.

So richten pwsh Sie die Anmeldeshell auf UNIX-Betriebssystemen-lein:

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

    • Dieser Pfad ist in der Regel etwa /usr/bin/pwsh unter Linux oder /usr/local/bin/pwsh unter macOS
    • Bei einigen Installationsmethoden wird dieser Eintrag automatisch zur Installationszeit hinzugefügt.
    • Falls pwsh nicht vorhanden /etc/shells, verwenden Sie einen Editor, um den Pfad pwsh an die letzte Zeile anzufügen. Dies erfordert erhöhte Rechte zum Bearbeiten.

  • Verwenden Sie das Chsh-Hilfsprogramm, um die Shell des aktuellen Benutzers auf folgendes festzulegenpwsh:

    chsh -s /usr/bin/pwsh

Warnung

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

-MTA

Starten Sie PowerShell mit einem Multithread-Apartment. Dieser Schalter 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, z Read-Host . B. Bestätigungsaufforderungen, führen zu Beendigungsfehlern von Anweisungen und nicht zum Hängen.

-NoProfile | -nop

Lädt die PowerShell-Profile nicht.

-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 in einer PowerShell-Sitzung aufgerufen werden, erhalten Sie deserialisierte Objekte als Ausgabe eher einfache Zeichenfolgen. Wenn sie von anderen Shells aufgerufen wird, handelt es sich bei der Ausgabe um Zeichenfolgendaten, die als CLIXML-Text formatiert sind.

-SettingsFile | -settings

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

Beachten Sie, dass diese Einstellungen nicht vom 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. Sie ist nicht für andere Zwecke vorgesehen oder unterstützt.

-STA

Starten Sie PowerShell mit einem Singlethread-Apartment. Dies ist die Standardeinstellung. 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 er beim Start ausgeführt wird. Jeder gültige PowerShell-Dateipfad wird unterstützt.

Um PowerShell in Ihrem Startverzeichnis zu starten, verwenden Sie Folgendes: pwsh -WorkingDirectory ~

-Help, -?, /?

Zeigt Hilfe für pwsh. Wenn Sie einen Pwsh-Befehl in PowerShell eingeben, stellen Sie die Befehlsparameter mit einem Bindestrich (), nicht einem Schrägstrich (-/) voran.