Compartir vía

Write-Progress

Módulo:
Microsoft.PowerShell.Utility Module

Muestra una barra de progreso dentro de una ventana de comandos de PowerShell.

Sintaxis

Default (Es el valor predeterminado). 

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

Description

El cmdlet Write-Progress muestra una barra de progreso en una ventana de comandos de PowerShell que muestra el estado de un comando o script en ejecución. Puede seleccionar los indicadores que refleja la barra y el texto que aparece encima y debajo de la barra de progreso.

PowerShell 7.2 agregó la $PSStyle variable automática que se usa para controlar cómo PowerShell muestra cierta información mediante secuencias de escape ANSI. El miembro $PSStyle.Progress permite controlar la representación de la barra de vista de progreso.

  • $PSStyle.Progress.Style: cadena ANSI que establece el estilo de representación.
  • $PSStyle.Progress.MaxWidth: establece el ancho máximo de la vista. Tiene como valor predeterminado 120. El valor mínimo es 18.
  • $PSStyle.Progress.View: enumeración con valores, Minimal y Classic. Classic es la representación existente sin cambios. Minimal es una representación mínima de línea única. Minimal es el valor predeterminado.

Para obtener más información sobre $PSStyle, vea about_ANSI_Terminals.md.

Nota:

Si el host no admite Terminal virtual, $PSStyle.Progress.View se establece automáticamente en Classic.

Ejemplos

Ejemplo 1: Mostrar el progreso de un bucle "for"

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

Este comando muestra el progreso de un bucle de for que cuenta de 1 a 100.

El cmdlet Write-Progress incluye un encabezado de barra de estado Activity, una línea de estado y la variable $i (el contador del bucle for), que indica la integridad relativa de la tarea.

Ejemplo 2: Mostrar el progreso de los bucles "for" anidados

$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

En este ejemplo se establece la vista de progreso en Classic y, a continuación, se muestra el progreso de dos bucles for anidados, cada uno representado por una barra de progreso.

El comando de la segunda barra de progreso incluye el parámetro id que lo distingue de la primera barra de progreso.

Sin el parámetro Id, las barras de progreso se superponen entre sí en lugar de mostrarse una debajo de la otra.

Nota:

En este ejemplo se establece la vista de progreso en Classic, que muestra los valores CurrentOperation Para cada barra de progreso. Cuando la vista de progreso se establece en Minimal, no se muestran los valores de CurrentOperation.

Ejemplo 3: Mostrar el progreso al buscar una cadena

# 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 muestra el progreso de un comando para buscar la cadena "bios" en el registro de eventos del sistema.

El valor del parámetro PercentComplete se calcula dividiendo el número de eventos procesados por el número total de eventos recuperados y multiplicando ese resultado en 100.

Ejemplo 4: Mostrar el progreso de cada nivel de un proceso anidado

$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

En este ejemplo, puede usar el parámetro ParentId para tener una salida con sangría para mostrar las relaciones de elementos primarios y secundarios en curso de cada paso.

Parámetros

-Activity

Especifica la primera línea de texto en el encabezado situado encima de la barra de estado. En este texto se describe la actividad cuyo progreso se notifica.

Propiedades del parámetro

Tipo:String
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:0
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-Completed

Indica si la barra de progreso está visible. Si se omite este parámetro, Write-Progress muestra información de progreso.

Propiedades del parámetro

Tipo:SwitchParameter
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-CurrentOperation

Especifica la línea de texto debajo de la barra de progreso de la vista de progreso Classic. En este texto se describe la operación que está teniendo lugar actualmente. Este parámetro no tiene ningún efecto cuando la vista de progreso está establecida en Minimal.

Propiedades del parámetro

Tipo:String
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-Id

Especifica un identificador que distingue cada barra de progreso de las demás. Use este parámetro cuando cree más de una barra de progreso en un solo comando. Si las barras de progreso no tienen identificadores diferentes, se superponen en lugar de mostrarse en una serie. No se permiten valores negativos.

Propiedades del parámetro

Tipo:Int32
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:2
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-ParentId

Especifica la actividad primaria de la actividad actual. Use el valor -1 si la actividad actual no tiene ninguna actividad primaria.

Propiedades del parámetro

Tipo:Int32
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-PercentComplete

Especifica el porcentaje de la actividad que se ha completado. Use el valor -1 si el porcentaje completado es desconocido o no aplicable.

Propiedades del parámetro

Tipo:Int32
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-SecondsRemaining

Especifica el número previsto de segundos restantes hasta que se complete la actividad. Use el valor -1 si el número de segundos restantes es desconocido o no aplicable.

Propiedades del parámetro

Tipo:Int32
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-SourceId

Especifica el origen del registro. Puede usarlo en lugar de id., pero no se puede usar con otros parámetros como ParentId.

Propiedades del parámetro

Tipo:Int32
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:Named
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

-Status

Especifica la segunda línea de texto en el encabezado situado encima de la barra de estado. En este texto se describe el estado actual de la actividad.

Propiedades del parámetro

Tipo:String
Valor predeterminado:None
Admite caracteres comodín:False
DontShow:False

Conjuntos de parámetros

(All)
Posición:1
Mandatory:False
Valor de la canalización:False
Valor de la canalización por nombre de propiedad:False
Valor de los argumentos restantes:False

CommonParameters

Este cmdlet admite los parámetros comunes: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction y -WarningVariable. Para obtener más información, vea about_CommonParameters.

Entradas

None

No se pueden canalizar objetos a este cmdlet.

Salidas

None

Este cmdlet no devuelve ninguna salida.

Notas

Si la barra de progreso no aparece, compruebe el valor de la variable $ProgressPreference. Si el valor se establece en SilentlyContinue, no se muestra la barra de progreso. Para obtener más información sobre las preferencias de PowerShell, consulte about_Preference_Variables.

Los parámetros del cmdlet corresponden a las propiedades de la clase System.Management.Automation.ProgressRecord. Para obtener más información, vea Clase ProgressRecord.