Розробка ASP.NET Framework 4.x на macOS із ServBay

ServBay завдяки вбудованому потужному середовищу Mono дозволяє легко і зручно розробляти та тестувати ASP.NET Framework 1.1/2.0/3.x/4.x (до версії 4.7.x включно) на macOS.

Починаючи з версії ServBay v1.12.0, інтегровано Mono 6.14.0 із попередньо встановленими сервером XSP для розробки та інструментом fastcgi-mono-server, що відкриває 2 основні способи запуску ASP.NET Framework 4.x додатків:

Використання XSP для швидкої розробки й тестування: XSP — це легкий вебсервер, створений для Mono і ідеально підходить для етапу розробки чи тестування.
Деплой через Nginx + FastCGI: Це стійкий, високопродуктивний спосіб, аналогічний продакшен-оточенню: запити через керований ServBay Nginx перенаправляються на бекенд Mono.

У цьому документі ви знайдете покрокову інструкцію з налаштування та запуску вашого ASP.NET Framework 4.x проекту під ServBay.

Про .NET Framework та .NET

Зверніть увагу, що цей документ присвячено розробці ASP.NET Framework 4.x на базі Mono — це класичний стек .NET.

ServBay також повністю підтримує сучасний .NET (включно з .NET Core, .NET 5/6/7/8+). Якщо ви створюєте новий .NET проект або плануєте міграцію на сучасну платформу, радимо користуватися офіційним Microsoft .NET SDK/рантаймом, що постачається з ServBay, а не методами Mono, описаними у цьому документі.

Необхідні передумови

Встановлення ServBay: Переконайтеся, що у вас встановлено ServBay v1.12.0 чи новішої версії на macOS.
Встановлення Mono:
- Запустіть додаток ServBay.
- У лівій навігації оберіть розділ «Пакети».
- У списку пакетів знайдіть категорію «.NET» і розгорніть її.
- Знайдіть «Mono 6» (версія має бути 6.14.0 або новіша), натисніть «Встановити» праворуч і зачекайте завершення встановлення.

Підготовка ASP.NET проекту

Файли проекту: Переконайтеся, що у вас є ASP.NET Framework 4.x Web Application чи Web Site проект із файлом web.config.
Рекомендована структура: Наполегливо радимо розміщувати ваш проект у папці www, яка управляється ServBay: /Applications/ServBay/www/. Створіть окрему підпапку для кожного проекту.
- Приклад: якщо проект називається MyWebApp, рекомендується використовувати шлях /Applications/ServBay/www/MyWebApp.
- У наступних кроках для прикладу використовується цей шлях. Обов’язково замініть його на шлях до вашого реального проекту.

Метод 1: XSP (вбудований сервер для розробки)

XSP — легкий Web-сервер, що постачається з Mono, ідеальний для локальної розробки та швидкого тестування додатків ASP.NET Framework. Mono 6 із ServBay уже містить XSP4 (для ASP.NET 4.x).

Підказка

Для ASP.NET 1.1 використовуйте команду xsp.
Для ASP.NET 2.0/3.x використовуйте xsp2.
Для ASP.NET 4.x використовуйте xsp4.

Кроки:

Відкрийте термінал: Запустіть застосунок Terminal у macOS.
Перейдіть у директорію проекту: Використайте команду cd, щоб перейти у корінну папку вашого ASP.NET проекту (де міститься web.config).
bash
```
# Приклад: перехід до папки проекту MyWebApp
cd /Applications/ServBay/www/MyWebApp
```
1
2
Запустіть сервер XSP: У директорії проекту виконайте наступну команду для запуску XSP4 на вибраному вільному порту (наприклад, 8080 або 9000), щоб уникнути конфліктів із іншими сервісами ServBay.
bash
```
# Старт проекту у поточній директорії на порту 9000
xsp4 --port 9000
```
1
2
- xsp4: запускає сервер XSP для .NET Framework 4.x.
- --port 9000: вказує порт для прослуховування.
Доступ до застосунку: Відкрийте браузер і перейдіть за адресою http://localhost:9000 або http://127.0.0.1:9000. Ви маєте побачити роботу свого ASP.NET додатку.
Зупинка сервера: Після завершення роботи поверніться у вікно терміналу, де запущено XSP, і натисніть Ctrl + C або Enter для зупинки сервера.

Переваги:

Легке та швидке налаштування.
Чудово підходить для розробки й дебагу.

Недоліки:

Не такий продуктивний, як продакшен-сервери (Nginx тощо).
Функціонал простий, не імітує повністю "бойове" середовище.
Потрібно тримати вікно терміналу відкритим.

Метод 2: Nginx + FastCGI

У цьому методі Nginx (керований через ServBay) працює фронтендом, обробляє статичні файли, а динамічні ASP.NET-запити (наприклад, .aspx, .ashx) перенаправляє через FastCGI-протокол до процесу Mono (fastcgi-mono-server4). Така схема ближча до реального продакшену, забезпечує кращу продуктивність і дозволяє використовувати всі можливості Nginx (SSL, кешування, стиснення і т.д.).

Підказка

Для ASP.NET 1.1 використовуйте команду fastcgi-mono-server.
Для ASP.NET 2.0/3.x використовуйте fastcgi-mono-server2.
Для ASP.NET 4.x використовуйте fastcgi-mono-server4.

Кроки:

Переконайтесь, що Mono і Nginx встановлені й працюють:
- Встановіть Mono 6 і Nginx через розділ «Пакети» у ServBay.
- Перейдіть до розділу «Сервіси» й переконайтеся, що Nginx запущено.
Підготуйте проект: Ваш проект має бути у рекомендованій папці, наприклад /Applications/ServBay/www/MyWebApp.
Запуск FastCGI Mono Server:
- Відкрийте нове вікно терміналу.
- Запустіть процес fastcgi-mono-server4. Він прийматиме FastCGI-запити від Nginx, опрацьовуватиме ASP.NET-сторінки та відповідатиме за бізнес-логіку.
  bash
```
# Приклад: запуск FastCGI для проекту 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: запуск FastCGI-сервера для .NET Framework 4.x.
  - --applications=/:/Applications/ServBay/www/MyWebApp: мапінг кореня URL (/) до фізичного шляху проекту. Mono шукатиме, наприклад, /Applications/ServBay/www/MyWebApp/some/page.aspx для /some/page.aspx. Замініть шлях на актуальний для вашого проекту!
  - --socket=tcp:127.0.0.1:9001: сервер слухає лише локальні з’єднання на порту 9001. Переконайтеся, що цей порт не зайнятий і співпадає з портом у налаштуваннях Nginx нижче.
  - --loglevels=Standard --printlog: (опційно) друкувати стандартні логи у термінал для діагностики.
- Увага: Вікно терміналу зі службою fastcgi-mono-server4 повинно залишатися відкритим, інакше сервер зупиниться. Для тривалого запуску використовуйте nohup, screen чи tmux.

Налаштування сайту у Nginx:

В ServBay перейдіть у розділ «Сайти».
Додайте новий сайт або відредагуйте існуючий.
Домен: Вкажіть зручний брендований домен, наприклад, mywebapp.servbay.demo. ServBay автоматично зареєструє цей домен у локальному Hosts-файлі для macOS і прив’яже до 127.0.0.1.
Корінь сайту: ВАЖЛИВО! Вкажіть фактичний шлях до проекту, наприклад, /Applications/ServBay/www/MyWebApp. Це задасть root-директиву Nginx для обробки статичних файлів.

Увімкнути та редагувати додаткову конфігурацію: Поставте галочку «Додаткова конфігурація». ServBay згенерує базовий Nginx-конфіг відповідно до ваших домену і директорії. Додайте вказані нижче (або схожі) налаштування для передачі ASP.NET-запитів на FastCGI Mono Server.

Ось приклад фрагмента конфігурації (навантаженої на сайт ServBay):

nginx

server {
    listen 80; # Слухає HTTP порт
    listen 443 ssl http2; # HTTPS, включено SSL та HTTP/2

    # SSL-сертифікати, якими керує 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;

    # Шляхи до сертифікатів — мають відповідати обраному домену
    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; # Має відповідати обраному домену в ServBay
    root /Applications/ServBay/www/MyWebApp; # **Обов'язково** співпадає із шляхом проекту

    # ASP.NET-дефолтні документи (за відсутності index.html/htm)
    index index.html index.htm default.aspx Default.aspx;

    # Головна логіка обробки запитів
    location / {
        # Послідовно шукає файл ($uri) чи папку ($uri/)
        # Якщо не знайдено статичних файлів — передає на @mono
        try_files $uri $uri/ @mono;
    }

    # (Опціонально) Кешування статичних файлів
    location ~* \.(ico|css|js|gif|jpe?g|png|svg|woff|woff2|ttf|eot)$ {
        expires max;
        log_not_found off;
        access_log off;
    }

    # Всі динамічні запити — на Mono через FastCGI
    location @mono {
        fastcgi_pass 127.0.0.1:9001; # СПІВПАДАЄ з портом fastcgi-mono-server4

        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; # для пошуку файлів Mono
        fastcgi_param PATH_INFO "";
        # fastcgi_param HOST $host; # за потреби додаткові параметри
    }

    # Можливе додаткове логування:
    # access_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.access.log;
    # error_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.error.log;
}

Збереження та перезапуск Nginx: Збережіть конфігурацію у ServBay. Програма спробує автоматично перезавантажити Nginx. У разі помилок відобразиться повідомлення із деталями. За потреби, перезапустіть Nginx вручну в розділі «Сервіси».

Відкрийте застосунок у браузері: Зайдіть за вказаним доменом (наприклад, https://mywebapp.servbay.demo). Завдяки SSL (порт 443), рекомендується використовувати HTTPS. Nginx відповідатиме за статичний контент, а динамічні запити віддасть Mono через fastcgi-mono-server4.

Переваги:

Вища продуктивність і стабільність — ближче до продакшену.
Можна повністю використовувати можливості Nginx (SSL, оптимізація статики тощо).
Глибока інтеграція із доменною і менеджмент-панеллю ServBay.

Недоліки:

Налаштовується дещо складніше, ніж XSP.
Потрібно ручне керування процесом fastcgi-mono-server4 (окрім випадків із зовнішніми менеджерами чи демонами).

Як вибрати відповідний метод

Для швидкої розробки, налагодження і простого тестування функцій найбільш просто і швидко скористатися XSP — запуск усього однієї командою.
Якщо потрібна вища продуктивність, тестування у наближених до продакшену умовах чи використання розширених можливостей (HTTPS, домени, оптимізація статики) — обирайте схему Nginx + FastCGI.

Додаткові поради та діагностика

Права доступу до файлів: Переконайтеся, що користувач macOS, від імені якого запускається Nginx (під керуванням ServBay), а також той, хто запускає fastcgi-mono-server4, мають права на читання файлів проекту (/Applications/ServBay/www/YourProjectName). За потреби використайте chmod чи chown для корекції доступу.
Відповідність шляхів: Ретельно перевірте, що вказівки root у Nginx і параметр --applications у fastcgi-mono-server4 вказують на одну і ту ж директорію проекту (де лежить web.config).
Конфлікти портів: Переконайтеся, що порт для XSP чи fastcgi-mono-server4 (наприклад, 9000 або 9001) не зайнятий іншими сервісами ServBay чи програмами.
Діагностика через логи:
- Переглядайте вивід у терміналі fastcgi-mono-server4 (зручно з параметром --printlog).
- Переглядайте error-лог Nginx; шлях зазвичай видно у налаштуваннях сайту, наприклад, /Applications/ServBay/logs/nginx/your-domain.error.log. Там часто міститься причина проблем із конфігурацією або зв’язком з FastCGI Mono Server.
Сумісність версій Mono: Вбудований Mono 6.14.0 доволі добре підтримує можливості .NET Framework 1.1 – 4.7.2. Якщо проект використовує новіші фічі чи виникають помилки — рекомендується або користуватися сучасним .NET SDK/рантаймом від Microsoft (які можна встановити в ServBay), або спробувати знизити версію фреймворка проекту.
Менеджмент процесу FastCGI: Для схеми з Nginx+FastCGI обов’язково стежте, щоб процес fastcgi-mono-server4 був увімкнений під час роботи сайту — можна запускати у фоновому режимі за допомогою менеджерів процесів або сервісів демона.

Завдяки інтегрованому середовищу Mono 6 у ServBay та рекомендованій структурі проектів, розробка і запуск класичних ASP.NET Framework 4.x додатків на macOS стають структурованими, надійними та зручними. Бажаємо вдалого старту у ваших розробках!

Розробка ASP.NET Framework 4.x на macOS із ServBay ​

Необхідні передумови ​

Підготовка ASP.NET проекту ​

Метод 1: XSP (вбудований сервер для розробки) ​

Метод 2: Nginx + FastCGI ​

Як вибрати відповідний метод ​

Додаткові поради та діагностика ​