Set-PSBreakpoint

  • Referencia
Módulo:
Microsoft.PowerShell.Utility

Establece un punto de interrupción en una línea, un comando o una variable.

Syntax

Set-PSBreakpoint
   [-Action <ScriptBlock>]
   [[-Column] <Int32>]
   [-Line] <Int32[]>
   [-Script] <String[]>
   [-Runspace <Runspace>]
   [<CommonParameters>]
Set-PSBreakpoint
   [-Action <ScriptBlock>]
   -Command <String[]>
   [[-Script] <String[]>]
   [-Runspace <Runspace>]
   [<CommonParameters>]
Set-PSBreakpoint
   [-Action <ScriptBlock>]
   [[-Script] <String[]>]
   -Variable <String[]>
   [-Mode <VariableAccessMode>]
   [-Runspace <Runspace>]
   [<CommonParameters>]

Description

El Set-PSBreakpoint cmdlet establece un punto de interrupción en un script o en cualquier comando que se ejecute en la sesión actual. Puede usar Set-PSBreakpoint para establecer un punto de interrupción antes de ejecutar un script o ejecutar un comando, o durante la depuración, cuando se detiene en otro punto de interrupción.

Set-PSBreakpoint no puede establecer un punto de interrupción en un equipo remoto. Para depurar un script en un equipo remoto, copie el script en el equipo local y depúrelo localmente.

Cada Set-PSBreakpoint comando crea uno de los tres tipos siguientes de puntos de interrupción:

  • Punto de interrupción de línea: establece puntos de interrupción en coordenadas de línea y columna concretas.
  • Punto de interrupción de comandos: establece puntos de interrupción en comandos y funciones.
  • Punto de interrupción variable: establece puntos de interrupción en variables.

Puede establecer un punto de interrupción en varias líneas, comandos o variables en un solo Set-PSBreakpoint comando, pero cada Set-PSBreakpoint comando establece solo un tipo de punto de interrupción.

En un punto de interrupción, PowerShell deja de ejecutarse temporalmente y proporciona control al depurador. El símbolo del sistema cambia a DBG\>y un conjunto de comandos del depurador están disponibles para su uso. Sin embargo, puede usar el parámetro Action para especificar una respuesta alternativa, como condiciones para el punto de interrupción o instrucciones para realizar tareas adicionales, como el registro o el diagnóstico.

El Set-PSBreakpoint cmdlet es uno de los varios cmdlets diseñados para depurar scripts de PowerShell. Para obtener más información sobre el depurador de PowerShell, consulte about_Debuggers.

Ejemplos

Ejemplo 1: Establecer un punto de interrupción en una línea

En este ejemplo se establece un punto de interrupción en la línea 5 del script Sample.ps1. Cuando se ejecuta el script, la ejecución se detiene inmediatamente antes de que se ejecute la línea 5.

Set-PSBreakpoint -Script "sample.ps1" -Line 5

Column     : 0
Line       : 5
Action     :
Enabled    : True
HitCount   : 0
Id         : 0
Script     : C:\ps-test\sample.ps1
ScriptName : C:\ps-test\sample.ps1

Cuando se establece un nuevo punto de interrupción por número de línea, el Set-PSBreakpoint cmdlet genera un objeto de punto de interrupción de línea (System.Management.Automation.LineBreakpoint) que incluye el identificador de punto de interrupción y el recuento de llamadas.

Ejemplo 2: Establecer un punto de interrupción en una función

En este ejemplo se crea un punto de interrupción de comando en la Increment función del cmdlet Sample.ps1. El script deja de ejecutarse inmediatamente antes de cada llamada a la función especificada.

Set-PSBreakpoint -Command "Increment" -Script "sample.ps1"

Command    : Increment
Action     :
Enabled    : True
HitCount   : 0
Id         : 1
Script     : C:\ps-test\sample.ps1
ScriptName : C:\ps-test\sample.ps1

El resultado es un objeto de punto de interrupción de comando. Antes de que se ejecute el script, el valor de la propiedad HitCount es 0.

Ejemplo 3: Establecer un punto de interrupción en una variable

En este ejemplo se establece un punto de interrupción en la variable Server en el script Sample.ps1. Usa el parámetro Mode con un valor de ReadWrite para detener la ejecución cuando se lee el valor de la variable y justo antes de que cambie el valor.

Set-PSBreakpoint -Script "sample.ps1" -Variable "Server" -Mode ReadWrite

Ejemplo 4: Establecer un punto de interrupción en cada comando que comience con el texto especificado

En este ejemplo se establece un punto de interrupción en todos los comandos del script Sample.ps1 que comienza por "write", como Write-Host.

Set-PSBreakpoint -Script Sample.ps1 -Command "write*"

Ejemplo 5: Establecer un punto de interrupción en función del valor de una variable

En este ejemplo se detiene la ejecución en la DiskTest función del Test.ps1 script solo cuando el valor de la $Disk variable es mayor que 2.

Set-PSBreakpoint -Script "test.ps1" -Command "DiskTest" -Action { if ($Disk -gt 2) { break } }

El valor de Action es un bloque de script que prueba el valor de la $Disk variable en la función.

La acción usa la palabra clave para detener la break ejecución si se cumple la condición. La alternativa (y el valor predeterminado) es Continue.

Ejemplo 6: Establecer un punto de interrupción en una función

En este ejemplo se establece un punto de interrupción en la CheckLog función . Dado que el comando no especifica un script, el punto de interrupción se establece en cualquier cosa que se ejecute en la sesión actual. El depurador se interrumpe cuando se llama a la función, no cuando se declara.

PS> Set-PSBreakpoint -Command "checklog"
Id       : 0
Command  : checklog
Enabled  : True
HitCount : 0
Action   :

function CheckLog {
>> get-eventlog -log Application |
>> where {($_.source -like "TestApp") -and ($_.Message -like "*failed*")}
>>}
>>
PS> Checklog
DEBUG: Hit breakpoint(s)
DEBUG:  Function breakpoint on 'prompt:Checklog'

Ejemplo 7: Establecer puntos de interrupción en varias líneas

En este ejemplo se establecen tres puntos de interrupción de línea en el script Sample.ps1. Establece un punto de interrupción en la columna 2 en cada una de las líneas especificadas en el script. La acción especificada en el parámetro Action se aplica a todos los puntos de interrupción.

PS C:\> Set-PSBreakpoint -Script "sample.ps1" -Line 1, 14, 19 -Column 2 -Action {&(log.ps1)}

Column     : 2
Line       : 1
Action     :
Enabled    : True
HitCount   : 0
Id         : 6
Script     : C:\ps-test\sample.ps1
ScriptName : C:\ps-test\sample.ps1


Column     : 2
Line       : 14
Action     :
Enabled    : True
HitCount   : 0
Id         : 7
Script     : C:\ps-test\sample.ps1
ScriptName : C:\ps-test\sample.ps1


Column     : 2
Line       : 19
Action     :
Enabled    : True
HitCount   : 0
Id         : 8
Script     : C:\ps-test\sample.ps1
ScriptName : C:\ps-test\sample.ps1

Ejemplo 8: Establecer un punto de interrupción en un espacio de ejecución

En este ejemplo, se inicia un trabajo. El espacio de ejecución se almacena en una variable y se pasa al comando Set-PSBreakPoint con el parámetro Runspace.

Start-Job -ScriptBlock {
    Start-Sleep -Seconds 10
}

$runspace = Get-Runspace -Id 1

Set-PSBreakpoint -Command Start-Sleep -Runspace $runspace

Parámetros

-Action

Especifica los comandos que se ejecutan en cada punto de interrupción en lugar de interrumpir. Escriba un bloque de script que contenga los comandos. Puede utilizar este parámetro para establecer puntos de interrupción condicionales o realizar otras tareas, como pruebas o registro.

Si se omite este parámetro o no se especifica ninguna acción, la ejecución se detiene en el punto de interrupción y se inicia el depurador.

Cuando se usa el parámetro Action , el bloque De script de acción se ejecuta en cada punto de interrupción. La ejecución no detendrá a menos que el bloque de script incluya la palabra clave Break. Si utiliza la palabra clave Continue en el bloque de script, la ejecución continúa hasta el siguiente punto de interrupción.

Para obtener más información, consulte about_Script_Blocks, about_Break y about_Continue.

Type:ScriptBlock
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Column

Especifica el número de la columna en el archivo de script en el que se detiene la ejecución. Escriba solo un número de columna. El valor predeterminado es la columna 1.

El valor column se usa con el valor del parámetro Line para especificar el punto de interrupción. Si el parámetro Line especifica varias líneas, el parámetro Column establece un punto de interrupción en la columna especificada en cada una de las líneas especificadas. PowerShell deja de ejecutarse antes de la instrucción o expresión que incluye el carácter en la posición de línea y columna especificadas.

Las columnas se cuentan desde el margen superior izquierdo comenzando por el número de columna 1 (no 0). Si se especifica una columna que no existe en el script, no se declara un error pero el punto de interrupción no se ejecuta nunca.

Type:Int32
Position:2
Default value:1
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Command

Establece un punto de interrupción de comando. Escriba nombres de cmdlet, como Get-Process, o nombres de función. Se permiten los caracteres comodín.

La ejecución se detiene justo antes de que se ejecute cada instancia de cada comando. Si el comando es una función, la ejecución detiene cada vez que se llama a la función y en cada sección BEGIN, PROCESS y END.

Type:String[]
Aliases:C
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:True

-Line

Establece un punto de interrupción de línea en un script. Escriba uno o más números de línea, separados por comas. PowerShell se detiene inmediatamente antes de ejecutar la instrucción que comienza en cada una de las líneas especificadas.

Las líneas se cuentan desde el margen superior izquierdo del archivo de script comenzando por el número de línea 1 (no 0). Si especifica una línea en blanco, la ejecución se detiene antes de la siguiente línea que no esté en blanco. Si la línea está fuera del intervalo, nunca se llama al punto de interrupción.

Type:Int32[]
Position:1
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Mode

Especifica el modo de acceso que desencadena puntos de interrupción variables. El valor predeterminado es Write.

Este parámetro solo es válido cuando se usa el parámetro Variable en el comando . El modo se aplica a todos los puntos de interrupción establecidos en el comando. Los valores permitidos para este parámetro son los siguientes:

  • Escritura : detiene la ejecución inmediatamente antes de escribir un nuevo valor en la variable.
  • Lectura : detiene la ejecución cuando se lee la variable, es decir, cuando se tiene acceso a su valor, ya sea para asignarse, mostrarse o usarse. En modo de lectura, la ejecución no se detiene cuando cambia el valor de la variable.
  • ReadWrite : detiene la ejecución cuando la variable se lee o escribe.
Type:VariableAccessMode
Accepted values:Read, Write, ReadWrite
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Runspace

Especifica el identificador de un objeto Runspace para que pueda interactuar con puntos de interrupción en el espacio de ejecución especificado.

Este parámetro se agregó en PowerShell 7.2.

Type:Runspace
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Script

Especifica una matriz de archivos de script en los que este cmdlet establece un punto de interrupción. Especifique las rutas de acceso y los nombres de uno o más archivos de script. Si los archivos están en el directorio actual, puede omitir la ruta de acceso. Se permiten los caracteres comodín.

De forma predeterminada, se establecen puntos de interrupción de variable y puntos de interrupción de comando en cualquier comando que se ejecute en la sesión actual. Este parámetro es necesario solo cuando se establece un punto de interrupción de línea.

Type:String[]
Position:0
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Variable

Especifica una matriz de variables en las que este cmdlet establece puntos de interrupción. Escriba una lista separada por comas de variables sin signos de dólar ($).

Use el parámetro Mode para determinar el modo de acceso que desencadena los puntos de interrupción. El modo predeterminado, Write, detiene la ejecución justo antes de que se escriba un nuevo valor en la variable.

Type:String[]
Aliases:V
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

Entradas

None

No se pueden canalizar objetos a este cmdlet.

Salidas

CommandBreakpoint

LineBreakpoint

VariableBreakpoint

Set-PSBreakpoint devuelve un objeto que representa cada punto de interrupción que establece.

Notas

PowerShell incluye los siguientes alias para Set-PSBreakpoint:

  • Todas las plataformas:

    • sbp

  • Set-PSBreakpoint no puede establecer un punto de interrupción en un equipo remoto. Para depurar un script en un equipo remoto, copie el script en el equipo local y depúrelo localmente.

  • Cuando se establece un punto de interrupción en más de una línea, comando o variable, Set-PSBreakpoint se genera un objeto de punto de interrupción para cada entrada.

  • Al establecer un punto de interrupción en una función o variable en el símbolo del sistema, puede establecer el punto de interrupción antes o después de crear la función o variable.