UltiDev Cassini Web Server Developer's Guide
Good old Cassini is getting obsolete. Replace it with the new and advanced
UltiDev Web Server Pro,
which is also free and redistributable.

Cassini Overview
Cassini for ASP.NET and Visual Studio Developers
Getting to Know UltiDev Cassini: Downloading and Installing
Getting to Know UltiDev Cassini: Let it Run Your Existing ASP.NET Applications
Getting to Know UltiDev Cassini: Studying Sample Projects
Debugging your ASP.NET Application with UltiDev Cassini
Using Cassini Explorer Web Service to Get Application Port Information
Packaging and Distributing ASP.NET Applications with UltiDev Cassini Web Server using Microsoft Visual Studio
Packaging ASP.NET Applications with UltiDev Cassini Web Server using InstallShield, WISE and NSIS

 
UltiDev Cassini Overview

UltiDev Cassini Web Server does support complete set of ASP.NET features. But even though it is not as feature-reach as IIS, UltiDev Cassini has one huge advantage over IIS: you can make Cassini a part of your application's setup package. With UltiDev Cassini you can reach huge, underserved group of users: those who lack IT staff required to run industry-strength web servers. Think of how successful Google Desktop is - a perfect personal web application. To create an application like it you will need a compact redistributable web server.

Enter UltiDev Cassini.

Our Cassini is a lightweight web server capable of hosting ASP.NET applications & web services, as well as static HTML web sites. UltiDev Cassini is highly improved compared to original Cassini web server sample from www.asp.net. Cassini's primary advantage is that it can be easily bundled with your ASP.NET application's setup package. UltiDev Cassini is absolutely free and requires no fees of any kind at all, ever!

Please check the Release Notes to find out what's new in this release of UltiDev Cassini.

Cassini for ASP.NET and Visual Studio Developers

Cassini Web Server, as it’s distributed by UltiDev LLC, is based on code published at www.asp.net. However, to make Cassini truly useful and developer-friendly we added numerous powerful features, like:
  • We made Cassini a windows service capable of running multiple ASP.NET applications simultaneously;
  • Most important for Visual Studio developers, UltiDev Cassini can be easily included into your setup package. In Visual Studio 2005 UltiDev Cassini components are added as a Setup Prerequisites. In Visual Studio .NET 2003 Cassini is added as a custom Setup.exe bootstrapper for your MSI package.
  • Applications distributed along with UltiDev Cassini can register themselves with the Cassini server after the installation - without you having to write a single line of code.
  • We added Cassini Explorer - an ASP.NET application management user interface. Cassini Explorer is running under Cassini, of course;
  • We added a very simple Cassini Configuration .NET API  for advanced application registration and configuration scenarios.
UltiDev Cassini Web Server comes in two flavors that are functionally equivalent, but target different versions of .NET Framework. Cassini 1.1 supports ASP.NET applications compiled for ASP.NET 1.0 and 1.1 and requires .NET Framework 1.1 to run. Cassini 2.0 supports applications compiled for ASP.NET 1.0, 1.1 and 2.0, and requires both .NET Framework 1.0 and 2.0 to be installed. The decision which one to use will be driven by what version of .NET Framework you expect your customers to have, as well as what version of ASP.NET your application was made for.

The remainder of this document is the set of detailed walkthroughs explaining how to make your ASP.NET application working with Cassini, how to debug with it, and how to create setup packages that bundle your ASP.NET application with UltiDev Cassini Web Server.


Getting to Know UltiDev Cassini: Downloading and Installing

You can download and install Cassini from UltiDev.com download page on most of the Windows operating systems: from Windows 2000 to all flavors of Windows XP, Windows 2003 Server, and even Windows Vista. During installation Cassini won’t ask you many questions and will just install itself, register its components, and create an “UltiDev | Cassini Web Server” group in the Programs menu. There you will find shortcuts to Cassini application configuration UI, and to some other useful functions and documents.


Getting to Know UltiDev Cassini: Let it Run Your Existing ASP.NET Applications

After you installed Cassini on your development box, the first thing you may want to do is to register your existing applications with Cassini. To do that, fire up Cassini Explorer and click "register application" button. It’s OK if your applications are also registered with IIS – Cassini and IIS coexist quite peacefully. When registering an application with Cassini the only required pieces of data are the application GUID and the folder where application is located. Once you have registered the application, see if it works by clicking the application name link.


Application GUID is a means of avoiding duplications when registering applications programmatically. Registering an application with existing GUID will replace previous application parameters, like name, port and location, and replace it with new ones.

When registering an application it’s highly recommended that you let Cassini assign a free port to your application instead of specifying the port explicitly. Regardless what port your application is on, you can always access the application by pointing your browser to http://localhost:7756/GoToApplication.aspx?AppID=<your application GUID>. That is a never-changing, port-independent URL to your application. If your ASP.NET application contains web services, your web service client can call Cassini Explorer web service at http://localhost:7756/CassiniConfigurationService.asmx to figure out what is the exact URL of the application hosting your web service. It's not quite a UDDI, but it gets your dynamic binding problem solved.

Getting to Know UltiDev Cassini: Study Sample Projects

Since for programmers sample is worth hundreds of pages of documentations, we created a sample project (in a few flavors - each for a particular version of the Visual Studio). They contain an ASP.NET project and a Setup Project illustrating topics explained below, namely, debugging with UltiDev Cassini, and creating setup package that includes your ASP.NET application and UltiDev Cassini Web Server redistributable components. Please note that appropriate version of UltiDev Cassini Web Server needs to be installed for samples to build and work.

Please note that although samples below are slightly different for x86 and x64 development systems, installation packages they create will work on both 32 and 64 bit systems. Also, Express Editions of the Visual Studio 20XX may not allow including multiple projects in a solution. You may need non-Express version of Visual Studio to use the samples.

Guidance for Redistributable Demo Project for Visual Studio 2008

  • If operating system on your development  box is  32 bit : Download and save archive with the sample file.
    - or -
    If operating system on your development  box is  64 bit : Download and save archive with the sample file.
  • Unzip the file to an empty folder.
  • Open "CassiniRedistDemoForVS2008\CassiniRedistDemoForVS2008\CassiniRedistDemoForVS2008.sln" solution file in Visual Studio 2008.

Guidance for Redistributable Demo Project for Visual Studio 2005

  • If operating system on your development  box is  32 bit : Download and save archive with the sample file.
    - or -
    If operating system on your development  box is  64 bit : Download and save archive with the sample file.
  • Unzip the file into an empty folder.
  • Open "Cassini2RedistDemo\Cassini2RedistDemo.sln" solution file in Visual Studio 2005.

Guidance for Redistributable Demo Project for Visual Studio.NET 2003

  • If operating system on your development  box is  32 bit : Download and save sample solution archive for 32-bit Windows.
    - or -
    If operating system on your development  box is  64 bit : Download and save sample solution archive for 32-bit Windows.
  • Unzip the file to root of C:\ drive - this is important because project contains hard-coded debug paths.
  • Create IIS virtual directory named SampleNonIISWebApp and pointing to C:\SampleNonIISWebApp\SampleNonIISWebApp. (You have to do this because VS 2003 cannot load a web project unless itís hooked up to IIS.)
  • In VS 2003 open the C:\SampleNonIISWebApp\SampleNonIISWebApp.sln solution.

Debugging your ASP.NET Application with UltiDev Cassini Web Server

You can debug your application under Cassini server using one of two options. First, less convenient, is to attach the debugger to UltiDevCassiniWebServer.exe (or UltiDevCassiniWebServer2.exe for ASP.NET 2.0) process. Second, the more convenient way, is to run UltiDev Cassini Web Server as a standalone console application.

Debugging in Visual Studio .NET 2003

To debug your web application with UltiDev Cassini, bring up your project properties and switch from Project to Program debugging, then specify “C:\Program Files\UltiDev\Cassini Web Server for ASP.NET 1.1\UltiDevCassiniWebServer.exe” as a Start Application, and set command line arguments to “/run” “c:\inetput\wwwroot\yourApplicationFolder”, or whatever the path to your application folder. For complete list of command line parameters run "C:\Program Files\UltiDev\Cassini Web Server for ASP.NET 1.1\UltiDevCassinWebServer.exe".

Debugging in Visual Studio 2005

To debug your web application in Visual Studio 2005, please bring up your project's Properties and switch debugging to external program and specify "C:\Program Files\UltiDev\Cassini Web Server for ASP.NET 2.0\UltiDevCassinWebServer2.exe" as program to run. Cassini server in console mode requires /run command line parameter, and at least a path to the physical folder where your ASP.NET application is. For complete list of command line parameters run "C:\Program Files\UltiDev\Cassini Web Server for ASP.NET 2.0\UltiDevCassinWebServer2.exe.

That’s about it. When you hit Build | Debug, Cassini will start hosting your application in console mode, and will launch the browser pointing to your application. You will be able to stop at breakpoints and inspect variable values just as if it was debugging under IIS. Cassini server takes some more optional parameters along with /run command, so you could tell what port, application ID, default document and browser to use so you could debug the application with FireFox or any other browser. Run Cassini server or /? command line switch to get information on console mode usage of the UltiDev Cassin Web Server.
 

Using Cassini Explorer Web Service to Get Application Port Information

As a rule, Cassini applications should let the system find and assign a free TCP port to the application. Client, of course, will not know exact location of your application, because on one box it could be http://localhost:1234/, and on another it could be http://localhost:5678/. Cassini Explorer always runs on the same fixed port 7756, and it has GoToApplication.aspx redirector page that will redirect browser to your application by application ID. Below we provide a sample URL that uses Cassini Explorer's GoToApplication.aspx to redirect browser to a given application. In order for web service clients to be able to call applications running under Cassini at random port numbers we added a web service to Cassini Explorer that returns the exact, port-sensitive URL of an application by application ID. Your web service client can call that web service to get your web service's actual URL even with randomly assigned port number.

Packaging and Distributing ASP.NET Applications with UltiDev Cassini Web Server using Microsoft Visual Studio

The most outstanding feature of UltiDev Cassini Web Server is that it is easily redistributable. This chapter explains how to include redistributable components into your Visual Studio setup project, and how to register your application with UltiDev Cassini web server at the end of the application's setup process.

UltiDev Cassini Web Server redistributable components are packaged as pre-requisites into Setup.exe bootstrapper. Creating custom bootstrapper is a natural feature of Visual Studio 2005/2008, but in Visual Studio .NET 2003 it isn't, so UltiDev has created a pre-packaged Setup.exe bootstrapper for setup projects generated by Visual Studio .NET 2003. For those who used UltiDev Cassini Beta and Release Candidate versions, this way of packaging is a departure from original, merge module based distribution model. The change was caused by poor upgradeability of components included as merge modules. Being a pre-requisite, not a merge module, has several implications:
- Cassini components got their own Product and Upgrade codes, which made Cassini reliably upgradeable;
- Uninstalling applications bundled with UltiDev Cassini will not automatically uninstall Cassini. Users, however, will be able to uninstall Cassini from Control Panel's Add/Remove Applications applet. This behavior is not different from installing other pre-requisites like Windows Installer, or .NET Framework.
- It's not enough to ship just an MSI file containing your application - UltiDev Cassini is not packaged in the MSI file along with the web app - it's in Setup.exe instead. Ship both Setup.exe and MSI package together.

Conceptually, creating a setup project that includes an ASP.NET application and UltiDev Cassini consists of following steps:

  1. Add a regular, non-web Setup project to the solution (web setup is for IIS only).
  2. Add Cassini redistributable components to the Setup.exe bootstrapper file (details below).
  3. Add files and custom build actions to the setup project that will register your application with Cassini after installation, and unregister during uninstallation.

Since these steps don't look exactly the same in Visual Studio .NET 2003 and Visual Studio 2005/2008, we have created two separate sets of instructions for each version of IDE:
- Creating Visual Studio .NET 2003 Setup project for ASP.NET 1.1 Application & UltiDev Cassini Web Server.
- Creating Visual Studio 2005 or 2008 Setup project for ASP.NET 2.0 or 3.x Applications & UltiDev Cassini Web Server.

Packaging ASP.NET Applications with UltiDev Cassini Web Server using InstallShield, WISE, NSIS and Other non Visual Studio Installation Authoring Tools

Since significant number of developers create installers for their applications using tools other than Visual Studio, this section offers generic guidelines for authoring installation packages that include the web application and UltiDev Cassini Web Server.

General Installation Flow

We recommend installing UltiDev Cassini runtime components before your application itself has been installed.

The high-level flow of your installation would look like this:

  1. Ensure appropriate .NET Framework is installed on the target system:
    • .NET Framework 1.1 is required for ASP.NET 1.1 case (.NET Framework 1.1  Service Pack 1  is required for Windows Vista and recommended for all other supported Windows OSes).
    • .NET Framework 2.0 is required for ASP.NET 2.0 case.
  2. Ensure Windows Installer 3.1 is present on the target system - it is used to install UltiDev Cassini runtime components.
  3. Install UltiDev Cassini Web Server Explorer.
  4. Install UltiDev Cassini Web Server (for ASP.NET 1.1 or 2.0 - depending on the type of your application).
  5. Install your application.
  6. Register your application with UltiDev Cassini Web Server.


Obtain UltiDev Cassini Web Server Runtime Component Installers

UltiDev Cassini runtime components include two Windows Installer (MSI) -based setup packages that can be included into your installation package and installed using either Windows Installer (MSI) API or MSIEXEC.EXE utility. You can download pre-packaged UltiDev Cassini runtime components here:

You can freely redistribute these Cassini Runtime components along with your ASP.NET applications.


Install UltiDev Cassini Web Server Runtime Components

To install UltiDev Cassini for ASP.NET  2.0  runtime components using MSIEXEC.EXE please use following command lines:
         msiexec.exe /passive /i CassiniExplorerSetup.msi
         msiexec.exe /passive /i CassiniServer2Setup.msi

To install UltiDev Cassini for ASP.NET  1.1  runtime components using MSIEXEC.EXE please use following command lines:
         msiexec.exe /passive /i CassiniExplorerSetup.msi
         msiexec.exe /passive /i CassiniServer1Setup.msi

Please note that if your application installation is also Windows Installer (MSI) -based, you will not be able to launch Cassini installer or any other MSI-based installation while your application installation is underway. Windows Installer API prohibits recursive MSI installations.
Therefore, if your application installation is MSI-based, you will need to launch UltiDev Cassini runtime components installation before your application installation begins. It's a good idea to put the code responsible for launching UltiDev Cassini runtime MSIs into Setup.exe.


Register Your Application With UltiDev Cassini Web Server

After both UltiDev Cassini and you application were installed, you need to register your application with UltiDev Cassini Web Server. There are two ways to register an application with UltiDev Cassini Web Server:
- Using .NET UltiDev Cassini Configuration API. (This option may be more practical when creating the package using Visual Studio.)
- Using UltiDev Cassini Web Server in command line mode. This option is universal and can be used by any installer authoring system that can launch an external program.

To register your application using UltiDev Cassini Web Server in command line mode, check these application command line registration examples:
Type of
Destination System
and
Cassini Web Server
Command Line
Cassini for ASP.NET  2.0 
on  32-bit  Windows 
"%ProgramFiles%\UltiDev\Cassini Web Server for ASP.NET 2.0\UltiDevCassinWebServer2.exe" /register <appFolder> <appGuid> [<defaultDocument>] [<Port> | 0] [/DontKeepRunning]
Cassini for ASP.NET  2.0 
on  64-bit  Windows 
"%ProgramFiles(x86)%\UltiDev\Cassini Web Server for ASP.NET 2.0\UltiDevCassinWebServer2.exe" /register <appFolder> <appGuid> [<defaultDocument>] [<Port> | 0] [/DontKeepRunning]
Cassini for ASP.NET  1.1 
on  32-bit  Windows 
"%ProgramFiles%\UltiDev\Cassini Web Server for ASP.NET 1.1\UltiDevCassinWebServer.exe" /register <appFolder> <appGuid> [<defaultDocument>] [<Port> | 0] [/DontKeepRunning]
Cassini for ASP.NET  1.1 
on  64-bit  Windows 
"%ProgramFiles(x86)%\UltiDev\Cassini Web Server for ASP.NET 1.1\UltiDevCassinWebServer.exe" /register <appFolder> <appGuid> [<defaultDocument>] [<Port> | 0] [/DontKeepRunning]

This table explains command line parameters of UltiDev Cassini Web Server:
Parameter Explanation Example
/register Tells Cassini to register an application N/A
<appFolder> Path to physical folder containing application's files. "C:\Program Files\My ASP.NET App"
<appGuid> GUID identifying the application. Should be the same when new versions of the application are released. 4886776A-BE3E-48aa-B350-424AED36CE5B
<defaultDocument> Optional. Name of the default application file. Can be omitted if default document is Default.aspx or index.htm. WebForm1.aspx
<Port> Optional. TCP/IP port number for the application. Omit or set to 0 to make Cassini assign a free port automatically. It is highly recommended to let Cassini assign the port to avoid port number collisions. 26854
/DontKeepRunning Optional. Tells UltiDev Cassini to unload the application if it has not served any requests in a while. /DontKeepRunning saves memory at the expense of longer first-page-served time. The flag is not set if parameter was omitted, ensuring fast first-page-served response by keeping application in memory. N/A

Examples:

  1. "%ProgramFiles%\UltiDev\Cassini Web Server for ASP.NET 2.0\UltiDevCassinWebServer2.exe" /register
    "%ProgramFiles%\My Company\Best Ever Web Application" 7ABEE8EC-5FFA-45f4-B881-6441D5B7C1E9 Default.aspx 0 /DontKeepRunning

    Cassini will register the application, assign port dynamically, sets Default.aspx as a default document, and ensures that application is not automatically loaded in memory when Cassini Server starts.
     
  2. "%ProgramFiles%\UltiDev\Cassini Web Server for ASP.NET 2.0\UltiDevCassinWebServer2.exe" /register
    "%ProgramFiles%\My Company\Best Ever Web Application" 7ABEE8EC-5FFA-45f4-B881-6441D5B7C1E9

    Cassini will register the application, assign port dynamically, use Default.aspx or index.htm as a default document, and keep application in memory for quick response even if application was idle.


Access Your Application Running Under UltiDev Cassini Web Server

To access your application use the link pointing to Cassini Explorer application redirection page and include your application ID in the query string:
        http://machinename:7756/GoToApplication.aspx?AppID=
7ABEE8EC-5FFA-45f4-B881-6441D5B7C1E9

This link will redirect browser to your application. Please note that the same application ID is used for redirection as for application registration and unregistration. This link is port-independent and will work on any computer where your application is installed even if Cassini has picked different TCP ports for your application on different systems.


Unregister Your Application With UltiDev Cassini Web Server

When your application is getting uninstalled, you need to unregister your application with UltiDev Cassini. To unregister your application using command line utility, use the same utility as with registration, but with different command line parameters. Command line parameter required for unregistration are /unregister and <appGuid>. For example:

"%ProgramFiles%\UltiDev\Cassini Web Server for ASP.NET 2.0\UltiDevCassinWebServer2.exe" /unregister
7ABEE8EC-5FFA-45f4-B881-6441D5B7C1E9

This command line will unregister your application with UltiDev Cassini Web Server.

IMPORTANT: Do NOT uninstall UltiDev Cassini runtime components when uninstalling your application. UltiDev Cassini may be used by other applications installed before or after yours and therefore may be required to remain installed.