Registros de errores de Windows PowerShell

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

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

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

Si el cmdlet no detectó una excepción, debe crear una nueva excepción y elegir la clase de excepción que mejor describa la condición de error. Sin embargo, no es necesario generar 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.

• Un 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).

• Una categoría de error que proporciona un designador general que se puede utilizar 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. Esta información la especifica Windows PowerShell (consulte Mensaje de invocación).

• El objeto de destino que se estaba procesando cuando ocurrió el error. Este 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

Cuando crea un registro de error, especifique un identificador que designe la condición de error dentro de su cmdlet. Windows PowerShell combina el identificador de destino con el nombre de su 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í solo. Está disponible sólo como parte del identificador de error completo.

Utilice las siguientes pautas para generar identificadores de error cuando cree registros de error:

• Cree identificadores de error específicos para una condición de error. Apunte a los identificadores de error con fines de diagnóstico y para scripts que controlen condiciones de error específicas con controladores de errores específicos. Un usuario debería poder utilizar el identificador de error para identificar el error y su origen. Los identificadores de error también permiten generar informes sobre condiciones de error específicas de excepciones existentes, de modo que no se requieren nuevas subclases de excepción.

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

• Cuando publica código utilizando un identificador de error particular, establece la semántica de los errores con ese identificador para el ciclo de vida completo de soporte del producto. No lo reutilice en un contexto que sea semánticamente diferente del contexto original. Si la semántica de este error cambia, cree y luego use un nuevo identificador.

• Por lo general, debería utilizar un identificador de error concreto sólo para excepciones de un tipo de CLR concreto. Si el tipo de excepción o el tipo de objeto de destino cambia, cree y luego use un nuevo identificador.

• Elija un texto para su identificador de error que corresponda de manera concisa al error que está informando. Utilice convenciones estándar de nomenclatura y uso de mayúsculas en .NET Framework. No utilice espacios en blanco ni puntuación. No localice identificadores de error.

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

Categoría de error

Cuando crea un registro de error, especifique la categoría del error utilizando 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 configuran la variable $ErrorView en "CategoryView".

Evite el uso de la constante System.Management.Automation.ErrorCategory NotSpecified. Si tiene alguna información sobre el error o sobre la operación que causó el error, elija la categoría que mejor describa el error o la operación, incluso si la categoría no coincide perfectamente.

La información que muestra Windows PowerShell se conoce como cadena de vista de categoría 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 de error System.Management.Automation.ErrorRecord.CategoryInfo).

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

La siguiente lista describe la información mostrada:

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

• TargetName: de forma predeterminada, el nombre del objeto que el cmdlet estaba procesando cuando ocurrió el error. U otra cadena definida por cmdlet.

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

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

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

Mensaje de error de reemplazo

Cuando desarrolla un registro de error para un cmdlet, el mensaje de error predeterminado para el error proviene del texto del mensaje predeterminado en la propiedad System.Exception.Message. Esta es una propiedad de solo lectura cuyo texto de mensaje está destinado únicamente a fines de depuración (de acuerdo con las pautas de .NET Framework). Le recomendamos que cree 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. Utilice uno de los siguientes constructores de este objeto porque proporcionan información de localización adicional que Windows PowerShell puede utilizar.

• ErrorDetails(Cmdlet, String, String, Object[]): use este constructor si la cadena de plantilla es una cadena de recursos en el mismo ensamblado en el que se implementa el cmdlet o si desea cargar la cadena de plantilla mediante una anulación del System. Método Management.Automation.Cmdlet.GetResourceString.

• ErrorDetails(Assembly, String, String, Object[]): use este constructor si la cadena de plantilla está en otro ensamblado y no la carga mediante una anulación de System.Management.Automation.Cmdlet.GetResourceString.

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

El mensaje de error de reemplazo se debe agregar antes de llamar a los métodos 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.

Información de acción recomendada

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 informar un registro de error, Windows PowerShell agrega automáticamente información que describe el comando que se invocó cuando ocurrió el error. Esta información la proporciona un objeto System.Management.Automation.Invocationinfo que contiene el nombre del cmdlet invocado por el comando, el comando en sí e información sobre la canalización o el script. Esta propiedad es de sólo lectura.

Ver también

System.Management.Automation.Cmdlet.WriteError

Error de terminación de lanzamiento del cmdlet de automatización de administración del sistema*

Categoría.de.error.de.automatización.de.gestión.del.sistema

System.Management.Automation.Errorcategoryinfo

Registro de errores de automatización de gestión del sistema

System.Management.Automation.ErrorDetails

System.Management.Automation.Invocationinfo

Informe de errores de Windows PowerShell

Escribir un cmdlet de Windows PowerShell