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. Sie sollten auch 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 weiter unten.

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 wird bei der Ausführung eine Reihe von Argumenten ü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. Die zusätzlichen 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.

Im Folgenden wird gezeigt, 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 ausgegeben.

  • 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 eine Reihe unterschiedlicher 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 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 dies entweder im Azure-Portal oder mithilfe von PowerShell erledigen.

  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

Azure Functions ermöglicht Ihnen das Nutzen des PowerShell-Katalogs zum Verwalten von Abhängigkeiten. Wenn die Abhängigkeitsverwaltung aktiviert ist, wird die Datei „requirements.psd1“ verwendet, um die benötigten Module automatisch herunterzuladen. Sie aktivieren dieses Verhalten, indem Sie im Stammverzeichnis der Datei host.json die managedDependency-Eigenschaft auf true festlegen (siehe folgendes Beispiel):

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

Wenn Sie ein neues PowerShell Functions-Projekt erstellen, ist die Abhängigkeitsverwaltung standardmäßig aktiviert, wobei das AzureAz-Modul enthalten ist. Die maximal unterstützte Anzahl von Modulen beträgt derzeit 10. Die unterstützte Syntax ist MajorNumber.* oder eine exakte Modulversion, wie im folgenden Beispiel von „requirements.psd1“ gezeigt:

@{
	Az = '1.*'
	SqlServer = '21.1.18147'
}

Wenn Sie die Datei „requirements.psd1“ aktualisieren, werden aktualisierte Module nach einem Neustart installiert.

Verwenden bestimmter Versionen als Ziel

Möglicherweise möchten Sie eine bestimmte Version eines Moduls in Ihrer Datei „requirements.psd1“ als Ziel verwenden. Wenn Sie beispielsweise eine ältere Version von Az.Accounts als die im Az-Modul enthaltene verwenden möchten, müssen Sie eine bestimmte Version als Ziel verwenden, wie im folgenden Beispiel gezeigt:

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

In diesem Fall müssen Sie auch am Anfang Ihrer Datei „profile.ps1“ eine import-Anweisung hinzufügen, die wie im folgenden Beispiel aussieht:

Import-Module Az.Accounts -RequiredVersion '1.9.5'

Auf diese Weise wird die ältere Version des Az.Account-Moduls zuerst geladen, wenn die Funktion gestartet wird.

Überlegungen zur Abhängigkeitsverwaltung

Berücksichtigen Sie Folgendes, wenn Sie Abhängigkeitsverwaltung verwenden:

  • Verwaltete Abhängigkeiten erfordern Zugriff auf https://www.powershellgallery.com, um Module herunterzuladen. Achten Sie bei lokaler Ausführung darauf, dass die Laufzeit auf diese URL zugreifen kann, indem Sie alle erforderlichen Firewallregeln hinzufügen.

  • Verwaltete Abhängigkeiten unterstützen derzeit keine Module, bei denen der Benutzer eine Lizenz akzeptieren muss, entweder durch interaktives Akzeptieren der Lizenz oder durch Bereitstellung des -AcceptLicense-Schalters beim Aufruf von Install-Module.

  • Verwaltete Abhängigkeiten werden nicht unterstützt, wenn Sie Ihre Funktions-App mit einem Flex-Verbrauchstarif hosten. Sie müssen stattdessen eigene benutzerdefinierte Module definieren.

App-Einstellungen für Abhängigkeitsverwaltung

Die folgenden Anwendungseinstellungen können verwendet werden, um zu ändern, wie die verwalteten Abhängigkeiten heruntergeladen und installiert werden.

Funktions-App-Einstellung Standardwert Beschreibung
MDMaxBackgroundUpgradePeriod 7.00:00:00 (sieben Tage) Steuert den Aktualisierungszeitraum im Hintergrund für PowerShell-Funktions-Apps. Weitere Informationen finden Sie unter MDMaxBackgroundUpgradePeriod.
MDNewSnapshotCheckPeriod 01:00:00 (eine Stunde) Gibt an, wie oft jeder PowerShell-Worker überprüft, ob Upgrades verwalteter Abhängigkeiten installiert wurden. Weitere Informationen finden Sie unter MDNewSnapshotCheckPeriod.
MDMinBackgroundUpgradePeriod 1.00:00:00 (ein Tag) Der Zeitraum nach einer vorherigen Upgradeprüfung, bevor eine weitere Upgradeprüfung gestartet wird. Weitere Informationen finden Sie unter MDMinBackgroundUpgradePeriod.

Im Wesentlichen beginnt Ihr App-Upgrade innerhalb von MDMaxBackgroundUpgradePeriod, und der Upgrade-Prozess wird innerhalb von MDNewSnapshotCheckPeriod abgeschlossen.

Benutzerdefinierte Module

Die Nutzung Ihrer eigenen benutzerdefinierten Module in Azure Functions unterscheidet sich von der normalen Vorgehensweise für PowerShell.

Auf Ihrem lokalen Computer wird das Modul in einem der global verfügbaren Ordner in Ihrem $env:PSModulePath installiert. Bei Ausführung in Azure haben Sie keinen Zugriff auf die auf Ihrem Computer installierten Module. Aus diesem Grund muss sich der $env:PSModulePath für eine PowerShell-Funktions-App vom $env:PSModulePath eines regulären PowerShell-Skripts unterscheiden.

In Functions enthält PSModulePath zwei Pfade:

  • Den Ordner Modules im Stammverzeichnis Ihrer Funktions-App
  • Einen Pfad zum Ordner Modules, der vom PowerShell-Sprachworker gesteuert wird

Modulordner auf Funktions-App-Ebene

Um benutzerdefinierte Module zu verwenden, können Sie die Module, von denen Ihre Funktionen abhängen, im Ordner Modules speichern. Module in diesem Ordner stehen in der Functions-Runtime automatisch zur Verfügung. Jede Funktion in der Funktions-App kann diese Module verwenden.

Hinweis

In der Datei requirements.psd1 angegebene Module werden automatisch heruntergeladen und in den Pfad eingeschlossen, sodass Sie sie nicht in den Ordner „modules“ einschließen müssen. Diese werden bei Ausführung in der Cloud lokal im Ordner $env:LOCALAPPDATA/AzureFunctions und im Ordner /data/ManagedDependencies gespeichert.

Um dieses benutzerdefinierte Modulfeature nutzen zu können, erstellen Sie den Ordner Modules im Stammverzeichnis der Funktions-App. Kopieren Sie die Module, die Sie in Ihren Funktionen verwenden möchten, an diesen Speicherort.

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

Mit dem Ordner Modules sollte Ihre Funktions-App folgende Ordnerstruktur 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.

Modulordner auf Ebene des Sprachworkers

Mehrere Module werden häufig vom PowerShell-Sprachworker verwendet. Diese Module werden im PSModulePath an letzter Stelle definiert.

Die aktuelle Liste der Module lautet wie folgt:

  • Microsoft.PowerShell.Archive: Modul für die Arbeit mit Archiven, z. B. .zip, .nupkg und anderen
  • ThreadJob: Eine threadbasierte Implementierung der PowerShell-Auftrags APIs

Von Azure Functions wird standardmäßig die neueste Version dieser Module verwendet. Um eine bestimmte Modulversion zu verwenden, legen Sie diese bestimmte Version im Ordner Modules Ihrer Funktionsanwendung ab.

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. Dadurch 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. Dies 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 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

In diesem Artikel wurden PowerShell-Funktionen in 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.

Bündeln von Modulen anstelle der Verwendung von Install-Module

Ihr Skript wird bei jedem Aufruf ausgeführt. Vermeiden Sie die Verwendung von Install-Module in Ihrem Skript. Verwenden Sie stattdessen Save-Module vor der Veröffentlichung, damit Ihre Funktion keine Zeit für das Herunterladen des Moduls aufbringen muss. Falls Kaltstarts Auswirkungen auf Ihre Funktionen haben, sollten Sie erwägen, Ihre Funktions-App in einem App Service-Plan mit Always On oder einem Premium-Plan bereitzustellen.

Nächste Schritte

Weitere Informationen finden Sie in den folgenden Ressourcen: