Set-PSBreakpoint
Define um ponto de interrupção em uma linha, um comando ou uma variável.
Sintaxe
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 script para o computador local e o depure localmente.
Cada Set-PSBreakpoint
comando cria um dos três tipos de pontos de interrupção a seguir:
- 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 da 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 é interrompida 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 ocorrências.
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 executar 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 do 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 pouco antes de o valor ser alterado.
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 Test.ps1
a DiskTest
execução na 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 interrompe 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 para cada uma das linhas especificada no script. A ação especificada no parâmetro Action se aplica 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 runspace
Neste exemplo, um trabalho é iniciado. O runspace é armazenado em uma variável e transmitido para o comando Set-PSBreakPoint
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 interromper. Insira um bloco de script que contenha os comandos. Você pode usar esse parâmetro para definir pontos de interrupção condicionais ou realizar outras tarefas, como teste ou registro em log.
Se este parâmetro é omitido, ou nenhuma ação é especificada, a execução para no ponto de interrupção e o depurador é iniciado.
Quando o parâmetro Action é usado, o bloco de script Action é executado em cada ponto de interrupção. A execução não é interrompida 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 continua até o próximo ponto de interrupção.
Para obter mais informações, consulte about_Script_Blocks, about_Break e about_Continue.
Tipo: | ScriptBlock |
Cargo: | Named |
Valor padrão: | None |
Obrigatório: | False |
Aceitar a entrada de pipeline: | False |
Aceitar caracteres curinga: | False |
-Column
Especifica o número de coluna da coluna no arquivo de script em que 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 interrompe a execução antes da instrução ou expressão que inclui o caractere na posição especificada da linha e da coluna.
Colunas são contadas a partir da margem superior esquerda começando pela coluna número 1 (não a 0). Se especificar uma coluna que não existe no script, um erro não é declarado, mas o ponto de interrupção não é executado.
Tipo: | Int32 |
Cargo: | 2 |
Valor padrão: | 1 |
Obrigatório: | False |
Aceitar a entrada de pipeline: | False |
Aceitar caracteres curinga: | False |
-Command
Define um ponto de interrupção do comando. Insira nomes de cmdlets, como Get-Process
, ou nomes de funções. Caracteres curinga são permitidos.
A execução para antes que cada instância de cada comando seja executada. Se o comando for uma função, a execução é interrompida toda vez que a função é chamada e a cada seção BEGIN, PROCESS e END.
Tipo: | String[] |
Aliases: | C |
Cargo: | Named |
Valor padrão: | None |
Obrigatório: | True |
Aceitar a entrada de pipeline: | False |
Aceitar caracteres curinga: | True |
-Line
Define um ponto de interrupção em um script. Insira um ou mais números de linha, separados por vírgulas. O PowerShell é interrompido imediatamente antes de executar a instrução que começa em cada uma das linhas especificadas.
Linhas são contadas a partir da margem superior esquerda do arquivo de script começando pela linha número 1 (não a 0). Se especificar uma linha em branco, a execução para antes da próxima linha que não estiver em branco. Se a linha está fora do intervalo, o ponto de interrupção nunca é atingido.
Tipo: | Int32[] |
Cargo: | 1 |
Valor padrão: | None |
Obrigatório: | True |
Aceitar a entrada de pipeline: | False |
Aceitar caracteres curinga: | False |
-Mode
Especifica o modo de acesso que dispara pontos de interrupção variáveis. O padrão é Gravar.
Este parâmetro é válido somente quando o parâmetro Variable é usado no comando. O modo se aplica a todos os pontos de interrupção definidos no comando. Os valores aceitáveis para esse parâmetro são:
- Gravação - Interrompe a execução imediatamente antes que um novo valor seja gravado na variável.
- Leitura - Interrompe a execução quando a variável é lida, ou seja, quando seu valor é acessado, seja para ser atribuído, exibido ou usado. No modo de leitura, a execução não é interrompida quando o valor da variável é alterado.
- ReadWrite - Interrompe a execução quando a variável é lida ou gravada.
Tipo: | VariableAccessMode |
Valores aceitos: | Read, Write, ReadWrite |
Cargo: | Named |
Valor padrão: | None |
Obrigatório: | False |
Aceitar a entrada de pipeline: | False |
Aceitar caracteres curinga: | False |
-Runspace
Especifica a ID de um objeto de Runspace para que você possa interagir com pontos de interrupção no runspace especificado.
Esse parâmetro foi adicionado no PowerShell 7.2.
Tipo: | Runspace |
Cargo: | Named |
Valor padrão: | None |
Obrigatório: | False |
Aceitar a entrada de pipeline: | False |
Aceitar caracteres curinga: | 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 estão no diretório atual, você pode omitir o caminho. Caracteres curinga 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. Esse parâmetro é necessário somente ao definir um ponto de interrupção de linha.
Tipo: | String[] |
Cargo: | 0 |
Valor padrão: | None |
Obrigatório: | False |
Aceitar a entrada de pipeline: | False |
Aceitar caracteres curinga: | 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 dispara os pontos de interrupção. O modo padrão, Write, para a execução imediatamente antes de um novo valor ser gravado na variável.
Tipo: | String[] |
Aliases: | V |
Cargo: | Named |
Valor padrão: | None |
Obrigatório: | True |
Aceitar a entrada de pipeline: | False |
Aceitar caracteres curinga: | False |
Entradas
None
Você não pode canalizar objetos para esse cmdlet.
Saídas
Set-PSBreakpoint
retorna um objeto que representa cada ponto de interrupção que ele define.
Observações
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 script para o computador local e o depure 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 uma função ou variável.