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 to building and configuring the template application. If you are interested, there is a follow up article to this one where I guide you through the process of creating a Twitter client that runs inside of the Genesis Smart Client Framework.
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
- Code - Contains miscelanious projects
- Databases - Contains database projects, including the CLR database project
- Deployment - Contains the deployment system that ships with Genesis (I'll do a whole article for this)
- Genesis Smart Framework - Most of the functional projects are in this folder
- Scripts - Contains database scripts for the installer
- Setup - Contains the setup project for the installer available on Code Plex
- Solutions - Contains the solutions that make up Genesis
- Web - Contains the web projects
- WebService - Contains the web service project
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.
When the solution opens for the first time you will be prompted to configure the database connection string.
Make sure, before you do this step, that you have created the database in SQL Server.
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.
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:
- Genesis.Host - This project is the Windows Forms client application. It implements the required Genesis interfaces which enables it to connect to the Genesis server to get meta-data, and to host Genesis Hosted Applications. This application will ensure that the libraries that make up the Hosted Applications are always up to date before executing them. This application also deals with user security and provides a working surface for the Hosted Applications.
- Genesis.Loader - This project is installed on client computers, generally using Click-Once. It connects to the Genesis.Filehost and downloads an XML file with installation instructions. This program then downloads all of the required files for the Genesis.Host and executes the host. The purpose of this application is to enable light weight installations on client computers. This program is responsible for making sure that the Genesis.Host is always up to date, and the Genesis.Host makes sure its dependant Libraries (ie. Hosted Applications) are always up to date.
- Genesis.Client.Common - Common Client libraries.
- Genesis.Client.Host - Client libraries specific to custom host implementations.
- Genesis.Client.HostFormLibrary - Client libraries with specific standard forms for custom host implementations.
- Genesis.Client.Module - Client library that contains all of the required interfaces and base classes for a Genesis Hosted Application.
- Genesis.Client.Security - Client library that enables client applications to use Genesis for authentication.
- BlueMarble.Genesis.sql - SQL project for the Genesis database.
- GenesisDbClr - CLR database project for the Genesis database.
- Genesis.Deployment - Deployment tool for Genesis Hosted Applications.
- Genesis.Management.Web - Web based management system for the Genesis Smart Client Framework. This application also serves as a sample implementation of a Genesis Hosted Application.
- Genesis.Management - This library is a Genesis Module (aka. Genesis Hosted Application). This library contains the logic needed to tell the client application how to behave. This module serves as a sample implementation of a Genesis Hosted Application.
- Genesis.WebService - This web service contains all of the server-side logic that is exposed to the client implementations.
- Genesis.FileHost - This web site serves as a HTTP file server. It contains the current versions of the Genesis.Host application, the Genesis Hosted Application library files and any files that your application would store centrally for all other clients to access.
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:
- BlueMarble.Genesis.SQL - You've already built and deployed this, no need to keep building and deploying it.
- GenesisDbClr - You've already built and deployed this, no need to keep building and deploying it.
- Genesis.Installer - You're not installing it.
- Genesis.Installer.Extensions - You're not installing it.
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:
- Genesis.WebService - web.config Update the value of the GenesisConnectionString to match your deployment settings
- Genesis.FileHost - web.config Update the value of the GenesisConnectionString to match your deployment settings
- Genesis.Web - web.config Update the value of the GenesisConnectionString to match your deployment settings
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.
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:
- BlueMarble.Genesis.Client - A custom implementation of the Genesis Client API. This replaces the Genesis.Host application in the previous solution.
- BlueMarble.Genesis.Client.Standard - Contains some standard Windows Forms used by the client application.
- Genesis.Application - This C# Library implements all of the Genesis Client interfaces and is a Genesis Hosted Application.
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.
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.
Build and Run your Application
You should now be presented with the following output from your build:
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.
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:
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.
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.
Enter the following information into the provided fields:
- Application Name - Enter a name for your application.
- Description - Enter a description for your application.
- Order - Enter the order that your application should be displayed when multiple applications are available.
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:
- Registered Users
- Genesis Application User
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.
Enter the following information into the provided fields:
- File Name - The name of the DLL that contains the Hosted Application. For the Template Application project the default name will be Genesis.Application.dll.
- Type - For a DLL set the Type to Library.
- Description - Enter a description for your file.
- Application - Select the Application that you created from this list.
- Order - The order in which the file is downloaded and processed by the client.
- Path - The local path where the Genesis.FileHost update process picks up the file to process into the server file store. The default for the Template Application is ..\..\Code\Genesis.Application\bin\Debug\
- Url - The online location where the Genesis.FileHost file store will make the file available. The default for the Template Application is http://localhost:1581/genesis.filehost/myApp/libraries/Genesis.Application.dllx
- Version - When adding a new DLL, simply enter 1.0.0.0 for the version. The Genesis.FileHost update process will automatically set the version number.
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
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:
The following changes have to be applied to the following Commands:
- Genesis.Application.Commands.ShowDefaultForm
- Genesis.Application.Commands.ShowMessage
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.
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:
- File Name - Genesis.Client.Host.dll
- Type - Library.
- Description - Genesis Client Host libraries for the Genesis Management System.
- Application - Select the Application that you created from this list.
- Order - 100.
- Path - ..\..\Genesis Smart Framework\Genesis.Client.Host\bin\debug\
- Url - http://localhost:1581/genesis.filehost/genesis/libraries/genesis.client.host.dllx
- Version - 1.60.1024.1
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:
- File - Genesis.Client.Host.dll
- Command Name - Web Browser.
- Description - This command shows the web browser.
- Type - Genesis.Client.Host.Commands.Common.ShowWebBrowser
Click on the Save icon on the top right corner of the page, then add the following roles to the Command:
- Registered Users
- Genesis Application User
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.
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.
When we look at the files in the project, there are 4 files that require our attention:
- AssemblyInfo.cs - Each time that you change the assembly, before you debug, you have to change the Version Number.
- Commands\ShowDefaultForm.cs - A standard Genesis Command, this command shows the default form Forms\DefaultForm.cs.
- Commands\ShowMessage.cs - A standard Genesis Command, this command uses System.Windows.Forms.MessageBox.Show to show a message using the parameters.
- Forms\DefaultForm.cs - A standard Windows Forms form. This form is shown using the ShowDefaultForm Command.
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.
Enter the following information into the provided fields:
- Ribbon Name - My First Menu
- Application - My First Genesis Application
- Order - 100
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.
Enter the following information into the provided fields:
- Ribbon Bar Name - Seperator 1
- Application - My First Menu
- Order - 100
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.
Enter the following information into the provided fields:
- Bar Name - My Menu Item
- Parent Bar Item - <Root Item>
- Bar Item Type - Button Item
- Ribbon Bar - Seperator 1
- Command - Default Form
- Image - Select any image from the list, and enter 16 in the Size value.
- Order - 100
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.
Fill in the fields and click on the Show button to execute the ShowMessage command.
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
- 24 APR 2010 - Updated download instructions.
- 19 APR 2010 - Published source code on CodePlex Online Source Control. Updated article to reflect this information.
