FastCGI & Mono: ASP.NET on Your Server

Table of Contents


The FastCGI Mono Server was developed as part of the 2007 Google Summer of Code with the goal of increasing the availablity of ASP.NET and simplifying configuration. Requiring as little as zero command line options and supporting a large number of servers, the FastCGI Mono Server makes it simple to include ASP.NET on your server.

This documentation contains configuration instructions for serveral web servers on Linux, with plans to expand support to Windows and Macintosh in the future. Please take the time to read all the information below before configuring your server.

How Does It Work?

FastCGI is an interprocess communcation mechanism available in many web servers. A web server will receive and respond to a request in the following manner corresponding to the diagram on the right:

  1. The browser tries accessing a page. It finds the host and sends it HTTP GET request.

  2. The web server receives the request, recognizes that it is supposted to send it to a given socket, in this case "/tmp/fastcgi-mono-server-0", connects to it, and sends the request in the CGI format using FastCGI records.

  3. fastcgi-mono-server receives the request and creates a Mono.WebServer.FastCgi.WorkerRequest (a subclass of System.Web.Hosting.SimpleWorkerRequest) and processes the request.

  4. SimpleWorkerRequest checks for an existing compiled version of the requested page. If it does not exist, the page is converted into C# (or the specified language) and compiled. It then invokes Render on the compiled representation of the page.

  5. The page is rendered and sent back to the SimpleWorkerRequest

  6. Overrided method calls in the FastCGI WorkerRequest send the response back to the web server using FastCGI records.

  7. The web server sends the response back to the browser.

  8. The browser displays the page.

Platform Documentation

Important Information

Paths vs. Extensions

Most programming languages used for web sites contain all their information within a single file format, for example, PHP uses the .php extension and Python uses the .py extension. ASP.NET, on the other hand, uses a combination of file types, combined with programming paradigms like session objects, sandboxed environments, and private directories. This makes configuring ASP.NET unique when compared to other FastCGI handlers you may have configured.

You could easily configure FastCGI to simply pass the 11 standard extensions to the FastCGI Mono Server and have all remaining files processed by standard methods, but you will suffer the following negative consequences:

To overcome these problems, the recommended method for processing files is to send all requests directly to the FastCGI Mono Server. This way, features and security are preserved. The negative consequence is that all files are then processed by the Mono Server and you suffer a decrease in performance. There are methods for overcoming this on a server-by-server basis. For example, directories could be excluded from ASP.NET and serve strictly static files, but this is a topic to be discussed in server configuration pages.

What are ASP.NET Applications?

If you've programmed with other web language even dabbled in ASP.NET on another hosting solution, you may be unfamiliar with what ASP.NET applications actually are, how they are used, and why this matters. The most important thing to know, is that every ASP.NET page belongs to an application and that they need to be configured properly for your application to load. That said, relax, because the FastCGI Mono Server does most of the work for you and odds are you won't have to worry about how to configure them. They're be more information on this in "How Applications are Handled."

Applications are, in short, directories on a website which behave just like a traditional application or program, with pages just being different UI's in the same program. This is managed by having all ASP.NET pages handled by a continuously running server which keeps the application alive, and keeping these separate pages in their own Application Domains as to stop one application from messing with another. This yields some very powerful features.

How Applications are Handled (And How to Configure Them)

By default, the FastCGI Mono Server detects applications for you with information it detects from the web server. As discussed in the last section, applications are unique directories. On a server, though, there are four different parts to a directory:

The FastCGI Mono Server detects applications by taking the their virtual and physical paths and recursing up the paths until A) the path names differ or B) the directory contains a bin directory. In the case of A, as soon as the names differ you've reached the point where a virtual directory has been applied, and in the case of B, a bin directory is a strong indicator of an application, and it is safest to assume that it is. In other word, for the paths /path/to/file.aspx and C:\Inetpub\wwwroot\path\to\file.aspx, / would be assumed as the directory unless /path/to/bin or /path/bin exists, in which case /path/to or /path would be the application. This should work for virtual paths, virtual hosts, and user directories without any problem.

However, you may want to register your own applications or turn off automatic mapping for whatever reason. [TODO: INSERT DESCRIPTION OF APPLICATION COMMAND LINE OPTIONS.]

Running the Mono Server and Web Server on Different Machines

Many web servers will let you connect to the FastCGI Mono Server on another machine over TCP. If you are using automatic application mapping, the paths it uses come from the web server and where it thinks the files should be. If you are your web server has a document root of C:\Inetpub\wwwroot and the machine running the Mono Server stores the files on D:\Inetpub\wwwroot, C:\Mirror\Inetpub\wwwroot, or anything other that C:\Inetpub\wwwroot, it will be unable to find or serve the files. Some servers will let you specify the document root to use, but it is recommended that you have an identical directory structure on both machines.