Udostępnij za pomocą

Write-Progress

Moduł:
Microsoft.PowerShell.Utility Module

Wyświetla pasek postępu w oknie polecenia programu PowerShell.

Składnia

Default (Domyślna) 

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

Opis

Polecenie cmdlet Write-Progress wyświetla pasek postępu w oknie poleceń programu PowerShell, który przedstawia stan uruchomionego polecenia lub skryptu. Możesz wybrać wskaźniki, odzwierciedlone na pasku oraz tekst wyświetlany powyżej i poniżej paska postępu.

Program PowerShell 7.2 dodał $PSStyle automatyczną zmienną używaną do kontrolowania sposobu wyświetlania określonych informacji przez program PowerShell przy użyciu sekwencji ucieczki ANSI. Element członkowski $PSStyle.Progress umożliwia kontrolowanie renderowania paska widoku postępu.

  • $PSStyle.Progress.Style — ciąg ANSI ustawia styl renderowania.
  • $PSStyle.Progress.MaxWidth — ustawia maksymalną szerokość widoku. Wartość domyślna to 120. Wartość minimalna to 18.
  • $PSStyle.Progress.View — wyliczenie z wartościami, Minimal i Classic. Classic jest istniejącym renderowaniem bez zmian. Minimal to renderowanie minimalne w jednym wierszu. Minimal jest wartością domyślną.

Aby uzyskać więcej informacji na temat $PSStyle, zobacz about_ANSI_Terminals.md.

Uwaga / Notatka

Jeśli host nie obsługuje terminalu wirtualnego, $PSStyle.Progress.View zostanie automatycznie ustawiona na Classic.

Przykłady

Przykład 1. Wyświetlanie postępu pętli "for"

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

To polecenie wyświetla postęp pętli for, która liczy się od 1 do 100.

Polecenie cmdlet Write-Progress zawiera nagłówek paska stanu Activity, wiersz stanu i zmienną $i (licznik w pętli for), który wskazuje względną kompletność zadania.

Przykład 2. Wyświetlanie postępu zagnieżdżonych pętli "for"

$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

W tym przykładzie ustawia widok postępu na Classic, a następnie wyświetla postęp dwóch zagnieżdżonych pętli for, z których każdy jest reprezentowany przez pasek postępu.

Polecenie Write-Progress drugiego paska postępu zawiera parametr Id, który odróżnia go od pierwszego paska postępu.

Bez parametru Id paski postępu będą nakładane na siebie zamiast wyświetlać jeden poniżej drugiego.

Uwaga / Notatka

W tym przykładzie ustawiono widok postępu na Classic, który wyświetla wartości CurrentOperation Dla każdego paska postępu. Gdy widok postępu jest ustawiony na Minimal, wartości CurrentOperation nie są wyświetlane.

Przykład 3. Wyświetlanie postępu podczas wyszukiwania ciągu

# 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
}

To polecenie wyświetla postęp polecenia w celu znalezienia ciągu "bios" w dzienniku zdarzeń systemu.

Wartość parametru PercentComplete jest obliczana przez podzielenie liczby zdarzeń przetworzonych $i przez łączną liczbę zdarzeń pobranych $Events.Count, a następnie pomnożenie tego wyniku przez 100.

Przykład 4. Wyświetlanie postępu dla każdego poziomu zagnieżdżonego procesu

$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

W tym przykładzie można użyć parametru ParentId, aby wyświetlić wcięcie danych wyjściowych w celu wyświetlenia relacji nadrzędny-podrzędny w toku każdego kroku.

Parametry

-Activity

Określa pierwszy wiersz tekstu w nagłówku powyżej paska stanu. W tym tekście opisano działanie, którego postęp jest zgłaszany.

Właściwości parametru

Typ:String
Domyślna wartość:None
Obsługuje symbole wieloznaczne:False
DontShow:False

Zestawy parametrów

(All)
Position:0
Obowiązkowy:False
Wartość z potoku:False
Wartość z potoku według nazwy właściwości:False
Wartość z pozostałych argumentów:False

-Completed

Wskazuje, czy pasek postępu jest widoczny. Jeśli ten parametr zostanie pominięty, Write-Progress wyświetla informacje o postępie.

Właściwości parametru

Typ:SwitchParameter
Domyślna wartość:None
Obsługuje symbole wieloznaczne:False
DontShow:False

Zestawy parametrów

(All)
Position:Named
Obowiązkowy:False
Wartość z potoku:False
Wartość z potoku według nazwy właściwości:False
Wartość z pozostałych argumentów:False

-CurrentOperation

Określa wiersz tekstu poniżej paska postępu w widoku postępu Classic. W tym tekście opisano operację, która jest obecnie wykonywana. Ten parametr nie ma wpływu, gdy widok postępu jest ustawiony na Minimal.

Właściwości parametru

Typ:String
Domyślna wartość:None
Obsługuje symbole wieloznaczne:False
DontShow:False

Zestawy parametrów

(All)
Position:Named
Obowiązkowy:False
Wartość z potoku:False
Wartość z potoku według nazwy właściwości:False
Wartość z pozostałych argumentów:False

-Id

Określa identyfikator, który odróżnia każdy pasek postępu od innych. Użyj tego parametru podczas tworzenia więcej niż jednego paska postępu w jednym poleceniu. Jeśli paski postępu nie mają różnych identyfikatorów, są one nakładane zamiast być wyświetlane w serii. Wartości ujemne nie są dozwolone.

Właściwości parametru

Typ:Int32
Domyślna wartość:None
Obsługuje symbole wieloznaczne:False
DontShow:False

Zestawy parametrów

(All)
Position:2
Obowiązkowy:False
Wartość z potoku:False
Wartość z potoku według nazwy właściwości:False
Wartość z pozostałych argumentów:False

-ParentId

Określa działanie nadrzędne bieżącego działania. Użyj wartości -1, jeśli bieżące działanie nie ma działania nadrzędnego.

Właściwości parametru

Typ:Int32
Domyślna wartość:None
Obsługuje symbole wieloznaczne:False
DontShow:False

Zestawy parametrów

(All)
Position:Named
Obowiązkowy:False
Wartość z potoku:False
Wartość z potoku według nazwy właściwości:False
Wartość z pozostałych argumentów:False

-PercentComplete

Określa wartość procentową ukończonego działania. Użyj wartości -1, jeśli procent ukończenia jest nieznany lub nie dotyczy.

Właściwości parametru

Typ:Int32
Domyślna wartość:None
Obsługuje symbole wieloznaczne:False
DontShow:False

Zestawy parametrów

(All)
Position:Named
Obowiązkowy:False
Wartość z potoku:False
Wartość z potoku według nazwy właściwości:False
Wartość z pozostałych argumentów:False

-SecondsRemaining

Określa przewidywaną liczbę sekund pozostałych do momentu zakończenia działania. Użyj wartości -1, jeśli liczba sekund pozostałych jest nieznana lub nie dotyczy.

Właściwości parametru

Typ:Int32
Domyślna wartość:None
Obsługuje symbole wieloznaczne:False
DontShow:False

Zestawy parametrów

(All)
Position:Named
Obowiązkowy:False
Wartość z potoku:False
Wartość z potoku według nazwy właściwości:False
Wartość z pozostałych argumentów:False

-SourceId

Określa źródło rekordu. Można go użyć zamiast identyfikatora, ale nie można go używać z innymi parametrami, takimi jak ParentId.

Właściwości parametru

Typ:Int32
Domyślna wartość:None
Obsługuje symbole wieloznaczne:False
DontShow:False

Zestawy parametrów

(All)
Position:Named
Obowiązkowy:False
Wartość z potoku:False
Wartość z potoku według nazwy właściwości:False
Wartość z pozostałych argumentów:False

-Status

Określa drugi wiersz tekstu w nagłówku powyżej paska stanu. W tym tekście opisano bieżący stan działania.

Właściwości parametru

Typ:String
Domyślna wartość:None
Obsługuje symbole wieloznaczne:False
DontShow:False

Zestawy parametrów

(All)
Position:1
Obowiązkowy:False
Wartość z potoku:False
Wartość z potoku według nazwy właściwości:False
Wartość z pozostałych argumentów:False

CommonParameters

To polecenie cmdlet obsługuje typowe parametry: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction i -WarningVariable. Aby uzyskać więcej informacji, zobacz about_CommonParameters.

Dane wejściowe

None

Nie można przekazywać obiektów do tego cmdletu.

Dane wyjściowe

None

To polecenie cmdlet nie zwraca żadnych danych wyjściowych.

Uwagi

Jeśli pasek postępu nie jest wyświetlany, sprawdź wartość zmiennej $ProgressPreference. Jeśli wartość jest ustawiona na SilentlyContinue, pasek postępu nie jest wyświetlany. Aby uzyskać więcej informacji na temat preferencji programu PowerShell, zobacz about_Preference_Variables.

Parametry polecenia cmdlet odpowiadają właściwościom klasy System.Management.Automation.ProgressRecord. Aby uzyskać więcej informacji, zobacz ProgressRecord Class.