Catharsis Tutorial 01 - Installing Catharsis

Introduction

This document outlines a simple step by step process containing everything you need to know to install the Catharsis framework on your computer and create a Catharsis solution.

Additional Information

The author of Catharsis, Radim Köhler, has added many CodeProject documents on the Catharsis ASP.NET MVS Framework which can be found here.

The source code for Catharsis can be found here.

Other tutorials in this series can be found here.

A printable Word version of this document is available here.

Prerequisites

The following prerequisites will be needed:

• .NET Framework 3.5 SP1
• Visual Studio 2008
• Team System 2008
• Support for C# and VB.NET (For LinqToXML)
• Microsoft SQL Server 2005
• With SQL Server Management Studio
• GuidanceAutomationExtensions
• Download from Microsoft
• Catharsis ProjectBase
• Download from http://www.codeplex.com/Catharsis/

ASP.NET MVC

This is not a prerequisite, but it will work if you already have it installed as long as it is the latest version. If in doubt and you do not need ASP.NET MVC for any other projects, use ControlPanel to remove it from your computer before installing Catharsis. The Catharsis framework contains the ASP.NET MVC assemblies so you do not actually need to have it installed.

GuidanceAutomationToolkit

If you intend to expand the functionality of the Guidance, you will need this.

Operating System used in tutorial

The operating system used in this tutorial was Windows Server 2003 SP1.

Once the required software is installed, you can begin to create a new application.

The following steps will guide you through the process:

1. Creating a new Catharsis project
2. Creating the database
3. Running the database wizard
4. Creating the database tables
5. Setting the StartUp project
6. Checking the config.files
7. Running Catharsis

Creating a New Catharsis Project

Click on the File -> New -> Project

Select ProjectBase.Guidance.

Give your application a name and create a file location for it. It is a good practice to use a naming convention like MyCompany.MyApplication.

In older versions of Catharsis, it was not possible to name spaces in the file path for the installation location. For example C:\Documents and Settings would not work, but this has now been fixed.

Before proceeding to the next step in the set up, it is a good idea to create the database which the application will use.

Creating the Database

Open Microsoft SQL Server Management Studio. When installing Microsoft SQL Server 2005, you will have been asked if you want to install the server as a named instance. Using a named instance is good practice because it allows multiple servers to run on the same machine. In the example below, the name of the computer is AP325373 and the name of the named instance is MSSQL2005. Using Windows authentication is the best option for our purposes. Select the named instance if you have one (otherwise select the default) and click Connect:

Now right click on Databases and select Add Database:

Give the database a name, we will use MyApplicationDB in this case:

Now click on the Options tab:

Select Compatibility Level: Simple.

Click Okay and your new database will appear in the list on the right:

Running the Database Wizard

Now go back to VS2008. When you click okay in the New Project dialog, a new one will appear asking for information about the database. Change the name of the database to match the database you created in the last step:

Now click Finish and wait for the framework to create a skeleton architecture for your project.

When this is completed, a popup is displayed which outlines what needs to be done next:

A window with some information on the creation of the skeleton code might remain on the screen. This is not important now, so just close that window.

Creating the Database Tables

So according to the instructions in the popup, we will now run some SQL scripts to create tables which are required by the framework.

In VS2008, find the DB_SQLServer folder and open the first script:

Select all of the text and copy it to the clipboard.

Go back to Microsoft SQL Server Management Studio. Right-click on your database and select New Query.

Now paste the text from the SQL script into the window. Change the name of the database which the script will be run on from the default ‘Product’ to the name of your database, MyApplicationDB in this case. Click the Execute button and the script will run to create the database tables that you need.

(Note: It is possible that an error message stating ‘Could not find the stored procedure MyApplicationDB’ can appear when attempting to run the script. If you close Microsoft SQL Server Management Studio and open it again, this will help).

Now run the second script in the same way. This script will populate the tables with some data. Remember again to change the database name.

There is a third table which contains data for optional create table statements for tracking. If you want to use the framework's built in ability to track changes to entities, you should run this script also. Tracking will be described in a later document.

Take care of the warning message in the SQL script:

/*
To use tracking also uncomment 
1) Nhibernate.config ProjectBase.Data mapping
2) Data.hbm.TrackedBase.hbm.xml
*/

We will deal with this in a later tutorial.

Setting the StartUp Project

Now we need to deal with the remaining items listed in the ToDo list pop-up which Catharsis displayed.

Right click on the web project and select ‘Set as Startup Project’.

Also do this for the Default.aspx file inside that project.

Checking the Config Files

Now we need to make some changes so the framework knows how to access our database. Open the web.config file:

Find the code for the connection string:

  <connectionStrings>
    <add name="ProjectDB" connectionString="Data Source=.\SQL2005;
		Database=MyApplicationDB;Trusted_Connection=yes;"/>
  </connectionStrings> 

Check that the database name is correct. This should be taken care of automatically if you created your database before running the Guidance as outlined in the steps above.

The same needs to be done in the App.config file in the test project.

Running Catharsis

Now we are ready to test the new solution MyCompany.MyApplication.

Click on the menu Window -> Close All Documents.

Now try debugging the solution. Click on the output window by selecting the Output tab in the bottom pane in VS2008 (This is good practice because it allows you to see what is happening during the build) and then select ‘Rebuild Solution’ as shown. We use rebuild instead of build as this ensures that every part of the application will be built.

It is possible that some references will appear to be broken before the rebuild is carried out but the rebuild will take care of this.

Now click on Debug or press F5 and run the application.

Summary

If no problems have occurred, it should be possible to do this in ten minutes. The result is that you have a complete multi-tier architecture on which to base your application without the considerable difficulties of planning and writing the architecture from scratch.

If any users have problems with their installation, please let me know and we will work on finding a solution, it is obviously important to supply information on your system and the status of all the prerequisites listed above.

The Next Step

Now that you have installed Catharsis, it's time to see what you can do with it. In the next tutorial, we will look at the Catharsis example solution where you will see how the Catharsis framework handles entities.

Other tutorials in this series can be found here.

History

• 28^th June, 2009: Initial post