Registrieren von Bindungserweiterungen von Azure Functions

Ab Version 2.x von Azure Functions umfasst die Funktionsruntime standardmäßig nur HTTP- und Timertrigger. Andere Trigger und Bindungen sind als separate Pakete verfügbar.

Funktions-Apps mit .NET-Klassenbibliotheken verwenden Bindungen, die als NuGet-Pakete im Projekt installiert sind. Nicht auf .NET basierende Funktions-Apps können mithilfe von Erweiterungsbundles dieselben Bindungen nutzen, ohne mit der .NET-Infrastruktur interagieren zu müssen.

In der folgenden Tabelle ist angegeben, wann und wie Sie Bindungen registrieren.

Entwicklungsumgebung Registrierung
in Functions 1.x
Registrierung
in Funktionen 2.x oder höher
Azure-Portal Automatic Automatic*
Nicht-.NET-Sprachen Automatic Verwendung von Erweiterungsbundles (empfohlen) oder explizite Installation von Erweiterungen
C#-Klassenbibliothek mit Visual Studio 2019 Verwendung von NuGet-Tools Verwendung von NuGet-Tools
C#-Klassenbibliothek mit Visual Studio Code Verwendung der .NET Core-CLI

* Das Portal verwendet Erweiterungsbündel.

Zugreifen auf Erweiterungen in Nicht-.NET-Sprachen

Für Java, JavaScript, PowerShell, Python und benutzerdefinierte Handlerfunktions-Apps wird die Verwendung von Erweiterungsbundles empfohlen, um auf Bindungen zuzugreifen. Falls die Verwendung von Erweiterungsbundles nicht möglich ist, können Sie Bindungserweiterungen explizit installieren.

Erweiterungsbündel

Mit Erweiterungsbundles können Sie Ihrer Funktions-App kompatible Bindungserweiterungen hinzufügen. Erweiterungsbundles werden in der Datei host.json der App aktiviert.

Sie können Erweiterungsbündel mit Version 2.x und höheren Versionen der Functions-Runtime verwenden.

Erweiterungsbundles sind mit Versionsangaben versehen. Jede Version enthält einen bestimmten Satz an Bindungserweiterungen, deren gemeinsame Funktionalität überprüft wurde. Wählen Sie eine Bundleversion entsprechend den Erweiterungen aus, die Sie in Ihrer App benötigen.

Um Ihrer Funktions-App ein Erweiterungsbundle hinzuzufügen, fügen Sie den Abschnitt extensionBundle in die Datei host.json ein. In vielen Fällen erfolgt die Hinzufügung automatisch durch Visual Studio Code und Azure Functions Core Tools.

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[2.*, 3.0.0)"
    }
}

In extensionBundle sind die folgenden Eigenschaften verfügbar:

Eigenschaft BESCHREIBUNG
id Der Namespace für Microsoft Azure Functions-Erweiterungsbündel.
version Die Version des zu installierenden Pakets. Die Functions Runtime wählt immer die zulässige Höchstversion aus, die durch den Versionsbereich oder das Intervall definiert ist. Mit dem obigen Versionswert sind alle Bündelversionen von 2.0.0 bis kleiner als 3.0.0 zulässig. Weitere Informationen finden Sie im Abschnitt zur Intervallnotation zum Angeben von Versionsbereichen.

In der folgenden Tabelle werden die derzeit verfügbaren Versionen des Standardbundles Microsoft.Azure.Functions.ExtensionBundle sowie Links zu den darin enthaltenen Erweiterungen aufgeführt.

Bundleversion Version in „host.json“ Enthaltene Erweiterungen
1.x [1.*, 2.0.0) Siehe Datei extensions.json, mit der das Bundle generiert wurde
2.x [2.*, 3.0.0) Siehe Datei extensions.json, mit der das Bundle generiert wurde

Hinweis

Sie können zwar in der Datei „host.json“ einen benutzerdefinierten Versionsbereich angeben, es wird aber empfohlen, einen Versionswert aus dieser Tabelle zu verwenden.

Explizites Installieren von Erweiterungen

Wenn Sie keine Erweiterungspakete verwenden können, können Sie Azure Functions Core Tools lokal nutzen, um die für Ihr Projekt erforderlichen Erweiterungspakete zu installieren.

Wichtig

Erweiterungen können nicht explizit in einer Funktions-App installiert werden, die Erweiterungspakete verwendet. Entfernen Sie den Abschnitt extensionBundle in host.json, bevor Sie Erweiterungen explizit installieren.

Die folgenden Elemente beschreiben einige Gründe, aus denen Erweiterungen möglicherweise manuell installiert werden müssen:

  • Sie müssen auf eine bestimmte Version einer Erweiterung zugreifen, die nicht in einem Paket verfügbar ist.
  • Sie müssen auf eine benutzerdefinierte Erweiterung zugreifen, die nicht in einem Paket verfügbar ist.
  • Sie müssen auf eine bestimmte Kombination von Erweiterungen zugreifen, die nicht in einem einzelnen Paket verfügbar ist.

Hinweis

Um Erweiterungen mithilfe von Core Tools manuell zu installieren, müssen Sie das .NET Core 2.x SDK installiert haben. Das .NET Core SDK wird von Azure Functions Core Tools zum Installieren von Erweiterungen über NuGet verwendet. Für die Verwendung von Azure Functions-Erweiterungen müssen Sie nicht mit .NET vertraut sein.

Bei der expliziten Installation von Erweiterungen wird die .NET-Projektdatei „extensions.csproj“ zum Stamm Ihres Projekts hinzugefügt. Diese Datei definiert die von Ihren Funktionen benötigten NuGet-Pakete. Sie können zwar mit den NuGet-Paketverweisen in dieser Datei arbeiten, mit Core Tools können Erweiterungen jedoch installiert werden, ohne die Datei manuell bearbeiten zu müssen.

Es gibt verschiedene Möglichkeiten, um Core Tools zum Installieren der erforderlichen Erweiterungen in Ihrem lokalen Projekt zu verwenden.

Installieren aller Erweiterungen

Verwenden Sie den folgenden Befehl, um automatisch alle Erweiterungspakete hinzuzufügen, die von den Bindungen in Ihrem lokalen Projekt verwendet werden:

func extensions install

Der Befehl liest die Datei function.json, um zu ermitteln, welche Pakete Sie benötigen, installiert diese und erzeugt das Erweiterungenprojekt (extensions.csproj) neu. Er fügt alle neuen Bindungen an die aktuelle Version hinzu, aktualisiert aber keine vorhandenen Bindungen. Verwenden Sie die Option --force, um vorhandene Bindungen beim Installieren neuer auf die neueste Version zu aktualisieren. Weitere Informationen finden Sie unter dem func extensions install-Befehl.

Verwendet Ihre Funktions-App Bindungen, die von Core Tools nicht erkannt werden, müssen Sie die jeweilige Erweiterung manuell installieren.

Installieren einer bestimmten Erweiterung

Verwenden Sie den folgenden Befehl, um ein bestimmtes Erweiterungspaket mit einer bestimmten Version zu installieren (in diesem Fall die Speichererweiterung):

func extensions install --package Microsoft.Azure.WebJobs.Extensions.Storage --version 4.0.2

Weitere Informationen finden Sie unter dem func extensions install-Befehl.

Installieren von Erweiterungen aus NuGet in .NET-Sprachen

Bei einem auf C#-Klassenbibliotheken basierenden Functions-Projekt sollten Sie Erweiterungen direkt installieren. Erweiterungsbündel wurden eigens für Projekte konzipiert, die nicht auf C#-Klassenbibliotheken basieren.

C#-Klassenbibliothek mit Visual Studio

In Visual Studio können Sie Pakete mithilfe des Befehls Install-Package aus der Paket-Manager-Konsole installieren, wie im folgenden Beispiel gezeigt wird:

Install-Package Microsoft.Azure.WebJobs.Extensions.ServiceBus -Version <TARGET_VERSION>

Der Name des Pakets, das für eine bestimmte Bindung verwendet wird, ist im Referenzartikel für diese Bindung angegeben. Ein Beispiel finden Sie im Referenzartikel zur Service Bus-Bindung im Abschnitt „Pakete“.

Ersetzen Sie <TARGET_VERSION> im Beispiel durch eine bestimmte Version des Pakets, z.B. 3.0.0-beta5. Gültige Versionen sind auf den Seiten der einzelnen Pakete auf NuGet.org aufgeführt. Die Hauptversionen, die Functions Runtime 1.x oder 2.x entsprechen, sind im Referenzartikel für die Bindung angegeben.

Wenn Sie Install-Package verwenden, um auf eine Bindung zu verweisen, müssen Sie keine Erweiterungsbündel verwenden. Diese Vorgehensweise ist spezifisch für Klassenbibliotheken, die in Visual Studio erstellt werden.

C#-Klassenbibliothek mit Visual Studio Code

Installieren Sie in Visual Studio Code Pakete für eine C#-Klassenbibliothek über die Eingabeaufforderung. Verwenden Sie hierfür den Befehl dotnet add package in der .NET Core-CLI. Im folgenden Beispiel wird veranschaulicht, wie Sie eine Bindung hinzufügen:

dotnet add package Microsoft.Azure.WebJobs.Extensions.<BINDING_TYPE_NAME> --version <TARGET_VERSION>

Die .NET Core-CLI kann nur für die Entwicklung in Azure Functions 2.x verwendet werden.

Ersetzen Sie <BINDING_TYPE_NAME> durch den Namen des Pakets, das die benötigte Bindung enthält. Den gewünschten Bindungsreferenzartikel finden Sie in der Liste der unterstützten Bindungen.

Ersetzen Sie <TARGET_VERSION> im Beispiel durch eine bestimmte Version des Pakets, z.B. 3.0.0-beta5. Gültige Versionen sind auf den Seiten der einzelnen Pakete auf NuGet.org aufgeführt. Die Hauptversionen, die Functions Runtime 1.x oder 2.x entsprechen, sind im Referenzartikel für die Bindung angegeben.

Nächste Schritte