about_Pwsh

Korte beschrijving

Hierin wordt uitgelegd hoe u de ine-interface van de pwsh opdracht-lgebruikt. Geeft de opdracht-line parameters weer en beschrijft de syntaxis.

Lange beschrijving

Zie about_PowerShell_exe voor meer informatie over de ine-opties-lvoor Windows PowerShell 5.1.

Syntaxis

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 | -? | /?

Parameters

Alle parameters zijn niet hoofdlettergevoelig-i.

-File | -f

De waarde van Bestand kan een bestandspad en optionele parameters zijn - . Als de waarde van Bestand is -, worden opdrachten gelezen uit standaardinvoer.

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 Get-Script.ps1 scriptbestand 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 Bestand, 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 een cmd.exe omgevingsvariabelewaarde wilt doorgeven, gebruikt u de cmd.exe syntaxis: pwsh -File .\test.ps1 -TestParam %windir%

Het uitvoeren van resultaten in cmd.exe het script dat de letterlijke tekenreeks $env:windir ontvangt, heeft daarentegen pwsh -File .\test.ps1 -TestParam $env:windir geen speciale betekenis voor de huidige cmd.exe shell. De $env:windir verwijzing naar de omgevingsvariabele kan worden gebruikt in een opdrachtparameter , omdat deze daar wordt geïnterpreteerd als PowerShell-code.

En als u dezelfde opdracht wilt uitvoeren vanuit een Batch-script, gebruikt %~dp0 u in plaats van .\ of $PSScriptRoot om de huidige uitvoeringsmap weer te geven: pwsh -File %~dp0test.ps1 -TestParam %windir% Als u .\test.ps1 in plaats daarvan gebruikt, genereert PowerShell een fout omdat het letterlijke pad niet kan worden gevonden .\test.ps1

Notitie

De parameter Bestand 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 (zoals powershell of pwsh) aanroept, weet deze niet wat u moet doen met een matrix, dus het wordt doorgegeven als een tekenreeks.

Als de waarde van Bestand is -, worden opdrachten gelezen uit standaardinvoer. Als pwsh -File - u zonder omgeleide standaardinvoer uitvoert, wordt een gewone sessie gestart. Dit is hetzelfde als het helemaal niet opgeven van de File parameter. Bij het lezen van standaardinvoer worden de invoerinstructies één instructie tegelijk uitgevoerd alsof ze zijn getypt bij de PowerShell-opdrachtprompt. Als een instructie niet correct wordt geparseerd, wordt de instructie niet uitgevoerd. De afsluitcode van het proces wordt bepaald door de status van de laatste (uitgevoerde) opdracht in de invoer. Bij normale beëindiging is de afsluitcode altijd 0. 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 exit opdracht.

-CommandNet als wanneer er een scriptafsluitfout optreedt, wordt de afsluitcode ingesteld op 1. In tegenstelling tot bij -Command, wanneer de uitvoering wordt onderbroken met Ctrl+C, is de afsluitcode echter .0 Zie about_Automatic_Variables voor meer informatie.$LASTEXITCODE

Notitie

Vanaf PowerShell 7.2 accepteert .ps1 de parameter Bestand alleen 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

De waarde van Command kan -zijn, een scriptblok of een tekenreeks. Als de waarde van Command is -, wordt de opdrachttekst gelezen uit de standaardinvoer.

De opdrachtparameter accepteert alleen een scriptblok voor uitvoering wanneer deze de waarde kan herkennen die als scriptbloktype is doorgegeven aan Command. Dit is alleen mogelijk wanneer deze wordt uitgevoerd pwsh vanaf een andere PowerShell-host. Het ScriptBlock-type kan zijn opgenomen in een bestaande variabele, geretourneerd uit een expressie of geparseerd door de PowerShell-host als een letterlijk scriptblok dat tussen accolades ({}) staat voordat het wordt doorgegeven aan pwsh.

pwsh -Command {Get-WinEvent -LogName security}

In cmd.exe, er is geen scriptblok (of ScriptBlock-type ), dus de waarde die aan Command wordt doorgegeven, is altijd 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 aan Command wordt doorgegeven, wordt nog steeds uitgevoerd als PowerShell-code, dus het script blokkeert accolades zijn vaak niet vereist in de eerste plaats wanneer deze wordt uitgevoerd.cmd.exe Als u een inlinescriptblok wilt uitvoeren dat in een tekenreeks is gedefinieerd, kan de aanroepoperator & worden gebruikt:

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 -, worden de opdrachten gelezen uit standaardinvoer. U moet standaardinvoer omleiden wanneer u de opdrachtparameter gebruikt met standaardinvoer. Voorbeeld:

@'
"in"

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

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

In dit voorbeeld wordt de volgende uitvoer gegenereerd:

in
hi there
out

Bij het lezen van standaardinvoer wordt de invoer geparseerd en één instructie tegelijk uitgevoerd, alsof deze zijn getypt bij de PowerShell-opdrachtprompt. Als de invoercode niet correct wordt geparseerd, wordt de instructie niet uitgevoerd. Tenzij u de -NoExit parameter gebruikt, wordt de PowerShell-sessie afgesloten wanneer er geen invoer meer is om uit standaardinvoer te lezen.

De afsluitcode van het proces wordt bepaald door de status van de laatste (uitgevoerde) opdracht in de invoer. De afsluitcode is 0 wanneer $? of $true 1 wanneer$?.$false Als de laatste opdracht een extern programma of een PowerShell-script is waarmee expliciet een andere afsluitcode dan 0 of 1wordt ingesteld, wordt die afsluitcode geconverteerd naar 1 voor procesafsluitcode. Op dezelfde manier wordt de waarde 1 geretourneerd wanneer een script-afsluitfout (runspace-terminating) optreedt, zoals a throw of-ErrorAction Stop, of wanneer de uitvoering wordt onderbroken met Ctrl+C.

Als u de specifieke afsluitcode wilt behouden, voegt u deze toe exit $LASTEXITCODE aan de opdrachtreeks of het scriptblok. Zie about_Automatic_Variables voor meer informatie.$LASTEXITCODE

-CommandWithArgs | -cwa

Dit is een experimentele functie die is toegevoegd in 7.4.

Hiermee voert u een PowerShell-opdracht uit met argumenten. In tegenstelling tot -Commanddeze parameter wordt de $args ingebouwde-in-variabele ingevuld die door de opdracht kan worden gebruikt.

De eerste tekenreeks is de opdracht. Extra tekenreeksen gescheiden door witruimte zijn de argumenten.

Voorbeeld:

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

In dit voorbeeld wordt de volgende uitvoer gegenereerd:

arg: arg1
arg: arg2

Notitie

Argument parseren met aanhalingstekens zorgt ervoor dat het voorbeeld mislukt als het wordt uitgevoerd van cmd.exe of powershell.exe. Als u deze wilt uitvoeren, kunt u dit gebruiken

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

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 bestandspad (.psscsessieconfiguratie) op. 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.

Voorbeeld:

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

-EncodedCommand | -e | -ec

Accepteert een met 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.

Voorbeeld:

$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 het op in de $env:PSExecutionPolicyPreference omgevingsvariabele. 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.

Instellen pwsh als de aanmeldingsshell op UNIX-like-besturingssystemen:

• Controleer of het volledige absolute pad waarnaar pwsh wordt vermeld onder /etc/shells

  • Dit pad is meestal iets als /usr/bin/pwsh in Linux of /usr/local/bin/pwsh in macOS
  • Bij sommige installatiemethoden wordt deze vermelding automatisch toegevoegd tijdens de installatie
  • Als pwsh deze niet aanwezig /etc/shellsis, gebruikt u een editor om het pad toe te voegen aan pwsh de laatste regel. Hiervoor zijn verhoogde bevoegdheden vereist om te bewerken.

• Gebruik het hulpprogramma chsh om de shell van uw huidige gebruiker in te stellen oppwsh:

  chsh -s /usr/bin/pwsh
  

Waarschuwing

Het instellen pwsh als de aanmeldingsshell wordt momenteel niet ondersteund op Windows-subsysteem voor Linux (WSL) en het instellen pwsh als de aanmeldingsshell kan ertoe leiden dat WSL mogelijk niet interactief kan worden gestart.

-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 fouten bij het beëindigen van 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

Overschrijft het systeem-ide-instellingenbestand-wpowershell.config.json voor de sessie. Standaard worden systeem-ide-instellingen-wgelezen uit de powershell.config.json $PSHOME map.

Houd er rekening mee dat deze instellingen niet worden gebruikt door het eindpunt dat is opgegeven door het -ConfigurationName argument.

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 standaardinstelling. 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 dit uitvoerbare PowerShell-bestand 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 wilt starten in uw basismap, 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 (-), niet een slash (/).