Condividi tramite

Write-Error

  • Riferimento
Modulo:
Microsoft.PowerShell.Utility

Scrive un oggetto nel flusso di errore.

Sintassi

Write-Error
     [-Message] <string>
     [-Category <ErrorCategory>]
     [-ErrorId <string>]
     [-TargetObject <Object>]
     [-RecommendedAction <string>]
     [-CategoryActivity <string>]
     [-CategoryReason <string>]
     [-CategoryTargetName <string>]
     [-CategoryTargetType <string>]
     [<CommonParameters>]
Write-Error
     [-Exception] <Exception>
     [-Message <string>]
     [-Category <ErrorCategory>]
     [-ErrorId <string>]
     [-TargetObject <Object>]
     [-RecommendedAction <string>]
     [-CategoryActivity <string>]
     [-CategoryReason <string>]
     [-CategoryTargetName <string>]
     [-CategoryTargetType <string>]
     [<CommonParameters>]
Write-Error
     [-ErrorRecord] <ErrorRecord>
     [-RecommendedAction <string>]
     [-CategoryActivity <string>]
     [-CategoryReason <string>]
     [-CategoryTargetName <string>]
     [-CategoryTargetType <string>]
     [<CommonParameters>]

Descrizione

Il cmdlet Write-Error dichiara un errore non irreversibile. Per impostazione predefinita, gli errori vengono inviati nel flusso di errore al programma host da visualizzare, insieme all'output.

Per scrivere un errore non irreversibile, immettere una stringa di messaggio di errore, un oggetto ErrorRecord o un oggetto Exception. Usare gli altri parametri di Write-Error per popolare il record di errore.

Gli errori non irreversibili scrivono un errore nel flusso di errore, ma non arrestano l'elaborazione dei comandi. Se un errore non irreversibile viene dichiarato in un elemento in una raccolta di elementi di input, il comando continua a elaborare gli altri elementi nella raccolta.

Per dichiarare un errore irreversibile, usare la parola chiave Throw. Per altre informazioni, vedere about_Throw.

Esempio

Esempio 1: Scrivere un errore per l'oggetto RegistryKey

Get-ChildItem | ForEach-Object {
    if ($_.GetType().ToString() -eq "Microsoft.Win32.RegistryKey")
    {
        Write-Error "Invalid object" -ErrorId B1 -TargetObject $_
    }
    else
    {
        $_
    }
}

Questo comando dichiara un errore non irreversibile quando il cmdlet Get-ChildItem restituisce un oggetto Microsoft.Win32.RegistryKey, ad esempio gli oggetti nella HKLM: o HKCU: unità del provider del Registro di sistema di PowerShell.

Esempio 2: Scrivere un messaggio di errore nella console

Write-Error "Access denied."

Questo comando dichiara un errore non irreversibile e scrive un errore "Accesso negato". Il comando usa il parametro message per specificare il messaggio, ma omette il nome del parametro message facoltativo.

Esempio 3: Scrivere un errore nella console e specificare la categoria

Write-Error -Message "Error: Too many input values." -Category InvalidArgument

Questo comando dichiara un errore non irreversibile e specifica una categoria di errore.

Esempio 4: Scrivere un errore usando un oggetto Exception

$E = [System.Exception]@{Source="Get-ParameterNames.ps1";HelpLink="https://go.microsoft.com/fwlink/?LinkID=113425"}
Write-Error -Exception $E -Message "Files not found. The $Files location doesn't contain any XML files."

Questo comando usa un 'oggetto Exception per dichiarare un errore non irreversibile.

Il primo comando usa una tabella hash per creare l'oggetto System.Exception. Salva l'oggetto eccezione nella variabile $E. È possibile usare una tabella hash per creare qualsiasi oggetto di un tipo con un costruttore Null.

Il secondo comando usa il cmdlet Write-Error per dichiarare un errore non irreversibile. Il valore del parametro Exception è l'oggetto Exception nella variabile $E.

Parametri

-Category

Specifica la categoria dell'errore. Il valore predefinito è NotSpecified. I valori accettabili per questo parametro sono:

  • NotSpecified
  • OpenError
  • CloseError
  • DeviceError
  • DeadlockDetected
  • InvalidArgument
  • InvalidData
  • InvalidOperation
  • InvalidResult
  • InvalidType
  • MetadataError
  • NotImplemented
  • NotInstalled
  • ObjectNotFound
  • OperationStopped
  • OperationTimeout
  • SyntaxError
  • ParserError
  • PermissionDenied
  • ResourceBusy
  • ResourceExists
  • ResourceUnavailable
  • ReadError
  • WriteError
  • FromStdErr
  • SecurityError
  • ProtocolError
  • ConnectionError
  • AuthenticationError
  • Limiti superati
  • Quota superata
  • NotEnabled

Per informazioni sulle categorie di errore, vedere 'enumerazione ErrorCategory.

Tipo:ErrorCategory
Valori accettati:NotSpecified, OpenError, CloseError, DeviceError, DeadlockDetected, InvalidArgument, InvalidData, InvalidOperation, InvalidResult, InvalidType, MetadataError, NotImplemented, NotInstalled, ObjectNotFound, OperationStopped, OperationTimeout, SyntaxError, ParserError, PermissionDenied, ResourceBusy, ResourceExists, ResourceUnavailable, ReadError, WriteError, FromStdErr, SecurityError, ProtocolError, ConnectionError, AuthenticationError, LimitsExceeded, QuotaExceeded, NotEnabled
Posizione:Named
Valore predefinito:NotSpecified
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

-CategoryActivity

Specifica l'azione che ha causato l'errore.

Tipo:String
Alias:Activity
Posizione:Named
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

-CategoryReason

Specifica come o perché l'attività ha causato l'errore.

Tipo:String
Alias:Reason
Posizione:Named
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

-CategoryTargetName

Specifica il nome dell'oggetto da elaborare quando si è verificato l'errore.

Tipo:String
Alias:TargetName
Posizione:Named
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

-CategoryTargetType

Specifica il tipo dell'oggetto da elaborare quando si è verificato l'errore.

Tipo:String
Alias:TargetType
Posizione:Named
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

-ErrorId

Specifica una stringa ID per identificare l'errore. La stringa deve essere univoca per l'errore.

Tipo:String
Posizione:Named
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

-ErrorRecord

Specifica un oggetto record di errore che rappresenta l'errore. Utilizzare le proprietà dell'oggetto per descrivere l'errore.

Per creare un oggetto record di errore, usare il cmdlet New-Object o ottenere un oggetto record di errore dalla matrice nella variabile automatica $Error.

Tipo:ErrorRecord
Posizione:0
Valore predefinito:None
Necessario:True
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

-Exception

Specifica un oggetto eccezione che rappresenta l'errore. Utilizzare le proprietà dell'oggetto per descrivere l'errore.

Per creare un oggetto eccezione, usare una tabella hash o usare il cmdlet New-Object.

Tipo:Exception
Posizione:0
Valore predefinito:None
Necessario:True
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

-Message

Specifica il testo del messaggio dell'errore. Se il testo include spazi o caratteri speciali, racchiuderlo tra virgolette. È anche possibile inviare tramite pipe una stringa di messaggio a Write-Error.

Tipo:String
Alias:Msg
Posizione:0
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:True
Accettare caratteri jolly:False

-RecommendedAction

Specifica l'azione che l'utente deve eseguire per risolvere o impedire l'errore.

Tipo:String
Posizione:Named
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

-TargetObject

Specifica l'oggetto in fase di elaborazione quando si è verificato l'errore. Immettere l'oggetto, una variabile che contiene l'oggetto o un comando che ottiene l'oggetto .

Tipo:Object
Posizione:Named
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

Input

String

È possibile inviare tramite pipe una stringa contenente un messaggio di errore a questo cmdlet.

Output

None

Questo cmdlet non restituisce alcun output. Scrive solo nel flusso dei messaggi di errore.

Note

Write-Error non modifica il valore della variabile automatica $?, pertanto non segnala una condizione di errore irreversibile. Per segnalare un errore irreversibile, usare il metodo $PSCmdlet.WriteError().