Developing ASP.NET Framework 4.x on macOS with ServBay

With ServBay’s robust built-in Mono environment, developing and testing ASP.NET Framework 1.1/2.0/3.x/4.x (up to 4.7.x) on macOS is simple and practical.

Starting from ServBay v1.12.0, we have integrated Mono 6.14.0, including the XSP development server and the fastcgi-mono-server tool. You now have two primary methods for running ASP.NET Framework 4.x applications:

1. Quick Development and Testing with XSP: XSP is a lightweight ASP.NET web server designed for Mono, perfect for development and fast prototyping.
2. Deployment with Nginx + FastCGI: This approach is more stable, offers better performance, and more closely replicates production environments. Nginx managed by ServBay forwards requests to Mono backend processes.

This guide walks you through configuring and running your ASP.NET Framework 4.x project within the ServBay environment.

About .NET Framework vs .NET

Please note: This guide covers ASP.NET Framework 4.x development based on Mono, which uses an older .NET technology stack.

ServBay also fully supports the latest .NET (including .NET Core, .NET 5/6/7/8+) for development and deployment. For new .NET projects, or if you wish to migrate to modern .NET versions, we recommend using the official Microsoft .NET SDK/runtime provided with ServBay, rather than the Mono-based approach outlined here.

Prerequisites

1. Install ServBay: Make sure you have ServBay v1.12.0 or above installed on your macOS.
2. Install Mono:
   • Open the ServBay application.
   • In the left sidebar, select “Packages”.
   • In the package list, find the “.NET” category and expand it.
   • Locate “Mono 6” (version 6.14.0 or above), click the “Install” button, and wait for the installation to complete.

Prepare Your ASP.NET Project

1. Project Files: Ensure you have an ASP.NET Framework 4.x Web Application or Web Site project that includes a web.config file.
2. Recommended Project Location: We strongly recommend placing your website project under ServBay’s unified www directory, located at /Applications/ServBay/www/. Create a separate subdirectory for each project.
   • Example: If your project is called MyWebApp, the recommended project root path is /Applications/ServBay/www/MyWebApp.
   • In the steps below, we’ll use /Applications/ServBay/www/MyWebApp as the example path. Be sure to replace this with your project's actual path.

Method 1: Using XSP (Built-in Development Server)

XSP is a lightweight web server that comes with Mono, making it ideal for local development and rapid testing of ASP.NET Framework applications. The Mono 6 package in ServBay already includes XSP4 (suitable for ASP.NET 4.x).

Tip

• To run ASP.NET 1.1 projects, use the xsp command.
• To run ASP.NET 2.0/3.x projects, use the xsp2 command.
• To run ASP.NET 4.x projects, use the xsp4 command.

Steps:

1. Open Terminal: Launch the Terminal application on your macOS.

2. Navigate to the Project Directory: Use the cd command to enter your ASP.NET project’s root directory (the one containing the web.config file).

   # Example: move into the directory for MyWebApp
   cd /Applications/ServBay/www/MyWebApp

3. Start the XSP Server: In the project root directory, run the following command to start the XSP4 server. Choose an unused port (e.g., 8080 or 9000) to avoid conflicts with other ServBay services.

   # Start the project on port 9000
   xsp4 --port 9000

   • xsp4: Launches the XSP server for .NET Framework 4.x.
   • --port 9000: Specifies the TCP port for the server to listen on.

4. Access Your Application: Open your web browser and go to http://localhost:9000 or http://127.0.0.1:9000. You should see your ASP.NET application running.

5. Stop the Server: Once you are done, return to the terminal window where XSP is running and press Ctrl + C or Enter to stop the server.

Advantages:

• Simple setup and quick startup.
• Ideal for local development and debugging.

Disadvantages:

• Not as performant as production-grade servers like Nginx.
• More basic functionality; does not fully mimic a production environment.
• Terminal window must remain open.

Method 2: Using Nginx + FastCGI

With this approach, ServBay-managed Nginx acts as your frontend web server, handling client requests and serving static files, while dynamic requests (like .aspx, .ashx, etc.) are forwarded using FastCGI to the Mono backend process (fastcgi-mono-server4). This setup more closely resembles a production environment, offers better performance, and lets you take advantage of Nginx’s advanced features (like SSL, caching, compression, etc.).

Tip

• To run ASP.NET 1.1 projects, use the fastcgi-mono-server command.
• To run ASP.NET 2.0/3.x projects, use the fastcgi-mono-server2 command.
• To run ASP.NET 4.x projects, use the fastcgi-mono-server4 command.

Steps:

1. Ensure Mono and Nginx Are Installed and Running:

   • Install Mono 6 and Nginx via the “Packages” tab in ServBay.
   • In the “Services” section of ServBay, ensure Nginx is started.

2. Prepare Your ASP.NET Project: Make sure your project is in the recommended path (e.g., /Applications/ServBay/www/MyWebApp).

3. Start the FastCGI Mono Server:

   • Open a new terminal window.
   • Run the fastcgi-mono-server4 process. This process listens for FastCGI requests from Nginx, serves ASP.NET pages, and handles business logic.

     # Example: Start FastCGI for MyWebApp
     fastcgi-mono-server4 --applications=/:/Applications/ServBay/www/MyWebApp \
                          --socket=tcp:127.0.0.1:9001 \
                          --loglevels=Standard \
                          --printlog

     • fastcgi-mono-server4: Starts the FastCGI server for .NET Framework 4.x.
     • --applications=/:/Applications/ServBay/www/MyWebApp: Maps the URL path to the physical project path. /: means the site root (/), /Applications/ServBay/www/MyWebApp is your actual project path. When Nginx forwards a request like /some/page.aspx, Mono will look for /Applications/ServBay/www/MyWebApp/some/page.aspx. Be sure to replace /Applications/ServBay/www/MyWebApp with your real project path.
     • --socket=tcp:127.0.0.1:9001: Specifies the TCP address and port for FastCGI. 127.0.0.1 means local connections only; 9001 is the port. Make sure this port is not used by other ServBay services or system applications, and that it matches the fastcgi_pass port in your Nginx config below.
     • --loglevels=Standard --printlog: (Optional) Print standard level logs in the terminal for easier debugging and to view Mono’s output.
   • Note: The terminal running fastcgi-mono-server4 must stay open, or the service will stop. For longer-running services, consider using nohup, screen, or tmux to keep it running in the background.

4. Configure the Nginx Site:

   • In ServBay, go to the “Sites” section.

   • Click “Add Site” or edit an existing site.

   • Set the Domain Name: For example, use a branded domain like mywebapp.servbay.demo. ServBay will automatically add this domain to your macOS Hosts file, pointing to 127.0.0.1.

   • Set the Document Root: Important! Set this to your actual ASP.NET project path, e.g., /Applications/ServBay/www/MyWebApp. This sets the root directive in Nginx for static file delivery.

   • Enable and Edit Custom Config: Check the “Custom Config” option in the site settings. ServBay will generate a base Nginx config for you. You’ll need to modify or extend the config to forward dynamic ASP.NET requests to FastCGI Mono Server.

     Here’s a sample section to check, add, or modify based on the config ServBay generates:

     server {
         listen 80; # Listen on HTTP
         listen 443 ssl http2; # Listen on HTTPS with SSL and HTTP/2
     
         # SSL certificate settings (managed by 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;
     
         # Cert file paths, automatically handled by ServBay
         ssl_certificate /Applications/ServBay/ssl/private/tls-certs/mywebapp.servbay.demo/mywebapp.servbay.demo.crt; # Match certificate to actual domain used
         ssl_certificate_key /Applications/ServBay/ssl/private/tls-certs/mywebapp.servbay.demo/mywebapp.servbay.demo.key; # Match certificate to actual domain used
     
         server_name mywebapp.servbay.demo; # Must match the domain you set in ServBay
         root /Applications/ServBay/www/MyWebApp; # **Ensure** this matches your Document Root
     
         # Add ASP.NET default documents — fallback if Nginx can't find index.html/htm
         index index.html index.htm default.aspx Default.aspx;
     
         # Main request logic
         location / {
             # Try to find the file or directory in order, else send to @mono
             try_files $uri $uri/ @mono;
         }
     
         # (Optional but recommended) Efficiently serve common static files directly
         # Use expires to leverage browser caching
         location ~* \.(ico|css|js|gif|jpe?g|png|svg|woff|woff2|ttf|eot)$ {
             expires max;
             log_not_found off;
             access_log off;
         }
     
         # Define @mono location for dynamic requests
         location @mono {
             # Send requests through FastCGI to Mono Server
             # **Port must** match the --socket port for fastcgi-mono-server4
             fastcgi_pass 127.0.0.1:9001;
     
             # Include standard FastCGI parameters
             include fastcgi_params;
             # Key parameter: set SCRIPT_FILENAME so Mono can find ASP.NET files
             fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
             # PATH_INFO not generally needed — set to empty
             fastcgi_param PATH_INFO "";
     
             # (Optional) Set other FastCGI params as needed, e.g., HOST
             # fastcgi_param HOST $host;
         }
     
         # ServBay may also add other default settings, e.g., logs
         # access_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.access.log;
         # error_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.error.log;
     }

   • Save and Reload/Restart Nginx: Save the Nginx config in ServBay. ServBay will attempt to reload Nginx automatically. If there are any syntax errors, you’ll get a prompt. If needed, manually restart Nginx via the “Services” page.

5. Access Your Application: Open your browser and visit the domain configured in Nginx (for example, https://mywebapp.servbay.demo). Since Nginx is listening on port 443 with SSL, using HTTPS is recommended. Nginx will serve static files directly and forward dynamic requests to fastcgi-mono-server4, with Mono running your ASP.NET code.

Advantages:

• Better performance and stability; suitable for production-like testing.
• Leverage powerful Nginx features (static file serving, SSL, load balancing, etc.).
• High integration with ServBay site/domain/Hosts management.

Disadvantages:

• More complex setup than XSP.
• Must manually manage the fastcgi-mono-server4 process (unless using background tools).

How to Choose the Right Approach

• For quick development, debugging, and simple feature testing, XSP is the easiest and fastest way to get started. Just one command to run.
• For higher performance, production-like testing or internal deployments, or if you want to use advanced Nginx features (like HTTPS, custom domains, static file optimization) and ServBay’s site management, Nginx + FastCGI is recommended.

Notes and Troubleshooting

• File Permissions: Make sure the user running Nginx (usually managed by ServBay) and the user running fastcgi-mono-server4 on macOS have sufficient read permissions for your project files (in /Applications/ServBay/www/YourProjectName). You may need to use chmod or chown to adjust file and directory permissions.
• Path Consistency: Carefully check that your Nginx config (root directive) and fastcgi-mono-server4 command (--applications parameter) both point to the exact root directory of your project, containing the web.config file.
• Port Conflicts: Be sure that the ports used by XSP or fastcgi-mono-server4 (e.g., 9000 or 9001 in these examples) are not occupied by other ServBay services or applications on your system.
• Log Checking:
  • Check the terminal output when starting fastcgi-mono-server4. The --printlog parameter helps you view Mono's runtime logs directly.
  • Inspect Nginx error logs. ServBay shows the relevant log paths in the site settings, usually in /Applications/ServBay/logs/nginx/your-domain.error.log. Error logs are critical for troubleshooting Nginx configs or FastCGI communication issues.
• Mono Version Compatibility: ServBay’s built-in Mono 6.14.0 is largely compatible with .NET Framework 1.1 through 4.7.2. If your app uses features from newer .NET Frameworks or if you encounter compatibility issues, consider using the official .NET SDK/runtime from Microsoft via ServBay for modern .NET applications, or downgrade your project to a framework supported by Mono.
• FastCGI Process Management: If you use Nginx + FastCGI, remember the fastcgi-mono-server4 process must stay running. During development, keeping the terminal open is sufficient, but for more robust setups, consider configuring it as a background service or using a process manager.

---

With ServBay’s integrated Mono 6 environment and the recommended project structure, developing and running traditional ASP.NET Framework 4.x applications on macOS has never been easier or more standardized. We hope this guide helps you get started quickly and smoothly!