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

ServBay simplifie le développement et le test d'applications ASP.NET Framework 1.1/2.0/3.x/4.x (jusqu'à 4.7.x) sur macOS grâce à un environnement Mono puissant intégré.

Depuis la version 1.12.0 de ServBay, nous avons intégré Mono 6.14.0 et inclus le serveur de développement XSP, vous offrant deux principales manières d'exécuter des applications ASP.NET Framework 4.x :

Utilisation de XSP pour un développement et des tests rapides
Utilisation de Nginx + FastCGI pour déployer des applications plus stables, proches d'un environnement de production.

Ce document vous guidera pour configurer et exécuter votre projet ASP.NET Framework 4.x dans l'environnement ServBay.

Prérequis

Installer ServBay : Assurez-vous d'avoir installé ServBay v1.12.0 ou une version supérieure sur macOS.
Installer Mono :
- Ouvrez l'application ServBay.
- Dans la barre de navigation à gauche, sélectionnez « Paquets ».
- Dans la liste des paquets, trouvez la catégorie « .NET » et cliquez pour développer.
- Trouvez « Mono 6 » (la version doit être 6.14.0 ou supérieure), cliquez sur le bouton « Installer » à droite et attendez que l'installation se termine.

Préparer votre projet ASP.NET

Fichier de projet : Assurez-vous d'avoir un projet Web Application ou Web Site avec ASP.NET Framework 4.x.
Emplacement recommandé : Nous recommandons fortement de placer votre projet de site web dans le répertoire www géré de manière centralisée par ServBay, à savoir /Applications/ServBay/www/. Créez un sous-répertoire séparé pour chaque projet.
- Exemple : Si votre projet s'appelle MyWebApp, le chemin recommandé serait /Applications/ServBay/www/MyWebApp.
- Dans les étapes suivantes, nous utiliserons /Applications/ServBay/www/MyWebApp comme chemin exemple. Assurez-vous de le remplacer par le chemin réel de votre projet.

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

XSP est un serveur Web ASP.NET léger, spécialement conçu pour Mono, idéal pour la phase de développement et de tests rapides. Le Mono 6 installé avec ServBay inclut XSP4 (correspondant à ASP.NET 4.x).

Conseils

Si vous devez exécuter un projet ASP.NET 1.1, utilisez la commande xsp.
Si vous devez exécuter un projet ASP.NET 2.0, utilisez la commande xsp2.

Étapes :

Ouvrir le Terminal : Ouvrez l'application Terminal de macOS.
Naviguer vers le répertoire du projet : Utilisez la commande cd pour accéder au répertoire racine de votre projet ASP.NET (le répertoire contenant le fichier web.config).
bash
```
# Exemple : accéder au répertoire du projet nommé MyWebApp
cd /Applications/ServBay/www/MyWebApp
```
1
2
Démarrer le serveur XSP : Dans le répertoire racine du projet, exécutez la commande suivante pour démarrer le serveur XSP4. Vous pouvez spécifier un numéro de port (par exemple, 8080 ou 9000) pour éviter les conflits avec d'autres services dans ServBay.
bash
```
# Démarrer le projet dans le répertoire courant sur le port 9000
xsp4 --port 9000
```
1
2
- xsp4 : appelle le serveur XSP adapté pour .NET 4.x.
- --port 9000 : spécifie le numéro de port à écouter par le serveur.
Accéder à l'application : Ouvrez votre navigateur Web et accédez à http://localhost:9000 ou http://127.0.0.1:9000. Vous devriez voir votre application ASP.NET en cours d'exécution.
Arrêter le serveur : Lorsque vous avez terminé le développement ou les tests, retournez à la fenêtre du terminal, appuyez sur Ctrl + C ou Entrée pour arrêter le serveur XSP.

Avantages :

Configuration simple, démarrage rapide.
Idéal pour le développement et le débogage locaux.

Inconvénients :

Performances inférieures aux serveurs de production comme Nginx.
Fonctionnalités relativement basiques, ne simulant pas complètement un environnement de production.

Méthode 2 : Utiliser Nginx + FastCGI

Cette méthode utilise Nginx, géré par ServBay, comme serveur Web frontal, qui retransmet les requêtes dynamiques au processus backend Mono (fastcgi-mono-server4) via le protocole FastCGI. Cela se rapproche davantage d'un déploiement en environnement de production et offre de meilleures performances.

Conseils

Si vous devez exécuter un projet ASP.NET 1.1, utilisez la commande fastcgi-mono-server.
Si vous devez exécuter un projet ASP.NET 2.0, utilisez la commande fastcgi-mono-server2.

Étapes :

Assurez-vous que Mono et Nginx sont installés et en cours d'exécution :
- Installez Mono 6 et Nginx via les « Paquets » de ServBay.
- Dans la partie « Services » de ServBay, assurez-vous que le service Nginx est en cours d'exécution.
Préparer le projet ASP.NET : Assurez-vous que votre projet est situé au chemin recommandé, par exemple /Applications/ServBay/www/MyWebApp.
Démarrer le serveur FastCGI Mono :
- Ouvrez une nouvelle fenêtre de terminal.
- Exécutez le processus fastcgi-mono-server4. Ce processus est chargé d'écouter les requêtes FastCGI en provenance de Nginx et d'exécuter votre code ASP.NET.
  bash
```
# Exemple : démarrer 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
  - --applications=/:/Applications/ServBay/www/MyWebApp : mappe le chemin d'accès à la racine (/) vers le chemin physique de votre projet. Assurez-vous de remplacer /Applications/ServBay/www/MyWebApp par le chemin réel de votre projet.
  - --socket=tcp:127.0.0.1:9001 : spécifie l'adresse TCP et le port que le serveur FastCGI écoutera. Assurez-vous que ce port (par exemple 9001) n'est pas utilisé, et qu'il correspond à la directive fastcgi_pass dans la configuration de Nginx ci-dessous.
  - --loglevels=Standard --printlog : (facultatif) imprime les journaux de niveau standard dans le terminal pour faciliter le débogage.
- Remarque : Cette fenêtre de terminal doit rester ouverte pour exécuter le service FastCGI. Pour un fonctionnement prolongé, vous devrez peut-être utiliser des outils comme nohup, screen ou tmux pour le faire fonctionner en arrière-plan.

Configurer le site Nginx :

Dans ServBay, accédez à la section « Sites ».
Cliquez sur « Ajouter un site » ou sélectionnez un site existant pour modifier.
Configurer le nom de domaine : par exemple mywebapp.test. ServBay l'ajoutera automatiquement à votre fichier Hosts.
Définir le répertoire racine du site : très important ! Réglez cela sur le chemin physique réel de votre projet ASP.NET, par exemple /Applications/ServBay/www/MyWebApp. Ceci configurera correctement la directive root dans la configuration Nginx.

Clé : vérifiez/modifiez le fichier de configuration Nginx : Cliquez sur la case « Configuration personnalisée » dans le coin supérieur droit des paramètres du site. ServBay générera une configuration de base en fonction du chemin racine que vous avez défini. Vous devez vous assurer que la configuration des blocs location / et @mono (ou d'autres blocs similaires) redirige correctement les requêtes vers le serveur FastCGI Mono.

Un exemple d'une configuration générée automatiquement par ServBay, nécessitant une vérification ou des ajouts pourrait ressembler à ceci :

nginx

server {
    listen 443;
    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;

    ssl_certificate /Applications/ServBay/ssl/private/tls-certs/mywebapp.test/mywebapp.test.crt; # Vérifiez que le certificat correspond au chemin réel
    ssl_certificate_key /Applications/ServBay/ssl/private/tls-certs/mywebapp.test/mywebapp.test.key; # Vérifiez que la clé correspond au chemin réel

    server_name mywebapp.test; # Doit correspondre au nom de domaine configuré dans ServBay
    root /Applications/ServBay/www/MyWebApp; # **Assurez-vous** que cela correspond au chemin racine du site que vous avez défini
    index index.html index.htm default.aspx Default.aspx; # Ajoutez le document par défaut d'ASP.NET

    location / {
        try_files $uri $uri/ @mono; # Tentez d'accéder aux fichiers statiques, sinon proxy vers @mono
    }

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

    location @mono {
        # Transférer les requêtes au serveur FastCGI Mono
        # **Le port doit** correspondre à celui spécifié par le paramètre --socket lors du démarrage de fastcgi-mono-server4
        fastcgi_pass 127.0.0.1:9001;

        # Paramètres FastCGI nécessaires
        include fastcgi_params;
        # SCRIPT_FILENAME sera correctement défini en fonction de la directive root et de $fastcgi_script_name
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param PATH_INFO "";
    }

    # ServBay pourrait également inclure d'autres configurations par défaut telles que les journaux, le contrôle d'accès, etc.
    # access_log /Applications/ServBay/logs/nginx/mywebapp.test.access.log;
    # error_log /Applications/ServBay/logs/nginx/mywebapp.test.error.log;
}

Sauvegarder la configuration et redémarrer Nginx : Enregistrez le fichier de configuration Nginx. ServBay rechargera automatiquement la configuration Nginx après sauvegarde. Si la configuration comporte des erreurs, ServBay vous en avertira. Si besoin, vous pourrez redémarrer manuellement Nginx dans la page « Services » de ServBay.

Accéder à l'application : Ouvrez un navigateur et accédez au nom de domaine que vous avez configuré dans Nginx (par exemple https://mywebapp.test, notez que HTTPS est utilisé ici). Nginx transmettra la requête au fastcgi-mono-server4, et Mono exécutera votre code ASP.NET.

Avantages :

Performances améliorées et plus de stabilité.
Mode de déploiement plus proche d'un environnement de production.
Peut utiliser Nginx pour gérer les fichiers statiques, la répartition de charge, SSL et d'autres fonctionnalités avancées.
Intégration plus profonde avec la gestion des sites, des domaines et des Hosts de ServBay.

Inconvénients :

Configuration un peu plus complexe comparée à XSP.
Nécessite la gestion manuelle du processus fastcgi-mono-server4.

Comment choisir

Pour un développement rapide, le débogage et les tests simples, utiliser XSP est la manière la plus pratique.
Pour des tests ou déploiements internes nécessitant de meilleures performances, ou pour ceux qui souhaitent tirer parti des fonctionnalités avancées de Nginx et de la gestion des sites dans ServBay, optez pour le mode Nginx + FastCGI.

Remarques et dépannage

Permissions de fichier : Assurez-vous que le processus Nginx (géré par ServBay) et l'utilisateur macOS exécutant fastcgi-mono-server4 ont les permissions de lecture sur vos fichiers de projet (situés à /Applications/ServBay/www/YourProjectName). Il peut parfois être nécessaire d'ajuster les permissions des répertoires (chmod ou chown).
Chemin : Vérifiez soigneusement que le chemin du projet dans la configuration Nginx (directive root) et la commande fastcgi-mono-server4 (paramètre --applications) sont absolument corrects et pointent vers le répertoire contenant le fichier web.config.
Conflit de ports : Assurez-vous que les ports utilisés par XSP ou fastcgi-mono-server4 (9000 ou 9001 dans cet exemple) ne sont pas utilisés par d'autres applications.
Logs :
- Vérifiez les journaux de sortie dans le terminal lors du démarrage de fastcgi-mono-server4.
- Vérifiez les journaux d'erreurs de Nginx. Vous pouvez trouver le chemin correspondant au journal d'erreurs du site dans les paramètres de site de ServBay (normalement à /Applications/ServBay/logs/nginx/mywebapp.test.error.log).
Compatibilité des versions de Mono : Mono 6.14.0 est compatible avec .NET Framework 1.1 jusqu'à environ .NET Framework 4.7.2. Si vous utilisez des fonctionnalités d'une version plus récente de .NET Framework, envisagez d'utiliser l'installation officielle de .NET Core ou .NET via ServBay.

Avec l'environnement Mono 6 intégré à ServBay et la structure de projet recommandée, le développement et l'exécution d'applications ASP.NET Framework 4.x sur macOS deviennent plus standards et pratiques. Nous espérons que ce document vous aidera à commencer votre travail de développement en toute sérénité !

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

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 ​

Comment choisir ​

Remarques et dépannage ​