Depurar Funções do Azure PowerShell localmente

O Azure Functions permite que você desenvolva suas funções como scripts do PowerShell.

Você pode depurar suas funções do PowerShell localmente como faria com qualquer script do PowerShell usando as seguintes ferramentas de desenvolvimento padrão:

  • Visual Studio Code: editor de texto gratuito, leve e de software livre da Microsoft com a extensão do PowerShell que oferece uma experiência completa de desenvolvimento do PowerShell.
  • Um console do PowerShell: depurar usando os mesmos comandos que você usaria para depurar qualquer outro processo do PowerShell.

O Azure Functions Core Tools dá suporte à depuração local do Azure Functions, incluindo funções do PowerShell.

Aplicativo de funções de exemplo

O aplicativo de funções usado neste artigo tem uma única função disparada por HTTP e tem os seguintes arquivos:

PSFunctionApp
 | - HttpTriggerFunction
 | | - run.ps1
 | | - function.json
 | - local.settings.json
 | - host.json
 | - profile.ps1

Esse aplicativo de funções é semelhante ao que você obtém ao concluir o início rápido do PowerShell.

O código da função em run.ps1 parece o seguinte script:

param($Request)

$name = $Request.Query.Name

if($name) {
    $status = 200
    $body = "Hello $name"
}
else {
    $status = 400
    $body = "Please pass a name on the query string or in the request body."
}

Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = $status
    Body = $body
})

Definir o ponto de anexação

Para depurar qualquer função do PowerShell, a função precisa parar para que o depurador seja anexado. O Wait-Debugger cmdlet interrompe a execução e aguarda o depurador.

Observação

Ao usar o PowerShell 7, você não precisa adicionar a Wait-Debugger chamada ao código.

Tudo o que você precisa fazer é adicionar uma chamada ao Wait-Debugger cmdlet logo acima da if instrução, da seguinte maneira:

param($Request)

$name = $Request.Query.Name

# This is where we will wait for the debugger to attach
Wait-Debugger

if($name) {
    $status = 200
    $body = "Hello $name"
}
# ...

A depuração começa na instrução if.

Com Wait-Debugger configurado, você já pode depurar as funções usando o Visual Studio Code ou um console do PowerShell.

Depurar no Visual Studio Code

Para depurar suas funções do PowerShell no Visual Studio Code, você deve ter o seguinte instalado:

Depois de instalar essas dependências, carregue um projeto existente do PowerShell Functions ou crie seu primeiro projeto do PowerShell Functions.

Observação

Se o projeto não tiver os arquivos de configuração necessários, você será solicitado a adicioná-los.

Definir a versão do PowerShell

O PowerShell Core é instalado lado a lado com o Windows PowerShell. Defina o PowerShell Core como a versão do PowerShell a ser usada com a extensão do PowerShell para Visual Studio Code.

  1. Pressione F1 para exibir o palete de comando e pesquise por Session.

  2. Escolha PowerShell: Mostrar Menu de Sessão.

  3. Se a Sessão atual não for o PowerShell Core 6, escolha Alternar para: PowerShell Core 6.

Quando você tiver um arquivo do PowerShell aberto, verá a versão exibida em verde na parte inferior direita da janela. Selecionar esse texto também exibe o menu da sessão. Para saber mais, confira a escolha de uma versão do PowerShell a ser usada com a extensão.

Iniciar o aplicativo de funções

Verifique se Wait-Debugger está definido na função onde você deseja conectar o depurador. Com a adição de Wait-Debugger, você pode depurar seu aplicativo de funções usando o Visual Studio Code.

Escolha o painel Depurar e depois anexar à função do PowerShell.

depurador

Você também pode pressionar a tecla F5 para iniciar a depuração.

A operação iniciar depuração realiza as seguintes tarefas:

  • Execute func extensions install no terminal para instalar as extensões do Azure Functions exigidas pelo seu aplicativo de funções.
  • Execute func host start no terminal para iniciar o aplicativo de funções no host do Azure Functions.
  • Anexa o depurador do PowerShell ao runspace do PowerShell dentro do runtime do Functions.

Observação

Você precisa garantir que PSWorkerInProcConcurrencyUpperBound esteja definido como 1 para garantir a experiência de depuração correta no Visual Studio Code. Esse é o padrão.

Com o aplicativo de funções em execução, você precisa de um console separado do PowerShell para chamar a função disparada por HTTP.

Nesse caso, o console do PowerShell é o cliente. O Invoke-RestMethod é usado para disparar a função.

Em um console do PowerShell, execute o seguinte comando:

Invoke-RestMethod "http://localhost:7071/api/HttpTrigger?Name=Functions"

Você observará que uma resposta não é retornada imediatamente. Isso ocorre porque Wait-Debugger anexou o depurador e a execução do PowerShell entrou no modo de interrupção assim que possível. Isso ocorre devido ao conceito breakall, que é explicado posteriormente. Após você pressionar o botão continue, o depurador é interrompido na linha logo após Wait-Debugger.

Nesse ponto, o depurador é anexado e você pode realizar todas as operações normais do depurador. Para obter mais informações sobre como usar o depurador no Visual Studio Code, consulte a documentação oficial.

Depois de continuar e invocar totalmente o script, você observará que:

  • O console do PowerShell que executou o Invoke-RestMethod retornou um resultado
  • O Console Integrado do PowerShell no Visual Studio Code está aguardando a execução de um script

Mais tarde, quando você invoca a mesma função, o depurador na extensão do PowerShell pausa imediatamente após o Wait-Debugger.

Depuração em um Console do PowerShell

Observação

Esta seção pressupõe que você leu os documentos do Azure Functions Core Tools e sabe como usar o func host start comando para iniciar seu aplicativo de funções.

Abra um console no cd diretório do aplicativo de funções e execute o seguinte comando:

func host start

Com o aplicativo de funções em execução e Wait-Debugger no local, você pode anexar ao processo. Você precisa de mais dois consoles do PowerShell.

Um dos consoles atua como o cliente. A partir disso, você chama Invoke-RestMethod para disparar a função. Por exemplo, você pode executar o seguinte código:

Invoke-RestMethod "http://localhost:7071/api/HttpTrigger?Name=Functions"

Você observará que ela não retorna uma resposta, que é um resultado do Wait-Debugger. O runspace do PowerShell está aguardando a anexação de um depurador. Vamos fazer isso.

No outro console do PowerShell, execute o seguinte comando:

Get-PSHostProcessInfo

Esse cmdlet retorna uma tabela parecida com a seguinte saída:

ProcessName ProcessId AppDomainName
----------- --------- -------------
dotnet          49988 None
pwsh            43796 None
pwsh            49970 None
pwsh             3533 None
pwsh            79544 None
pwsh            34881 None
pwsh            32071 None
pwsh            88785 None

Tome nota do ProcessId para o item na tabela com o ProcessName como dotnet. Esse processo é seu aplicativo de funções.

Em seguida, execute o seguinte snippet de código:

# This enters into the Azure Functions PowerShell process.
# Put your value of `ProcessId` here.
Enter-PSHostProcess -Id $ProcessId

# This triggers the debugger.
Debug-Runspace 1

Uma vez iniciado, o depurador é interrompido e mostra algo semelhante à seguinte saída:

Debugging Runspace: Runspace1

To end the debugging session type the 'Detach' command at the debugger prompt, or type 'Ctrl+C' otherwise.

At /Path/To/PSFunctionApp/HttpTriggerFunction/run.ps1:13 char:1
+ if($name) { ...
+ ~~~~~~~~~~~
[DBG]: [Process:49988]: [Runspace1]: PS /Path/To/PSFunctionApp>>

Nesse ponto, você está parado em um ponto de interrupção no depurador do PowerShell. Nele, você pode realizar todas as operações de depuração comuns, contornar, intervir, continuar, encerrar, entre outras. Para ver o conjunto completo de comandos de depuração disponíveis no console, execute o comando h ou o comando ?.

Você também pode definir pontos de interrupção nesse nível com o Set-PSBreakpoint cmdlet.

Depois de continuar e invocar totalmente o script, você observará que:

  • O console do PowerShell em que você executou Invoke-RestMethod agora retornou um resultado.
  • O console do PowerShell em que você executou Debug-Runspace está aguardando a execução de um script.

Você pode invocar a mesma função novamente (usando Invoke-RestMethod , por exemplo) e o depurador interrompe logo após o comando Wait-Debugger.

Considerações sobre a depuração

Tenha em mente os problemas a seguir ao depurar seu código do Functions.

BreakAll pode fazer com que o depurador seja interrompido em um local inesperado

A extensão do PowerShell usa Debug-Runspace, que, por sua vez, depende do recurso BreakAll do PowerShell. Esse recurso instrui o PowerShell a parar no primeiro comando executado. Esse comportamento dá a você a oportunidade de definir pontos de interrupção dentro do runspace depurado.

O runtime do Azure Functions executa alguns comandos antes de realmente invocar o script run.ps1, portanto, é possível que o depurador acabe sendo interrompido dentro do Microsoft.Azure.Functions.PowerShellWorker.psm1 ou Microsoft.Azure.Functions.PowerShellWorker.psd1.

Se essa interrupção acontecer, execute o continue comando ou c para ignorar esse ponto de interrupção. Em seguida, você para no ponto de interrupção esperado.

Resolução de problemas

Caso tenha dificuldades durante a depuração, verifique o seguinte:

Verificação Ação
Execute func --version no terminal. Se você receber um erro que func não pode ser encontrado, as Ferramentas Principais (func.exe) podem estar ausentes da variável local path . Reinstalar o Core Tools.
No Visual Studio Code, o terminal padrão precisa ter acesso ao func.exe. Verifique se você não está usando um terminal padrão que não tem as Ferramentas Principais instaladas, como o Subsistema do Windows para Linux (WSL). Defina o shell padrão no Visual Studio Code como PowerShell 7 (recomendado) ou Windows PowerShell 5.1.

Próximas etapas

Para saber mais sobre como desenvolver funções usando o PowerShell, consulte o guia de desenvolvedor do PowerShell do Azure Functions.

  • Last updated on