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 string 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 http://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 string de ID para identificar o erro. A string 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 string), 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 string que contém uma mensagem de erro para Write-Error. |
| Saídas | Error object
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.