Otk Custom Dbinstaller 1

OTK Custom DBInstaller Version 1.0

Publisher : OTK Web Solutions Date Released: 02 Jan 2007 Doc. Version : 1.1

PREREQUISITES This document assumes that:
You have experience in System
You have experience in
You have experience in
You have experience in

Microsoft Visual Studio 2005 Professional Edition or Team Setup and Deployment Projects application configuration file Microsoft SQL Server 2000

Contents 1. 2. 3. 4. 5. 6. 7. 8. 9.

Introduction System Requirements Download and Installation Understanding and Customizing Custom DBInstaller Using Custom DBInstaller as Custom Action in Visual Studio’s Setup and Deployment Projects Using Custom DBInstaller to Fix Application Database Program Limitations Copyright and License How to Contact Us

1. Introduction Custom DBInstaller is one of the software components developed by OTK Web Solutions. It is being used by OTK to provide installation of the required SQL Server database for its upcoming RAD product called OTKRap. It is now being released to the public free of charge in order to help those Microsoft .NET developers to incorporate a database installation feature into their Setup or Web Setup Project, which originally does not provide by Microsoft Visual Studio 2005. However, the Setup or Web Setup Project allows developers to add custom actions, which can be a customized EXE, DLL, or Installer Class. Therefore, Custom DBInstaller has been built as a standalone executable primarily for this purpose. For instructions on how to add Custom DBInstaller as a custom action, see Section 5 – Using Custom DBInstaller as Custom Action in Visual Studio’s Setup and Deployment Projects. In order to share this component with developers around the world, it has been modified to take advantage of the app.config file so that it is able to customize by the developers to suit their preferences, such as changing the form title, whether to allow users to overwrite the existing database and so on. For more information about changing these preferences, see Section 4 – Understanding and Customizing Custom DBInstaller and Section 6 - Using Custom DBInstaller to Fix Application Database.

Hope you find this component useful and feel free to feedback to us on anything about this component. For our contact information, see Section 9 – How to Contact Us.

2. System Requirements To install Custom DBInstaller, you need:



Windows XP Professional or Windows Server 2003 Microsoft .NET Framework 2.0

Additional software needed to run Custom DBInstaller:


Microsoft SQL Server 2000

Additional software needed to make Custom DBInstaller as part of your application installer:



Microsoft Visual Studio 2005 Professional Edition, or Microsoft Visual Studio 2005 Team Edition

3. Download and Installation To download Custom DBInstaller, go to: http://otkdownload.blogspot.com After downloading the Custom DBInstaller, double-click on OTK.CustomDBInstaller.Setup.msi to start the installer and follow the instructions on the screen.

4. Understanding and Customizing Custom DBInstaller Custom DBInstaller is an executable program file (OTKCustomDbInstaller.exe) developed in VB.NET. Its primary goal is to allow the developers to incorporate SQL database installation features into their application installer by adding it as a custom action in their Visual Studio’s Setup Project or Web Setup Project. It is also able to run independently by the users in order to install only the application database or reinstall the application database by overwriting the existing one. It also comes with a configuration file called OTKCustomDbInstaller.exe.config, which allows the developers to customize Custom DBInstaller to suit their needs. This configuration file is actually an app.config file that most of the .NET developers familiar with. The table below shows all the keys available in the appSettings section and their respective usage: Key Title

Usage To change the form title of the Custom DBInstaller dialog box, e.g. Install Northwind Application SQL Database.

DatabaseName

This will be the name of the database to be created by Custom DBInstaller, e.g. Northwind.

DefaultServerName

The default server name of the SQL Server when Custom DBInstaller is first loaded. The default value is (local).

DefaultUserID

The default user id when Custom DBInstaller is first loaded. The given user id must have the permission to restore database. The default value is sa.

DefaultPassword

The default password of the user id when Custom DBInstaller is first loaded. The default value is empty.

AllowEnterDbConnection

To specify whether to allow the user to enter or edit the database connection information, such as server name, user id, and password. Setting it to False will also hide the entire Database Connection frame. The default value is True.

ShowOptions

To specify whether to show the Options frame that allows the user to select one of the following:



Install only if not exist. Do not delete. Delete existing if any and reinstall again.

This is particularly useful when you do not want the users to overwrite the database every time they reinstall the database or the application. The default selected option is always the first option, i.e. Install only if not exist. Do not delete. DatabaseBackupFileName

The SQL database backup file name. This backup file needs to be presented in the same folder as where the OTKCustomDbInstaller.exe file is resided, e.g. application_database.bak.

5. Using Custom DBInstaller as Custom Action in Visual Studio’s Setup and Deployment Projects Although you can apply Custom DBInstaller in all kinds of Setup and Deployment Projects that support Custom Actions, in this document, we will use Web Setup Project as an example. To add Custom DBInstaller as a custom action in your Web Setup Project, follow the steps below: 1) Get ready your application’s SQL database and back it up to the Custom DBInstaller program folder where the OTKCustomDbInstaller.exe is resided. This will facilitate you to add it to your Web Setup Project at the later stage and make it more manageable. 2) Customize Custom DBInstaller according to your needs by changing the OTKCustomDbInstaller.exe.config file (see previous section) and save it. Remember to specify the database backup filename according the name that you previously backup. 3) Now you have three files in your Custom DBInstaller program folder:



OTKCustomDbInstaller.exe OTKCustomDbInstaller.exe.config (modified version)




Your application’s SQL database backup file

4) Open your solution in Visual Studio containing your Web Setup Project and open your File System Editor. For Custom DBInstaller to automatically launch at the end of your application installation session, you need to install your Web application together with the Custom DBInstaller. Note that whichever custom actions that you added will be the post-installation actions. 5) Add the three files as stated in step 3) to the File System Editor of your Web Setup Project. You may want to add them to the Program Files Folder as shown in Figure 1-0.

Figure 1-0 – Adding Custom DBInstaller to File System Editor 6) Now open your Custom Actions Editor and add the OTKCustomDbInstaller.exe file to the Install folder as shown in Figure 2-0. 7) Select OTKCustomDbInstaller.exe and change the InstallerClass property to False (see Figure 2-0).

Figure 2-0 – Adding Custom DBInstaller to Custom Actions Editor 8) If you have done with your other Web Setup Project tasks, build the project and try running your MSI file. Your Custom DBInstaller should be loaded at the end of your installation session according to your configuration preferences.

6. Using Custom DBInstaller to Fix Application Database To allow Custom DBInstaller to fix or reinstall the application database, in your OTKCustomDbInstaller.exe.config file, simply set the ShowOptions value to True. This will give the users an option to delete the existing database and reinstall the new one.

CAUTION: Selecting this option will delete all the data in the existing database and reinstall a fresh copy of the application database from the distributed database backup file. Custom DBInstaller will not create a backup copy of the existing database and OTK Web Solutions will not responsible for any lost of data.

7. Program Limitations Custom DBInstaller has the following known issues and limitations:









It does not have an option to backup or automatically backup the existing database before overwriting. It does not provide an option to update the application configuration file, e.g. the connectionstring section of the Web.config file. It does not support command line argument. Developers are not able to place the image banner on top of the dialog box as provided by the standard Windows Installer. When hiding any of the frames (Database Connection and Options), the one that visible will not change the format and layout for better appearance. Information in the OTKCustomDbInstaller.exe.config file will not be encrypted. It does not support model dialog, namely the user can still access the caller while Custom DBInstaller is still loaded. Due to the reason that the Custom DBInstaller is free of charge, we need the agreement of the users to allow us to: o Place the product hyperlink on the Custom DBInstaller’s user interface (Powered By: OTK Custom DBInstaller). o Display the OTK Custom DBInstaller product name on the title bar.

8. Copyright and License OTK Custom DBInstaller version 1.0 is freeware, which means you can use it without charge and distribute the complete package to any groups or individuals freely. The future versions of OTK Custom DBInstaller may or may not be free until further notice. Copyright ©2007 OTK Web Solutions. All Rights Rserved.

9. How to Contact Us We prefer our users to send us their feedback by submitting their comments through the following blog: http://otkfeedback.blogspot.com For other inquiries, you may email us at: [email protected] Thank you and hope you enjoy using our products!