Beginner’s Guide to ASP.NET on Mono

Overview

This tutorial describes some tips and tricks used to develop and debug ASP.NET web applications hosted on Linux servers using the Mono C# runtime framework.

This tutorial is intended for novice web programmers, and covers some of the basic steps required to develop an ASP.NET web application using Visual Studio on the PC, and then deploy that applicaiton to the Linux server.

In this tutorial you will learn

  • Some know differences between Visual Studio solution files and files compatible with Mono on Linux. This will allow you to fix a number of small problems before first deploying to the Linux server.
  • How to use the MonoDevelop IDE to open and debug your Visual Studio solution on a Linux Machine.

Tools and Work Flow

We use the following work flow to develop simple ASP.NET applications to run on our Linux server.

  1. Code a feature using Visual Studio, deploy and debug using IIS on PC as localhost.

2.  Make sure to fix these two possible problems:

  1. Make sure you pay attention to case on all file names and link paths.  Unlike windows, Linux is case sensitive, so if you see errors about missing files such as “Site.master” can not be found, make sure the file is not named “Site.Master”
  2. In older aspx files, the attribute naming the .cs file appears like this: CodeFile=”Default.aspx.cs”. You must  change it to this: CodeBehind=”Default.aspx.cs”

3.  When feature is working in Visual Studio, publish the web application project to a file location on the PC.

4.  Copy the files to the Linux machine to the web root folder setup for this solution.

5.  Hit the URL with your web browser. You will usually notice an exception on the first try.  Hit it again and your website should be working.

6.  If your website is not working, you will have to figure out why.  Of course, it was working on Windows, so it your problem is almost definately specific to Linux mono.

Troubleshooting these problems is the hard part.  We used the following workflow to debug the ASP.NET project on a Linux machine running mono.

1.  Setup a machine with Monodevelop IDE.

Ideally this would be the same kind of machine you will be running the ASP.NET application on.  For our project, we used MonoDevelop on openSUSE Linux.  This Linux distribution is maintained by Novell, where many of the principle engineers of the Mono project used to work. It has also had Mono version 3.x as part of the repository for the longest.

2.  Copy your solution (preferably via source control) to the Linux machine, and open the solution with MonoDevelop.

3.  For users of visual studio, using MonoDevelop should be pretty straight forward, as the programs are very similar.  However, you will have to get around the following problem first:

This is caused by the issue describedhere.

To fix this, open up the .csproj file, find the <ProjectTools> element,  and change the ToolsVersion atrribute to 4.0.

4.  After saving the file, you should now be able to open your solution in MonoDevelop.

5.  Find the Build menu and select Rebuild All.  Then find the Run menu and select Start Debugging

6.  The XSP server should automatically start in ad hoc mode, and you will see your web application launched in the Firefox browser.

You can now debug your application.  The debugger, including keyboard shortcuts, works very similar to Visual Studio.