Lokales Debuggen von PowerShell-Azure-Funktionen

Mit Azure Functions können Sie Ihre Funktionen als PowerShell-Skripts entwickeln.

Sie können Ihre PowerShell-Funktionen lokal wie alle PowerShell-Skripts mithilfe der folgenden Standardentwicklungstools debuggen:

  • Visual Studio Code: Der kostenlose, einfache und open-Source-Text-Editor von Microsoft mit der PowerShell-Erweiterung, die eine vollständige PowerShell-Entwicklungsumgebung bietet.
  • Eine PowerShell-Konsole: Debuggen Sie mit denselben Befehlen, die Sie zum Debuggen anderer PowerShell-Prozesse verwenden würden.

Azure Functions Core Tools unterstützt das lokale Debuggen von Azure-Funktionen, einschließlich PowerShell-Funktionen.

Beispielfunktions-App

Die in diesem Artikel verwendete Funktions-App verfügt über eine einzelne ausgelöste HTTP-Funktion und verfügt über die folgenden Dateien:

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

Diese Funktions-App ähnelt der, die Sie erhalten, wenn Sie die PowerShell-Schnellstartanleitung abschließen.

Der Funktionscode in run.ps1 sieht wie das folgende Skript aus:

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

Anfügepunkt festlegen

Zum Debuggen einer beliebigen PowerShell-Funktion muss die Funktion angehalten werden, damit der Debugger angefügt wird. Das Wait-Debugger Cmdlet beendet die Ausführung und wartet auf den Debugger.

Hinweis

Bei Verwendung von PowerShell 7 müssen Sie den Wait-Debugger Aufruf nicht in Ihrem Code hinzufügen.

Alles, was Sie tun müssen, ist, einen Aufruf des Wait-Debugger-Cmdlets direkt oberhalb der if-Anweisung einzufügen, wie folgt:

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"
}
# ...

Das Debuggen beginnt mit der if Anweisung.

Mit Wait-Debugger an Ort und Stelle können Sie jetzt die Funktionen mithilfe von Visual Studio Code oder einer PowerShell-Konsole debuggen.

Debuggen in Visual Studio Code

Um Ihre PowerShell-Funktionen in Visual Studio Code zu debuggen, müssen Sie folgendes installiert haben:

Laden Sie nach der Installation dieser Abhängigkeiten ein vorhandenes PowerShell-Funktionen-Projekt, oder erstellen Sie Ihr erstes PowerShell-Funktionen-Projekt.

Hinweis

Wenn Ihr Projekt nicht über die erforderlichen Konfigurationsdateien verfügt, werden Sie aufgefordert, sie hinzuzufügen.

Festlegen der PowerShell-Version

PowerShell Core wird parallel mit Windows PowerShell installiert. Legen Sie PowerShell Core als PowerShell-Version fest, die mit der PowerShell-Erweiterung für Visual Studio Code verwendet werden soll.

  1. Drücken Sie F1, um die Befehlspalette anzuzeigen, und suchen Sie dann nach Session.

  2. Wählen Sie PowerShell aus: Sitzungsmenü anzeigen.

  3. Wenn Ihre aktuelle Sitzung nicht PowerShell Core 6 ist, wählen Sie Zu PowerShell Core 6 wechseln.

Wenn eine PowerShell-Datei geöffnet ist, wird die version grün unten rechts im Fenster angezeigt. Wenn Sie diesen Text auswählen, wird auch das Sitzungsmenü angezeigt. Weitere Informationen finden Sie in der Auswahl einer PowerShell-Version, die mit der Erweiterung verwendet werden soll.

Starten der Funktions-App

Stellen Sie sicher, dass Wait-Debugger in der Funktion gesetzt ist, an der Sie den Debugger anfügen möchten. Mit Wait-Debugger können Sie Ihre Funktions-App mit Visual Studio Code debuggen.

Wählen Sie den Debugbereich aus, und fügen Sie dann die PowerShell-Funktion an.

Debugger

Sie können auch F5 drücken, um mit dem Debuggen zu beginnen.

Der Startdebuggingvorgang führt die folgenden Aufgaben aus:

  • Führen Sie func extensions install im Terminal aus, um alle Azure Functions-Erweiterungen zu installieren, die von Ihrer Funktions-App benötigt werden.
  • Führen Sie func host start im Terminal aus, um die Funktions-App im Functions-Host zu starten.
  • Fügen Sie den PowerShell-Debugger an den PowerShell-Runspace innerhalb der Functions-Laufzeitumgebung an.

Hinweis

Sie müssen sicherstellen, dass PSWorkerInProcConcurrencyUpperBound auf 1 festgelegt ist, um die korrekte Debugerfahrung in Visual Studio Code sicherzustellen. Dies ist die Standardeinstellung.

Wenn Ihre Funktions-App ausgeführt wird, benötigen Sie eine separate PowerShell-Konsole, um die ausgelöste HTTP-Funktion aufzurufen.

In diesem Fall ist die PowerShell-Konsole der Client. Die Invoke-RestMethod Funktion wird verwendet, um die Funktion auszulösen.

Führen Sie in einer PowerShell-Konsole den folgenden Befehl aus:

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

Sie werden feststellen, dass eine Antwort nicht sofort zurückgegeben wird. Der Grund dafür ist, dass Wait-Debugger den Debugger angefügt hat und dass die PowerShell-Ausführung in den Unterbrechungsmodus (break) gewechselt ist, sobald sie konnte. Dies liegt an dem Konzept breakAll, das später erläutert wird. Nachdem Sie die Schaltfläche continue gedrückt haben, unterbricht der Debugger in der Zeile direkt hinter Wait-Debugger.

An diesem Punkt ist der Debugger angefügt, und Sie können alle normalen Debuggervorgänge ausführen. Weitere Informationen zur Verwendung des Debuggers in Visual Studio Code finden Sie in der offiziellen Dokumentation.

Nachdem Sie das Skript fortgesetzt und vollständig aufgerufen haben, werden Sie feststellen, dass:

  • Die PowerShell-Konsole, die Invoke-RestMethod ausgeführt hat, hat ein Ergebnis zurückgegeben.
  • Die integrierte PowerShell-Konsole in Visual Studio Code wartet auf die Ausführung eines Skripts.

Bei nachfolgenden Aufrufen derselben Funktion unterbricht der Debugger in der PowerShell-Erweiterung direkt nach Wait-Debugger.

Debuggen in einer PowerShell-Konsole

Hinweis

In diesem Abschnitt wird davon ausgegangen, dass Sie die Dokumentation zu Azure Functions Core Tools gelesen haben und wissen, wie Sie den func host start Befehl zum Starten Ihrer Funktions-App verwenden.

Öffnen Sie eine Konsole, wechseln Sie mittels cd in das Verzeichnis Ihrer Funktions-App, und führen Sie den folgenden Befehl aus:

func host start

Mit der in Ausführung befindlichen Funktions-App und bei eingefügtem Wait-Debugger können Sie an den Prozess anfügen. Sie benötigen zwei weitere PowerShell-Konsolen.

Eine der Konsolen fungiert als Client. Sie rufen Invoke-RestMethod auf, um die Funktion auszulösen. Sie können beispielsweise den folgenden Befehl ausführen:

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

Sie werden feststellen, dass es keine Antwort liefert, was auf Wait-Debugger zurückzuführen ist. Der PowerShell-Runspace wartet nun darauf, dass ein Debugger angefügt wird. Fügen wir ihn also an.

Führen Sie in der anderen PowerShell-Konsole den folgenden Befehl aus:

Get-PSHostProcessInfo

Dieses Cmdlet gibt eine Tabelle zurück, die wie die folgende Ausgabe aussieht:

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

Notieren Sie sich die ProcessId für das Element in der Tabelle mit dem ProcessName als dotnet. Dieser Prozess ist Ihre Funktions-App.

Führen Sie als Nächstes den folgenden Codeausschnitt aus:

# 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

Nach dem Starten unterbricht der Debugger und zeigt ungefähr die folgende Ausgabe an:

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

Zu diesem Zeitpunkt halten Sie an einem Breakpoint (Unterbrechungspunkt) im PowerShell-Debugger. Von hier aus können Sie alle üblichen Debugvorgänge ausführen, also Prozedurschritt, schrittweises Ausführen, Fortfahren, Beenden und andere. Um den vollständigen Satz von Debugbefehlen anzuzeigen, die in der Konsole verfügbar sind, führen Sie die Befehle h oder ? aus.

Sie können haltepunkte auch auf dieser Ebene mit dem Set-PSBreakpoint Cmdlet festlegen.

Nachdem Sie ihr Skript fortgesetzt und vollständig aufgerufen haben, werden Sie folgendes feststellen:

  • Die PowerShell-Konsole, in der Sie ausgeführt Invoke-RestMethod haben, hat nun ein Ergebnis zurückgegeben.
  • Die PowerShell-Konsole, in der Sie ausgeführt Debug-Runspace haben, wartet auf die Ausführung eines Skripts.

Sie können dieselbe Funktion erneut aufrufen (z. B. mithilfe von Invoke-RestMethod), und der Debugger unterbricht unmittelbar hinter dem Befehl Wait-Debugger.

Überlegungen zum Debuggen

Beachten Sie beim Debuggen des Funktionscodes die folgenden Probleme.

BreakAll kann dazu führen, dass der Debugger an unerwarteter Stelle unterbrochen wird.

Die PowerShell-Erweiterung verwendet Debug-Runspace, was wiederum auf das Feature von BreakAll PowerShell basiert. Diese Funktion weist PowerShell an, beim ersten ausgeführten Befehl anzuhalten. Dieses Verhalten bietet Ihnen die Möglichkeit, Haltepunkte innerhalb des Debug-Runspaces festzulegen.

Die Azure Functions Runtime führt ein paar Befehle vor dem tatsächlichen Aufrufen Ihres run.ps1-Skripts aus, sodass dies dazu führen kann, dass der Debugger innerhalb von Microsoft.Azure.Functions.PowerShellWorker.psm1 oder Microsoft.Azure.Functions.PowerShellWorker.psd1 unterbricht.

Sollte dieser Break passieren, führen Sie den continue- oder c-Befehl aus, um diesen Breakpunkt zu überspringen. Sie halten dann am erwarteten Haltepunkt an.

Problembehandlung

Wenn Beim Debuggen Schwierigkeiten auftreten, sollten Sie folgendes überprüfen:

Prüfen Maßnahme
Führen Sie func --version im Terminal aus. Wenn Sie einen Fehler erhalten, dass func nicht gefunden werden kann, fehlen möglicherweise Core Tools (func.exe) in der lokalen path Variablen. Installieren Sie Core Tools neu.
In Visual Studio Code muss das Standardterminal Zugriff auf func.exehaben. Stellen Sie sicher, dass Sie kein Standardterminal verwenden, auf dem keine Core Tools installiert sind, z. B. Windows-Subsystem für Linux (WSL). Legen Sie die Standardshell in Visual Studio Code entweder auf PowerShell 7 (empfohlen) oder Windows PowerShell 5.1 fest.

Nächste Schritte

Weitere Informationen zum Entwickeln von Funktionen mithilfe von PowerShell finden Sie im Entwicklerhandbuch zu Azure Functions PowerShell.

  • Last updated on