Once you've finished an Application, how do you distribute it?
Creating a Setup and Deployment package in Visual Studio 2008 makes distributing your finished applications quick and easy.
Preparing DatabaseSnooper for distribution
Launch Microsoft Visual Studio 2008. Drop down the File menu and select Open Project... Locate your DatabaseSnooper project file (DatabaseSnooper.vbproj) and double-click on it to open it.
DatabaseSnooper is very close to being distributable. It already includes a help file and context sensitive help. We only need to add a couple more things to it before it will be ready for deployment.
Set DatabaseSnooper's Icon property
As you know, every program has an icon associated with it. We have yet to assign an icon to any of the projects we've done so far. But when you prepare a program for distribution, you don't want to forget to spend at least 2 or 3 hours trying to find or create an icon for it. In fact, for some particularly small applications, you may spend more time finding an icon for it than writing the program itself. Well, I've saved you some time here by providing you with an icon file for DatabaseSnooper. Right-click on the DatabaseSnooper project in the solution explorer window, and select Properties from the context menu to display the DatabaseSnooper properties window:
With the Application tab selected, click on the Browse... item on the Icon combobox, as shown above. Then navigate to the c:\shared\bitmaps folder and select the EYE.ICO file, as shown:
Click the Open button to assign this icon file to your project (Note: If you are doing this project at home or work, feel free to find another icon file as a substitute and use it for the duration of this project. Do a search for free icons on the web). Your DatabaseSnooper project window should now look like the following illustration:
Click the Save All button on the standard toolbar.
Applying the Icon to the Form files
Open the design view of the frmDatabaseSnooper.vb form file. Make sure the frmDatabaseSnooper form is selected in the design view window so you can see its properties in the properties window. Click on the ellipses button of the Icon property to open a browser window. Select the EYE.ICO file that we just added to the project folder, like this:
With the EYE.ICO file selected click the Open button. The Icon property of the frmDatabaseSnooper form should now look like this:
And the upper left corner of the frmDatabaseSnooper form in your design window should look like this:
Now set the Icon property of the frmAbout form to the EYE.ICO file as well.
Click the Save All button.
Put a copy of the DatabaseSnooper.chm help file into the DatabaseSnooper project folder
Back when we did the DatabaseSnooper project we placed the DatabaseSnooper.chm help file inside the DatabaseSnooper\bin\Debug folder so that we could test it. You need to move that file into the DatabaseSnooper project folder, do that now.
Create and add a readme.txt file to the DatabaseSnooper project folder
As a common practice, a readme.txt or support.txt file is included in the program folder of most applications. It contains program installation, removal, and support instructions for the user. We will now create a very basic readme.txt file that will be included in our deployment package for DatabaseSnooper.
Open the Notepad application (usually found inside the Accessories folder on the Start menu). Use the illustration below as a guide and type this text, which briefly describes the minimum system requirements for DatabaseSnooper, how to install the program, and how to uninstall it:
When you are finished, select Save on notepad's File menu. Be sure to save the file as readme.txt inside your DatabaseSnooper project folder.
Make sure the DatabaseSnooper project folder includes all the files your deployment package needs
Click the Show All Files button at the top of the solution explorer window to display all the files in the DatabaseSnooper project. It should look like this:
Be sure that the DatabaseSnooper.chm help file, the EYE.ICO file, and the Readme.txt files are listed, as above. Note: All the files in your DatabaseSnooper project folder should be listed. If the DatabaseSnooper.chm help file, the EYE.ICO file, or the Readme.txt file are missing, make sure you put copies of them into your DatabaseSnooper project folder before going on.
Adding the Solutions Configurations selection combo box to the toolbar
When you test run a project it is compiled to an exe or dll file inside a Debug folder which is in the bin folder of your project folder. This compiled version of your program contains extra code that lets you suspend your program, step through it line by line, and examine the value of variables in real time. When an error occurs in a program compiled in Debug mode the development environment can stop and highlight the line that caused the error so that you can easily debug it. When we are ready to compile a program for distribution we need to remove the extra debugging code that a Debug compiled version contains—which streamlines the program and can speed up its performance significating—we need compile it in Release mode. Changing back and forth from Debug to Release mode isn't possible until we add the Solutions Configurations selection combo box to the toolbar.
The illustration above includes a toolbar with the Solutions Configurations selection combo box. It makes switching a build from Debug to Release mode easy. Unfortunately it is not normally included on the toolbar by default. So here is how we add it to the toolbar—in the classroom this should already be on your toolbar:
1) Drop down the Tools menu and select Options... to display the Options dialog. Checkmark the Show advanced build configurations item, as shown and click the OK button:
2) Drop down the Tools menu again and select Customize... to display the Customize dialog. Click on the Command tab and select the Build item in the Categories listbox. Scroll the Commands listbox all the way to the bottom to find the Solution Configurations combo box, as shown:
3) Use the left mouse button to click and drag the Solutions Configurations combo box to your toolbar and drop it there—I suggest placing it near your Start Debugging button, like this:
Click the Close button to close the Customize dialog. Now you will be able to easily change the compile method from Debug to Release whenever you need to.
Compiling a Release version of DatabaseSnooper
Set the Solutions Configurations combo box on the toolbar to Release. Right-click on the DatabaseSnooper project in the solution explorer window and select the Build menu item, as shown:
This compiles and creates the DatabaseSnooper.exe file (in the DatabaseSnooper\bin\Release folder) in a final, distributable form.
Adding a Setup and Deployment project with Setup Wizard
Do NOT remove your DatabaseSnooper project! Now drop down the File menu and under the Add menu item select New Project... When the Add New Project dialog appears, click on the little arror (+ in Visual Studio 2005) in front of Other Projects Types to expand it. Click on the Setup and Deployment item to see the templates that are available for creating setup and deployment packages, as shown below:
Click on the Setup Wizard template and type SetupDatabaseSnooper in the Name textbox (as shown above) and click the OK button. This starts the Setup Wizard. This is the first dialog you should see:
Click on the Next button to display the Choose a Project Type dialog:
Select the Create a setup for a Windows application item (as shown above) and click the Next button to display the Choose Project Outputs to Include dialog:
Check mark the following items:
- Localized resources from DatabaseSnooper—This
would include the satellite assemblies for each culture's resources. If your
program is designed to be deployed internationally, it would include
resource files that support
European date formats and other currency formats.
- Content Files from DatabaseSnooper—Includes
all content files in the project.
- Primary output from DatabaseSnooper—Includes
the DLL or EXE built by the project.
- Documentation Files from DatabaseSnooper—Includes the XML Documentation files for the project.
Now click the Next button to display the Choose files to include dialog:
Because we've added all the files we want to include to the DatabaseSnooper project folder, we don't need to add any additional files with this dialog, so leave it blank and click the Next button to display the final Create Project dialog, which should look like this:
Click the Finish button. Take a look at your solution explorer window. It should now contain two projects—DatabaseSnooper and SetupDatabaseSnooper—inside a Solution named DatabaseSnooper:
Click the Save All button. Note: If you need to close this project and open it again later, be sure to open the DatabaseSnooper.sln solution file, not the DatabaseSnooper.vbproj project file. The solution file includes both projects as shown above.
Set the AddRemoveProgramsIcon property of the SetupDatabaseSnooper project
The AddRemoveProgramsIcon property of the SetupDatabaseSnooper project is the icon that will be displayed with the program you are distributing in the Add Remove Programs list after your program is installed on a user's computer. It's good to make this icon the same one your application uses so that a user won't have a problem quickly spotting your application in the Add Remove Programs list when then go to remove it from their computer (usually after running it the first time—I'm joking, really I am).
Click once on the SetupDatabaseSnooper project in the solution explorer window to see it's properties in the properties window. Click on the drop-down arrow of the AddRemoveProgramsIcon property:
Then choose the Browse item to open the Icon selection dialog (as shown below):
Click on the Browse button to see the Select Item in Project dialog (as shown below):
The three folders in the Select Item in Project dialog Look in pane represent locations on the user's computer where your application is going to be installed, they are:
- Application Folder—This is the actual folder where your application is installed on the user's computer. For the DatabaseSnooper application, this would normally default to c:\Program Files\[company name]\DatabaseSnooper, but the user has the opportunity to change this location during the installation process.
- User's Desktop—The desktop of the user's computer. You can use this folder to add a shortcut to your application to the user's desktop during installation.
- User's Programs Menu—This is inside to Programs folder on the user's Start menu. Here you will create a DatabaseSnooper folder and add shortcut's inside it for your application, application help files, support website links, and any support documents included with your application.
We will add the EYE.ICO file to the Application Folder. Select the Application Folder item (as shown above) and click the OK button:
Now click on the Add File button to open a browser window and select the EYE.ICO file inside your DatabaseSnooper project folder. Your Select Item in Project dialog should then match the following illustration:
Click the OK button. Your Icon selection dialog should now match the following illustration, with the single EYE.ICO in the Current Icon pane. Click once on the icon to select it, this enables the OK button. Now click the OK button to close the dialog:
You should now see a new EYE.ICO file entry inside the SetupDatabaseSnooper project in the solution explorer window (as shown below):
Setting the other Properties of the SetupDatabaseSnooper project
Click once on the SetupDatabaseSnooper project in the solution explorer window to see it's properties in the properties window. The illustration below shows the complete list of a Deployment Project's properties:
Use the list above to guide you and add your own values for the following properties—Use some of my values in the illustration above if you need to, but make sure you enter values for all of the properties below:
- Author
- Description
- Manufacturer
- ManufacturerUrl
- Product Name
- SupportPhone
- SupportUrl
- Title—This is the title that will appear on the installation dialog during the setup process
- Version
Do not modify the ProductCode or UpgradeCode registry key values, these are generated for you, and will be different for every application you distribute. There are times when these values might need to be modified, but not for this exercise.
Using the File System Editor to configure your deployment package
With the SetupDatabaseSnooper project selected in the solution explorer window, click on the File System Editor button on the top left of the solution explorer window (circled below):
This displays the File System panes of the SetupDatabaseSnooper deployment project (as shown below):
I've described these folders before when we added the EYE.ICO file to the Application Folder for the AddRemoveProgramsIcon property. Now we will look at them one-by-one and in more detail as we add items to them.
Choosing Files for the Application Folder
Recall that the Application Folder is the folder where your application is installed on the user's computer. We need to include the DatabaseSnooper program and help files, and any readme.txt or support.txt files if they exist.
Open the Application Folder by clicking on it in the File System on Target Machine pane on the left side (as shown below). You should notice that this folder already contains the EYE.ICO file we added above, and several other items, like this:
Starting at the bottom, right-click on the Primary output from DatabaseSnooper item, and select Outputs from the context menu as shown below:
This displays the Outputs dialog which lists the DatabaseSnooper.exe file, this is the executable file produced earlier when we built the project:
Click the OK button to close it.
Adding the DatabaseSnooper Help file to the Application Folder
Right-click below the other items in the file pane of the Application Folder and select the File item under the Add menu as shown below:
This displays an Add Files browser window. Navigate to your DatabaseSnooper project folder and select the DatabaseSnooper.chm help file (as shown below), and click the Open button:
Now the file pane of the Application Folder should look like this and include the DatabaseSnooper.chm help file:
Adding the readme.txt file to the Application Folder
Right-click in the Application Folder's File pane again and select the File item under the Add menu one more time. Navigate to your DatabaseSnooper project folder and select the readme.txt that you just created and click the Open button to add it to the file pane. Now the file pane of the Application Folder should look like this:
The application folder for DatabaseSnooper—once it is installed on the user's computer—will now contain the DatabaseSnooper.exe program file, help file, readme.txt file, EYE.ICO file and the other items listed. When creating a Setup and Deployment Project, you are free to add other files if you wish—for example, a database file that your program uses, graphic files, mpeg files, etc. But for this project, these are all the files we will include.
Adding a Shortcut to the User's Desktop folder
Open the User's Desktop folder by clicking on it in the File System on Target Machine pane on the left side. To add a shortcut to the DatabaseSnooper.exe program file to the user's desktop, right-click on the files pane (as shown below) to display a context menu. Select the Create New Shortcut item:
This displays the Select Item in Project dialog. Note: We are only allowed to create shortcuts to files that are part of our installation package. With the Application Folder selected in the Look in window, click on the OK button (as shown below):
You should now see a list of the items we added to the Application Folder previously. Select the Primary output from DatabaseSnooper item and click the OK button (as shown below):
Renaming and setting an Icon for the Shortcut in the User's Desktop folder
Right-click on the new shortcut in the Files pane of the User's Desktop folder and select Rename from the context menu:
Change the name of the shortcut to Database Snooper. With the shortcut you just created selected, so that its properties are displayed in the properties windows, click on the drop-down arrow of the Icon property and choose the Browse item (as shown below):
This opens the Icon selection dialog. Click on the Browse button to display the Select Item in Project dialog. With the Application Folder item selected click the OK button to open it so that we can see the EYE.ICO file inside:
Select the EYE.ICO file and click the OK button. Your Icon selection dialog should now look like this:
Click on the icon to select it and enable the OK button then click the OK button. The EYE.ICO icon will now be applied to the shortcut to the program file that you've added to the User's Desktop folder.
Adding an Application Folder and Shortcuts to the User's Programs Menu folder
The User's Programs Menu represents the location on the user's computer inside the Programs folder on the Start menu. This is where we will create a DatabaseSnooper folder and fill it with shortcuts to our program files.
Open the User's Programs Menu folder by clicking on it in the File System on Target Machine pane on the left side. Now right-click in the files pane on the right side and select Folder under the Add menu item of the context menu, like this:
Change the name of the new folder from New Folder #1 to Database Snooper, as shown in the following illustration:
The Database Snooper folder needs shortcuts to the DatabaseSnooper program, help, and readme.txt files.
Open the DatabaseSnooper folder you just added to the User's Programs Menu folder by clicking on it in the File System on Target Machine pane on the left side. Right-click in the files pane on the right side and select the Create New Shortcut item on the context menu. Follow the steps we just took above to add a shortcut to the DatabaseSnooper application file to the desktop, and add shortcuts to these files from inside the Application Folder:
- Primary output from DatabaseSnooper
- DatabaseSnooper.chm
- readme.txt
The files pane of the DatabaseSnooper folder should now look like this:
Rename the above shortcuts and set their Icon properties as follows:
| Old Name | New Name | Icon Property |
| Shortcut to DatabaseSnooper.chm | Database Snooper Help | (don't set) |
| Shortcut to Primary output from DatabaseSnooper | Database Snooper | EYE.ICO |
| Shortcut to readme.txt | Read Me | (don't set) |
When you are finished, the shortcuts in the files pane of the Database Snooper folder—which is inside the User's Programs Menu folder—should look like this. Note: These files are sorted alphabetically and do not correspond to the order of the files in the first illustration above with their old names:
The Final step - Selecting the Type of Package to create
Right-click on the SetupDatabaseSnooper setup and deployment project in the solution explorer window and select the Properties menu item to display the SetupDatabaseSnooper Property Pages dialog, as shown:
Let's take a look at the options on this dialog:
- Configuration - Normally always set to Active(Release), which means it will include the Active project in the solution (DatabaseSnooper in this case), compiled in a Release format which will not include the Debug information that helps us trouble-shoot the project as we are creating it.
- Output file name - This is the name and location of the Microsoft Setup Information file (.msi). Leave this set to the default location and filename of Release\SetupDatabaseSnooper.msi. This is the Release folder inside the SetupDatabaseSnooper project. This is where the deployable package files will be created.
- Package Files - Lets you choose how the files will be packaged within
the Windows Installer file. The following options are available—we will use
the In Setup File option:
Option Description As loose uncompressed files The separate installation package files will be placed in the same directory as the .msi file and will not be compressed into archive files.
In setup file The installation package files will be compressed inside self-extracting archive files, for easy distribution. Note: This is the option you would select if you want to distribute your application over a network or via the internet.
In cabinet file(s) The installation package files will be compressed in one or more .cab files in the same directory as the .msi file. Note: This is the option you would select if you want to distribute your application on floppy diskettes.
- Compression - We usually set this to Optimized for Speed. The Optimized for Size option will compile the application in such a what that the executable file will be smaller, but the program may run slower. With the size of hard drives these days, running out of space is the least of your worries.
Without changing any of the default settings, click the OK button.
Building the Setup Package
Now we are ready to build our Setup Package for DatabaseSnooper. Save the project before going on. To build the Setup Package, right-click on the SetupDatabaseSnooper project in the solution explorer window, as shown:
Select the Build item on the context menu to start the build and keep your eye on the lower left corner of the window. When the build is complete, you should see this message:
Installing your finished DatabaseSnooper Application
Important: Before doing this step, be sure that you have administrator access to the computer your are using. If you are doing this project in the classroom, please tell me, and I will give you administrator privileges before going on.
Be sure to exit from Visual Studio 2008 for this next step. Now open the My Documents folder and navigate to the bin\Release folder inside your SetupDatabaseSnooper project folder. It's contents should look like this:
These are the installation files for DatabaseSnooper. You can send them to a friend and they can install your DatabaseSnooper program. They only need to run the Setup.exe program.
Double-Click the Setup.exe file now. After a moment, you should see the following Database Snooper Setup Wizard dialog:
Click on the Next button to see the Select Installation Folder dialog:
This dialog allows the user to choose the installation folder. Notice how the default location includes the value of the Manufacturer property of the SetupDatabaseSnooper project in the path, which in my example is Georgie Productions. Your installation path should include the value you specified for the Manufacturer property. The user can also select whether this installation should be available to All Users or only the current user who is installing it. Leave the default values unchanged and click the Next button.
A Confirm Installation dialog appears next. Click on the Next button to start the installation process. The Installing DatabaseSnooper dialog should display for a while during actual installation process (see the following illustration):
When the installation completes successfully you should see the Installation Complete dialog, which looks like this:
Click the Close button to close the Installation Complete dialog.
Checking what the Installation did
Once the DatabaseSnooper installation is complete, take a look at your Desktop. Is there a shortcut to DatabaseSnooper there?
Now click on the Start button and open the Programs menu. Do you see a new DatabaseSnooper folder? Does it contain shortcuts to the DatabaseSnooper program, help and readme.txt files, as shown below:
Now take a look inside the c:\Program Files\ folder. You should find a folder with the name of your Manufacture property (Georgie Productions in my case), and inside it is the DatabaseSnooper folder with your program files, as show below:
Viewing the Support Information, and uninstalling DatabaseSnooper
After you've finished testing your DatabaseSnooper installation, let's uninstall it. Make sure DatabaseSnooper is not running and open the control panel and run the Add/Remove Programs applet (Note: In Windows Vista choose the Uninstall a Program item). The list of programs that are installed on your computer will be different, but you should see the DatabaseSnooper program somewhere in the list, like this:
Click on the Click here for support information link (as shown above) so see the Support Info dialog. The information on this dialog is taken from several of the property settings we applied to the SetupDatabaseSnooper project:
Close the Support Info dialog. Now click the Remove button of the DatabaseSnooper application in the Currently Installed Programs list. You should see the following confirmation dialog. Note: Before clicking the Yes button, make sure the confirmation dialog is telling you that you are about to remove DatabaseSnooper from your computer. Do not accidentally remove the wrong program!
After clicking the Yes button, the uninstall process should take just a few seconds. After it's finished, make sure that all the files your DatabaseSnooper installation pack added to the computer were removed.
Creating a Setup and Deployment Package - A Summary
- Open the finished application project that you wish to distribute.
- Add a new Setup and Deployment project to the solution.
- Add an Icon to the finished application project and set the Icon properties of the forms, if you had not already done this previously.
- Set the AddRemoveProgramsIcon property of the Setup and Deployment project to the same Icon your finished application project uses. You will need to include the actual icon file in the Application Folder, so that is will be included with your installation package. Note: One common practice is to create a special ╪ (not) crossed-out version of the icon for this purpose.
- Set the properties of the Setup and Deployment project which
include:
- Author
- Description
- Manufacturer
- ManufacturerUrl
- Product Name
- SupportPhone
- SupportUrl
- Title
- Version
- Choose the files to be installed in the Application Folder of the user's computer.
- Create shortcuts to your installation files to be installed on the Desktop of the user's computer. Be sure to set the Icon property of shortcuts to your application to the same Icon file that the application uses. Note: Including a shortcut to your application on the desktop is optional.
- Add an application folder that contains short cuts to your installation files to the user's Programs folder on their Start menu. Note: Be sure to set the Icon property of shortcuts to your application to the same Icon file that the application uses.
- Select the type of Setup Package to be created via the property pages dialog of the Setup and Deployment project.
- Build the Setup Package.
- Deploy the the Setup Package files.