Utiliser Azure Functions Core Tools

Azure Functions Core Tools vous permet de développer et de tester vos fonctions sur votre ordinateur local à partir de l’invite de commandes ou du terminal. Vos fonctions locales peuvent être connectées aux services Azure actifs, et vous pouvez déboguer vos fonctions sur votre ordinateur local à l’aide du runtime Functions complet. Vous pouvez même déployer une application de fonction sur votre abonnement Azure.

Notes

Ne mélangez pas un développement local avec un développement de portail dans une même application de fonction. Lorsque vous créez et publiez des fonctions à partir d'un projet local, vous ne devez pas maintenir ni modifier le code du projet dans le portail.

Développez des fonctions sur votre ordinateur local et publiez-les sur Azure à l’aide de Core Tools en suivant ces étapes de base :

Prérequis

Les prérequis spécifiques pour Core Tools dépendent des fonctionnalités que vous envisagez d’utiliser :

Publier : Core Tools dépend d’Azure CLI ou d’Azure PowerShell pour l’authentification auprès de votre compte Azure. Cela signifie que vous devez installer l’un de ces outils pour pouvoir publier sur Azure à partir d’Azure Functions Core Tools.

Installer les extensions : pour installer manuellement des extensions avec Core Tools, vous devez avoir installé le SDK .NET Core 3.1. Core Tools installe le kit SDK .NET Core pour installer des extensions à partir de NuGet. Vous n’avez pas besoin de connaître .NET pour utiliser les extensions Azure Functions.

Versions de Core Tools

Il existe quatre versions d’Azure Functions Core Tools. La version que vous utilisez dépend de votre environnement de développement local, du choix du langage et du niveau de prise en charge requis.

Choisissez un onglet version ci-dessous pour en savoir plus sur chaque version spécifique et pour obtenir des instructions d’installation détaillées :

Prend en charge la version 4.x du runtime Functions. Ces versions prennent en charge Windows, macOS et Linux, et utilisent des gestionnaires de package spécifiques à la plateforme ou npm pour l’installation. Il s’agit de la version recommandée du runtime Functions et des outils principaux.

Vous ne pouvez installer qu’une seule version de Core Tools sur un ordinateur donné. Sauf indication contraire, les exemples de cet article concernent la version 3.x.

Installer Azure Functions Core Tools

Azure Functions Core Tools inclut une version du même runtime qu’Azure Functions, que vous pouvez exécuter sur votre ordinateur de développement local. Il fournit également des commandes pour créer des fonctions, se connecter à Azure et déployer des projets de fonction.

À partir de la version 2.x, les outils de base s’exécutent sur Windows, macOS et Linux.

Les étapes suivantes utilisent un programme d’installation Windows (MSI) pour installer Core Tools v4.x. Pour plus d’informations sur les autres programmes d’installation basés sur des packages, consultez le fichier Lisezmoi des outils principaux.

Téléchargez et exécutez le programme d’installation de Core Tools, selon votre version de Windows :

Modifier les versions des Outils principaux

Lorsque vous passez à une autre version des outils principaux, vous devez utiliser le même gestionnaire de package que l’installation d’origine pour passer à une autre version de package. Par exemple, si vous avez installé la version 2. x des outils principaux à l’aide de NPM, vous devez utiliser la commande suivante pour effectuer une mise à niveau vers la version 3. x :

npm install -g azure-functions-core-tools@3 --unsafe-perm true

Si vous avez utilisé Windows installer (MSI) pour installer les outils principaux sur Windows, vous devez désinstaller l’ancienne version de la fonction ajout/suppression de programmes avant d’installer une autre version.

Créer un projet Functions local

Un répertoire de projet Functions contient les fichiers et dossiers suivants, quel que soit le langage :

Nom de fichier Description
host.json Pour plus d’informations, consultez la référence host.json.
local.settings.json Paramètres utilisé par les outils de base lors de l’exécution locale, y compris les paramètres de l’application. Pour en savoir plus, consultez paramètres locaux.
.gitignore Empêche la publication accidentelle du fichier local.settings.json dans un référentiel Git. Pour en savoir plus, consultez paramètres locaux.
.vscode\extensions.json Fichier de paramètres utilisé lors de l’ouverture du dossier du projet dans Visual Studio Code.

Pour en savoir plus sur la structure du projet Functions, consultez le Guide de développement Azure Functions.

Dans la fenêtre du terminal ou à partir d’une invite de commandes, exécutez la commande suivante pour créer le projet et le référentiel Git local :

func init MyFunctionProj

Cet exemple crée un projet Functions dans un nouveau dossier MyFunctionProj. Vous êtes invité à choisir un langage par défaut pour votre projet.

Les considérations suivantes s’appliquent à l’initialisation d’un projet :

  • Si vous ne fournissez pas l’option --worker-runtime dans la commande, vous êtes invité à choisir votre langage. Pour plus d’informations, consultez les informations de référence sur func init.

  • Lorsque vous ne fournissez pas de nom de projet, le dossier actif est initialisé.

  • Si vous envisagez de publier votre projet sur un conteneur Linux personnalisé, utilisez l’option --docker pour vous assurer qu’un fichier Dockerfile est généré pour votre projet. Pour en savoir plus, consultez Créer une fonction sur Linux en utilisant une image personnalisée.

Certains langages peuvent avoir des considérations supplémentaires :

  • Core Tools vous permet de créer des projets d’application de fonction pour le runtime .NET en tant que projets de bibliothèque de classes C# (.csproj) in-process et de processus Worker isolé. Ces projets, qui peuvent être utilisés avec Visual Studio ou Visual Studio Code, sont compilés pendant le débogage et lors de la publication sur Azure.

  • Utilisez le paramètre --csx si vous souhaitez travailler localement avec des fichiers de script C# (.csx). Il s’agit des mêmes fichiers que ceux que vous recevez lorsque vous créez des fonctions dans le Portail Azure et lorsque vous utilisez la version 1.x des outils de base. Pour plus d’informations, consultez les informations de référence sur func ini.

Inscrire des extensions

À partir de la version 2. x du runtime, les liaisons et les déclencheurs de fonctions sont implémentés en tant que packages d’extension .NET (NuGet). Pour les projets C# compilés, il vous suffit de référencer les packages d’extension NuGet pour les déclencheurs et les liaisons spécifiques que vous utilisez. Les liaisons HTTP et les déclencheurs de minuteur ne nécessitent pas d’extensions.

Pour améliorer l’expérience de développement pour les projets non-C#, Functions vous permet de référencer un bundle d’extension avec version dans votre fichier host.json de projet. Les packages d’extension rendent toutes les extensions disponibles pour votre application et suppriment les risques de problèmes de compatibilité entre les extensions. Les packages d’extension éliminent également la nécessité d’installer le kit de développement logiciel .NET Core 3.1. et d’avoir à gérer le fichier extensions.csproj.

Les packages d’extension constituent l’approche recommandée pour les projets Functions autres que les projets conformes à C#, ainsi que le script C#. Pour ces projets, le paramètre de groupe d’extension est généré dans le fichier host.json au cours de l’initialisation. Si les packs ne sont pas activées, vous devez mettre à jour le fichier host.json du projet.

Le moyen le plus simple d’installer les extensions de liaison consiste à activer les offres groupées d’extension. Lorsque vous activez les offres groupées, un ensemble prédéfini de packages d’extension sont automatiquement installés.

Pour activer les offres groupées d’extension, ouvrez le fichier host.json et mettez à jour son contenu pour qu’il corresponde au code suivant :

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[2.*, 3.0.0)"
    }
}

Pour en savoir plus, consultez Inscrire des extensions de liaison Azure Functions.

Il peut y avoir des cas dans un projet autre que .NET dans lesquels vous ne pouvez pas utiliser les packages d’extension, par exemple lorsque vous devez cibler la version spécifique d’une extension qui n’est pas dans le bundle. Dans ce cas, vous pouvez utiliser les outils de base pour installer localement les packages d’extension nécessaires à votre projet. Pour plus d’informations, consultez Installer les extensions.

Paramètres locaux

Lors de l’exécution dans une application de fonction dans Azure, les paramètres requis par vos fonctions sont stockés de manière sécurisée dans les paramètres de l’application. Lors du développement local, ces paramètres sont, à la place, ajoutés à l'Valuesobjet dans le fichier local.settings.json. Le fichier local.settings.json stocke également les paramètres utilisés par les outils de développement locaux.

Étant donné que le fichier local.settings.json peut contenir des secrets, tels que des chaînes de connexion, vous ne devez jamais le stocker dans un référentiel distant. Pour en savoir plus sur les paramètres locaux, consultez le Fichier de paramètres locaux.

Par défaut, ces paramètres ne sont pas migrés automatiquement lorsque le projet est publié dans Azure. Utilisez l’option --publish-local-settings lors de la publication pour vous assurer que ces paramètres sont ajoutés à l’application de fonction dans Azure. Les valeurs de la section ConnectionStrings ne sont jamais publiées.

Ces valeurs de paramètres d’application de fonction peuvent aussi être lues dans votre code en tant que variables d’environnement. Pour plus d’informations, consultez la section Variables d’environnement de ces rubriques de référence spécifiques à une langue :

Si aucune chaîne de connexion de stockage valide n’est définie pour AzureWebJobsStorage et qu’aucun émulateur de stockage local n’est utilisé, le message d’erreur suivant s’affichera :

Valeur manquante pour AzureWebJobsStorage dans local.settings.json. Cette valeur est nécessaire pour tous les déclencheurs autres que HTTP. Vous pouvez exécuter 'func azure functionapp fetch-app-settings <functionAppName>' ou spécifier une chaîne de connexion dans local.settings.json.

Obtenir vos chaînes de connexion de stockage

Même si vous utilisez l’émulateur de stockage Azure pour le développement, vous pouvez exécuter localement votre configuration avec une connexion de stockage. Si vous avez déjà créé un compte de stockage, vous pouvez obtenir une chaîne de connexion de stockage valide de plusieurs façons :

  1. Dans le Azure portal, recherchez et sélectionnez Comptes de stockage.

    Sélectionner des comptes de stockage à partir du Portail Azure

  2. Sélectionnez votre compte de stockage, sélectionnez Clés d’accès dans Paramètres, puis copiez une des valeurs Chaîne de connexion.

    Copier une chaîne de connexion à partir du portail Azure

Créer une fonction

Pour créer une fonction dans un projet existant, exécutez la commande suivante :

func new

Dans la version 3.x/2.x, lorsque vous exécutez func new, vous êtes invité à choisir un modèle dans le langage par défaut de votre application de fonction. Ensuite, vous êtes invité à choisir le nom de votre fonction. Dans la version 1.x, vous êtes également invité à choisir le langage.

Vous pouvez également spécifier le nom et le modèle de la fonction dans la commande func new. L’exemple suivant utilise l’option --template pour créer un déclencheur HTTP nommé MyHttpTrigger :

func new --template "Http Trigger" --name MyHttpTrigger

Cet exemple crée un déclencheur de file d’attente de stockage nommé MyQueueTrigger :

func new --template "Azure Queue Storage Trigger" --name MyQueueTrigger

Pour plus d’informations, consultez la commande func new.

Exécuter des fonctions localement

Pour exécuter un projet Functions, vous exécutez l’hôte Functions à partir du répertoire racine de votre projet. L’hôte active les déclencheurs pour toutes les fonctions du projet. La commande start varie selon le langage de votre projet.

func start

Notes

La version 1.x du runtime Functions, en revanche, exige func host start. Pour en savoir plus, consultez Référence Azure Functions Core Tools.

Quand l’hôte Functions démarre, il génère l’URL des fonctions déclenchées par HTTP, comme dans l’exemple suivant :

Found the following functions:
Host.Functions.MyHttpTrigger

Job host started
Http Function MyHttpTrigger: http://localhost:7071/api/MyHttpTrigger

Important

Lors d’une exécution locale, l’autorisation n’est pas appliquée pour les points de terminaison HTTP. Cela signifie que toutes les demandes HTTP locales sont gérées de manière authLevel = "anonymous". Pour plus d’informations, consultez l’article sur la liaison HTTP.

Transmission de données de test à une fonction

Pour tester vos fonctions localement, vous démarrez l’hôte Functions et vous appelez des points de terminaison sur le serveur local avec des requêtes HTTP. Le point de terminaison que vous appelez varie selon le type de fonction.

Notes

Les exemples de cette rubrique utilisent l’outil cURL pour envoyer des requêtes HTTP à partir du terminal ou d’une invite de commandes. Vous pouvez utiliser un outil de votre choix pour envoyer les requêtes HTTP au serveur local. L’outil cURL est disponible par défaut sur les systèmes Linux et Windows 10 Build 17063 et versions ultérieures. Avec les anciennes versions de Windows, vous devez d’abord télécharger et installer l’outil cURL.

Pour des informations plus générales sur le test de fonctions, consultez Stratégies permettant de tester votre code dans Azure Functions.

Fonctions déclenchées par HTTP et par Webhook

Vous appelez le point de terminaison suivant pour exécuter localement des fonctions déclenchées par HTTP et par Webhook :

http://localhost:{port}/api/{function_name}

Vérifiez que vous utilisez le même nom de serveur et le même port que celui où l’hôte Functions écoute. Vous voyez cela dans la sortie générée lors du démarrage de l’hôte Functions. Vous pouvez appeler cette URL en utilisant n’importe quelle méthode HTTP prise en charge par le déclencheur.

La commande cURL suivante déclenche la fonction de démarrage rapide MyHttpTrigger à partir d’une demande GET avec le paramètre namepassé dans la chaîne de requête.

curl --get http://localhost:7071/api/MyHttpTrigger?name=Azure%20Rocks

L’exemple suivant est la même fonction appelée à partir d’une demande POST en passant name dans le corps de la demande :

curl --request POST http://localhost:7071/api/MyHttpTrigger --data '{"name":"Azure Rocks"}'

Notez que vous pouvez passer des requêtes GET depuis un navigateur en passant des données dans la chaîne de requêtes. Pour toutes les autres méthodes HTTP, vous devez utiliser cURL, Fiddler, Postman ou un outil de test HTTP similaire qui prend en charge les demandes POST.

Fonctions non déclenchées via HTTP

Pour toutes les fonctions autres que les déclencheurs HTTP et EventGrid, vous pouvez tester vos fonctions localement avec REST en appelant un point de terminaison spécial appelé point de terminaison d’administration. L’appel de ce point de terminaison au moyen d’une requête HTTP POST sur le serveur local déclenche la fonction.

Pour tester des fonctions Event Grid déclenchées localement, consultez Tests locaux avec une application web de visionneuse.

Vous pouvez éventuellement passer des données de test à l’exécution dans le corps de la requête POST. Cette fonctionnalité est similaire à l’onglet Test dans le portail Azure.

Vous appelez le point de terminaison d’administrateur suivant pour déclencher des fonctions non-HTTP :

http://localhost:{port}/admin/functions/{function_name}

Pour passer des données de test au point de terminaison d’administrateur d’une fonction, vous devez fournir les données dans le corps d’un message de requête POST. Le corps du message doit avoir le format JSON suivant :

{
    "input": "<trigger_input>"
}

La valeur de <trigger_input> contient des données dans un format attendu par la fonction. L’exemple cURL suivant est une demande POST adressée à une fonction QueueTriggerJS. Dans ce cas, l’entrée est une chaîne qui est équivalente au message attendu dans la file d’attente.

curl --request POST -H "Content-Type:application/json" --data '{"input":"sample queue data"}' http://localhost:7071/admin/functions/QueueTrigger

Lorsque vous appelez un point de terminaison d’administrateur sur votre application de fonction dans Azure, vous devez fournir une clé d’accès. Pour en savoir plus, consultez Clés d’accès Function.

Publication dans Azure

Les Azure Functions Core Tools prennent en charge deux types de déploiement :

Type de déploiement Commande Description
Fichiers projet func azure functionapp publish Déploie les fichiers de projet de fonction directement dans votre application de fonction à l’aide d’un déploiement zip.
Cluster Kubernetes func kubernetes deploy Déploie votre application de fonction Linux en tant que conteneur docker client sur un cluster Kubernetes.

Avant de publier

Important

L’interface de ligne de commande Azure ou Azure PowerShell doit être installé localement pour que vous puissiez publier sur Azure à partir de Core Tools.

Un dossier de projet peut contenir des fichiers et des répertoires spécifiques à une langue qui ne doivent pas être publiés. Les éléments exclus sont listés dans un fichier .funcignore situé dans le dossier racine du projet.

Vous devez avoir déjà créé une application de fonction dans votre abonnement Azure où vous prévoyez de déployer votre code. Les projets qui nécessitent une compilation doivent être générés pour favoriser le déploiements des fichiers binaires.

Pour découvrir comment créer une application de fonction à partir de l’invite de commandes ou d’une fenêtre de terminal à l’aide d’Azure CLI ou d’Azure PowerShell, consultez Créer une application de fonction pour une exécution serverless.

Important

Lorsque vous créez une application de fonction dans le portail Azure, elle utilise par défaut la version 3.x du runtime de Function. Pour que l’application de fonction utilise la version 1.x du runtime, suivez les instructions dans Exécution sur la version 1.x. Vous ne pouvez pas modifier la version du runtime pour une application de fonction qui possède des fonctions déjà existantes.

Déployer des fichiers de projet

Pour publier votre code local dans une application de fonction sur Azure, utilisez la commande publish :

func azure functionapp publish <FunctionAppName>

Les remarques suivantes s’appliquent à ce type de déploiement :

  • La publication remplace les fichiers existants dans l’application de fonction.

  • Utilisez l’option --publish-local-settings pour créer automatiquement des paramètres d’application dans votre application de fonction en fonction des valeurs dans le fichier local.settings.js.

  • Une compilation distante est effectuée sur les projets compilés. Ceci peut être contrôlé par l’option --no-build.

  • Votre projet est déployé de sorte qu’il s’exécute à partir du package de déploiement. Pour désactiver ce mode de déploiement recommandé, utilisez l’option --nozip.

  • Java utilise Maven pour publier votre projet local sur Azure. Utilisez plutôt la commande suivante pour publier sur Azure : mvn azure-functions:deploy. Les ressources Azure sont créées lors du déploiement initial.

  • Vous obtiendrez une erreur si vous tentez de publier sur une application <FunctionAppName> qui n’existe pas dans votre abonnement.

Cluster Kubernetes

Functions vous permet également de définir votre projet Functions pour qu’il s’exécute dans un conteneur Docker. Utilisez --docker option de func init pour générer un fichier Docker pour votre langage. Ce fichier est ensuite utilisé lors de la création d’un conteneur à déployer. Pour savoir comment publier un conteneur personnalisé sur Azure sans Kubernetes, consultez Créer une fonction sur Linux à l’aide d’un conteneur personnalisé.

Les outils principaux peuvent être utilisés pour déployer votre projet en tant qu’image conteneur personnalisée sur un cluster Kubernetes.

La commande suivante utilise fichier Dockerfile pour générer un conteneur et le déployer sur un cluster Kubernetes.

func kubernetes deploy --name <DEPLOYMENT_NAME> --registry <REGISTRY_USERNAME> 

Pour en savoir plus, consultez Déploiement d’une application de fonction sur Kubernetes.

Installer les extensions

Si vous ne pouvez pas utiliser les packs d’extensions, vous pouvez utiliser Azure Functions Core Tools localement pour installer les packs d’extensions spécifiques requis par votre projet.

Important

Vous ne pouvez pas installer explicitement des extensions dans une application de fonction avec les bundles d’extension installés. Tout d’abord, supprimez la section extensionBundle dans host.json avant d’installer des extensions de manière explicite.

Les éléments suivants décrivent certaines raisons pour lesquelles vous devrez peut-être installer des extensions manuellement :

  • Vous devez accéder à une version spécifique d’une extension qui n’est pas disponible dans un bundle.
  • Vous devez accéder à une extension personnalisée qui n’est pas disponible dans un bundle.
  • Vous devez accéder à une combinaison spécifique d’extensions non disponibles dans un seul bundle.

Lorsque vous installez explicitement des extensions, un fichier de projet .NET nommé extensions.csproj est ajouté à la racine de votre projet. Ce fichier définit l’ensemble des packages NuGet requis par vos fonctions. Bien que vous puissiez utiliser les références de package NuGet dans ce fichier, Core Tools vous permet d’installer des extensions sans avoir à modifier manuellement le fichier projet C#.

Il existe plusieurs façons d’utiliser les outils de base pour installer les extensions requises dans votre projet local.

Installer toutes les extensions

Utilisez la commande suivante pour ajouter automatiquement tous les packages d’extensions utilisés par les liaisons dans votre projet local :

func extensions install

La commande lit le fichier function.json pour voir les packages dont vous avez besoin, les installe et regénère le projet des extensions (extensions.csproj). Il ajoute les nouvelles liaisons à la version actuelle, mais ne met pas à jour les liaisons existantes. Utilisez l’option --force pour mettre à jour les liaisons existantes vers la dernière version pendant les nouvelles installations. Pour plus d’informations, reportez-vous à la commande func extensions install.

Si votre application de fonction utilise des liaisons ou des packages NuGet que Core Tools ne reconnaît pas, vous devez installer manuellement l’extension spécifique.

Installer une extension spécifique

Utilisez la commande suivante pour installer un package d’extension spécifique à une version spécifique, dans ce cas l’extension Storage :

func extensions install --package Microsoft.Azure.WebJobs.Extensions.Storage --version 5.0.0

Vous pouvez utiliser cette commande pour installer n’importe quel package NuGet compatible. Pour plus d’informations, consultez la commande func extensions install.

Surveillance des fonctions

Il est recommandé de superviser l’exécution de vos fonctions par l’intégration à Azure Application Insights. Vous pouvez également diffuser des journaux d’exécution sur votre ordinateur local. Pour en savoir plus, consultez Surveiller l’exécution des fonctions Azure.

Intégration d’Application Insights

L’intégration d’Application Insights doit être activée lorsque vous créez votre application de fonction dans Azure. Si, pour une raison quelconque, votre application de fonction n’est pas connectée à une instance Application Insights, il est facile d’effectuer cette intégration dans le portail Azure. Pour en savoir plus, consultez Activer l'intégration d'Application Insights.

Activer les journaux de diffusion en continu

Vous pouvez afficher un flux de fichiers journaux générés par vos fonctions dans une session de ligne de commande sur votre ordinateur local.

Streaming des journaux intégré

Utilisez la commande func azure functionapp logstream pour commencer à recevoir les journaux de streaming d’une application de fonction s’exécutant dans Azure, comme dans l’exemple suivant :

func azure functionapp logstream <FunctionAppName>

Notes

Le streaming de journaux intégré n’est pas encore activé dans Core Tools pour les applications de fonction s’exécutant sur Linux dans le cadre d’un plan Consommation. Pour ces plans d’hébergement, vous devez utiliser Flux de métriques temps réel pour voir les journaux en quasi-temps réel.

Live Metrics Stream (Flux continu de mesures)

Vous pouvez voir le Flux de métriques temps réel de votre application de fonction dans une nouvelle fenêtre de navigateur en incluant l’option --browser, comme dans l’exemple suivant :

func azure functionapp logstream <FunctionAppName> --browser

Les journaux de diffusion en continu de ce type nécessitent que l’intégration d’Application Insights soit activée pour votre application de fonction.

Étapes suivantes

Découvrez comment développer, tester et publier des fonctions Azure à l’aide d’Azure Functions Core Tools. Azure Functions Core Tools est disponible en open source et hébergé sur GitHub. Pour enregistrer un bogue ou une demande de fonctionnalité, créez un problème GitHub.