Rozwój aplikacji ASP.NET Framework 4.x na macOS z ServBay

ServBay, dzięki wbudowanemu i rozbudowanemu środowisku Mono, umożliwia łatwy rozwój i testowanie aplikacji ASP.NET Framework 1.1/2.0/3.x/4.x (do wersji 4.7.x włącznie) na macOS.

Od wersji ServBay v1.12.0, oprogramowanie to zawiera Mono 6.14.0 oraz wbudowane narzędzia XSP (serwer deweloperski) i fastcgi-mono-server. Zapewnia to dwa główne sposoby uruchamiania aplikacji ASP.NET Framework 4.x:

Szybki rozwój i testowanie z użyciem XSP: XSP to lekki serwer ASP.NET opracowany dla Mono – idealny do etapu programowania i szybkich testów lokalnych.
Wdrożenie z Nginx + FastCGI: To podejście zapewnia wyższą wydajność, większą stabilność i lepsze odwzorowanie środowiska produkcyjnego. Nginx (zarządzany przez ServBay) przekierowuje żądania do backendowego procesu Mono.

W tym przewodniku pokażemy krok po kroku, jak skonfigurować i uruchomić projekt ASP.NET Framework 4.x w środowisku ServBay.

O .NET Framework i .NET

Pamiętaj, że ten przewodnik dotyczy ASP.NET Framework 4.x wykorzystującego Mono, czyli starszej wersji stosu technologicznego .NET.

ServBay obsługuje również najnowszy .NET (w tym .NET Core, .NET 5/6/7/8+). Jeśli tworzysz nowy projekt lub zamierzasz przejść na nowszą technologię, zalecamy korzystanie z oficjalnego SDK/runtime Microsoft .NET oferowanego przez ServBay, zamiast rozwiązań opartych o Mono i ASP.NET Framework opisanych w tym dokumencie.

Wymagania wstępne

Zainstaluj ServBay: Upewnij się, że masz zainstalowany ServBay w wersji v1.12.0 lub nowszej na macOS.
Zainstaluj Mono:
- Otwórz aplikację ServBay.
- W lewym pasku nawigacji wybierz „Pakiety”.
- Na liście pakietów przejdź do kategorii „.NET” i rozwiń ją.
- Znajdź „Mono 6” (wersja 6.14.0 lub nowsza), kliknij przycisk „Instaluj” po prawej stronie i poczekaj na zakończenie instalacji.

Przygotowanie projektu ASP.NET

Pliki projektu: Upewnij się, że posiadasz projekt typu Web Application lub Web Site dla ASP.NET Framework 4.x, zawierający plik web.config.
Rekomendowane miejsce przechowywania: Zalecamy umieszczenie swojego projektu w katalogu www zarządzanym przez ServBay, czyli /Applications/ServBay/www/. Utwórz osobny podkatalog dla każdego projektu.
- Przykład: Jeśli projekt nosi nazwę MyWebApp, rekomendowana ścieżka to /Applications/ServBay/www/MyWebApp.
- W dalszej części przewodnika korzystamy z przykładu /Applications/ServBay/www/MyWebApp. Podmień tę ścieżkę na rzeczywistą ścieżkę swojego projektu.

Metoda 1: Użycie XSP (wbudowany serwer deweloperski)

XSP to lekki serwer WWW dołączony do Mono, świetny do lokalnego rozwoju i szybkich testów aplikacji ASP.NET Framework. Instalacja Mono 6 w ServBay zawiera XSP4 (dla ASP.NET 4.x).

Wskazówki

Dla projektów ASP.NET 1.1 użyj polecenia xsp.
Dla projektów ASP.NET 2.0/3.x użyj polecenia xsp2.
Dla projektów ASP.NET 4.x użyj polecenia xsp4.

Kroki:

Uruchom terminal: Otwórz aplikację Terminal w systemie macOS.
Przejdź do katalogu projektu: Użyj polecenia cd, aby przejść do głównego katalogu projektu ASP.NET (zawierającego plik web.config).
bash
```
# Przykład: wejście do katalogu projektu MyWebApp
cd /Applications/ServBay/www/MyWebApp
```
1
2
Uruchom serwer XSP: Będąc w katalogu głównym projektu, uruchom poniższe polecenie, by wystartować XSP4 na wybranym, wolnym porcie (np. 8080 lub 9000), unikając konfliktów z innymi usługami ServBay.
bash
```
# Uruchamianie projektu na porcie 9000
xsp4 --port 9000
```
1
2
- xsp4: Uruchamia serwer XSP dla .NET Framework 4.x.
- --port 9000: Ustala numer portu do nasłuchu serwera.
Uzyskaj dostęp do aplikacji: Otwórz przeglądarkę i wpisz http://localhost:9000 lub http://127.0.0.1:9000. Powinieneś zobaczyć swoją aplikację ASP.NET działającą lokalnie.
Zatrzymanie serwera: Po zakończeniu pracy wróć do terminala, w którym działa XSP i naciśnij Ctrl + C lub klawisz Enter, aby zatrzymać serwer.

Zalety:

Bardzo prosty w konfiguracji, szybki start.
Idealny do lokalnego developmentu i debugowania.

Wady:

Niższa wydajność od profesjonalnych serwerów (np. Nginx).
Ograniczone możliwości – nie symuluje w pełni środowiska produkcyjnego.
Konieczność pozostawienia uruchomionego okna terminala.

Metoda 2: Nginx + FastCGI

W tej metodzie Nginx (zarządzany przez ServBay) działa jako serwer frontendowy – obsługuje statyczne pliki oraz przekazuje żądania dynamiczne (np. .aspx, .ashx) do backendowego procesu Mono (fastcgi-mono-server4) za pomocą protokołu FastCGI. To rozwiązanie jest wydajniejsze, lepiej odwzorowuje środowisko produkcyjne i umożliwia korzystanie z zaawansowanych funkcji Nginx (np. SSL, cache, kompresja).

Wskazówki

Dla projektów ASP.NET 1.1 użyj polecenia fastcgi-mono-server.
Dla projektów ASP.NET 2.0/3.x użyj polecenia fastcgi-mono-server2.
Dla projektów ASP.NET 4.x użyj polecenia fastcgi-mono-server4.

Kroki:

Upewnij się, że Mono i Nginx są zainstalowane i uruchomione:
- Zainstaluj Mono 6 i Nginx przez sekcję „Pakiety” w ServBay.
- Upewnij się, że w sekcji „Usługi” w ServBay Nginx jest uruchomiony.
Przygotuj projekt ASP.NET: Upewnij się, że projekt znajduje się we wskazanej ścieżce, np. /Applications/ServBay/www/MyWebApp.
Uruchom FastCGI Mono Server:
- Otwórz nowy terminal.
- Uruchom proces fastcgi-mono-server4, który będzie nasłuchiwał żądań FastCGI z Nginx i obsługiwał logikę ASP.NET.
  bash
```
# Przykład: uruchomienie FastCGI dla projektu 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: Uruchamia serwer FastCGI dla .NET Framework 4.x.
  - --applications=/:/Applications/ServBay/www/MyWebApp: Mapuje root URL (/) na fizyczną ścieżkę projektu. Przy przychodzących żądaniach, Mono odszuka plik ASPX na tej ścieżce. Pamiętaj, aby zamienić /Applications/ServBay/www/MyWebApp na prawdziwą ścieżkę swojego projektu!
  - --socket=tcp:127.0.0.1:9001: Określa adres IP i port do nasłuchu FastCGI. Musisz upewnić się, że wybrany port (np. 9001) nie jest zajęty.
  - --loglevels=Standard --printlog: (Opcjonalne) Pokazuje logi w terminalu, co ułatwia debugowanie.
- Uwaga: Aby aplikacja działała, terminal z uruchomionym fastcgi-mono-server4 musi pozostać otwarty. Dla dłuższych sesji możesz skorzystać z narzędzi takich jak nohup, screen lub tmux.

Skonfiguruj stronę Nginx:

W ServBay przejdź do sekcji „Strony”.
Kliknij „Dodaj stronę” lub wybierz istniejącą do edycji.
Ustaw nazwę domeny: np. mywebapp.servbay.demo. ServBay automatycznie doda ją do pliku Hosts i skieruje na 127.0.0.1.
Ustaw katalog główny strony: Bardzo ważne! Wskaż ścieżkę do projektu ASP.NET, np. /Applications/ServBay/www/MyWebApp. Pozwoli to poprawnie skonfigurować dyrektywę root Nginx do obsługi plików statycznych.

Edytuj własną konfigurację: Zaznacz opcję „Własna konfiguracja”. ServBay wygeneruje bazowy plik konfiguracyjny Nginx – należy dodać/modyfikować sekcje odpowiadające za przekierowanie żądań dynamicznych do FastCGI Mono Server.

Na przykład, wygenerowana konfiguracja może wyglądać tak:

nginx

server {
    listen 80; # Nasłuch na porcie HTTP
    listen 443 ssl http2; # Obsługa HTTPS, włączony SSL i HTTP/2

    # Automatyczna konfiguracja certyfikatów SSL przez 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;

    # Ścieżki do plików certyfikatów – automatycznie zarządzane przez ServBay
    ssl_certificate /Applications/ServBay/ssl/private/tls-certs/mywebapp.servbay.demo/mywebapp.servbay.demo.crt; # Upewnij się, że certyfikat zgadza się z nazwą domeny
    ssl_certificate_key /Applications/ServBay/ssl/private/tls-certs/mywebapp.servbay.demo/mywebapp.servbay.demo.key; # jw.

    server_name mywebapp.servbay.demo; # Powinna pokrywać się z wpisem w ServBay
    root /Applications/ServBay/www/MyWebApp; # **Musi** być zgodna z katalogiem projektu

    # Dodanie domyślnych dokumentów ASP.NET – fallback, jeśli nie ma index.html/htm
    index index.html index.htm default.aspx Default.aspx;

    # Główna logika routingu
    location / {
        try_files $uri $uri/ @mono; # Wyszukaj plik/katalog; jeśli nie – przekieruj do FastCGI
    }

    # (Opcjonalnie, zalecane) – szybka obsługa plików statycznych przez Nginx z cache
    location ~* \.(ico|css|js|gif|jpe?g|png|svg|woff|woff2|ttf|eot)$ {
        expires max;
        log_not_found off;
        access_log off;
    }

    # Punkt wejścia dla routing'u ASP.NET – jeśli statyczny plik nie istnieje
    location @mono {
        fastcgi_pass 127.0.0.1:9001; # **Port musi** zgadzać się z tym ustawionym w FastCGI

        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param PATH_INFO "";

        # Dodatkowe parametry FastCGI, np. HOST, jeśli potrzebne
        # fastcgi_param HOST $host;
    }

    # ServBay doda również inne opcje, np. ścieżki logów:
    # access_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.access.log;
    # error_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.error.log;
}

Zapisz konfigurację i przeładuj/uruchom ponownie Nginx: Zapisz plik konfiguracyjny w ServBay. ServBay spróbuje automatycznie przeładować Nginx; jeśli pojawią się błędy składni, pokaże odpowiedni komunikat. W razie potrzeby przejdź do sekcji „Usługi” i ręcznie uruchom ponownie Nginx.

Uzyskaj dostęp do aplikacji: Wejdź do przeglądarki i wpisz domenę skonfigurowaną w Nginx (np. https://mywebapp.servbay.demo). Dzięki obsłudze portu 443 z SSL, zalecane jest korzystanie z HTTPS. Nginx samodzielnie obsłuży pliki statyczne, a żądania dynamiczne przekaże do procesu fastcgi-mono-server4, gdzie Mono wykona kod ASP.NET.

Zalety:

Wysoka wydajność, większa stabilność, rekomendowane do testów przypominających środowisko produkcyjne.
Możliwość korzystania z dorobku Nginx (statyczne pliki, SSL, balansery itd.).
Dobra integracja z zarządzaniem stronami, domenami i plikiem Hosts przez ServBay.

Wady:

Konfiguracja jest bardziej złożona niż przy użyciu XSP.
Wymaga ręcznego zarządzania procesem fastcgi-mono-server4 (chyba że pracujesz z narzędziami do pracy w tle).

Jak wybrać odpowiednią metodę

Do szybkiego developmentu, debugowania i prostych testów funkcjonalnych polecamy użycie XSP – jest to najprostsza i najszybsza opcja, uruchamiana jednym poleceniem.
Dla testów wydajnościowych, środowisk zbliżonych do produkcyjnych albo korzystania z zaawansowanych funkcji Nginx (np. HTTPS, własne domeny, optymalizacja statycznych plików) oraz do lepszej integracji z zarządzaniem stronami w ServBay rekomendujemy wariant Nginx + FastCGI.

Wskazówki i rozwiązywanie problemów

Uprawnienia do plików: Użytkownik, pod którym działa Nginx (oraz uruchamiany przez Ciebie fastcgi-mono-server4), musi mieć odpowiednie uprawnienia do odczytu plików projektu (np. /Applications/ServBay/www/YourProjectName). W razie problemów możesz użyć chmod lub chown do dostosowania uprawnień.
Spójność ścieżek: Wielokrotnie sprawdź, czy w konfiguracji Nginx (root) i w poleceniu uruchamiania fastcgi-mono-server4 (--applications) widnieje ta sama, właściwa ścieżka – wskazująca katalog z plikiem web.config.
Konflikt portów: Upewnij się, że wybrane porty (np. 9000 lub 9001) nie są już w użyciu przez inne usługi lub aplikacje.
Sprawdzanie logów:
- Przeanalizuj logi wyświetlane w terminalu podczas uruchamiania fastcgi-mono-server4 (flaga --printlog).
- Sprawdź logi błędów Nginx – w ustawieniach stron w ServBay znajdziesz ich dokładną ścieżkę, na przykład /Applications/ServBay/logs/nginx/your-domain.error.log. Analiza tych logów bardzo pomaga w rozwiązywaniu problemów konfiguracyjnych lub z komunikacją pomiędzy Nginx a FastCGI Mono Server.
Kompatybilność Mono: Wersja Mono 6.14.0 zawarta w ServBay generalnie obsługuje .NET Framework od 1.1 do 4.7.2. Korzystając z funkcji dostępnych w wyższych wersjach lub napotykając problemy ze zgodnością, rozważ użycie .NET SDK/Runtime od Microsoft dostępnego w ServBay albo obniżenie wersji Framework w projekcie.
Zarządzanie procesem FastCGI: Przy wyborze opcji Nginx + FastCGI pamiętaj: proces fastcgi-mono-server4 musi być cały czas aktywny. Na czas developmentu wystarczy otwarty terminal, ale w przypadku dłuższego działania rozważ użycie narzędzi takich jak menedżer usług, screen lub tmux.

Wykorzystując wbudowane środowisko Mono 6 i sprawdzoną strukturę projektów ServBay, programowanie i uruchamianie klasycznych aplikacji ASP.NET Framework 4.x na Macu jest dużo prostsze i bardziej uporządkowane. Mamy nadzieję, że dzięki temu przewodnikowi szybko i bezproblemowo rozpoczniesz prace developerskie!

Rozwój aplikacji ASP.NET Framework 4.x na macOS z ServBay ​

Wymagania wstępne ​

Przygotowanie projektu ASP.NET ​

Metoda 1: Użycie XSP (wbudowany serwer deweloperski) ​

Metoda 2: Nginx + FastCGI ​

Jak wybrać odpowiednią metodę ​

Wskazówki i rozwiązywanie problemów ​