Write-Progress

模組:

Microsoft.PowerShell.Utility Module

在 PowerShell 指令視窗中顯示進度條。

語法

Default (預設值)

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

Description

該 Write-Progress 指令檔會在 PowerShell 指令視窗中顯示進度條，顯示執行中的指令或腳本的狀態。 你可以選擇進度條所反映的指標，以及進度條上下顯示的文字。

PowerShell 7.2 新增了 $PSStyle 自動變數，用來控制 PowerShell 如何透過 ANSI 跳脫序列顯示特定資訊。 這個 $PSStyle.Progress 成員讓你可以控制進度列的渲染。

• $PSStyle.Progress.Style - ANSI 字串設定渲染風格。
• $PSStyle.Progress.MaxWidth - 設定視圖的最大寬度。 預設為 120。 最小值為 18。
• $PSStyle.Progress.View - 一個具有值且 MinimalClassic的枚舉。 Classic 是現有的轉譯，沒有任何變更。 Minimal 是單行最小渲染。 Minimal 是預設值。

欲了解更多資訊 $PSStyle，請參閱 about_ANSI_Terminals.md。

Note

如果主機不支援虛擬終端機，$PSStyle.Progress.View 會自動設定為 Classic。

範例

範例 1：顯示「for」迴圈的進度

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

此指令顯示 for 從1到100的循環進度。

該 Write-Progress 指令小程式包含狀態列標題 Activity、狀態行，以及變數 $i （迴圈中的 for 計數器），用以指示任務的相對完整性。

範例 2：顯示巢狀「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

此範例將進度視圖設為 Classic ，並顯示兩個巢狀 for 循環的進度，每個循環以進度條表示。

第二個進度條的 Write-Progress 指令包含 Id 參數，用以區分它與第一個進度條。

若沒有 Id 參數，進度條會互相疊加，而非一一顯示。

Note

此範例將進度視圖設為 Classic，顯示每個進度條的 CurrentOperation 值。 當進度檢視設為 Minimal時， CurrentOperation 的值不會顯示。

範例 3：在搜尋字串時顯示進度

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

此指令會顯示在系統事件日誌中尋找字串「bios」的指令進度。

PercentComplete 參數值的計算方式是將已處理$i的事件數除以檢$Events.Count索的事件總數，再乘以 100。

範例 4：顯示巢狀程序每個層級的進度

$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

在這個範例中，你可以使用 ParentId 參數讓輸出縮排，顯示每個步驟進度中的父子關係。

參數

-Activity

指定狀態列上方標題的第一行文字。 本文描述了所報告進展的活動。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	0
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Completed

顯示進度條是否可見。 若忽略此參數，則 Write-Progress 顯示進度資訊。

參數屬性

類型:	SwitchParameter
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-CurrentOperation

指定進度列 Classic 下方的文字行。 本文描述目前正在進行的行動。 當進度視圖設為 Minimal時，此參數無效。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Id

指定一個識別碼，區分每個進度條與其他進度條。 當你在同一個指令中建立多個進度條時，請使用這個參數。 如果進度條沒有不同的 ID，它們會疊加而非連續顯示。 不允許使用負數值。

參數屬性

類型:	Int32
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	2
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-ParentId

指定當前活動的父活動。 如果目前的活動沒有父活動，就使用該值 -1 。

參數屬性

類型:	Int32
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-PercentComplete

指定完成的活動百分比。 如果完成百分比未知或不適用，請使用該數值 -1 。

參數屬性

類型:	Int32
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-SecondsRemaining

指定活動完成前剩餘的預計秒數。 如果剩餘秒數未知或不適用，請使用該數值 -1 。

參數屬性

類型:	Int32
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-SourceId

指定紀錄來源。 你可以用它來取代 Id ，但不能搭配像 ParentID 這類其他參數一起使用。

參數屬性

類型:	Int32
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Status

指定狀態列上方標題的第二行文字。 本文描述了目前的活動狀態。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	1
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

CommonParameters

此 cmdlet 支援常見參數：-Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。 如需詳細資訊，請參閱 about_CommonParameters。

輸入

None

您不能將物件透過管道傳送到此 Cmdlet。

輸出

None

此 Cmdlet 不會傳回任何輸出。

備註

如果進度條沒出現，就檢查變 $ProgressPreference 數值。 如果 值設為 SilentlyContinue，進度條不會顯示。 欲了解更多 PowerShell 偏好設定，請參見 about_Preference_Variables。

指令小程式的參數對應於 System.Management.Automation.ProgressRecord 類別的屬性。 欲了解更多資訊，請參閱 ProgressRecord 課程。

相關連結

• 寫入-除錯
• 寫入錯誤
• Write-Host
• 輸出寫入
• 寫入進度
• Write-Verbose
• Write-Warning