Azure Functions med .NET Aspire (förhandsversion)

.NET Aspire är ett ramverk som förenklar utvecklingen av distribuerade applikationer i molnet. Med integreringen av .NET Aspire med Azure Functions kan du utveckla, felsöka och orkestrera ett Azure Functions .NET-projekt som en del av .NET Aspire-appvärden.

Förutsättningar

Konfigurera utvecklingsmiljön för användning av Azure Functions med .NET Aspire:

• Installera .NET 9 SDK och .NET Aspire 9.0 eller senare. Även om .NET 9 SDK krävs stöder .NET Aspire 9.0 ramverken .NET 8 och .NET 9.
• Om du använder Visual Studio uppdaterar du till version 17.12 eller senare. Du måste också ha den senaste versionen av Azure Functions-verktygen för Visual Studio. Så här söker du efter uppdateringar:
  1. Gå till Verktygsalternativ>.
  2. Under Projekt och lösningar väljer du Azure Functions.
  3. Välj Sök efter uppdateringar och installera uppdateringar enligt anvisningarna.

Lösningsstruktur

En lösning som använder Azure Functions och .NET Aspire har flera projekt, inklusive ett programvärdprojekt och ett eller flera Functions-projekt.

Appvärdprojektet är startpunkten för ditt program. Den samordnar installationen av komponenterna i ditt program, inklusive Functions-projektet.

Lösningen innehåller vanligtvis också ett standardprojekt för tjänsten . Det här projektet innehåller en uppsättning standardtjänster och konfigurationer som ska användas i olika projekt i ditt program.

Appvärdprojekt

Om du vill konfigurera integreringen kontrollerar du att appvärdprojektet uppfyller följande krav:

• App-värdprojektet måste referera till Aspire.Hosting.Azure.Functions. Det här paketet definierar den nödvändiga logiken för integreringen.
• Apptjänstprojektet måste ha en projektreferens för varje funktionsprojekt som du vill inkludera i orkestreringen.
• I appvärdens Program.cs fil måste du inkludera projektet genom att anropa AddAzureFunctionsProject<TProject>() på din IDistributedApplicationBuilder instans. Du använder den här metoden i stället för att använda den AddProject<TProject>() metod som du använder för andra projekttyper i .NET Aspire. Om du använder AddProject<TProject>()kan functions-projektet inte startas korrekt.

I följande exempel visas en minimal Program.cs fil för ett apphost-projekt:

var builder = DistributedApplication.CreateBuilder(args);

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

builder.Build().Run();

Azure Functions-projekt

Om du vill konfigurera integreringen kontrollerar du att Azure Functions-projektet uppfyller följande krav:

• Functions-projektet måste referera till 2.x-versionerna av Microsoft.Azure.Functions.Worker och Microsoft.Azure.Functions.Worker.Sdk. Du måste också uppdatera alla Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore-referenser till 2.x-versionen.

• Filen Program.cs måste använda IHostApplicationBuilder-versionen av startprocessen för värdinstansen. Det här kravet innebär att du måste använda FunctionsApplication.CreateBuilder(args).

• Om lösningen innehåller ett standardprojekt för tjänsten kontrollerar du att functions-projektet är konfigurerat att använda det:

  • Functions-projektet bör innehålla en projektreferens till standardprojektet för tjänsten.
  • Innan du skapar IHostApplicationBuilder i Program.csska du inkludera ett anrop till builder.AddServiceDefaults().

I följande exempel visas en minimal Program.cs fil för ett Functions-projekt som används i .NET Aspire:

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

var builder = FunctionsApplication.CreateBuilder(args);

builder.AddServiceDefaults();

builder.ConfigureFunctionsWebApplication();

builder.Build().Run();

Det här exemplet innehåller inte standardkonfigurationen för Application Insights som visas i många andra Program.cs exempel och i Azure Functions-mallarna. I stället konfigurerar du OpenTelemetry-integrering i .NET Aspire genom att anropa builder.AddServiceDefaults metoden.

Tänk på följande riktlinjer för att få ut mesta möjliga av integreringen:

• Inkludera inga direkta Application Insights-integreringar i Functions-projektet. Övervakning i .NET Aspire hanteras i stället via dess OpenTelemetry-stöd. Du kan konfigurera .NET Aspire för att exportera data till Azure Monitor via standardprojektet för tjänsten.
• Definiera inte anpassade appinställningar i local.settings.json filen för Functions-projektet. Den enda inställningen som ska vara i local.settings.json är "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated". Ange alla andra appkonfigurationer via appvärdprojektet.

Anslutningskonfiguration med .NET Aspire

Appvärdprojektet definierar resurser och hjälper dig att skapa anslutningar mellan dem med hjälp av kod. Det här avsnittet visar hur du konfigurerar och anpassar anslutningar som ditt Azure Functions-projekt använder.

.NET Aspire innehåller standardanslutningsbehörigheter som kan hjälpa dig att komma igång. Dessa behörigheter kanske dock inte är lämpliga eller tillräckliga för ditt program.

För scenarier som använder rollbaserad åtkomstkontroll i Azure (RBAC) kan du anpassa behörigheter genom att anropa WithRoleAssignments() metoden för projektresursen. När du anropar WithRoleAssignments()tas alla standardrolltilldelningar bort och du måste uttryckligen definiera de fullständiga rolltilldelningar som du vill använda. Om du hostar din applikation på Azure Container Apps WithRoleAssignments() måste du också anropa AddAzureContainerAppEnvironment() på DistributedApplicationBuilder.

Azure Functions-värdlagring

Azure Functions kräver en värdlagringsanslutning (AzureWebJobsStorage) för flera av dess kärnbeteenden. När du anropar AddAzureFunctionsProject<TProject>() i appvärdprojektet skapas en AzureWebJobsStorage anslutning som standard och tillhandahålls till Functions-projektet. Den här standardanslutningen använder Azure Storage-emulatorn för lokala utvecklingskörningar och etablerar automatiskt ett lagringskonto när det distribueras. Om du vill ha mer kontroll kan du ersätta den här anslutningen genom att anropa .WithHostStorage() functions-projektresursen.

Standardbehörigheterna som .NET Aspire anger för värdlagringsanslutningen beror på om du anropar WithHostStorage() eller inte. Genom att lägga till WithHostStorage() tas en tilldelning av rollen lagringskontodeltagare bort. I följande tabell visas de standardbehörigheter som .NET Aspire anger för värdlagringsanslutningen:

I följande exempel visas en minimal Program.cs fil för ett programvärdprojekt som ersätter värdlagringen och anger en rolltilldelning:

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();

Utlösar- och bindningsanslutningar

Dina utlösare och bindningar hänvisar till anslutningar med namn. Följande .NET Aspire-integreringar tillhandahåller dessa anslutningar via ett anrop till WithReference() på projektresursen:

I följande exempel visas en minimal Program.cs fil för ett programvärdprojekt som konfigurerar en köutlösare. I det här exemplet har motsvarande köutlösare egenskapen Connection inställd på MyQueueTriggerConnection, så anropet till WithReference() anger namnet.

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();

För andra integreringar gör anrop till WithReference att ställa in konfigurationen på ett annat sätt. De gör konfigurationen tillgänglig för .NET Aspire-klientintegreringar, men inte för utlösare och bindningar. För dessa integreringar anropar du WithEnvironment() för att skicka anslutningsinformationen för utlösaren eller bindningen för att lösa.

I följande exempel visas hur du anger miljövariabeln MyBindingConnection för en resurs som exponerar ett anslutningsstränguttryck:

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

Om du vill att både .NET Aspire-klientintegreringar och systemet med utlösare och bindningar ska använda en anslutning kan du konfigurera både WithReference() och WithEnvironment().

För vissa resurser kan strukturen för en anslutning skilja sig från när du kör den lokalt och när du publicerar den till Azure. I föregående exempel otherIntegration kan vara en resurs som körs som en emulator, så ConnectionStringExpression skulle returnera en emulatoranslutningssträng. Men när resursen publiceras kan .NET Aspire konfigurera en identitetsbaserad anslutning och ConnectionStringExpression returnera tjänstens URI. I det här fallet kan du behöva ange ett annat miljövariabelnamn för att konfigurera identitetsbaserade anslutningar för Azure Functions.

I följande exempel används builder.ExecutionContext.IsPublishMode för att villkorligt lägga till det nödvändiga suffixet:

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

Mer information om de anslutningsformat som varje bindning stöder och de behörigheter som dessa format kräver finns i bindningens referenssidor.

Värd för applikationen

När du publicerar ett Azure Functions-projekt till Azure distribueras det som standard till Azure Container Apps.

Under förhandsgranskningsperioden stöder inte containerappresurserna händelsedriven skalning. Azure Functions-stöd är inte tillgängligt för appar som distribueras i det här läget. Om du behöver öppna ett supportärende väljer du resurstypen Azure Container Apps.

Överväganden och metodtips

Tänk på följande när du utvärderar integreringen av Azure Functions med .NET Aspire:

• Stöd för integreringen finns för närvarande i förhandsversion.

• Konfigurationen av utlösare och bindningar via .NET Aspire är för närvarande begränsad till specifika integreringar. Mer information finns i Anslutningskonfiguration med .NET Aspire i den här artikeln.

• Filen Program.cs bör använda IHostApplicationBuilder versionen av startproceduren för värdinstansen. IHostApplicationBuilder gör att du kan anropa builder.AddServiceDefaults() för att lägga till .NET Aspire-tjänstens standardinställningar i ditt Functions-projekt.

• .NET Aspire använder OpenTelemetry för övervakning. Du kan konfigurera .NET Aspire för att exportera data till Azure Monitor via standardprojektet för tjänsten.

  I många andra Azure Functions-kontexter kan du inkludera direkt integrering med Application Insights genom att registrera arbetstjänsten. Vi rekommenderar inte den här typen av integrering i .NET Aspire. Det kan leda till körningsfel med version 2.22.0 av Microsoft.ApplicationInsights.WorkerService, men version 2.23.0 åtgärdar det här problemet. När du använder .NET Aspire tar du bort alla direkta Application Insights-integreringar från ditt Functions-projekt.

• För Functions-projekt som har registrerats för en .NET Aspire-orkestrering bör merparten av programkonfigurationen komma från värdprojektet för .NET Aspire-appen. Undvik att ange saker i local.settings.json, förutom inställningen FUNCTIONS_WORKER_RUNTIME . Om du anger samma miljövariabel i local.settings.json och .NET Aspire använder systemet .NET Aspire-versionen.

• Konfigurera inte Azure Storage-emulatorn för några anslutningar i local.settings.json. Många Functions-startmallar innehåller emulatorn som standard för AzureWebJobsStorage. Emulatorkonfiguration kan dock uppmana vissa utvecklarverktyg att starta en version av emulatorn som kan vara i konflikt med den version som .NET Aspire använder.