Write-Error

Grava um objeto para o fluxo de erros.

Sintaxe

Write-Error -ErrorRecord <ErrorRecord> [-CategoryActivity <string>] [-CategoryReason <string>] [-CategoryTargetName <string>] [-CategoryTargetType <string>] [-RecommendedAction <string>] [<CommonParameters>]

Write-Error [-Message] <string> [-Category {<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>}] [-ErrorId <string>] [-TargetObject <Object>] [-CategoryActivity <string>] [-CategoryReason <string>] [-CategoryTargetName <string>] [-CategoryTargetType <string>] [-RecommendedAction <string>] [<CommonParameters>]

Write-Error -Exception <Exception> [-Category {<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>}] [-ErrorId <string>] [-Message <string>] [-TargetObject <Object>] [-CategoryActivity <string>] [-CategoryReason <string>] [-CategoryTargetName <string>] [-CategoryTargetType <string>] [-RecommendedAction <string>] [<CommonParameters>]

Descrição

O cmdlet Write-Error grava um erro no fluxo de erros do Windows PowerShell. Por padrão, são enviados erros ao programa host a ser exibido, junto com a saída.

Você pode gravar um erro enviando uma cadeia de caracteres de mensagem de erro, um objeto ErrorRecord ou um objeto Exception. Use os outros parâmetros de Write-Error para popular o registro de erro.

Parâmetros

-Category <ErrorCategory>

Especifica a categoria do erro. O valor padrão é NotSpecified.

Para obter informações sobre as categorias de erro, consulte "ErrorCategory Enumeration" na biblioteca do MSDN (Microsoft Developer Network) em https://go.microsoft.com/fwlink/?LinkId=143600.

Necessário?	false
Posição?	named
Valor padrão	NotSpecified
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-CategoryActivity <string>

Descreve a ação que provocou o erro.

Necessário?	false
Posição?	named
Valor padrão	Nenhum
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-CategoryReason <string>

Explica como ou porque a atividade provocou o erro.

Necessário?	false
Posição?	named
Valor padrão	Nenhum
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-CategoryTargetName <string>

Especifica o nome do objeto que estava sendo processado quando ocorreu o erro.

Necessário?	false
Posição?	named
Valor padrão	Nenhum
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-CategoryTargetType <string>

Especifica o tipo .NET do objeto que estava sendo processado quando ocorreu o erro.

Necessário?	false
Posição?	named
Valor padrão	Nenhum
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-ErrorId <string>

Especifica uma cadeia de caracteres de ID para identificar o erro. A cadeia de caracteres deve ser exclusiva ao erro.

Necessário?	false
Posição?	named
Valor padrão	Nenhum
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-ErrorRecord <ErrorRecord>

Especifica um objeto de registro de erro que inclui propriedades que descrevem o erro.

Para obter um objeto de registro de erro, use o cmdlet New-Object ou use um objeto de registro de erro da matriz na variável automática $Error.

Necessário?	true
Posição?	named
Valor padrão	Nenhum
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-Exception <Exception>

Especifica uma exceção que representa o erro.

É possível usar uma exceção em vez de especificar o texto da mensagem ou um registro de exceção.

Necessário?	true
Posição?	named
Valor padrão	Nenhum
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-Message <string>

Especifica o texto da mensagem do erro. Se o texto incluir espaços ou caracteres especiais, coloque-o entre aspas. Também é possível canalizar uma cadeia de mensagens para o Write-Error.

Necessário?	true
Posição?	1
Valor padrão	Nenhum
Aceitar entrada do pipeline?	true (ByValue)
Aceitar caracteres curinga?	false

-RecommendedAction <string>

Descreve a ação que o usuário deve tomar para resolver ou impedir o erro.

Necessário?	false
Posição?	named
Valor padrão	Nenhum
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-TargetObject <Object>

Especifica o objeto que estava sendo processado quando ocorreu o erro. Insira o objeto (como uma cadeia de caracteres), uma variável que contenha o objeto ou um comando que obtenha o objeto.

Necessário?	false
Posição?	named
Valor padrão	Nenhum
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

<CommonParameters>

Esse cmdlet oferece suporte aos parâmetros comuns: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer e -OutVariable. Para obter mais informações, consulte about_Commonparameters.

Entradas e saídas

O tipo de entrada é o tipo dos objetos que você pode canalizar para o cmdlet. O tipo de retorno é o tipo dos objetos que o cmdlet retorna.

Entradas	System.String Você pode canalizar uma cadeia de caracteres que contém uma mensagem de erro para Write-Error.
Saídas	Objeto de erro Write-Error só grava no fluxo de erros. Ele não retorna objetos.

Exemplo 1

C:\PS>get-childitem | foreach-object { if ($_.gettype().tostring() -eq "Microsoft.Win32.RegistryKey") {write-error "Out-of-band object" -errorID B1 -targetobject $_ } else {$_ } }

Descrição
-----------
Esse comando grava um erro quando o cmdlet Get-ChildItem retorna um objeto Microsoft.Win32.RegistryKey, como os objetos nas unidades HKLM: ou HKCU do provedor Registry do Windows PowerShell.

Exemplo 2

C:\PS>write-error  "Access denied."

Descrição
-----------
Esse comando grava um erro "Access denied". O comando usa o parâmetro Message para especificar a mensagem, mas omite o nome do parâmetro Message opcional.

Exemplo 3

C:\PS>write-error -message "Error: Too many input values." -category InvalidArgument

Descrição
-----------
Esse comando grava um erro e especifica uma categoria de erro.

Consulte também

Conceitos

Write-Debug
Write-Verbose
Write-Output
Write-Host
Write-Progress
Write-Warning