Condividi tramite

Write-Progress

Modulo:
Microsoft.PowerShell.Utility Module

Visualizza una barra di stato all'interno di una finestra di comando di PowerShell.

Sintassi

Default (impostazione predefinita). 

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

Descrizione

Il cmdlet Write-Progress visualizza una barra di stato in una finestra di comando di PowerShell che illustra lo stato di un comando o di uno script in esecuzione. È possibile selezionare gli indicatori che la barra riflette e il testo visualizzato sopra e sotto l'indicatore di stato.

PowerShell 7.2 ha aggiunto la $PSStyle variabile automatica usata per controllare come PowerShell visualizza determinate informazioni usando sequenze di escape ANSI. Il membro $PSStyle.Progress consente di controllare il rendering della barra di avanzamento della visualizzazione.

  • $PSStyle.Progress.Style: stringa ANSI che imposta lo stile di rendering.
  • $PSStyle.Progress.MaxWidth: imposta la larghezza massima della visualizzazione. Il valore predefinito è 120. Il valore minimo è 18.
  • $PSStyle.Progress.View: enumerazione con valori, Minimal e Classic. Classic è il rendering esistente senza modifiche. Minimal è un rendering minimo a riga singola. Minimal è l'impostazione predefinita.

Per altre informazioni su $PSStyle, vedere about_ANSI_Terminals.md.

Annotazioni

Se l'host non supporta il terminale virtuale, $PSStyle.Progress.View viene impostato automaticamente su Classic.

Esempio

Esempio 1: Visualizzare lo stato di avanzamento di un ciclo 'for'

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

Questo comando visualizza lo stato di avanzamento di un ciclo for che conta da 1 a 100.

Il cmdlet Write-Progress include un'intestazione della barra di stato Activity, una riga di stato e la variabile $i (il contatore nel ciclo for), che indica la relativa completezza dell'attività.

Esempio 2: Visualizzare lo stato di avanzamento dei cicli 'for' annidati

$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

In questo esempio viene impostata la visualizzazione dello stato di avanzamento su Classic e quindi viene visualizzato lo stato di avanzamento di due cicli di for annidati, ognuno rappresentato da un indicatore di stato.

Il comando Write-Progress per la seconda barra di stato include il parametro ID che lo distingue dalla prima barra di stato.

Senza il parametro id , le barre di stato verranno sovrapposte l'una all'altra anziché essere visualizzate una sotto l'altra.

Annotazioni

In questo esempio viene impostata la visualizzazione dello stato di avanzamento su Classic, che visualizza i valori CurrentOperation Per ogni indicatore di stato. Quando la visualizzazione stato è impostata su Minimal, i valori CurrentOperation non vengono visualizzati.

Esempio 3: Visualizzare lo stato di avanzamento durante la ricerca di una stringa

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

Questo comando visualizza lo stato di avanzamento di un comando per trovare la stringa "bios" nel registro eventi di sistema.

Il valore del parametro PercentComplete viene calcolato dividendo il numero di eventi elaborati $i dal numero totale di eventi recuperati $Events.Count e moltiplicando il risultato per 100.

Esempio 4: Visualizzare lo stato di avanzamento per ogni livello di un processo annidato

$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

In questo esempio è possibile usare il parametro parentId per visualizzare relazioni padre-figlio in corso di ogni passaggio.

Parametri

-Activity

Specifica la prima riga di testo nell'intestazione sopra la barra di stato. Questo testo descrive l'attività di cui viene segnalato lo stato di avanzamento.

Proprietà dei parametri

Tipo:String
Valore predefinito:None
Supporta i caratteri jolly:False
DontShow:False

Set di parametri

(All)
Posizione:0
Obbligatorio:False
Valore dalla pipeline:False
Valore dalla pipeline in base al nome della proprietà:False
Valore dagli argomenti rimanenti:False

-Completed

Indica se la barra di stato è visibile. Se questo parametro viene omesso, Write-Progress visualizza informazioni sullo stato di avanzamento.

Proprietà dei parametri

Tipo:SwitchParameter
Valore predefinito:None
Supporta i caratteri jolly:False
DontShow:False

Set di parametri

(All)
Posizione:Named
Obbligatorio:False
Valore dalla pipeline:False
Valore dalla pipeline in base al nome della proprietà:False
Valore dagli argomenti rimanenti:False

-CurrentOperation

Specifica la riga di testo sotto l'indicatore di stato nella Classic visualizzazione stato. Questo testo descrive l'operazione attualmente in corso. Questo parametro non ha alcun effetto quando la visualizzazione stato è impostata su Minimal.

Proprietà dei parametri

Tipo:String
Valore predefinito:None
Supporta i caratteri jolly:False
DontShow:False

Set di parametri

(All)
Posizione:Named
Obbligatorio:False
Valore dalla pipeline:False
Valore dalla pipeline in base al nome della proprietà:False
Valore dagli argomenti rimanenti:False

-Id

Specifica un ID che distingue ogni indicatore di stato dagli altri. Usare questo parametro quando si creano più barre di stato in un singolo comando. Se le barre di stato non hanno ID diversi, vengono sovrapposti anziché essere visualizzati in una serie. I valori negativi non sono consentiti.

Proprietà dei parametri

Tipo:Int32
Valore predefinito:None
Supporta i caratteri jolly:False
DontShow:False

Set di parametri

(All)
Posizione:2
Obbligatorio:False
Valore dalla pipeline:False
Valore dalla pipeline in base al nome della proprietà:False
Valore dagli argomenti rimanenti:False

-ParentId

Specifica l'attività padre dell'attività corrente. Usare il valore -1 se l'attività corrente non ha attività padre.

Proprietà dei parametri

Tipo:Int32
Valore predefinito:None
Supporta i caratteri jolly:False
DontShow:False

Set di parametri

(All)
Posizione:Named
Obbligatorio:False
Valore dalla pipeline:False
Valore dalla pipeline in base al nome della proprietà:False
Valore dagli argomenti rimanenti:False

-PercentComplete

Specifica la percentuale dell'attività completata. Usare il valore -1 se la percentuale di completamento è sconosciuta o non applicabile.

Proprietà dei parametri

Tipo:Int32
Valore predefinito:None
Supporta i caratteri jolly:False
DontShow:False

Set di parametri

(All)
Posizione:Named
Obbligatorio:False
Valore dalla pipeline:False
Valore dalla pipeline in base al nome della proprietà:False
Valore dagli argomenti rimanenti:False

-SecondsRemaining

Specifica il numero previsto di secondi rimanenti fino al completamento dell'attività. Usare il valore -1 se il numero di secondi rimanenti è sconosciuto o non applicabile.

Proprietà dei parametri

Tipo:Int32
Valore predefinito:None
Supporta i caratteri jolly:False
DontShow:False

Set di parametri

(All)
Posizione:Named
Obbligatorio:False
Valore dalla pipeline:False
Valore dalla pipeline in base al nome della proprietà:False
Valore dagli argomenti rimanenti:False

-SourceId

Specifica l'origine del record. È possibile usarlo al posto di ID, ma non può essere usato con altri parametri come ParentId.

Proprietà dei parametri

Tipo:Int32
Valore predefinito:None
Supporta i caratteri jolly:False
DontShow:False

Set di parametri

(All)
Posizione:Named
Obbligatorio:False
Valore dalla pipeline:False
Valore dalla pipeline in base al nome della proprietà:False
Valore dagli argomenti rimanenti:False

-Status

Specifica la seconda riga di testo nell'intestazione sopra la barra di stato. Questo testo descrive lo stato corrente dell'attività.

Proprietà dei parametri

Tipo:String
Valore predefinito:None
Supporta i caratteri jolly:False
DontShow:False

Set di parametri

(All)
Posizione:1
Obbligatorio:False
Valore dalla pipeline:False
Valore dalla pipeline in base al nome della proprietà:False
Valore dagli argomenti rimanenti:False

CommonParameters

Questo cmdlet supporta i parametri comuni: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Per altre informazioni, vedi about_CommonParameters.

Input

None

Gli oggetti non possono essere inviati tramite pipe a questo cmdlet.

Output

None

Questo cmdlet non restituisce alcun output.

Note

Se l'indicatore di stato non viene visualizzato, controllare il valore della variabile $ProgressPreference. Se il valore è impostato su SilentlyContinue, l'indicatore di stato non viene visualizzato. Per altre informazioni sulle preferenze di PowerShell, vedere about_Preference_Variables.

I parametri del cmdlet corrispondono alle proprietà della classe System.Management.Automation.ProgressRecord. Per altre informazioni, vedere Classe ProgressRecord.