Configurer le développement local pour Azure Static Web Apps

Article
02/07/2024

Lorsqu'il est publié dans le cloud, un site Azure Static Web Apps englobe de nombreux services qui fonctionnent ensemble comme s'il s'agissait de la même application. Ces services comprennent :

L'application web statique
L'API Azure Functions
Les services d'authentification et d'autorisation
Les services de routage et de configuration

Ces services doivent communiquer entre eux, et Azure static Web Apps gère cette intégration pour vous dans le cloud.

Toutefois, lorsque vous exécutez votre application localement, ces services ne sont pas automatiquement liés.

Pour offrir une expérience similaire à celle dont vous bénéficiez dans Azure, l'interface de ligne de commande (CLI) Azure Static Web Apps fournit les services suivants :

Un serveur local de sites statiques
Un proxy vers le serveur de développement de l'infrastructure frontale
Un proxy vers vos points de terminaison d'API, disponible via Azure Functions Core Tools
Un serveur d'authentification et d'autorisation fictif
La mise en œuvre des itinéraires et paramètres de configuration locaux

Remarque

Souvent, les sites créés avec une infrastructure frontale requièrent un paramètre de configuration de proxy pour gérer correctement les demandes sous l’itinéraire api. En cas d’utilisation de la CLI d’Azure Static Web Apps, la valeur de l’emplacement du proxy est /api et, sans la CLI, la valeur est http://localhost:7071/api.

Fonctionnement

Le graphique suivant montre comment les demandes sont gérées localement.

Diagram showing the Azure Static Web App CLI request and response flow.

Important

Accédez à http://localhost:4280 pour accéder à l’application servie par l’interface CLI.

Les demandes adressées au port 4280 sont transférées vers le serveur approprié en fonction de leur type.
Les demandes de contenu statique, telles que HTML ou CSS, sont gérées par le serveur de contenu statique de l'interface CLI interne ou par le serveur de l'infrastructure frontale à des fins de débogage.
Les demandes d'authentification et d'autorisation sont gérées par un émulateur, qui fournit un profil d'identité factice à votre application.
Le runtime Functions Core Tools¹ gère les demandes envoyées à l'API du site.
Les réponses de tous les services sont renvoyées au navigateur comme s'il s’agissait d'une seule et même application.

Dès que vous démarrez l’interface utilisateur et les applications API Azure Functions indépendamment, démarrez l’interface CLI Static Web Apps et pointez-la sur les applications en cours d’exécution en utilisant la commande suivante :

swa start http://localhost:<DEV-SERVER-PORT-NUMBER> --api-location http://localhost:7071

Si vous utilisez la commande swa init, l’interface CLI Static Web Apps examine le code de votre application et crée un fichier de configuration swa-cli.config.json pour l’interface CLI. Lorsque vous utilisez le fichier swa-cli.config.json, vous pouvez exécuter swa start pour lancer votre application localement.

¹ Les outils Azure Functions Core Tools sont automatiquement installés par l’interface CLI s’ils ne sont pas déjà sur votre système.

L’article suivant détaille les étapes d’exécution d’une application basée sur des nœuds, mais le processus est le même pour n’importe quel langage ou environnement.

Prérequis

Site Azure Static Web Apps existant : si vous n'en avez pas, commencez avec l'application de démarrage vanilla-api.
Node.js avec npm : exécutez la version Node.js LTS, qui inclut l'accès à npm.
Visual Studio Code : utilisé pour le débogage de l'application API, mais non requis pour l'interface CLI.

Bien démarrer

Ouvrez un terminal dans le dossier racine de votre site Azure Static Web Apps existant.

Installez l'interface CLI.
```
npm install -D @azure/static-web-apps-cli
```
Conseil

Si vous souhaitez installer l’interface CLI SWA globalement, utilisez -g à la place de -D. Toutefois, il est vivement recommandé d’installer SWA en tant que dépendance de développement.
Si nécessaire, générez votre application.

Exécutez npm run build, ou la commande équivalente de votre projet.
Initialisez le référentiel pour l’interface CLI.
```
swa init
```
Répondez aux questions posées par l’interface CLI pour vérifier que vos paramètres de configuration sont corrects.
Démarrez l'interface CLI.
```
swa start
```
Accédez à http://localhost:4280 pour voir l’application dans le navigateur.

Autres façons de démarrer l'interface CLI

Description	Commande	Commentaires
Servir un dossier spécifique	`swa start ./<OUTPUT_FOLDER_NAME>`	Remplacez `<OUTPUT_FOLDER_NAME>` par le nom de votre dossier de sortie.
Utiliser un serveur de développement d'infrastructure en cours d'exécution	`swa start http://localhost:3000`	Cette commande fonctionne lorsque vous disposez d’une instance de votre application s’exécutant sous le port `3000`. Mettez à jour le numéro de port si votre configuration est différente.
Démarrer une application Functions dans un dossier	`swa start ./<OUTPUT_FOLDER_NAME> --api-location ./api`	Remplacez `<OUTPUT_FOLDER_NAME>` par le nom de votre dossier de sortie. Cette commande s’attend à ce que l’API de votre application dispose de fichiers dans le `api` dossier. Mettez à jour cette valeur si votre configuration est différente.
Utiliser une application Functions en cours d'exécution	`swa start ./<OUTPUT_FOLDER_NAME> --api-location http://localhost:7071`	Remplacez `<OUTPUT_FOLDER_NAME>` par le nom de votre dossier de sortie. Cette commande s’attend à ce que votre application Azure Functions soit disponible via le port `7071`. Mettez à jour le numéro de port si votre configuration est différente.

Émulation d'autorisation et d'authentification

L'interface CLI Static Web Apps émule le flux de sécurité implémenté dans Azure. Lorsqu'un utilisateur se connecte, vous pouvez définir un profil d'identité factice renvoyé à l'application.

Par exemple, lorsque vous tentez d’accéder à /.auth/login/github, une page est renvoyée pour vous permettre de définir un profil d’identité.

Remarque

L'émulateur fonctionne avec n'importe quel fournisseur de sécurité, pas seulement GitHub.

Local authentication and authorization emulator

L'émulateur présente une page qui vous permet de fournir les valeurs suivantes pour le principal de client :

Valeur	Description
Nom d’utilisateur	Nom du compte associé au fournisseur de sécurité. Cette valeur apparaît en tant que propriété `userDetails` dans le principal de client, et elle est générée automatiquement si vous ne fournissez pas de valeur.
Code utilisateur	Valeur générée automatiquement par l'interface CLI.
Rôles	Liste de noms de rôles, chaque nom figurant sur une nouvelle ligne.
Revendications	Liste de revendications utilisateur, chaque nom figurant sur une nouvelle ligne.

Une fois connecté :

Vous pouvez utiliser le point de terminaison /.auth/me ou un point de terminaison de fonction pour récupérer le principal de clientde l'utilisateur.
La navigation pour /.auth/logout effacer le principal du client et déconnecter l’utilisateur fictif.

Débogage

Il existe deux contextes de débogage dans une application web statique. Le premier concerne le site de contenu statique et le second les fonctions API. Un débogage local est possible en permettant à l'interface CLI Static Web Apps d'utiliser des serveurs de développement pour l'un ou l'autre de ces contextes (ou les deux).

Les étapes suivantes présentent un scénario commun qui utilise des serveurs de développement pour les deux contextes de débogage.

Démarrez le serveur de développement de site statique. Cette commande est spécifique à l'infrastructure frontale que vous utilisez, mais elle est souvent fournie sous forme de commandes telles que npm run build, npm start ou npm run dev.
Ouvrez le dossier de l'application API dans Visual Studio Code et démarrez une session de débogage.
Démarrez l’interface CLI de Static Web Apps en utilisant la commande suivante.
```
swa start http://localhost:<DEV-SERVER-PORT-NUMBER> --appDevserverUrl http://localhost:7071
```
Remplacez <DEV_SERVER_PORT_NUMBER> par le numéro de port du serveur de développement.

Les captures d'écran suivantes illustrent les terminaux d'un scénario de débogage classique :

Le site de contenu statique s'exécute via npm run dev.

Static site development server

L'application API Azure Functions exécute une session de débogage dans Visual Studio Code.

Visual Studio Code API debugging

L'interface CLI Static Web Apps est lancée à l'aide des deux serveurs de développement.

Azure Static Web Apps CLI terminal

Désormais, les demandes qui passent par le port 4280 sont acheminées vers le serveur de développement de contenu statique ou la session de débogage d'API.

Pour plus d'informations sur les différents scénarios de débogage, avec des conseils sur la personnalisation des ports et des adresses de serveur, consultez le Référentiel de l'interface CLI Azure Static Web Apps.

Exemple de configuration de débogage

Visual Studio Code utilise un fichier pour activer des sessions de débogage dans l’éditeur. Si Visual Studio Code ne génère pas de fichier launch.json pour vous, vous pouvez placer la configuration suivante dans .vscode/launch.json.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Attach to Node Functions",
            "type": "node",
            "request": "attach",
            "port": 9229,
            "preLaunchTask": "func: host start"
        }
    ]
}

Étapes suivantes

Configurer votre application

Partager via