How to install Catharsis Guidance

The Catharsis framework Guidance prerequisites and installation overview. 
HOW TO install the guidance, create new solution, run the application.

The Catharsis Guidance installation

The following steps will guide you through the process:

1. Prerequisites
2. Creating the database
3. Creating a new solution - running the Catharsis framework Guidance wizard
4. Creating the database tables
5. Setting the StartUp project
6. Running Catharsis

Prerequisites  

top

The following prerequisites will be needed:

• .NET Framework 3.5 SP1
• Visual Studio 2008 (e.g. Team System 2008)
• Support for both C# and VB.NET (For LinqToXML)
• MS SQL Server 2005 (With SQL Server Management Studio)
• GuidanceAutomationExtensions.exe (Download from Microsoft)
• The Catharsis Guidance (Download from http://catarsa.com/Articles/Download/Catharsis)

ASP.NET MVC

top

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 (source-code) you will also need this GAT.

Creating the database

top

Open Microsoft SQL Server Management Studio. When installing MS 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 Recovery model: Simple (allows the log file shrinking, which is a good choice for development)

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

Creating a new solution - running the Catharsis framework Guidance wizard

top

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.

When you click okay in the New Project dialog and 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:

Click Next. On the next wizard page you can decide if the Services entities (User, Localization, Documentation), which are built in the framework, will be persisted in the Database or in XML files (AppData) folder. The usual scenario is to use the default option.

But there are cases, when you have to create the application and do not have any choice to change the DB Schema (e.g. tables are not visible and the only interfaces are stored procedures). In such scenarios, it is very handy to still have the Catharsis Services Entities - persisted in .XML files.

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

When this 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

top

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 DBSQLServer folder and open the first script:

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

Go back to MS 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.

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

There is an insert script which contains the user information. Change the values to your Login, first and last names:

This will grant you Admin rights for the first application run. In the future you can manage users and rights directly from the application.

If you've selected to use the XML as the persistence for the Services Entities, change the

Web project > App_Data > User.xml file the similar way:

Setting the StartUp project

top

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:

Collapse

  <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

top

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.

The Catharsis Guidance is working - new solution was created

top

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.

Enjoy Catharsis