Compartilhar via

Write-Progress

Módulo:
Microsoft.PowerShell.Utility Module

Exibe uma barra de progresso em uma janela de comando do PowerShell.

Sintaxe

Default (Padrão) 

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

Description

O cmdlet Write-Progress exibe uma barra de progresso em uma janela de comando do PowerShell que ilustra o status de um comando ou script em execução. Você pode selecionar os indicadores que a barra reflete e o texto que aparece acima e abaixo da barra de progresso.

O PowerShell 7.2 adicionou a variável $PSStyle automática usada para controlar como o PowerShell exibe determinadas informações usando sequências de escape ANSI. O membro $PSStyle.Progress permite controlar a renderização da barra de exibição de progresso.

  • $PSStyle.Progress.Style – uma cadeia de caracteres ANSI definindo o estilo de renderização.
  • $PSStyle.Progress.MaxWidth - Define a largura máxima da exibição. Usa 120 como padrão. O valor mínimo é 18.
  • $PSStyle.Progress.View - Uma enumeração com valores, Minimal e Classic. Classic é a renderização existente sem alterações. Minimal é uma renderização mínima de linha única. Minimal é o padrão.

Para obter mais informações sobre $PSStyle, consulte about_ANSI_Terminals.md.

Observação

Se o host não der suporte ao Terminal Virtual, $PSStyle.Progress.View será automaticamente definido como Classic.

Exemplos

Exemplo 1: Exibir o progresso de um loop 'for'

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

Esse comando exibe o progresso de um loop de for que conta de 1 a 100.

O cmdlet Write-Progress inclui um título de barra de status Activity, uma linha de status e a variável $i (o contador no loop for), que indica a integridade relativa da tarefa.

Exemplo 2: Exibir o progresso de loops 'for' aninhados

$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

Este exemplo define o modo de exibição de progresso como Classic e exibe o progresso de dois loops de for aninhados, cada um representado por uma barra de progresso.

O comando Write-Progress da segunda barra de progresso inclui o parâmetro ID que o distingue da primeira barra de progresso.

Sem o parâmetro ID, as barras de progresso seriam sobrepostas umas às outras em vez de serem exibidas uma abaixo da outra.

Observação

Este exemplo define o modo de exibição de progresso como Classic, que exibe os valores CurrentOperation para cada barra de progresso. Quando o modo de exibição de progresso é definido como Minimal, os valores CurrentOperation não são exibidos.

Exemplo 3: Exibir o progresso durante a pesquisa de uma cadeia de caracteres

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

Este comando exibe o progresso de um comando para localizar a cadeia de caracteres "bios" no log de eventos do sistema.

O valor do parâmetro PercentComplete é calculado dividindo o número de eventos que foram processados $i pelo número total de eventos recuperados $Events.Count e multiplicando esse resultado por 100.

Exemplo 4: exibir o progresso de cada nível de um processo aninhado

$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

Neste exemplo, você pode usar o parâmetro ParentId para ter saída recuada para mostrar relações pai-filho no progresso de cada etapa.

Parâmetros

-Activity

Especifica a primeira linha de texto no título acima da barra de status. Este texto descreve a atividade cujo progresso está sendo relatado.

Propriedades do parâmetro

Tipo:String
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:0
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-Completed

Indica se a barra de progresso está visível. Se esse parâmetro for omitido, Write-Progress exibirá informações de progresso.

Propriedades do parâmetro

Tipo:SwitchParameter
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-CurrentOperation

Especifica a linha de texto abaixo da barra de progresso na exibição de progresso Classic. Este texto descreve a operação que está ocorrendo no momento. Esse parâmetro não tem efeito quando a exibição de progresso é definida como Minimal.

Propriedades do parâmetro

Tipo:String
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-Id

Especifica uma ID que distingue cada barra de progresso das outras. Use esse parâmetro ao criar mais de uma barra de progresso em um único comando. Se as barras de progresso não tiverem IDs diferentes, elas serão sobrepostas em vez de serem exibidas em uma série. Valores negativos não são permitidos.

Propriedades do parâmetro

Tipo:Int32
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:2
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-ParentId

Especifica a atividade pai da atividade atual. Use o valor -1 se a atividade atual não tiver nenhuma atividade pai.

Propriedades do parâmetro

Tipo:Int32
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-PercentComplete

Especifica o percentual da atividade concluída. Use o valor -1 se a porcentagem concluída for desconhecida ou não aplicável.

Propriedades do parâmetro

Tipo:Int32
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-SecondsRemaining

Especifica o número projetado de segundos restantes até que a atividade seja concluída. Use o valor -1 se o número de segundos restantes for desconhecido ou não for aplicável.

Propriedades do parâmetro

Tipo:Int32
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-SourceId

Especifica a origem do registro. Você pode usá-lo no lugar de de ID, mas não pode ser usado com outros parâmetros, como ParentId.

Propriedades do parâmetro

Tipo:Int32
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-Status

Especifica a segunda linha de texto no título acima da barra de status. Este texto descreve o estado atual da atividade.

Propriedades do parâmetro

Tipo:String
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:1
Obrigatório:False
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

CommonParameters

Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.

Entradas

None

Não é possível transferir objetos para esse cmdlet.

Saídas

None

Esse cmdlet não retorna nenhuma saída.

Observações

Se a barra de progresso não aparecer, verifique o valor da variável $ProgressPreference. Se o valor for definido como SilentlyContinue, a barra de progresso não será exibida. Para obter mais informações sobre as preferências do PowerShell, consulte about_Preference_Variables.

Os parâmetros do cmdlet correspondem às propriedades da classe System.Management.Automation.ProgressRecord. Para obter mais informações, consulte de classe ProgressRecord.