À propos des scripts

Article
06/21/2023

Description courte

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

Description longue

Un script est un fichier de 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 de fichier du script et utilisez des 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 distante sur un autre ordinateur.

L’écriture d’un script enregistre une commande pour une utilisation ultérieure et facilite son partage avec d’autres personnes. Plus important encore, il vous permet d’exécuter les commandes simplement en tapant le chemin du script et le nom du fichier. Les scripts peuvent être aussi simples qu’une commande unique dans un fichier ou aussi étendus 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 exécuté sur des plateformes non Windows.

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

La stratégie d’exécution étant enregistrée dans le Registre, vous ne devez la modifier qu’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

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 script.

Par exemple, la commande suivante utilise le paramètre ServiceName du script Get-ServiceLog pour demander un journal de l’activité du 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 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, consultez 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 du 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 suivi du chemin d’accès et du nom de fichier du script. Si le chemin du script se trouve dans votre Path variable d’environnement, vous pouvez omettre le chemin.

Par exemple, pour obtenir de l’aide sur 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, des fonctions et des 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 #Require des instructions éventuelles.

Les paramètres de script fonctionnent comme des paramètres de fonction. Les valeurs de paramètre 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 tapent 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 Comment-Based pour les scripts

Create une rubrique d’aide à l’aide de mots clés spéciaux dans les commentaires. Pour créer une 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-Based pour les scripts

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

Pour associer le script à la rubrique d’aide xml, utilisez . Mot clé d’aide externalHelp. 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 Guide pratique pour écrire l’aide sur l’applet de commande.

Retour d’une valeur de sortie

Par défaut, les scripts ne retournent pas de status de sortie à la fin du script. Vous devez utiliser l’instruction exit pour renvoyer un code de sortie à partir d’un script. Par défaut, l’instruction exit retourne 0. Vous pouvez fournir une valeur numérique pour retourner une autre status de sortie. Un code de sortie différent de zéro signale généralement une défaillance.

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

Sous Unix, seuls les nombres positifs compris entre [byte]::MinValue (0) et [byte]::MaxValue (255) sont autorisés. Un nombre négatif dans la plage de -1 à -255 est automatiquement traduit en nombre positif en ajoutant 256. Par exemple, -2 est transformé en 254.

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 non numérique ou en dehors de la plage spécifique à la plateforme est traduit en valeur de 0.

Étendue du script et approvisionnement en points

Chaque script s’exécute dans sa propre étendue. Les fonctions, variables, alias et lecteurs qui sont 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, par exemple Global ou Local, ou vous pouvez indiquer la source du script.

La fonctionnalité d’approvisionnement par points vous permet d’exécuter un script dans l’étendue actuelle plutôt que dans l’étendue du script. Lorsque vous exécutez un script qui est généré par des points, 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 créer un script, tapez un point (.) et un espace avant le chemin du script.

Par exemple :

. C:\scripts\UtilityFunctions.ps1

. .\UtilityFunctions.ps1

Une fois le UtilityFunctions.ps1 script exécuté, les fonctions et les 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 le script et l’exécutez, le script crée la New-Profile fonction et la $ProfileName variable de 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 est simplement un script avec une extension de fichier .psm1.

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

Autres fonctionnalités de script

PowerShell offre 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 exécuté. 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 actif, notamment des informations sur la façon dont il a été démarré ou « appelé ». 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 du fichier du script. $MyInvocation. Line 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 renseignées uniquement lorsque l’appelant ou l’appelant est un script.
- PSCommandPath contient le chemin d’accès 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.
$PSCommandPath Contrairement aux variables automatiques et$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 actif.
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 qui peuvent inclure des commandes non sécurisées. Pour plus d’informations, consultez about_Execution_Policies et about_Signing.