Freigeben über

Azure-Funktionen mit .NET Aspire (Vorschau)

.NET Aspire ist ein Stapel, der einen festen Ansatz verfolgt und die Entwicklung verteilter Anwendungen in der Cloud vereinfacht. Mit der Integration von .NET Aspire mit Azure Functions können Sie ein Azure Functions .NET-Projekt als Teil des .NET Aspire-App-Hosts entwickeln, debuggen und koordinieren.

Von Bedeutung

Die Integration von .NET Aspire mit Azure Functions befindet sich derzeit in der Vorschau und kann geändert werden.

Voraussetzungen

Richten Sie Ihre Entwicklungsumgebung für die Verwendung von Azure Functions mit .NET Aspire ein:

  • Installieren Sie das .NET 9 SDK und .NET Aspire 9.0 oder höher. Obwohl das .NET 9 SDK erforderlich ist, unterstützt .NET Aspire 9.0 die .NET 8- und .NET 9-Frameworks.
  • Wenn Sie Visual Studio verwenden, aktualisieren Sie auf Version 17.12 oder höher. Sie müssen auch über die neueste Version der Azure Functions-Tools für Visual Studio verfügen. So suchen Sie nach Updates:
    1. Wechseln Sie zu Tools>Optionen.
    2. Wählen Sie unter "Projekte und Lösungen" die Option "Azure Functions" aus.
    3. Wählen Sie Nach Updates suchen aus, und installieren Sie Updates, wenn Sie dazu aufgefordert werden.

Lösungsstruktur

Eine Lösung, die Azure Functions und .NET Aspire verwendet, verfügt über mehrere Projekte, einschließlich eines App-Hostprojekts und eines oder mehrerer Functions-Projekte.

Das App-Hostprojekt ist der Einstiegspunkt für Ihre Anwendung. Es koordiniert die Einrichtung der Komponenten Ihrer Anwendung, einschließlich des Functions-Projekts.

Die Lösung enthält in der Regel auch ein Dienststandardprojekt . Dieses Projekt stellt eine Reihe von Standarddiensten und Konfigurationen bereit, die für projekte in Ihrer Anwendung verwendet werden sollen.

App-Hostprojekt

Um die Integration erfolgreich zu konfigurieren, stellen Sie sicher, dass das App-Hostprojekt die folgenden Anforderungen erfüllt:

  • Das App-Hostprojekt muss auf Aspire.Hosting.Azure.Functions verweisen. Dieses Paket definiert die erforderliche Logik für die Integration.
  • Das App-Hostprojekt muss über einen Projektverweis für jedes Funktionen-Projekt verfügen, das Sie in die Orchestrierung einbeziehen möchten.
  • In der Datei des App-Hosts Program.cs müssen Sie das Projekt einschließen, indem Sie AddAzureFunctionsProject<TProject>() auf Ihrer IDistributedApplicationBuilder Instanz aufrufen. Sie verwenden diese Methode anstelle der AddProject<TProject>() Methode, die Sie für andere Projekttypen in .NET Aspire verwenden. Wenn Sie AddProject<TProject>() verwenden, kann das Functions-Projekt nicht ordnungsgemäß gestartet werden.

Das folgende Beispiel zeigt eine minimale Program.cs Datei für ein App-Hostprojekt:

var builder = DistributedApplication.CreateBuilder(args);

builder.AddAzureFunctionsProject<Projects.MyFunctionsProject>("MyFunctionsProject");

builder.Build().Run();

Azure Functions-Projekt

Um die Integration erfolgreich zu konfigurieren, stellen Sie sicher, dass das Azure Functions-Projekt die folgenden Anforderungen erfüllt:

Das folgende Beispiel zeigt eine minimale Program.cs Datei für ein Functions-Projekt, das in .NET Aspire verwendet wird:

using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Extensions.Hosting;

var builder = FunctionsApplication.CreateBuilder(args);

builder.AddServiceDefaults();

builder.ConfigureFunctionsWebApplication();

builder.Build().Run();

Dieses Beispiel enthält nicht die standardmäßige Application Insights-Konfiguration, die in vielen anderen Program.cs Beispielen und in den Azure Functions-Vorlagen angezeigt wird. Stattdessen konfigurieren Sie die OpenTelemetry-Integration in .NET Aspire durch Aufrufen der builder.AddServiceDefaults Methode.

Beachten Sie die folgenden Richtlinien, um die Integration optimal zu verwenden:

  • Fügen Sie keine direkten Application Insights-Integrationen in das Funktionsprojekt ein. Die Überwachung in .NET Aspire erfolgt stattdessen über die OpenTelemetry-Unterstützung. Sie können .NET Aspire so konfigurieren, dass Daten über das Dienststandardprojekt nach Azure Monitor exportiert werden.
  • Definieren Sie keine benutzerdefinierten App-Einstellungen in der local.settings.json Datei für das Functions-Projekt. Die einzige Einstellung, die in local.settings.json enthalten sein soll, ist "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated". Legen Sie alle anderen App-Konfigurationen über das App-Hostprojekt fest.

Verbindungskonfiguration mit .NET Aspire

Das App-Hostprojekt definiert Ressourcen und unterstützt Sie beim Erstellen von Verbindungen zwischen ihnen mithilfe von Code. In diesem Abschnitt wird gezeigt, wie Verbindungen konfiguriert und angepasst werden, die ihr Azure Functions-Projekt verwendet.

.NET Aspire enthält Standardverbindungsberechtigungen, die Ihnen bei den ersten Schritten helfen können. Diese Berechtigungen sind jedoch möglicherweise nicht geeignet oder für Ihre Anwendung ausreichend.

Für Szenarien, die die rollenbasierte Zugriffssteuerung (Azure Role-Based Access Control, RBAC) verwenden, können Sie Berechtigungen anpassen, indem Sie die WithRoleAssignments() Methode für die Projektressource aufrufen. Wenn Sie aufrufen WithRoleAssignments(), werden alle Standardrollenzuweisungen entfernt, und Sie müssen explizit die gewünschten vollständigen Rollenzuweisungen definieren. Wenn Sie Ihre Anwendung in Azure Container-Apps hosten, erfordert die Verwendung von WithRoleAssignments() auch, dass Sie AddAzureContainerAppEnvironment() auf DistributedApplicationBuilder anrufen.

Hostspeicher von Azure Functions

Azure Functions erfordert für mehrere seiner wichtigsten Funktionalitäten eine Hostspeicherverbindung (AzureWebJobsStorage). Wenn Sie AddAzureFunctionsProject<TProject>() in Ihrem App-Hostprojekt aufrufen, wird die AzureWebJobsStorage-Verbindung standardmäßig erstellt und dem Functions-Projekt bereitgestellt. Diese Standardverbindung verwendet den Azure Storage-Emulator für die lokale Entwicklung und stellt automatisch ein Speicherkonto bereit, wenn sie bereitgestellt wird. Um mehr Kontrolle zu erhalten, können Sie diese Verbindung durch Aufrufen .WithHostStorage() der Projektressource "Functions" ersetzen.

Die Standardberechtigungen, die .NET Aspire für die Hostspeicherverbindung festlegt, hängt davon ab, ob Sie aufrufen WithHostStorage() oder nicht. Beim Hinzufügen von WithHostStorage() wird eine Zuordnung von Mitwirkenden für das Speicherkonto entfernt. In der folgenden Tabelle sind die Standardberechtigungen aufgeführt, die .NET Aspire für die Hostspeicherverbindung festlegt:

Hostspeicherverbindung Standardrollen
Kein Anruf an WithHostStorage() Mitwirkender an Storage-Blobdaten,
Mitwirkender an Storage-Warteschlangendaten,
Mitwirkende für Speichertabellendaten,
Speicherkontomitwirkender
Aufrufen von WithHostStorage() Mitwirkender an Storage-Blobdaten,
Mitwirkender an Storage-Warteschlangendaten,
Mitwirkender an Storage-Tabellendaten

Das folgende Beispiel zeigt eine minimale Program.cs Datei für ein App-Hostprojekt, das den Hostspeicher ersetzt und eine Rollenzuweisung angibt:

using Azure.Provisioning.Storage;

var builder = DistributedApplication.CreateBuilder(args);

builder.AddAzureContainerAppEnvironment("myEnv");

var myHostStorage = builder.AddAzureStorage("myHostStorage");

builder.AddAzureFunctionsProject<Projects.MyFunctionsProject>("MyFunctionsProject")
    .WithHostStorage(myHostStorage)
    .WithRoleAssignments(myHostStorage, StorageBuiltInRole.StorageBlobDataOwner);

builder.Build().Run();

Hinweis

Der Besitzer von Speicher-BLOB-Daten ist die Rolle, die wir für die grundlegenden Anforderungen der Hostspeicherverbindung empfehlen. In Ihrer App können Probleme auftreten, wenn die Verbindung zum Blob-Dienst nur über den .NET Aspire-Standard Mitwirkende an Speicherblobdaten hergestellt ist.

Fügen Sie für Produktionsszenarien Aufrufe von WithHostStorage() und WithRoleAssignments() hinzu. Sie können diese Rolle dann explizit festlegen, zusammen mit allen anderen Personen, die Sie benötigen.

Trigger und Bindungsverbindungen

Ihre Trigger und Bindungen verweisen mithilfe des Namens auf Verbindungen. Die folgenden .NET Aspire-Integrationen stellen diese Verbindungen über einen Aufruf von WithReference() auf der Projektressource bereit:

.NET Aspire-Integration Standardrollen
Azure Blob Storage Mitwirkender an Storage-Blobdaten,
Mitwirkender an Storage-Warteschlangendaten,
Mitwirkender an Storage-Tabellendaten
Azure Queue Storage Mitwirkender an Storage-Blobdaten,
Mitwirkender an Storage-Warteschlangendaten,
Mitwirkender an Storage-Tabellendaten
Azure Event Hubs Azure Event Hubs-Datenbesitzer
Azure Service Bus Azure Service Bus-Datenbesitzer

Das folgende Beispiel zeigt eine minimale Program.cs Datei für ein App-Hostprojekt, das einen Warteschlangentrigger konfiguriert. In diesem Beispiel ist die Connection-Eigenschaft des entsprechenden Warteschlangenauslösers auf MyQueueTriggerConnection festgelegt, sodass der Aufruf von WithReference() den Namen angibt.

var builder = DistributedApplication.CreateBuilder(args);

var myAppStorage = builder.AddAzureStorage("myAppStorage").RunAsEmulator();
var queues = myAppStorage.AddQueues("queues");

builder.AddAzureFunctionsProject<Projects.MyFunctionsProject>("MyFunctionsProject")
    .WithReference(queues, "MyQueueTriggerConnection");

builder.Build().Run();

Bei anderen Integrationen werden Aufrufe zum WithReference Festlegen der Konfiguration auf eine andere Weise durchgeführt. Sie stellen die Konfiguration für .NET Aspire-Clientintegrationen zur Verfügung, aber nicht für Trigger und Bindungen. Für diese Integrationen rufen Sie WithEnvironment() auf, um die Verbindungsinformationen zum Auflösen des Auslösers oder der Bindung zu übergeben.

Das folgende Beispiel zeigt, wie Die Umgebungsvariable MyBindingConnection für eine Ressource festgelegt wird, die einen Verbindungszeichenfolgenausdruck verfügbar macht:

builder.AddAzureFunctionsProject<Projects.MyFunctionsProject>("MyFunctionsProject")
    .WithEnvironment("MyBindingConnection", otherIntegration.Resource.ConnectionStringExpression);

Wenn Sie möchten, dass sowohl .NET Aspire-Client-Integrationen als auch das System von Triggern und Bindungen eine Verbindung verwenden, können Sie sowohl WithReference() als auch WithEnvironment() konfigurieren.

Bei einigen Ressourcen kann sich die Struktur einer Verbindung zwischen der lokalen Ausführung und der Veröffentlichung in Azure möglicherweise unterscheiden. Im vorherigen Beispiel könnte otherIntegration eine Ressource sein, die als Emulator ausgeführt wird, sodass ConnectionStringExpression eine Emulatorverbindungszeichenfolge zurückgeben würde. Wenn die Ressource veröffentlicht wird, kann .NET Aspire jedoch eine identitätsbasierte Verbindung einrichten und ConnectionStringExpression den URI des Diensts zurückgeben. In diesem Fall müssen Sie möglicherweise einen anderen Umgebungsvariablennamen angeben, um identitätsbasierte Verbindungen für Azure-Funktionen einzurichten.

Im folgenden Beispiel wird builder.ExecutionContext.IsPublishMode verwendet, um das erforderliche Suffix bedingt hinzuzufügen:

builder.AddAzureFunctionsProject<Projects.MyFunctionsProject>("MyFunctionsProject")
    .WithEnvironment("MyBindingConnection" + (builder.ExecutionContext.IsPublishMode ? "__serviceUri" : ""), otherIntegration.Resource.ConnectionStringExpression);

Ausführliche Informationen zu den Verbindungsformaten, die jede Bindung unterstützt, sowie zu den Berechtigungen, die diese Formate erfordern, finden Sie auf den Referenzseiten der Bindung.

Hosten der Anwendung

Wenn Sie ein Azure Functions-Projekt in Azure veröffentlichen, wird es standardmäßig in Azure-Container-Apps bereitgestellt.

Während des Vorschauzeitraums unterstützen die Ressourcen der Container-App keine ereignisgesteuerte Skalierung. Die Unterstützung von Azure Functions ist für Apps, die in diesem Modus bereitgestellt werden, nicht verfügbar. Wenn Sie ein Supportticket öffnen müssen, wählen Sie den Ressourcentyp "Azure Container Apps" aus.

Überlegungen und bewährte Methoden

Berücksichtigen Sie die folgenden Punkte, wenn Sie die Integration von Azure-Funktionen mit .NET Aspire bewerten:

  • Die Unterstützung für die Integration befindet sich derzeit in der Vorschauphase.

  • Die Trigger- und Bindungskonfiguration über .NET Aspire ist derzeit auf bestimmte Integrationen beschränkt. Ausführliche Informationen finden Sie in diesem Artikel unter Verbindungskonfiguration mit .NET Aspire .

  • Ihre Program.cs Datei sollte die IHostApplicationBuilder Version des Hostinstanzstarts verwenden. Mit IHostApplicationBuilder können Sie builder.AddServiceDefaults() aufrufen, um die Standardwerte des .NET Aspire-Diensts zu Ihrem Azure Functions-Projekt hinzuzufügen.

  • .NET Aspire verwendet OpenTelemetry zur Überwachung. Sie können .NET Aspire so konfigurieren, dass Daten über das Dienststandardprojekt nach Azure Monitor exportiert werden.

    In vielen anderen Azure Functions-Kontexten können Sie die direkte Integration in Application Insights einschließen, indem Sie den Workerdienst registrieren. Wir empfehlen diese Art von Integration in .NET Aspire nicht. Es kann zu Laufzeitfehlern mit Version 2.22.0 von Microsoft.ApplicationInsights.WorkerService führen, doch Version 2.23.0 behebt dieses Problem. Wenn Sie .NET Aspire verwenden, entfernen Sie alle direkten Application Insights-Integrationen aus Ihrem Functions-Projekt.

  • Bei Funktionen-Projekten, die in einer .NET Aspire-Orchestrierung aufgelistet sind, sollte der Großteil der Anwendungskonfiguration aus dem .NET Aspire-App-Hostprojekt stammen. Vermeiden Sie das Festlegen von Elementen in local.settings.json, außer der FUNCTIONS_WORKER_RUNTIME Einstellung. Wenn Sie dieselbe Umgebungsvariable in local.settings.json und .NET Aspire festlegen, verwendet das System die .NET Aspire-Version.

  • Konfigurieren Sie den Azure Storage-Emulator nicht für Verbindungen in local.settings.json. Viele Functions-Startvorlagen enthalten den Emulator als Standard für AzureWebJobsStorage. Die Emulatorkonfiguration kann jedoch einige Entwicklertools auffordern, eine Version des Emulators zu starten, die mit der Von .NET Aspire verwendeten Version in Konflikt geraten kann.