about_Scripts

Description courte

Décrit comment exécuter et écrire des scripts dans PowerShell.

Description longue

Un script est un fichier texte brut qui contient une ou plusieurs commandes PowerShell. Les scripts PowerShell ont une .ps1 extension de fichier.

L’exécution d’un script ressemble beaucoup à l’exécution d’une applet de commande. Vous tapez le chemin d’accès et le nom du fichier du script et utilisez les paramètres pour envoyer des données et définir des options. Vous pouvez exécuter des scripts sur votre ordinateur ou dans une session à distance sur un autre ordinateur.

L’écriture d’un script enregistre une commande pour une utilisation ultérieure et facilite le partage avec d’autres utilisateurs. Plus important encore, il vous permet d’exécuter les commandes simplement en tapant le chemin d’accès du script et le nom de fichier. Les scripts peuvent être aussi simples qu’une seule commande dans un fichier ou aussi étendue qu’un programme complexe.

Les scripts ont des fonctionnalités supplémentaires, telles que le #Requires commentaire spécial, l’utilisation de paramètres, la prise en charge des sections de données et la signature numérique pour la sécurité. Vous pouvez également écrire des rubriques d’aide pour les scripts et pour toutes les fonctions du script.

Comment exécuter un script

Avant de pouvoir exécuter un script sur Windows, vous devez modifier la stratégie d’exécution PowerShell par défaut. La stratégie d’exécution ne s’applique pas à PowerShell s’exécutant sur des plateformes non Windows.

La stratégie d’exécution par défaut, Restrictedempêche l’exécution de tous les scripts, y compris les scripts que vous écrivez sur l’ordinateur local. Pour plus d'informations, voir about_Execution_Policies.

La stratégie d’exécution est enregistrée dans le Registre. Vous devez donc la modifier une seule fois sur chaque ordinateur.

Pour modifier la stratégie d’exécution, utilisez la procédure suivante.

À l'invite de commandes, tapez :

Set-ExecutionPolicy AllSigned

or

Set-ExecutionPolicy RemoteSigned

La modification prend effet immédiatement.

Pour exécuter un script, tapez le nom complet et le chemin d’accès complet au fichier de script.

Par exemple, pour exécuter le script Get-ServiceLog.ps1 dans le répertoire C:\Scripts, tapez :

C:\Scripts\Get-ServiceLog.ps1

Pour exécuter un script dans le répertoire actif, tapez le chemin d’accès au répertoire actif ou utilisez un point pour représenter le répertoire actif, suivi d’une barre oblique inverse (.\).

Par exemple, pour exécuter le script ServicesLog.ps1 dans le répertoire local, tapez :

.\Get-ServiceLog.ps1

Si le script a des paramètres, tapez les paramètres et les valeurs de paramètre après le nom du fichier de script.

Par exemple, la commande suivante utilise le paramètre ServiceName du script Get-ServiceLog pour demander un journal d’activité de service WinRM.

.\Get-ServiceLog.ps1 -ServiceName WinRM

En tant que fonctionnalité de sécurité, PowerShell n’exécute pas de scripts lorsque vous double-cliquez sur l’icône de script dans Explorateur de fichiers ou lorsque vous tapez le nom du script sans chemin d’accès complet, même lorsque le script se trouve dans le répertoire actif. Pour plus d’informations sur l’exécution de commandes et de scripts dans PowerShell, consultez about_Command_Precedence.

Exécuter avec PowerShell

À partir de PowerShell 3.0, vous pouvez exécuter des scripts à partir de Explorateur de fichiers.

Pour utiliser la fonctionnalité « Exécuter avec PowerShell » :

Exécutez Explorateur de fichiers, cliquez avec le bouton droit sur le nom du fichier de script, puis sélectionnez « Exécuter avec PowerShell ».

La fonctionnalité « Exécuter avec PowerShell » est conçue pour exécuter des scripts qui n’ont pas de paramètres requis et ne retournent pas de sortie à l’invite de commandes.

Pour plus d’informations, voir about_Run_With_PowerShell.

Exécution de scripts sur d’autres ordinateurs

Pour exécuter un script sur un ou plusieurs ordinateurs distants, utilisez le paramètre FilePath de l’applet Invoke-Command de commande.

Entrez le chemin d’accès et le nom de fichier du script comme valeur du paramètre FilePath . Le script doit résider sur l'ordinateur local ou dans un répertoire auquel celui-ci peut accéder.

La commande suivante exécute le Get-ServiceLog.ps1 script sur les ordinateurs distants nommés Server01 et Server02.

Invoke-Command -ComputerName Server01,Server02 -FilePath `
  C:\Scripts\Get-ServiceLog.ps1

Obtenir de l’aide pour les scripts

L’applet de commande Get-Help obtient les rubriques d’aide pour les scripts, ainsi que pour les applets de commande et d’autres types de commandes. Pour obtenir la rubrique d’aide d’un script, tapez Get-Help le chemin d’accès et le nom de fichier du script. Si le chemin d’accès au script se trouve dans votre Path variable d’environnement, vous pouvez omettre le chemin d’accès.

Par exemple, pour obtenir de l’aide pour le script ServicesLog.ps1, tapez :

get-help C:\admin\scripts\ServicesLog.ps1

Comment écrire un script

Un script peut contenir des commandes PowerShell valides, notamment des commandes uniques, des commandes qui utilisent le pipeline, les fonctions et les structures de contrôle, telles que les instructions If et les boucles For.

Pour écrire un script, ouvrez un nouveau fichier dans un éditeur de texte, tapez les commandes et enregistrez-les dans un fichier avec un nom de fichier valide avec l’extension de .ps1 fichier.

L’exemple suivant est un script simple qui obtient les services qui s’exécutent sur le système actuel et les enregistre dans un fichier journal. Le nom de fichier journal est créé à partir de la date actuelle.

$date = (get-date).dayofyear
get-service | out-file "$date.log"

Pour créer ce script, ouvrez un éditeur de texte ou un éditeur de script, tapez ces commandes, puis enregistrez-les dans un fichier nommé ServiceLog.ps1.

Paramètres dans les scripts

Pour définir des paramètres dans un script, utilisez une instruction Param. L’instruction Param doit être la première instruction d’un script, à l’exception des commentaires et des #Require instructions.

Les paramètres de script fonctionnent comme les paramètres de fonction. Les valeurs des paramètres sont disponibles pour toutes les commandes du script. Toutes les fonctionnalités des paramètres de fonction, y compris l’attribut Parameter et ses arguments nommés, sont également valides dans les scripts.

Lors de l’exécution du script, les utilisateurs de script tapez les paramètres après le nom du script.

L’exemple suivant montre un Test-Remote.ps1 script qui a un paramètre ComputerName . Les deux fonctions de script peuvent accéder à la valeur du paramètre ComputerName .

param ($ComputerName = $(throw "ComputerName parameter is required."))

function CanPing {
   $error.clear()
   $tmp = test-connection $computername -erroraction SilentlyContinue

   if (!$?)
       {write-host "Ping failed: $ComputerName."; return $false}
   else
       {write-host "Ping succeeded: $ComputerName"; return $true}
}

function CanRemote {
    $s = new-pssession $computername -erroraction SilentlyContinue

    if ($s -is [System.Management.Automation.Runspaces.PSSession])
        {write-host "Remote test succeeded: $ComputerName."}
    else
        {write-host "Remote test failed: $ComputerName."}
}

if (CanPing $computername) {CanRemote $computername}

Pour exécuter ce script, tapez le nom du paramètre après le nom du script. Par exemple :

C:\PS> .\test-remote.ps1 -computername Server01

Ping succeeded: Server01
Remote test failed: Server01

Pour plus d’informations sur l’instruction Param et les paramètres de fonction, consultez about_Functions et about_Functions_Advanced_Parameters.

Écriture d’aide pour les scripts

Vous pouvez écrire une rubrique d’aide pour un script à l’aide de l’une des deux méthodes suivantes :

• Aide basée sur les commentaires pour les scripts

  Créez une rubrique d’aide à l’aide de mot clé spéciales dans les commentaires. Pour créer de l’aide basée sur des commentaires pour un script, les commentaires doivent être placés au début ou à la fin du fichier de script. Pour plus d’informations sur l’aide basée sur les commentaires, consultez about_Comment_Based_Help.

• Aide XML pour les scripts

  Créez une rubrique d’aide basée sur XML, telle que le type qui est généralement créé pour les applets de commande. L’aide XML est requise si vous traduisez des rubriques d’aide en plusieurs langues.

Pour associer le script à la rubrique d’aide basée sur XML, utilisez le fichier . Commentaire d’aide ExternalHelp mot clé. Pour plus d’informations sur le mot clé ExternalHelp, consultez about_Comment_Based_Help. Pour plus d’informations sur l’aide basée sur XML, consultez Comment écrire l’aide sur les applets de commande.

Retour d’une valeur de sortie

Par défaut, les scripts ne retournent pas d’état de sortie lorsque le script se termine. Vous devez utiliser l’instruction exit pour retourner un code de sortie d’un script. Par défaut, l’instruction exit retourne 0. Vous pouvez fournir une valeur numérique pour retourner un autre état de sortie. Un code de sortie différent de zéro signale généralement un échec.

Sur Windows, n’importe quel nombre entre [int]::MinValue et [int]::MaxValue est autorisé.

Dans PowerShell, l’instruction exit définit la valeur de la $LASTEXITCODE variable. Dans l’interpréteur de commandes Windows (cmd.exe), l’instruction exit définit la valeur de la variable d’environnement %ERRORLEVEL% .

Tout argument qui n’est pas numérique ou en dehors de la plage spécifique à la plateforme est traduit en valeur de 0.

Étendue de script et approvisionnement par points

Chaque script s’exécute dans sa propre étendue. Les fonctions, variables, alias et lecteurs créés dans le script existent uniquement dans l’étendue du script. Vous ne pouvez pas accéder à ces éléments ou à leurs valeurs dans l’étendue dans laquelle le script s’exécute.

Pour exécuter un script dans une autre étendue, vous pouvez spécifier une étendue, telle que Global ou Local, ou vous pouvez pointer la source du script.

La fonctionnalité d’approvisionnement par points vous permet d’exécuter un script dans l’étendue actuelle au lieu de l’étendue du script. Lorsque vous exécutez un script source, les commandes du script s’exécutent comme si vous les aviez tapées à l’invite de commandes. Les fonctions, variables, alias et lecteurs créés par le script sont créés dans l’étendue dans laquelle vous travaillez. Une fois le script exécuté, vous pouvez utiliser les éléments créés et accéder à leurs valeurs dans votre session.

Pour dot sourcer un script, tapez un point (.) et un espace avant le chemin du script.

Par exemple :

. C:\scripts\UtilityFunctions.ps1

or

. .\UtilityFunctions.ps1

Une fois le UtilityFunctions.ps1 script exécuté, les fonctions et variables créées par le script sont ajoutées à l’étendue actuelle.

Par exemple, le UtilityFunctions.ps1 script crée la New-Profile fonction et la $ProfileName variable.

#In UtilityFunctions.ps1

function New-Profile
{
  Write-Host "Running New-Profile function"
  $profileName = split-path $profile -leaf

  if (test-path $profile)
    {write-error "Profile $profileName already exists on this computer."}
  else
    {new-item -type file -path $profile -force }
}

Si vous exécutez le UtilityFunctions.ps1 script dans sa propre étendue de script, la New-Profile fonction et la $ProfileName variable existent uniquement pendant l’exécution du script. Lorsque le script se termine, la fonction et la variable sont supprimées, comme illustré dans l’exemple suivant.

C:\PS> .\UtilityFunctions.ps1

C:\PS> New-Profile
The term 'new-profile' is not recognized as a cmdlet, function, operable
program, or script file. Verify the term and try again.
At line:1 char:12
+ new-profile <<<<
   + CategoryInfo          : ObjectNotFound: (new-profile:String) [],
   + FullyQualifiedErrorId : CommandNotFoundException

C:\PS> $profileName
C:\PS>

Lorsque vous pointez la source du script et que vous l’exécutez, le script crée la New-Profile fonction et la $ProfileName variable dans votre session dans votre étendue. Une fois le script exécuté, vous pouvez utiliser la New-Profile fonction dans votre session, comme illustré dans l’exemple suivant.

C:\PS> . .\UtilityFunctions.ps1

C:\PS> New-Profile

    Directory: C:\Users\juneb\Documents\WindowsPowerShell

    Mode    LastWriteTime     Length Name
    ----    -------------     ------ ----
    -a---   1/14/2009 3:08 PM      0 Microsoft.PowerShellISE_profile.ps1

C:\PS> $profileName
Microsoft.PowerShellISE_profile.ps1

Pour plus d’informations sur l’étendue, consultez about_Scopes.

Scripts dans les modules

Un module est un ensemble de ressources PowerShell associées qui peuvent être distribuées en tant qu’unité. Vous pouvez utiliser des modules pour organiser vos scripts, fonctions et autres ressources. Vous pouvez également utiliser des modules pour distribuer votre code à d’autres personnes et obtenir du code à partir de sources approuvées.

Vous pouvez inclure des scripts dans vos modules, ou créer un module de script, qui est un module qui se compose entièrement ou principalement d’un script et de ressources de prise en charge. Un module de script n’est qu’un script avec une extension de fichier .psm1.

Pour plus d’informations sur les modules, consultez about_Modules.

Autres fonctionnalités de script

PowerShell propose de nombreuses fonctionnalités utiles que vous pouvez utiliser dans des scripts.

• #Requires - Vous pouvez utiliser une #Requires instruction pour empêcher l’exécution d’un script sans modules ou composants logiciels enfichables spécifiés et une version spécifiée de PowerShell. Pour plus d’informations, consultez about_Requires.

• $PSCommandPath - Contient le chemin d’accès complet et le nom du script en cours d’exécution. Ce paramètre est valide dans tous les scripts. Cette variable automatique est introduite dans PowerShell 3.0.

• $PSScriptRoot - Contient le répertoire à partir duquel un script est en cours d’exécution. Dans PowerShell 2.0, cette variable est valide uniquement dans les modules de script (.psm1). À compter de PowerShell 3.0, il est valide dans tous les scripts.

• $MyInvocation - La $MyInvocation variable automatique contient des informations sur le script actuel, y compris des informations sur la façon dont elle a été démarrée ou « appelée ». Vous pouvez utiliser cette variable et ses propriétés pour obtenir des informations sur le script pendant son exécution. Par exemple, le $MyInvocation. La variable MyCommand.Path contient le chemin d’accès et le nom de fichier du script. $MyInvocation. La ligne contient la commande qui a démarré le script, y compris tous les paramètres et valeurs.

  À compter de PowerShell 3.0, $MyInvocation deux nouvelles propriétés fournissent des informations sur le script qui a appelé ou appelé le script actuel. Les valeurs de ces propriétés sont remplies uniquement lorsque l’appelant ou l’appelant est un script.

  • PSCommandPath contient le chemin complet et le nom du script qui a appelé ou appelé le script actuel.

  • PSScriptRoot contient le répertoire du script qui a appelé ou appelé le script actuel.

  Contrairement aux $PSCommandPath variables automatiques, $PSScriptRoot qui contiennent des informations sur le script actuel, les propriétés PSCommandPath et PSScriptRoot de la $MyInvocation variable contiennent des informations sur le script qui a appelé le script actuel.

• Sections données : vous pouvez utiliser le Data mot clé pour séparer les données de la logique dans les scripts. Les sections de données peuvent également faciliter la localisation. Pour plus d’informations, consultez about_Data_Sections et about_Script_Internationalization.

• Signature de script : vous pouvez ajouter une signature numérique à un script. Selon la stratégie d’exécution, vous pouvez utiliser des signatures numériques pour restreindre l’exécution de scripts pouvant inclure des commandes non sécurisées. Pour plus d’informations, consultez about_Execution_Policies et about_Signing.

Voir aussi

• about_Command_Precedence
• about_Comment_Based_Help
• about_Execution_Policies
• about_Functions
• about_Modules
• about_Profiles
• about_Requires
• about_Run_With_PowerShell
• about_Scopes
• about_Script_Blocks
• about_Signing
• Invoke-Command