UltiDev Cassini Web Server Developer's Guide

The contents of this document has changed to reflect the functionality of the
General Availability release of UltiDev Cassini Web Server.
If you are using older version, we recommend upgrading. If you need information on the Release
Candidate version of the product, please refer to RC1 Developer's Guide.

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 two simple
sample projects - one for Visual Studio .NET 2003, and another for Visual Studio 2005. Both 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.

Visual Studio .NET 2003 Sample Visual Studio 2005 Sample

Installation Instructions Installation Instructions
If operating system on your development box is 32 If operating system on your
bit : Download and save sample solution archive for development box is 32 bit :
32-bit Windows. Download and save the sample
- or - file.
If operating system on your development box is 64 - or -
 bit : Download and save sample solution archive for If operating system on your
32-bit Windows. development box is 64 bit :
Download and save the sample
file.

Compiled solutions will work on both 32 and 64-bit systems regardless of the type of the development operating system. 32
or 64 sample solutions are different only in folder paths they pull their components from ("C:\Program Files (x86)" on 64 bit
build systems versus "C:\Program Files" on 32 bit build systems.)
Unzip the file to root of C:\ drive - this is important Unzip the file to any folder.
because project contains hard-coded debug paths. Open the
Create IIS virtual directory named Cassini2RedistDemo.sln
SampleNonIISWebApp and pointing to solution file in Visual Studio
C:\SampleNonIISWebApp\SampleNonIISWebApp. 2005.
(You have to do this because VS 2003 cannot load a
web project unless it’s hooked up to IIS.) Pleas note that Express Editions of the
Visual Studio may not allow including
In VS 2003 open the multiple projects in a solution. You may
C:\SampleNonIISWebApp\SampleNonIISWebApp.sln need non-Express version of Visual Studio
solution. to use the sample.

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, 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 looks exactly the same in Visual Studio .NET 2003 and Visual Studio 2005,
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 Setup project for ASP.NET 2.0 Application & 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:

Download UltiDev Cassini Web Server Explorer MSI

Download UltiDev Cassini Web Server for ASP.NET 2.0 MSI
Download UltiDev Cassini Web Server for ASP.NET 1.1 MSI

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
Command Line
and
Cassini Web Server
Cassini for
ASP.NET 2.0 "%ProgramFiles%\UltiDev\Cassini Web Server for ASP.NET 2.0\UltiDevCassinWebServer2.exe"
on 32-bit /register <appFolder> <appGuid> [<defaultDocument>] [<Port> | 0] [/DontKeepRunning]
Windows
Cassini for
ASP.NET 2.0 "%ProgramFiles(x86)%\UltiDev\Cassini Web Server for ASP.NET
2.0\UltiDevCassinWebServer2.exe" /register <appFolder> <appGuid> [<defaultDocument>]
on 64-bit [<Port> | 0] [/DontKeepRunning]
Windows
Cassini for
ASP.NET 1.1 "%ProgramFiles%\UltiDev\Cassini Web Server for ASP.NET 1.1\UltiDevCassinWebServer.exe"
on 32-bit /register <appFolder> <appGuid> [<defaultDocument>] [<Port> | 0] [/DontKeepRunning]
Windows
Cassini for
ASP.NET 1.1 "%ProgramFiles(x86)%\UltiDev\Cassini Web Server for ASP.NET
1.1\UltiDevCassinWebServer.exe" /register <appFolder> <appGuid> [<defaultDocument>]
on 64-bit
 on 64-bit [<Port> | 0] [/DontKeepRunning]
Windows

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

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.

© UltiDev LLC, All rights reserved. Terms and Conditions