Depurar o PowerShell Funções do Azure localmente

  • Artigo

Funções do Azure permite-lhe desenvolver as suas funções como scripts do PowerShell.

Pode depurar as suas funções do PowerShell localmente, tal como faria com os scripts do PowerShell com as seguintes ferramentas de desenvolvimento padrão:

  • Visual Studio Code: editor de texto gratuito, leve e open source da Microsoft com a extensão do PowerShell que oferece uma experiência de desenvolvimento completa do PowerShell.
  • Uma consola do PowerShell: depurar com os mesmos comandos que utilizaria para depurar qualquer outro processo do PowerShell.

Funções do Azure Ferramentas Principais suporta a depuração local de Funções do Azure, incluindo as funções do PowerShell.

Aplicação de funções de exemplo

A aplicação de funções utilizada neste artigo tem uma única função acionada por HTTP e tem os seguintes ficheiros:

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

Esta aplicação de funções é semelhante à que obtém quando conclui o início rápido do PowerShell.

O código de função no run.ps1 tem o seguinte aspeto:

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 tem de parar para que o depurador seja anexado. O Wait-Debugger cmdlet para a execução e aguarda pelo depurador.

Nota

Ao utilizar o PowerShell 7, não precisa de adicionar a Wait-Debugger chamada no seu código.

Tudo o que precisa de fazer é adicionar uma chamada ao Wait-Debugger cmdlet imediatamente acima da instrução, da if seguinte forma:

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 .

Agora Wait-Debugger , pode depurar as funções com o Visual Studio Code ou uma consola do PowerShell.

Depurar no Visual Studio Code

Para depurar as funções do PowerShell no Visual Studio Code, tem de ter o seguinte instalado:

Depois de instalar estas dependências, carregue um projeto de Funções do PowerShell existente ou crie o seu primeiro projeto de Funções do PowerShell.

Nota

Se o seu projeto não tiver os ficheiros de configuração necessários, ser-lhe-á pedido que os adicione.

Definir a versão do PowerShell

O PowerShell Core instala-se lado a lado com Windows PowerShell. Defina o PowerShell Core como a versão do PowerShell para utilizar com a extensão do PowerShell para o Visual Studio Code.

  1. Prima F1 para apresentar a palete de comando e, em seguida, procure Session.

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

  3. Se a sessão Atual não for o PowerShell Core 6, selecione Mudar para: PowerShell Core 6.

Quando tem um ficheiro do PowerShell aberto, verá a versão apresentada a verde na parte inferior direita da janela. Selecionar este texto também apresenta o menu de sessão. Para saber mais, veja Escolher uma versão do PowerShell para utilizar com a extensão.

Iniciar a aplicação de funções

Verifique se Wait-Debugger está definido na função onde pretende anexar o depurador. Com Wait-Debugger a adição, pode depurar a sua aplicação de funções com o Visual Studio Code.

Selecione o painel Depuração e, em seguida , a função Anexar ao PowerShell.

depurador

Também pode premir a tecla F5 para iniciar a depuração.

A operação iniciar a depuração faz as seguintes tarefas:

  • É executado func extensions install no terminal para instalar quaisquer extensões de Funções do Azure necessárias pela sua aplicação de funções.
  • É executado func host start no terminal para iniciar a aplicação de funções no anfitrião funções.
  • Anexe o depurador do PowerShell à área de execução do PowerShell no runtime das Funções.

Nota

Tem de garantir que PSWorkerInProcConcurrencyUpperBound está definido como 1 para garantir uma experiência de depuração correta no Visual Studio Code. Esta é a predefinição.

Com a aplicação de funções em execução, precisa de uma consola do PowerShell separada para chamar a função acionada por HTTP.

Neste caso, a consola do PowerShell é o cliente. O Invoke-RestMethod é utilizado para acionar a função.

Numa consola do PowerShell, execute o seguinte comando:

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

Irá reparar que uma resposta não é devolvida imediatamente. Isto porque Wait-Debugger ligou o depurador e a execução do PowerShell entrou em modo de interrupção assim que pôde. Isto deve-se ao conceito BreakAll, que é explicado mais tarde. Depois de premir o continue botão, o depurador quebra-se na linha logo a seguir Wait-Debuggera .

Neste momento, o depurador está anexado e pode efetuar todas as operações normais de depurador. Para obter mais informações sobre como utilizar o depurador no Visual Studio Code, veja a documentação oficial.

Depois de continuar e invocar totalmente o script, irá reparar que:

  • A consola do PowerShell que devolveu Invoke-RestMethod um resultado
  • A Consola Integrada do PowerShell no Visual Studio Code está à espera que seja executado um script

Mais tarde, quando invocar a mesma função, o depurador na extensão do PowerShell é incorrido logo após o Wait-Debugger.

Depuração numa Consola do PowerShell

Nota

Esta secção pressupõe que leu os documentos do Funções do Azure Core Tools e sabe como utilizar o func host start comando para iniciar a sua aplicação de funções.

Abra uma consola, cd no diretório da sua aplicação de funções e execute o seguinte comando:

func host start

Com a aplicação de funções em execução e a Wait-Debugger implementada, pode anexar ao processo. Precisa de mais duas consolas do PowerShell.

Uma das consolas funciona como cliente. A partir daí, chama Invoke-RestMethod para acionar a função. Por exemplo, pode executar o seguinte comando:

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

Irá reparar que não devolve uma resposta, que é o resultado do Wait-Debugger. O runspace do PowerShell está agora à espera que seja anexado um depurador. Vamos anexar isto.

Na outra consola do PowerShell, execute o seguinte comando:

Get-PSHostProcessInfo

Este cmdlet devolve uma tabela semelhante à 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

Anote o para o ProcessId item na tabela com o ProcessName como dotnet. Este processo é a sua aplicação de funções.

Em seguida, execute o seguinte fragmento:

# 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 quebra e mostra algo semelhante ao seguinte resultado:

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>>

Neste momento, está parado num ponto de interrupção no depurador do PowerShell. A partir daqui, pode realizar todas as operações de depuração habituais, avançar, avançar, continuar, sair e outras pessoas. Para ver o conjunto completo de comandos de depuração disponíveis na consola, execute os h comandos ou ? .

Também pode definir pontos de interrupção a este nível com o Set-PSBreakpoint cmdlet.

Assim que continuar e invocar totalmente o script, irá reparar que:

  • A consola do PowerShell onde executou Invoke-RestMethod devolveu agora um resultado.
  • A consola do PowerShell onde executou Debug-Runspace está à espera que um script seja executado.

Pode invocar a mesma função novamente (por Invoke-RestMethod exemplo) e o depurador é ativado imediatamente após o Wait-Debugger comando.

Considerações sobre a depuração

Tenha em atenção os seguintes problemas ao depurar o código das Funções.

BreakAll pode fazer com que o depurador se quebre num local inesperado

A extensão do PowerShell utiliza Debug-Runspace, que por sua vez depende da funcionalidade do BreakAll PowerShell. Esta funcionalidade indica ao PowerShell para parar no primeiro comando que é executado. Este comportamento dá-lhe a oportunidade de definir pontos de interrupção dentro da área de execução depurada.

O Funções do Azure runtime executa alguns comandos antes de invocar o scriptrun.ps1, pelo que é possível que o depurador acabe por se partir dentro do Microsoft.Azure.Functions.PowerShellWorker.psm1 ou Microsoft.Azure.Functions.PowerShellWorker.psd1.

Se esta interrupção ocorrer, execute o continue comando ou c para ignorar este ponto de interrupção. Em seguida, pare no ponto de interrupção esperado.

Resolução de problemas

Se tiver dificuldades durante a depuração, deve verificar o seguinte:

Marcar Ação
Execute func --version a partir do terminal. Se receber um erro que func não pode ser encontrado, as Ferramentas Principais (func.exe) poderão estar em falta na variável local path . Reinstale as Ferramentas Principais.
No Visual Studio Code, o terminal predefinido tem de ter acesso a func.exe. Certifique-se de que não está a utilizar um terminal predefinido que não tenha as Ferramentas Principais instaladas, como Subsistema Windows para Linux (WSL). Defina a shell predefinida no Visual Studio Code como PowerShell 7 (recomendado) ou Windows PowerShell 5.1.

Passos seguintes

Para saber mais sobre como desenvolver Funções com o PowerShell, veja Funções do Azure guia para programadores do PowerShell.