about_Pwsh
Korte beschrijving
Hierin wordt uitgelegd hoe u de opdracht pwsh
-line interface gebruikt. Geeft de opdracht weer-line-parameters en beschrijft de syntaxis.
Lange beschrijving
Zie about_PowerShell_exevoor informatie over de opdracht-line-opties voor Windows PowerShell 5.1.
Syntaxis
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 | -? | /?
Parameters
Alle parameters zijn hoofdlettergevoelig-i.
-File | -f
Als de waarde van File
is -
, wordt de opdrachttekst gelezen uit standaardinvoer.
Het uitvoeren van pwsh -File -
zonder omgeleide standaardinvoer start een gewone sessie. Dit is hetzelfde als het helemaal niet opgeven van de parameter File
.
Dit is de standaardparameter als er geen parameters aanwezig zijn, maar waarden aanwezig zijn op de opdrachtregel. Het opgegeven script wordt uitgevoerd in het lokale bereik ('dot-sourced') van de nieuwe sessie, zodat de functies en variabelen die door het script worden gemaakt, beschikbaar zijn in een nieuwe sessie. Voer het scriptbestandspad en eventuele parameters in. Het bestand moet de laatste parameter in de opdracht zijn, omdat alle tekens die zijn getypt na de parameternaam van het bestand worden geïnterpreteerd als het scriptbestandspad gevolgd door de scriptparameters.
Normaal gesproken worden de switchparameters van een script opgenomen of weggelaten.
Met de volgende opdracht wordt bijvoorbeeld de parameter All van het scriptbestand Get-Script.ps1 gebruikt: -File .\Get-Script.ps1 -All
In zeldzame gevallen moet u mogelijk een Booleaanse-waarde opgeven voor een switchparameter. Als u een Booleaanse-waarde wilt opgeven voor een schakelparameter in de waarde van de parameter File, gebruikt u de parameter die normaal gesproken onmiddellijk wordt gevolgd door een dubbele punt en de booleaanse waarde, zoals de volgende: -File .\Get-Script.ps1 -All:$False
.
Parameters die aan het script worden doorgegeven, worden doorgegeven als letterlijke tekenreeksen, na interpretatie door de huidige shell. Als u bijvoorbeeld in cmd.exe
bent en een omgevingsvariabelewaarde wilt doorgeven, gebruikt u de syntaxis van de cmd.exe
: pwsh -File .\test.ps1 -TestParam %windir%
Het uitvoeren van pwsh -File .\test.ps1 -TestParam $env:windir
in cmd.exe
resulteert daarentegen in het script dat de letterlijke tekenreeks ontvangt $env:windir
omdat het geen speciale betekenis heeft voor de huidige cmd.exe
shell. De $env:windir
stijl van de verwijzing naar omgevingsvariabele kan worden gebruikt in een parameter Command, omdat deze wordt geïnterpreteerd als PowerShell-code.
Als u dezelfde opdracht wilt uitvoeren vanuit een Batch-script, gebruikt u %~dp0
in plaats van .\
of $PSScriptRoot
om de huidige uitvoeringsmap weer te geven: pwsh -File %~dp0test.ps1 -TestParam %windir%
. Als u in plaats daarvan .\test.ps1
hebt gebruikt, genereert PowerShell een fout omdat het letterlijke pad niet kan worden gevonden .\test.ps1
Notitie
De parameter File biedt geen ondersteuning voor scripts met behulp van een parameter die een matrix met argumentwaarden verwacht. Dit is helaas een beperking van de manier waarop een systeemeigen opdracht argumentwaarden ophaalt. Wanneer u een systeemeigen uitvoerbaar bestand aanroept (zoals powershell
of pwsh
), weet deze niet wat u moet doen met een matrix, zodat deze wordt doorgegeven als een tekenreeks.
Wanneer het scriptbestand wordt beëindigd met een exit
opdracht, wordt de afsluitcode van het proces ingesteld op het numerieke argument dat wordt gebruikt met de opdracht exit
. Bij normale beëindiging wordt de afsluitcode altijd 0
.
Zie $LASTEXITCODE
in about_Automatic_Variablesvoor meer informatie.
Net als bij -Command
, wordt de afsluitcode ingesteld op 1
wanneer er een scriptafsluitfout optreedt. In tegenstelling tot -Command
, wordt de afsluitcode echter 0
wanneer de uitvoering wordt onderbroken met Ctrl+C.
Notitie
Vanaf PowerShell 7.2 accepteert de parameter File alleen .ps1
bestanden in Windows. Als er een ander bestandstype wordt opgegeven, wordt er een fout gegenereerd. Dit gedrag is specifiek voor Windows. Op andere platforms probeert PowerShell andere bestandstypen uit te voeren.
-Command | -c
Hiermee worden de opgegeven opdrachten (en parameters) uitgevoerd alsof ze zijn getypt bij de PowerShell-opdrachtprompt en vervolgens worden afgesloten, tenzij de NoExit
parameter is opgegeven.
De waarde van Command kan -
, een scriptblok of een tekenreeks zijn. Als de waarde van Command is -
, wordt de opdrachttekst gelezen uit de standaardinvoer.
De parameter Command accepteert alleen een scriptblok voor uitvoering wanneer de waarde die is doorgegeven aan Command als ScriptBlock- type kan worden herkend. Dit is alleen mogelijk bij het uitvoeren van pwsh
vanaf een andere PowerShell-host. De ScriptBlock type kan zijn opgenomen in een bestaande variabele, geretourneerd uit een expressie of geparseerd door de PowerShell-host als een letterlijk scriptblok tussen accolades ({}
), voordat deze wordt doorgegeven aan pwsh
.
pwsh -Command {Get-WinEvent -LogName security}
In cmd.exe
is er geen scriptblok (of ScriptBlock type), zodat de waarde die wordt doorgegeven aan Opdracht altijd is een tekenreeks. U kunt een scriptblok in de tekenreeks schrijven, maar in plaats van dat het wordt uitgevoerd, gedraagt het zich precies alsof u het hebt getypt bij een typische PowerShell-prompt, waarbij de inhoud van het scriptblok naar u wordt afgedrukt.
Een tekenreeks die wordt doorgegeven aan Opdracht nog steeds wordt uitgevoerd als PowerShell-code, dus het script blokkeert accolades zijn vaak niet vereist in de eerste plaats bij het uitvoeren vanaf cmd.exe
. Als u een inlinescriptblok wilt uitvoeren dat in een tekenreeks is gedefinieerd, kunt u de aanroepoperator&
gebruiken:
pwsh -Command "& {Get-WinEvent -LogName security}"
Als de waarde van Command een tekenreeks is, moet Command de laatste parameter voor pwsh zijn, omdat alle argumenten die erop volgen, worden geïnterpreteerd als onderdeel van de opdracht die moet worden uitgevoerd.
Wanneer de resultaten vanuit een bestaande PowerShell-sessie worden aangeroepen, worden de resultaten geretourneerd naar de bovenliggende shell als gedeserialiseerde XML-objecten, niet live-objecten. Voor andere shells worden de resultaten geretourneerd als tekenreeksen.
Als de waarde van Command is -
, wordt de opdrachttekst gelezen uit de standaardinvoer. U moet standaardinvoer omleiden bij het gebruik van de Command parameter met standaardinvoer. Bijvoorbeeld:
@'
"in"
"hi" |
% { "$_ there" }
"out"
'@ | powershell -NoProfile -Command -
In dit voorbeeld wordt de volgende uitvoer gegenereerd:
in
hi there
out
De afsluitcode van het proces wordt bepaald door de status van de laatste (uitgevoerde) opdracht in het scriptblok. De afsluitcode wordt 0
wanneer $?
is $true
of 1
wanneer $?
is $false
. Als de laatste opdracht een extern programma of een PowerShell-script is waarmee expliciet een andere afsluitcode dan 0
of 1
wordt ingesteld, wordt die afsluitcode geconverteerd naar 1
voor afsluitcode voor proces. Als u de specifieke afsluitcode wilt behouden, voegt u exit $LASTEXITCODE
toe aan uw opdrachtreeks of scriptblok.
Zie $LASTEXITCODE
in about_Automatic_Variablesvoor meer informatie.
Op dezelfde manier wordt de waarde 1 geretourneerd wanneer een scripteindingsfout (runspace-terminating), zoals een throw
of -ErrorAction Stop
, optreedt of wanneer de uitvoering wordt onderbroken met Ctrl+C-.
-ConfigurationName | -config
Hiermee geeft u een configuratie-eindpunt waarin PowerShell wordt uitgevoerd. Dit kan elk eindpunt zijn dat is geregistreerd op de lokale computer, inclusief de standaardeindpunten voor externe communicatie van PowerShell of een aangepast eindpunt met specifieke mogelijkheden voor gebruikersrollen.
Voorbeeld: pwsh -ConfigurationName AdminRoles
-ConfigurationFile
Hiermee geeft u een sessieconfiguratie (.pssc
) bestandspad. De configuratie in het configuratiebestand wordt toegepast op de PowerShell-sessie.
Voorbeeld: pwsh -ConfigurationFile "C:\ProgramData\PowerShell\MyConfig.pssc"
-CustomPipeName
Hiermee geeft u de naam op die moet worden gebruikt voor een extra IPC-server (benoemde pipe) die wordt gebruikt voor foutopsporing en andere communicatie tussen processen. Dit biedt een voorspelbaar mechanisme voor het maken van verbinding met andere PowerShell-exemplaren. Meestal gebruikt met de parameter CustomPipeName op Enter-PSHostProcess
.
Deze parameter is geïntroduceerd in PowerShell 6.2.
Bijvoorbeeld:
# PowerShell instance 1
pwsh -CustomPipeName mydebugpipe
# PowerShell instance 2
Enter-PSHostProcess -CustomPipeName mydebugpipe
-EncodedCommand | -e | -ec
Accepteert een base64--egecodeerde tekenreeksversie van een opdracht. Gebruik deze parameter om opdrachten naar PowerShell te verzenden waarvoor complexe, geneste quotering is vereist. De Base64-weergave moet een UTF-16LE-gecodeerde tekenreeks zijn.
Bijvoorbeeld:
$command = 'dir "c:\program files" '
$bytes = [System.Text.Encoding]::Unicode.GetBytes($command)
$encodedCommand = [Convert]::ToBase64String($bytes)
pwsh -encodedcommand $encodedCommand
-ExecutionPolicy | -ex | -ep
Hiermee stelt u het standaarduitvoeringsbeleid voor de huidige sessie in en slaat u dit op in de omgevingsvariabele $env:PSExecutionPolicyPreference
. Met deze parameter wordt het permanent geconfigureerde uitvoeringsbeleid niet gewijzigd.
Deze parameter is alleen van toepassing op Windows-computers. Op niet-Windows-platforms worden de parameter en de opgegeven waarde genegeerd.
-InputFormat | -inp | -if
Beschrijft de indeling van gegevens die naar PowerShell worden verzonden. Geldige waarden zijn 'Text' (tekenreeksen) of 'XML' (geserialiseerde CLIXML-indeling).
-Interactive | -i
Een interactieve prompt aan de gebruiker presenteren. Inverse voor de parameter NonInteractive.
-Login | -l
In Linux en macOS start u PowerShell als aanmeldingsshell, met behulp van /bin/sh om aanmeldingsprofielen zoals /etc/profile en ~/.profile uit te voeren. In Windows doet deze schakeloptie niets.
Belangrijk
Deze parameter moet eerst PowerShell starten als aanmeldingsshell. Deze parameter wordt genegeerd als deze op een andere positie wordt doorgegeven.
Als u pwsh
wilt instellen als de aanmeldingsshell op UNIX--like-besturingssystemen:
Controleer of het volledige absolute pad naar
pwsh
wordt vermeld onder/etc/shells
- Dit pad is meestal iets als
/usr/bin/pwsh
in Linux of/usr/local/bin/pwsh
op macOS - Bij sommige installatiemethoden wordt deze vermelding automatisch toegevoegd tijdens de installatie
- Als
pwsh
niet aanwezig is in/etc/shells
, gebruikt u een editor om het pad toe te voegen aanpwsh
op de laatste regel. Hiervoor zijn verhoogde bevoegdheden vereist om te bewerken.
- Dit pad is meestal iets als
Gebruik het hulpprogramma chsh om de shell van uw huidige gebruiker in te stellen op
pwsh
:chsh -s /usr/bin/pwsh
Waarschuwing
Het instellen van pwsh
omdat de aanmeldingsshell momenteel niet wordt ondersteund in Windows Subsystem voor Linux (WSL) en het instellen van pwsh
als de aanmeldingsshell kan leiden tot het interactief starten van WSL.
-MTA
Start PowerShell met behulp van een appartement met meerdere threads. Deze switch is alleen beschikbaar in Windows. Het gebruik van deze parameter op niet-Windows-platforms resulteert in een fout.
-NoExit | -noe
Sluit niet af na het uitvoeren van opstartopdrachten.
Voorbeeld: pwsh -NoExit -Command Get-Date
-NoLogo | -nol
Verbergt de banner bij het opstarten van interactieve sessies.
-NonInteractive | -noni
Deze schakeloptie wordt gebruikt om sessies te maken waarvoor geen gebruikersinvoer nodig is. Dit is handig voor scripts die worden uitgevoerd in geplande taken of CI/CD-pijplijnen. Pogingen om interactieve functies te gebruiken, zoals Read-Host
of bevestigingsprompts, resulteren in afsluitfouten in instructies in plaats van vast te hangen.
-NoProfile | -nop
Laadt de PowerShell-profielen niet.
-NoProfileLoadTime
Hiermee verbergt u de laadtijdtekst van het PowerShell-profiel die wordt weergegeven bij het opstarten wanneer de laadtijd langer is dan 500 milliseconden.
-OutputFormat | -o | -of
Bepaalt hoe de uitvoer van PowerShell is opgemaakt. Geldige waarden zijn 'Text' (tekenreeksen) of 'XML' (geserialiseerde CLIXML-indeling).
Voorbeeld: pwsh -o XML -c Get-Date
Wanneer u wordt aangeroepen in een PowerShell-sessie, krijgt u gedeserialiseerde objecten als uitvoer eerder gewone tekenreeksen. Wanneer de uitvoer wordt aangeroepen vanuit andere shells, is de uitvoer tekenreeksgegevens die zijn opgemaakt als CLIXML-tekst.
-SettingsFile | -settings
Hiermee overschrijft u het systeembestand-wide powershell.config.json
-instellingen voor de sessie. Systeem--wide-instellingen worden standaard gelezen uit de powershell.config.json
in de $PSHOME
directory.
Houd er rekening mee dat deze instellingen niet worden gebruikt door het eindpunt dat is opgegeven door het argument -ConfigurationName
.
Voorbeeld: pwsh -SettingsFile c:\myproject\powershell.config.json
-SSHServerMode | -sshs
Wordt gebruikt in sshd_config voor het uitvoeren van PowerShell als een SSH-subsysteem. Het is niet bedoeld of ondersteund voor ander gebruik.
-STA
Start PowerShell met behulp van een appartement met één thread. Dit is de standaardwaarde. Deze switch is alleen beschikbaar op het Windows-platform. Het gebruik van deze parameter op niet-Windows-platforms resulteert in een fout.
-Version | -v
Geeft de versie van PowerShell weer. Aanvullende parameters worden genegeerd.
-WindowStyle | -w
Hiermee stelt u de vensterstijl voor de sessie in. Geldige waarden zijn normaal, geminimaliseerd, gemaximaliseerd en verborgen. Deze parameter is alleen van toepassing op Windows. Het gebruik van deze parameter op niet-Windows-platforms resulteert in een fout.
-WorkingDirectory | -wd | -wo
Hiermee stelt u de oorspronkelijke werkmap in door deze uit te voeren bij het opstarten. Elk geldig PowerShell-bestandspad wordt ondersteund.
Als u PowerShell in uw basismap wilt starten, gebruikt u: pwsh -WorkingDirectory ~
-Help, -?, /?
Geeft help weer voor pwsh
. Als u een pwsh-opdracht in PowerShell typt, moet u de opdrachtparameters vooraf laten gaan met een afbreekstreepje (-
), geen slash (/
).