Partager via

Azure Functions avec .NET Aspire (préversion)

.NET Aspire est une pile d’opinion qui simplifie le développement d’applications distribuées dans le cloud. L’intégration de .NET Aspire à Azure Functions vous permet de développer, de déboguer et d’orchestrer un projet .NET Azure Functions dans le cadre de l’hôte de l’application Aspire .NET.

Important

L’intégration de .NET Aspire à Azure Functions est actuellement en préversion et est susceptible de changer.

Conditions préalables

Configurez votre environnement de développement pour l’utilisation d’Azure Functions avec .NET Aspire :

  • Installez le SDK .NET 9 et .NET Aspire 9.0 ou version ultérieure. Bien que le SDK .NET 9 soit requis, .NET Aspire 9.0 prend en charge les frameworks .NET 8 et .NET 9.
  • Si vous utilisez Visual Studio, mettez à jour vers la version 17.12 ou ultérieure. Vous devez également disposer de la dernière version des outils Azure Functions pour Visual Studio. Pour rechercher les mises à jour :
    1. Accédez à Outils>Options.
    2. Sous Projets et solutions, sélectionnez Azure Functions.
    3. Sélectionnez Rechercher les mises à jour et installez les mises à jour comme indiqué.

Structure de la solution

Une solution qui utilise Azure Functions et .NET Aspire a plusieurs projets, notamment un projet hôte d’application et un ou plusieurs projets Functions.

Le projet hôte d’application est le point d’entrée de votre application. Il orchestre la configuration des composants de votre application, y compris le projet Functions.

La solution inclut généralement un projet de service par défaut . Ce projet fournit un ensemble de services et de configurations par défaut à utiliser dans les projets de votre application.

Projet hôte d’application

Pour configurer correctement l’intégration, vérifiez que le projet hôte d’application répond aux exigences suivantes :

  • Le projet hôte d’application doit référencer Aspire.Hosting.Azure.Functions. Ce package définit la logique nécessaire pour l’intégration.
  • Le projet hôte d’application doit avoir une référence de projet pour chaque projet Functions que vous souhaitez inclure dans l’orchestration.
  • Dans le fichier de l’hôte d’application Program.cs, vous devez inclure le projet en appelant AddAzureFunctionsProject<TProject>() dans votre instance IDistributedApplicationBuilder. Vous utilisez cette méthode au lieu d’utiliser la AddProject<TProject>() méthode que vous utilisez pour d’autres types de projet dans .NET Aspire. Si vous utilisez AddProject<TProject>(), le projet Functions ne peut pas démarrer correctement.

L’exemple suivant montre un fichier minimal Program.cs pour un projet hôte d’application :

var builder = DistributedApplication.CreateBuilder(args);

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

builder.Build().Run();

Projet Azure Functions

Pour configurer l’intégration, vérifiez que le projet Azure Functions répond aux exigences suivantes :

  • Le projet Functions doit référencer les versions 2.x de Microsoft.Azure.Functions.Worker et Microsoft.Azure.Functions.Worker.Sdk. Vous devez également mettre à jour les références Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore à la version 2.x.

  • Votre Program.cs fichier doit utiliser la IHostApplicationBuilder version du démarrage de l’instance hôte. Cette exigence signifie que vous devez utiliser FunctionsApplication.CreateBuilder(args).

  • Si votre solution inclut un projet par défaut de service, vérifiez que votre projet Functions est configuré pour l’utiliser :

    • Le projet Functions doit inclure une référence de projet au projet par défaut du service.
    • Avant de construire IHostApplicationBuilder dans Program.cs, incluez un appel à builder.AddServiceDefaults().

L’exemple suivant montre un fichier minimal Program.cs pour un projet Functions utilisé dans .NET Aspire :

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

var builder = FunctionsApplication.CreateBuilder(args);

builder.AddServiceDefaults();

builder.ConfigureFunctionsWebApplication();

builder.Build().Run();

Cet exemple n’inclut pas la configuration Application Insights par défaut qui apparaît dans de nombreux autres Program.cs exemples et dans les modèles Azure Functions. Au lieu de cela, vous configurez l’intégration d’OpenTelemetry dans .NET Aspire en appelant la builder.AddServiceDefaults méthode.

Pour tirer le meilleur parti de l’intégration, tenez compte des instructions suivantes :

  • N’incluez pas d’intégrations Application Insights directes dans le projet Functions. La surveillance dans .NET Aspire est plutôt prise en charge par le support d’OpenTelemetry. Vous pouvez configurer .NET Aspire pour exporter des données vers Azure Monitor via le projet par défaut du service.
  • Ne définissez pas les paramètres d’application personnalisés dans le local.settings.json fichier du projet Functions. Le seul paramètre qui doit être dans local.settings.json est "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated". Définissez toutes les autres configurations d’application via le projet hôte d’application.

Configuration de connexion avec .NET Aspire

Le projet hôte d’application définit des ressources et vous aide à créer des connexions entre elles à l’aide du code. Cette section montre comment configurer et personnaliser les connexions utilisées par votre projet Azure Functions.

.NET Aspire inclut des autorisations de connexion par défaut qui peuvent vous aider à commencer. Toutefois, ces autorisations peuvent ne pas être appropriées ou suffisantes pour votre application.

Pour les scénarios qui utilisent le contrôle d’accès en fonction du rôle Azure (RBAC), vous pouvez personnaliser les autorisations en appelant la WithRoleAssignments() méthode sur la ressource de projet. Lorsque vous appelez WithRoleAssignments(), toutes les attributions de rôles par défaut sont supprimées et vous devez définir explicitement les attributions de rôles de jeu complet souhaitées. Si vous hébergez votre application sur Azure Container Apps, l’utilisation de WithRoleAssignments() nécessite également que vous appeliez AddAzureContainerAppEnvironment() sur DistributedApplicationBuilder.

Stockage hôte Azure Functions

Azure Functions nécessite une connexion de stockage hôte (AzureWebJobsStorage) pour plusieurs de ses comportements de base. Lorsque vous appelez AddAzureFunctionsProject<TProject>() dans votre projet hôte d'application, une connexion AzureWebJobsStorage est créée par défaut et fournie au projet de Fonctions. Cette connexion par défaut utilise l’émulateur stockage Azure pour les exécutions de développement local et provisionne automatiquement un compte de stockage lorsqu’il est déployé. Pour plus de contrôle, vous pouvez remplacer cette connexion en appelant .WithHostStorage() la ressource de projet Functions.

Les autorisations par défaut que .NET Aspire définit pour la connexion de stockage hôte dépendent de si vous appelez WithHostStorage() ou non. L’ajout WithHostStorage() supprime une attribution contributeur de compte de stockage . Le tableau suivant répertorie les autorisations par défaut que .NET Aspire définit pour la connexion de stockage hôte :

Connexion de stockage hôte Rôles par défaut
Aucun appel à WithHostStorage() Contributeur aux données Blob du stockage,
Contributeur aux données en file d’attente du stockage,
Contributeur de données de table de stockage
Contributeur au compte de stockage
Appeler WithHostStorage() Contributeur aux données Blob du stockage,
Contributeur aux données en file d’attente du stockage,
Contributeur aux données de table du stockage

L’exemple suivant montre un fichier minimal Program.cs pour un projet hôte d’application qui remplace le stockage hôte et spécifie une attribution de rôle :

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

Remarque

Propriétaire des données blob du stockage est le rôle que nous recommandons pour les besoins de base de la connexion de stockage d’hôte. Votre application peut rencontrer des problèmes si la connexion au service d’objets blob ne dispose que du rôle par défaut Contributeur aux données Blob du stockage dans .NET Aspire.

Pour les scénarios de production, incluez des appels à WithHostStorage() et à WithRoleAssignments(). Vous pouvez ensuite définir ce rôle explicitement, ainsi que les autres dont vous avez besoin.

Connexions de déclencheur et de liaison

Vos déclencheurs et liaisons référencent les connexions par nom. Les intégrations .NET Aspire suivantes fournissent ces connexions via un appel à WithReference() la ressource de projet :

Intégration de .NET Aspire Rôles par défaut
Stockage Blob Azure Contributeur aux données Blob du stockage,
Contributeur aux données en file d’attente du stockage,
Contributeur aux données de table du stockage
Stockage de files d'attente Azure Contributeur aux données Blob du stockage,
Contributeur aux données en file d’attente du stockage,
Contributeur aux données de table du stockage
Azure Event Hubs Propriétaire de données Azure Event Hubs
Azure Service Bus Propriétaire de données Azure Service Bus

L’exemple suivant montre un fichier minimal Program.cs pour un projet hôte d’application qui configure un déclencheur de file d’attente. Dans cet exemple, le déclencheur de file d’attente correspondant a sa propriété Connection définie sur MyQueueTriggerConnection, de sorte que l’appel à WithReference() spécifie le nom.

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

Pour d'autres intégrations, les appels à WithReference définissent la configuration d'une manière différente. Ils rendent la configuration disponible pour les intégrations clientes .NET Aspire, mais pas pour les déclencheurs et les liaisons. Pour ces intégrations, appelez WithEnvironment() pour passer les informations de connexion pour le déclencheur ou la liaison à résoudre.

L’exemple suivant montre comment définir la variable MyBindingConnection d’environnement d’une ressource qui expose une expression de chaîne de connexion :

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

Si vous souhaitez que les intégrations clientes .NET Aspire et le système de déclencheurs et de liaisons utilisent une connexion, vous pouvez configurer à la fois WithReference() et WithEnvironment().

Pour certaines ressources, la structure d’une connexion peut être différente entre le moment où vous l’exécutez localement et celui où vous la publiez sur Azure. Dans l’exemple précédent, otherIntegration peut être une ressource qui s’exécute en tant qu’émulateur de sorte que ConnectionStringExpression retourne une chaîne de connexion d’émulateur. Toutefois, lorsque la ressource est publiée, .NET Aspire peut configurer une connexion basée sur une identité et ConnectionStringExpression retournerait l’URI du service. Dans ce cas, pour configurer des connexions basées sur des identités pour Azure Functions, vous devrez peut-être fournir un autre nom de variable d’environnement.

L’exemple suivant utilise builder.ExecutionContext.IsPublishMode pour ajouter conditionnellement le suffixe nécessaire :

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

Pour plus d’informations sur les formats de connexion pris en charge par chaque liaison et les autorisations requises par ces formats, consultez les pages de référence de la liaison.

Hébergement de l’application

Par défaut, lorsque vous publiez un projet Azure Functions sur Azure, il est déployé sur Azure Container Apps.

Pendant la période d’évaluation, les ressources de l’application conteneur ne prennent pas en charge la mise à l’échelle pilotée par les événements. La prise en charge d’Azure Functions n’est pas disponible pour les applications déployées dans ce mode. Si vous devez ouvrir un ticket de support, sélectionnez le type de ressource Azure Container Apps.

Considérations et bonnes pratiques

Tenez compte des points suivants lorsque vous évaluez l’intégration d’Azure Functions à .NET Aspire :

  • La prise en charge de l’intégration est actuellement en préversion.

  • La configuration du déclencheur et de la liaison via .NET Aspire est actuellement limitée à des intégrations spécifiques. Pour plus d’informations, consultez La configuration de connexion avec .NET Aspire dans cet article.

  • Votre Program.cs fichier doit utiliser la IHostApplicationBuilder version du démarrage de l’instance hôte. IHostApplicationBuilder vous permet d’appeler builder.AddServiceDefaults() pour ajouter le service Aspire .NET par défaut à votre projet Functions.

  • .NET Aspire utilise OpenTelemetry pour la surveillance. Vous pouvez configurer .NET Aspire pour exporter des données vers Azure Monitor via le projet par défaut du service.

    Dans de nombreux autres contextes Azure Functions, vous pouvez inclure l’intégration directe à Application Insights en inscrivant le service worker. Nous ne recommandons pas ce type d’intégration dans .NET Aspire. Il peut entraîner des erreurs d’exécution avec la version 2.22.0 de Microsoft.ApplicationInsights.WorkerService, bien que la version 2.23.0 résout ce problème. Lorsque vous utilisez .NET Aspire, supprimez toutes les intégrations Application Insights directes de votre projet Functions.

  • Pour les projets Functions inscrits dans une orchestration .NET Aspire, la plupart de la configuration de l’application doit provenir du projet hôte d’application Aspire .NET. Évitez de définir des éléments dans local.settings.json, autre que le FUNCTIONS_WORKER_RUNTIME paramètre. Si vous définissez la même variable d’environnement dans local.settings.json et .NET Aspire, le système utilise la version de .NET Aspire.

  • Ne configurez pas l’émulateur stockage Azure pour les connexions dans local.settings.json. De nombreux modèles de démarrage Functions incluent l’émulateur par défaut pour AzureWebJobsStorage. Toutefois, la configuration de l’émulateur peut inviter certains outils de développement à démarrer une version de l’émulateur qui peut entrer en conflit avec la version utilisée par .NET Aspire.