ASP.NET Framework 4.x Entwicklung auf macOS mit ServBay

Dank der leistungsstarken, integrierten Mono-Umgebung von ServBay wird die Entwicklung und das Testen von ASP.NET Framework 1.1/2.0/3.x/4.x (bis einschließlich Version 4.7.x) auf dem Mac einfach und praktisch.

Seit ServBay v1.12.0 ist Mono 6.14.0 direkt enthalten – mitsamt dem XSP Entwicklungsserver und dem Tool fastcgi-mono-server. Das bietet Ihnen zwei Hauptmöglichkeiten, ASP.NET Framework 4.x Anwendungen laufen zu lassen:

Schnelle Entwicklung & Tests mit XSP: XSP ist ein schlanker, speziell für Mono entworfener ASP.NET Webserver und ideal für die Entwicklungs- und Testphase geeignet.
Produktionsnahe Bereitstellung via Nginx + FastCGI: Hier läuft ServBay’s Nginx als Frontend-Webserver und leitet Anfragen an einen Mono-Backend-Prozess weiter – stabil, performant und nahe an realen Produktionsumgebungen.

Diese Dokumentation zeigt Schritt für Schritt, wie Sie Ihr ASP.NET Framework 4.x-Projekt mit ServBay konfigurieren und betreiben.

Über .NET Framework und .NET

Beachten Sie, dass es hier um die Entwicklung mit dem älteren ASP.NET Framework 4.x auf Basis von Mono geht.

ServBay unterstützt auch die neuesten .NET-Versionen (inklusive .NET Core, .NET 5/6/7/8+). Für neue .NET-Projekte oder für die Migration auf moderne .NET-Versionen empfiehlt sich die offizielle Microsoft .NET SDK/Runtime-Integration von ServBay – nicht die in diesem Guide vorgestellte Mono-basierte Methode.

Voraussetzungen

ServBay installieren: Stellen Sie sicher, dass ServBay v1.12.0 (oder neuer) bereits auf Ihrem macOS installiert ist.
Mono installieren:
- Starten Sie die ServBay-Anwendung.
- Wählen Sie den Bereich „Pakete“ in der linken Navigation.
- Suchen Sie im Paket-Listing die Kategorie „.NET“ und klappen Sie diese auf.
- Finden Sie „Mono 6“ (mindestens Version 6.14.0), klicken Sie auf „Installieren“ und warten Sie bis die Installation abgeschlossen ist.

Ihr ASP.NET Projekt vorbereiten

Projektdateien: Sie benötigen ein ASP.NET Framework 4.x Web Application oder Web Site Project, das eine web.config-Datei enthält.
Empfohlener Speicherort: Wir empfehlen dringend, Ihr Webprojekt im von ServBay verwalteten www-Verzeichnis, d. h. unter /Applications/ServBay/www/, abzulegen – und für jedes Projekt dort einen eigenen Unterordner zu erstellen.
- Beispiel: Trägt Ihr Projekt den Namen MyWebApp, lautet der empfohlene Web-Stammordner /Applications/ServBay/www/MyWebApp.
- In den folgenden Schritten nehmen wir /Applications/ServBay/www/MyWebApp als Beispielpfad. Ersetzen Sie diesen unbedingt durch den tatsächlichen Pfad Ihres Projekts!

Methode 1: Einsatz von XSP (integrierter Entwicklungsserver)

Der mit Mono ausgelieferte, schlanke Webserver XSP ist ideal für lokale Entwicklung und schnelle Tests von ASP.NET Framework-Anwendungen. Das Mono 6-Paket von ServBay beinhaltet XSP4 (für ASP.NET 4.x-Projekte).

Hinweis

Für ASP.NET 1.1-Projekte nutzen Sie bitte das Kommando xsp.
Für ASP.NET 2.0/3.x-Projekte setzen Sie xsp2 ein.
Für ASP.NET 4.x-Projekte verwenden Sie xsp4.

Vorgehensweise:

Terminal öffnen: Starten Sie das Terminal auf Ihrem Mac.
Zum Projektverzeichnis navigieren: Wechseln Sie per cd-Befehl ins Stammverzeichnis Ihres ASP.NET-Projekts (das die web.config-Datei enthält).
bash
```
# Beispiel: Wechsle ins MyWebApp Verzeichnis
cd /Applications/ServBay/www/MyWebApp
```
1
2
XSP-Server starten: Führen Sie im Projektverzeichnis das folgende Kommando aus, um den XSP4-Server zu starten. Wählen Sie dafür einen freien Port wie 8080 oder 9000, damit es nicht zu Konflikten mit anderen ServBay-Diensten kommt.
bash
```
# Starte das Projekt auf Port 9000
xsp4 --port 9000
```
1
2
- xsp4: Der für .NET Framework 4.x geeignete Server.
- --port 9000: TCP-Port, auf den der Server lauscht.
Anwendung im Browser aufrufen: Öffnen Sie Ihren Webbrowser und gehen Sie zu http://localhost:9000 bzw. http://127.0.0.1:9000. Ihre ASP.NET-Anwendung sollte jetzt erreichbar sein.
Server anhalten: Wenn Sie mit Entwicklung/Test fertig sind, stoppen Sie den XSP-Server im Terminal-Fenster mit Ctrl + C oder durch Drücken der Eingabetaste.

Vorteile:

Sehr einfache Konfiguration und schneller Start.
Optimal für lokale Entwicklung und Debugging.

Nachteile:

Geringere Performance als produktionsreife Webserver wie Nginx.
Funktional eingeschränkt – nicht alle Produktionsbedingungen sind exakt nachgebildet.
Terminal muss zum Betrieb geöffnet bleiben.

Methode 2: Einsatz von Nginx + FastCGI

Bei dieser Methode agiert ServBays Nginx als Webserver-Frontend: Er nimmt Client-Anfragen entgegen, bedient statische Dateien direkt und leitet Anfragen zu dynamischen Ressourcen (.aspx, .ashx etc.) via FastCGI-Protokoll an den Mono-Backend-Prozess (fastcgi-mono-server4) weiter. Das ist produktionsnäher, performanter und ermöglicht die Nutzung der erweiterten Features von Nginx (z. B. SSL, Caching, Kompression usw.).

Hinweis

ASP.NET 1.1-Projekte: fastcgi-mono-server
ASP.NET 2.0/3.x-Projekte: fastcgi-mono-server2
ASP.NET 4.x-Projekte: fastcgi-mono-server4

Vorgehensweise:

Mono und Nginx installiert & aktiv:
- Installieren Sie Mono 6 und Nginx über den Bereich „Pakete“ in ServBay.
- Prüfen Sie im Bereich „Dienste“, ob Nginx aktiv ist.
ASP.NET Projekt bereitstellen: Achten Sie darauf, dass Ihr Projekt im empfohlenen Verzeichnis wie /Applications/ServBay/www/MyWebApp liegt.
FastCGI-Mono-Server starten:
- Öffnen Sie ein neues Terminal-Fenster.
- Starten Sie den Prozess fastcgi-mono-server4, der Nginx-FastCGI-Anfragen entgegennimmt und Ihre ASP.NET-Seiten verarbeitet.
  bash
```
# Beispiel: FastCGI Mono Server für MyWebApp starten
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: Startet den Server für .NET Framework 4.x.
  - --applications=/:/Applications/ServBay/www/MyWebApp: Weist das URL-Root / dem physischen Verzeichnis /Applications/ServBay/www/MyWebApp zu. Wenn Nginx z. B. /some/page.aspx weiterleitet, sucht bzw. verarbeitet Mono diese relativ zu diesem Pfad. Ersetzen Sie /Applications/ServBay/www/MyWebApp unbedingt durch Ihren echten Projektordner!
  - --socket=tcp:127.0.0.1:9001: Lauscht auf localhost:9001 – der Port muss frei sein und zum späteren Nginx-Konfigurationswert passen.
  - --loglevels=Standard --printlog: (Optional) Gibt Standardlogdaten im Terminal zur besseren Analyse aus.
- Hinweis: Das Terminal-Fenster, in dem fastcgi-mono-server4 läuft, muss geöffnet bleiben – sonst stoppt der Dienst. Für den dauerhaften Betrieb empfiehlt sich ggf. die Nutzung von Tools wie nohup, screen oder tmux.

Nginx-Site konfigurieren:

Öffnen Sie in ServBay den Bereich „Sites“.
Fügen Sie eine neue Site hinzu oder bearbeiten Sie eine vorhandene.
Domain-Name einstellen: Zum Beispiel mywebapp.servbay.demo. ServBay trägt diesen Eintrag automatisch in die Hosts-Datei Ihres Macs ein (zeigt auf 127.0.0.1).
Root-Verzeichnis definieren: Wichtig! Legen Sie das Projektverzeichnis – etwa /Applications/ServBay/www/MyWebApp – als Webroot fest. So wird die root-Direktive in Nginx korrekt für statische Dateien gesetzt.

Eigene Konfiguration aktivieren & anpassen: Aktivieren Sie die Option „Eigene Konfiguration“ oben rechts in den Site-Einstellungen. ServBay generiert darauf basierend eine initiale Nginx-Konfiguration, die Sie nach Bedarf ergänzen oder anpassen, um ASP.NET-Anfragen per FastCGI an Mono weiterzuleiten.

Prüfen oder ergänzen Sie insbesondere folgende Abschnitte in der von ServBay generierten Konfiguration:

nginx

server {
    listen 80; # HTTP Port
    listen 443 ssl http2; # HTTPS Port mit SSL und HTTP/2

    # SSL-Zertifikat – von ServBay verwaltet
    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;

    # Zertifikatspfad – ServBay generiert & verwaltet diese automatisch
    ssl_certificate /Applications/ServBay/ssl/private/tls-certs/mywebapp.servbay.demo/mywebapp.servbay.demo.crt; # Pfad sollte zu Domain passen
    ssl_certificate_key /Applications/ServBay/ssl/private/tls-certs/mywebapp.servbay.demo/mywebapp.servbay.demo.key; # Pfad sollte zu Domain passen

    server_name mywebapp.servbay.demo; # Muss zu Ihrer ServBay-Site passen
    root /Applications/ServBay/www/MyWebApp; # **WICHTIG:** Muss zum eingestellten Webroot passen

    # ASP.NET Default-Dokumente, die Nginx bei fehlendem index.html/htm durchgeht
    index index.html index.htm default.aspx Default.aspx;

    # Haupt-Request-Logik
    location / {
        # Prüft, ob Datei oder Verzeichnis existiert; leitet sonst an @mono weiter
        try_files $uri $uri/ @mono;
    }

    # (Optional, empfohlen) Statische Dateien sehr effizient per Nginx ausliefern
    # Caching maximieren und Logeinträge für statische Dateien vermeiden
    location ~* \.(ico|css|js|gif|jpe?g|png|svg|woff|woff2|ttf|eot)$ {
        expires max;
        log_not_found off;
        access_log off;
    }

    # @mono Block: Leitet dynamische Anfragen an FastCGI Mono Server weiter
    location @mono {
        # FastCGI-Weiterleitung – Port muss mit fastcgi-mono-server4 übereinstimmen!
        fastcgi_pass 127.0.0.1:9001;

        # Standard-FastCGI-Parameter
        include fastcgi_params;
        # Wichtig: Ermittelt den Pfad der zu verarbeitenden Datei
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param PATH_INFO "";

        # (Optional) Zusätzliche FastCGI-Parameter nach Bedarf
        # fastcgi_param HOST $host;
    }

    # Weitere Standard-Logs, werden ggf. von ServBay ergänzt
    # access_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.access.log;
    # error_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.error.log;
}

Konfiguration speichern & Nginx neuladen/neustarten: Speichern Sie die Nginx-Konfiguration in ServBay. ServBay versucht, Nginx automatisch neuzuladen. Bei Syntaxfehlern erscheint eine Warnung. Wenn nötig können Sie auch im Bereich „Dienste“ Nginx manuell neu starten.

Anwendung aufrufen: Öffnen Sie den Browser und geben Sie die in Nginx eingestellte Domain ein (z. B. https://mywebapp.servbay.demo). Da SSL konfiguriert ist, empfiehlt sich die Nutzung von HTTPS. Nginx liefert statische Dateien direkt aus, dynamische Anfragen werden an fastcgi-mono-server4 weitergeleitet und von Mono abgearbeitet.

Vorteile:

Höhere Performance, Stabilität – optimal für produktionsnahe Tests.
Nutzung der vollen Nginx-Features (SSL, Static Files, Load Balancing etc.).
Eng integrierbar mit ServBays Site-, Domain- und Hosts-Management.

Nachteile:

Konfiguration etwas komplexer als XSP.
Der fastcgi-mono-server4-Prozess muss manuell verwaltet werden (außer bei Backend-Tools).

Auswahl der passenden Methode

Für schnelle Entwicklung, Debugging und einfache Funktionstests wählen Sie XSP – schnell und unkompliziert per Terminalbefehl.
Für höhere Performance, produktionsnahe Tests oder interne Deployments sowie zum Einsatz erweiterter Nginx-Funktionen (HTTPS, eigene Domains, optimierte Dateiauslieferung) empfiehlt sich Nginx + FastCGI.

Hinweise & Fehlersuche

Dateiberechtigungen: Achten Sie darauf, dass sowohl der von ServBay verwaltete Nginx-Benutzer als auch Ihr (macOS-)Benutzer für fastcgi-mono-server4 ausreichende Lese/Rechte auf Ihr Projektverzeichnis (/Applications/ServBay/www/YourProjectName) haben. Falls nötig prüfen/anpassen mit chmod bzw. chown.
Pfad-Konsistenz: Kontrollieren Sie akribisch, dass die Projektpfade sowohl in der Nginx-Konfiguration (root) als auch im fastcgi-mono-server4-Kommando (--applications) korrekt gesetzt sind – jeweils auf den Projektstamm mit web.config zeigen.
Port-Konflikte: Stellen Sie sicher, dass die verwendeten Ports (z. B. 9000, 9001) weder von ServBay noch anderen Programmen belegt sind.
Log-Analyse:
- Terminalausgabe beim Start von fastcgi-mono-server4 beobachten. Die Option --printlog erleichtert Live-Logdiagnose.
- Prüfen Sie die Nginx-Error-Logs. Die jeweiligen Pfade finden Sie in den Site-Einstellungen in ServBay; standardmäßig liegen sie unter /Applications/ServBay/logs/nginx/your-domain.error.log. Diese sind essenziell, um Nginx- oder Kommunikationsfehler zwischen Nginx und FastCGI zu identifizieren.
Mono Kompatibilität: Das in ServBay eingebaute Mono 6.14.0 ist im Regelfall kompatibel mit .NET Framework 1.1 bis 4.7.2. Sollten Sie Features aus höheren Framework-Versionen nutzen, oder auf Kompatibilitätsprobleme stoßen, empfiehlt sich entweder die Nutzung des ServBay-Microsoft-Stacks oder ein Downgrade Ihres Projekts auf von Mono unterstützte Versionen.
FastCGI Prozess-Management: Entscheiden Sie sich für Nginx + FastCGI, denken Sie daran, dass der fastcgi-mono-server4-Prozess dauerhaft laufen muss – beim Entwickeln genügt ein offenes Terminal, für den produktiven Betrieb empfiehlt sich eine Einrichtung als Hintergrunddienst oder mit einem Prozessmanager.

Mit der integrierten Mono 6-Umgebung und einer gut durchdachten Projektstruktur gestaltet sich die Entwicklung und das Betreiben klassischer ASP.NET Framework 4.x-Anwendungen auf dem Mac mit ServBay deutlich unkomplizierter und professioneller. Wir wünschen viel Erfolg bei Ihrem Einstieg in die plattformübergreifende .NET-Webentwicklung!

ASP.NET Framework 4.x Entwicklung auf macOS mit ServBay ​

Voraussetzungen ​

Ihr ASP.NET Projekt vorbereiten ​

Methode 1: Einsatz von XSP (integrierter Entwicklungsserver) ​

Methode 2: Einsatz von Nginx + FastCGI ​

Auswahl der passenden Methode ​

Hinweise & Fehlersuche ​