Write-Progress (Microsoft.PowerShell.Utility)

Write-Progress

在 PowerShell 命令窗口中显示进度条。

句法

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

描述

Write-Progress cmdlet 在 PowerShell 命令窗口中显示一个进度条，描述正在运行的命令或脚本的状态。您可以选择进度条反映的指示器以及进度条上方和下方显示的文本。

PowerShell 7.2 添加了 $PSStyle 自动变量，用于控制 PowerShell 如何使用 ANSI 转义序列显示某些信息。 $PSStyle.Progress 成员允许您控制进度视图栏渲染。

• $PSStyle.Progress.Style - 设置渲染样式的 ANSI 字符串。
• $PSStyle.Progress.MaxWidth - 设置视图的最大宽度。默认为120。最小值为 18。
• $PSStyle.Progress.View - 具有值 Minimal 和 Classic 的枚举。 Classic 是没有任何更改的现有渲染。 Minimal 是单行最小渲染。 最小 是默认值。

有关 $PSStyle 的更多信息，请参阅 about_ANSI_Terminals.md。

笔记

如果主机不支持虚拟终端，$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 cmdlet 包括状态栏标题 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           = 'Progress'
            PercentComplete  = $j
            CurrentOperation = 'InnerLoop'
        }
        Write-Progress @InnerLoopProgressParameters
        Start-Sleep -Milliseconds 25
    }
}

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

此示例将进度视图设置为 Classic，然后显示两个嵌套 for 循环的进度，每个循环均由进度条表示。

第二个进度条的 Write-Progress 命令包含将其与第一个进度条区分开来的 Id 参数。

如果没有 Id 参数，进度条将相互叠加，而不是一个一个地显示在另一个之下。

示例 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 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
}

此命令显示在系统事件日志中查找字符串“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

0

None

False

False

False

-Completed

指示进度条是否可见。如果省略此参数，Write-Progress 将显示进度信息。

SwitchParameter

命名

None

False

False

False

-CurrentOperation

指定进度条下方的文本行。此文本描述当前正在发生的操作。

String

命名

None

False

False

False

-Id

指定一个 ID，用于区分每个进度条与其他进度条。当您在单个命令中创建多个进度条时，请使用此参数。如果进度条没有不同的 ID，它们会叠加而不是按系列显示。不允许使用负值。

整数32

2

None

False

False

False

-ParentId

指定当前活动的父活动。如果当前活动没有父活动，则使用值 -1。

整数32

命名

None

False

False

False

-PercentComplete

指定已完成活动的百分比。如果完成百分比未知或不适用，请使用值 -1。

整数32

命名

None

False

False

False

-SecondsRemaining

指定活动完成之前预计剩余的秒数。如果剩余秒数未知或不适用，请使用值-1。

整数32

命名

None

False

False

False

-SourceId

指定记录的来源。您可以使用它来代替 Id，但不能与 ParentId 等其他参数一起使用。

整数32

命名

None

False

False

False

-Status

指定状态栏上方标题中的第二行文本。此文本描述了活动的当前状态。

String

1

None

False

False

False

输入

无

您无法将对象通过管道传输到此 cmdlet。

输出

无

此 cmdlet 不返回任何输出。

笔记

如果未出现进度条，请检查 $ProgressPreference 变量的值。如果该值设置为 SilentlyContinue，则不会显示进度条。有关 PowerShell 首选项的详细信息，请参阅 about_Preference_Variables。

cmdlet 的参数对应于System.Management.Automation.ProgressRecord 类的属性。有关详细信息，请参阅 ProgressRecord 类。