about_Pwsh

  • Article

Description courte

Explique comment utiliser l’interface d’ine pwsh de commande-l. Affiche les paramètres d’entrée de commande-let décrit la syntaxe.

Description longue

Pour plus d’informations sur les options d’entrée de commande-lpour Windows PowerShell 5.1, consultez about_PowerShell_exe.

Syntaxe

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

Paramètres

Tous les paramètres ne respectent pas la casse-i.

-File | -f

Si la valeur 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. Il s’agit de la même chose que de 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 les valeurs sont présentes dans la ligne de commande. Le script spécifié s’exécute dans l’étendue locale (« point source ») de la nouvelle session, afin que les fonctions et les variables créées par le script soient disponibles lors de la nouvelle session. Entrez le chemin de fichier de script et tous les paramètres. 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 Fichier sont interprétés comme le chemin de 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 switch 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 les cmd.exe résultats du script reçoit la chaîne $env:windir littérale, car elle n’a aucune signification spéciale pour l’interpréteur de commandes actuel cmd.exe . Le $env:windir style de référence des variables d’environnement peut être utilisé à l’intérieur d’un paramètre Command , car il 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 plutôt .\ que pour $PSScriptRoot représenter le répertoire d’exécution actuel : pwsh -File %~dp0test.ps1 -TestParam %windir%. Si vous avez utilisé .\test.ps1à la place, PowerShell lève une erreur car elle ne peut pas trouver le chemin littéral .\test.ps1

Remarque

Le paramètre File ne peut pas prendre en charge les scripts à l’aide d’un paramètre qui attend un tableau de valeurs d’argument. Cela est malheureusement une limitation de la façon dont une commande native obtient des valeurs d’argument. Lorsque vous appelez un exécutable natif (par powershell exemple, ou pwsh), il ne sait pas quoi faire avec un tableau, de sorte qu’il est passé en tant que 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.

Pour plus d’informations, consultez $LASTEXITCODE about_Automatic_Variables.

Similaire à -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

Remarque

À compter de PowerShell 7.2, le paramètre Fichier 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 s’ils ont été tapés à l’invite de commandes PowerShell, puis quittent, 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 La commande 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ée à partir d’une expression ou analysée par l’hôte PowerShell en tant que bloc de script littéral placé entre accolades ({}), avant d’être passé à pwsh.

pwsh -Command {Get-WinEvent -LogName security}

Dans cmd.exe, il n’existe aucune chose telle qu’un bloc de script (ou un type ScriptBlock ), de sorte que la valeur passée à Command est toujours une chaîne. Vous pouvez écrire un bloc de script à l’intérieur de la chaîne, mais au lieu d’être exécuté, il se comporte exactement comme si vous l’avez tapé à une invite PowerShell classique, en imprimant le contenu du bloc de script à vous.

Une chaîne passée à la commande est toujours exécutée en tant que code PowerShell. Par conséquent, les accolades de bloc de script ne sont souvent pas requises 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, il est possible d’utiliser l’opérateur d’appel& :

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

Si la valeur de Command est une chaîne, Command doit être le dernier paramètre pour pwsh, car tous les arguments suivants 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 renvoyés à l’interpréteur de commandes parent en tant qu’objets XML désérialisés, et non à des objets actifs. Pour les autres interpréteurs de commandes, les résultats sont retournés sous forme de chaînes.

Si la valeur de La commande est -, le texte de la commande est lu à partir d’une entrée standard. Vous devez rediriger l’entrée standard lors de l’utilisation du 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 pour 1 le code de sortie du processus. Pour conserver le code de sortie spécifique, ajoutez exit $LASTEXITCODE à votre chaîne de commande ou bloc de script.

Pour plus d’informations, consultez $LASTEXITCODE about_Automatic_Variables.

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

-CommandWithArgs | -cWa

Il s’agit d’une fonctionnalité expérimentale ajoutée dans la version 7.4.

Exécute une commande PowerShell avec des arguments. Contrairement -Commandà ce paramètre, ce paramètre remplit la $args variable n générée-iqui peut être utilisée par la commande.

La première chaîne est la commande. Les chaînes supplémentaires délimitées par des espaces blancs sont les arguments.

Par exemple :

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

Cet exemple produit la sortie suivante :

arg: arg1
arg: arg2

-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

-ConfigurationFile

Spécifie un chemin de fichier de configuration de session (.pssc). La configuration contenue dans le fichier de configuration est appliquée à la session PowerShell.

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

-CustomPipeName

Spécifie le nom à utiliser pour un serveur IPC supplémentaire (canal nommé) utilisé pour le débogage et d’autres communications interprocessus. 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 codée en base64-ed’une commande. Utilisez ce paramètre pour envoyer des commandes à PowerShell qui nécessitent des guillemets complexes et imbriqués. 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. Sur les plateformes non-Windows, le paramètre et la valeur fournies sont ignorés.

-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ésenter une invite interactive à l’utilisateur. Inverse pour le paramètre NonInteractive.

-Login | -l

Sur Linux et macOS, démarre PowerShell comme interpréteur de commandes de connexion, à l’aide de /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 commencer par démarrer PowerShell en tant qu’interpréteur de commandes de connexion. Ce paramètre est ignoré s’il est passé à une autre position.

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

  • Vérifiez que le chemin absolu complet à pwsh répertorier sous /etc/shells

    • Ce chemin d’accès est généralement similaire /usr/bin/pwsh à 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 ce n’est pas le /etc/shellscas, utilisez un éditeur pour ajouter le chemin d’accès sur pwsh la dernière ligne. Cela nécessite des privilèges élevés pour modifier.

  • 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 comme 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. L’utilisation de ce paramètre sur les plateformes non-Windows entraîne une erreur.

-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 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. Toutes les tentatives d’utilisation de fonctionnalités interactives, telles que Read-Host les invites de confirmation, entraînent la fin des erreurs d’instruction au lieu d’être suspendues.

-NoProfile | -nop

Ne charge pas les profils PowerShell.

-NoProfileLoadTime

Masque le texte du temps de chargement du profil PowerShell affiché au démarrage lorsque le temps de chargement dépasse 500 millisecondes.

-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é dans une session PowerShell, vous obtenez des objets désérialisés en tant que chaînes de sortie plutôt simples. Lorsqu’elle est appelée à partir d’autres interpréteurs de commandes, la sortie est mise en forme de données de chaîne en tant que 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 dans le powershell.config.json$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. Elle n’est pas prévue ou prise 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. L’utilisation de ce paramètre sur les plateformes non-Windows entraîne une erreur.

-Version | -v

Affiche la version de PowerShell. Des 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. Ce paramètre s’applique uniquement à Windows. L’utilisation de ce paramètre sur les plateformes non-Windows entraîne une erreur.

-WorkingDirectory | -wd | -wO

Définit le répertoire de travail initial en s’exécutant au démarrage. Tout chemin d’accès 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 commande avec un trait d’union (-), pas une barre oblique (/).