Ontwikkelen van ASP.NET Framework 4.x op macOS met ServBay

Dankzij de krachtige geïntegreerde Mono-omgeving maakt ServBay het eenvoudig en praktisch om ASP.NET Framework 1.1/2.0/3.x/4.x (tot en met 4.7.x) te ontwikkelen en testen op macOS.

Vanaf ServBay v1.12.0 is Mono 6.14.0 geïntegreerd, samen met de XSP-ontwikkelserver en het fastcgi-mono-server-hulpprogramma. Dit biedt twee hoofdmethoden om ASP.NET Framework 4.x-applicaties uit te voeren:

Snel ontwikkelen en testen met XSP: XSP is een lichtgewicht ASP.NET-webserver speciaal ontworpen voor Mono, ideaal voor ontwikkel- en testdoeleinden.
Productiesimulatie via Nginx + FastCGI: Deze aanpak is stabieler, levert betere prestaties en komt dichter bij een productiesetting. Nginx, beheerd door ServBay, stuurt verzoeken door naar een Mono-backendproces.

In deze gids leer je hoe je je ASP.NET Framework 4.x-project configureert en uitvoert in de ServBay-omgeving.

Over .NET Framework en .NET

Let op: deze documentatie behandelt ontwikkeling voor ASP.NET Framework 4.x op basis van Mono, wat een oudere technologie-stack van .NET is.

ServBay ondersteunt ook de nieuwste .NET-versies (inclusief .NET Core, .NET 5/6/7/8+) volledig. Voor nieuwe .NET-projecten of migratie naar moderne .NET-versies adviseren wij het gebruik van de officiële Microsoft .NET SDK/runtime van ServBay, in plaats van de in dit artikel beschreven Mono-gebaseerde aanpak.

Vereisten

Installeer ServBay: Zorg dat ServBay v1.12.0 of nieuwer op je macOS-systeem is geïnstalleerd.
Installeer Mono:
- Open de ServBay-applicatie.
- Selecteer "Pakketten" in de zijbalk.
- Zoek de ".NET"-categorie in de lijst en klap deze uit.
- Zoek "Mono 6" (de versie moet 6.14.0 of hoger zijn), klik op de knop "Installeren" en wacht tot de installatie voltooid is.

Voorbereiden van je ASP.NET-project

Projectbestanden: Zorg ervoor dat je een ASP.NET Framework 4.x Web Application of Web Site project hebt, inclusief het bestand web.config.
Aanbevolen locatie: We raden ten zeerste aan om je webproject in de door ServBay beheerde www-map te plaatsen: /Applications/ServBay/www/. Maak voor elk project een aparte submap aan.
- Voorbeeld: Als je project MyWebApp heet, is de aanbevolen padnaam /Applications/ServBay/www/MyWebApp.
- In de rest van dit document wordt /Applications/ServBay/www/MyWebApp gebruikt als voorbeeldpad. Vervang dit altijd door het werkelijke pad van jouw project.

Methode 1: Gebruik XSP (geïntegreerde ontwikkelserver)

XSP is een lichte webserver die bij het Mono-project hoort en perfect is voor lokale ontwikkeling en snel testen van ASP.NET Framework-applicaties. De bij ServBay geïnstalleerde Mono 6 bevat XSP4 (de versie voor ASP.NET 4.x).

Tip

Voor projecten op ASP.NET 1.1 gebruik je het commando xsp.
Voor ASP.NET 2.0/3.x-projecten gebruik je xsp2.
Voor ASP.NET 4.x-projecten gebruik je xsp4.

Stappen:

Open Terminal: Start de Terminal-app op je Mac.
Navigeer naar je projectmap: Gebruik het cd-commando om naar de hoofdmap van je ASP.NET-project te gaan (de map waar het bestand web.config zich bevindt).
bash
```
# Voorbeeld: naar je MyWebApp projectmap gaan
cd /Applications/ServBay/www/MyWebApp
```
1
2
Start de XSP-server: Voer het volgende commando uit in de hoofdmap van je project om de XSP4-server te starten. Kies een ongebruikt poortnummer (zoals 8080 of 9000) om conflicten met andere ServBay-diensten te voorkomen.
bash
```
# Start het project op poort 9000
xsp4 --port 9000
```
1
2
- xsp4: Start de XSP-server voor .NET Framework 4.x.
- --port 9000: Geeft het TCP-poortnummer op waarop de server luistert.
Open je applicatie: Ga in je browser naar http://localhost:9000 of http://127.0.0.1:9000. Je zou nu je draaiende ASP.NET-applicatie moeten zien.
Stop de server: Klaar met testen? Druk in de terminal waar XSP draait op Ctrl + C of op de Enter-toets om de server te stoppen.

Voordelen:

Eenvoudige en snelle configuratie.
Ideaal voor lokale ontwikkeling en foutopsporing.

Nadelen:

Minder prestaties dan production-grade webservers zoals Nginx.
Beperkte functionaliteit, niet gelijk aan productieomgevingen.
Terminalvenster moet open blijven.

Methode 2: Gebruik Nginx + FastCGI

Met deze methode fungeert Nginx (beheerd door ServBay) als frontendwebserver. Nginx behandelt inkomende verzoeken en statische bestanden, terwijl dynamische verzoeken (zoals .aspx of .ashx-bestanden) via het FastCGI-protocol doorgestuurd worden naar een Mono-backendproces (fastcgi-mono-server4). Deze opzet bootst een productieomgeving na en biedt betere prestaties. Bovendien kun je profiteren van geavanceerde Nginx-functionaliteit zoals SSL, caching en compressie.

Tip

Voor ASP.NET 1.1 gebruik je het commando fastcgi-mono-server.
Voor ASP.NET 2.0/3.x-projecten gebruik je fastcgi-mono-server2.
Voor ASP.NET 4.x-projecten gebruik je fastcgi-mono-server4.

Stappen:

Zorg dat Mono en Nginx geïnstalleerd en actief zijn:
- Installeer Mono 6 en Nginx via het "Pakketten"-menu in ServBay.
- Controleer onder "Diensten" dat Nginx actief is.
Bereid je ASP.NET-project voor: Plaats het project op de aanbevolen locatie, bijvoorbeeld /Applications/ServBay/www/MyWebApp.
Start FastCGI Mono Server:
- Open een nieuw terminalvenster.
- Start het fastcgi-mono-server4-proces, dat verzoeken van Nginx ontvangt en ASP.NET-pagina’s afhandelt.
  bash
```
# Start FastCGI voor het MyWebApp-project
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: Start de FastCGI-server voor .NET Framework 4.x-projecten.
  - --applications=/:/Applications/ServBay/www/MyWebApp: Definieert de URL-naar-mapkoppeling. /: betekent dat / (root-URL) mapt naar de opgegeven projectmap. Wanneer Nginx een verzoek doorstuurt zoals /some/page.aspx, zoekt Mono dit bestand in /Applications/ServBay/www/MyWebApp/some/page.aspx. Vervang /Applications/ServBay/www/MyWebApp door jouw eigen projectpad!
  - --socket=tcp:127.0.0.1:9001: Luister op het TCP-adres en poortnummer. Gebruik poort 9001 of een andere vrije poort en zorg dat deze overeenkomt met de Nginx-configuratie.
  - --loglevels=Standard --printlog: (Optioneel) Standaard logniveau voor debugging, output in de terminal.
- Let op: Het terminalvenster waarin fastcgi-mono-server4 draait moet open blijven. Voor langdurig gebruik kun je tools als nohup, screen of tmux inzetten zodat het proces op de achtergrond blijft draaien.

Configureer je Nginx-site:

Ga naar het "Sites"-gedeelte binnen ServBay.
Kies "Site toevoegen" of bewerk een bestaande site.
Domeinnaam instellen: Gebruik bijvoorbeeld een merkgerelateerde domein zoals mywebapp.servbay.demo. ServBay voegt dit domein automatisch toe aan het Hosts-bestand van macOS zodat het doorverwijst naar 127.0.0.1.
Website root instellen: Belangrijk! Stel dit in op het daadwerkelijke pad van je ASP.NET-project, bv. /Applications/ServBay/www/MyWebApp. Dit zorgt ervoor dat de Nginx root-instructie correct is voor de afhandeling van statische bestanden.

Schakel "Aangepaste configuratie" in: Vink rechtsboven het selectievakje "Aangepaste configuratie" aan. ServBay genereert nu een basis-Nginx-configuratie voor jouw domein en projectmap. Je moet deze verder aanpassen zodat ASP.NET-verzoeken worden doorgestuurd naar de FastCGI Mono Server.

Zie hieronder een voorbeeldconfiguratie van ServBay (aan te passen op basis van jouw situatie):

nginx

server {
    listen 80; # Luistert naar HTTP
    listen 443 ssl http2; # Luistert naar HTTPS, SSL en HTTP/2 ingeschakeld

    # SSL-certificaatinstellingen (worden door ServBay beheerd)
    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;

    # Pad naar certificaatbestanden, overeenkomend met domeinnaam
    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; # Moet overeenkomen met de domeinnaam
    root /Applications/ServBay/www/MyWebApp; # **Zorg dat deze overeenkomt met je website root**

    # ASP.NET standaarddocumenten toevoegen naast index.html/htm
    index index.html index.htm default.aspx Default.aspx;

    # Hoofdverzoekverwerking
    location / {
        # Probeer eerst het bestand ($uri) of map ($uri/) te vinden
        # Niet gevonden? Stuur verzoek door naar @mono
        try_files $uri $uri/ @mono;
    }

    # (Optioneel, aanbevolen) Nginx verzorgt statische bestanden
    # Met 'expires' kun je browsercaching instellen
    location ~* \.(ico|css|js|gif|jpe?g|png|svg|woff|woff2|ttf|eot)$ {
        expires max; # Maximaal lang in de browser cache
        log_not_found off; # Geen logs bij ontbrekende statische bestanden
        access_log off; # Geen logboek voor toegang tot statische bestanden
    }

    # @mono named location voor dynamische ASP.NET-verzoeken
    location @mono {
        # Doorsturen via FastCGI naar Mono Server
        # **Poort moet overeenkomen met fastcgi-mono-server4**
        fastcgi_pass 127.0.0.1:9001;

        # Standaard FastCGI-parameters
        include fastcgi_params;
        # SCRIPT_FILENAME wijst Mono naar het juiste ASP.NET-bestand
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        # PATH_INFO meestal niet vereist, stel op leeg
        fastcgi_param PATH_INFO "";

        # (Optioneel) Andere FastCGI-parameters, zoals HOST
        # fastcgi_param HOST $host;
    }

    # ServBay kan aanvullende loginstellingen toevoegen
    # access_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.access.log;
    # error_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.error.log;
}

Configuratie opslaan & Nginx herstarten/herladen: Sla het aangepaste Nginx-configuratiebestand op in ServBay. ServBay probeert Nginx automatisch te herladen. Bij syntaxfouten verschijnt er een foutmelding. Je kunt Nginx ook handmatig herstarten via het "Diensten"-overzicht.

Open je applicatie: Ga in de browser naar het geconfigureerde domein (zoals https://mywebapp.servbay.demo). Door SSL op poort 443 kun je het best via HTTPS openen. Nginx bedient statische bestanden zelf en stuurt dynamische aanvragen door naar fastcgi-mono-server4 voor verwerking via Mono.

Voordelen:

Hogere prestaties en meer stabiliteit, uitermate geschikt voor productieachtige tests.
Profiteer van alle krachtige Nginx-mogelijkheden (zoals statische bestandendeling, SSL, load balancing).
Naadloze integratie met ServBay-sitebeheer, domeinen en hostsbeheer.

Nadelen:

Iets complexere configuratie dan XSP.
Handmatige procestart van fastcgi-mono-server4 vereist (tenzij met backgrondmanager).

Welke methode kies je?

Voor snelle ontwikkeling, debugging en simpele tests is XSP de makkelijkste en snelste optie. Eén commando is voldoende om te beginnen.
Heb je hogere prestaties nodig, een productieachtige testomgeving, of wil je profiteren van opties als HTTPS, custom domeinen en geoptimaliseerde statische bestanden, dan is Nginx + FastCGI de beste keuze.

Belangrijke aandachtspunten en probleemoplossing

Bestandsrechten: Zorg ervoor dat de gebruiker waaronder Nginx draait (meestal door ServBay beheerd) én je eigen gebruiker voldoende leesrechten hebben op het projectbestand in /Applications/ServBay/www/YourProjectName. Pas zo nodig de rechten aan met chmod of chown.
Padconsistentie: Controleer zorgvuldig of de paden in de Nginx-configuratie (root) en het fastcgi-mono-server4-commando (--applications) exact overeenkomen. Ze moeten allebei verwijzen naar de hoofdmap van je project (met web.config).
Poortconflicten: Zorg dat de voor XSP of fastcgi-mono-server4 gekozen poorten (zoals 9000 of 9001) niet in gebruik zijn door andere systemen of ServBay-diensten.
Logbestanden raadplegen:
- Bekijk de terminaluitvoer van fastcgi-mono-server4, vooral met de optie --printlog ingeschakeld.
- Controleer de Nginx-foutenlog. ServBay toont het pad naar deze logs in de sitesectie, doorgaans op /Applications/ServBay/logs/nginx/your-domain.error.log. Hier vind je cruciale informatie over Nginx-configuratieproblemen of communicatieproblemen met Mono.
Mono-versiecompatibiliteit: De ingebouwde Mono 6.14.0 in ServBay ondersteunt vrijwel alle functionaliteiten van .NET Framework 1.1 t/m 4.7.2. Gebruik je functies uit recentere .NET Framework-versies of ondervind je compatibiliteitsproblemen, overweeg dan het installeren van de officiële Microsoft .NET SDK/runtime via ServBay voor moderne .NET-apps — of downgrade je project naar een door Mono ondersteunde versie.
Beheer FastCGI-processen: Bij gebruik van Nginx + FastCGI moet fastcgi-mono-server4 continu actief blijven. Tijdens ontwikkeling kun je het terminalvenster gewoon open houden. In formelere omgevingen kun je ervoor kiezen dit proces met een procesmanager op de achtergrond te laten draaien.

Dankzij de ingebouwde Mono 6-omgeving van ServBay en het aanbevolen projectstructuur kun je klassiek ASP.NET Framework 4.x ontwikkelen en uitvoeren op macOS op een gestroomlijnde en beheerste manier. Hopelijk helpt deze documentatie je om vlot met je ontwikkeling te starten!

Ontwikkelen van ASP.NET Framework 4.x op macOS met ServBay ​

Vereisten ​

Voorbereiden van je ASP.NET-project ​

Methode 1: Gebruik XSP (geïntegreerde ontwikkelserver) ​

Methode 2: Gebruik Nginx + FastCGI ​

Welke methode kies je? ​

Belangrijke aandachtspunten en probleemoplossing ​