Разработка 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, что предоставляет два основных способа запуска приложений ASP.NET Framework 4.x:

Быстрая разработка и тестирование с помощью XSP: XSP — это лёгкий веб-сервер, оптимизированный под Mono, идеально подходит для локального программирования и оперативных тестов.
Развертывание через Nginx + FastCGI: Более стабильный и производительный вариант, ориентированный на условия, близкие к промышленной эксплуатации: Nginx, управляемый ServBay, перенаправляет запросы к Mono-бэкенду через FastCGI.

В этом руководстве рассматривается процесс настройки и запуска вашего проекта ASP.NET Framework 4.x в среде ServBay.

О .NET Framework и .NET

Обратите внимание: данный документ посвящён разработке на основе Mono для ASP.NET Framework 4.x — это более старая ветка технологий .NET.

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

Требования

Установка ServBay: Убедитесь, что на вашем macOS установлен ServBay версии 1.12.0 или новее.
Установка Mono:
- Запустите приложение ServBay.
- В левой панели выберите раздел «Пакеты».
- В списке найдите категорию «.NET» и разверните её.
- Найдите «Mono 6» (версия должна быть минимум 6.14.0), кликните «Установить» справа и дождитесь окончания установки.

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

Файлы проекта: У вас должен быть проект ASP.NET Framework 4.x — Web Application или Web Site, содержащий файл web.config.
Рекомендованный путь размещения: Мы настоятельно рекомендуем помещать все проекты в централизованную директорию ServBay — www, расположенную по адресу /Applications/ServBay/www/. Для каждого проекта создавайте отдельную подпапку.
- Пример: для проекта MyWebApp корневой путь к сайту будет /Applications/ServBay/www/MyWebApp.
- В дальнейшем в примерах используется именно этот путь — обязательно заменяйте его на актуальный для вашего проекта.

Метод 1: Использование XSP (встроенного сервера разработки)

XSP — это лёгкий веб-сервер из состава 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: запускает сервер для .NET Framework 4.x.
- --port 9000: указывает TCP-порт, который будет слушать сервер.
Откройте приложение в браузере: Перейдите по адресу http://localhost:9000 или http://127.0.0.1:9000 — вы должны увидеть работающий сайт ASP.NET.
Остановите сервер: После завершения разработки или тестирования вернитесь в окно терминала, где запущен XSP, и нажмите Ctrl + C или клавишу Enter для остановки сервера.

Плюсы:

Простота и скорость запуска.
Отлично подходит для локальной разработки и отладки.

Минусы:

Уступает по производительности промышленным веб-серверам типа Nginx.
Функционал ограничен — не имитирует целиком продакшн-среду.
Необходимо держать терминал открытым.

Метод 2: Использование Nginx + FastCGI

В этом подходе Nginx из комплекта ServBay выполняет роль фронтенда: обрабатывает запросы пользователей и статические файлы, а динамические (например, .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 активна.
Подготовьте ASP.NET проект: Переместите свой проект по рекомендуемому пути, например /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-рутов (/) на физический путь к проекту, например, /Applications/ServBay/www/MyWebApp. При запросе /some/page.aspx Mono ищет и исполняет файл по пути /Applications/ServBay/www/MyWebApp/some/page.aspx. Обязательно замените путь на фактический для вашего проекта.
  - --socket=tcp:127.0.0.1:9001: указывает адрес и порт, который слушает FastCGI-сервер. Выберите свободный порт (например, 9001) и используйте тот же порт потом в конфигурации Nginx через директиву fastcgi_pass.
  - --loglevels=Standard --printlog: (по желанию) выводит стандартные логи Mono в терминал.
- Внимание: Окно терминала, где запущен fastcgi-mono-server4, должно оставаться открытым, иначе процесс завершится. Для фонового режима рекомендуется использовать nohup, screen, tmux и аналогичные утилиты.

Настройте сайт в Nginx:

В ServBay откройте раздел «Сайты».
Создайте новый сайт или выберите существующий для редактирования.
Задайте доменное имя: Например, mywebapp.servbay.demo. ServBay автоматически пропишет это имя в файл Hosts, назначив IP 127.0.0.1.
Укажите корневой каталог сайта: Важно! Установите путь к корню проекта, например /Applications/ServBay/www/MyWebApp. Это значение попадёт в директиву root в конфигурации Nginx и определит обработку статических файлов.

Включите и откройте пользовательскую конфигурацию: Поставьте галочку у опции «Пользовательская конфигурация» в настройках сайта. ServBay создаст базовый конфиг nginx, который следует отредактировать, чтобы корректно проксировать запросы ASP.NET к Mono через FastCGI.

Пример фрагмента Nginx-конфига, который требуется уточнить/добавить:

nginx

server {
    listen 80; # HTTP-порт
    listen 443 ssl http2; # HTTPS с поддержкой 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;

    # Пути до сертификатов, генерируемых 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; # Должно совпадать с настройками сайта в ServBay
    root /Applications/ServBay/www/MyWebApp; # **Убедитесь**, что совпадает с корнем сайта

    # Добавлены стандартные ASP.NET стартовые страницы
    index index.html index.htm default.aspx Default.aspx;

    # Основная логика обработки запросов
    location / {
        # Сначала ищет физический файл ($uri) или папку ($uri/);
        # если не найдено — перенаправляет на @mono
        try_files $uri $uri/ @mono;
    }

    # (Рекомендуется) — Nginx раздаёт статические файлы напрямую
    location ~* \.(ico|css|js|gif|jpe?g|png|svg|woff|woff2|ttf|eot)$ {
        expires max; # Максимальное кэширование в браузерах
        log_not_found off; # Не логировать ошибки отсутствия статических файлов
        access_log off; # Не вести отдельный лог обращений к статике
    }

    # Блок для передачи динамических запросов Mono
    location @mono {
        # FastCGI Mono Server — порт должен совпадать с указанным при запуске Mono (например, 9001)
        fastcgi_pass 127.0.0.1:9001;

        # Подключение стандартных FastCGI-параметров
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        # PATH_INFO обычно не нужен
        fastcgi_param PATH_INFO "";

        # Прочие параметры опциональны
        # fastcgi_param HOST $host;
    }

    # ServBay также может прописывать пути к логам и другие настройки
    # 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 будет автоматически перезагружен. При ошибках ServBay предложит их исправить. При необходимости перезапустите Nginx вручную через раздел «Сервисы».

Откройте сайт в браузере: Перейдите по адресу вашего домена (например, https://mywebapp.servbay.demo). Если сайт настраивался с поддержкой SSL (порт 443), заходите по HTTPS — Nginx обслужит статические файлы напрямую, а динамические .aspx или .ashx передаст серверу Mono через FastCGI для обработки .NET-кода.

Плюсы:

Высокая производительность, стабильная работа — идеальна для тестирования, близкого к промышленному.
Использование всего потенциала Nginx: работа со статикой, SSL, балансировка, кэширование и пр.
Глубокая интеграция с системой управления сайтами и доменами ServBay.

Минусы:

Сложность настройки выше, чем у XSP.
Необходимо следить за жизненным циклом процесса fastcgi-mono-server4 (желательно запускать его в фоне через менеджер процессов).

Как выбрать подходящий способ

Для быстрой разработки, отладки и тестирования выбирайте XSP — самый лёгкий, минимальный по настройке и мгновенно запускаемый вариант.
Для оптимальной производительности, полноценной предпродакшн среды или если важно использование профессиональных возможностей Nginx и управления сайтами/SSL — используйте связку Nginx + FastCGI.

Важные нюансы и устранение неисправностей

Права доступа к файлам: Процессы Nginx (обычно запускаемые ServBay) и пользователь, работающий с fastcgi-mono-server4, должны иметь права на чтение всех файлов проекта (в /Applications/ServBay/www/YourProjectName). При необходимости используйте chmod и chown для корректировки прав.
Корректность путей: Проверьте, что пути в настройках Nginx (root) и при запуске Mono (--applications) абсолютно идентичны и указывают на каталог с файлом web.config.
Свободные порты: Проследите, чтобы XSP или fastcgi-mono-server4 использовали порты (например, 9000 или 9001), которые не заняты другими службами в ServBay или сторонними приложениями.
Анализ логов:
- Проверяйте логи, выводимые Mono при запуске fastcgi-mono-server4 (параметр --printlog поможет направить все в терминал).
- Изучайте логи ошибок Nginx — путь до него ServBay указывает в настройках сайта, обычно это /Applications/ServBay/logs/nginx/your-domain.error.log. Анализируйте их при любых проблемах с проксированием или обработкой запросов.
Совместимость версий Mono: Mono 6.14.0 от ServBay обеспечивает совместимость с .NET Framework 1.1–4.7.2. Если используются особенности более новых версий или возникают проблемы, попробуйте запускать проект через официальный .NET SDK/рантайм Microsoft или понизьте уровень .NET Framework до поддерживаемого Mono.
Управление процессами FastCGI: При использовании схемы Nginx + FastCGI не забывайте, что процесс fastcgi-mono-server4 должен быть запущен без остановки — для разработки достаточно держать терминал открытым, для стабильной работы стоит рассмотреть запуск как фонового сервиса или с помощью менеджеров процессов.

Благодаря интегрированной среде Mono 6 и удобной проектной структуре, разработка традиционных приложений ASP.NET Framework 4.x на macOS с помощью ServBay становится максимально простой и надёжной. Пусть это руководство поможет вам успешно стартовать и эффективно работать с вашими .NET-проектами!

Разработка ASP.NET Framework 4.x на macOS с помощью ServBay ​

Требования ​

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

Метод 1: Использование XSP (встроенного сервера разработки) ​

Метод 2: Использование Nginx + FastCGI ​

Как выбрать подходящий способ ​

Важные нюансы и устранение неисправностей ​