Genesis Hybrid Smart Client Framework - Part VII

Stephan Johnson

4.75/5 (11 votes)

22 Jul 2009Ms-PL16 min read

32.2K

1.7K

This is part VII of a VII part series. This article covers the source code in a breakdown of each project's function.

Download installer - 3.33 MB
Download source - 2.5 MB
Download the latest release from Code Plex (opens in new window)

Latest Updates

23 July 2009: I've been in communication with developers using the code through these articles and corrected numerous issues with the installer. I've also zipped the code and attached it to this article, and it has been uploaded to Code Plex.

22 July 2009: I've just released a new version with an installer on Code Plex. I will be updating the attached zip file with this article later today. The installer makes it easier to set up and configure the framework before you start developing your own hosted applications. Follow the instructions on the release page.

If you are downloading the source code from this page, please refer to the release notes for instructions on compiling and executing the samples.

Introduction - The Complete Source

Over the last few articles, I've introduced you to various aspects of the source code. This article will highlight specific source code that serves important functions. By now you should have figured out that there are multiple components to the system. A web service for communicating with the database and to provide a client API, a web application used as an online file repository, a windows client application that implements the client API and possibly other databases and web applications. You should also have an understanding of how the client updates the hosted applications.

The Genesis Management System was implemented as a complete hosted application with the client API to demonstrate how to develop rich applications that are hosted using the Genesis Smart Client Framework.

This article is part VII of VII. Go to part I to see the index.

Please refer to our web site www.bluemarble.co.za for the most up to date information about the Genesis Smart Client Framework or any of our newsfeeds.

In order to pursue our active interest in releasing this version of the Genesis Smart Client Framework as an open source product, we've created a profile on www.codeplex.com where we maintain the most recent copy of the source code. If you want the latest version of the Genesis Smart Client Framework source code, go to our Code Plex profile or download the latest release from Code Plex.

Exploring the Solutions

The current release of the source code on Code Plex has three solution files in the Solutions folder. The three solutions are:

BlueMarble.Genesis.Client
This solution demonstrates how to implement your own Smart Client application using the Genesis Smart Client Framework client API.
Template Solution
This solution demonstrates how to implement your own hosted application using the Genesis Smart Client Framework client API.
Genesis Smart Client Framework
This solution contains the commercial release of the Smart Client application that uses the 3^rd party Ribbon control. This solution uses the BlueMarble.Genesis.Client Smart Client application as the default.

Exploring the Architecture

The Genesis Smart Client Framework has a multi-tier architecture to enable large scale enterprise rollout of Smart Client technology. The framework itself, including the client API was developed using C# for Microsoft .NET 3.5, SOAP Web Services, SQL Server 2008, TSQL, ASP.NET Web Forms and Windows Forms.

The goal was to implement an easy to use framework to allow us to focus on rapid application development without having to concern the developers with the basics for each new project. Our framework implements the following Smart Client concepts:

Self-Updating/Healing
Our client API allows the Smart Client application to determine when it is not using the latest version of the source code. This enables the application to update itself to ensure the user is always using the latest version.
Advanced Communication
By implementing our client API and developing your application using our guidelines, the framework facilitates advanced SOAP communication between the hosted applications and your servers.
Security
Our framework deals with user security, developers never have to worry about confirming user access from their code, all access is dynamically handled by the security system. Operators can grant intermittent access to certain code features to selected users.
Richness
By integrating web forms with Windows Forms through our Super Browser component, users can be working on a website and execute local code from inside the hosted application. A hyperlink can launch a local Windows Forms dialog allowing the user to edit the record. After the update, the webpage will self-refresh.
Control & Consistency
By allowing operators to control every aspect of the user interface and therefore the user experience, good governance will bring consistency in the user experience.

Back-end

The server side of the Genesis Smart Client Framework consists of a few projects, including a web services project, web application and a database. There are some common shared libraries as well.

Genesis.WebServices

The Genesis.WebServices project is an ASP.NET web services project. It contains the standard web services that implement the API. These web services are implemented by the Genesis.Client.Common libraries to form the Genesis Smart Client Framework client API.

In theory, any application using any development platform/technology can be distributed and managed by the Genesis Smart Client Framework. If you can develop your own libraries to implement the web services in this project, you would have developed your own port of the Genesis Smart Client Framework client API. You can then develop a Smart Client application implementing your port in the language (or platform) of your choice.

Exception

The Exception web service deals with login exceptions that occur in the Smart Client application while executing a hosted application to a central database where developers and system operators can access critical information. The following methods are available:

public void LogException(System.Xml.XmlNode Exception)

FileManager

The FileManager web service deals with files in the Genesis File System. The FileManager web service allows for partial file uploads, in case of slow network connections or to allow the Smart Client application to support disconnected uploads. The following methods are available:

C#
```
public Guid UploadFile
	(string FileName, string FileType, int FileSize, Guid UserGuid)
```
This method allows the client to create a file upload session. The parameters required are the File Name, Type of File, Size of the File and the User Guid for the user uploading the file. This method returns a Guid for partial uploads.
C#
```
public void UploadFilePart(Guid DocumentGuid, int FilePartNumber, byte[] FilePart)
```
This method uploads parts of a file for a given file upload session. The parameters required are the File Upload Session Guid (DocumentGuid), the position of the file in the collection of parts, and a byte array containing the actual file part.
C#
```
public void JoinFileParts(Guid DocumentGuid)
```
Once all the file parts for a given file have been uploaded, the file parts can be joined on the server. This is simply an end to end binding of the collection of byte arrays that make up the file parts.
C#
```
public void DeleteTemporaryFolder(Guid DocumentGuid)
```
Once a file has been joined, the complete file will be available for other users to access. This method deletes the individual file parts on the server for a specific file.
C#
```
public int GetArraySize()
```
The server can determine the size of the byte arrays for individual file parts. The Smart Client application can request from the server the recommended size for the file parts.
C#
```
protected string SetFilePath(Guid DocumentGuid)
```
This method returns the local server path for a specific document.
C#
```
protected string SetUrlPath(Guid DocumentGuid)
```
This method returns the online server URL for a specific document.
C#
```
protected string GetFileType(Guid DocumentGuid)
```
This method queries the type of a file in the Genesis File System.

Genesis

The Genesis web service deals with dynamic queries on the database. The following methods are available:

C#
```
public System.Data.DataTable ExecuteTable(Guid TransactionGuid, 
	string CommandText, string ConnectionStringKey, 
	System.Data.CommandType CommandType, string TableName, 
	params Common.Classes.DataParameter[] Parameters)
```
This method executes an ExecuteDataset method on a SQL Command. The first table is extracted into a DataTable which is the return value of this method. The parameters required are the TransactionGuid (not implemented), the text of the SQL Command, the name of the Connection String Key in the configuration file, the name of the Table to extract out of the Dataset and an array of the parameters.
C#
```
public object ExecuteScalar(Guid TransactionGuid, string CommandText, 
	string ConnectionStringKey, System.Data.CommandType CommandType, 
	string TableName, params Common.Classes.DataParameter[] Parameters)
```
This method executes an ExecuteScalar method on a SQL Command. The parameters required are the TransactionGuid (not implemented), the text of the SQL Command, the name of the Connection String Key in the configuration file, the name of the Table to extract out of the Dataset and an array of the parameters.
C#
```
public void ExecuteNonQuery(Guid TransactionGuid, string CommandText, 
	string ConnectionStringKey, System.Data.CommandType CommandType, 
	string TableName, params Common.Classes.DataParameter[] Parameters)
```
This method executes an ExecuteNonQuery method on a SQL Command. The parameters required are the TransactionGuid (not implemented), the text of the SQL Command, the name of the Connection String Key in the configuration file, the name of the Table to extract out of the Dataset and an array of the parameters.

KeepAlive

The KeepAlive web service deals with keeping connections with the server active to ensure reliable network speeds. It also serves as a test for the Smart Client application to detect when to go into offline mode. The following methods are available:

C#
```
public string Ping()
```
This method simply returns the current time from the server.
C#
```
public System.Xml.XmlNode Test(System.Xml.XmlNode TestNode)
```
This method allows the Smart Client application to pass diagnostic information to the server in an XML packet. This packet can contain information from the client, such as the test start time, and test requirements on the server, such as a Ping Test. Different tests can do different server actions. Each server action updates the XML packet which is returned to the client for a local diagnostic of server access time, throughput, etc.

Lookup

The Lookup web service provides a generic lookup interface to database tables. The following methods are available:

public DataTable GetLookupValues
    (string TableName, string ValueColumnName, string DisplayColumnName)

This method returns a datatable with the lookup values from a custom table.

public DataTable GetLookupValuesUsingConnection(string TableName, 
    string ValueColumnName, string DisplayColumnName, string ConnectionStringKey)

This method returns a datatable with the lookup values from a custom table using a different database connection.

Module

The Module web service deals with the Application, File, Command and user interface Meta-Data. The following methods are available:

C#
```
public DataTable GetApplicationRibbons(Guid SessionGuid)
```
This method returns a list of all of the top level ribbons. The parameter required is the active user SessionGuid.
C#
```
public DataTable GetRibbonBars(Guid SessionGuid, Guid RibbonGuid)
```
This method returns a list of all of the Ribbon Bars for a specific Ribbon. The parameters required are the active user SessionGuid and the Ribbon Guid.
C#
```
public DataTable GetBarItems
    (Guid SessionGuid, Guid RibbonBarGuid, Guid ParentBarItemGuid)
```
This method returns a list of all the Bar Items for a specific Ribbon Bar. The parameters required are the active user SessionGuid, RibbonBarGuid and the ParentBarItemGuid (for hierarchical Bar Items).
C#
```
public DataTable GetApplicationFiles(Guid SessionGuid, Guid ApplicationGuid)
```
This method returns a list of all the files required for a specific hosted application. The parameters required are the active user SessionGuid and the ApplicationGuid.
C#
```
public DataTable GetApplicationCommands(Guid SessionGuid, Guid FileGuid)
```
This method returns a list of all the Commands for a specific file. The parameters required are the active user SessionGuid and the FileGuid.
C#
```
public DataTable ApplicationGetList()
```
This method returns a list of all of the Hosted Applications.
C#
```
public DataTable ApplicationGetByApplicationGuid(Guid ApplicationGuid)
```
This method returns a specific Hosted Application. The parameter required is the ApplicationGuid.
C#
```
public bool ApplicationUpdate(int ApplicationId, Guid ApplicationGuid, 
    string ApplicationName, string ApplicationDescription, int Order, bool Visible)
```
This application updates the Hosted Application record on the server. The parameters required are the ApplicationId for the record to update, ApplicationGuid, ApplicationName, ApplicationDescription, the Application Order and visibility.
C#
```
public int ApplicationInsert(Guid ApplicationGuid, string ApplicationName, 
    string ApplicationDescription, int Order, bool Visible)
```
This application creates a new Hosted Application record on the server. The parameters required are the ApplicationGuid, ApplicationName, ApplicationDescription, the Application Order and visibility.
C#
```
public DataTable FileGetList()
```
This method returns a list of all the files for Hosted Applications.
C#
```
public DataTable FileGetByFileGuid(Guid FileGuid)
```
This method returns a specific File. The parameter required is the FileGuid.
C#
```
public DataTable FileGetByFileTypeId(int FileTypeId)
```
This method returns a list of all files that are of a specific type. The parameter required is the FileTypeId.

public bool FileUpdate(int FileId, Guid FileGuid, Guid ApplicationGuid, 
    string FileName, string FileDescription, string FilePath, string FileUrl, 
    int FileTypeId, int VersionMajor, int VersionMinor, int VersionBuild, 
    int VersionRevision, int Order)

This method updates the File record on the server. The parameters required are the FileId, FileGuid, ApplicationGuid, FileName, FileDescription, FilePath, FileUrl, FileTypeId, Version and the File Order.

public int FileInsert(Guid FileGuid, Guid ApplicationGuid, string FileName, 
    string FileDescription, string FilePath, string FileUrl, int FileTypeId, 
    int VersionMajor, int VersionMinor, int VersionBuild, int VersionRevision, 
    int Order)

This method creates a new File record on the server. The parameters required are the FileGuid, ApplicationGuid, FileName, FileDescription, FilePath, FileUrl, FileTypeId, Version and the File Order.

C#
```
public DataTable CommandGetList()
```
This method returns a list of all the Commands.
C#
```
public DataTable CommandGetListWithNullRecord()
```
This method returns a list of all the Commands, including a record with a NULL reference. This record is used when allowing the user to select a Command from a list, but where the user can select no Command as a valid option.
C#
```
public DataTable CommandGetByCommandGuid(Guid CommandGuid)
```
This method returns a specific Command. The parameter required is the CommandGuid.

public bool CommandUpdate(int CommandId, Guid CommandGuid, Guid FileGuid, 
    string CommandName, string CommandDescription, string CommandCode, 
    string CommandType)

This method updates the Command record on the server. The parameters required are the CommandId, CommandGuid, FileGuid, CommandName, CommandDescription, CommandCode and the CommandType.

C#
```
public int CommandInsert(Guid CommandGuid, Guid FileGuid, string CommandName, 
    string CommandDescription, string CommandCode, string CommandType)
```
This method creates a new Command record on the server. The parameters required are the CommandGuid, FileGuid, CommandName, CommandDescription, CommandCode and the CommandType.
C#
```
public DataTable RibbonGetList()
```
This method returns a list of all the Ribbons.
C#
```
public DataTable RibbonGetByRibbonGuid(Guid RibbonGuid)
```
This method returns a specific Ribbon. The parameter required is the RibbonGuid.
C#
```
public bool RibbonUpdate(int RibbonId, Guid RibbonGuid, Guid ApplicationGuid, 
    string RibbonName, int Order)
```
This method updates the Ribbon record on the server. The parameters required are the RibbonId, RibbonGuid, ApplicationGuid, RibbonName and the Order of the Ribbon.
C#
```
public int RibbonInsert(Guid RibbonGuid, Guid ApplicationGuid, 
    string RibbonName, int Order)
```
This method creates a new Ribbon record on the server. The parameters required are the RibbonGuid, ApplicationGuid, RibbonName and the Order of the Ribbon.
C#
```
public DataTable RibbonBarGetList()
```
This method returns a list of all the Ribbon Bars.
C#
```
public DataTable RibbonBarGetByRibbonBarGuid(Guid RibbonBarGuid)
```
This method returns a specific Ribbon Bar. The parameter required is the RibbonBarGuid.
C#
```
public bool RibbonBarUpdate(int RibbonBarId, Guid RibbonBarGuid, 
    Guid RibbonGuid, string RibbonBarName, int Order)
```
This method updates the Ribbon Bar record on the server. The parameters required are the RibbonBarId, RibbonBarGuid, RibbonGuid, RibbonBarName and the Order for the Ribbon Bar.
C#
```
public int RibbonBarInsert(Guid RibbonBarGuid, Guid RibbonGuid, 
    string RibbonBarName, int Order)
```
This method creates a new Ribbon Bar record on the server. The parameters required are the RibbonBarGuid, RibbonGuid, RibbonBarName and the Order for the Ribbon Bar.
C#
```
public DataTable BarItemGetList()
```
This method returns a list of all the Bar Items.
C#
```
public DataTable BarItemGetListWithNullRecord()
```
This method returns a list of all the Bar Items, including a record with a NULL reference. This record is used when allowing the user to select a Bar Item from a list, but where the user can select no Bar Item as a valid option.
C#
```
public DataTable BarItemGetByBarItemGuid(Guid BarItemGuid)
```
This method returns a specific Bar Item. The parameter required is the BarItemGuid.

public bool BarItemUpdate(int BarItemId, Guid BarItemGuid, Guid RibbonBarGuid, 
    Guid ParentBarItemGuid, Guid CommandGuid, string BarItemName, 
    string BarItemImage, int BarItemImageSize, int BarItemTypeId, int Order)

This method updates the Bar Item record on the server. The parameters required are the BarItemId, BarItemGuid, RibbonBarGuid, ParentBarItemGuid, CommandGuid, BarItemName, BarItemImage, BarItemImageSize, BarItemTypeId and the Order of the Bar Item.

C#
```
public int BarItemInsert(Guid BarItemGuid, Guid RibbonBarGuid, 
    Guid ParentBarItemGuid, Guid CommandGuid, string BarItemName, 
    string BarItemImage, int BarItemImageSize, int BarItemTypeId, int Order) 
```
This method creates a new Bar Item record on the server. The parameters required are the BarItemGuid, RibbonBarGuid, ParentBarItemGuid, CommandGuid, BarItemName, BarItemImage, BarItemImageSize, BarItemTypeId and the Order of the Bar Item.

Security

The Security web service deals with authenticating the user and module access. The following methods are available:

public Guid AuthorizeUser(Guid ApplicationGuid, string Username, string Password)

public Guid CreateTransaction(string TransactionCode, Guid SessionGuid)

public void CompleteTransaction(Guid TransactionGuid)

C#
```
public DataTable RoleGetList()
```

public DataTable RoleGetByRoleGuid(Guid RoleGuid)

public DataTable RoleGetByUserGuid(Guid UserGuid)

public DataTable RoleGetByApplicationGuid(Guid ApplicationGuid)

public DataTable RoleGetByCommandGuid(Guid CommandGuid)

public DataTable RoleGetByRibbonGuid(Guid RibbonGuid)

public DataTable RoleGetByRibbonBarGuid(Guid RibbonBarGuid)

public bool RoleUpdate
	(int RoleId, Guid RoleGuid, string RoleName, string RoleDescription)

public int RoleInsert(Guid RoleGuid, string RoleName, string RoleDescription)

C#
```
public DataTable UserGetList()
```

public DataTable UserGetByUserGuid(Guid UserGuid)

public bool UserUpdate(int UserId, Guid UserGuid, string UserName, 
	string Password, string Email, bool Active, string StartupScript)

public int UserInsert(Guid UserGuid, string UserName, string Password, 
	string Email, bool Active, string StartupScript)

C#
```
public DataTable UserRoleGetList()
```

public int UserRoleInsert(Guid UserGuid, Guid RoleGuid)

public int UserRoleDelete(Guid UserGuid, Guid RoleGuid)

public DataTable ApplicationRoleGetList()

public int ApplicationRoleInsert(Guid ApplicationGuid, Guid RoleGuid)

public int ApplicationRoleDelete(Guid ApplicationGuid, Guid RoleGuid)

C#
```
public DataTable CommandRoleGetList()
```

public int CommandRoleInsert(Guid CommandGuid, Guid RoleGuid)

public int CommandRoleDelete(Guid CommandGuid, Guid RoleGuid)

C#
```
public DataTable RibbonRoleGetList()
```

public int RibbonRoleInsert(Guid RibbonGuid, Guid RoleGuid)

public int RibbonRoleDelete(Guid RibbonGuid, Guid RoleGuid)

C#
```
public DataTable RibbonBarRoleGetList()
```

public int RibbonBarRoleInsert(Guid RibbonBarGuid, Guid RoleGuid)

public int RibbonBarRoleDelete(Guid RibbonBarGuid, Guid RoleGuid)

Genesis.FileHost

The Genesis.FileHost acts as the Genesis File System by exposing the required application files to the Smart Client applications, and also by acting as the upload repository for files that are created by the Smart Client application. This function is important because it allows immediate access to a file from another Smart Client application.

There are a couple of functional web pages available on the file host as well. These are:

Database/File System Synchronization

By opening the /update.aspx file in your browser, the system will synchronize the database and the file system. A report will be generated as to the success of the update including new/updated Commands and version numbers.

Database Backup

By opening the /deployment/database/backup.aspx file in your browser with the required parameters, the system will create a backup of the specified database and publish it in the Genesis File System.

Online Deployment

By opening the /Deployment/default.aspx file in your browser, you will be able to upload a deployment package to the server.

Web.Config

There are some important keys in the web.config file.

XML

<appsettings>
	<add key="LocalPath" value=".\"/>
	<add key="WebPath" value="http://localhost:1581/Genesis.FileHost/"/>
	<add key="DevelopmentPath" value="..\..\"/>
	<add key="TempPath" value="..\..\Temp\FileHost\"/>
	<add key="BackupPath" value="..\..\Databases\Backup\"/>
</appsettings>
<connectionstrings>
	<add name="GenesisConnectionString" 
		connectionString="Server=VSQL01\SQL01;
		Initial Catalog=BlueMarble.Genesis.Dev;Integrated Security=SSPI;"/>
</connectionstrings>

Database

There are two database projects. One contains TSQL stored procedures and the other contains CLR stored procedures. The CLR stored procedures are used by the authentication system, the TSQL stored procedures are implemented in the web services and form part of the API.

The Client API

The client API is a C# for Microsoft .NET 3.5 implementation of the SOAP web services in the Genesis.WebServices project. It consists of a few projects all of which have base classes and interfaces to simplify the development cycle.

Genesis.Client.Common

The Genesis.Client.Common class library implements the most common Genesis APIs. It implements the SOAP client for the Exception, FileManager, Genesis, KeepAlive and Lookup web services. It also has some base classes for dialogs and forms. This class library was developed using C# for Microsoft .NET 3.5.

Genesis.Client.Module

The Genesis.Client.Module class library implements the Genesis Module API. It implements the SOAP client for the Module web services. This class library was developed using C# for Microsoft .NET 3.5.

Genesis.Client.Security

The Genesis.Client.Security class library implements the Genesis Security API. It implements the SOAP client for the Security Web services. This class library was developed using C# for Microsoft .NET 3.5.

Genesis.Client.Host

The Genesis.Client.Host class library implements the Genesis Host API. It has the required interfaces and default forms required by all Smart Client applications.

The Smart Client Application

The Smart Client application implements the Genesis Smart Client Framework client API. It serves as the host for the applications hosted in the Genesis Smart Client Framework. There are two different Smart Client applications available with this source release.

Genesis.Host

The Genesis.Host windows application serves as the host for the applications. It implements the Genesis Smart Client Framework client API and supports authenticating the user and signing the user into an application. It can download the required application updates, and display the user interface components for the application.

The Genesis.Host Smart Client application is dependant on the Genesis.Client.HostFormLibrary class libraries for its user interface components. It is also dependant on a 3^rd party Ribbon control.

Genesis.Client.HostFormLibrary

The Genesis.Client.HostFormLibrary contains some user interface elements for the 3^rd party Ribbon control that is used by the Genesis.Host Smart Client application.

Other Information

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

DISCLAIMER

The Genesis Smart Client Framework is a commercial closed source application. It is being provided on Code Project with all of the benefits that articles on Code Project grant its users (i.e. Free and Fair use), however it must be noted that some modules contain a 3^rd party control that we are unable to license via Code Project. Once all of the articles are uploaded, the code will be extracted to a separate obfuscated library to protect our vendor's Intellectual Property. The full source code will be provided for this library, excluding the few lines that could compromise our License. An alternative will also be provided for developers who wish to use a completely free version.

DISCLAIMER UPDATE

An implementation of a standard Microsoft .NET controls user interface has been created and is available on Code Plex as of release 1.30.1024.0. This release complies with all of the Code Project article publishing terms and conditions.

Update History

23 July 2009

Added zipped source code to complement the MSI
Resolved a few issues in the installer specifically relating to Windows XP installations with IIS 5

22 July 2009

Updated the link to the latest release on Code Plex
The Code Plex release is now contained in an MSI setup project and installs the database and web components correctly. It also installs a Project Template into Visual Studio.
TODO: The release on Code Plex is currently just the installer, I am busy building the source only ZIP files to publish on Code Project (this article) and Code Plex.

22 June 2009

Added an update history section to this document.
Added short descriptions of each method (INCOMPLETE)

License

This article, along with any associated source code and files, is licensed under The Microsoft Public License (Ms-PL)