As a part of Branding within SSW, all the product installations should have a standard
layout. There is no point having one installation that has the SSW Logo and the
web site if none of the others follow suit.
The idea is that each product when the first installation is created should have
several items filled out by the programmer working on the product. Below is a list
of the current items that are required in the product installations.
-
Installation directories
To setup template for the Wise Installer for Windows:
- Copy SSWWindowsApplications.msi
from www.ssw.com.au/ssw/Standards/WiseSetup/WiseScript/SSW.msi
to you application's "Setup" folder.
This template will be used in conjunction with the Visual Build Pro script which
will be used to build release packages.
- Now we can create new setup with the standard template
Right-click the SSW.msi and choose "Edit in Wise editor".
Figure: Open file using the Wise editor.
- Go to the "File" Menu and "Save As...", then choose "Installer
Projects (*.wsi)" from the type combo as shown below, then name the file after
your solution file's name.
Figure: Save file as a wsi file.
This will prevent developers from keeping a template on their local drive rather
than always getting the latest template.
-
Copy the Product Code Across
This is very important if you are creating a new package for an existing product.
You also need to check the codes in the package that you get from Source Safe to ensure that they're the same as the previous released version.
If you do not copy the Product Code across from the old WSI file, your new package
will not be able to detect versions created with old Wise packages and will not
uninstall these older versions.
Copying the Product Code:
- Open the old WSI file.
- Select the Setup Editor.
- Click the Product Tab.
- Select Properties from the tree view.
- Copy the Product Code value.
- Paste the Product Code into your new WSI file.
- Repeat the process for the UpgradeCode.
- Repeat the process for the PackageCode (which is found in the Summary section).
-
-
Figure: The Product Code
-
Include all the files needed
Select "Files" on the left hand side and browse through to the folder
containing your release. Select the files you would like to add, and click 'Add
File'.
Make sure the directory structure in the bottom left is correct as needed on the
client computer.
The icon of the project should be set in the Application's exe.
-
-
Figure: Adding files to the package
The following files should NOT be included:
- *.scc;*.vspscc - Source Safe Files
- *.pdb - Debug Files
- *.user - User settings for Visual Studio .NET IDE
You can enforce these by adding those extensions to the Exclude Wildcard. Make sure
that the wildcards are similar to those in the application's old msi.
-
- Figure: Using Wildcards
-
- Figure:
Exclude wildcards
These files will automatically be removed on uninstall because Wise keeps a link
to each file that has been added above. However, if there are files that have been
added to the directory after the installation process, Wise will not have
the list of these files to remove. Therefore the RemoveFile operation needs to be
added to the list as shown below:
- In the Destination Files list, select the "Remove file" option from the "Operation"
button.
-
-
Figure: Specifying the "Remove File" Operation.
- In the dialog box, check the "All Files" checkbox and select "Uninstall" in the
"Remove During:" drop down list.
-
-
Figure: "Remove all files during uninstall".
- Click OK.
-
-
Figure: The "RemoveFile" operation is added to the file list.
-
Change the Default Directory
Once the files have been added, the directory will be available in the Directory
combo boxes throughout the wise installer.
- Go to the "Project Details" section from the left hand menu.
- Click the "Change" button and select the appropriate Program Files folder
that the product will be installed under.
Figure: Select the correct Default Directory
The merge module directory must now also be set if you want to use the components
than can't be packaged automatically.
- Go to the "Merge Module" section from the left hand menu, click "Add"
button to add modules
Figure: Add MFC component
- Set the destination directory of the component to install.
Figure: Install MFC component to System32 folder.
- The module is added. You can double click the module to edit its properties.
Figure: The MFC module is added to the installer.
-
Enter Add/Remove Program Information
Select "Add/Remove Programs" on the left hand side and enter information
that will show up in the Add/Remove Program Control Panel for Windows 2000/XP:
- Select the icon that will appear in the Add/Remove Program list.
There should be an ssw.ico for SSW products.
Note: You will need to add the files first before accessing the executable through
the 'browse..' button.
- Check "Hide modify button" if the product does not have multiple installation
features.
- Contact Person should be the current head developer for the application.
- Help URL should reference product's Online User Guide
Example: /ssw/CodeAuditor/UserGuide.aspx
Figure: Add/Remove Program entry page
Figure: What it will look like in Add/Remove Control Panel
-
Add Shortcuts
Enter Shortcut setting that will appear in the Start | Program Menu
- Destination Directory will be suffixed with version so product version can be checked
at a glance without executing the application. This will be handled by Visual Build
PRO.
- Prefix Name of each item with a number so sorting can be controlled. Main executable
should start with 1 so it will appear at the top.
- Click 'Add'.
- Click 'Next'.
- Select the main executable to be put in your installation package.
- Click 'Next'
- Expand the 'Programs' node and select the '[ProductName]' folder, then click Ok
- Change the name of the Shortcut as shown in Figure1.
- Select the icon.
- Look at the disabled "Icon Number" and remember the icon number value.
- Uncheck "Advertised" checkbox and enter the icon number value in the "Icon
Number" textbox.
- Click OK.
Note: If you remove the file from the wise package that is associated with the shortcut,
the shortcut will also be removed.
Figure 1: Make sure the shortcut name is "1. [ProductName]" and select
the icon by clicking "New Icon" button.
- Change the component reference in the Shortcut Tables.
- Select "Setup Editor" on the bottom left panel
- Select "Tables" tab on the top left panel
- Select the "Shortcuts" table on the left panel list (as shown in Figure
2)
- Change all the "Components_" column to be the same as the Executable.
(as shown in Figure 3)
Figure 2: The default way in which the "Shortcuts" table has different
references to the "Component_" key. This will not allow the _Update and
_Uninstall shortcut to be removed from the start menu on uninstall.
Figure 3: A better way of allowing shortcuts to be removed on uninstall is to have
the component references the same as the shortcut of the executable file.
- Technical Note: (this step is not required) Destination Directory are
stored in the Directory Table. This should generally be left as it is since Visual
Build PRO will update the DefaultProgramMenu directory name.
If there is an exception to changing it from the standard naming system (which I
doubt will be the case, then refer to Figure 4 to access the Directory Table):
- Select Setup Editor on the bottom left panel
- Select Tables tab on the left panel
- Select Directory on the left panel list
- Select Row with DefaultProgramMenu on the main panel
Figure 4: Add Shortcuts that appears in Start Menu
Figure 5: Modify DefaultProgramMenu to change Shortcuts destination
Figure 6: This is how it should look in Start Menu
-
Remove Unnecessary System Searches
The Wise Template includes all the possible system searches for all SSW's products.
This makes it easier to remove the registry key searches that specific applications
do not need, rather than adding them individually and having to spend those extra
few minutes to find the registry keys required per application.
If the system searches are not removed, the first dialog of the wizard takes a long
time to load.
Figure: Wise dialog taking a long time to finish searching the system.
In the wise file that has been copied over to the specific Setup folder, remove
all the system searches you do not need.
Figure: Select unneeded system searches and click "Delete"
-
Remove Assembly Dependency Check
Make sure the Wise File does not scan for dependencies.
This makes sure that the Build Script does not include the dependencies (especially
moving dll's into the GAC of the destination machine), which was not initially specified.
The reason why we turn the scanning for dependencies off is for the following:
- Usually the assemblies that wise wants to add, are the ones that the developer doesn't
want to add. When you tell it no it asks for every subsequent build.
- The additional scanning takes time, and sometimes a lot of time.
- Not being able to build wise and just walk away and come back later the dialog demands
user interference.
eg. In Smart Salary, because the job was an upsize job there was a lot of interop
libraries that WISE insisted that we must have. Clicking through 10+ screens to
ignore the add-reference dialog got really tedious.
- The build script will automatically add them when running in silent mode.
Trade off:
- Obviously, if WISE doesn't scan for dependencies, then when you add new components,
you may forget to add them to your setup project. However, if you forgot to add
a component to setup, this is usually very quickly caught in testing the application,
and the fix is relatively simple as well. This simple trade off is worth all the
hassle of having it on.
Steps to remove Assembly Dependency scanning:
- Goto Tools -> Options.
- Make sure the "Never Scan Dependencies" is selected in the "Scan
Dependencies" drop down.
- Make sure the "Rescan assembly dependencies on compile" and "Rescan
assembly attributes on compile" are both unchecked.
- You can also uncheck the "Rescan for COM interop registry keys on compile",
and select ".Net Application" in the drop down.
- Click OK.
Figure: Bad
Figure: Removing the assembly dependency checks for every compile - Good
-
Modify Custom Actions
The SSW Template provides an existing number of custom actions used for standardizing
the installation package. However the custom actions need to be specified for each
application.
There are only two custom actions that need to be modified and can be done by following
the below steps:
- Click the MSI Script Tab (found in the bottom Tab control of the Wise environment)
- Select "All Custom Actions" from the pull down combo box as shown below.
Figure: Select "All Custom Actions"
- Select the "LaunchApplicationAction" from the list of actions as shown
below.
Figure: Select the "LaunchApplicationAction" Custom Action
- Double click the custom action and modify the exe to be that of your application's
.exe.
Figure: Modify the 'LaunchApplicationAction' to point to the application's exe by
browsing the destination files.
- Do the same for the "LaunchDocAction" so that it points to the specific
application's User Guide.
Figure: Modify the 'LaunchDocAction' to point to the application's UserGuide URL.
- Save the .wsi file
The other steps are optional. After the wise file has been saved and checked
for correctness, the next step would be to get the Visual Build template from the
following link:
Template for Visual
Build PRO can be found here.
-
Launch Program and View Documentation options on Exit
Dialog
On Exit Dialog, we must include Run Program, Open Online User Guide and Run SSW
Diagnostics.
SSW Diagnostics helps our developer to analyze your problem by collecting information
about your system. This application will collect that information and then email
it to our developers, you may view the information before you send it if you wish.
Now to configure scripts to provide this capability:
- Select Setup Editor from bottom tab
- Select Dialogs from the side panel tab
- Select Exit Dialog from the side panel
- Double click each checkbox and check that the property is set correctly
Figure: Configuring Exit Dialog to support Autorun
- Double click the Finish button and set the Events to run program after installation.
Figure: Configuring Finish button
For more information on
Versioning Standards please follow this link.
-
Register and UnRegister Assemblies (DLL) for Com-Interop
Projects
If you are building a setup for a Com-Interop project, some information needs to
be added to the registry so that your DLL can be called as though they were COM
components.
Make sure that the "Application Type" in WISE is configured as either
a .NET Application or MIXED, because otherwise (obviously enough) WISE will not
let you register the Assembly.
Figure: Make sure the "Application Type" in WISE is configured to .NET
Application or MIXED
To configure WISE to register the Assembly, in the Installation Expert, under the
Feature Details Tab on the left hand side, select "Files" and double click
the DLL that you want to register.
Figure: Double click the assembly file you want to register
In the dialog box that pops up, enter the following details under the "self-registration"
tab
Figure: Configure 'Self-registration' for assembly
Make sure you have "Use order specified below" selected in the drop down
and that you check the "Generate COM interop registry keys for .NET assembly"
at the bottom of the dialog window.
After doing that, WISE will create all the registry keys that are required to properly
register the DLL for a COM-interop project. You can verify that by looking at the
registry keys added to the destination computer under WISE
Figure: Wise will generate all necessary registry keys for register the DLL
Compile and test your project.
When you uninstall the product, WISE will take care of unregistering the Assembly
for you by removing the registry keys it created during install.
-
Apply theme to installation dialogs
You can change the look of installation dialog boxes with theme. You can add/edit the images, texts Wise 7 offers some standard themes in "Dialogs".
Figure: Select theme.
You can also edit those standard themes.
Figure: Edit theme.
We do have our standard for the look of dialogs during installation. Check the user guide.
To customize the dialogs, we need to go to Setup Editor | Dialogs to edit.
Figure: Customize dialog
Note: If the installation file is created by previous Wise, like Wise 5, we will find the "none" option in the default theme. Please make sure that the default theme is set to be "NONE" if you have ever created customized dialog. Otherwise, the dialog box customization will be lost.
Figure: Set the default theme to "none"
Figure: dialog customization is lost.
-
Generate both EXE and MSI packages from Wise Installer
Nowadays the exe package is more commonly use, for example some of the famous software
download websites, they are hosting files on voluntary ISP around the world, some
of them don't have the MIME types setup for MSI, however EXE is widely accepted.
EXE provides upgrade feature which will allow user to uninstall old version automatically,
it's very handy for end users. However, MSI can be opened in WISE studio directly,
so it's very handy for developers to analyze the content. Therefore, they both have
pro and cons and we provide both version.
Figure: Generate MSI package only(Bad)
Figure: Generate both EXE and MSI packages and prompt use for uninstalling old version
(Good)
This will ensure WISE generating EXE as well as MSI packages for your product.
Make sure you tick 'Prompt to remove previous version before installing' checkbox,
and update the prompt message in 'Property' table. The reason for this is because
our Visual Build will include the product version in our product name, so if you
don't do this, the prompt message will be very confusing.
Figure: Default Wise warning message for uninstalling old version (Bad)
Figure: Modified Wise warning message for uninstalling old version (Good)
To change this, go to the 'Property' table in wise, and change the 'WiseInitExistError'
property's value to
Old version detected.
You are trying to install %s; however version %s is already installed on your computer.
You must uninstall the existing version before continuing.
Do you want to uninstall the existing version?
|
Tip: To add a line break before the last sentence, you can write this message in
'Word' first and copy paste into wise.
Figure: Update the default warning message in Wise table
When you use Visual Build to build the product and deploy it on our servers, please
make sure you upload both the MSI and EXE.
-
Some special features for Vista
Vista is totally different from other OS of Microsoft. It has special system folder architecture and security mechanism.
Wise 7 can support Vista very well. There are some special features designed for Vista. If you want to build the product compliant with Vista, please take care of the following settings.
-
"AllUsers" is a hidden property in the property table, setup editor. Its default value is 0 - that means the software will be installed per user.
This value should be set to 2 - the files (e.g. the shortcuts) will be installed according to user access level:
for standard user access privileges, the files are stored in folders under the user's personal profile;
for administrator access privileges, the files are stored in folders under "All Users" profile. (in Vista, it is "ProgramData" folder)
- Figure: Set the "ALLUSERS" property
-
In "Windows Installer Options", you can set to enable/disable the UAC (User Account Control) during the installation. This configuration does not mean you can open or close UAC in Vista.
In fact, enable this will make the installer to try to elevate privilege while it is writing files to protected area.
e.g. When you try to do a per machine installation, you will need to write files to "ProgramData" folder, or add registry keys to "HKEY_LOCAL_MACHINE". If you do not enable this, the installation process will fail because you may not have administrator privileges to do so.
- Figure: Installer Options
-
If you want to create new template by Wise 7, be careful of "Create a Vista Standard User Installation" checkbox. Enable this will make the installation only has standard user access privileges and can't operate on any protected files.
- Figure: Create a new template
-
Run 'SSW Diagnostics' after installation (Recommend)
It's recommend to run 'SSW Diagnostics' after SSW product's installation, so we
include this option in our installation package
Figure: It's recommended to tick run SSW Diagnostics
after the installation
Make sure you point the link to the correct
address, we have 2 redirect files in our redirect folder:
-
Do you have a 'Systems Requirements' screen when
installing a product?
Installing a product should be easy and fuss free! If your product requires other
programs to be installed, for example the Microsoft .NET Framework, I find it is
best to include a 'Systems Requirements' screen where the user can click the
links provided and install the required programs and then continue with the installation
of your product. If your installation exits prematurely due to not having the required
programs installed, the user can get frustrated - make life easy for them!
Figure: Installation Prerequisites Screen
However, sometime it's very hard to detect the required software in user environment,
eg. a database server on the network. In such cases, you should still include the
required software on other screen to warn your user. At least let them know what
they are going to need to run your application.
Figure: Installation Prerequisites (Optional) Screen