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 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 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.
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.
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.
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.
- 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.
- 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.
- 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.
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.
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.
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:
- Add a regular, non-web Setup project to the
solution (web setup is for IIS only).
- Add Cassini redistributable components to the
Setup.exe bootstrapper file (details below).
- 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.
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:
- 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.
- Ensure Windows Installer 3.1 is present on the
target system - it is used to install UltiDev
Cassini runtime components.
- Install UltiDev Cassini Web Server Explorer.
- Install UltiDev Cassini Web Server (for ASP.NET
1.1 or 2.0 - depending on the type of your
application).
- Install your application.
- 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:
- "%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.
- "%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.
|
 |
