about_PowerShell_exe

Description courte

Explique comment utiliser l’interface powershell.exe de ligne de commande. Affiche les paramètres de ligne de commande et décrit la syntaxe.

Description longue

Pour plus d’informations sur les options de ligne de commande pour PowerShell 7, consultez about_Pwsh.

SYNTAX

PowerShell[.exe]
    [-PSConsoleFile <file> | -Version <version>]
    [-NoLogo]
    [-NoExit]
    [-Sta]
    [-Mta]
    [-NoProfile]
    [-NonInteractive]
    [-InputFormat {Text | XML}]
    [-OutputFormat {Text | XML}]
    [-WindowStyle <style>]
    [-EncodedArguments <Base64EncodedArguments>]
    [-EncodedCommand <Base64EncodedCommand>]
    [-ConfigurationName <string>]
    [-File - | <filePath> <args>]
    [-ExecutionPolicy <ExecutionPolicy>]
    [-Command - | { <script-block> [-args <arg-array>] }
                | { <string> [<CommandParameters>] } ]

PowerShell[.exe] -Help | -? | /?

Paramètres

Tous les paramètres ne respectent pas la casse.

-File - | <filePath><args>

La valeur de File peut être - ou un chemin de fichier et des paramètres facultatifs. Si la valeur du fichier est -, les commandes sont lues à partir d’une entrée standard.

Si la valeur du fichier est un chemin de fichier, le script 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 dans cette 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. Toutes les valeurs typées après le paramètre File sont interprétées comme le chemin de fichier de script et les paramètres passés à ce script. Par exemple : -File .\Get-Script.ps1 -Domain Central

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 Get-Script.ps1 fichier de script : -File .\Get-Script.ps1 -All

Dans de rares cas, vous devrez peut-être fournir une valeur booléenne pour un paramètre. Il n’est pas possible de passer une valeur booléenne explicite pour un paramètre switch lors de l’exécution d’un script de cette façon. Cette limitation a été supprimée dans PowerShell 6 (pwsh.exe).

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 : powershell.exe -File .\test.ps1 -TestParam %windir%

En revanche, l’exécution powershell.exe -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 utilisez .\test.ps1 à la place, PowerShell génère 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.

Si la valeur du fichier est -, les commandes sont lues à partir d’une entrée standard. L’exécution powershell -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. Lors de la lecture à partir d’une entrée standard, les instructions d’entrée sont exécutées une instruction à la fois comme si elles étaient tapées à l’invite de commandes PowerShell. Si une instruction n’analyse pas correctement, l’instruction n’est pas exécutée. Le code de sortie du processus est déterminé par l’état de la dernière commande (exécutée). Avec la réussite de l’exécution, le code de sortie est toujours 0. 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.

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 Pour plus d’informations, consultez $LASTEXITCODE about_Automatic_Variables.

-Command

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 powershell.exe à 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é à powershell.exe.

powershell -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, l’opérateur & d’appel peut être utilisé :

powershell.exe -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 Command est -, les commandes sont lues à 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

Lors de la lecture à partir d’une entrée standard, l’entrée est analysée et exécutée une instruction à la fois, comme si elles étaient tapées à l’invite de commandes PowerShell. Si le code d’entrée n’analyse pas correctement, l’instruction n’est pas exécutée. Sauf si vous utilisez le -NoExit paramètre, la session PowerShell se ferme lorsqu’il n’y a plus d’entrée à lire à partir d’une entrée standard.

Le code de sortie du processus est déterminé par l’état de la dernière commande (exécutée) dans l’entrée. 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. 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.

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.

-ConfigurationName <, chaîne>

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.

-EncodedArguments <Base64EncodedArguments>

Accepte des arguments de commande de version de chaîne encodés en Base64. Utilisez ce paramètre pour envoyer des arguments nécessitant des guillemets complexes et imbriqués. La représentation Base64 doit être une chaîne encodée UTF-16LE.

-EncodedCommand <Base64EncodedCommand>

Accepte une version de chaîne codée en base 64 d’une commande. Utilisez ce paramètre pour envoyer à PowerShell des commandes qui nécessitent des guillemets ou des accolades complexes. La chaîne doit être mise en forme à l’aide de l’encodage de caractères UTF-16LE.

-ExecutionPolicy ExecutionPolicy <>

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 la stratégie d’exécution PowerShell définie dans le Registre. Pour plus d’informations sur les stratégies d’exécution PowerShell, notamment une liste de valeurs valides, consultez about_Execution_Policies.

-InputFormat {Text | XML}

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é).

-Mta

Démarre PowerShell à l’aide d’un cloisonnement multithread. Ce paramètre est introduit dans PowerShell 3.0. Dans PowerShell 2.0, le cloisonnement par défaut est multithread (MTA). Dans PowerShell 3.0, le cloisonnement par défaut est monothread (STA).

-NoExit

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

-NonInteractive

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.

-NoLogo

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

-NoProfile

Ne charge pas le profil PowerShell.

-OutputFormat {Text | XML}

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é).

-PSConsoleFile <FilePath>

Charge le fichier de console PowerShell spécifié. Entrez le chemin d’accès et le nom du fichier de console. Pour créer un fichier de console, utilisez l’applet de commande Export-Console dans PowerShell.

-Sta

Démarre PowerShell à l’aide d’un cloisonnement monothread. Dans Windows PowerShell 2.0, le cloisonnement par défaut est multithread (MTA). Dans Windows PowerShell 3.0, le cloisonnement par défaut est monothread (STA).

-Version <de PowerShell>

Démarre la version spécifiée de PowerShell. Les valeurs valides sont 2.0 et 3.0. La version que vous spécifiez doit être installée sur le système. Si Windows PowerShell 3.0 est installé sur l’ordinateur, « 3.0 » est la version par défaut. Sinon, « 2.0 » est la version par défaut. Pour plus d'informations, consultez Installation de PowerShell.

-Style de fenêtre WindowStyle <>

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

-Help, -?, /?

Affiche l’aide pour PowerShell.exe. Si vous tapez une PowerShell.exe commande dans une session PowerShell, ajoutez les paramètres de commande avec un trait d’union (-), pas une barre oblique (/). Vous pouvez utiliser un trait d’union ou une barre oblique dans cmd.exe.

Remarques

Remarque de dépannage : Dans PowerShell 2.0, le démarrage de certains programmes de la console PowerShell échoue avec un LastExitCode de 0xc0000142.

EXEMPLES

# Create a new PowerShell session and load a saved console file
PowerShell -PSConsoleFile sqlsnapin.psc1

# Create a new PowerShell V2 session with text input, XML output, and no logo
PowerShell -Version 2.0 -NoLogo -InputFormat text -OutputFormat XML

# Execute a PowerShell Command in a session
PowerShell -Command "Get-EventLog -LogName security"

# Run a script block in a session
PowerShell -Command {Get-EventLog -LogName security}

# An alternate way to run a command in a new session
PowerShell -Command "& {Get-EventLog -LogName security}"

# To use the -EncodedCommand parameter:
$command = "dir 'c:\program files' "
$bytes = [System.Text.Encoding]::Unicode.GetBytes($command)
$encodedCommand = [Convert]::ToBase64String($bytes)
powershell.exe -encodedCommand $encodedCommand