Partilhar via

Set-PSBreakpoint

  • Referência
Módulo:
Microsoft.PowerShell.Utility

Define um ponto de interrupção em uma linha, comando ou variável.

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

O Set-PSBreakpoint cmdlet define um ponto de interrupção em um script ou em qualquer comando executado na sessão atual. Você pode usar Set-PSBreakpoint para definir um ponto de interrupção antes de executar um script ou executar um comando, ou durante a depuração, quando parado em outro ponto de interrupção.

Set-PSBreakpoint Não é possível definir um ponto de interrupção em um computador remoto. Para depurar um script em um computador remoto, copie-o para o computador local e, em seguida, depure-o localmente.

Cada Set-PSBreakpoint comando cria um dos seguintes três tipos de pontos de interrupção:

  • Ponto de interrupção de linha - Define pontos de interrupção em coordenadas específicas de linha e coluna.
  • Ponto de interrupção de comando - Define pontos de interrupção em comandos e funções.
  • Ponto de interrupção variável - Define pontos de interrupção em variáveis.

Você pode definir um ponto de interrupção em várias linhas, comandos ou variáveis em um único Set-PSBreakpoint comando, mas cada Set-PSBreakpoint comando define apenas um tipo de ponto de interrupção.

Em um ponto de interrupção, o PowerShell interrompe temporariamente a execução e dá controle ao depurador. O prompt de comando muda para DBG\>, e um conjunto de comandos do depurador fica disponível para uso. No entanto, você pode usar o parâmetro Action para especificar uma resposta alternativa, como condições para o ponto de interrupção ou instruções para executar tarefas adicionais, como registro em log ou diagnóstico.

O Set-PSBreakpoint cmdlet é um dos vários cmdlets projetados para depurar scripts do PowerShell. Para obter mais informações sobre o depurador do PowerShell, consulte about_Debuggers.

Exemplos

Exemplo 1: Definir um ponto de interrupção em uma linha

Este exemplo define um ponto de interrupção na linha 5 no script Sample.ps1. Quando o script é executado, a execução para imediatamente antes da execução da linha 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

Quando você define um novo ponto de interrupção por número de linha, o Set-PSBreakpoint cmdlet gera um objeto de ponto de interrupção de linha (System.Management.Automation.LineBreakpoint) que inclui a ID do ponto de interrupção e a contagem de acertos.

Exemplo 2: Definir um ponto de interrupção em uma função

Este exemplo cria um ponto de interrupção de Increment comando na função no cmdlet Sample.ps1. O script para de ser executado imediatamente antes de cada chamada para a função 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

O resultado é um objeto de ponto de interrupção de comando. Antes da execução do script, o valor da propriedade HitCount é 0.

Exemplo 3: Definir um ponto de interrupção em uma variável

Este exemplo define um ponto de interrupção na variável Server no script Sample.ps1. Ele usa o parâmetro Mode com um valor de ReadWrite para interromper a execução quando o valor da variável é lido e imediatamente antes do valor mudar.

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

Exemplo 4: Definir um ponto de interrupção em cada comando que começa com o texto especificado

Este exemplo define um ponto de interrupção em cada comando no script Sample.ps1 que começa com "write", como Write-Host.

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

Exemplo 5: Definir um ponto de interrupção dependendo do valor de uma variável

Este exemplo interrompe a Test.ps1 execução na DiskTest função no script somente quando o valor da $Disk variável é maior que 2.

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

O valor da Ação é um bloco de script que testa o $Disk valor da variável na função.

A ação usa a break palavra-chave para interromper a execução se a condição for atendida. A alternativa (e o padrão) é Continuar.

Exemplo 6: Definir um ponto de interrupção em uma função

Este exemplo define um ponto de interrupção na CheckLog função. Como o comando não especifica um script, o ponto de interrupção é definido em qualquer coisa que seja executada na sessão atual. O depurador quebra quando a função é chamada, não quando é declarada.

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'

Exemplo 7: Definir pontos de interrupção em várias linhas

Este exemplo define três pontos de interrupção de linha no script Sample.ps1. Ele define um ponto de interrupção na coluna 2 em cada uma das linhas especificadas no script. A ação especificada no parâmetro Action aplica-se a todos os pontos de interrupção.

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

Exemplo 8: Definir um ponto de interrupção em um espaço de execução

Neste exemplo, um trabalho é iniciado. O runspace é armazenado em uma variável e passado para o Set-PSBreakPoint comando com o 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 comandos que são executados em cada ponto de interrupção em vez de quebra. Insira um bloco de script que contenha os comandos. Você pode usar esse parâmetro para definir pontos de interrupção condicionais ou para executar outras tarefas, como teste ou registro.

Se esse parâmetro for omitido ou nenhuma ação for especificada, a execução será interrompida no ponto de interrupção e o depurador será iniciado.

Quando o parâmetro Action é usado, o bloco de script Action é executado em cada ponto de interrupção. A execução não para a menos que o bloco de script inclua a palavra-chave Break. Se você usar a palavra-chave Continue no bloco de script, a execução será retomada até o próximo ponto de interrupção.

Para obter mais informações, consulte about_Script_Blocks, about_Break e about_Continue.

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

-Column

Especifica o número da coluna no arquivo de script no qual a execução é interrompida. Insira apenas um número de coluna. O padrão é a coluna 1.

O valor Column é usado com o valor do parâmetro Line para especificar o ponto de interrupção. Se o parâmetro Line especificar várias linhas, o parâmetro Column definirá um ponto de interrupção na coluna especificada em cada uma das linhas especificadas. O PowerShell para de executar antes da instrução ou expressão que inclui o caractere na posição de linha e coluna especificada.

As colunas são contadas a partir da margem superior esquerda, começando com a coluna número 1 (não 0). Se você especificar uma coluna que não existe no script, um erro não será declarado, mas o ponto de interrupção nunca será executado.

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

-Command

Define um ponto de interrupção de comando. Insira nomes de cmdlets, como Get-Process, ou nomes de funções. Curingas são permitidos.

A execução para pouco antes de cada instância de cada comando ser executada. Se o comando for uma função, a execução será interrompida sempre que a função for chamada e em cada seção BEGIN, PROCESS e END.

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

-Line

Define um ponto de interrupção de linha em um script. Insira um ou mais números de linha, separados por vírgulas. O PowerShell para imediatamente antes de executar a instrução que começa em cada uma das linhas especificadas.

As linhas são contadas a partir da margem superior esquerda do arquivo de script começando com o número de linha 1 (não 0). Se você especificar uma linha em branco, a execução será interrompida antes da próxima linha não vazia. Se a linha estiver fora do intervalo, o ponto de interrupção nunca será atingido.

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

-Mode

Especifica o modo de acesso que aciona pontos de interrupção variáveis. O padrão é Write.

Este parâmetro é válido somente quando o parâmetro Variable é usado no comando. O modo aplica-se a todos os pontos de interrupção definidos no comando. Os valores aceitáveis para este parâmetro são:

  • Write - Interrompe a execução imediatamente antes de um novo valor ser gravado na variável.
  • Leitura - Interrompe a execução quando a variável é lida, ou seja, quando seu valor é acessado, para ser atribuído, exibido ou usado. No modo de leitura, a execução não para quando o valor da variável muda.
  • ReadWrite - Interrompe a execução quando a variável é lida ou gravada.
Type:VariableAccessMode
Accepted values:Read, Write, ReadWrite
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Runspace

Especifica a Id de um objeto Runspace para que você possa interagir com pontos de interrupção no espaço de execução especificado.

Esse parâmetro foi adicionado no PowerShell 7.2.

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

-Script

Especifica uma matriz de arquivos de script na qual esse cmdlet define um ponto de interrupção. Insira os caminhos e nomes de arquivo de um ou mais arquivos de script. Se os arquivos estiverem no diretório atual, você poderá omitir o caminho. Curingas são permitidos.

Por padrão, os pontos de interrupção variáveis e os pontos de interrupção de comando são definidos em qualquer comando executado na sessão atual. Este parâmetro é necessário somente ao definir um ponto de interrupção de linha.

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

-Variable

Especifica uma matriz de variáveis nas quais esse cmdlet define pontos de interrupção. Insira uma lista separada por vírgulas de variáveis sem cifrões ($).

Use o parâmetro Mode para determinar o modo de acesso que aciona os pontos de interrupção. O modo padrão, Write, interrompe a execução imediatamente antes de um novo valor ser gravado na variável.

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

Entradas

None

Não é possível canalizar objetos para este cmdlet.

Saídas

CommandBreakpoint

LineBreakpoint

VariableBreakpoint

Set-PSBreakpoint Retorna um objeto que representa cada ponto de interrupção definido.

Notas

O PowerShell inclui os seguintes aliases para Set-PSBreakpoint:

  • Todas as plataformas:

    • sbp

  • Set-PSBreakpoint Não é possível definir um ponto de interrupção em um computador remoto. Para depurar um script em um computador remoto, copie-o para o computador local e, em seguida, depure-o localmente.

  • Quando você define um ponto de interrupção em mais de uma linha, comando ou variável, Set-PSBreakpoint gera um objeto de ponto de interrupção para cada entrada.

  • Ao definir um ponto de interrupção em uma função ou variável no prompt de comando, você pode definir o ponto de interrupção antes ou depois de criar a função ou variável.