Développer localement avec le CLI swa

Cet article fait partie de la série Azure Static Web Apps avec Blazor.

Un exemple complet et fonctionnel est disponible ici : mongeon/code-examples · azure-swa-blazor/05-local-dev-cli.

Dans l’article 3, on a contourné le problème du développement local en configurant le HttpClient pour pointer directement vers le port d’Azure Functions. Ça fonctionne, mais ça ne reproduit pas le comportement de SWA en production : le proxy, le routing /api/, les routes protégées, l’authentification. Le CLI swa existe pour régler tout ça.

Installer les outils

Vous avez besoin de deux choses :

# Le CLI de Static Web Apps
npm install -g @azure/static-web-apps-cli

# Azure Functions Core Tools (si pas déjà installé)
npm install -g azure-functions-core-tools@4

Vérifiez que tout est en place :

swa --version
func --version

La commande swa start

Le CLI swa agit comme le proxy de SWA en production. Il écoute sur http://localhost:4280 et redirige les requêtes vers votre app Blazor et votre API Functions. Toutes les requêtes vers /api/* passent par le proxy, exactement comme en production.

La commande de base pour notre projet :

swa start http://localhost:5000 --run "dotnet run --project Client.csproj" --api-location Api

Ça fait trois choses en une seule commande. D’abord, ça lance votre projet Blazor avec dotnet run et attend qu’il soit disponible sur le port 5000. Ensuite, ça démarre Azure Functions Core Tools dans le dossier Api. Enfin, ça lance le proxy SWA sur http://localhost:4280 qui relie les deux.

Vous accédez à votre app sur http://localhost:4280, pas sur localhost:5000. C’est le port du proxy qui reproduit le comportement de SWA.

Utiliser swa init pour la configuration

Plutôt que de taper la commande complète à chaque fois, vous pouvez initialiser un fichier de configuration :

swa init

Le CLI va vous poser quelques questions sur votre projet et générer un fichier swa-cli.config.json à la racine :

{
  "$schema": "https://aka.ms/azure/static-web-apps-cli/schema",
  "configurations": {
    "azure-swa-blazor": {
      "appLocation": ".",
      "apiLocation": "Api",
      "outputLocation": "wwwroot",
      "appDevserverUrl": "http://localhost:5000",
      "run": "dotnet run --project Client.csproj",
      "apiDevserverUrl": ""
    }
  }
}

Après ça, un simple swa start suffit. Le CLI lit la config et lance tout correctement.

L’émulation de l’authentification

C’est probablement la feature la plus utile du CLI pour le développement. Quand vous accédez à /.auth/login/github via le proxy local, le CLI ne vous envoie pas chez GitHub. Il affiche plutôt un formulaire qui vous laisse simuler un login en choisissant un nom d’utilisateur, un provider et des rôles.

Ça veut dire que vous pouvez tester vos pages protégées et vos <AuthorizeView> sans avoir à configurer de vrais fournisseurs d’authentification. Le /.auth/me retourne les infos du user simulé, et le header x-ms-client-principal est injecté dans les requêtes API, exactement comme en production.

Pour tester différents rôles, déconnectez-vous via /.auth/logout, puis reconnectez-vous en spécifiant les rôles voulus dans le formulaire. C’est très pratique pour valider que vos routes protégées et votre logique de rôles fonctionnent correctement.

Le fichier staticwebapp.config.json en local

Le CLI respecte votre staticwebapp.config.json. Les routes protégées, les redirections, les headers, tout est appliqué localement. Si vous avez configuré une route /admin/* qui nécessite le rôle authenticated, le CLI va bloquer l’accès si vous n’êtes pas “connecté” via l’émulation.

Si le CLI ne trouve pas votre fichier de config, spécifiez son emplacement avec --swa-config-location :

swa start http://localhost:5000 --api-location Api --swa-config-location Client/wwwroot

Lancer l’API séparément

Parfois, c’est pratique de lancer Azure Functions dans un terminal séparé pour voir ses logs plus clairement. Dans ce cas, démarrez Functions vous-même :

cd Api
func start --port 7071

Et pointez le CLI vers le serveur qui tourne déjà :

swa start http://localhost:5000 --api-location http://localhost:7071

Quand --api-location reçoit une URL au lieu d’un chemin de dossier, le CLI sait qu’il doit proxier vers un serveur existant plutôt que d’en démarrer un.

Le debug dans Visual Studio

Si vous utilisez Visual Studio, vous pouvez configurer la solution pour lancer les deux projets en même temps. Clic droit sur la solution > Configure Startup Projects > Multiple startup projects, et mettez Client et Api en “Start”.

Visual Studio va lancer les deux projets en debug. Vous pouvez mettre des breakpoints dans votre code Blazor et dans vos Functions. Par contre, vous perdez le proxy SWA. Pour avoir le proxy en plus du debug, lancez swa start dans un terminal séparé en pointant vers les ports de Visual Studio.

Une approche qui fonctionne bien : lancez les deux projets en debug dans Visual Studio, puis dans un terminal :

swa start http://localhost:5000 --api-location http://localhost:7071

Vous gardez le debug avec breakpoints et vous avez le proxy SWA avec l’émulation d’auth.

Ce qui peut accrocher

Le port de Blazor peut changer. Vérifiez dans Properties/launchSettings.json de votre projet Client sur quel port il écoute. Si c’est 5292 au lieu de 5000, ajustez la commande swa start en conséquence.

Le CLI télécharge les Functions Core Tools automatiquement s’il ne les trouve pas, ce qui peut surprendre la première fois. C’est généralement mieux d’installer les Core Tools vous-même pour contrôler la version.

Les fichiers statiques en développement. Si vous utilisez --run avec dotnet run ou dotnet watch, le CLI proxie vers le dev server de Blazor et sert les fichiers dynamiquement. Pas besoin de faire un dotnet publish avant.

Hot reload fonctionne. Si vous utilisez dotnet watch run au lieu de dotnet run, les changements dans vos fichiers Razor se reflètent automatiquement dans le navigateur via le proxy.

Dans le prochain et dernier article de la série, on va explorer les preview environments : comment chaque pull request génère un environnement complet avec sa propre URL.

Articles de la série

C’est quoi une Azure Static Web App?
Le fichier staticwebapp.config.json
Brancher une API Azure Functions
L’authentification intégrée de SWA
Développer localement avec le CLI swa (Cet article)
Les preview environments sur les PR

Bon déploiement, et si le port 4280 est déjà pris, le CLI va vous le dire assez clairement.

Cet article a été rédigé avec l’aide de l’IA et révisé par moi.