Développement local de Azure Functions : correction des points de défaillance courants

• VS Code associé à l’extension Azure Functions — ce n’est pas obligatoire, mais cela rend le débogage et la création de structures de projet bien moins pénibles

Vérification rapide à effectuer avant de continuer :

func --version
node --version    # or python --version / dotnet --version

Un écart de version entre les Core Tools et le moteur de votre langage est l’une des causes les plus insidieuses et les plus fréquentes pour lesquelles quelque chose fonctionne bien sur une machine mais échoue sur une autre.

3. Création de votre première application fonctionnelle locale

Utilisez la CLI pour créer un projet entièrement nouveau :

func init MyFunctionApp --worker-runtime node
cd MyFunctionApp
func new --name HttpTriggerExample --template "HTTP trigger"

L’exécution de ce code génère une structure de dossiers comprenant un host.json, un local.settings.json, ainsi qu’un répertoire contenant le code de votre déclencheur. host.json gère les paramètres applicables à l’ensemble du hôte, tels que le comportement de l’enregistrement des logs, les bundles d’extensions et les délais d’attente. local.settings.json est un fichier destiné uniquement à votre machine ; il provoque suffisamment de confusion lors de la première exécution pour mériter une explication dédiée.

4. Le fichier local.settings.json — À quoi sert-il et pourquoi il embrouille les utilisateurs ?

Ce fichier stocke vos variables d’environnement locales et vos chaînes de connexion. Il ne doit jamais être envoyé sur Azure ; son unique fonction est de gérer la configuration exclusive à l’ordinateur local.

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "node"
  }
}

Deux erreurs récurrentes expliquent la plupart des plaintes du type « le hôte ne démarre même pas » :

1. Oublier de définir AzureWebJobsStorage. Presque toutes les catégories de déclencheurs — Timer, Queue, Blob — dépendent d’une connexion de stockage, même lors des exécutions locales. L’utilisation de UseDevelopmentStorage=true dirige l’hôte vers Azurite plutôt qu’un compte Azure Storage en production.
2. Définir FUNCTIONS_WORKER_RUNTIME de manière incorrecte. Lorsque cette valeur ne correspond pas au langage réellement utilisé (node, python, dotnet, java, powershell), l’hôte ne chargera pas vos fonctions, ce qui se traduit généralement par une erreur vague au lieu d’indiquer clairement qu’il y a un incompatibilité de runtime.

5. Azurite : votre émulateur de stockage local (et pourquoi vous ne pouvez pas l’ignorer)

Azurite remplace Azure Storage pour tout ce qui s’exécute localement, en émulant des files d’attente, des blobs et des tables directement sur votre machine. Éviter cette étape est la cause principale des erreurs StorageException ou de refus de connexion dès qu’un déclencheur de file d’attente ou de blob est utilisé.

Démarrer l’émulateur dans une fenêtre de terminal dédiée avant d’ouvrir votre application fonctionnelle :

azurite --silent --location ./azurite-data --debug ./azurite-data/debug.log

Si vous préférez travailler depuis VS Code, l’extension Azurite vous permet de démarrer l’émulateur via une seule entrée dans la palette de commandes, sans avoir besoin d’un terminal distinct. Quelle que soit la méthode choisie, assurez-vous qu’il reste en cours d’exécution tout au long de votre session — il est très facile d’oublier qu’il n’est pas actif et de perdre dix minutes à essayer de résoudre un message « connexion échouée » qui signifie en réalité simplement que l’émulateur n’a jamais été lancé.

6. Exécution et test des fonctions déclenchées par HTTP

Lorsque Azurite est prêt, lancez votre application fonctionnelle :

func start

Votre terminal affichera l’URL locale de chaque fonction, à peu près comme ceci :

Http Functions:
    HttpTriggerExample: [GET,POST] http://localhost:7071/api/HttpTriggerExample

Vous pouvez y accéder avec curl, Postman ou un navigateur si c’est une requête GET :

curl "http://localhost:7071/api/HttpTriggerExample?name=Dev"

Si vous n’obtenez aucun retour plutôt qu’une réponse, cherchez une collision de port : un processus func start resté en arrière-plan, ou une autre instance, pourrait déjà occuper le port 7071. Arrêter les processus inutiles de Functions (recherchez func dans Gestionnaire des tâches, ou exécutez pkill -f func sous macOS/Linux) résout généralement ce problème immédiatement.

7. Tester les déclencheurs non HTTP localement (Timer, Queue, Blob, Service Bus)

Les déclencheurs HTTP constituent le cas simple. Les autres nécessitent une préparation supplémentaire :

• Déclencheurs de minuterie s’activent automatiquement selon leur plan CRON dès le démarrage de l’hôte, sans aucune exigence supplémentaire. Pour effectuer des tests plus tôt, vous pouvez ajouter temporairement "RunOnStartup": true à la définition du déclencheur afin qu’il se déclenche immédiatement.
• Déclencheurs de file d’attente nécessitent un message réel en attente dans une file d’attente gérée par Azurite. Vous pouvez ajouter un message de test via l’Azure Storage Explorer, qui communique avec Azurite exactement comme il le ferait avec un compte de stockage réel, ou par l’intermédiaire de l’extension de stockage de l’Azure CLI destinée à votre chaîne de connexion locale.

C’est l’un des véritables défauts du développement local avec Functions : certains types de déclencheurs ne peuvent tout simplement pas être entièrement reproduits localement, et les traiter comme s’ils le pouvaient ne fait que gaspiller votre temps.

8. Débogage dans VS Code

C’est ici que la configuration locale commence réellement à se montrer utile. Une fois l’extension Azure Functions installée :

1. Ouvrez le dossier de votre projet dans VS Code.
2. Placez des points d’arrêt là où vous en avez besoin à l’intérieur du code déclencheur.
3. Appuyez sur F5 — VS Code s’occupe de compiler le projet, de démarrer Azurite si c’est configuré ainsi, de lancer l’hôte des Functions et d’attacher le débogueur, tout cela sans aucune action manuelle.

Les fichiers .vscode/launch.json et tasks.json générés automatiquement coordonnent tout cela en arrière-plan. Si les points d’arrêt n’arrêtent pas l’exécution, vérifiez que la configuration preLaunchTask dans launch.json récompile bien votre code avant le démarrage de l’hôte — une compilation obsolète est une cause subtile mais fréquente pour laquelle les points d’arrêt semblent être ignorés.

9. Erreurs courantes et moyens de les corriger réellement

Cette ligne en particulier provoque plus de confusion chez les développeurs que tout défaut réel au sein du runtime des Functions eux-mêmes. local.settings.json est délibérément omis de votre package de déploiement pour des raisons de sécurité, ce qui signifie que toute valeur secrète ou de configuration stockée là ne sera pas automatiquement transmise avec votre application vers Azure — vous devez l’ajouter séparément, soit via le portail Azure, soit à l’aide des outils CLI ou de pipeline.

10. Exécuter les Functions localement avec Docker

Si votre équipe souhaite que les environnements locaux et de production soient identiques — ou si vous devez valider un conteneur Linux personnalisé — Azure Functions propose également une solution basée sur Docker :

func init MyFunctionApp --worker-runtime node --docker
cd MyFunctionApp
docker build -t my-function-app .
docker run -p 7071:80 -it my-function-app

Cette approche entraîne plus de surcoût par rapport à une simple fonction func start, mais elle élimine toute une catégorie de problèmes du type « ça marche sur ma machine », en particulier pour les équipes qui déploient dans des conteneurs personnalisés ou qui ont besoin d’une cohérence stricte au niveau du système d’exploitation avec ce qui fonctionne en production.

11. Gérer les secrets et les variables d’environnement de la bonne manière

N’ajoutez pas local.settings.json au contrôle de version. Il est conçu pour contenir des chaînes de connexion réelles pendant le développement, et les projets prédéfinis l’excluent par défaut de git — vérifiez bien votre .gitignore pour en être sûr. Lorsque vous travaillez en équipe :

• Partagez une version filtrée, comme local.settings.json.example, remplie de valeurs de remplacement plutôt que de vrais secrets.

12. Bonnes pratiques pour un cycle de développement local fluide

• Démarrez Azurite avant d’activer l’hôte Functions — l’ordre est important, car certains déclencheurs vérifient le stockage dès leur démarrage.
• Précisez la version des outils de base utilisée par votre équipe, que ce soit dans vos documents ou dans un script de configuration. Les incohérences de version entre les machines constituent un frein discret mais réel à la productivité.
• Exécutez func start --verbose chaque fois que vous rencontrez un problème de démarrage — le niveau de journalisation par défaut cache souvent la cause réelle.
• Redémarrez l’hôte chaque fois que vous modifiez host.json ou local.settings.json ; aucun de ces fichiers n’est pris en compte lors du chargement dynamique.
• Gardez une ressource Azure de niveau bas disponible pour des types de déclencheurs tels que Service Bus ou Event Grid qui ne peuvent pas être entièrement reproduits dans un émulateur local.

Considerations finales

func start cesse d’être perçu comme un pari et devient simplement une commande de routine.

Si l’on doit retenir une seule habitude à partir de tout cela, c’est bien celle-ci : vérifiez toujours si Azurite est réellement en cours d’exécution avant de commencer à diagnostiquer quoi que ce soit d’autre. Cette seule négligence coûte silencieusement plus de temps que n’importe quel véritable bug dans votre code.

Lectures complémentaires

• Référence des commandes Node.js pour les serveurs de développement local et en production — Une référence des commandes facile à parcourir couvrant la gestion des versions de Node.js, les gestionnaires de paquets, l’installation de l’environnement, le débogage, PM2, ainsi que les déploiements Linux sans interruption.