Write-Progress

  • Référence
Module:
Microsoft.PowerShell.Utility

Affiche une barre de progression dans une fenêtre Commande PowerShell.

Syntax

Write-Progress
     [-Activity] <String>
     [[-Status] <String>]
     [[-Id] <Int32>]
     [-PercentComplete <Int32>]
     [-SecondsRemaining <Int32>]
     [-CurrentOperation <String>]
     [-ParentId <Int32>]
     [-Completed]
     [-SourceId <Int32>]
     [<CommonParameters>]

Description

L’applet Write-Progress de commande affiche une barre de progression dans une fenêtre de commande PowerShell qui représente l’état d’une commande ou d’un script en cours d’exécution. Vous pouvez sélectionner les indicateurs reflétés par la barre et le texte qui s'affiche au-dessus et en dessous de celle-ci.

Exemples

Exemple 1 : Afficher la progression d’une boucle For

for ($i = 1; $i -le 100; $i++ )
{
    Write-Progress -Activity "Search in Progress" -Status "$i% Complete:" -PercentComplete $i;
}

Cette commande affiche la progression d'une boucle For qui compte de 1 à 100.

L’applet Write-Progress de commande inclut un en-tête Activityde barre d’état, une ligne d’état et la variable $i (le compteur dans la boucle For), qui indique l’intégralité relative de la tâche.

Exemple 2 : Afficher la progression des boucles For imbriquées

for($I = 1; $I -lt 101; $I++ )
{
    Write-Progress -Activity Updating -Status 'Progress->' -PercentComplete $I -CurrentOperation OuterLoop
    for($j = 1; $j -lt 101; $j++ )
    {
        Write-Progress -Id 1 -Activity Updating -Status 'Progress' -PercentComplete $j -CurrentOperation InnerLoop
    }
}

Updating
Progress ->
 [ooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo]
OuterLoop
Updating
Progress
 [oooooooooooooooooo                                                   ]
InnerLoop

Cet exemple affiche la progression de deux boucles For imbriquées, chacune d'elles étant représentée par une barre de progression.

La Write-Progress commande de la deuxième barre de progression inclut le paramètre ID qui le distingue de la première barre de progression.

Sans le paramètre Id , les barres de progression sont superimposées les unes sur les autres au lieu d’être affichées un en dessous de l’autre.

Exemple 3 : Afficher la progression lors de la recherche d’une chaîne

# Use Get-EventLog to get the events in the System log and store them in the $Events variable.
$Events = Get-EventLog -LogName system
# Pipe the events to the ForEach-Object cmdlet.
$Events | ForEach-Object -Begin {
    # In the Begin block, use Clear-Host to clear the screen.
    Clear-Host
    # Set the $i counter variable to zero.
    $i = 0
    # Set the $out variable to a empty string.
    $out = ""
} -Process {
    # In the Process script block search the message property of each incoming object for "bios".
    if($_.message -like "*bios*")
    {
        # Append the matching message to the out variable.
        $out=$out + $_.Message
    }
    # Increment the $i counter variable which is used to create the progress bar.
    $i = $i+1
    # Use Write-Progress to output a progress bar.
    # The Activity and Status parameters create the first and second lines of the progress bar heading, respectively.
    Write-Progress -Activity "Searching Events" -Status "Progress:" -PercentComplete ($i/$Events.count*100)
} -End {
    # Display the matching messages using the out variable.
    $out
}

Cette commande affiche la progression d'une commande qui recherche la chaîne « bios » dans le journal des événements système.

La valeur du paramètre PercentComplete est calculée en divisant le nombre d’événements qui ont été traités $I par le nombre total d’événements récupérés $Events.count , puis en multipliant ce résultat par 100.

Exemple 4 : Afficher la progression pour chaque niveau d’un processus imbriqué

foreach ( $i in 1..10 ) {
  Write-Progress -Id 0 "Step $i"
  foreach ( $j in 1..10 ) {
    Write-Progress -Id 1 -ParentId 0 "Step $i - Substep $j"
    foreach ( $k in 1..10 ) {
      Write-Progress -Id 2  -ParentId 1 "Step $i - Substep $j - iteration $k"; start-sleep -m 150
    }
  }
}

Step 1
     Processing
    Step 1 - Substep 2
         Processing
        Step 1 - Substep 2 - Iteration 3
             Processing

Dans cet exemple, vous pouvez utiliser le paramètre ParentId pour avoir une sortie en retrait pour afficher les relations parent/enfant en cours de chaque étape.

Paramètres

-Activity

Spécifie la première ligne de texte dans le titre au-dessus de la barre d'état. Ce texte décrit l'activité dont la progression est montrée.

Type:String
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Completed

Indique si la barre de progression est visible. Si ce paramètre est omis, Write-Progress affiche les informations de progression.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-CurrentOperation

Spécifie la ligne de texte en dessous de la barre de progression. Ce texte décrit l'opération qui est actuellement en cours.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Id

Spécifie un ID qui distingue chaque barre de progression des autres. Utilisez ce paramètre quand vous créez plusieurs barres de progression dans une même commande. Si les barres de progression n'ont pas des ID distincts, elles sont superposées, au lieu de s'afficher dans une série.

Type:Int32
Position:2
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ParentId

Spécifie l’activité parente de l’activité active. Utilisez la valeur -1 si l'activité en cours n'a pas d'activité parente.

Type:Int32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-PercentComplete

Spécifie le pourcentage de l'activité qui est terminé. Utilisez la valeur -1 si le pourcentage terminé est inconnu ou non applicable.

Type:Int32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SecondsRemaining

Spécifie le nombre de secondes prévues restant avant la fin de l'activité. Utilisez la valeur -1 si le nombre de secondes restantes est inconnu ou non applicable.

Type:Int32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SourceId

Spécifie la source de l’enregistrement. Vous pouvez l’utiliser à la place de l’ID , mais ne peut pas être utilisé avec d’autres paramètres tels que ParentId.

Type:Int32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Status

Spécifie la deuxième ligne de texte dans le titre au-dessus de la barre d'état. Ce texte décrit l'état actuel de l'activité.

Type:String
Position:1
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Entrées

None

Vous ne pouvez pas diriger d'entrée vers cette applet de commande.

Sorties

None

Write-Progress ne génère aucune sortie.

Notes

Si la barre de progression n’apparaît pas, vérifiez la valeur de la $ProgressPreference variable. Si la valeur est définie à SilentlyContinue, la barre de progression n'est pas affichée. Pour plus d’informations sur les préférences PowerShell, consultez about_Preference_Variables.

Les paramètres de l’applet de commande correspondent aux propriétés de la classe System.Management.Automation.ProgressRecord . Pour plus d’informations, consultez La classe ProgressRecord.