How to Develop ASP.NET Framework 4.x on macOS

ServBay simplifies the development and testing of ASP.NET Framework 1.1/2.0/3.x/4.x (up to 4.7.x) on macOS through its powerful built-in Mono environment.

Starting with ServBay v1.12.0, we integrated Mono 6.14.0 and included the XSP development server. We offer two primary ways to run ASP.NET Framework 4.x applications:

• Quick development and testing using XSP
• Deploying applications using Nginx + FastCGI for a more stable, production-like environment.

This document will guide you on how to configure and run your ASP.NET Framework 4.x projects in the ServBay environment.

Prerequisites

1. Install ServBay: Ensure you have ServBay v1.12.0 or higher installed on macOS.
2. Install Mono:
   • Open the ServBay application.
   • In the left navigation bar, select "Packages."
   • In the package list, locate the ".NET" category and click to expand it.
   • Find "Mono 6" (version should be 6.14.0 or higher), click the "Install" button on the right, and wait for the installation to complete.

Prepare Your ASP.NET Project

1. Project File: Ensure you have a Web Application or Web Site project using ASP.NET Framework 4.x.
2. Recommended Storage Location: We strongly recommend placing your website project in the unified www directory managed by ServBay, specifically at /Applications/ServBay/www/. Create a separate subdirectory for each project.
   • Example: If your project is named MyWebApp, the recommended path would be /Applications/ServBay/www/MyWebApp.
   • In the subsequent steps, we will use /Applications/ServBay/www/MyWebApp as the example path. Please replace this with the actual path of your project.

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

XSP is a lightweight ASP.NET web server designed specifically for Mono, making it ideal for development and quick testing. The Mono 6 package installed with ServBay includes XSP4 (for ASP.NET 4.x).

Tip

• If you want to run an ASP.NET 1.1 project, use the xsp command.
• If you want to run an ASP.NET 2.0 project, use the xsp2 command.

Steps:

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

2. Navigate to the Project Directory: Use the cd command to navigate to the root directory of your ASP.NET project (the directory containing the web.config file).

   # Example: Enter the project directory named 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. You can specify a port number (e.g., 8080 or 9000) to avoid conflicts with other services in ServBay.

   # Start the project in the current directory on port 9000
   xsp4 --port 9000

   • xsp4: Calls the XSP server for .NET 4.x.
   • --port 9000: Specifies the port number for the server to listen on.

4. Access the 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: When you finish development or testing, return to the terminal window and press Ctrl + C or Enter to stop the XSP server.

Advantages:

• Simple configuration, quick to start.
• Ideal for local development and debugging.

Disadvantages:

• Performance is not as good as production-grade servers like Nginx.
• Relatively basic functionality; does not fully simulate a production environment.

Method 2: Using Nginx + FastCGI

This method uses Nginx, managed by ServBay, as the front-end web server, forwarding dynamic requests to the Mono backend process (fastcgi-mono-server4) via the FastCGI protocol. This approach is closer to a production environment and offers better performance.

Tip

• If you want to run an ASP.NET 1.1 project, use the fastcgi-mono-server command.
• If you want to run an ASP.NET 2.0 project, use the fastcgi-mono-server2 command.

Steps:

1. Ensure Mono and Nginx Are Installed and Running:

   • Install Mono 6 and Nginx through ServBay's "Packages."
   • In ServBay, under the "Services" section, ensure that the Nginx service is running.

2. Prepare the ASP.NET Project: Ensure your project is located in the recommended path, such as /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 and executes your ASP.NET code.

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

     • --applications=/:/Applications/ServBay/www/MyWebApp: Maps the website's root path (/) to your project's physical path. Be sure to replace /Applications/ServBay/www/MyWebApp with the actual path of your project.
     • --socket=tcp:127.0.0.1:9001: Specifies the TCP address and port for the FastCGI server to listen on. Ensure this port (e.g., 9001) is not occupied and matches the fastcgi_pass directive in the Nginx configuration below.
     • --loglevels=Standard --printlog: (Optional) Print standard-level logs to the terminal for debugging purposes.
   • Note: This terminal window needs to stay open to run the FastCGI service. For long-running processes, you may want to use nohup or tools like screen/tmux to run it in the background.

4. Configure the Nginx Site:

   • In ServBay, go to the "Sites" section.

   • Click "Add Site" or select an existing site to edit.

   • Set Domain Name: For example, mywebapp.test. ServBay will automatically add this to your Hosts file.

   • Set Website Root Directory: Very important! Set this as your ASP.NET project's actual path, like /Applications/ServBay/www/MyWebApp. This will correctly set the root directive in the Nginx configuration.

   • Key: Check/Edit Nginx Configuration File: Click on the "Custom Configuration" selection box in the upper right corner of the site settings. ServBay will generate a base configuration based on your set website root. You need to ensure that the location / and @mono (or similarly named location block) configurations correctly proxy requests to the FastCGI Mono Server.

     A sample section from a configuration that needs checking or adding is shown below:

     server {
         listen 443;
         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.test/mywebapp.test.crt; # Ensure the certificate matches the actual path
         ssl_certificate_key /Applications/ServBay/ssl/private/tls-certs/mywebapp.test/mywebapp.test.key; # Ensure the certificate matches the actual path
     
         server_name mywebapp.test; # Must match the domain set in ServBay
         root /Applications/ServBay/www/MyWebApp; # **Ensure** this matches the website root you set
         index index.html index.htm default.aspx Default.aspx; # Add ASP.NET default documents
     
         location / {
             try_files $uri $uri/ @mono; # Try static files; if not, pass to @mono
         }
     
         # (Optional but recommended) Nginx directly handles common static files
         # location ~* \.(ico|css|js|gif|jpe?g|png|svg|woff|woff2|ttf|eot)$ {
         #     expires max;
         #     log_not_found off;
         #     access_log off;
         # }
     
         location @mono {
             # Pass requests to FastCGI Mono Server
             # **Port must** match the port specified when launching fastcgi-mono-server4 with --socket
             fastcgi_pass 127.0.0.1:9001;
     
             # Necessary FastCGI parameters
             include fastcgi_params;
             # SCRIPT_FILENAME will be set correctly based on the root directive and $fastcgi_script_name
             fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
             fastcgi_param PATH_INFO "";
         }
     
         # ServBay may also include other default configurations, such as logging, access control, etc.
         # access_log /Applications/ServBay/logs/nginx/mywebapp.test.access.log;
         # error_log /Applications/ServBay/logs/nginx/mywebapp.test.error.log;
     }

   • Save Configuration and Restart Nginx: Save the Nginx configuration file. ServBay will automatically reload the Nginx configuration upon saving. If there are errors in the configuration, ServBay will prompt them. If necessary, you can manually restart Nginx on the ServBay "Services" page.

5. Access the Application: Open your browser and go to the domain you configured in Nginx (e.g., https://mywebapp.test, note the use of HTTPS). Nginx will forward the requests to fastcgi-mono-server4, which will execute your ASP.NET code through Mono.

Advantages:

• Better performance, more stability.
• Closer to production-like deployment.
• Can utilize Nginx for handling static files, load balancing, SSL, and other advanced functions.
• More integrated with ServBay's site management, domain, and Hosts management features.

Disadvantages:

• Configuration is relatively more complex than XSP.
• Requires manual management of the fastcgi-mono-server4 process.

How to Choose

• For quick development, debugging, and simple testing, using XSP is the easiest way.
• For higher performance, testing closer to a production environment, or if you wish to leverage Nginx's advanced features and ServBay's site management, choose the Nginx + FastCGI approach.

Notes and Troubleshooting

• File Permissions: Ensure that the Nginx process (usually managed by ServBay) and the macOS user running fastcgi-mono-server4 have read access to your project files (located at /Applications/ServBay/www/YourProjectName). You may need to adjust directory permissions (chmod or chown).
• Path: Carefully check that the project paths in the Nginx configuration (root directive) and the fastcgi-mono-server4 command (--applications parameter) are completely correct and point to the directory containing web.config.
• Port Conflicts: Ensure that the ports used by XSP or fastcgi-mono-server4 (in the examples, 9000 or 9001) are not occupied by other applications.
• Logs:
  • Check the output logs in the terminal when starting fastcgi-mono-server4.
  • Check the Nginx error logs. You can find the error log path for the corresponding site in the ServBay site settings (usually at /Applications/ServBay/logs/nginx/mywebapp.test.error.log).
• Mono Version Compatibility: Mono 6.14.0 is compatible with .NET Framework 1.1 up to roughly .NET Framework 4.7.2. If you are using features from a higher version of the .NET Framework, consider using the official .NET Core or .NET installed via ServBay.

---

With the built-in Mono 6 environment and recommended project structure in ServBay, developing and running ASP.NET Framework 4.x applications on macOS has become more standardized and convenient. We hope this document helps you smoothly get started with your development work!