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




Tabla de contenido