Développer en ASP.NET Framework 4.x sur macOS avec ServBay

Grâce à son environnement Mono performant intégré, ServBay permet de développer et tester facilement des applications ASP.NET Framework 1.1/2.0/3.x/4.x (jusqu’à 4.7.x inclus) sur macOS.

À partir de la version ServBay v1.12.0, Mono 6.14.0 est inclus, avec le serveur de développement XSP ainsi que l’outil fastcgi-mono-server. Vous disposez ainsi de deux principales méthodes pour exécuter vos applications ASP.NET Framework 4.x :

Développement et test rapide avec XSP : XSP est un serveur web léger conçu pour Mono, idéal pour le développement et les tests rapides.
Déploiement Nginx + FastCGI : Cette solution offre plus de stabilité et de performances et simule mieux un environnement de production en relayant les requêtes du client depuis Nginx (géré par ServBay) vers le backend Mono.

Ce guide vous accompagne dans la configuration et l’exécution de votre projet ASP.NET Framework 4.x sous ServBay.

À propos de .NET Framework et .NET

Notez que ce guide traite du développement ASP.NET Framework 4.x basé sur Mono, une technologie issue d’une génération précédente de .NET.

ServBay prend également en charge les toutes dernières versions de .NET (y compris .NET Core, .NET 5/6/7/8+), pour lesquelles le SDK/runtime officiel Microsoft est intégré. Pour de nouveaux projets .NET ou lors d’une migration vers des technologies plus récentes, nous vous recommandons d’utiliser l’infrastructure .NET native fournie par ServBay plutôt que Mono.

Prérequis

Installer ServBay : Vérifiez que la version 1.12.0 (ou supérieure) de ServBay est installée sur votre macOS.
Installer Mono :
- Lancez l’application ServBay.
- Dans la barre de navigation à gauche, allez dans « Packages ».
- Dans la liste des paquets, trouvez « .NET » et développez la catégorie.
- Sélectionnez « Mono 6 » (version 6.14.0 ou plus récente) puis cliquez sur « Installer ». Patientez jusqu’à la fin de l’installation.

Préparer votre projet ASP.NET

Fichiers du projet : Assurez-vous de disposer d’un projet Web Application ou Web Site ASP.NET Framework 4.x comportant le fichier web.config.
Emplacement recommandé : Nous recommandons fortement de placer chaque site dans un sous-répertoire du dossier principal www de ServBay, à savoir /Applications/ServBay/www/. Un dossier distinct par projet est préférable.
- Exemple : Pour un projet nommé MyWebApp, le chemin racine conseillé serait /Applications/ServBay/www/MyWebApp.
- Les exemples ci-dessous utiliseront /Applications/ServBay/www/MyWebApp comme chemin. Adaptez-le à l’emplacement réel de votre projet.

Méthode 1 : Utiliser XSP (serveur de développement intégré)

XSP, livré avec Mono, est un serveur web léger idéal pour le développement local et les tests rapides de vos applications ASP.NET Framework. Le package Mono 6 de ServBay inclut XSP4 (pour ASP.NET 4.x).

Astuce

Pour un projet ASP.NET 1.1, utilisez la commande xsp.
Pour ASP.NET 2.0/3.x, utilisez la commande xsp2.
Pour ASP.NET 4.x, utilisez la commande xsp4.

Étapes :

Ouvrir un terminal : Lancez l’application Terminal de macOS.
Naviguer vers le dossier du projet : À l’aide de la commande cd, placez-vous dans le répertoire racine du projet ASP.NET (celui qui contient web.config).
bash
```
# Exemple : se placer dans le dossier du projet MyWebApp
cd /Applications/ServBay/www/MyWebApp
```
1
2
Démarrer le serveur XSP : Depuis la racine du projet, lancez XSP4 sur un port libre (par exemple 8080 ou 9000) pour éviter les conflits avec d’autres services ServBay.
bash
```
# Lancer le projet sur le port 9000
xsp4 --port 9000
```
1
2
- xsp4 : Lance le serveur XSP pour le framework .NET 4.x.
- --port 9000 : Définit le port TCP à écouter.
Accéder à l’application : Ouvrez votre navigateur et rendez-vous à l’adresse http://localhost:9000 ou http://127.0.0.1:9000. Votre application ASP.NET devrait apparaître.
Arrêter le serveur : Lorsqu’il n’est plus nécessaire, revenez à la fenêtre Terminal correspondante et appuyez sur Ctrl + C ou sur Entrée pour arrêter XSP.

Avantages :

Mise en place très simple, démarrage ultra rapide.
Adapté au développement local et au debug.

Inconvénients :

Performances moindres comparées à un serveur web de production (ex : Nginx).
Fonctionnalités basiques, émule partiellement l’environnement réel.
Nécessité de garder le terminal ouvert.

Méthode 2 : Utiliser Nginx + FastCGI

Ici, Nginx géré par ServBay sert d’interface web : il reçoit les requêtes, traite les fichiers statiques et transmet les requêtes dynamiques (comme .aspx, .ashx, etc.) au processus Mono backend (fastcgi-mono-server4) via FastCGI. Cette configuration est plus proche d’un environnement de production, tire parti des fonctionnalités avancées de Nginx (SSL, cache, compression…) et offre de meilleures performances.

Astuce

Pour un projet ASP.NET 1.1, utilisez la commande fastcgi-mono-server.
Pour ASP.NET 2.0/3.x, utilisez la commande fastcgi-mono-server2.
Pour ASP.NET 4.x, utilisez la commande fastcgi-mono-server4.

Étapes :

Vérifier l’installation et le fonctionnement de Mono et Nginx :
- Installez Mono 6 et Nginx via la section « Packages » de ServBay.
- Dans « Services », assurez-vous que Nginx est bien démarré.
Préparer le projet ASP.NET : Placez le projet dans un chemin conseillé, exemple /Applications/ServBay/www/MyWebApp.
Démarrer FastCGI Mono Server :
- Ouvrez un nouveau terminal.
- Exécutez le processus fastcgi-mono-server4, qui écoutera les requêtes FastCGI de Nginx, analysera les pages ASP.NET et exécutera le code métier.
  bash
```
# Exemple : lancer le service FastCGI pour le projet MyWebApp
fastcgi-mono-server4 --applications=/:/Applications/ServBay/www/MyWebApp \
                     --socket=tcp:127.0.0.1:9001 \
                     --loglevels=Standard \
                     --printlog
```
  1
  2
  3
  4
  5
  - fastcgi-mono-server4 : Démarre le serveur FastCGI pour .NET Framework 4.x.
  - --applications=/:/Applications/ServBay/www/MyWebApp : Mappe le chemin URL racine (/) vers le chemin physique du projet. N’oubliez pas : remplacez /Applications/ServBay/www/MyWebApp par le chemin réel de votre projet. Mono localisera et exécutera vos fichiers ASP.NET à cet emplacement.
  - --socket=tcp:127.0.0.1:9001 : Définit l’adresse et le port d’écoute FastCGI. Assurez-vous que le port (ici 9001) est disponible sur votre système et corresponde à celui de fastcgi_pass dans la config Nginx ci-dessous.
  - --loglevels=Standard --printlog : (optionnel) Affiche les logs standards dans le terminal, utile pour le debug.
- Note : Le terminal où est lancé fastcgi-mono-server4 doit rester ouvert, sinon le service s’arrête. Pour un fonctionnement en arrière-plan ou en production, privilégiez des outils comme nohup, screen ou tmux.

Configurer le site Nginx :

Accédez à la section « Sites » dans ServBay.
Ajoutez un nouveau site ou modifiez un site existant.
Définir le nom de domaine : Par exemple mywebapp.servbay.demo. ServBay ajoutera automatiquement ce domaine au fichier Hosts de macOS (pointant vers 127.0.0.1).
Définir le dossier racine du site : Point essentiel ! Ajoutez le chemin réel de votre projet ASP.NET, ex /Applications/ServBay/www/MyWebApp. Cela mettra à jour la directive root dans la configuration Nginx, utile pour le service des fichiers statiques.

Activer et modifier la configuration personnalisée : Cochez la case « Configuration personnalisée ». ServBay générera une base de configuration Nginx en fonction de votre domaine et dossier racine. Vous pouvez ensuite l’enrichir ou la modifier pour permettre le transfert des requêtes ASP.NET dynamiques vers le FastCGI Mono Server.

Exemple de configuration basée sur celle générée par ServBay à ajuster :

nginx

server {
    listen 80; # Port HTTP
    listen 443 ssl http2; # Port HTTPS avec SSL et HTTP/2

    # SSL géré automatiquement par ServBay
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers 'TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384';
    ssl_prefer_server_ciphers on;
    ssl_session_timeout 1d;
    ssl_session_cache shared:ServBay:10m;
    ssl_session_tickets off;

    # Chemins des certificats, générés/gérés automatiquement
    ssl_certificate /Applications/ServBay/ssl/private/tls-certs/mywebapp.servbay.demo/mywebapp.servbay.demo.crt;
    ssl_certificate_key /Applications/ServBay/ssl/private/tls-certs/mywebapp.servbay.demo/mywebapp.servbay.demo.key;

    server_name mywebapp.servbay.demo; # Doit correspondre au domaine configuré
    root /Applications/ServBay/www/MyWebApp; # **Assurez-vous** que cela reflète exactement le dossier racine de votre projet

    # Fichiers par défaut reconnus (Nginx tentera ces fichiers s’il ne trouve pas index.html/htm)
    index index.html index.htm default.aspx Default.aspx;

    # Logique principale de gestion des requêtes
    location / {
        # Recherche des fichiers/dossiers dans l’ordre
        # Si non trouvé, transfert vers @mono
        try_files $uri $uri/ @mono;
    }

    # (Optionnel mais recommandé) Nginx gère les fichiers statiques
    location ~* \.(ico|css|js|gif|jpe?g|png|svg|woff|woff2|ttf|eot)$ {
        expires max;
        log_not_found off;
        access_log off;
    }

    # Bloc nommé @mono pour les requêtes dynamiques ASP.NET
    location @mono {
        # Passage du traitement à Mono via FastCGI
        # **Le port ici doit correspondre à celui utilisé dans fastcgi-mono-server4**
        fastcgi_pass 127.0.0.1:9001;

        # Inclusion des paramètres FastCGI standards
        include fastcgi_params;
        # Paramètre clef : permet à Mono de localiser le fichier ASP.NET à exécuter
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        # Généralement inutile pour Mono, PATH_INFO peut rester vide
        fastcgi_param PATH_INFO "";

        # (Optionnel) Ajoutez ici d’autres paramètres FastCGI selon besoin
        # fastcgi_param HOST $host;
    }

    # ServBay peut ajouter d’autres paramètres par défaut, comme les chemins de log
    # access_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.access.log;
    # error_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.error.log;
}

Sauvegardez la config puis rechargez/redémarrez Nginx : Enregistrez le fichier de configuration Nginx dans ServBay. Celui-ci se chargera d’appliquer les modifications automatiquement. En cas d’erreur de syntaxe, une alerte apparaîtra. Si besoin, redémarrez Nginx manuellement depuis la section « Services ».

Accéder à votre application : Ouvrez le navigateur et rendez-vous sur le domaine configuré (ex : https://mywebapp.servbay.demo). Grâce à la configuration SSL sur le port 443, l’utilisation de HTTPS est recommandée. Nginx gérera les fichiers statiques et transmettra les requêtes dynamiques à fastcgi-mono-server4 – l’exécution de votre code ASP.NET sera alors assurée côté Mono.

Avantages :

Meilleures performances et stabilité, idéal pour des tests quasi-production.
Exploitation des fonctionnalités avancées de Nginx (fichiers statiques, SSL, répartition de charge, etc.).
Intégration optimale avec la gestion des sites, domaines et du fichier Hosts de ServBay.

Inconvénients :

Configuration plus complexe que XSP.
Gestion manuelle du processus fastcgi-mono-server4 (sauf usage d’un superviseur de process).

Choisir la méthode adaptée

Pour le développement rapide, le debug et les tests fonctionnels simples, XSP reste la solution idéale et la plus rapide à lancer – une seule commande suffit.
Pour des besoins de performance, de simulation d’un workflow de production, ou si vous souhaitez exploiter les fonctionnalités avancées (HTTPS, domaines personnalisés, optimisation des fichiers statiques, etc.) et l’intégration approfondie à ServBay, préférez le mode Nginx + FastCGI.

À savoir & dépannage

Droits sur les fichiers : Vérifiez que l’utilisateur Nginx (géré par ServBay) et l’utilisateur macOS exécutant fastcgi-mono-server4 disposent bien des droits de lecture sur le projet (dossier /Applications/ServBay/www/YourProjectName et ses contenus). Utilisez les commandes chmod ou chown si nécessaire.
Concordance des chemins : Contrôlez que le chemin défini dans la config Nginx (root) et celui dans la commande fastcgi-mono-server4 (--applications) correspondent bien à la racine du projet contenant web.config.
Conflit de ports : Assurez-vous que le port utilisé par XSP ou fastcgi-mono-server4 (9000/9001 dans les exemples) n’est pas déjà occupé par un autre service ServBay ou une autre application.
Vérification des logs :
- Surveillez la sortie console lors du lancement de fastcgi-mono-server4. L’argument --printlog facilite le suivi des logs Mono.
- Consultez les logs d’erreur Nginx. ServBay affiche le chemin des logs pour chaque site, en général /Applications/ServBay/logs/nginx/your-domain.error.log. C’est un outil central pour isoler les problèmes de configuration ou les soucis de communication avec FastCGI Mono Server.
Compatibilité des versions Mono : Mono 6.14.0 (intégré à ServBay) est globalement compatible avec les fonctionnalités .NET Framework v1.1 à v4.7.2. Si votre projet cible une version ultérieure ou en cas de souci de compatibilité, privilégiez le SDK/runtime Microsoft officiel fourni par ServBay ou adaptez votre projet pour rester compatible Mono.
Gestion du processus FastCGI : En mode Nginx + FastCGI, souvenez-vous que le processus fastcgi-mono-server4 doit tourner en continu. En mode dev, gardez le terminal ouvert ; en mode test/prod, optez pour une configuration en arrière-plan type service ou emploi d’un outil de gestion (tmux, screen…).

L’environnement intégré Mono 6 de ServBay, allié à une organisation cohérente des projets, simplifie et fiabilise le développement et l’exécution d’applications ASP.NET Framework 4.x traditionnelles sur macOS. Nous espérons que ce guide vous aidera à démarrer dans les meilleures conditions !

Développer en ASP.NET Framework 4.x sur macOS avec ServBay ​

Prérequis ​

Préparer votre projet ASP.NET ​

Méthode 1 : Utiliser XSP (serveur de développement intégré) ​

Méthode 2 : Utiliser Nginx + FastCGI ​

Choisir la méthode adaptée ​

À savoir & dépannage ​