⚠️ This page has been archived

✅ New page with updated info: ssw.com.au

Home > Archive > SSW Standards > Wise Setup > SSW's Wise Standard for Products

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.

This is a standard WISE Installation Script file (to make an .msi). You will need WISE for Windows Installer to open it.
Note: This document has been updated to Wise 7.

To see the standard on how to release a version see http://www.ssw.com.au/ssw/Standards/WiseSetup/ReleasingAVersion.aspx

SSW's Wise Enterprise Standard for Products
  1. Installation Directories
  2. Copy the Product Code Across
  3. Include all the files needed
  4. Change the Default Directory
  5. Enter Add/Remove Program Information
  6. Add Shortcuts
  7. Remove Unnecessary System Searches
  8. Remove Assembly Dependency
  9. Modify Custom Actions
  10. Launch Program and View Documentation options on Exit Dialog
  11. Register and UnRegister Assemblies (DLL) for ComInterop Projects
  12. Apply theme to installation dialogs
  13. Generate both EXE and MSI packages from Wise Installer
  14. Some special features for Vista
  15. Run 'SSW Diagnostics' after installation (Recommend)
  16. Do you have a 'Systems Requirements' screen when installing a product?
  1. Installation directories

    To setup template for the Wise Installer for Windows:

    1. 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.

    2. 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.

    3. 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.


  2. 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:

    1. Open the old WSI file.
    2. Select the Setup Editor.
    3. Click the Product Tab.
    4. Select Properties from the tree view.
    5. Copy the Product Code value.
    6. Paste the Product Code into your new WSI file.
    7. Repeat the process for the UpgradeCode.
    8. Repeat the process for the PackageCode (which is found in the Summary section).

    Figure: The Product Code

  3. 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.

    wildcard
    Figure: Using Wildcards

    wildcard-details
    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:

    1. In the Destination Files list, select the "Remove file" option from the "Operation" button.
      destination operation
      Figure: Specifying the "Remove File" Operation.
    2. In the dialog box, check the "All Files" checkbox and select "Uninstall" in the "Remove During:" drop down list.
      Remove File Properties
      Figure: "Remove all files during uninstall".
    3. Click OK.
      Remove File Operation
      Figure: The "RemoveFile" operation is added to the file list.
  4. Change the Default Directory

    Once the files have been added, the directory will be available in the Directory combo boxes throughout the wise installer.

    1. Go to the "Project Details" section from the left hand menu.
    2. 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.

    1. Go to the "Merge Module" section from the left hand menu, click "Add" button to add modules


      Figure: Add MFC component

    2. Set the destination directory of the component to install.


      Figure: Install MFC component to System32 folder.
    3. The module is added. You can double click the module to edit its properties.


      Figure: The MFC module is added to the installer.

  5. 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:

    1. 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.

    2. Check "Hide modify button" if the product does not have multiple installation features.

    3. Contact Person should be the current head developer for the application.

    4. Help URL should reference product's Online User Guide
      Example: /ssw/CodeAuditor/UserGuide.aspx

      Wise Add remove
      Figure: Add/Remove Program entry page


      Figure: What it will look like in Add/Remove Control Panel
  6. Add Shortcuts

    Enter Shortcut setting that will appear in the Start | Program Menu

    1. 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.

    2. 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.

      Add shortcut
      Figure 1: Make sure the shortcut name is "1. [ProductName]" and select the icon by clicking "New Icon" button.

    3. 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.

    4. 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

    5. Shortcuts page
      Figure 4: Add Shortcuts that appears in Start Menu

      Table directory page
      Figure 5: Modify DefaultProgramMenu to change Shortcuts destination


      Figure 6: This is how it should look in Start Menu


  7. 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"


  8. 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:

    1. Goto Tools -> Options.
    2. Make sure the "Never Scan Dependencies" is selected in the "Scan Dependencies" drop down.
    3. Make sure the "Rescan assembly dependencies on compile" and "Rescan assembly attributes on compile" are both unchecked.
    4. You can also uncheck the "Rescan for COM interop registry keys on compile", and select ".Net Application" in the drop down.
    5. Click OK.


      Figure: Bad


      Figure: Removing the assembly dependency checks for every compile - Good


  9. 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:

    1. Click the MSI Script Tab (found in the bottom Tab control of the Wise environment)
    2. Select "All Custom Actions" from the pull down combo box as shown below.

      Figure: Select "All Custom Actions"
    3. Select the "LaunchApplicationAction" from the list of actions as shown below.

      Figure: Select the "LaunchApplicationAction" Custom Action
    4. 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.
    5. 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.
    6. 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.

  10. 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:
    1. Select Setup Editor from bottom tab
    2. Select Dialogs from the side panel tab
    3. Select Exit Dialog from the side panel
    4. Double click each checkbox and check that the property is set correctly


      Figure: Configuring Exit Dialog to support Autorun

    5. 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.

  11. 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.

  12. 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.

  13. 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.

  14. 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.
    1. "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
    2. 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
    3. 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
  15. Run 'SSW Diagnostics' after installation (Recommend)

  16. 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:

    http://www.ssw.com.au/ssw/Redirect/SSWDiagnostics.aspx - this point to SSW Diagnostics website
    http://www.ssw.com.au/ssw/Redirect/SSWDiagnostics.asp - this point to the latest version of SSW Diagnostics

    You should use the aspx one for redirect user to SSW Diagnostics website.

  17. 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

Acknowledgements

John Prince
Mark Liu
John Liu - 11 Feb 2002
Sergei Tchernykh - 07 May 2002
Ashraf Moollan - 05 May 2004
Adel Helal - 14 Dec 2005
Brite Cheng - 26 Mar 2008