Sdílet prostřednictvím

Azure Functions s .NET Aspire (Preview)

.NET Aspire je náročná technologická sada, která zjednodušuje vývoj distribuovaných aplikací v cloudu. Integrace .NET Aspire s Azure Functions umožňuje vyvíjet, ladit a orchestrovat projekt Azure Functions .NET jako součást hostitele aplikace .NET .NET.

Důležité

Integrace .NET Aspire se službou Azure Functions je aktuálně ve verzi Preview a může se změnit.

Požadavky

Nastavení vývojového prostředí pro použití Azure Functions s .NET Aspire:

  • Nainstalujte SDK sadu .NET 9 a .NET Aspire 9.0 nebo novější. I když je vyžadována sada .NET 9 SDK, rozhraní .NET Aspire 9.0 podporuje architektury .NET 8 a .NET 9.
  • Pokud používáte Visual Studio, aktualizujte na verzi 17.12 nebo novější. Musíte mít také nejnovější verzi nástrojů Azure Functions pro Visual Studio. Kontrola aktualizací:
    1. Přejděte naMožnosti>.
    2. V části Projekty a řešení vyberte Azure Functions.
    3. Podle výzvy vyberte Vyhledat aktualizace a nainstalovat aktualizace.

Struktura řešení

Řešení, které používá Azure Functions a .NET Aspire, má několik projektů, včetně hostitelského projektu aplikace a jednoho nebo více projektů Functions.

Projekt hostitele aplikace je vstupním bodem vaší aplikace. Orchestruje nastavení komponent aplikace, včetně projektu Functions.

Řešení obvykle zahrnuje také výchozí projekt služby . Tento projekt poskytuje sadu výchozích služeb a konfigurací, které se mají použít napříč projekty ve vaší aplikaci.

Projekt hostingu aplikace

Pokud chcete úspěšně nakonfigurovat integraci, ujistěte se, že hostitelský projekt aplikace splňuje následující požadavky:

  • Projekt hostitele aplikace musí odkazovat na Aspire.Hosting.Azure.Functions. Tento balíček definuje potřebnou logiku pro integraci.
  • Hostitelský projekt aplikace musí mít odkaz na projekt pro každý projekt Functions, který chcete zahrnout do orchestrace.
  • V souboru Program.cs hostitele aplikace musíte voláním na instanci AddAzureFunctionsProject<TProject>() zahrnout projekt IDistributedApplicationBuilder. Tuto metodu AddProject<TProject>() použijete místo metody, kterou používáte pro jiné typy projektů v rozhraní .NET Aspire. Pokud používáte AddProject<TProject>(), projekt Functions se nemůže správně spustit.

Následující příklad ukazuje minimální Program.cs soubor pro hostitelský projekt aplikace:

var builder = DistributedApplication.CreateBuilder(args);

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

builder.Build().Run();

Projekt Azure Functions

Pokud chcete úspěšně nakonfigurovat integraci, ujistěte se, že projekt Azure Functions splňuje následující požadavky:

Následující příklad ukazuje minimální Program.cs soubor pro projekt Functions použitý v .NET Aspire:

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

var builder = FunctionsApplication.CreateBuilder(args);

builder.AddServiceDefaults();

builder.ConfigureFunctionsWebApplication();

builder.Build().Run();

Tento příklad neobsahuje výchozí konfiguraci Application Insights, která se zobrazí v mnoha dalších Program.cs příkladech a v šablonách Azure Functions. Místo toho nakonfigurujete integraci OpenTelemetry v .NET Aspire voláním builder.AddServiceDefaults metody.

Pokud chcete využít integraci na maximum, zvažte následující pokyny:

  • Do projektu Functions nezahrnujte žádné přímé integrace Application Insights. Monitorování v .NET Aspire se místo toho zpracovává prostřednictvím podpory OpenTelemetry. Rozhraní .NET Aspire můžete nakonfigurovat tak, aby exportoval data do služby Azure Monitor prostřednictvím výchozího projektu služby.
  • Nedefinujte vlastní nastavení aplikace v local.settings.json souboru pro projekt Functions. Jediné nastavení, které by mělo být v local.settings.json je "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated". Nastavte všechny ostatní konfigurace aplikací prostřednictvím hostitelského projektu aplikace.

Konfigurace připojení pomocí rozhraní .NET Aspire

Projekt hostitele aplikace definuje prostředky a pomáhá vytvářet propojení mezi nimi pomocí kódu. Tato část ukazuje, jak nakonfigurovat a přizpůsobit připojení, která váš projekt Azure Functions používá.

.NET Aspire obsahuje výchozí oprávnění pro připojení, která vám můžou pomoct začít. Tato oprávnění ale nemusí být pro vaši aplikaci vhodná nebo dostatečná.

Ve scénářích, které používají řízení přístupu na základě role v Azure (RBAC), můžete oprávnění přizpůsobit voláním WithRoleAssignments() metody pro prostředek projektu. Při volání WithRoleAssignments()se odeberou všechna výchozí přiřazení rolí a musíte explicitně definovat požadovaná přiřazení rolí úplné sady. Pokud hostujete aplikaci ve službě Azure Container Apps, je nutné použít WithRoleAssignments() a volat AddAzureContainerAppEnvironment() na DistributedApplicationBuilder.

Hostitelské úložiště Azure Functions

Azure Functions vyžaduje připojení k úložišti hostitele (AzureWebJobsStorage) pro několik základních chování. Při volání AddAzureFunctionsProject<TProject>() ve vašem hostitelském projektu aplikace se ve výchozím nastavení vytvoří připojení, které je poskytnuto projektu Functions. Toto výchozí připojení používá emulátor služby Azure Storage pro spuštění místního vývoje a automaticky zřídí účet úložiště při nasazení. Pokud chcete mít větší kontrolu, můžete toto připojení nahradit voláním .WithHostStorage() zdroje projektu Functions.

Výchozí oprávnění, která rozhraní .NET Aspire nastaví pro připojení k úložišti hostitele, závisí na tom, jestli voláte WithHostStorage() nebo ne. Přidáním WithHostStorage() se odebere přiřazení přispěvatele účtu úložiště. Následující tabulka uvádí výchozí oprávnění, která .NET Aspire nastaví pro připojení k úložišti hostitele:

Připojení k úložišti hostitele Výchozí role
Žádný hovor na WithHostStorage() Přispěvatel dat objektů blob služby Storage
Přispěvatel dat fronty služby Storage
Přispěvatel dat tabulky služby Storage
Přispěvatel ke službě úložiště
Volání WithHostStorage() Přispěvatel dat objektů blob služby Storage
Přispěvatel dat fronty služby Storage
Přispěvatel dat tabulky úložiště

Následující příklad ukazuje minimální Program.cs soubor pro hostitelský projekt aplikace, který nahrazuje úložiště hostitele a určuje přiřazení role:

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

Poznámka:

Vlastník dat objektů blob služby Storage je role, kterou doporučujeme pro základní potřeby připojení hostitele k úložišti. Aplikace může narazit na problémy, pokud je připojení ke službě blob nastaveno pouze na výchozí roli Storage Blob Data Contributor.

V produkčních scénářích uveďte volání jak WithHostStorage(), tak WithRoleAssignments(). Tuto roli pak můžete explicitně nastavit společně s ostatními, které potřebujete.

Připojení spouštěče a vazby

Vaše spouštěče a vazby odkazují na připojení podle jména. Následující integrace .NET Aspire poskytují tato připojení prostřednictvím volání na WithReference() u zdroje projektu:

Integrace .NET Aspire Výchozí role
Azure Blob Storage Přispěvatel dat objektů blob služby Storage
Přispěvatel dat fronty služby Storage
Přispěvatel dat tabulky úložiště
Azure Queue Storage Přispěvatel dat objektů blob služby Storage
Přispěvatel dat fronty služby Storage
Přispěvatel dat tabulky úložiště
Azure Event Hubs Vlastník dat služby Azure Event Hubs
Azure Service Bus Vlastník dat služby Azure Service Bus

Následující příklad ukazuje minimální Program.cs soubor pro hostitelský projekt aplikace, který konfiguruje spouštěč fronty. V tomto příkladu má odpovídající aktivační událost fronty vlastnost Connection nastavenu na MyQueueTriggerConnection, takže volání specifikuje název WithReference().

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

Při jiných integracích se volání k nastavení WithReference konfigurace provádějí odlišně. Zpřístupní konfiguraci integračním klientům .NET Aspire, ale ne k triggerům a vazbám. U těchto integrací zavolejte WithEnvironment() pro zpracování informací o připojení s cílem vyřešení triggeru nebo vazby.

Následující příklad ukazuje, jak nastavit proměnnou MyBindingConnection prostředí pro prostředek, který zveřejňuje výraz připojovacího řetězce:

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

Pokud chcete, aby integrace klientů .NET Aspire i systém triggerů a vazeb používaly připojení, můžete nakonfigurovat obojí WithReference() i WithEnvironment().

U některých prostředků se struktura připojení může lišit mezi tím, kdy ho spouštíte místně a kdy ho publikujete do Azure. V předchozím příkladu může být otherIntegration prostředek, který běží jako emulátor, takže ConnectionStringExpression by vrátil připojovací řetězec emulátoru. Ale když je prostředek publikován, může platforma .NET Aspire nastavit připojení založené na identitě a ConnectionStringExpression vrátit URI služby. V tomto případě může být při nastavování připojení založených na identitě pro Azure Functions potřeba zadat jiný název proměnné prostředí.

Následující příklad používá builder.ExecutionContext.IsPublishMode k podmíněnému přidání nezbytné přípony:

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

Podrobnosti o formátech připojení, které jednotlivé vazby podporují, a oprávnění, která tyto formáty vyžadují, najdete na referenčních stránkách vazby.

Hostování aplikace

Ve výchozím nastavení se při publikování projektu Azure Functions do Azure nasadí do Azure Container Apps.

Během období Preview prostředky aplikace kontejneru nepodporují škálování řízené událostmi. Podpora azure Functions není dostupná pro aplikace nasazené v tomto režimu. Pokud potřebujete otevřít ticket podpory, vyberte typ prostředku Azure Container Apps.

Důležité informace a osvědčené postupy

Při vyhodnocování integrace služby Azure Functions s .NET Aspire zvažte následující body:

  • Podpora integrace je aktuálně ve verzi Preview.

  • Konfigurace triggeru a vazby prostřednictvím rozhraní .NET Aspire je v současné době omezená na konkrétní integrace. Podrobnosti najdete v tématu Konfigurace připojení s rozhraním .NET Aspire v tomto článku.

  • Soubor Program.cs by měl používat IHostApplicationBuilderverzi spuštění instance hostitele. IHostApplicationBuilder umožňuje voláním builder.AddServiceDefaults() přidat do vašeho Functions projektu výchozí hodnoty služby .NET Aspire.

  • .NET Aspire používá k monitorování OpenTelemetry. Rozhraní .NET Aspire můžete nakonfigurovat tak, aby exportoval data do služby Azure Monitor prostřednictvím výchozího projektu služby.

    V mnoha dalších kontextech Azure Functions můžete zahrnout přímou integraci s Application Insights registrací pracovní služby. Tento typ integrace v .NET Aspire nedoporučujeme. Může vést k chybám za běhu verze 2.22.0 z Microsoft.ApplicationInsights.WorkerService, i když verze 2.23.0 tento problém řeší. Pokud používáte .NET Aspire, odeberte z projektu Functions všechny přímé integrace Application Insights.

  • U projektů Functions zařazených do orchestrace .NET Aspire by většina konfigurace aplikace měla pocházet z hostitelského projektu aplikace .NET Aspire. Vyhněte se nastavování položek v local.settings.json, kromě nastavení FUNCTIONS_WORKER_RUNTIME. Pokud nastavíte stejnou proměnnou prostředí v local.settings.json a .NET Aspire, systém použije verzi .NET Aspire.

  • Nenakonfigurujte emulátor služby Azure Storage pro žádná připojení v local.settings.json. Mnoho úvodních šablon Functions zahrnuje emulátor jako výchozí nastavení pro AzureWebJobsStorage. Konfigurace emulátoru ale může vyzvat některé vývojářské nástroje ke spuštění verze emulátoru, která může být v konfliktu s verzí, kterou používá .NET Aspire.