Write-Progress

  • Referenz
Modul:
Microsoft.PowerShell.Utility

Zeigt eine Statusanzeige in einem PowerShell-Befehlsfenster an.

Syntax

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

Beschreibung

Das Write-Progress Cmdlet zeigt eine Statusleiste in einem PowerShell-Befehlsfenster an, die die status eines ausgeführten Befehls oder Skripts darstellt. Sie können die dargestellten Indikatoren wählen, sowie den Text, der über und unter der Statusanzeige erscheint.

PowerShell 7.2 hat die automatische Variable hinzugefügt, mit der $PSStyle gesteuert wird, wie PowerShell bestimmte Informationen mithilfe von ANSI-Escapesequenzen anzeigt. Mit $PSStyle.Progress dem Member können Sie das Rendering der Statusansichtsleiste steuern.

  • $PSStyle.Progress.Style: Eine ANSI-Zeichenfolge, die den Renderingstil festlegt.
  • $PSStyle.Progress.MaxWidth: Legt die maximale Breite der Ansicht fest. Der Standardwert lautet 120. Der Mindestwert ist 18.
  • $PSStyle.Progress.View: Eine Enumeration mit den Werten Minimal und Classic. Classic ist das vorhandene Rendering ohne Änderungen. Minimal ist ein einzeiliges minimales Rendering. Minimal ist die Standardeinstellung.

Weitere Informationen zu $PSStylefinden Sie unter about_ANSI_Terminals.md.

Hinweis

Wenn Host das virtuelle Terminal nicht unterstützt, wird $PSStyle.Progress.View automatisch auf Classic festgelegt.

Beispiele

Beispiel 1: Anzeigen des Status einer For-Schleife

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

Dieser Befehl zeigt den Fortschritt einer for Schleife an, die von 1 bis 100 zählt.

Das Write-Progress Cmdlet enthält eine status BalkenüberschriftActivity, eine status Zeile und die Variable $i (der Indikator in der for Schleife), die die relative Vollständigkeit der Aufgabe angibt.

Beispiel 2: Anzeigen des Fortschritts geschachtelter For-Schleifen

$PSStyle.Progress.View = 'Classic'

for($I = 0; $I -lt 10; $I++ ) {
    $OuterLoopProgressParameters = @{
        Activity         = 'Updating'
        Status           = 'Progress->'
        PercentComplete  = $I * 10
        CurrentOperation = 'OuterLoop'
    }
    Write-Progress @OuterLoopProgressParameters
    for($j = 1; $j -lt 101; $j++ ) {
        $InnerLoopProgressParameters = @{
            ID               = 1
            Activity         = 'Updating'
            Status           = 'Progress'
            PercentComplete  = $j
            CurrentOperation = 'InnerLoop'
        }
        Write-Progress @InnerLoopProgressParameters
        Start-Sleep -Milliseconds 25
    }
}

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

In diesem Beispiel wird die Statusansicht auf Classic festgelegt und dann der Fortschritt von zwei geschachtelten for Schleifen angezeigt, die jeweils durch eine Statusleiste dargestellt werden.

Der Write-Progress Befehl für die zweite Statusleiste enthält den Id-Parameter , der ihn von der ersten Statusleiste unterscheidet.

Ohne den Id-Parameter würden die Statusanzeigen einander überlagert, anstatt untereinander angezeigt zu werden.

Beispiel 3: Anzeigen des Fortschritts bei der Suche nach einer Zeichenfolge

# Use Get-WinEvent to get the events in the System log and store them in the $Events variable.
$Events = Get-WinEvent -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 an 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
    # Determine the completion percentage
    $Completed = ($i/$Events.count) * 100
    # 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 $Completed
} -End {
    # Display the matching messages using the out variable.
    $out
}

Dieser Befehl zeigt den Status eines Befehls zum Suchen der Zeichenfolge „bios“ im Systemereignisprotokoll an.

Der Wert des PercentComplete-Parameters wird berechnet, indem die Anzahl der verarbeiteten $i Ereignisse durch die Gesamtanzahl der abgerufenen $Events.count Ereignisse dividiert und dann das Ergebnis mit 100 multipliziert wird.

Beispiel 4: Anzeigen des Fortschritts für jede Ebene eines geschachtelten Prozesses

$PSStyle.Progress.View = 'Classic'

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 -Milliseconds 150
    }
  }
}

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

In diesem Beispiel können Sie den ParentId-Parameter verwenden, um eine eingezogene Ausgabe zu haben, um die Beziehungen zwischen übergeordnetem und untergeordnetem Element im Fortschritt jedes Schritts anzuzeigen.

Parameter

-Activity

Gibt die erste Textzeile in der Überschrift über der Statusanzeige an. Dieser Text beschreibt die Aktivität, deren Status gemeldet wird.

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

-Completed

Gibt an, ob die Statusanzeige sichtbar ist. Wenn dieser Parameter nicht angegeben wird, Write-Progress werden Statusinformationen angezeigt.

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

-CurrentOperation

Gibt die Textzeile unterhalb der Statusanzeige an. In diesem Text wird der vorgang beschrieben, der derzeit ausgeführt wird.

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

-Id

Gibt eine ID an, die die einzelnen Statusanzeigen voneinander unterscheidet. Verwenden Sie diesen Parameter, wenn Sie in einem einzigen Befehl mehr als eine Statusanzeige erstellen. Wenn die Statusanzeigen nicht über unterschiedliche IDs verfügen, werden sie überlagert, anstatt in einer Reihe angezeigt zu werden. Negative Werte sind nicht zulässig.

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

-ParentId

Gibt die übergeordnete Aktivität der aktuellen Aktivität an. Verwenden Sie den Wert -1 , wenn die aktuelle Aktivität keine übergeordnete Aktivität aufweist.

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

-PercentComplete

Gibt den Prozentsatz der abgeschlossenen Aktivität an. Verwenden Sie den Wert -1 , wenn der vollständige Prozentsatz unbekannt oder nicht zutreffend ist.

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

-SecondsRemaining

Gibt die voraussichtliche Anzahl von Sekunden an, bis die Aktivität abgeschlossen ist. Verwenden Sie den Wert -1 , wenn die verbleibende Anzahl von Sekunden unbekannt oder nicht zutreffend ist.

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

-SourceId

Gibt die Quelle des Datensatzes an. Sie können dies anstelle von ID verwenden, aber nicht mit anderen Parametern wie ParentId verwendet werden.

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

-Status

Gibt die zweite Textzeile in der Überschrift über der Statusanzeige an. Dieser Text beschreibt den aktuellen Status der Aktivität.

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

Eingaben

None

Sie können keine Objekte an dieses Cmdlet übergeben.

Ausgaben

None

Dieses Cmdlet gibt keine Ausgabe zurück.

Hinweise

Wenn die Statusanzeige nicht angezeigt wird, überprüfen Sie den Wert der $ProgressPreference Variablen. Wenn der Wert auf SilentlyContinuefestgelegt ist, wird die Statusleiste nicht angezeigt. Weitere Informationen zu PowerShell-Einstellungen finden Sie unter about_Preference_Variables.

Die Parameter des Cmdlets entsprechen den Eigenschaften der System.Management.Automation.ProgressRecord-Klasse . Weitere Informationen finden Sie unter ProgressRecord-Klasse.