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