Compartir a través de

Registros de errores de Windows PowerShell

Los cmdlets deben pasar un objeto System.Management.Automation.ErrorRecord que identifica la condición de error para terminar y no terminar errores.

El objeto System.Management.Automation.ErrorRecord contiene la siguiente información:

  • Excepción que describe el error. A menudo, se trata de una excepción que el cmdlet detectó y convirtió en un registro de error. Cada registro de error debe contener una excepción.

Si el cmdlet no ha captado una excepción, debe crear una nueva excepción y elegir la clase de excepción que describa mejor la condición de error. Sin embargo, no es necesario iniciar la excepción porque se puede acceder a ella a través de la propiedad System.Management.Automation.ErrorRecord.Exception del objeto System.Management.Automation.ErrorRecord.

  • Identificador de error que proporciona un designador de destino que se puede usar con fines de diagnóstico y mediante scripts de Windows PowerShell para controlar condiciones de error específicas con controladores de errores específicos. Cada registro de error debe contener un identificador de error (consulte Identificador de error).

  • Categoría de error que proporciona un designador general que se puede usar con fines de diagnóstico. Cada registro de error debe especificar una categoría de error (consulte Categoría de error).

  • Un mensaje de error de reemplazo opcional y una acción recomendada (consulte Mensaje de error de reemplazo).

  • Información de invocación opcional sobre el cmdlet que produjo el error. Windows PowerShell especifica esta información (vea Mensaje de invocación).

  • Objeto de destino que se estaba procesando cuando se produjo el error. Podría ser el objeto de entrada o podría ser otro objeto que el cmdlet estaba procesando. Por ejemplo, para el comando Remove-Item -Recurse C:\somedirectory, el error podría ser una instancia de un objeto FileInfo para "C:\somedirectory\lockedfile". La información del objeto de destino es opcional.

Identificador de error

Al crear un registro de error, especifique un identificador que designe la condición de error dentro del cmdlet. Windows PowerShell combina el identificador de destino con el nombre del cmdlet para crear un identificador de error completo. Se puede acceder al identificador de error completo a través de la propiedad System.Management.Automation.ErrorRecord.FullyQualifiedErrorId del objeto System.Management.Automation.ErrorRecord. El identificador de error no está disponible por sí mismo. Solo está disponible como parte del identificador de error completo.

Use las instrucciones siguientes para generar identificadores de error al crear registros de error:

  • Realice identificadores de error específicos de una condición de error. Tenga como destino los identificadores de error con fines de diagnóstico y para scripts que controlan condiciones de error específicas con controladores de errores específicos. Un usuario debe poder usar el identificador de error para identificar el error y su origen. Los identificadores de error también permiten notificar condiciones de error específicas de excepciones existentes para que no se requieran nuevas subclases de excepción.

  • En general, asigne identificadores de error diferentes a rutas de acceso de código diferentes. El usuario final se beneficia de identificadores específicos. A menudo, cada ruta de acceso de código que llama a System.Management.Automation.Cmdlet.WriteError o System.Management.Automation.Cmdlet.ThrowTerminatingError* tiene su propio identificador. Como regla, defina un nuevo identificador al definir una nueva cadena de plantilla para el mensaje de error y viceversa. No use el mensaje de error como identificador.

  • Al publicar código con un identificador de error determinado, se establece la semántica de los errores con ese identificador para el ciclo de vida completo de soporte técnico del producto. No reutilice en un contexto que sea semánticamente diferente del contexto original. Si la semántica de este cambio de error, cree y, a continuación, use un nuevo identificador.

  • Por lo general, solo debe usar un identificador de error determinado para excepciones de un tipo CLR determinado. Si cambia el tipo de excepción o el tipo del objeto de destino, cree y, a continuación, use un nuevo identificador.

  • Elija texto para el identificador de error que corresponda concisamente al error que está notificando. Use las convenciones estándar de nomenclatura y mayúsculas de .NET Framework. No use espacios en blanco ni signos de puntuación. No localice los identificadores de error.

  • No genere de forma dinámica identificadores de error de forma no reproducible. Por ejemplo, no incorpore información de error como un identificador de proceso. Los identificadores de error solo son útiles si corresponden a los identificadores de error vistos por otros usuarios que experimentan la misma condición de error.

Categoría de error

Al crear un registro de error, especifique la categoría del error mediante una de las constantes definidas por la enumeración System.Management.Automation.ErrorCategory. Windows PowerShell usa la categoría de error para mostrar información de error cuando los usuarios establecen la variable $ErrorView en "CategoryView".

Evite usar la constante System.Management.Automation.ErrorCategoryNotSpecified. Si tiene información sobre el error o sobre la operación que provocó el error, elija la categoría que mejor describa el error o la operación, incluso si la categoría no es una coincidencia perfecta.

La información mostrada por Windows PowerShell se conoce como la cadena de vista de categorías y se crea a partir de las propiedades de la clase System.Management.Automation.ErrorCategoryInfo. (Se accede a esta clase a través de la propiedad error System.Management.Automation.ErrorRecord.CategoryInfo).

{Category}: ({TargetName}:{TargetType}):[{Activity}], {Reason}

En la lista siguiente se describe la información que se muestra:

  • Categoría: una constante System.Management.Automation.ErrorCategor y definida por Windows PowerShell.

  • TargetName: de forma predeterminada, el nombre del objeto que el cmdlet estaba procesando cuando se produjo el error. O bien, otra cadena definida por el cmdlet.

  • TargetType: de forma predeterminada, el tipo del objeto de destino. O bien, otra cadena definida por el cmdlet.

  • Actividad: de forma predeterminada, el nombre del cmdlet que creó el registro de error. O bien, alguna otra cadena definida por cmdlets.

  • Motivo: De forma predeterminada, el tipo de excepción. O bien, otra cadena definida por el cmdlet.

Mensaje de error de reemplazo

Al desarrollar un registro de error para un cmdlet, el mensaje de error predeterminado para el error procede del texto del mensaje predeterminado en la propiedad System.Exception.Message de. Se trata de una propiedad de solo lectura cuyo texto de mensaje está pensado solo para fines de depuración (según las directrices de .NET Framework). Se recomienda crear un mensaje de error que reemplace o aumente el texto del mensaje predeterminado. Haga que el mensaje sea más fácil de usar y más específico para el cmdlet.

El mensaje de reemplazo lo proporciona un objeto System.Management.Automation.ErrorDetails. Use uno de los siguientes constructores de este objeto porque proporcionan información adicional de localización que Windows PowerShell puede usar.

El mensaje de reemplazo debe ajustarse a las directrices de diseño de .NET Framework para escribir mensajes de excepción con una pequeña diferencia. Las directrices indican que los mensajes de excepción se deben escribir para los desarrolladores. Estos mensajes de reemplazo deben escribirse para el usuario del cmdlet.

Se debe agregar el mensaje de error de reemplazo antes de llamar a los métodos de System.Management.Automation.Cmdlet.WriteError o System.Management.Automation.Cmdlet.ThrowTerminatingError*. Para agregar un mensaje de reemplazo, establezca la propiedad System.Management.Automation.ErrorRecord.ErrorDetails del registro de error. Cuando se establece esta propiedad, Windows PowerShell muestra la propiedad System.Management.Automation.ErrorDetails.Message* en lugar del texto del mensaje predeterminado.

El objeto System.Management.Automation.ErrorDetails también puede proporcionar información sobre qué acciones se recomiendan cuando se produce el error.

Información de invocación

Cuando un cmdlet usa System.Management.Automation.Cmdlet.WriteError o System.Management.Automation.Cmdlet.ThrowTerminatingError* para notificar un registro de error, Windows PowerShell agrega automáticamente información que describe el comando que se invocó cuando se produjo el error. Esta información la proporciona un objeto System.Management.Automation.InvocationInfo que contiene el nombre del cmdlet invocado por el comando, el propio comando e información sobre la canalización o el script. Esta propiedad es de sólo lectura.

Véase también

System.Management.Automation.Cmdlet.WriteError

System.Management.Automation.Cmdlet.ThrowTerminatingError*

System.Management.Automation.ErrorCategory

System.Management.Automation.ErrorCategoryInfo

System.Management.Automation.ErrorRecord

System.Management.Automation.ErrorDetails

System.Management.Automation.InvocationInfo

informe de errores de Windows PowerShell

escribir un cmdlet de Windows PowerShell

  • Last updated on