Configuring and running Mono ASP.NET 3.5 (AJAX.NET) on Linux computers

Before we will start, we should install Linux. To do this, you can download any of LiveCDs with live installation. Officially, Mono supported only on one free Linux - openSuse. However, you can make it work on any RedHat (and its alternatives), OpenSolaris. It works, but unsupported on Debians, Ubuntu and Maemo. We’ll stick to openSuse by now.

Let’s install it - OS

I’m assuming, that you’re installing Linux as the only OS on the machine, so insert liveCD (it can be either Gnome or KDE) and wait for Linux to run. It will run live image directly on your machine without installation.

When it’ll up, you’ll see liveInstall icon in your desktop. Click it and skip first two screens (it is only language and local settings). Next screen (disk partitions) is necessary for us.

On this screen, first delete all automatic partitions. The only one main partition will remain (/DEV/SDA or /DEV/HDA). Next you should choose non-LVM option and then start creating partitions.

Create first partition with mount point /boot and size of 100Mb. File system for this partition should be ext3.

Create second partition with file system SWAP (you will not have mount point) and set the size twice bigger, then RAM amount.

Create last partition with mount point / and all remaining size on disk.

All other steps are optional, you can just click Next button.

After about 10 minutes you’ll have up and running openSuse system. (If you forgot to remove CD, choose HardDisk as boot option)

Web Server installation

Now we have to install web server. You can choose either Apache, FastCGI  or use build-in server within Mono – XSP. We’ll choose Apache

Goto “Computer” it’s in the same place as Start button :) and choose YaST. You’ll be asked for admin password, you entered while installing the system.

Now in the Filter field, type “Install”. Choose “Software Management” from the available programs at right. Now, when Package Selection dialog opens, type “apache”, you’ll find apache2. Select it and click Install. Apache will move to the right column. Optionally, you can install also prefork and utils packages.

Now hit “Apply” to install it. Within two minutes, you’ll be asked to log off and log on. Do it.

By now apache is not running, you should run it and set it starts automatically. To do this, enter terminal window (you can either do it from “Computer” menu or right clicking desktop).

You need elevation to administrate startup programs. So type: “su –“ and enter your password. Terminal color turns red. Type “chkconfig apache2 on”. Now you should check whether it done, so type: “chkconfig apache2 –list”. You should see “On” near number 3 and 5.

To run apache manually, just type “/etc/init.d/apache2 start” to stop “/etc/init.d/apache2 stop”, to restart “/etc/init.d/apache2 restart” and to check the status “/etc/init.d/apache2 status”

We done, apache is up and running. Now we should install mono

Mono installation

Start with the same YaST but this time, type “mono” – you’'ll get a lot of programs. To simplified installation, choose (or type) mono-complete. This will all available Mono modules.

After Mono will be installed, you should install also apache2-mod_mono to make possible running ASP.NET mono pages in Apache. do this.

Log off – log on and move to configuration

Mono configuration

Now it’s time to configure what ASP.NET pages you want to run. We want ASP.NET 2.0, so we should run mono apache mode for this version. To do this, go to the terminal, elevate yourself (su –) and type following: “vi /etc/apache2/httpd.conf” This will open VI editor with apache configuration file in it.

Now it’s time to learn VI a little. To start editing, you should type “A” – it will write “INSERT” in the lower left corner. To return to the command mode, hit escape key. To save (from command mode) “:w” to exit and save “:wq” to exit without save “:q!”. To find “/” and string the pattern you are looking for.

Now go the the very end of the file  and write under Include “/etc/apache2/vhosts.d/*.conf” following:
(to short string “[D]” is your virtual directory (slash blank is root), “[P]” is physical path to your site without trailing slash)

MonoServerPath default /usr/bin/mod-mono_server2
Alias [D] “[P]”
AddMonoApplications default “[D]:[P]”
<Location [D]>
SetHandler mono
</Location>

So, if your site is MySite and it is in /srv/www/htdocs/MySite, this section will looks as following:

MonoServerPath default /usr/bin/mod-mono_server2
Alias /MySite “/srv/www/htdocs/MySite”
AddMonoApplications default “/MySite:/srv/www/htdocs/MySite”
<Location /MySite>
SetHandler mono
</Location>

If you want to turn it to the root site, this will looks following:

MonoServerPath default /usr/bin/mod-mono_server2
AddMonoApplications default “/:/srv/www/htdocs/MySite”
<Location />
SetHandler mono
</Location>

Now, we’ll add mono administrative site to be able to restart mono only without touching apache itself. To do this, after last </Location> you should add following:

<Location /mono>
SetHandler mono-ctrl
Order deny,allow
Deny from all
Allow from 127.0.0.1
</Location>

I think it’s very clear what it did :)

If you have more, then one site and want to configure mono differently for each one of those, you should add VirtualHost section. To do this, include your configuration in to

<VirtualHost [IP and port you want, for example 1.1.1.1:80 or *:80 for all IPs on port 80]>
ServerName [Name you want]
…
</VirtualHost>

We done. Restart apache and enter the url you set (for example http://localhost/MySite/)

Working? Good. You finished.

Not working (familiar yellow error 500 screen)? Keep reading…

Debugging Mono website

Do you remember, that you have no development environment in this machine? You can install it, or download Mono liveCD with openSuse. But before doing it, please note, that GTK# (it’s devenv) is not very user friendly. It even worse, then Eclipse. So let’s try to understand first whether we can fix small compatibility problems without entering code.

The most convenient method to debug web site on Mono is by using XSP and XSP2 mini web servers. Just enter the directory of the site and run it. By default you’ll be able to access the site by using “http://localhost:8080” (it also be written for you). Enter and notice whether you have any errors in console. No? Keep doing

The most common problem is “error 500” with nonsense stack. If it contains ScriptManager error Type not found, the problem is in Web.config file. Try to regenerate it to be compatible to Mono (for example, Mono has different version of System.Web.Extensions assembly. In ASP.NET 3.5 it has version 3.5, Mono has only 1.0.61025.0 (the old AJAX.NET). To recreate your web.config all you have to do is to execute “mconfig af AJAX Web.config” It will create default web.config file, supports System.Web.Extensions (AJAX features).

Not helped? Keep doing. Let’s look another time into the stack – if it contains errors in “EnablePageMethods” or “ShouldGenerateScript” or “EncryptString” – the problem is serialization. Mono has very limited support for JSON, XML and SOAP serialization. Try to look into your code and notice if you have classes, marked with [Serializable] or you are transferring your own classes by using PageMethods. If so, replace it with regular strings (my grandma serialization).

Person p = new Person();
string sstr = string.Format(“{0}|{1}|{2}|{3}”, p.FirstName, p.LastName, p.Age, p.Wage);
return sstr;
…
var sstr = persons[i].split("|");
var p.FirstName =  sstr[0];
var p.LastName =  sstr[1];
var p.Age =  sstr[2];
var p.Wage =  sstr[3];

Not helped? Try to rename “Bin” directory into “bin” “mv Bin bin –r”. Actually this was fixed in latest versions of Mono, but who knows?…

No? Check whether you have partial classes, which is not supported by Mono. If so, recompile it like this

mcs /t:library /out:bin/test.dll –r:System.Web –r:System.Data –r:System.Web.Services –r:System.Web.UI.Controls test.aspx.cs

If you have Generics in your code, you should use gmcs, rather then mcs.

Not helped? It looks, that you have to either install Mono on your Windows machine and debug your code with it. Or, alternatively install GTK# and do in on Linux.

But wait, before doing such big step, install and check the binary compatibility of your code. To do this, you need “Moma” – a simple tool, that tell you if everything is ok for Mono in your assemblies.

Good luck and see you in my forthcoming TechEd session, where I’m presenting openSuse, running UDP multicast server with ASP.NET 3.5 extended methods (It uses recompiled ISAPI filters for apache, rather then regular limited AJAX support in Mono)

Have a nice day and be good people.