Sviluppo ASP.NET Framework 4.x con ServBay su macOS

Grazie al potente ambiente Mono integrato, ServBay semplifica lo sviluppo e il test di applicazioni ASP.NET Framework 1.1/2.0/3.x/4.x (supporto fino alla versione 4.7.x) su macOS.

Dalla versione ServBay v1.12.0, viene fornito Mono 6.14.0 corredato dal server di sviluppo XSP e dallo strumento fastcgi-mono-server, offrendoti due principali modalità per eseguire applicazioni ASP.NET Framework 4.x:

1. Sviluppo e test rapido con XSP: XSP è un web server leggero, progettato per Mono, ideale per la fase di sviluppo e test veloce.
2. Distribuzione con Nginx + FastCGI: Questa modalità, più stabile e performante, simula da vicino un ambiente di produzione, inoltrando le richieste tramite l'Nginx gestito da ServBay ai processi back-end Mono.

In questa guida troverai le istruzioni per configurare ed eseguire il tuo progetto ASP.NET Framework 4.x nell’ambiente di ServBay.

Riguardo .NET Framework e .NET

Nota: Questo documento si riferisce allo sviluppo di ASP.NET Framework 4.x con Mono, parte del "vecchio" stack tecnologico .NET.

ServBay supporta anche le ultime versioni di .NET (inclusi .NET Core, .NET 5/6/7/8+). Se stai lavorando su nuovi progetti o vuoi migrare a versioni più moderne, ti consigliamo di adottare il supporto ufficiale Microsoft .NET SDK/runtime fornito da ServBay, invece del metodo qui descritto basato su Mono.

Prerequisiti

1. Installa ServBay: Verifica di avere installato ServBay v1.12.0 o versioni successive su macOS.
2. Installa Mono:
   • Apri l'applicazione ServBay.
   • Nel menu laterale, seleziona "Pacchetti".
   • Nell'elenco dei pacchetti, trova la categoria ".NET" ed espandila.
   • Cerca "Mono 6" (deve essere almeno la versione 6.14.0), clicca su "Installa" e attendi la fine del processo.

Prepara il tuo progetto ASP.NET

1. File di progetto: Assicurati di avere un progetto ASP.NET Framework 4.x di tipo Web Application o Web Site con il file web.config incluso.
2. Percorso consigliato: Raccomandiamo vivamente di posizionare il tuo progetto nella cartella www gestita da ServBay, cioè in /Applications/ServBay/www/. Crea una sottocartella separata per ogni progetto.
   • Esempio: Se il progetto si chiama MyWebApp, il percorso di root consigliato sarà /Applications/ServBay/www/MyWebApp.
   • Nei passaggi a seguire useremo /Applications/ServBay/www/MyWebApp come esempio. Ricorda di sostituirlo con il percorso reale del tuo progetto.

Metodo 1: Utilizzo di XSP (Server di sviluppo integrato)

XSP è il web server leggero incluso in Mono, perfetto per lo sviluppo locale e i test rapidi di applicazioni ASP.NET Framework. Il pacchetto Mono 6 distribuito da ServBay include già XSP4 (compatibile con ASP.NET 4.x).

Suggerimento

• Per progetti ASP.NET 1.1, usa il comando xsp.
• Per progetti ASP.NET 2.0/3.x, usa il comando xsp2.
• Per progetti ASP.NET 4.x, usa il comando xsp4.

Procedura:

1. Apri il Terminale: Lancia "Terminale" su macOS.

2. Vai nella directory del progetto: Usa il comando cd per posizionarti nella cartella di root del progetto ASP.NET (dove si trova web.config).

   # Esempio: accedere alla directory del progetto MyWebApp
   cd /Applications/ServBay/www/MyWebApp

3. Avvia il server XSP: Dal percorso principale del progetto, esegui il comando qui sotto per lanciare XSP4. Puoi specificare una porta libera (come 8080 o 9000), evitando conflitti con altri servizi di ServBay.

   # Avvia il progetto sulla porta 9000
   xsp4 --port 9000

   • xsp4: esegue il server XSP per .NET Framework 4.x.
   • --port 9000: imposta la porta TCP su cui il server ascolterà.

4. Accedi all'applicazione: Apri il browser e visita http://localhost:9000 o http://127.0.0.1:9000. Se tutto è configurato correttamente, vedrai la tua app ASP.NET attiva.

5. Ferma il server: Per interrompere XSP al termine del test o dello sviluppo, torna al Terminale e premi Ctrl + C oppure Invio.

Vantaggi:

• Configurazione immediata, avvio veloce.
• Ideale per sviluppo locale e debug.

Svantaggi:

• Prestazioni inferiori rispetto a web server di produzione come Nginx.
• Funzionalità limitate, non riproduce totalmente l’ambiente produttivo.
• Terminale da mantenere aperto.

Metodo 2: Utilizzo di Nginx + FastCGI

Questa modalità utilizza Nginx (gestito da ServBay) come web server front-end per ricevere le richieste dei client e servire file statici. Le richieste dinamiche (come .aspx, .ashx, ecc.) vengono inoltrate attraverso FastCGI ai processi Mono (fastcgi-mono-server4). Così ottieni una configurazione simile a un ambiente di produzione, con migliori prestazioni e tutte le funzionalità avanzate offerte da Nginx (SSL, cache, compressione, ecc.).

Suggerimento

• Per progetti ASP.NET 1.1, usa fastcgi-mono-server.
• Per progetti ASP.NET 2.0/3.x, usa fastcgi-mono-server2.
• Per progetti ASP.NET 4.x, usa fastcgi-mono-server4.

Procedura:

1. Verifica installazione di Mono e Nginx e che siano avviati:

   • Installa Mono 6 e Nginx dal menu "Pacchetti" di ServBay.
   • Nella sezione "Servizi" verifica che Nginx sia in esecuzione.

2. Prepara il progetto ASP.NET: Riponi il tuo progetto nella posizione consigliata, come /Applications/ServBay/www/MyWebApp.

3. Avvia il FastCGI Mono Server:

   • Apri una nuova finestra del Terminale.
   • Avvia il processo fastcgi-mono-server4. Questo servizio ascolta le richieste FastCGI da Nginx, elabora le pagine ASP.NET ed esegue la logica dell'applicazione.

     # Avvio del servizio FastCGI per il progetto MyWebApp
     fastcgi-mono-server4 --applications=/:/Applications/ServBay/www/MyWebApp \
                          --socket=tcp:127.0.0.1:9001 \
                          --loglevels=Standard \
                          --printlog

     • fastcgi-mono-server4: avvia il server FastCGI per .NET Framework 4.x.
     • --applications=/:/Applications/ServBay/www/MyWebApp: mappa l’URL root (/) alla directory fisica del tuo progetto. Cambia /Applications/ServBay/www/MyWebApp con il percorso corretto.
     • --socket=tcp:127.0.0.1:9001: imposta indirizzo IP e porta TCP; assicurati che la porta (esempio 9001) sia libera e corrisponda a quella specificata nella configurazione di Nginx.
     • --loglevels=Standard --printlog: (opzionali) mostrano i log direttamente nel terminale, utili per debug.
   • Nota: Mantieni la finestra del terminale con fastcgi-mono-server4 aperta per mantenere attivo il servizio. In ambienti più formali puoi adoperare strumenti come nohup, screen o tmux per lasciarlo in background.

4. Configura il sito Nginx:

   • In ServBay, accedi alla sezione "Siti".

   • Clicca su "Aggiungi sito" o modifica uno già esistente.

   • Imposta il dominio: usa, ad esempio, mywebapp.servbay.demo per facilitare il riconoscimento. ServBay aggiornerà automaticamente il file Hosts di macOS per puntarlo a 127.0.0.1.

   • Configura la root del sito: Fondamentale! Imposta la root sul percorso reale del tuo progetto (es. /Applications/ServBay/www/MyWebApp). Quest’impostazione sincronizza la direttiva root di Nginx.

   • Abilita e modifica la configurazione personalizzata: Spunta l’opzione "Configurazione personalizzata" nelle impostazioni del sito. ServBay genererà un file base per la configurazione di Nginx; dovrai aggiungere o modificare le seguenti parti per l’integrazione con il FastCGI Mono Server.

     Di seguito una configurazione d’esempio revisionata:

     server {
         listen 80; # Porta HTTP
         listen 443 ssl http2; # Porta HTTPS, SSL e HTTP/2 abilitati
     
         # Configurazione SSL automatica 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;
     
         # Percorsi certificati SSL, gestiti automaticamente da ServBay
         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; # Deve corrispondere al dominio impostato in ServBay
         root /Applications/ServBay/www/MyWebApp; # **Verifica** che sia la root corretta
     
         # Documenti predefiniti ASP.NET
         index index.html index.htm default.aspx Default.aspx;
     
         # Gestione principale delle richieste
         location / {
             try_files $uri $uri/ @mono;
         }
     
         # (Opzionale ma consigliato) Gestione file statici
         location ~* \.(ico|css|js|gif|jpe?g|png|svg|woff|woff2|ttf|eot)$ {
             expires max;
             log_not_found off;
             access_log off;
         }
     
         # Location nominata per richieste ASP.NET dinamiche
         location @mono {
             fastcgi_pass 127.0.0.1:9001;
             include fastcgi_params;
             fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
             fastcgi_param PATH_INFO "";
     
             # (Opzionale) Aggiungi altri parametri FastCGI se necessario
             # fastcgi_param HOST $host;
         }
     
         # Configurazione ServBay aggiuntiva (log, ecc.)
         # access_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.access.log;
         # error_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.error.log;
     }

   • Salva e ricarica/riavvia Nginx: Salva la configurazione in ServBay. Verrà eseguita la ricarica automatica di Nginx, con notifica in caso di errori sintattici. Puoi anche riavviare manualmente Nginx dalla sezione "Servizi".

5. Accedi all’applicazione: Dal browser, vai al dominio configurato su Nginx (es. https://mywebapp.servbay.demo). La presenza di SSL sulla porta 443 consiglia l’accesso in HTTPS. Nginx restituirà direttamente i file statici e passerà le richieste dinamiche a fastcgi-mono-server4, che processerà il codice ASP.NET.

Vantaggi:

• Migliori performance e maggiore stabilità, ideale per test vicino alla produzione.
• Sfrutta le funzionalità avanzate di Nginx (static file server, SSL, bilanciamento carico).
• Integrazione completa con gestione siti, domini e hosts di ServBay.

Svantaggi:

• Configurazione più articolata rispetto a XSP.
• Richiede la gestione manuale del processo fastcgi-mono-server4 (a meno di strumenti di background).

Come scegliere il metodo più adatto

• Per sviluppo rapido, debug e test funzionali semplici, XSP è la soluzione più rapida e immediata, attivabile con un solo comando.
• Se necessiti di performance superiori, test più realistici o vuoi sfruttare le funzionalità avanzate di Nginx (HTTPS, domini personalizzati, ottimizzazioni statiche) e la gestione dei siti ServBay, scegli la modalità Nginx + FastCGI.

Avvertenze e troubleshooting

• Permessi file: Assicurati che sia il processo Nginx (gestito da ServBay) sia l’utente macOS che esegue fastcgi-mono-server4 abbiano i permessi di lettura sui file del progetto. Se necessario, usa chmod o chown per correggere i permessi.
• Correttezza dei percorsi: Verifica che il valore impostato per root in Nginx e per il parametro --applications in fastcgi-mono-server4 siano coerenti e puntino alla directory principale (quella con web.config).
• Conflitti di porta: Assicurati che le porte utilizzate (es. 9000 per XSP, 9001 per FastCGI) non siano già in uso da altri servizi di ServBay o altre applicazioni.
• Controllo log:
  • Consulta i log prodotti al lancio di fastcgi-mono-server4 (grazie al parametro --printlog).
  • Consulta il log errori di Nginx. Il percorso viene mostrato nelle impostazioni sito di ServBay, di solito in /Applications/ServBay/logs/nginx/nome-dominio.error.log. Questi log sono fondamentali per individuare problemi di configurazione o di comunicazione con Mono.
• Compatibilità Mono: Mono 6.14.0 incluso in ServBay copre le funzionalità di .NET Framework dalla 1.1 alla 4.7.2. L’utilizzo di funzionalità di versioni superiori può causare errori; valuta il passaggio all’SDK/Runtime ufficiale Microsoft o il downgrade della tua soluzione.
• Gestione processi FastCGI: Con Nginx + FastCGI, ricorda che fastcgi-mono-server4 deve restare attivo. In sviluppo puoi lasciar aperto il terminale; per ambienti formali, considera la configurazione come servizio di sistema o usa un process manager.

---

Grazie all’integrazione di Mono 6 e all’organizzazione suggerita dei progetti, ServBay rende lo sviluppo e l’esecuzione di applicazioni ASP.NET Framework 4.x tradizionali su macOS più semplici, efficienti e ordinati. Speriamo che questa guida ti sia utile per partire subito al meglio con il tuo lavoro!