Desarrollo de ASP.NET Framework 4.x en macOS con ServBay

ServBay, gracias a su potente entorno Mono integrado, facilita el desarrollo y las pruebas de ASP.NET Framework 1.1/2.0/3.x/4.x (con soporte hasta la versión 4.7.x) directamente en macOS.

Desde la versión v1.12.0 de ServBay, hemos integrado Mono 6.14.0, junto con el servidor de desarrollo XSP y la herramienta fastcgi-mono-server, ofreciéndote dos métodos principales para ejecutar aplicaciones ASP.NET Framework 4.x:

1. Desarrollo y pruebas rápidas con XSP: XSP es un servidor web ligero diseñado especialmente para Mono, ideal para el desarrollo y pruebas rápidas.
2. Despliegue con Nginx + FastCGI: Esta opción es más estable, ofrece un mejor rendimiento y se acerca más a un entorno productivo real, ya que Nginx (gestionado por ServBay) reenvía solicitudes al proceso Mono en segundo plano para su procesamiento.

Esta guía te mostrará cómo configurar y ejecutar tu proyecto ASP.NET Framework 4.x en el entorno ServBay.

Acerca de .NET Framework y .NET

Ten en cuenta que esta guía trata sobre el desarrollo de ASP.NET Framework 4.x basado en Mono, que pertenece a una pila tecnológica .NET más antigua.

ServBay también ofrece soporte completo para la última versión de .NET (incluyendo .NET Core, .NET 5/6/7/8+). Si desarrollas un proyecto .NET moderno o planeas migrar, te recomendamos usar el SDK/Runtime oficial de Microsoft proporcionado por ServBay en lugar del método basado en Mono aquí descrito.

Requisitos previos

1. Instalar ServBay: Asegúrate de tener instalado ServBay v1.12.0 o superior en macOS.
2. Instalar Mono:
   • Abre la aplicación ServBay.
   • En la barra de navegación lateral, selecciona “Paquetes”.
   • En la lista de paquetes, encuentra la categoría “.NET” y haz clic para expandirla.
   • Busca “Mono 6” (debe ser versión 6.14.0 o superior), haz clic en el botón “Instalar” y espera a que finalice la instalación.

Prepara tu proyecto ASP.NET

1. Archivos del proyecto: Asegúrate de contar con un proyecto ASP.NET Framework 4.x (Web Application o Web Site) que incluya el archivo web.config.
2. Ubicación recomendada: Te recomendamos encarecidamente colocar tu proyecto web dentro del directorio gestionado por ServBay, www: /Applications/ServBay/www/. Crea una subcarpeta independiente para cada proyecto.
   • Ejemplo: Si tu proyecto se llama MyWebApp, la ruta raíz recomendada es /Applications/ServBay/www/MyWebApp.
   • En los pasos siguientes, usaremos /Applications/ServBay/www/MyWebApp como ruta de ejemplo. Sustituye siempre esta ruta por la de tu proyecto real.

Método 1: Uso de XSP (servidor de desarrollo integrado)

XSP es el servidor web ligero incluido en el proyecto Mono, ideal para desarrollo local y pruebas rápidas de aplicaciones ASP.NET Framework. El paquete Mono 6 de ServBay incluye XSP4 (para ASP.NET 4.x).

Sugerencia

• Si tu proyecto es de ASP.NET 1.1, utiliza el comando xsp.
• Para ASP.NET 2.0/3.x, utiliza el comando xsp2.
• Para ASP.NET 4.x, utiliza el comando xsp4.

Pasos:

1. Abre la terminal: Lanza la aplicación Terminal de macOS.

2. Navega a tu directorio de proyecto: Usa el comando cd para ingresar al directorio raíz de tu proyecto ASP.NET (donde está el archivo web.config).

   # Ejemplo: entra en la carpeta de proyecto llamada MyWebApp
   cd /Applications/ServBay/www/MyWebApp

3. Inicia el servidor XSP: Dentro del directorio raíz, ejecuta el siguiente comando para iniciar XSP4. Puedes indicar un puerto libre (por ejemplo 8080 o 9000) para evitar conflictos con otros servicios de ServBay.

   # Iniciar el proyecto actual en el puerto 9000
   xsp4 --port 9000

   • xsp4: Inicializa el servidor XSP preparado para .NET Framework 4.x.
   • --port 9000: Especifica el puerto TCP en el que escuchará el servidor.

4. Accede a la aplicación: Abre tu navegador y visita http://localhost:9000 o http://127.0.0.1:9000. Deberías ver tu aplicación ASP.NET en funcionamiento.

5. Detén el servidor: Tras finalizar tu sesión de desarrollo/prueba, vuelve a la terminal donde ejecutaste XSP y presiona Ctrl + C o la tecla Enter para detener el servidor.

Ventajas:

• Configuración muy sencilla y arranque rápido.
• Ideal para desarrollo local y depuración.

Desventajas:

• Menor rendimiento comparado con servidores web de producción como Nginx.
• Funcionalidad básica, no simula un entorno productivo real.
• Requiere mantener la ventana de terminal abierta.

Método 2: Uso de Nginx + FastCGI

Con este método, Nginx gestionado por ServBay actúa como servidor web frontend, manejando peticiones de los clientes y sirviendo archivos estáticos, y, a través del protocolo FastCGI, transmite solicitudes dinámicas (como .aspx, .ashx, etc.) al proceso Mono en segundo plano (fastcgi-mono-server4). Esto se asemeja mucho más a un despliegue en producción, ofreciendo mejor rendimiento y permitiéndote aprovechar capacidades avanzadas de Nginx (SSL, caché, compresión, etc.).

Sugerencia

• Si tu proyecto es de ASP.NET 1.1, usa el comando fastcgi-mono-server.
• Para ASP.NET 2.0/3.x, usa el comando fastcgi-mono-server2.
• Para ASP.NET 4.x, usa el comando fastcgi-mono-server4.

Pasos:

1. Verifica que Mono y Nginx estén instalados y en ejecución:

   • Instala Mono 6 y Nginx desde la sección “Paquetes” de ServBay.
   • En la sección “Servicios” de ServBay, asegúrate de que el servicio Nginx esté en marcha.

2. Prepara tu proyecto ASP.NET: Confirma que el proyecto está en la ruta recomendada, por ejemplo /Applications/ServBay/www/MyWebApp.

3. Inicia FastCGI Mono Server:

   • Abre una nueva ventana de terminal.
   • Ejecuta el proceso fastcgi-mono-server4. Este proceso se encargará de recibir peticiones FastCGI desde Nginx, procesando páginas ASP.NET y la lógica de negocio.

     # Ejemplo: iniciar FastCGI para el proyecto MyWebApp
     fastcgi-mono-server4 --applications=/:/Applications/ServBay/www/MyWebApp \
                          --socket=tcp:127.0.0.1:9001 \
                          --loglevels=Standard \
                          --printlog

     • fastcgi-mono-server4: Inicia el servidor FastCGI preparado para .NET Framework 4.x.
     • --applications=/:/Applications/ServBay/www/MyWebApp: Mapea la ruta URL raíz (/) al directorio físico del proyecto. Cuando Nginx reenvía solicitudes como /some/page.aspx, Mono buscará y ejecutará /Applications/ServBay/www/MyWebApp/some/page.aspx. Sustituye siempre /Applications/ServBay/www/MyWebApp por la ruta real de tu proyecto.
     • --socket=tcp:127.0.0.1:9001: Define la dirección y puerto TCP para FastCGI. 127.0.0.1 solo acepta conexiones locales, y 9001 es el puerto. Asegúrate de que este puerto (como el 9001) no esté en uso por otros servicios y que coincida con el definido en la configuración de Nginx (fastcgi_pass).
     • --loglevels=Standard --printlog: (Opcional) Muestra logs de nivel estándar directamente en la terminal, útil para depuración y seguimiento de la actividad Mono.
   • Nota: La ventana en la que ejecutas fastcgi-mono-server4 debe permanecer abierta; de lo contrario, el servicio se detendrá. Para ejecución prolongada, considera usar nohup, screen o tmux para mantenerlo activo en segundo plano.

4. Configura el sitio en Nginx:

   • Desde ServBay, accede a la sección “Sitios”.

   • Haz clic en “Agregar sitio” o edita uno existente.

   • Configura tu dominio: Por ejemplo, un dominio del tipo mywebapp.servbay.demo. ServBay añadirá automáticamente este dominio al archivo Hosts de macOS, apuntando a 127.0.0.1.

   • Configura la raíz del sitio: ¡Muy importante! Debe ser la ruta real de tu proyecto ASP.NET, por ejemplo /Applications/ServBay/www/MyWebApp. Esto se reflejará en la directiva root de Nginx, que gestiona los archivos estáticos.

   • Activa y edita la configuración personalizada: Marca la casilla “Configuración personalizada” en la esquina superior derecha de la configuración del sitio. ServBay generará una configuración base de Nginx en función de tu dominio y carpeta raíz. A partir de allí, deberás añadir o modificar el bloque adecuado para redirigir las solicitudes dinámicas a FastCGI/Mono.

     Aquí se muestra un ejemplo típico sobre el que debes revisar, añadir o modificar algunos bloques:

     server {
         listen 80; # Escuchar en el puerto HTTP
         listen 443 ssl http2; # Escuchar en el puerto HTTPS, habilitar SSL y HTTP/2
     
         # Configuración SSL gestionada automáticamente por 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;
     
         # Rutas de certificados, gestionados automáticamente por ServBay
         ssl_certificate /Applications/ServBay/ssl/private/tls-certs/mywebapp.servbay.demo/mywebapp.servbay.demo.crt; # Asegúrate de que concuerdan con tu dominio
         ssl_certificate_key /Applications/ServBay/ssl/private/tls-certs/mywebapp.servbay.demo/mywebapp.servbay.demo.key; # Asegúrate de que concuerdan con tu dominio
     
         server_name mywebapp.servbay.demo; # Debe coincidir con el dominio configurado
         root /Applications/ServBay/www/MyWebApp; # **Asegúrate** de que coincida con la raíz real
     
         # Añade los documentos por defecto de ASP.NET; Nginx probará index.html/htm y luego estos otros
         index index.html index.htm default.aspx Default.aspx;
     
         # Lógica principal de manejo de solicitudes
         location / {
             # Buscar el archivo o carpeta correspondiente ($uri o $uri/)
             # Si no existe archivo estático, dirigir la petición a @mono
             try_files $uri $uri/ @mono;
         }
     
         # (Opcional, pero recomendado) Nginx sirve eficientemente archivos estáticos comunes
         # Puedes usar expires para cachear contenido en el navegador
         location ~* \.(ico|css|js|gif|jpe?g|png|svg|woff|woff2|ttf|eot)$ {
             expires max;
             log_not_found off;
             access_log off;
         }
     
         # Definición del bloque nombrado @mono para peticiones dinámicas
         location @mono {
             # Redirige la petición vía FastCGI a Mono Server
             # **El puerto debe coincidir** con el especificado en --socket al arrancar fastcgi-mono-server4
             fastcgi_pass 127.0.0.1:9001;
     
             # Incluye los parámetros estándar de FastCGI
             include fastcgi_params;
             # Parámetro clave: define el archivo de script físico que ejecutará Mono
             fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
             # PATH_INFO normalmente no es necesario, así que lo dejamos vacío
             fastcgi_param PATH_INFO "";
     
             # (Opcional) Otros parámetros, como HOST, se pueden agregar según necesidad
             # fastcgi_param HOST $host;
         }
     
         # ServBay puede incluir otras configuraciones por defecto, como rutas de logs
         # access_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.access.log;
         # error_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.error.log;
     }

   • Guarda la configuración y recarga/reinicia Nginx: Al guardar el archivo de configuración desde ServBay, el sistema intentará recargar Nginx automáticamente. Si detecta errores de sintaxis, ServBay te notificará. Si es necesario, puedes reiniciar manualmente Nginx desde la sección “Servicios”.

5. Accede a tu aplicación: Abre el navegador y accede al dominio configurado (por ejemplo, https://mywebapp.servbay.demo). Dado que Nginx está configurado con SSL en el puerto 443, se recomienda usar HTTPS. Nginx servirá los archivos estáticos directamente y redirigirá las solicitudes dinámicas a fastcgi-mono-server4, ejecutando tu código ASP.NET desde Mono.

Ventajas:

• Mejor rendimiento, mayor estabilidad y más parecido a un entorno real de producción.
• Permite aprovechar las funciones avanzadas de Nginx (servicio de archivos estáticos, SSL, balanceo de carga, etc.).
• Mejor integración con las herramientas de administración de sitios, dominios y Hosts de ServBay.

Desventajas:

• Requiere una configuración un poco más elaborada respecto a XSP.
• Debes gestionar manualmente el proceso fastcgi-mono-server4 (a menos que uses un gestor de procesos).

¿Cómo elegir el método adecuado?

• Para un desarrollo rápido, depuración o pruebas funcionales simples, XSP es la forma más sencilla y veloz de poner tu proyecto en marcha. Sólo necesitas un comando.
• Si necesitas mayor rendimiento, pruebas cercanas a producción o aprovechar características avanzadas (HTTPS, dominios personalizados, optimización de archivos estáticos) e integración con la gestión de sitios de ServBay, lo ideal es optar por el modo Nginx + FastCGI.

Consideraciones y solución de problemas

• Permisos de archivos: Verifica que el usuario que ejecuta Nginx (gestionado habitualmente por ServBay) y el usuario que ejecuta fastcgi-mono-server4 tengan permisos de lectura suficientes sobre los archivos de tu proyecto (en /Applications/ServBay/www/YourProjectName). Si hace falta, ajusta los permisos usando chmod o cambia la propiedad con chown.
• Coherencia de rutas: Confirma que la ruta configurada en root de Nginx y el parámetro --applications de fastcgi-mono-server4 sean correctos y apunten al directorio raíz donde está el archivo web.config.
• Conflicto de puertos: Asegúrate de que los puertos utilizados por XSP o fastcgi-mono-server4 (como 9000 o 9001) estén libres y no coincidan con otros servicios de ServBay ni con aplicaciones externas.
• Revisión de logs:
  • Consulta los logs que aparecen en la terminal al iniciar fastcgi-mono-server4. El parámetro --printlog te ayuda a monitorear la actividad en tiempo real.
  • Revisa los logs de error de Nginx. ServBay te permite ver los logs asociados a cada sitio desde la interfaz, normalmente en /Applications/ServBay/logs/nginx/your-domain.error.log. Estos logs son claves para identificar problemas de configuración o de comunicación entre Nginx y Mono.
• Compatibilidad de versiones de Mono: Mono 6.14.0 integrado en ServBay es compatible en líneas generales con .NET Framework 1.1 a 4.7.2. Si usas características de versiones superiores o enfrentas problemas de compatibilidad, considera instalar el SDK/runtime oficial de .NET de Microsoft directamente con ServBay, o bien, adapta tu proyecto a una versión soportada por Mono.
• Gestión de procesos FastCGI: Si eliges el método Nginx + FastCGI, recuerda que el proceso fastcgi-mono-server4 debe permanecer en ejecución. Durante el desarrollo puedes dejar la terminal abierta, pero en entornos formales es recomendable gestionarlo como un servicio de fondo o mediante un gestor de procesos.

---

Gracias al entorno integrado Mono 6 de ServBay y una estructura de proyectos recomendada, desarrollar y ejecutar aplicaciones clásicas de ASP.NET Framework 4.x en macOS es ahora más normalizado y sencillo. ¡Esperamos que esta documentación te ayude a iniciar tu trabajo de desarrollo sin complicaciones!