Introduction

The Genesis Smart Client Framework was developed by Blue Marble, a South African software development house. The framework was developed as the means of distributing an application to a large wide-spread audience over the internet.

By providing a Dynamic Application Workspace the framework allowed the development team to focus on developing task specific modules, while the framework dealt with keeping client software up to date with the latest version of the modules, and provided users access to modules they were allowed to work with.

This article is a step-by-step guide for writing your first Genesis Smart Client Framework application. I will guide you through the process of downloading the latest source code from Code Plex.

I will be making use of the latest source code release for Visual Studio 2010 and Microsoft.NET 4.0, however the same steps will apply for the Visual Studio 2008 and Microsoft.NET 3.5SP1 version.

Download the latest source

To download the lastest version of the source code, go to Code Plex and download Genesis Source Code 1.60.1024.1 for Visual Studio 2010 (current latest version)

UPDATE: I have just published the source code to the CodePlex Online Source Control. This provides easier access to the project, and more information on progress. It is available here.

I will be assuming, for the purpose of this article, that you are extracting the source code to C:\Genesis\

Step 1 - Build the Source Code and Deploy the Database

The first step after having extracted the source code is to build the project and to deploy the database.

Once you have extracted the source code to C:\Genesis\, open Explorer and browse to C:\Genesis\Stable\. You will see the following directories

To build the solution, open the Solutions folder and go to the Genesis Smart Client Framework sub-folder. Open the Genesis Smart Client Framework.sln in Visual Studio 2010.

Genesis Smart Client Framework Solution

When the solution opens for the first time you will be prompted to configure the database connection string.

Configure Database Connection 1

Make sure, before you do this step, that you have created the database in SQL Server.

Configure Database Connection 2

My local SQL server is located on (local)\SQL, change this to your SQL Server, including the authentication settings.

When everything is setup, you should see the following solution in your Solution Explorer.

Configure Database Connection 2

The Genesis Smart Client Framework solution is the central solution and contains all of the required project that encompass the Genesis Smart Client Framework. The following projects are included:

Database Deployment

Deploy the BlueMarble.Genesis.SQL database project to the database that you have created. After you have deployed the database tables and stored procedures, browse to C:\Genesis\Stable\Scripts on your local computer and run the Data.SQL script against your database to setup the initial data. If you have deployment issues, you can run the scripts in the following sequence: Tables.sql, StoredProcedures.sql, Assemblies.sql, Data.sql.

Once you've deployed the above, and scripted the initial data into the database, please run the following data fix to make some changes from the standard installation version to the source-only version:

USE [Genesis]
GO
UPDATE Module_File SET FilePath = '..\..\Scripts\' WHERE FilePath = '.\Scripts\'
UPDATE Module_File SET FilePath = '..\..\Genesis Smart Framework\Genesis.Client.Host\bin\debug\' WHERE FilePath = '.\Client\'
UPDATE Module_File SET FilePath = '..\..\Resources\' WHERE FilePath = '..\Resources\'
UPDATE Module_File SET FilePath = '..\..\Code\Genesis.Management\bin\debug\' WHERE FilePath = '.\Management\'
UPDATE Module_File SET FileUrl = REPLACE(FileUrl, 'http://localhost/genesis.filehost/', 'http://localhost:1581/genesis.filehost/')
UPDATE Module_File SET [FileName] = REPLACE([FileName], '.dll', '.dllx')
UPDATE Security_User SET StartupScript = 'http://localhost:1581/genesis.filehost/genesis/scripts/login.xml'


Deploy the GenesisDbClr CLR database project to the database that you have created. (Ensure that your database has clr-enabled set to true). If you have deployment issues, browse to C:\Genesis\Stable\Scripts on your local computer and run the Assemblies.SQL script against your database to create the CLR procedures.

Build the C# Code

You can now build the entire solution.

If you have any errors during the build, check the configuration manager and remove the following projects from the build steps:

Final Configuration

You've now managed to deploy the database and build all of the source code, the last step would be to change the required database connection strings in the web and web service applications. Check the following applications for web.config or app.config files. Open the required file and check for the connection string to the Genesis database:

In the Genesis.FileHost project, update the following key in the web.config file:

<add key="DevelopmentPath" value="..\..\Assemblies\"/> to <add key="DevelopmentPath" value=".\"/>

Writing a Genesis Hosted Application

In order to write a Genesis Hosted Application we're going to build on the Template Solution provided with the Source Code. So the first step would be to browse to C:\Genesis\Stable\Solutions\Template Solution\ on your local computer and to open the Template Solution.sln in Visual Studio 2010. You should be presented with the following view.

Template Solution

You will first notice a repeat of numerous of the projects from the previous solution. I'll exclude them here. The remainder of the projects are detailed below:

Set the Genesis.Application C# Library as the default startup project. Open the properties for this project and go to the Debug section. Set the Start Action to Start external program and set the program to start to c:\Genesis\Code Plex\Code\BlueMarble.Genesis.Client\bin\Debug\BlueMarble.Genesis.Client.exe. This will ensure that the custom Genesis Host implementation is started.

Template Solution

You also have to set the Build Events Post-build event command line to start iexplore http://localhost:1581/genesis.filehost/update.aspx?DevelopmentPath=$(ProjectDir) and the Run the post-build event to When the build updates the project output.

Template Solution

Build and Run your Application

You should now be presented with the following output from your build:

Template Solution

In the image above, you will see all of the files that the Genesis File Host has collected after the build has completed. This will happen every time that your build changes and ensures that you are getting the latest version of the code while you are debugging. The reason that this is required is that the Genesis Client Host application will download and execute whatever code is currently on the server, so if you forget to update the server you will have endless problems trying to identify why your code is not debugging properly.

It is important to note that the update process will investigate the DLL files in the Development Path every time and it will update the File Version in the Module_File table to match the DLL. This means that you set the file version each time between a build to ensure that your client application downloads the latest version of the DLL when you debug. It is also important to note that your client application will NOT download a DLL if the local version matches the server version. It is important to change the version number each time you wish to build and test the results while debugging.

You can close the browser with the update output now, and you will notice another window would have opened.

Template Solution

Log in with the following username/password: user1/user1.

Once the system has pre-authenticated you, you should notice that there is an Application in the combo box. The Genesis Management System 2010 is used to configure the Genesis Smart Client Framework. Click Sign in to continue. Once the process is complete, you should see the following screen:

Template Solution

You have now successfully managed to compile the Genesis Smart Client Framework, and got the Genesis Management System 2010 up and running. You use the Genesis Management System 2010 to configure any new applications that Genesis can host. The next step is to take the Genesis.Application template provided with the Source Code and configure it so that we can run the Hosted Application.

Configuring the Template Application

To configure the Genesis.Application template, open the Genesis Administration menu, and click on the Application item.

Template Solution

You will be presented with a list of the current Hosted Applications available on the Genesis Smart Client Framework server. Click on the New Application icon in the top right hand corner to create a new Hosted Application Configuration.

Template Solution

Enter the following information into the provided fields:

Template Solution

Click the Save icon in the top right corner and proceed to the bottom half of the page to view the Security Roles that have access to your application. Select the following roles:

Template Solution

Proceed to open the Genesis Administration menu and clicking on the File menu item. You will be presented with the following screen, click on the New File icon in the top right hand corner.

Template Solution

Enter the following information into the provided fields:

Template Solution

When you run the update process, you can either right click on the Update.ASPX page in the Genesis.FileHost project and select 'View In Browser', or browse to http://localhost:1581/genesis.filehost/update.aspx , you will see the following output, including Genesis.Application.dll

Template Solution

Once this process has run, you can re-run the application, and log back into the Genesis Management System 2010. IMPORTANT: The default application should be your new application that you created! IT WILL FAIL if you attempt to log into this application.

Once you are logged in, open the Genesis Administration menu and click on the Commands menu item. You will then be presented with the following screen where you can view all of the registered Commands:

Template Solution

The following changes have to be applied to the following Commands:

Open the Command, browse to the bottom of the page. There you will see a section where you can assign User Roles to each command. This will allow users belonging to that role to execute the Command on the Client Application.

Template Solution Template Solution

Click the Save Command icon in the top right corner of the page.

Also check that the Genesis.Common.ShowBrowser Command has the Registered Users and the Genesis Application Users roles assigned to it.

Because your application will be using components of the Genesis.Client.Host library, such as the built in Web Browser, you will need to define it as a required file of your application. To do this, open the Genesis Administration menu and click on the Files menu item. Click on the New File icon in the top right corner of the page.

Enter the following information into the provided fields:

Once you have registered the Genesis.Client.Host.dll file in the meta-data, you will have to add the Command entry for the Genesis.Common.ShowBrowser as well. Open the Genesis Administration menu and click on the Commands menu item. Click on the New Command icon in the top right corner of the page.

Enter the following information into the provided fields:

Click on the Save icon on the top right corner of the page, then add the following roles to the Command:

You can now close the Genesis Management System 2010

You are ready to run your Genesis Hosted Application now!

You are now ready to run your custom Genesis Hosted Application. Press F5 to debug the application. On the login screen, enter user1/user1 and select your application from the Application combo box then click on Sign in.

Your application should run, and execute the users' startup script.

Template Solution

You won't notice much of anything else though, however you have setup your project and you can start adding your own code to the Template Application now. Lets have a look at the Genesis.Application project.

Template Solution

When we look at the files in the project, there are 4 files that require our attention:

Using the Genesis Management System 2010 you can configure the Menu and Toolbars in the Client Application to include references to your commands. These commands will only generate visible menu/toolbar endpoints if the authenticated user has access to see them.

Re-run the Client Application again and this time log back into the Genesis Management System 2010. Open the Genesis Administration menu and click on the Ribbon menu item. Create a new Ribbon by clicking on the Create Ribbon icon in the top right corner of the page.

Template Solution Template Solution

Enter the following information into the provided fields:

Add the Registered Users and Genesis Application Users roles to this item.

Because the original framework was developed using a Ribbon Bar control, the configuration naming convention is oriented towards Ribbon layouts. However it is mapped onto a normal Menu/Toolbar configuration.

Open the Genesis Administration menu and click on the Ribbon Bars menu item. Create a new Ribbon Bar by clicking on the Create Ribbon Bar icon in the top right corner of the page.

Template Solution Template Solution

Enter the following information into the provided fields:

Add the Registered Users and Genesis Application Users roles to this item.

Because of a difference between Ribbon Bar layouts and standard menu's, such as the one used by the Template Application and the custom Client Host Application.

Open the Genesis Administration menu and click on the Item menu item. Create a new Bar Item by clicking on the Create Bar Item icon in the top right corner of the page.

Template Solution

Enter the following information into the provided fields:

Add the Registered Users and Genesis Application Users roles to this item.

Final Steps

If you re-run the application in debug mode, and this time sign into the My First Genesis Application Application, you will see a new Menu. Click on the My First Menu menu, then click on the Menu menu item.

Template Solution Template Solution

Fill in the fields and click on the Show button to execute the ShowMessage command.

Template Solution

You have successfully created and hosted your first Genesis Hosted Application. Go ahead and customize it.

In my next article I will continue where this article left off by creating a custom Twitter client that runs inside of the Genesis Smart Client Framework.

Other information

Blue Marble is proud to be a Microsoft BizSpark startup company.

Updates