Freigeben über

PowerShell-Entwicklerhandbuch für Azure Functions

  • Artikel

Dieser Artikel enthält Informationen zum Schreiben von Funktionen in Azure Functions mithilfe von PowerShell.

Eine PowerShell-Azure-Funktion (Funktion) wird als ein PowerShell-Skript dargestellt, das durch Auslösen ausgeführt wird. Jedes Funktionsskript verfügt über eine zugehörige Datei function.json, in der definiert ist, wie sich die Funktion verhält, also z. B. wie sie ausgelöst wird und welche Ein- und Ausgabeparameter verwendet werden. Weitere Informationen finden Sie im Artikel zu Triggern und Bindungen.

Wie andere Arten von Funktionen akzeptieren PowerShell-Skriptfunktionen Parameter, die den Namen aller Eingabebindungen entsprechen, die in der Datei function.json definiert sind. Ein TriggerMetadata-Parameter wird ebenfalls übergeben. Dieser enthält zusätzliche Informationen zu dem Trigger, der die Funktion gestartet hat.

In diesem Artikel wird davon ausgegangen, dass Sie bereits die Entwicklerreferenz zu Azure Functionsgelesen haben. Außerdem wird davon ausgegangen, dass Sie den Schnellstart für Functions und PowerShell abgeschlossen haben, in dem Sie Ihre erste PowerShell-Funktion erstellen.

Ordnerstruktur

Die erforderlichen Ordnerstruktur für ein PowerShell-Projekt sieht folgendermaßen aus. Diese Standardeinstellung kann geändert werden. Weitere Informationen finden Sie im Abschnitt zu scriptFile.

PSFunctionApp
 | - MyFirstFunction
 | | - run.ps1
 | | - function.json
 | - MySecondFunction
 | | - run.ps1
 | | - function.json
 | - Modules
 | | - myFirstHelperModule
 | | | - myFirstHelperModule.psd1
 | | | - myFirstHelperModule.psm1
 | | - mySecondHelperModule
 | | | - mySecondHelperModule.psd1
 | | | - mySecondHelperModule.psm1
 | - local.settings.json
 | - host.json
 | - requirements.psd1
 | - profile.ps1
 | - extensions.csproj
 | - bin

Im Stammverzeichnis des Projekts befindet sich eine freigegebene Datei host.json, die zum Konfigurieren der Funktions-App verwendet werden kann. Jede Funktion verfügt über einen Ordner mit einer eigenen Codedatei (PS1-Datei) und Bindungskonfigurationsdatei (function.json). Der Name des übergeordneten Verzeichnisses der Datei „function.json“ ist immer der Name Ihrer Funktion.

Bestimmte Bindungen erfordern das Vorhandensein einer Datei mit dem Namen extensions.csproj. Die in Version 2.x oder höher der Functions-Runtime erforderlichen Bindungserweiterungen sind in der Datei extensions.csproj definiert, die eigentlichen Bibliotheksdateien befinden sich im Ordner bin. Wenn Sie lokal entwickeln, müssen Sie Bindungserweiterungen registrieren. Wenn Sie Funktionen im Azure-Portal entwickeln, wird diese Registrierung für Sie ausgeführt.

PowerShell-Funktions-Apps enthalten möglicherweise optional eine Datei profile.ps1, die ausgeführt wird, wenn eine Funktions-App gestartet wird (auch als Kaltstart bezeichnet). Weitere Informationen finden Sie unter PowerShell-Profil.

Definieren eines PowerShell-Skripts als Funktion

Standardmäßig sucht die Functions-Runtime in run.ps1 nach Ihrer Funktion, wobei sich run.ps1 im gleichen übergeordneten Verzeichnis befindet wie die entsprechende Datei function.json.

An das Skript werden bei der Ausführung mehrere Argumente übergeben. Um diese Parameter zu behandeln, fügen Sie oben im Skript einen param-Block hinzu wie im folgenden Beispiel gezeigt:

# $TriggerMetadata is optional here. If you don't need it, you can safely remove it from the param block
param($MyFirstInputBinding, $MySecondInputBinding, $TriggerMetadata)

TriggerMetadata-Parameter

Der TriggerMetadata-Parameter wird verwendet, um zusätzliche Informationen zum Trigger anzugeben. Diese Metadaten variieren von Bindung zu Bindung, sie enthalten aber alle eine sys-Eigenschaft mit den folgenden Daten:

$TriggerMetadata.sys
Eigenschaft Beschreibung des Dataflows type
UtcNow Zeitpunkt der Auslösung der Funktion in UTC Datetime
MethodName Der Name der Funktion, die ausgelöst wurde Zeichenfolge
RandGuid Eine eindeutige GUID für diese Ausführung der Funktion Zeichenfolge

Jeder Triggertyp verfügt über einen anderen Satz von Metadaten. Die $TriggerMetadata für QueueTrigger enthalten neben anderen Informationen z. B. Werte für InsertionTime, Id und DequeueCount. Weitere Informationen zu den Metadaten von Warteschlangentriggern finden Sie in der offiziellen Dokumentation zu Warteschlangentriggern. Sehen Sie in der Dokumentation zu den von Ihnen verwendeten Triggern nach, welche Informationen in den Metadaten der Trigger enthalten sind.

Bindungen

In PowerShell werden Bindungen in der Datei „function.json“ einer Funktion konfiguriert und definiert. Funktionen interagieren auf verschiedene Weise mit Bindungen.

Lesen von Triggern und Eingabedaten

Die Trigger und Eingabebindungen werden als Parameter an die Funktion übergeben. Bei Eingabebindungen ist in „function.json“ für direction die Richtung in angegeben. Die in function.json definierte name-Eigenschaft stellt den Namen des Parameters im param-Block dar. Da PowerShell benannte Parameter für die Bindung verwendet, spielt die Reihenfolge der Parameter keine Rolle. Es hat sich jedoch bewährt, die Reihenfolge der Bindungen zu verwenden, die in der Datei function.json festgelegt ist.

param($MyFirstInputBinding, $MySecondInputBinding)

Schreiben von Ausgabedaten

In Functions ist bei einer Ausgabebindung die direction in der Datei „functions.json“ auf out festgelegt. Sie können mit dem Cmdlet Push-OutputBinding, das in der Functions-Runtime verfügbar ist, in eine Ausgabebindung schreiben. In allen Fällen entspricht die name-Eigenschaft der Bindung gemäß der Definition in function.json dem Name-Parameter des Cmdlets Push-OutputBinding.

Das folgende Beispiel zeigt, wie Sie Push-OutputBinding in Ihrem Funktionsskript aufrufen:

param($MyFirstInputBinding, $MySecondInputBinding)

Push-OutputBinding -Name myQueue -Value $myValue

Sie können über die Pipeline auch einen Wert für eine bestimmte Bindung übergeben.

param($MyFirstInputBinding, $MySecondInputBinding)

Produce-MyOutputValue | Push-OutputBinding -Name myQueue

Das Verhalten von Push-OutputBinding hängt vom Wert für -Name ab:

  • Wenn der angegebene Name nicht in eine gültige Ausgabebindung aufgelöst werden kann, wird ein Fehler ausgelöst.

  • Wenn die Ausgabebindung eine Auflistung von Werten akzeptiert, können Sie Push-OutputBinding wiederholt aufrufen, um mehrere Werte zu pushen.

  • Wenn die Ausgabebindung nur einen Singletonwert akzeptiert, wird durch einen zweiten Aufruf von Push-OutputBinding ein Fehler ausgelöst.

Syntax für Push-OutputBinding

Im Folgenden sind gültige Parameter für den Aufruf von Push-OutputBinding angegeben:

Name type Position BESCHREIBUNG
-Name String 1 Der Name der Ausgabebindung, die Sie festlegen möchten
-Value Object 2 Der Wert der festzulegenden Ausgabebindung, der vom ByValue-Wert der Pipeline akzeptiert wird.
-Clobber SwitchParameter benannt (Optional:) Durch die Angabe wird erzwungen, dass der Wert für eine angegebene Ausgabebindung festgelegt werden muss.

Die folgenden allgemeinen Parameter werden ebenfalls unterstützt:

  • Verbose
  • Debug
  • ErrorAction
  • ErrorVariable
  • WarningAction
  • WarningVariable
  • OutBuffer
  • PipelineVariable
  • OutVariable

Weitere Informationen finden Sie unter About CommonParameters (Informationen zu CommonParameters).

Beispiel für „Push-OutputBinding“: HTTP-Antworten

Ein HTTP-Trigger gibt eine Antwort mithilfe einer Ausgabebindung mit dem Namen response zurück. Im folgenden Beispiel hat die Ausgabebindung von response den Wert „output #1“:

PS >Push-OutputBinding -Name response -Value ([HttpResponseContext]@{
    StatusCode = [System.Net.HttpStatusCode]::OK
    Body = "output #1"
})

Da die Ausgabe über HTTP erfolgt (wobei nur ein Singletonwert akzeptiert wird), wird ein Fehler ausgelöst, wenn Push-OutputBinding ein zweites Mal aufgerufen wird.

PS >Push-OutputBinding -Name response -Value ([HttpResponseContext]@{
    StatusCode = [System.Net.HttpStatusCode]::OK
    Body = "output #2"
})

Für Ausgaben, die nur Singletonwerte akzeptieren, können Sie mit dem -Clobber-Parameter den alten Wert überschreiben, anstatt das Hinzufügen zu einer Auflistung zu versuchen. Im folgenden Beispiel wird davon ausgegangen, dass Sie bereits einen Wert hinzugefügt haben. Mithilfe von -Clobber überschreibt die Antwort im folgenden Beispiel den vorhandenen Wert, um den Wert „output #3“ zurückzugeben:

PS >Push-OutputBinding -Name response -Value ([HttpResponseContext]@{
    StatusCode = [System.Net.HttpStatusCode]::OK
    Body = "output #3"
}) -Clobber

Beispiel für „Push-OutputBinding“: Einreihen von Ausgabebindungen in Warteschlangen

Push-OutputBinding dient zum Senden von Daten an Ausgabebindungen, z. B. eine Azure Queue Storage-Ausgabebindung. Im folgenden Beispiel hat die in die Warteschlange geschriebene Nachricht den Wert „output #1“:

PS >Push-OutputBinding -Name outQueue -Value "output #1"

Die Ausgabebindung für eine Speicherwarteschlange akzeptiert mehrere Ausgabewerte. In diesem Fall wird durch Aufrufen des folgenden Beispiels nach dem ersten Beispiel eine Liste mit den beiden Elementen „output #1“ und „output #2“ in die Warteschlange geschrieben.

PS >Push-OutputBinding -Name outQueue -Value "output #2"

Wenn das folgende Beispiel nach den ersten beiden aufgerufen wird, werden der Ausgabeauflistung zwei weitere Werte hinzugefügt:

PS >Push-OutputBinding -Name outQueue -Value @("output #3", "output #4")

Beim Schreiben in die Warteschlange enthält die Nachricht diese vier Werte: „output #1“, „output #2“, „output #3“ und „output #4“.

Cmdlet Get-OutputBinding

Sie können das Cmdlet Get-OutputBinding verwenden, um die Werte abzurufen, die derzeit für Ihre Ausgabebindungen festgelegt sind. Dieses Cmdlet ruft eine Hashtabelle mit den Namen der Ausgabebindungen und ihren jeweiligen Werten ab.

Das folgende Beispiel zeigt die Verwendung von Get-OutputBinding für das Zurückgeben der aktuellen Bindungswerte:

Get-OutputBinding

Name                           Value
----                           -----
MyQueue                        myData
MyOtherQueue                   myData

Get-OutputBinding umfasst auch den Parameter -Name, der zum Filtern der zurückgegebenen Bindungen verwendet werden kann, wie im folgenden Beispiel gezeigt:

Get-OutputBinding -Name MyQ*

Name                           Value
----                           -----
MyQueue                        myData

Platzhalter (*) werden in Get-OutputBinding unterstützt.

Protokollierung

Die Protokollierung funktioniert bei PowerShell-Funktionen wie die reguläre PowerShell-Protokollierung. Sie können die Cmdlets für die Protokollierung verwenden, um in beliebige Ausgabestreams zu schreiben. Jedes Cmdlet ist einer der von Functions verwendeten Protokollebenen zugeordnet.

Protokollierungsebene von Functions Protokollierungs-Cmdlet
Fehler Write-Error
Warnung Write-Warning
Information Write-Information
Write-Host
Write-Output
Schreibt in die Information-Protokollebene.
Debuggen Write-Debug
Trace Write-Progress
Write-Verbose

Zusätzlich zu diesen Cmdlets wird alles, was in die Pipeline geschrieben wird, auf die Protokollebene Information umgeleitet und mit der Standardformatierung von PowerShell angezeigt.

Wichtig

Die Verwendung der Cmdlets Write-Verbose oder Write-Debug reicht nicht für die Anzeige von Protokollen der Ebenen „Ausführlich“ und „Debuggen“. Sie müssen auch den Schwellenwert für die Protokollebene konfigurieren, mit dem Sie angeben, welche Protokollebene Sie tatsächlich benötigen. Weitere Informationen finden Sie unter Konfigurieren der Protokollebene für Funktions-Apps.

Konfigurieren der Protokollebene für Funktions-Apps

Sie können in Azure Functions den Schwellenwert definieren und damit steuern, was Functions in die Protokolle schreibt. Um den Schwellenwert für alle in die Konsole geschriebenen Traces festzulegen, verwenden Sie die logging.logLevel.default-Eigenschaft in der host.json-Datei. Diese Einstellung gilt für alle Funktionen in Ihrer Funktionen-App.

Im folgenden Beispiel wird der Schwellenwert zum Aktivieren der ausführlichen Protokollierung für alle Funktionen festgelegt. Für die MyFunction-Funktion wird hingegen der Schwellenwert für die Debugprotokollierung festgelegt:

{
    "logging": {
        "logLevel": {
            "Function.MyFunction": "Debug",
            "default": "Trace"
        }
    }
}

Weitere Informationen finden Sie in der host.json-Referenz.

Anzeigen der Protokolle

Wenn Ihre Funktions-App in Azure ausgeführt wird, können Sie sie mit Application Insights überwachen. Lesen Sie Überwachen von Azure Functions, um weitere Informationen zum Anzeigen und Abfragen von Funktionsprotokollen zu erhalten.

Wenn Sie Ihre Funktions-App für die Entwicklung lokal ausführen, erfolgt die Protokollierung standardmäßig entsprechend dem Dateisystem. Legen Sie zum Anzeigen der Protokolle an der Konsole die Umgebungsvariable AZURE_FUNCTIONS_ENVIRONMENT auf Development fest, bevor Sie die Funktions-App starten.

Typen von Triggern und Bindungen

Sie können für Ihre Funktions-Apps viele unterschiedliche Trigger und Bindungen verwenden. Die vollständige Liste der Trigger und Bindungen finden Sie hier.

Alle Trigger und Bindungen werden im Code als echte Datentypen dargestellt:

  • Hashtable
  • Zeichenfolge
  • byte[]
  • INT
  • double
  • HttpRequestContext
  • HttpResponseContext

Die ersten fünf Typen in dieser Liste sind Standardtypen von .NET. Die letzten beiden werden nur für den Trigger HttpTrigger verwendet.

Jeder Bindungsparameter in Ihren Funktionen muss einen dieser Typen aufweisen.

HTTP: Trigger und Bindungen

HTTP- und Webhooktrigger und HTTP-Ausgabebindungen verwenden Request- und Response-Objekte, um das HTTP-Messaging darzustellen.

Anforderungsobjekt

Das Anforderungsobjekt, das an das Skript übergeben wird, ist vom Typ HttpRequestContext, der über die folgenden Eigenschaften verfügt:

Eigenschaft Beschreibung des Dataflows type
Body Ein Objekt, das den Hauptteil der Anforderung enthält. Body wird basierend auf den Daten in den am besten geeigneten Typ serialisiert. Bei JSON-Daten wird z. B. eine Hashtabelle übergeben. Wenn es sich bei den Daten um eine Zeichenfolge handelt, erfolgt die Übergabe auch als Zeichenfolge. Objekt (object)
Headers Ein Wörterbuch mit den Headern der Anforderung. Wörterbuch<string,string>*
Method Die HTTP-Methode der Anforderung. Zeichenfolge
Params Ein Objekt, das die Routingparameter der Anforderung enthält. Wörterbuch<string,string>*
Query Ein Objekt, das die Abfrageparameter enthält. Wörterbuch<string,string>*
Url Die URL der Anforderung. Zeichenfolge

* Bei Dictionary<string,string>-Schlüsseln wird nicht zwischen Groß- und Kleinschreibung unterschieden.

Antwortobjekt

Das Antwortobjekt, das Sie zurücksenden sollten, weist den Typ HttpResponseContext auf, der über die folgenden Eigenschaften verfügt:

Eigenschaft Beschreibung des Dataflows type
Body Ein Objekt, das den Hauptteil der Antwort enthält. Objekt (object)
ContentType Einstellungsmöglichkeit für den Inhaltstyp der Antwort Zeichenfolge
Headers Ein Objekt, das die Header der Antwort enthält. Wörterbuch oder Hashtabelle
StatusCode Der HTTP-Statuscode der Antwort. Zeichenfolge oder ganze Zahl

Zugreifen auf Anforderung und Antwort

Bei der Arbeit mit HTTP-Triggern können Sie auf die HTTP-Anforderung auf die gleiche Weise wie auf andere Eingabebindungen zugreifen. Dies ist der param-Block.

Verwenden Sie ein HttpResponseContext-Objekt, um eine Antwort zurückzugeben, wie im folgenden Beispiel dargestellt:

function.json

{
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "authLevel": "anonymous"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    }
  ]
}

run.ps1

param($req, $TriggerMetadata)

$name = $req.Query.Name

Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = [System.Net.HttpStatusCode]::OK
    Body = "Hello $name!"
})

Das Ergebnis eines Aufrufs dieser Funktion wäre:

PS > irm http://localhost:5001?Name=Functions
Hello Functions!

Typumwandlung für Trigger und Bindungen

Für bestimmte Bindungen wie Blobbindungen können Sie den Typ des Parameters angeben.

Damit z. B. Daten aus Blob Storage als Zeichenfolge bereitgestellt werden, fügen Sie dem param-Block die folgende Typumwandlung hinzu:

param([string] $myBlob)

PowerShell-Profil

In PowerShell gibt es das Konzept von PowerShell-Profilen. Wenn Sie nicht mit PowerShell-Profilen vertraut sind, lesen Sie unter Informationen zu Profilen nach.

Bei PowerShell-Funktionen wird das Profilskript einmal pro PowerShell-Workerinstanz in der App bei der ersten Bereitstellung und nach dem Leerlauf (Kaltstart) ausgeführt. Wenn die Parallelität durch Festlegen des Werts PSWorkerInProcConcurrencyUpperBound aktiviert ist, wird das Profilskript für jeden erstellten Runspace ausgeführt.

Wenn Sie eine Funktions-App mit Tools wie Visual Studio Code und Azure Functions Core Tools erstellen, wird automatisch eine Standarddatei profile.ps1 erstellt. Das Standardprofil wird im GitHub-Repository von Core Tools verwaltet und bietet Folgendes:

  • Automatische MSI-Authentifizierung in Azure
  • Möglichkeit der Aktivierung des Azure PowerShell-Alias AzureRM bei Bedarf

PowerShell-Versionen

Die folgende Tabelle zeigt die PowerShell-Versionen, die für jede Hauptversion der Functions-Runtime verfügbar sind, sowie die erforderliche .NET-Version:

Functions-Version PowerShell-Version .NET-Version
4.x PowerShell 7.4 .NET 8
4.x PowerShell 7.2 (Supportende) .NET 6

Die aktuell von der Runtime verwendete Version sehen Sie in der Ausgabe $PSVersionTable einer Funktion.

Weitere Informationen zur Azure Functions-Runtime-Supportrichtlinie finden Sie in diesem Artikel.

Hinweis

Der Support für PowerShell 7.2 in Azure Functions endet am 8. November 2024. Möglicherweise müssen Sie beim Upgrade Ihrer PowerShell 7.2-Funktionen auf PowerShell 7.4 einige Breaking Changes beheben. Befolgen Sie diesen Migrationsleitfaden, um ein Upgrade auf PowerShell 7.4 durchzuführen.

Lokale Ausführung unter einer bestimmten Version

Bei der lokalen Ausführung von PowerShell-Funktionen müssen Sie dem Values-Array in der Datei „local.setting.json“ im Projektstamm die Einstellung "FUNCTIONS_WORKER_RUNTIME_VERSION" : "7.4" hinzufügen. Wenn Sie PowerShell 7.4 lokal ausführen, sieht Ihre Datei „local.settings.json“ wie im folgenden Beispiel aus:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "",
    "FUNCTIONS_WORKER_RUNTIME": "powershell",
    "FUNCTIONS_WORKER_RUNTIME_VERSION" : "7.4"
  }
}

Hinweis

In PowerShell Functions bezieht sich der Wert „~7“ für FUNCTIONS_WORKER_RUNTIME_VERSION auf „7.0.x“. PowerShell-Funktions-Apps mit „~7“ werden nicht automatisch auf „7.4“ aktualisiert. In Zukunft müssen Apps für PowerShell-Funktions-Apps sowohl die Hauptversion als auch die Nebenversion angeben, die als Ziel verwendet werden soll. Daher ist es notwendig, „7.4“ anzugeben, wenn Sie „7.4.x“ als Ziel verwenden möchten.

Ändern der PowerShell-Version

Berücksichtigen Sie diese Überlegungen, bevor Sie Ihre PowerShell-Funktions-App zu PowerShell 7.4 migrieren:

  • Da die Migration möglicherweise zu Breaking Changes in Ihrer App führt, lesen Sie diesen Migrationsleitfaden, bevor Sie Ihre App auf PowerShell 7.4 upgraden.

  • Stellen Sie sicher, dass Ihre Funktions-App mit der neuesten Version der Functions-Runtime in Azure ausgeführt wird, die derzeit Version 4.x ist. Weitere Informationen finden Sie unter Anzeigen und Aktualisieren der aktuellen Runtimeversion.

Verwenden Sie die folgenden Schritte, um die von Ihrer Funktions-App verwendete PowerShell-Version zu ändern. Sie können diesen Vorgang entweder im Azure-Portal oder mithilfe von PowerShell durchführen.

  1. Navigieren Sie im Azure-Portal zu Ihrer Funktions-App.

  2. Wählen Sie unter Einstellungen die Option Konfiguration aus. Suchen Sie auf der Registerkarte Allgemeine Einstellungen die PowerShell-Version.

    image

  3. Wählen Sie die gewünschte PowerShell Core-Version und anschließend Speichern aus. Wenn Sie vor dem anstehenden Neustart gewarnt werden, wählen Sie Fortsetzen aus. Die Funktions-App wird unter der gewählten PowerShell-Version neu gestartet.

Hinweis

Azure Functions-Unterstützung für PowerShell 7.4 ist allgemein verfügbar (GA). Möglicherweise wird PowerShell 7.4 im Azure-Portal weiterhin als Vorschau angegeben, dies wird jedoch bald geändert, um den Status der allgemeinen Verfügbarkeit widerzuspiegeln.

Die Funktions-App startet neu, nachdem die Änderung der Konfiguration vorgenommen wurde.

Verwaltung von Abhängigkeiten

Module in Azure Functions, die in PowerShell geschrieben wurden, können auf zwei Arten verwaltet werden: über das Feature „Verwaltete Abhängigkeiten“ oder durch direktes Einschließen der Module in Ihre App-Inhalte. Jede Methode hat ihre eigenen Vorteile, und welche die richtige ist, hängt von Ihren spezifischen Anforderungen ab.

Auswählen des richtigen Modulverwaltungsansatzes

Warum das Feature „Verwaltete Abhängigkeiten“ verwenden?

  • Vereinfachte Erstinstallation: Die Installation der Module wird automatisch anhand Ihrer Datei requirements.psd1 durchgeführt.
  • Automatische Upgrades: Module werden automatisch aktualisiert, einschließlich Sicherheitskorrekturen, ohne dass ein manueller Eingriff erforderlich ist.

Warum Module in App-Inhalte einschließen?

  • Keine Abhängigkeit vom PowerShell-Katalog: Module werden mit Ihrer App gebündelt, wodurch externe Abhängigkeiten beseitigt werden.
  • Mehr Kontrolle: Das Risiko von durch automatische Upgrades bedingten Regressionen wird vermieden, und Sie haben die volle Kontrolle darüber, welche Modulversionen verwendet werden.
  • Kompatibilität: Funktioniert mit Flex-Verbrauch und wird für andere Linux-SKUs empfohlen.

Feature „Verwaltete Abhängigkeiten“

Das Feature „Verwaltete Abhängigkeiten“ ermöglicht es Azure Functions, die in der Datei requirements.psd1 angegebenen PowerShell-Module automatisch herunterzuladen und zu verwalten. Dieses Feature ist in neuen PowerShell-Funktions-Apps standardmäßig aktiviert.

Konfigurieren von requirements.psd1

Um verwaltete Abhängigkeiten in Azure Functions mit PowerShell zu verwenden, müssen Sie eine requirements.psd1-Datei konfigurieren. In dieser Datei sind die Module angegeben, die für Ihre Funktion erforderlich sind. Azure Functions lädt diese Module automatisch herunter und aktualisiert sie, um sicherzustellen, dass Ihre Umgebung auf dem neuesten Stand bleibt.

Gehen Sie wie folgt vor, um die Datei requirements.psd1 einzurichten und zu konfigurieren:

  1. Erstellen Sie eine requirements.psd1-Datei im Stammverzeichnis Ihrer Azure-Funktion, wenn noch keine vorhanden ist.
  2. Definieren Sie die Module und deren Versionen in einer PowerShell-Datenstruktur.

Beispieldatei für requirements.psd1:

@{
    'Az' = '9.*'  # Specifies the Az module and will use the latest version with major version 9
}

Einschließen von Modulen in App-Inhalte

Wenn Sie mehr Kontrolle über Ihre Modulversionen haben und Abhängigkeiten von externen Ressourcen vermeiden möchten, können Sie Module direkt in die Inhalte Ihrer Funktions-App einschließen.

Gehen Sie wie folgt vor, um benutzerdefinierte Module einzuschließen:

  1. Erstellen Sie einen Modules-Ordner im Stammverzeichnis Ihrer Funktions-App.

    mkdir ./Modules

  2. Kopieren Sie Module in den Modules-Ordner mit einer der folgenden Methoden:

    • Wenn Module bereits lokal verfügbar sind:

      Copy-Item -Path /mymodules/mycustommodule -Destination ./Modules -Recurse

    • Verwenden von Save-Module für den Abruf aus dem PowerShell-Katalog:

      Save-Module -Name MyCustomModule -Path ./Modules

    • Verwenden von Save-PSResource aus dem ModulPSResourceGet:

      Save-PSResource -Name MyCustomModule -Path ./Modules

Ihre Funktions-App sollte die folgende Struktur aufweisen:

PSFunctionApp
 | - MyFunction
 | | - run.ps1
 | | - function.json
 | - Modules
 | | - MyCustomModule
 | | - MyOtherCustomModule
 | | - MySpecialModule.psm1
 | - local.settings.json
 | - host.json
 | - requirements.psd1

Wenn Sie Ihre Funktions-App starten, fügt der PowerShell-Sprachworker diesen Ordner Modules dem $env:PSModulePath hinzu, damit die Module wie bei normalen PowerShell-Skripts automatisch geladen werden.

Behandlung von Problemen mit verwalteten Abhängigkeiten

Aktivieren von verwalteten Abhängigkeiten

Damit verwaltete Abhängigkeiten funktionieren, muss das Feature in host.json aktiviert sein:

{
  "managedDependency": {
          "enabled": true
       }
}

Verwenden bestimmter Versionen als Ziel

Wenn bestimmte Modulversionen verwendet werden sollen, müssen die folgenden beiden Schritte befolgt werden, um sicherzustellen, dass die richtige Modulversion geladen wird:

  1. Geben Sie die Modulversion in requirements.psd1 an:

    @{
  'Az.Accounts' = '1.9.5'
}

  2. Fügen Sie eine wichtige Anweisung zu profile.ps1 hinzu:

    Import-Module Az.Accounts -RequiredVersion '1.9.5'

Mit diesen Schritten stellen Sie sicher, dass die angegebene Version geladen wird, wenn Ihre Funktion startet.

Konfigurieren bestimmter Intervalleinstellungen für verwaltete Abhängigkeiten

Sie können mithilfe der folgenden App-Einstellungen konfigurieren, wie verwaltete Abhängigkeiten heruntergeladen und installiert werden:

Einstellung Standardwert Beschreibung
MDMaxBackgroundUpgradePeriod 7.00:00:00 (sieben Tage) Steuert den Aktualisierungszeitraum im Hintergrund für PowerShell-Funktions-Apps.
MDNewSnapshotCheckPeriod 01:00:00 (eine Stunde) Gibt an, wie oft der PowerShell-Worker nach Updates sucht
MDMinBackgroundUpgradePeriod 1.00:00:00 (ein Tag) Mindestzeit zwischen Upgradeüberprüfungen

Überlegungen zur Abhängigkeitsverwaltung

  • Internetzugriff: Verwaltete Abhängigkeiten erfordern Zugriff auf https://www.powershellgallery.com, um Module herunterzuladen. Stellen Sie sicher, dass Ihre Umgebung diesen Zugriff zulässt, einschließlich der Änderung von Firewall-/VNet-Regeln bei Bedarf.
  • Lizenzakzeptanz: Verwaltete Abhängigkeiten unterstützen keine Module, die eine Lizenzakzeptanz erfordern.
  • Flex-Verbrauchsplan: Das Feature „Verwaltete Abhängigkeiten“ wird im Flex-Verbrauchsplan nicht unterstützt. Verwenden von benutzerdefinierten Modulen als Alternative
  • Modulspeicherorte: Auf Ihrem lokalen Computer werden Module in der Regel in einem der global verfügbaren Ordner in Ihrem $env:PSModulePath installiert. Bei der Ausführung in Azure unterscheidet sich der $env:PSModulePath für eine PowerShell-Funktions-App vom $env:PSModulePath in einem regulären PowerShell-Skript und enthält sowohl den Ordner Modules, der mit Ihrem App-Inhalt hochgeladen wurde, als auch einen separaten Speicherort, der von verwalteten Abhängigkeiten verwaltet wird.

Umgebungsvariablen

In Functions werden App-Einstellungen, z.B. Dienstverbindungszeichenfolgen, während der Ausführung als Umgebungsvariablen verfügbar gemacht. Auf diese Einstellungen können Sie über $env:NAME_OF_ENV_VAR zugreifen, wie im folgenden Beispiel gezeigt:

param($myTimer)

Write-Host "PowerShell timer trigger function ran! $(Get-Date)"
Write-Host $env:AzureWebJobsStorage
Write-Host $env:WEBSITE_SITE_NAME

Es gibt mehrere Möglichkeiten zum Hinzufügen, Aktualisieren und Löschen von Funktionen-App-Einstellungen:

Zur Durchführung von Änderungen an den Funktions-App-Einstellungen muss Ihre Funktions-App neu gestartet werden.

Wenn App-Einstellungen lokal ausgeführt werden, werden sie über die Projektdatei local.settings.json gelesen.

Parallelität

Standardmäßig kann die PowerShell-Runtime von Functions nur einen Aufruf einer Funktion zu einem Zeitpunkt verarbeiten. Dieser Grad an Parallelität ist in den folgenden Situationen jedoch möglicherweise nicht ausreichend:

  • Wenn Sie versuchen, eine große Anzahl von Aufrufen gleichzeitig zu verarbeiten
  • Wenn Ihre Funktionen andere Funktionen innerhalb derselben Funktions-App aufrufen

Es gibt einige Parallelitätsmodelle, die Sie je nach Art der Workload untersuchen könnten:

  • Erhöhung von FUNCTIONS_WORKER_PROCESS_COUNT. Durch Erhöhen dieser Einstellung können Funktionsaufrufe in mehreren Prozessen innerhalb derselben Instanz behandelt werden, was einen gewissen CPU- und Arbeitsspeicheroverhead mit sich bringt. Im Allgemeinen werden E/A-gebundene Funktionen nicht durch diesen Overhead beeinträchtigt. Bei CPU-gebundenen Funktionen können die Auswirkungen erheblich sein.

  • Erhöhen Sie den Einstellungswert PSWorkerInProcConcurrencyUpperBound für die App. Das Erhöhen dieser Einstellung ermöglicht die Erstellung mehrerer Runspaces innerhalb desselben Prozesses, was den CPU- und Arbeitsspeicheroverhead erheblich reduziert.

Sie legen diese Umgebungsvariable in den App-Einstellungen Ihrer Funktions-App fest.

Abhängig von Ihrem Anwendungsfall kann Durable Functions die Skalierbarkeit erheblich verbessern. Weitere Informationen finden Sie unter Anwendungsmuster von Durable Functions.

Hinweis

Möglicherweise erhalten Sie die Warnung „Anforderungen werden aufgrund nicht verfügbarer Runspaces in die Warteschlange gestellt“. Beachten Sie, dass dies kein Fehler ist. Die Nachricht teilt Ihnen mit, dass sich Anforderungen in der Warteschlange befinden und diese bearbeitet werden, wenn die vorherigen Anforderungen abgeschlossen sind.

Überlegungen zur Verwendung von Parallelität

PowerShell ist standardmäßig eine Singlethread-Skriptsprache. Parallelität kann jedoch mithilfe mehrerer PowerShell-Runspaces im gleichen Prozess hinzugefügt werden. Die Anzahl der erstellten Runspaces – und daher die Anzahl gleichzeitiger Threads pro Worker – ist durch die Anwendungseinstellung PSWorkerInProcConcurrencyUpperBound begrenzt. Standardmäßig wird die Anzahl der Runspaces in Version 4.x der Functions-Laufzeit auf 1.000 festgelegt. In den Versionen bis 3.x ist die maximale Anzahl von Runspaces auf 1 festgelegt. Der Durchsatz Ihrer Funktions-App hängt von der im ausgewählten Plan verfügbaren CPU-Anzahl und Arbeitsspeichergröße ab.

Azure PowerShell verwendet einige Kontexte und Status auf Prozessebene, die Ihnen viel Eingabearbeit ersparen können. Wenn Sie jedoch Parallelität in Ihrer Funktions-App aktivieren und Aktionen aufrufen, die den Zustand ändern, könnte es zu Racebedingungen kommen. Diese Racebedingungen sind schwierig zu debuggen, da ein Aufruf von einem bestimmten Zustand abhängt, während ein anderer Aufruf diesen Zustand ändert.

Parallelität hat in Azure PowerShell einen enormen Wert, da einige Vorgänge sehr viel Zeit in Anspruch nehmen können. Sie müssen dabei jedoch umsichtig vorgehen. Wenn Sie vermuten, dass eine Racebedingung vorliegt, legen Sie die App-Einstellung „PSWorkerInProcConcurrencyUpperBound“ auf 1 fest, und verwenden Sie stattdessen Isolation auf Sprachworkerprozess-Ebene für Parallelität.

Konfigurieren von scriptFile der Funktion

Standardmäßig wird eine PowerShell-Funktion aus der Datei run.ps1 ausgeführt, die sich im gleichen übergeordneten Verzeichnis wie die zugehörige Datei function.json befindet.

Die scriptFile-Eigenschaft in der Datei function.json kann verwendet werden, um eine Ordnerstruktur zu erhalten, die wie im folgenden Beispiel aussieht:

FunctionApp
 | - host.json
 | - myFunction
 | | - function.json
 | - lib
 | | - PSFunction.ps1

In diesem Fall enthält die Datei function.json für myFunction eine scriptFile-Eigenschaft, die auf die Datei mit der exportierten Funktion verweist, die ausgeführt werden soll.

{
  "scriptFile": "../lib/PSFunction.ps1",
  "bindings": [
    // ...
  ]
}

Verwenden von PowerShell-Modulen durch Konfigurieren eines entryPoint

PowerShell-Funktionen werden in diesem Artikel mit der Standardskriptdatei run.ps1 gezeigt, die von den Vorlagen generiert wird. Sie können Ihre Funktionen aber auch in PowerShell-Module einfügen. Sie können auf Ihren spezifischen Funktionscode im Modul mit den Feldern scriptFile und entryPoint in der Konfigurationsdatei „function.json“ verweisen.

In diesem Fall ist entryPoint der Name einer Funktion oder eines Cmdlets in dem PowerShell-Modul, auf das in scriptFile verwiesen wird.

Gehen Sie z. B. von der folgenden Ordnerstruktur aus:

FunctionApp
 | - host.json
 | - myFunction
 | | - function.json
 | - lib
 | | - PSFunction.psm1

PSFunction.psm1 enthält dabei Folgendes:

function Invoke-PSTestFunc {
    param($InputBinding, $TriggerMetadata)

    Push-OutputBinding -Name OutputBinding -Value "output"
}

Export-ModuleMember -Function "Invoke-PSTestFunc"

In diesem Beispiel umfasst die Konfiguration für myFunction eine scriptFile-Eigenschaft, die auf PSFunction.psm1 – ein PowerShell-Modul in einem anderen Ordner – verweist. Die entryPoint-Eigenschaft verweist auf die Invoke-PSTestFunc-Funktion, die den Einstiegspunkt für das Modul darstellt.

{
  "scriptFile": "../lib/PSFunction.psm1",
  "entryPoint": "Invoke-PSTestFunc",
  "bindings": [
    // ...
  ]
}

Bei dieser Konfiguration wird Invoke-PSTestFunc auf die gleiche Weise wie run.ps1 ausgeführt.

Überlegungen zu PowerShell-Funktionen

Beachten Sie beim Arbeiten mit PowerShell-Funktionen die Überlegungen in den folgenden Abschnitten.

Kaltstart

Bei der Entwicklung von Azure Functions im serverlosen Hostingmodell sind Kaltstarts Realität. Kaltstart bezieht sich auf den Zeitraum, den der Start Ihrer Funktions-App bis zum Verarbeiten einer Anforderung dauert. Kaltstarts treten beim Verbrauchstarif häufiger auf, da Ihre Funktions-App während inaktiver Phasen heruntergefahren wird.

Vermeiden der Verwendung von Install-Module

Das Ausführen von Install-Module in Ihrem Funktionsskript bei jedem Aufruf kann zu Leistungsproblemen führen. Verwenden Sie stattdessen Save-Module oder Save-PSResource, bevor Sie Ihre Funktions-App veröffentlichen, um die erforderlichen Module zu bündeln.

Weitere Informationen finden Sie im Abschnitt Abhängigkeitsverwaltung.

Nächste Schritte

Weitere Informationen finden Sie in den folgenden Ressourcen: