TEMA about_Debuggers DESCRIPCIÓN BREVE Describe el depurador de Windows PowerShell. DESCRIPCIÓN DETALLADA Depurar es el proceso de examinar un script mientras se ejecuta a fin de identificar y corregir errores que pueda haber en las instrucciones del script. El depurador de Windows PowerShell se ha diseñado para ayudarle a examinar e identifica errores e ineficacias en los scripts. Nota: el depurador de Windows PowerShell no se ejecuta remotamente. Para depurar un script en un equipo remoto, copie el script en el equipo local. Las características del depurador de Windows PowerShell se pueden utilizar para examinar un script, una función, un comando o una expresión de Windows PowerShell mientras se está ejecutando. El depurador de Windows PowerShell incluye un conjunto de cmdlets que permiten establecer y administrar puntos de interrupción, así como ver la pila de llamadas. Windows PowerShell proporciona varios métodos que se pueden utilizar para depurar el script, las funciones y los comandos. Método 1: el cmdlet Set-PsDebug proporciona características de depuración de script básicas, como la ejecución paso a paso y el seguimiento. Para obtener más información, escriba: "get-help set-psdebug". Método 2: el cmdlet Set-StrictMode se utiliza para detectar las referencias a las variables no inicializadas o a propiedades no existentes de un objeto, así como sintaxis de funciones no válida. Método 3: se pueden agregar instrucciones de diagnóstico a un script, como las que muestran el valor de las variables, las que leen la entrada de la línea de comandos o las que informan de cuál es la instrucción actual. Para esta tarea se utilizan los cmdlets que contienen el verbo Write, tales como Write-Host, Write-Debug, Write-Warning y Write-Verbose. Método 4: el depurador de Windows PowerShell se utiliza para depurar un script. También puede utilizarse para depurar una función o un bloque de script que se ha escrito en el símbolo del sistema. Es posible establecer puntos de interrupción, ejecutar el script paso a paso, examinar los valores de las variables, ejecutar los comandos de diagnóstico y registro, y mostrar la pila de llamadas. Cmdlets del depurador El depurador de Windows PowerShell incluye el conjunto siguiente de cmdlets: Set-PsBreakpoint: establece puntos de interrupción en las líneas, las variables y los comandos. Get-PsBreakpoint: obtiene los puntos de interrupción de la sesión actual. Disable-PsBreakpoint: desactiva los puntos de interrupción de la sesión actual. Enable-PsBreakpoint: vuelve a habilitar todos los puntos de interrupción de la sesión actual. Remove-PsBreakpoint: elimina todos los puntos de interrupción de la sesión actual. Get-PsCallStack: muestra la pila de llamadas actual. Iniciar y detener el depurador Para iniciar el depurador, establezca uno o más puntos de interrupción. A continuación, ejecute el script, el comando o la función que desee depurar. Al llegar a un punto de interrupción, la ejecución se detiene y se entrega el control al depurador. Para detener el depurador, ejecute el script, el comando o la función hasta que haya finalizado. O bien, escriba "stop" o "t". Comandos del depurador Cuando se utiliza el depurador en la consola de Windows PowerShell, los comandos siguientes permiten controlar la ejecución. Nota: para obtener información sobre cómo utilizar el depurador en otras aplicaciones host, consulte la documentación de la aplicación host. s, Step-into Ejecuta la próxima instrucción y, a continuación, se detiene. v, Step-over Ejecuta la próxima instrucción, pero omite funciones e invocaciones. Las instrucciones omitidas se ejecutan, pero no paso a paso. o, Step-out Recorre la función actual paso a paso para salir; sube un nivel si está anidada. Si está en el cuerpo principal, continúa hasta el final o hasta el próximo punto de interrupción. Las instrucciones omitidas se ejecutan, pero no paso a paso. c, Continue Continúa ejecutándose hasta que el script haya finalizado o hasta que se alcance el próximo punto de interrupción. Las instrucciones omitidas se ejecutan, pero no paso a paso. l, List Muestra la parte del script que se está ejecutando. De forma predeterminada, muestra la línea actual, cinco líneas anteriores y 10 líneas subsiguientes. Para seguir mostrando el script, presione ENTRAR. l <m>, List Muestra 16 líneas del script, empezando por el número de línea especificado por <m>. l <m> <n>, List Muestra <n> líneas del script, empezando por el número de línea especificado por <m>. q, Stop Detiene la ejecución del script y sale del depurador. k, Get-PsCallStack Muestra la pila de llamadas actual. <Enter> Repite el último comando si era Step (s), Step-over (v) o List (l). De lo contrario, representa una acción de envío. ?, h Muestra la Ayuda de comandos del depurador. Para salir del depurador, se utiliza Stop (q). Desde el propio depurador también es posible escribir comandos, mostrar el valor de las variables, usar cmdlets y ejecutar scripts. Con estos comandos del depurador, es posible ejecutar un script, detenerse en un punto complicado, estudiar los valores de las variables y el estado del sistema, y seguir ejecutando el script hasta identificar un problema. Entorno del depurador Al llegar a un punto de interrupción, se entra en el entorno del depurador. El símbolo del sistema cambia y comienza por "[DBG]:". El símbolo del sistema se puede personalizar. Además, en algunas aplicaciones host, como la consola de Windows PowerShell, (pero no en el entorno de scripting integrado de Windows PowerShell [ISE]) se abre un símbolo del sistema anidado para llevar a cabo la depuración. Puede detectar que se trata de un símbolo del sistema anidado por los caracteres de mayor que (ASCII 62) seguidos que aparecen en el símbolo del sistema. Por ejemplo, a continuación se muestra el símbolo del sistema de depuración predeterminado en la consola de Windows PowerShell: [DBG]: PS (get-location)>>> El nivel de anidamiento se puede buscar mediante la variable automática $NestedPromptLevel. Además, se define una variable automática, $ PSDebugContext, en el ámbito local. La presencia de la variable $PsDebugContext se puede usar para determinar si la ejecución se está realizando en el depurador. Por ejemplo: if ($psdebugcontext) {"Depurando"} else {"No depurando"} El valor de la variable $PSDebugContext se puede usar al depurar. [DBG]: PS>>> $psdebugcontext.invocationinfo Nombre CommandLineParameters UnboundArguments Ubicación ---- --------------------- ---------------- -------- = {} {} C:\ps-test\vote.ps1 (1) Depuración y ámbito Al efectuar una interrupción que pasa el control al depurador, no se cambia el ámbito en el que se opera; sin embargo, cuando se alcanza un punto de interrupción en un script, se pasa al ámbito del script. El ámbito del script es un elemento secundario del ámbito en el que se ejecutó el depurador. Para buscar las variables y los alias definidos en el ámbito del script, se utiliza el parámetro Scope de los cmdlets Get-Alias o Get-Variable. Por ejemplo, el comando siguiente obtiene las variables del ámbito local (script): get-variable -scope 0 Este comando puede abreviarse como sigue: gv -s 0 Se trata de una manera útil de ver únicamente las variables que se han definido en el script y durante la depuración. Depurar en la línea de comandos Cuando se establece un punto de interrupción de variable o de comando, el punto de interrupción solamente se puede establecer en un archivo de script. Sin embargo, de forma predeterminada, el punto de interrupción se establece en cualquier cosa que se ejecute en la sesión actual. Por ejemplo, si establece un punto de interrupción en la variable $name, el depurador lleva a cabo la interrupción en cualquier variable $name de cualquier script, comando, función, cmdlet de script o expresión que se ejecute hasta que se deshabilite o quite el punto de interrupción. Esto permite depurar los scripts en un contexto más realista, donde les pueden afectar funciones, variables y otros scripts de la sesión y del perfil del usuario. Los puntos de interrupción de línea son específicos de los archivos de script, de modo que solamente se establecen en estos archivos. Depurar funciones Cuando se establece un punto de interrupción en una función que tiene secciones Begin, Process y End, el depurador realiza la interrupción en la primera línea de cada sección. Por ejemplo: function test-cmdlet { begin { write-output "Begin" } process { write-output "Process" } end { write-output "End" } } C:\PS> set-psbreakpoint -command test-cmdlet C:\PS> test-cmdlet Begin Entrando en modo de depuración. Use h o ? para obtener ayuda. Alcanzar Punto de interrupción de comando en 'prompt:test-cm dlet' test-cmdlet [DBG]: C:\PS> c Process Entrando en modo de depuración. Use h o ? para obtener ayuda. Alcanzar Punto de interrupción de comando en 'prompt:test-cm dlet' test-cmdlet [DBG]: C:\PS> c End Entrando en modo de depuración. Use h o ? para obtener ayuda. Alcanzar Punto de interrupción de comando en 'prompt:test-cm dlet' test-cmdlet [DBG]: C:\PS> Depurar scripts remotos El depurador de Windows PowerShell no se puede ejecutar en una sesión remota. Para depurar un script en un equipo remoto, copie el script en el equipo local. El comando siguiente copia el script Test.ps1 del equipo remoto Server01 en el equipo local: invoke-command -computername Server01 ` {get-content c:\ps-test\test.ps1} | set-location c:\ps-test\test.ps1 Ejemplos Este script de prueba detecta la versión del sistema operativo y muestra el mensaje apropiado para el sistema. Incluye una función, una llamada a una función y una variable. El comando siguiente muestra el contenido del archivo de script de pruebas: c:>\PS-test> get-content test.ps1 function psversion { "Windows PowerShell " + $psversiontable.psversion if ($psversiontable.psversion.major -lt 2) { "Debe actualizarse a Windows PowerShell 2.0" } else { "¿Ha ejecutado hoy un trabajo de segundo plano (start-job)?" } } $scriptname = $MyInvocation.MyCommand.Path psversion "$scriptname finalizado." Para comenzar, establezca un punto de interrupción en un punto de interés del script, como una línea, un comando, una variable o una función. Empiece creando un punto de interrupción de línea en la primera línea del script Test.ps1 del directorio actual. PS C:\ps-test> set-psbreakpoint -line 1 -script test.ps1 Este comando puede abreviarse como sigue: PS C:\ps-test> spb 1 -s test.ps1 El comando devuelve un objeto del punto de interrupción de línea (System.Management.Automation.LineBreakpoint). Column : 0 Line : 1 Action : Enabled : True HitCount : 0 Id : 0 Script : C:\ps-test\test.ps1 ScriptName : C:\ps-test\test.ps1 Ahora, inicie el script. PS C:\ps-test> .\test.ps1 Cuando el script alcanza el primer punto de interrupción, el mensaje de punto de interrupción indica que el depurador está activo. Describe el punto de interrupción y ofrece una vista previa de la primera línea del script, que es una declaración de función. El símbolo del sistema también cambia para indicar que el depurador tiene el control. La línea de vista previa incluye el nombre del script y el número de línea del comando cuya vista previa se muestra. Entrando en modo de depuración. Use h o ? para obtener ayuda. Alcanzar Punto de interrupción de línea en 'C:\ps-test\test. ps1:1' test.ps1:1 function psversion { DBG> Utilice el comando Step (s) para ejecutar la primera instrucción del script y mostrar una vista previa de la próxima instrucción. En la instrucción siguiente se utiliza la variable automática $MyInvocation para establecer el valor de la variable &ScriptName en la ruta de acceso y el nombre del archivo de script. DBG> s test.ps1:11 $scriptname = $MyInvocation.MyCommand.Path En este punto, la variable $ScriptName no contiene ningún valor, pero se puede comprobar el valor de la variable mostrándolo. En este caso, el valor es $null. DBG> $scriptname DBG> Utilice otro comando Step (s) para ejecutar la instrucción actual y mostrar una vista previa de la próxima instrucción del script. La instrucción siguiente llama a la función PsVersion. DBG> s test.ps1:12 psversion En este punto, la variable $ScriptName contiene un valor, pero se puede comprobar el valor de la variable mostrándolo. En este caso, el valor está establecido en la ruta de acceso del script. DBG> $scriptname C:\ps-test\test.ps1 Utilice otro comando Step para ejecutar la llamada a la función. Presione ENTRAR o escriba "s" en lugar de Step. DBG> s test.ps1:2 "Windows PowerShell " + $psversiontable.psversion El mensaje de depuración incluye una vista previa de la instrucción en la función. Para ejecutar esta instrucción y mostrar una vista previa de la próxima instrucción de la función, se puede utilizar un comando Step. Sin embargo, en este caso, utilice el comando Step-Out (o). Completa la ejecución de la función (a menos que alcance un punto de interrupción) y pasa a la próxima instrucción del script. DBG> o Windows PowerShell 2.0 ¿Ha ejecutado hoy un trabajo de segundo plano (start-job)? test.ps1:13 "$scriptname finalizado" Dado que nos encontramos en la última instrucción del script, los comandos Step, Step-Out y Continue tienen el mismo efecto. En este caso, utilice Step-Out (o). C:\ps-test\test.ps1 finalizado PS C:\ps-test> El comando Step-Out ejecuta el último comando. El símbolo del sistema estándar indica que el depurador se ha cerrado y ha devuelto el control al procesador de comandos. Ahora, ejecute el depurador de nuevo. Primero, para eliminar el punto de interrupción actual, utilice los cmdlets Get-PsBreakpoint y Remove-PsBreakpoint. (Si piensa que es posible reutilizar el punto de interrupción, utilice el cmdlet Disable-PsBreakpoint en lugar de Remove-PsBreakpoint.) PS C:\ps-test> Get-PsBreakpoint | Remove-PSBreakpoint Este comando puede abreviarse como sigue: PS C:\ps-test> gbp | rbp Otra posibilidad es ejecutar el comando escribiendo una función, como la siguiente: function delbr { gbp | rbp } Ahora, cree un punto de interrupción en la variable $scriptname. PS C:\ps-test> set-psbreakpoint -variable scriptname -script test.ps1 Este comando puede abreviarse como sigue: PS C:\ps-test> sbp -v scriptname -s test.ps1 Ahora, inicie el script. El script alcanza el punto de interrupción de variable. El modo predeterminado es Write, así que la ejecución se detiene justo delante de la instrucción que cambia el valor de la variable. PS C:\ps-test> .\test.ps1 Alcanzar Punto de interrupción variable en 'C:\ps-test\test.ps1:$scriptname' (acceso Write) test.ps1:11 $scriptname = $MyInvocation.mycommand.path DBG> Muestre el valor actual de la variable $scriptname, que es $null. DBG> $scriptname DBG> Utilice un comando Step (s) para ejecutar la instrucción contenida en la variable. A continuación, muestre el nuevo valor de la variable $scriptname. DBG> $scriptname C:\ps-test\test.ps1 Utilice un comando Step (s) para mostrar una vista previa de la próxima instrucción del script. DBG> s test.ps1:12 psversion La próxima instrucción es una llamada a la función PsVersion. Para omitir la función pero ejecutarla, utilice un comando Step-Over (v). Si ya se encuentra en la función cuando utilice Step-Over, no surtirá efecto. Se muestra la llamada a la función, pero no se ejecuta. DBG> v Windows PowerShell 2.0 ¿Ha ejecutado hoy un trabajo de segundo plano (start-job)? test.ps1:13 "$scriptname finalizado" El comando Step-Over ejecuta la función y muestra una vista previa de la próxima instrucción del script, que imprime la línea final. Utilice un comando Stop (t) para salir del depurador. El símbolo del sistema regresa al símbolo del sistema estándar. C:\ps-test> Para eliminar los puntos de interrupción, utilice los cmdlets Get-PsBreakpoint y Remove-PsBreakpoint. PS C:\ps-test> Get-PsBreakpoint | Remove-PSBreakpoint Cree un nuevo punto de interrupción de comando en la función PsVersion. PS C:\ps-test> Set-PsBreakpoint -command psversion -script test.ps1 Este comando puede abreviarse como sigue: PS C:\ps-test> sbp -c psversion -s test.ps1 Ahora, ejecute el script. PS C:\ps-test> .\test.ps1 Alcanzar Punto de interrupción de comando en 'C:\ps-test\test.ps1:psversion' test.ps1:12 psversion DBG> El script alcanza el punto de interrupción en la llamada a la función. En este punto, todavía no se ha llamado a la función. Esto le permite utilizar el parámetro Action de Set-PsBreakpoint a fin de establecer las condiciones para la ejecución del punto de interrupción o realizar tareas de preparación o diagnóstico, tales como iniciar un registro o invocar un script de diagnóstico o de seguridad. Para establecer una acción, utilice un comando Continue (c) para salir del script y un comando Remove-PsBreakpoint para eliminar el punto de interrupción actual. (Los puntos de interrupción son de solo lectura, de modo que no se puede agregar una acción al punto de interrupción actual.) DBG> c Windows PowerShell 2.0 ¿Ha ejecutado hoy un trabajo de segundo plano (start-job)? C:\ps-test\test.ps1 finalizado PS C:\ps-test> get-psbreakpoint | remove-psbreakpoint PS C:\ps-test> Ahora, cree un nuevo punto de interrupción de comando con una acción. El comando siguiente establece un punto de interrupción de comando con una acción que registra el valor de la variable $scriptname cuando se llama a la función. Dado que la palabra clave Break no se utiliza en la acción, la ejecución no se detiene. (El carácter de acento grave [`] es el carácter de continuación de línea.) PS C:\ps-test> set-psbreakpoint -command psversion -script test.ps1 ` -action { add-content "El valor de `$scriptname es $scriptname." ` path action.log} También puede agregar acciones que establezcan condiciones para el punto de interrupción. En el comando siguiente, el punto de interrupción de comando se ejecuta solamente si la directiva de ejecución se establece en RemoteSigned, la directiva más restrictiva que permite ejecutar scripts. (El carácter de acento grave [`] es el carácter de continuación.) PS C:\ps-test> set-psbreakpoint -script test.ps1 -command psversion ` -action { if ((get-executionpolicy) -eq "RemoteSigned") { break }} La palabra clave Break en la acción dirige el depurador para que ejecute el punto de interrupción. También puede utilizar la palabra clave Continue si desea dirigir el depurador para que se ejecute sin interrupciones. Dado que la palabra clave predeterminada es Continue, debe especificar Break si desea detener la ejecución. Ahora, ejecute el script. PS C:\ps-test> .\test.ps1 Alcanzar Punto de interrupción de comando en 'C:\ps-test\test.ps1:psversion' test.ps1:12 psversion Dado que la directiva de ejecución se ha establecido en RemoteSigned, la ejecución se detiene en la llamada a la función. En este punto, puede ser interesante comprobar la pila de llamadas. Utilice el cmdlet Get-PsCallStack o el comando Get-PsCallStack (k) del depurador. El comando siguiente obtiene la pila de llamadas actual. DBG> k 2: prompt 1: .\test.ps1: $args=[] 0: prompt: $args=[] En este ejemplo se muestran tan solo algunas de las maneras de utilizar el depurador de Windows PowerShell. Para obtener más información sobre los cmdlets del depurador, escriba el comando siguiente: help <nombre-del-cmdlet> -full Por ejemplo, escriba: help set-psbreakpoint -full VEA TAMBIÉN Disable-PsBreakpoint Get-PsBreakpoint Remove-PsBreakpoint Set-PsBreakpoint Set-PsDebug Set-Strictmode Write-Debug Write-Verbose Enable-PsBreakpoint Get-PsCallStack