Freigeben über

Write-Progress

Modul:
Microsoft.PowerShell.Utility Module

Zeigt eine Statusanzeige in einem PowerShell-Befehlsfenster an.

Syntax

Default (Standardwert) 

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

Beschreibung

Das cmdlet Write-Progress zeigt eine Statusanzeige in einem PowerShell-Befehlsfenster an, das den Status eines ausgeführten Befehls oder Skripts darstellt. Sie können die Indikatoren auswählen, die die Leiste widerspiegelt, und den Text, der oberhalb und unterhalb der Statusleiste angezeigt wird.

PowerShell 7.2 hat die $PSStyle automatischen Variable hinzugefügt, die verwendet wird, um zu steuern, wie PowerShell bestimmte Informationen mithilfe von ANSI-Escapesequenzen anzeigt. Mit dem $PSStyle.Progress-Element können Sie das Rendern der Statusansichtsleiste steuern.

  • $PSStyle.Progress.Style – Eine ANSI-Zeichenfolge, die den Renderingstil festlegt.
  • $PSStyle.Progress.MaxWidth – Legt die maximale Breite der Ansicht fest. Wird standardmäßig auf 120 festgelegt. Der Mindestwert ist 18.
  • $PSStyle.Progress.View – Eine Enumeration mit Werten, Minimal und Classic. Classic ist das vorhandene Rendering ohne Änderungen. Minimal ist eine einzeilige minimale Darstellung. Minimal ist die Standardeinstellung.

Weitere Informationen zu $PSStylefinden Sie unter about_ANSI_Terminals.md.

Hinweis

Wenn der Host virtuelles Terminal nicht unterstützt, wird $PSStyle.Progress.View automatisch auf Classicfestgelegt.

Beispiele

Beispiel 1: Anzeigen des Fortschritts 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 zwischen 1 und 100 zählt.

Das Cmdlet Write-Progress enthält eine Statusleistenüberschrift Activity, eine Statuszeile und die Variable $i (der Zähler in der for Schleife), die die relative Vollständigkeit des Vorgangs 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           = 'Inner Progress'
            PercentComplete  = $j
            CurrentOperation = 'InnerLoop'
        }
        Write-Progress @InnerLoopProgressParameters
        Start-Sleep -Milliseconds 25
    }
}

Updating
Progress ->
 [ooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo]
OuterLoop
Updating
Inner 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 Befehl Write-Progress für die zweite Statusleiste enthält den parameter ID, der ihn von der ersten Statusleiste unterscheidet.

Ohne den parameter ID werden die Statusanzeigen nebeneinander angeordnet, anstatt untereinander angezeigt zu werden.

Hinweis

In diesem Beispiel wird die Statusansicht auf Classicfestgelegt, wodurch die CurrentOperation- Werte für jede Statusleiste angezeigt werden. Wenn die Statusansicht auf Minimalfestgelegt ist, werden die CurrentOperation- Werte nicht angezeigt.

Beispiel 3: Anzeigen des Fortschritts beim Suchen 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
}

Mit diesem Befehl wird der Fortschritt eines Befehls angezeigt, um die Zeichenfolge "bios" im Systemereignisprotokoll zu finden.

Der PercentComplete Parameterwert wird berechnet, indem die Anzahl der Ereignisse dividiert wird, die $i durch die Gesamtanzahl der $Events.Count abgerufenen Ereignisse dividiert und dann mit 100 multipliziert werden.

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 parameter ParentId verwenden, um die Ausgabe eingezogen zu haben, um beziehungen zwischen übergeordneten und untergeordneten Elementen im Fortschritt der einzelnen Schritte anzuzeigen.

Parameter

-Activity

Gibt die erste Textzeile in der Überschrift oberhalb der Statusleiste an. Dieser Text beschreibt die Aktivität, deren Fortschritt gemeldet wird.

Parametereigenschaften

Typ:String
Standardwert:None
Unterstützt Platzhalter:False
Nicht anzeigen:False

Parametersätze

(All)
Position:0
Obligatorisch.:False
Wert aus Pipeline:False
Wert aus Pipeline nach dem Eigenschaftsnamen:False
Wert aus verbleibenden Argumenten:False

-Completed

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

Parametereigenschaften

Typ:SwitchParameter
Standardwert:None
Unterstützt Platzhalter:False
Nicht anzeigen:False

Parametersätze

(All)
Position:Named
Obligatorisch.:False
Wert aus Pipeline:False
Wert aus Pipeline nach dem Eigenschaftsnamen:False
Wert aus verbleibenden Argumenten:False

-CurrentOperation

Gibt die Textzeile unterhalb der Statusleiste in der Classic Statusansicht an. In diesem Text wird der Vorgang beschrieben, der gerade ausgeführt wird. Dieser Parameter hat keine Auswirkung, wenn die Statusansicht auf Minimalfestgelegt ist.

Parametereigenschaften

Typ:String
Standardwert:None
Unterstützt Platzhalter:False
Nicht anzeigen:False

Parametersätze

(All)
Position:Named
Obligatorisch.:False
Wert aus Pipeline:False
Wert aus Pipeline nach dem Eigenschaftsnamen:False
Wert aus verbleibenden Argumenten:False

-Id

Gibt eine ID an, die die einzelnen Statusanzeigen von den anderen unterscheidet. Verwenden Sie diesen Parameter, wenn Sie mehr als eine Statusleiste in einem einzigen Befehl erstellen. Wenn die Statusanzeigen keine anderen IDs enthalten, werden sie überlagert, anstatt in einer Reihe angezeigt zu werden. Negative Werte sind nicht zulässig.

Parametereigenschaften

Typ:Int32
Standardwert:None
Unterstützt Platzhalter:False
Nicht anzeigen:False

Parametersätze

(All)
Position:2
Obligatorisch.:False
Wert aus Pipeline:False
Wert aus Pipeline nach dem Eigenschaftsnamen:False
Wert aus verbleibenden Argumenten: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.

Parametereigenschaften

Typ:Int32
Standardwert:None
Unterstützt Platzhalter:False
Nicht anzeigen:False

Parametersätze

(All)
Position:Named
Obligatorisch.:False
Wert aus Pipeline:False
Wert aus Pipeline nach dem Eigenschaftsnamen:False
Wert aus verbleibenden Argumenten:False

-PercentComplete

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

Parametereigenschaften

Typ:Int32
Standardwert:None
Unterstützt Platzhalter:False
Nicht anzeigen:False

Parametersätze

(All)
Position:Named
Obligatorisch.:False
Wert aus Pipeline:False
Wert aus Pipeline nach dem Eigenschaftsnamen:False
Wert aus verbleibenden Argumenten:False

-SecondsRemaining

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

Parametereigenschaften

Typ:Int32
Standardwert:None
Unterstützt Platzhalter:False
Nicht anzeigen:False

Parametersätze

(All)
Position:Named
Obligatorisch.:False
Wert aus Pipeline:False
Wert aus Pipeline nach dem Eigenschaftsnamen:False
Wert aus verbleibenden Argumenten:False

-SourceId

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

Parametereigenschaften

Typ:Int32
Standardwert:None
Unterstützt Platzhalter:False
Nicht anzeigen:False

Parametersätze

(All)
Position:Named
Obligatorisch.:False
Wert aus Pipeline:False
Wert aus Pipeline nach dem Eigenschaftsnamen:False
Wert aus verbleibenden Argumenten:False

-Status

Gibt die zweite Textzeile in der Überschrift oberhalb der Statusleiste an. Dieser Text beschreibt den aktuellen Status der Aktivität.

Parametereigenschaften

Typ:String
Standardwert:None
Unterstützt Platzhalter:False
Nicht anzeigen:False

Parametersätze

(All)
Position:1
Obligatorisch.:False
Wert aus Pipeline:False
Wert aus Pipeline nach dem Eigenschaftsnamen:False
Wert aus verbleibenden Argumenten:False

CommonParameters

Dieses Cmdlet unterstützt die allgemeinen Parameter -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction und -WarningVariable. Weitere Informationen findest du unter about_CommonParameters.

Eingaben

None

Sie können keine Objekte an dieses Cmdlet weiterleiten.

Ausgaben

None

Dieses Cmdlet gibt keine Ausgabe zurück.

Hinweise

Wenn die Statusleiste nicht angezeigt wird, überprüfen Sie den Wert der variablen $ProgressPreference. Wenn der Wert auf SilentlyContinuefestgelegt ist, wird die Statusanzeige 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 Class.