about_Pwsh

Description courte

Explique comment utiliser l’interface de commande pwsh-line. Affiche les paramètres de la commande-line et décrit la syntaxe.

Description longue

Syntaxe

pwsh[.exe]
   [[-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 <SettingsFilePath>]
   [-SSHServerMode]
   [-STA]
   [-Version]
   [-WindowStyle <style>]
   [-WorkingDirectory <directoryPath>]

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

Paramètres

Tous les paramètres respectent la casse-i.

-File | -f

Si la valeur de est -, le texte de File la commande est lu à partir d’une entrée standard. L’exécution pwsh -File - sans entrée standard redirigée démarre une session régulière. Cela revient à ne pas spécifier le File paramètre du tout.

Il s’agit du paramètre par défaut si aucun paramètre n’est présent, mais que des valeurs sont présentes dans la ligne de commande. Le script spécifié s’exécute dans l’étendue locale (« dot-sourced »), de sorte que les fonctions et les variables créées par le script soient disponibles dans la session active. Entrez le chemin d’accès au fichier de script et les paramètres éventuels. Le fichier doit être le dernier paramètre de la commande, car tous les caractères tapés après le nom du paramètre File sont interprétés comme le chemin du fichier de script suivi des paramètres de script.

En règle générale, les paramètres de commutateur d’un script sont inclus ou omis. Par exemple, la commande suivante utilise le paramètre All du fichier de script Get-Script.ps1 : -File .\Get-Script.ps1 -All

Dans de rares cas, vous devrez peut-être fournir une valeur booléenne pour un paramètre switch. Pour fournir une valeur booléenne pour un paramètre de commutateur dans la valeur du paramètre File , utilisez le paramètre normalement suivi immédiatement d’un signe deux-points et de la valeur booléenne, par exemple : -File .\Get-Script.ps1 -All:$False.

Les paramètres passés au script sont passés comme chaînes littérales (après l’interprétation de l’interpréteur de commandes actuel). Par exemple, si vous êtes dans cmd.exe et que vous souhaitez passer une valeur de variable d’environnement, vous devez utiliser la cmd.exe syntaxe : pwsh -File .\test.ps1 -TestParam %windir%

En revanche, l’exécution pwsh -File .\test.ps1 -TestParam $env:windir dans cmd.exe entraîne dans le script la réception de la chaîne $env:windir littérale, car elle n’a aucune signification particulière pour l’interpréteur de commandes actuel cmd.exe . Le $env:windir style de référence de variable d’environnement peut être utilisé à l’intérieur d’un paramètre Command , car il y est interprété comme du code PowerShell.

De même, si vous souhaitez exécuter la même commande à partir d’un script Batch, vous utilisez %~dp0 au lieu de ou $PSScriptRoot pour représenter le répertoire d’exécution .\ actuel : pwsh -File %~dp0test.ps1 -TestParam %windir%. Si vous utilisez .\test.ps1à la place , PowerShell génère une erreur, car il ne trouve pas le chemin littéral .\test.ps1

Notes

Le paramètre File ne peut pas prendre en charge les scripts utilisant un paramètre qui attend un tableau de valeurs d’argument. Malheureusement, il s’agit d’une limitation de la façon dont une commande native obtient des valeurs d’argument. Lorsque vous appelez un exécutable natif (tel que powershell ou pwsh), il ne sait pas quoi faire avec un tableau, il est donc passé sous forme de chaîne.

Lorsque le fichier de script se termine par une exit commande, le code de sortie du processus est défini sur l’argument numérique utilisé avec la exit commande. Avec l’arrêt normal, le code de sortie est toujours 0.

Comme pour -Command, lorsqu’une erreur de fin de script se produit, le code de sortie est défini sur 1. Toutefois, contrairement à -Command, lorsque l’exécution est interrompue avec Ctrl-C , le code de sortie est 0.

Notes

À partir de PowerShell 7.2, le paramètre File accepte .ps1 uniquement les fichiers sur Windows. Si un autre type de fichier est fourni, une erreur est levée. Ce comportement est spécifique à Windows. Sur d’autres plateformes, PowerShell tente d’exécuter d’autres types de fichiers.

-Command | -c

Exécute les commandes spécifiées (et tous les paramètres) comme si elles avaient été tapées à l’invite de commandes PowerShell, puis se ferme, sauf si le NoExit paramètre est spécifié.

La valeur de Command peut être -, un bloc de script ou une chaîne. Si la valeur de Command est -, le texte de la commande est lu à partir d’une entrée standard.

Le paramètre Command accepte uniquement un bloc de script pour l’exécution lorsqu’il peut reconnaître la valeur passée à Command en tant que type ScriptBlock . Cela n’est possible que lors de l’exécution pwsh à partir d’un autre hôte PowerShell. Le type ScriptBlock peut être contenu dans une variable existante, retourné à partir d’une expression ou analysé par l’hôte PowerShell en tant que bloc de script littéral placé dans des accolades ({}), avant d’être passé à pwsh.

pwsh -Command {Get-WinEvent -LogName security}

Dans cmd.exe, il n’existe pas de bloc de script (ou de type ScriptBlock ), de sorte que la valeur passée à Command sera toujours une chaîne. Si vous écrivez un bloc de script dans la chaîne, il se comportera exactement comme s’il avait été tapé dans une invite PowerShell classique, affichant le contenu du bloc de script au lieu de s’exécuter.

Une chaîne passée à Command est toujours exécutée en tant que code PowerShell. Par conséquent, les accolades de blocs de script ne sont souvent pas nécessaires en premier lieu lors de l’exécution à partir de cmd.exe. Pour exécuter un bloc de script inline défini à l’intérieur d’une chaîne, l’opérateur &d’appel peut être utilisé :

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

Si la valeur de Command est une chaîne, Command doit être le dernier paramètre de pwsh, car tous les arguments qui la suivent sont interprétés comme faisant partie de la commande à exécuter.

Lorsqu’ils sont appelés à partir d’une session PowerShell existante, les résultats sont retournés à l’interpréteur de commandes parent sous forme d’objets XML désérialisés, et non d’objets actifs. Pour les autres interpréteurs de commandes, les résultats sont retournés sous forme de chaînes.

Si la valeur de Command est -, le texte de la commande est lu à partir d’une entrée standard. Vous devez rediriger l’entrée standard lorsque vous utilisez le paramètre Command avec une entrée standard. Par exemple :

@'
"in"

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

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

Cet exemple produit la sortie suivante :

in
hi there
out

Le code de sortie du processus est déterminé par l’état de la dernière commande (exécutée) dans le bloc de script. Le code de sortie est 0 quand $? est $true ou 1 quand $? est $false. Si la dernière commande est un programme externe ou un script PowerShell qui définit explicitement un code de sortie autre que 0 ou 1, ce code de sortie est converti en pour le code de 1 sortie de processus. Pour conserver le code de sortie spécifique, ajoutez exit $LASTEXITCODE à votre chaîne de commande ou à votre bloc de script.

De même, la valeur 1 est retournée lorsqu’une erreur de fin de script (arrêt de l’exécution), telle qu’un throw ou -ErrorAction Stop, se produit ou quand l’exécution est interrompue avec Ctrl-C.

-ConfigurationName | -config

Spécifie un point de terminaison de configuration dans lequel PowerShell est exécuté. Il peut s’agir de n’importe quel point de terminaison inscrit sur l’ordinateur local, y compris les points de terminaison de communication à distance PowerShell par défaut ou un point de terminaison personnalisé ayant des fonctionnalités de rôle utilisateur spécifiques.

Exemple : pwsh -ConfigurationName AdminRoles

-CustomPipeName

Spécifie le nom à utiliser pour un serveur IPC supplémentaire (canal nommé) utilisé pour le débogage et d’autres communications inter-processus. Cela offre un mécanisme prévisible pour la connexion à d’autres instances PowerShell. Généralement utilisé avec le paramètre CustomPipeName sur Enter-PSHostProcess.

Ce paramètre a été introduit dans PowerShell 6.2.

Par exemple :

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

-EncodedCommand | -e | -ec

Accepte une version de chaîne ncodée en Base64-ed’une commande. Utilisez ce paramètre pour envoyer des commandes à PowerShell qui nécessitent des guillemets imbriqués complexes. La représentation Base64 doit être une chaîne encodée UTF-16LE.

Par exemple :

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

-ExecutionPolicy | -ex | -ep

Définit la stratégie d’exécution par défaut pour la session active et l’enregistre dans la variable d’environnement $env:PSExecutionPolicyPreference . Ce paramètre ne modifie pas les stratégies d’exécution configurées de manière permanente.

Ce paramètre s’applique uniquement aux ordinateurs Windows. La $env:PSExecutionPolicyPreference variable d’environnement n’existe pas sur les plateformes non Windows.

-InputFormat | -inp | -if

Décrit le format des données envoyées à PowerShell. Les valeurs valides sont « Text » (chaînes de texte) ou « XML » (format CLIXML sérialisé).

-Interactive | -i

Présentez une invite interactive à l’utilisateur. Inverse pour le paramètre NonInteractive.

-Login | -l

Sur Linux et macOS, démarre PowerShell en tant qu’interpréteur de commandes de connexion, en utilisant /bin/sh pour exécuter des profils de connexion tels que /etc/profile et ~/.profile. Sur Windows, ce commutateur ne fait rien.

Important

Ce paramètre doit venir en premier pour démarrer PowerShell en tant qu’interpréteur de commandes de connexion. Le passage de ce paramètre à une autre position sera ignoré.

Pour configurer pwsh en tant qu’interpréteur de commandes de connexion sur les systèmes d’exploitation UNIX-like :

  • Vérifiez que le chemin d’accès absolu complet à pwsh est répertorié sous /etc/shells

    • Ce chemin est généralement quelque chose comme /usr/bin/pwsh sur Linux ou /usr/local/bin/pwsh sur macOS
    • Avec certaines méthodes d’installation, cette entrée est ajoutée automatiquement au moment de l’installation
    • Si pwsh n’est pas présent dans /etc/shells, utilisez un éditeur pour ajouter le chemin à pwsh sur la dernière ligne. Cela nécessite des privilèges élevés pour la modification.
  • Utilisez l’utilitaire chsh pour définir l’interpréteur de commandes de votre utilisateur actuel sur pwsh:

    chsh -s /usr/bin/pwsh
    

Avertissement

La définition pwsh de l’interpréteur de commandes de connexion n’est actuellement pas prise en charge sur Sous-système Windows pour Linux (WSL), et la tentative de définition pwsh en tant qu’interpréteur de commandes de connexion peut entraîner l’impossibilité de démarrer WSL de manière interactive.

-MTA

Démarrez PowerShell à l’aide d’un appartement multithread. Ce commutateur est disponible uniquement sur Windows.

-NoExit | -noe

Ne quitte pas après l’exécution de commandes de démarrage.

Exemple : pwsh -NoExit -Command Get-Date

-NoLogo | -nol

Masque la bannière de copyright au démarrage des sessions interactives.

-NonInteractive | -noni

Ce commutateur est utilisé pour créer des sessions qui ne doivent pas nécessiter d’entrée utilisateur. Cela est utile pour les scripts qui s’exécutent dans des tâches planifiées ou des pipelines CI/CD. Toute tentative d’utilisation de fonctionnalités interactives, telles que Read-Host ou des invites de confirmation, entraîne des erreurs de fin d’instruction au lieu de se suspendre.

-NoProfile | -nop

Ne charge pas les profils PowerShell.

-OutputFormat | -o | -of

Détermine la mise en forme de la sortie de PowerShell. Les valeurs valides sont « Text » (chaînes de texte) ou « XML » (format CLIXML sérialisé).

Exemple : pwsh -o XML -c Get-Date

Quand vous êtes appelé avec une session PowerShell, vous obtenez des objets désérialisés en tant que chaînes plutôt simples de sortie. Lorsqu’elle est appelée à partir d’autres interpréteurs de commandes, la sortie est des données de chaîne au format texte CLIXML.

-SettingsFile | -settings

Remplace le fichier de paramètres de l’ide powershell.config.json système-wpour la session. Par défaut, les paramètres de l’ide système-wsont lus à partir du powershell.config.json dans le $PSHOME répertoire .

Notez que ces paramètres ne sont pas utilisés par le point de terminaison spécifié par l’argument -ConfigurationName .

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

-SSHServerMode | -sshs

Utilisé dans sshd_config pour exécuter PowerShell en tant que sous-système SSH. Il n’est pas prévu ou pris en charge pour toute autre utilisation.

-STA

Démarrez PowerShell à l’aide d’un appartement à thread unique. Il s’agit de la valeur par défaut. Ce commutateur est disponible uniquement sur la plateforme Windows.

-Version | -v

Affiche la version de PowerShell. Les paramètres supplémentaires sont ignorés.

-WindowStyle | -w

Définit le style de fenêtre pour la session. Les valeurs valides sont Normal, Hidden, Minimized et Maximized.

-WorkingDirectory | -wd

Définit le répertoire de travail initial en exécutant au démarrage. Tout chemin de fichier PowerShell valide est pris en charge.

Pour démarrer PowerShell dans votre répertoire de base, utilisez : pwsh -WorkingDirectory ~

-Help, -?, /?

Affiche l’aide pour pwsh. Si vous tapez une commande pwsh dans PowerShell, ajoutez les paramètres de la commande avec un trait d’union (-), et non une barre oblique (/).