Windows Installer Editor Reference

Transcript

Windows Installer Editor Reference Legal Notice The software described in this document is furnished under a license agreement and may be used only in accordance with the terms of the agreement. Windows Installer Editor (Wise Package Studio 7.0 SP3) Copyright © 1994-2008 Symantec Corporation. All Rights Reserved. Symantec, the Symantec Logo, Altiris, and any Altiris and Symantec trademarks used in the product are trademarks or registered trademarks of Symantec Corporation or its affiliates in the U.S. and other countries. Other names may be trademarks of their respective owners. The product described in this document is distributed under licenses restricting its use, copying, distribution, and decompilation/reverse engineering. No part of this document may be reproduced in any form by any means without prior written authorization of Symantec Corporation and its licensors, if any. THE DOCUMENTATION IS PROVIDED “AS IS” AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID. SYMANTEC CORPORATION SHALL NOT BE LIABLE FOR INCIDENTAL OR CONSEQUENTIAL DAMAGES IN CONNECTION WITH THE FURNISHING, PERFORMANCE, OR USE OF THIS DOCUMENTATION. THE INFORMATION CONTAINED IN THIS DOCUMENTATION IS SUBJECT TO CHANGE WITHOUT NOTICE. The Licensed Software and Documentation are deemed to be commercial computer software as defined in FAR 12.212 and subject to restricted rights as defined in FAR Section 52.227-19 “Commercial Computer Software - Restricted Rights” and DFARS 227.7202, “Rights in Commercial Computer Software or Commercial Computer Software Documentation”, as applicable, and any successor regulations. Any use, modification, reproduction release, performance, display or disclosure of the Licensed Software and Documentation by the U.S. Government shall be solely in accordance with the terms of this Agreement. ConflictManager® is protected by U.S. Patent No. 7,028,019. Symantec Corporation 20330 Stevens Creek Blvd. Cupertino, CA 95014 http://www.symantec.com Altiris, Inc. 47911 Halyard Dr. Plymouth, MI 48170 http://www.altiris.com Windows Installer Editor Reference 2 Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Technical Support Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Chapter 1: Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 About Windows Installer Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Starting the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Product Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Installation Expert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About Page Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing Page Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Current Feature Drop-Down List. . . . . . . . . . . . . . . . . . . . Using the Current Release Drop-Down List . . . . . . . . . . . . . . . . . . . Using the Task List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Filtering the Task List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Finding Table Errors From the Task List. . . . . . . . . . . . . . . . . . . . . . Adding User-Defined Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Generating Shared Resource Reports . . . . . . . . . . . . . . . . . . . . . . . Installation Resources and Their Locations . . . . . . . . . . . . . . . . . . . . . . Generating Package Contents Reports. . . . . . . . . . . . . . . . . . . . . . . . . . Downloading Redistributable Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . Downloading Redistributables From the Wise Web Site or Product CD . Downloading Redistributables From Other Vendors’ Web Sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 16 17 18 20 21 22 23 24 25 26 26 27 27 28 29 29 30 Chapter 2: Setting Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 How you can set up Windows Installer Editor . . . . . . . . . . Setting Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting General Options . . . . . . . . . . . . . . . . . . . . . Setting .NET Assembly Options . . . . . . . . . . . . . . . . Setting Advertising Options . . . . . . . . . . . . . . . . . . . Setting Digital Signature Options . . . . . . . . . . . . . . . About ExpressBuild . . . . . . . . . . . . . . . . . . . . . . . . . Setting ExpressBuild Options . . . . . . . . . . . . . . . How ExpressBuild Groups Work . . . . . . . . . . . . . Requirements for Using ExpressBuild . . . . . . . . . Setting Installation Expert Options . . . . . . . . . . . . . . Setting Merge Module Directories . . . . . . . . . . . . . . . Activating Suppressed Prompts . . . . . . . . . . . . . . . . Setting Repository Options . . . . . . . . . . . . . . . . . . . Setting Source Control Options . . . . . . . . . . . . . . . . Setting Wildcard Groups . . . . . . . . . . . . . . . . . . . . . Creating and Editing Installation Templates . . . . . . . . . . . Component Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About Component Rules . . . . . . . . . . . . . . . . . . . . . Selecting a Component Rule Set. . . . . . . . . . . . . . . . Using Component Rules to Align GUIDs in an Upgrade Windows Installer Editor Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 32 33 34 36 37 38 39 40 40 41 42 43 44 45 46 47 48 49 50 51 3 Customizing Component Rules . . . . . . . . . . . Adding and Editing Component Rules . . . Microsoft Best Practices Component Rule Set . One File Per Component Rule Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 53 55 56 Chapter 3: Working With Wise Installation Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Before You Create an Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . File Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Project Files and Database Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Target Platforms: 32-bit and 64-bit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to Specify the Target Platform . . . . . . . . . . . . . . . . . . . . . . . . . What’s Different in a 64-bit Installation? . . . . . . . . . . . . . . . . . . . . . . 32-bit Applications on 64-bit Computers . . . . . . . . . . . . . . . . . . . . . . Guidelines for Creating Platform-Specific Installations. . . . . . . . . . . . . Creating Multiple, Platform-Specific Installations from One Project File . Defining the INSTALLDIR Property in a Mixed-Platform Installation. Starting a New Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About Standard User Installations . . . . . . . . . . . . . . . . . . . . . . . . . . Creating an Installation for Standard Users . . . . . . . . . . . . . . . . . . . . Creating a Device Driver Installation. . . . . . . . . . . . . . . . . . . . . . . . . Options for New Installations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Opening an Installation Package. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Comparing Windows Installer Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Saving an Installation as XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working With Installations in the Software Manager Database . . . . . . . . . . Compiling An Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing and Running An Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing An Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running An Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 59 60 61 62 62 64 65 66 68 69 70 70 71 72 73 74 76 76 77 79 79 80 Chapter 4: Defining an Installation Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Project Summary Page . . . . . . . . . . . . . . . . . . . . . . . . . . Product Details Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding Meta Data to the Software Manager Database . . Incrementing the Product Version. . . . . . . . . . . . . . . . Setting the Default Installation Directory. . . . . . . . . . . General Information Page . . . . . . . . . . . . . . . . . . . . . . . . Add/Remove Programs Page . . . . . . . . . . . . . . . . . . . . . . Features Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Strategies for Organizing Files Into Features . . . . . . . . Adding a New Feature . . . . . . . . . . . . . . . . . . . . . . . . Configuring a Feature Using Its Drop-Down List . . . . . . Configuring a Feature Using the Feature Details Dialog . Using Conditions With Features . . . . . . . . . . . . . . . . . Adding and Deleting Feature Conditions . . . . . . . . . . . Managing Binary Resources . . . . . . . . . . . . . . . . . . . . . . . Adding Binary Resources . . . . . . . . . . . . . . . . . . . . . . Refreshing Binary Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 . 83 . 86 . 87 . 88 . 89 . 89 . 90 . 92 . 94 . 95 . 96 100 101 101 103 103 Chapter 5: Assembling an Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 Files or Web Files Page . . . . . . . . . . . . . . . . . . . . . . . . . . When to Use the File-Related Installation Expert Pages . Installation Directories . . . . . . . . . . . . . . . . . . . . . . . Files or Web Files Page Icons . . . . . . . . . . . . . . . . . . . Windows Installer Editor Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 107 108 109 4 Adding Files to an Installation . . . . . . . . . . . . . . . . . . . . . Adding Merge Modules Instead of Files . . . . . . . . . . . . . . . Adding Files From the Wise Software Repository . . . . . . . . Adding Contents of Directories to the Installation . . . . . . . . Adding .NET Assemblies to the Installation . . . . . . . . . . . . How Assembly Dependencies are Added to an Installation. . Assembly Dependencies . . . . . . . . . . . . . . . . . . . . . . About Dependency Scan Exclusions . . . . . . . . . . . . . . About the Global Dependency Exclusion List . . . . . . . . Editing Settings for Automatic Updating . . . . . . . . . . . . . . Removing a File From the Destination Computer . . . . . . . . Copying and Moving Files on the Destination Computer. . . . Editing File Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing General File Details . . . . . . . . . . . . . . . . . . . . Setting Permissions for Files and Directories . . . . . . . . Editing Self-Registration Settings for Files . . . . . . . . . . Editing Assembly Settings for Files . . . . . . . . . . . . . . . Creating a Win32 Assembly . . . . . . . . . . . . . . . . . . . . Viewing Shared File Resources . . . . . . . . . . . . . . . . . . Editing XML Files During Installation . . . . . . . . . . . . . . Editing DIFxApp Options . . . . . . . . . . . . . . . . . . . . . . How Self-Registration Information is Captured . . . . . . . . . . Using WiseComCapture.exe . . . . . . . . . . . . . . . . . . . . Resolving File Conflicts Within Windows Installer Editor. . . . . . . Resolving Conflicts With Rules in Windows Installer Editor . . Resolving Conflicts Individually in Windows Installer Editor . Registry Page. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding Registry Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . Removing Registry Entries From the Destination Computer . Importing and Exporting Registry Entries . . . . . . . . . . . . . Configuring General Registry Settings . . . . . . . . . . . . . . . . Setting Permissions for Registry Keys . . . . . . . . . . . . . . . . Viewing Shared Registry Resources . . . . . . . . . . . . . . . . . Special Registry Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . INI Files Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating and Editing .INI Files . . . . . . . . . . . . . . . . . . . . . Shortcuts Page. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding a Shortcut to an Installation . . . . . . . . . . . . . . . . . Editing a Shortcut Configuration . . . . . . . . . . . . . . . . . . . . Adding an Environment Variable. . . . . . . . . . . . . . . . . . . . . . . Adding File Associations . . . . . . . . . . . . . . . . . . . . . . . . . . . . Determining Extension Settings . . . . . . . . . . . . . . . . . . . . Adding Command Verbs . . . . . . . . . . . . . . . . . . . . . . . . . Selecting MIME Types . . . . . . . . . . . . . . . . . . . . . . . . . . . Services Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding a Service to the Destination Computer . . . . . . . . . . Controlling Services on the Destination Computer . . . . . . . Adding an ODBC Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting ODBC Data Source Details . . . . . . . . . . . . . . . . . . Setting ODBC Driver Details . . . . . . . . . . . . . . . . . . . . . . Setting ODBC Translator Details . . . . . . . . . . . . . . . . . . . . Adding to the Windows Firewall Exception List . . . . . . . . . . . . . Windows Installer Editor Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 112 113 114 115 116 117 117 118 119 120 122 123 124 125 126 127 128 130 131 132 133 133 134 135 136 138 140 142 143 144 146 147 147 147 148 149 150 151 152 153 154 155 156 156 156 158 159 160 160 161 161 5 Chapter 6: Your Installation on the Destination Computer . . . . . . . . . . . . . . . . . . . . . 164 About System Requirements . . . . . . . . . . . . . . . . . . . . . . . . Setting a Requirement on the System Requirements Page. Setting a Requirement by Creating a Launch Condition . . . Performing a System Search . . . . . . . . . . . . . . . . . . . . . . . . Searching For Files or Directories . . . . . . . . . . . . . . . . . . Searching For Items in .INI Files . . . . . . . . . . . . . . . . . . Searching For a Registry Value. . . . . . . . . . . . . . . . . . . . Searching For a Previously-Installed Component . . . . . . . Setting Version-Specific Windows Installer Options . . . . . . . . . About UAC Elevation of Windows Installer Installations . . . About UAC Elevation of an Entire Installation . . . . . . . . . . Setting Features for Installation Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 164 166 167 168 169 171 172 174 176 178 179 Chapter 7: Organizing Your Installation Into Releases . . . . . . . . . . . . . . . . . . . . . . . . 181 About Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a New Release. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Outputting a Multiple-Language Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing a Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing Properties for a Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing Summary Items for a Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining a Feature and Component Set for a Release . . . . . . . . . . . . . . . . . . . . . . . Sharing Settings Between Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example: Creating an Evaluation Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Build Options for a Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About the Installation of an .MSI into an SVS Layer . . . . . . . . . . . . . . . . . . . . . . . . About the Exclusion of Files on the Build Options Page . . . . . . . . . . . . . . . . . . . . . . About Maintenance of an .MSI Installed into an SVS Layer . . . . . . . . . . . . . . . . . . . Adding Prerequisites to a Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding a Windows Installer or .NET Framework Runtime. . . . . . . . . . . . . . . . . . . . . Adding a Prerequisite File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding a Runtime Prerequisite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing the WiseScript That Creates the Installation .EXE . . . . . . . . . . . . . . . . . . . . Creating Web-Based Installations With WebDeploy . . . . . . . . . . . . . . . . . . . . . . . . . . . . The WebDeploy Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tips for Creating an Efficient WebDeploy Installation . . . . . . . . . . . . . . . . . . . . . . . Creating a WebDeploy Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Uploading a WebDeploy Installation to the Web . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up Media for Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding a Media Item. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding a Media Destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Including Features and Components in Media Items . . . . . . . . . . . . . . . . . . . . . . . . Sharing Media Settings Between Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example: Spanning an Installation Across Media and Sharing Media Size Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 182 184 185 186 186 187 188 189 190 192 193 194 195 195 197 199 200 201 203 204 204 206 207 208 210 211 212 213 Chapter 8: Advanced Installations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 About the Mobile Devices Page. . . . . . . . . . . Process for Adding Mobile Device Support About Windows Mobile Installations . . . . Adding Windows Mobile Files . . . . . . About Palm OS Installations. . . . . . . . . . Adding Palm OS Files . . . . . . . . . . . Setting Administrator Options . . . . . . . . . . . Specifying Search Locations. . . . . . . . . . . . . Windows Installer Editor Reference ............. to an Installation ............. ............. ............. ............. ............. ............. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 216 216 217 219 220 222 224 6 Setting Options for an Administrative Installation . . . . . . . . . . . . About Command Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Command Line To Apply to an Installation . . . . . . Applying UI Options to an Installation . . . . . . . . . . . . . . Applying Logging Options to an Installation . . . . . . . . . . Applying an Advertising Option to an Installation . . . . . . Applying a Repair Option to an Installation . . . . . . . . . . Changing Public Properties in an Installation . . . . . . . . . Applying Transforms to an Installation . . . . . . . . . . . . . Applying or Removing Patches With a Command Line . . . Command Line Options For WFWI.EXE . . . . . . . . . . . . . . . . WFWI.EXE Command Line Option Example . . . . . . . . . . Automating the Build Process. . . . . . . . . . . . . . . . . . . . Adding a Digital Signature to an Installation . . . . . . . . . . . . . . . Creating an Installation for Microsoft SMS . . . . . . . . . . . . . . . . . Creating a .NET Installation When You Have the .NET Framework Creating a .NET Installation Without the .NET Framework . . . . . . About Web Installations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Features That Support Web Installations . . . . . . . . . . . . . . . Creating a Web Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Virtual Directory . . . . . . . . . . . . . . . . . . . . . . . . Creating a New Web Folder . . . . . . . . . . . . . . . . . . . . . . . . Setting Installation Options for a Web Installation . . . . . . . . Setting Installation Options for a Child Virtual Directory . . . . About the Web Site Details Dialog . . . . . . . . . . . . . . . . . . . Installing Web Settings From a File. . . . . . . . . . . . . . . . . . . Configuring a Microsoft SQL Server During Installation . . . . . . . . Tips for Using the SQL Server Scripts Page . . . . . . . . . . . . . Setting SQL Connection Strings . . . . . . . . . . . . . . . . . . . . . Specifying SQL Statements . . . . . . . . . . . . . . . . . . . . . . . . Specifying Replacements in SQL Statements . . . . . . . . . . . . Importing .NET Framework Security Settings. . . . . . . . . . . . . . . MTS/COM+ Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding an MTS or COM+ Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 226 227 229 230 231 232 233 234 234 235 236 237 237 238 239 240 242 243 244 246 248 249 250 252 253 254 255 256 256 258 258 260 260 Chapter 9: Translating an Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 About the Languages Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Translated .MSI . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Language Transform . . . . . . . . . . . . . . . . . . . . . . . Sharing Language Settings Between Releases . . . . . . . . . . . . . Removing a Language from an Installation . . . . . . . . . . . . . . . Defining and Translating Into Additional Languages . . . . . . . . . . . . About the New Language Wizard . . . . . . . . . . . . . . . . . . . . . . Defining a New Language and Exporting All Text for Translation Importing All Text Strings After Translation . . . . . . . . . . . . . . . Importing All Text Strings With the New Language Wizard . . . . Translating Text Strings You Have Added or Changed . . . . . . . . . . . Translating Text Strings by Exporting to a File . . . . . . . . . . . . . Exporting Selected Text Strings to a File . . . . . . . . . . . . . . Importing Selected Text Strings From a File . . . . . . . . . . . Translating Text Directly Without Exporting It . . . . . . . . . . . . . Translating Text on the Language Strings Dialog . . . . . . . . Changing Text in Installation Expert and Setup Editor . . . . . Resizing Dialog Controls After Translation . . . . . . . . . . . . . . . . . . . Windows Installer Editor Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 265 266 267 268 269 270 271 272 273 275 275 276 277 278 278 279 280 7 About the Language Menu . . . . . . . . . . . . . . . Changing the Default Language . . . . . . . . About the Default Release Language. . . . . About the Language Strings Dialog . . . . . . . . . Keeping Track of Changed Text Strings . . . What Pre-Translated Languages Are Available?. Language IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 281 282 283 283 284 285 Chapter 10: Distributing an Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 Package Distribution . . . . . . . . . . . . . . . . . . . . . . . . . WiseUpdate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The WiseUpdate Process . . . . . . . . . . . . . . . . . . . Using WiseUpdate in an Installation . . . . . . . . . . . Configuring the WiseUpdate Page . . . . . . . . . . About the WiseUpdate Update File . . . . . . . . . Customizing the WiseUpdate Dialog Boxes. . . . Uploading WiseUpdate Files With an FTP Client Testing WiseUpdate . . . . . . . . . . . . . . . . . . . Options for Running WiseUpdate Client . . . . . . . . . WiseUpdate Tips. . . . . . . . . . . . . . . . . . . . . . . . . Troubleshooting WiseUpdate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 287 289 290 290 292 293 294 294 295 296 297 Chapter 11: Upgrading Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299 About Upgrading Applications . . . . . . . . . . . . . . . . . Preparing for Software Updates . . . . . . . . . . . . . . . . Archive the Shipping Version of the .MSI. . . . . . . Determine the Form of the Update . . . . . . . . . . . Determine the Product Code and Product Version . Check the Installation With UpgradeSync . . . . . . UpgradeSync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Patch Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . Upgrades. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating an Upgrade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299 299 299 300 301 301 302 302 302 303 Chapter 12: Working With Source Paths. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305 About source paths. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Source Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding an Installation to Source Control . . . . . . . . . . . . . . . . . . . Adding Files to an Installation in Source Control. . . . . . . . . . . . . . Checking Files Into Source Control . . . . . . . . . . . . . . . . . . . . . . . Checking Files Out from Source Control . . . . . . . . . . . . . . . . . . . Getting Latest Version of Files . . . . . . . . . . . . . . . . . . . . . . . . . . Removing Files from Source Control . . . . . . . . . . . . . . . . . . . . . . Undoing the Check Out of Files . . . . . . . . . . . . . . . . . . . . . . . . . Showing History of the Installation File . . . . . . . . . . . . . . . . . . . . Showing the Differences Between Installation Files. . . . . . . . . . . . Comparing the Current Installation to the Latest in Source Control. About Path Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Turning Path Variable Substitution On and Off . . . . . . . . . . . . . . . Creating a User-Defined Path Variable . . . . . . . . . . . . . . . . . . . . Creating a Path Variable Based on an Environment Variable . . . . . Creating a Path Variable Based on a Registry Value . . . . . . . . . . . Windows Installer Editor Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305 305 306 307 308 309 309 310 310 310 311 311 312 313 313 314 314 8 Source Paths in an Installation . . . . . . . . . . . . . . . . . . . . . . . . Changing Source Directories . . . . . . . . . . . . . . . . . . . . . . Converting to Relative Source File Paths . . . . . . . . . . . . . . Converting to UNC-Based Source File Paths . . . . . . . . . . . . Changing the Source Directory Dynamically During Compile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315 316 317 318 318 Chapter 13: Merge Modules and Transforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320 About Merge Modules . . . . . . . . . . . . . . . . . . . . . . . . . . Available Tabs and Pages in Merge Modules . . . . . . . . Setting Merge Module Details . . . . . . . . . . . . . . . Setting Dependencies for a Merge Module . . . . . . Setting Exclusions for a Merge Module . . . . . . . . Creating a Merge Module As a New Installation . . . . . Creating a Merge Module From Existing Components . Creating a Configurable Merge Module . . . . . . . . . . . Setting Configuration Item Details . . . . . . . . . . . Specifying Drop-Down List Values for Substitution Specifying a Bitfield for Substitution . . . . . . . . . . Specifying a Key for Substitution . . . . . . . . . . . . Example: Configuring an Item for a Merge Module About the Merge Modules Page . . . . . . . . . . . . . . . . Adding a Merge Module to an Installation . . . . . . Editing Merge Module Details . . . . . . . . . . . . . . . About Transforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Transform Based on an Existing .MSI . . . . Setting Transform Details . . . . . . . . . . . . . . . . . . . . Creating a Universal Transform . . . . . . . . . . . . . . . . Applying a Transform to an Installation . . . . . . . . . . . Multiple Instance Installations . . . . . . . . . . . . . . . . . Installing Multiple Instances. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320 321 322 323 324 325 326 328 329 330 331 332 333 334 335 337 338 339 340 341 342 343 345 Chapter 14: Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346 About Windows Installer Editor tools. . . . . . . . . . . . . . . . ApplicationWatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Convert SMS Installer or WiseScript Installation. . . . . . . . Converting an SMS Installer or WiseScript Installation Import Visual Studio Projects. . . . . . . . . . . . . . . . . . . . . Importing an Installation From a Visual Studio Project MSI to WSI Conversion . . . . . . . . . . . . . . . . . . . . . . . . . Converting an .MSI to a .WSI File. . . . . . . . . . . . . . . Specifying Merge Module Source Directories . . . . . . . Specifying File Source Directories . . . . . . . . . . . . . . . Package Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . Removing Files With Missing or Invalid Source Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346 347 347 348 349 350 352 352 353 355 356 357 Chapter 15: Setup Editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359 About Setup Editor . . . . . . . . . . . . . . . . Product Tab . . . . . . . . . . . . . . . . . . . . . Specifying Summary Information . . . Features Tab . . . . . . . . . . . . . . . . . . . . Assigning a Component to a Feature. Modules Icon . . . . . . . . . . . . . . . . . Advertising Icon . . . . . . . . . . . . . . . Creating a Folder in Setup Editor . . . Windows Installer Editor Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359 361 362 363 364 365 366 367 9 Creating Duplicate File Entries . . . . . Components Tab . . . . . . . . . . . . . . . . . Component Errors . . . . . . . . . . . . . Adding and Editing a Component . . . Moving Items Between Components . About the Key Path. . . . . . . . . . . . . Isolating a .DLL With an .EXE. . . . . . Adding Published Components . . . . . Tables Tab . . . . . . . . . . . . . . . . . . . . . . Creating a New Table . . . . . . . . . . . Creating a New Row in a Table. . . . . Editing Existing Tables . . . . . . . . . . Searching for Table Data . . . . . . . . . Finding Validation Errors . . . . . . . . . Editing Binary Data in the Icon Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367 368 370 370 373 374 374 375 376 378 379 379 380 380 381 Chapter 16: Using Conditions and Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383 Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Where Can You Use Conditions? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Condition Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Examples of Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . WiseFixConditions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Conditions With Condition Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Checking the Value of a Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Checking the Value of an Environment Variable . . . . . . . . . . . . . . . . . . . . . . . . . Checking If and How a Feature or Component is Currently Installed . . . . . . . . . . . Checking If and How a Feature or Component Will Be Installed by This Installation Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How Do You Use Properties? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a New Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383 383 385 386 386 387 388 389 390 390 391 392 393 Chapter 17: Working With Dialogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395 About Dialogs . . . . . . . . . . . . . . . . . . . . . . . . . . . About the Wizard Dialogs . . . . . . . . . . . . . . . . Using the Dialogs Page . . . . . . . . . . . . . . . . . . . . . Changing the Theme of Dialogs . . . . . . . . . . . . Adding and Editing Dialog Themes . . . . . . . . . . Importing Text into License and Readme Dialogs Changing the Order of Web Dialogs . . . . . . . . . Using the Dialogs Tab . . . . . . . . . . . . . . . . . . . . . . Adding Controls to Dialogs. . . . . . . . . . . . . . . . Editing Dialog Details . . . . . . . . . . . . . . . . . . . . . . Creating a New Dialog . . . . . . . . . . . . . . . . . . . . . About Dialog Controls . . . . . . . . . . . . . . . . . . . . . . Types of Dialog Controls . . . . . . . . . . . . . . . . . Editing Dialog Controls . . . . . . . . . . . . . . . . . . Basic Control Settings . . . . . . . . . . . . . . . . Setting an Event on a Control . . . . . . . . . . Assigning Help to a Control . . . . . . . . . . . . Assigning Conditions to a Control . . . . . . . . Setting the Graphic for a Control . . . . . . . . Setting the Items in a Control . . . . . . . . . . Organizing and Aligning Controls on Dialogs . . . Aligning Dialog Controls . . . . . . . . . . . . . . Windows Installer Editor Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395 396 398 399 400 401 402 402 404 404 406 407 407 409 409 412 413 413 414 414 415 416 10 Centering Dialog Controls . . . . . . . . . . . . . . . . Making Dialog Controls the Same Size . . . . . . . Spacing Dialog Controls Evenly . . . . . . . . . . . . Setting Dialog Tab Order . . . . . . . . . . . . . . . . . About Billboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding Billboards to a Dialog . . . . . . . . . . . . . . . . . Obtaining Logon Information From a Dialog. . . . . . . . . . Adding the Logon Information Dialog . . . . . . . . . . . About the SQL Connection Dialog . . . . . . . . . . . . . . . . . Adding the SQL Connection Dialog to an Installation . Editing Additional SQL Connection Dialogs . . . . . . . . Adding the Custom Property Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417 417 417 418 418 419 421 421 422 423 424 425 Chapter 18: Macro Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427 About the Macro Editor . . . . . . . . . . . . . . . About Macro Files . . . . . . . . . . . . . . . . . . . Creating, Editing, and Running a Macro. Events That Can Trigger a Macro . . . . . About the Macro Editor Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427 427 428 429 430 Chapter 19: Debugger for Windows Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432 About the Debugger . . . . . . . . . . . . . . . . . . . . . . . . The Debugger Window . . . . . . . . . . . . . . . . . . . Running the Debugger . . . . . . . . . . . . . . . . . . . . . . Setting Properties and Applying Transforms in the Setting and Clearing Debugger Breakpoints . . . . . Evaluating Conditions . . . . . . . . . . . . . . . . . . . . Working With Temporary Tables and Columns . . . Searching For Text in Tables . . . . . . . . . . . . . . . ........ ........ ........ Debugger . ........ ........ ........ ........ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432 432 433 434 434 435 435 435 Chapter 20: Using MSI Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436 About MSI Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The MSI Script Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About Installation Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding a Custom Action Outside a Sequence . . . . . . . . . . . . . . . . . . Adding a Custom Action to Multiple Sequences. . . . . . . . . . . . . . . . . About Installation Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Finding Text in MSI Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Types of Actions in MSI Script Sequences . . . . . . . . . . . . . . . . . . . . . . . About the Standard and Custom Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . Adding and Editing Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Commenting Out Script Lines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Calling WiseScripts with Custom Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . Examples of WiseScripts You Run From an .MSI . . . . . . . . . . . . . . . . . . . Using a WiseScript to Parse a Path . . . . . . . . . . . . . . . . . . . . . . . . . Using a WiseScript to Install a License File. . . . . . . . . . . . . . . . . . . . Uninstalling Changes Made by a WiseScript . . . . . . . . . . . . . . . . . . . Troubleshooting: When WiseScript Custom Actions Fail on Windows Vista . Guidelines for Using Custom Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Guidelines for Custom Action Location . . . . . . . . . . . . . . . . . . . . . . . . . Guidelines for Custom Action Conditions . . . . . . . . . . . . . . . . . . . . . . . . Guidelines for Nested Installation Custom Actions . . . . . . . . . . . . . . . . . Guidelines for Calling VBScripts and JScripts . . . . . . . . . . . . . . . . . . . . . Windows Installer Editor Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436 437 437 439 439 440 440 441 441 442 442 443 443 444 444 445 446 448 449 450 451 451 452 11 Guidelines for Calling .DLLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453 Launching a Custom Action from a Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454 Troubleshooting Custom Actions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455 Chapter 21: Custom Action Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456 About Custom Actions . . . . . . . . . . . . . . . . . . . . . . . . . Call Custom DLL From Destination . . . . . . . . . . . . . Call Custom DLL From Installation . . . . . . . . . . . . . Call Custom DLL From Installed Files . . . . . . . . . . . Configuring .DLL Parameter Settings . . . . . . . . . . . Call DLL From Installation . . . . . . . . . . . . . . . . . . . Call DLL From Installed Files . . . . . . . . . . . . . . . . . Call JScript From Embedded Code . . . . . . . . . . . . . Call JScript From Installation . . . . . . . . . . . . . . . . . Call JScript From Installed Files . . . . . . . . . . . . . . . Call JScript From Property . . . . . . . . . . . . . . . . . . . Call VBScript From Embedded Code . . . . . . . . . . . . Call VBScript From Installation . . . . . . . . . . . . . . . . Call VBScript From Installed Files . . . . . . . . . . . . . . Call VBScript From Property. . . . . . . . . . . . . . . . . . Display Message. . . . . . . . . . . . . . . . . . . . . . . . . . Download File From Internet . . . . . . . . . . . . . . . . . End Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . Execute Program From Destination . . . . . . . . . . . . . Execute Program From Installation . . . . . . . . . . . . . Execute Program From Installed Files . . . . . . . . . . . Execute Program From Path. . . . . . . . . . . . . . . . . . If Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . Install MSI From Destination . . . . . . . . . . . . . . . . . Install MSI From Installation . . . . . . . . . . . . . . . . . Install MSI From Relative Path . . . . . . . . . . . . . . . . Launch Web Page . . . . . . . . . . . . . . . . . . . . . . . . . Open Document From Installed Files. . . . . . . . . . . . Pause Installation . . . . . . . . . . . . . . . . . . . . . . . . . Post Data to HTTP Server . . . . . . . . . . . . . . . . . . . Remark . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Run WiseScript From Destination . . . . . . . . . . . . . . Run WiseScript From Installation . . . . . . . . . . . . . . Run WiseScript From Installed Files . . . . . . . . . . . . Set Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . Set Feature State . . . . . . . . . . . . . . . . . . . . . . . . . Set Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . Terminate Installation . . . . . . . . . . . . . . . . . . . . . . Using the Custom Action Location Tab. . . . . . . . . . . . . . Using the Custom Action Location Tab for Merge Modules Using the Custom Action Properties Tab . . . . . . . . . . . . Using the Custom Action Description Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457 457 458 459 460 461 462 463 463 464 465 466 466 467 468 468 469 470 470 471 472 472 473 473 474 475 476 477 477 477 478 479 479 481 482 482 483 484 484 485 486 489 Chapter 22: Windows Installer and .NET Technologies . . . . . . . . . . . . . . . . . . . . . . . . 490 About Microsoft Windows Installer . . . . . . . . . . . . . . . . . . . . . . . Frequently Asked Questions About Microsoft Windows Installer Working With Components and Features . . . . . . . . . . . . . . . . About GUIDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Windows Installer Editor Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490 491 492 493 12 About Microsoft .NET Technology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493 Frequently Asked Questions About Microsoft .NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494 Requirements for Creating a .NET Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497 Appendix A: Wise Custom Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498 Appendix B: Wise Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504 Appendix C: Property Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508 Build Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508 INI File Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512 Run Time Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515 Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517 Windows Installer Editor Reference 13 Preface This chapter includes the following topics: z Product Documentation z Technical Support Resources Product Documentation This documentation assumes that you are proficient in the use of the Windows operating system. If you need help using the operating system, consult its user documentation. Use the following sources of information to learn this product. Online Help The online help contains detailed technical information and step-by-step instructions for performing common tasks. Access help in the following ways: z To display context-sensitive help for the active window or dialog box, press F1. z To select a help topic from a table of contents, index, or search, select Help menu > Help Topics. Reference Manual All the material in the online help is also available in a .PDF-format reference manual, which you can access by selecting Help menu > Reference Manual. Getting Started Guide The Getting Started Guide contains system requirements, installation instructions, and a tutorial. You can access a .PDF version of the Getting Started Guide from the Windows Start menu. Windows Installer SDK Help You can get technical details about Windows Installer from its own help system, which is written by Microsoft for a developer audience. In Wise for Windows Installer, select Help menu > Windows Installer SDK Help. Version 3.1 of the Windows Installer SDK Help is provided. If you have obtained a later version, links from the Wise product documentation to the Windows Installer SDK Help might not work. Release Notes The product release notes cover new features, enhancements, bug fixes, and known issues for the current version of this product. Access the release notes in the following ways: z Browse the product CD. Windows Installer Editor Reference 14 z Select Release Notes from the Altiris program group on the Windows Start menu. Technical Support Resources If you need help beyond what the product documentation provides, visit the Altiris Service Center, which is your complete online resource for Altiris product support. Access the Altiris Service Center from the Support section of the Altiris Web site. Use the Altiris Service Center to access the following Altiris support tools and services. Knowledgebase Provides a central repository for technical information at Altiris. Articles are reviewed and refined by Altiris personnel and provide information about past problems and their resolutions. Support forums Lets Altiris users collaborate and share information. The support forums are monitored by experienced customers, Altiris partners and Altiris personnel. License Management Portal Manages and provides access to Altiris product licenses. Altiris Support Helpdesk Lets Altiris premium and enterprise support customers use a Web-based tool to log new support incidents, update existing incidents and communicate with Altiris support personnel. User groups Provide a place for Altiris users to discuss IT management projects, learn best practices, discover the latest product features, and network with other users. Before you contact technical support, obtain the following information: z Serial number and product version, which you can find by selecting Help menu > About. z Operating system version and service pack version if applicable. z A description of what you do before the problem occurs. z The text of any error messages that appear. z Your name, company name, and how to contact you. z Contract number or payment information, if applicable. Windows Installer Editor Reference 15 Chapter 1 Introduction This chapter includes the following topics: z About Windows Installer Editor on page 16 z Starting the Software on page 16 z The Product Interface on page 17 z Using Installation Expert on page 18 z Using the Task List on page 24 z Installation Resources and Their Locations on page 27 z Generating Package Contents Reports on page 28 z Downloading Redistributable Files on page 29 About Windows Installer Editor Windows Installer Editor is an installation development tool for creating and editing Windows® Installer (.MSI) installation packages. It is a complete and user-friendly front end for generating Windows Installer database files, which are executed by the Windows Installer engine. With Windows Installer Editor, you can: z Create installations that are compliant with the Microsoft Windows 2000, XP, and Vista logo program. z Edit and refine installations that you have converted from other formats. z Import development projects. Microsoft® Windows® Installer is a Microsoft technology that provides a standard installation engine that can be used for the installation of any 32-bit Windows application. It resides on the destination computer and performs the installation of applications. Windows Installer technology provides features that are not available in traditional installation-building products (examples: self-healing and install-ondemand). Windows Installer Editor is a tool in Wise Package Studio®. Starting the Software To start the software 1. In Wise Package Studio, do one of the following: „ Windows Installer Editor Reference On the Projects tab, click the Run link to the right of the task or tool associated with Windows Installer Editor. The installation associated with the current project might be opened by default. This tool might open to a different view based on command-line options defined in Process Templates Setup. 16 Introduction „ 2. On the Tools tab, double-click Windows Installer Editor. Select File menu > New. The New Installation File dialog box appears. 3. Complete the dialog box: a. In the Categories list, click Predefined Templates. b. In the Templates/Tools list, click the Windows Application icon. The Windows Application icon lets you create a standard installation. You can create other types of installations. See Starting a New Installation on page 69 and Options for New Installations on page 72. c. In the File type section, specify the type of file to create. d. In Target Platform, specify whether this installation is enabled for 32-bit, 64bit (x64), or 64-bit (Itanium) platforms. This sets the initial target platform for the Default release. e. If the application has been written to be installed and run by standard users without elevation, mark Create a Vista Standard User Installation. This clears the Enable User Account Control (UAC) check box in Installation Expert > Windows Installer Options page. See Creating an Installation for Standard Users on page 70. f. Click OK. The new installation opens. The Product Interface Windows Installer Editor has the following views, each of which provides you with a different development environment. Installation Expert Installation Expert lets you create basic Windows Installer installations and provides an easy-to-use, task-oriented user interface to perform the most common installation tasks. Each page of Installation Expert lets you configure a specific aspect of your installation. See Using Installation Expert on page 18. Windows Installer Editor Reference 17 Introduction MSI Script MSI Script provides a powerful yet easy-to-use environment for editing Windows Installer installation sequences. A sequence is a set of actions that are performed during a particular type of installation. MSI Script is easy to work with even if you are not familiar with the underlying Windows Installer technology. Just double-click the custom action to add to your sequence or start typing the action name, then fill out options for the action. A new line based on the action and the options you entered appears in the sequence at the location of the last selected action. The resulting sequence is displayed in clear, readable statements. See About MSI Script on page 436 Setup Editor Setup Editor is a powerful view of the installation, and using its advanced features requires proficiency in the Windows Installer development environment or in software development. Setup Editor lets you create fully customized interactive installations. Certain advanced tasks can be performed only in Setup Editor. See About Setup Editor on page 359. To navigate between views, click the navigation tabs at the lower left of the main window. Additional Interfaces z The Tools menu contains powerful tools that perform specialized functions. See About Windows Installer Editor tools on page 346. z The Compile, Test, Debug, and Run buttons let you test and compile the installation. See Compiling An Installation on page 77, Testing and Running An Installation on page 79, and About the Debugger on page 432. Using Installation Expert To access Installation Expert, click Installation Expert at the lower left of the Windows Installer Editor main window. Windows Installer Editor Reference 18 Introduction Installation Expert window in Windows Installer Editor Page Views Page Area Page Groups Compile and Test View Navigation Page Views Use the Page Views drop-down list to select a page view, which is a set of Installation Expert page groups and pages. See About Page Views on page 20 and Customizing Page Views on page 21. Page Groups When you select a page view, its pages are organized into page groups. Click the group name to expand or collapse its pages. Click a page name to display that page. Page Area When you click a page name in a page group, this area displays the page’s options. Each page lets you define a specific aspect of the installation. (Examples: On the Files page, you define what files are included in the installation. On the Registry page, you define what registry keys and values are created on the destination computer.) Complete only the pages that are pertinent to your particular installation, in any order. If required information is missing, an error message appears during compile. z Use on the toolbar to navigate from page to page, or click the page name in the list of pages. z To display help for the current page, press F1. z To return a page to its last saved state, select Edit menu > Reset Page. View Navigation Click these tabs to change views. Windows Installer Editor Reference 19 Introduction Compiling and Testing Compile, Test, Debug, and Run buttons test and compile the installation. See also: Using the Current Release Drop-Down List on page 23 Using the Current Feature Drop-Down List on page 22 About Page Views A page view is a set of Installation Expert page groups and pages that you select from the Page Views drop-down list. Select a page view to display only specific page groups and pages. Types of Page Views z Predefined page views that display the groups and pages most frequently used for a particular type of installation. The All page view displays all page groups and pages. The Merge Module page view appears for all merge modules. You cannot edit or delete predefined page views. z Custom page views that you create to meet your specific needs. See Customizing Page Views on page 21. z Page views that are created when you create an installation template. You cannot delete these page views. See Creating and Editing Installation Templates on page 47. The page views are arranged alphabetically in the Page Views drop-down list with the exception of the All page view, which is always first. The list also includes and , which are at the end of the list and are used to create or customize page views. Predefined Templates and Page Views Most predefined installation templates have an associated page view. When you create a new installation by using one of these templates, the page view that is associated with that template becomes the default page view of the installation. When you open the installation, this page view appears in the Page Views drop-down list. You can select a different page view from the list at any time, except when you are working in a merge module or universal transform. Merge module and universal transform projects cannot use other page views, and their page views cannot be used with other types of projects. When you select a different page view, it changes the pages displayed in Installation Expert but does not change the installation type. If you change the page view and save the installation, this new page view displays the next time you open the installation, unless you clear the Display the page view associated with a project when a project is opened check box in Wise Options. Custom Templates and Page Views When you create a custom installation template, a page view is created with the same name and is listed in the Page Views drop-down list. See Creating and Editing Installation Templates on page 47. Windows Installer Editor Reference 20 Introduction When you use a template to create an installation, the default page view is the page view that was displayed when the template was created. If the template’s default page view is a custom page view, you can customize it. See Customizing Page Views on page 21. You can share page views that are associated with an installation template because the page view is stored in the template, which is located in the share point directory. Which Page View Appears? z The Display the page view associated with a project when a project is opened check box in Wise Options determines what page view appears. If you clear this check box, the page view in Installation Expert does not change when you open a project regardless of its associated page view. See Setting Installation Expert Options on page 41. z The All page view is used when you open an installation file that does not have an associated page view. An .MSI does not have an associated page view. See also: Using Installation Expert on page 18 Customizing Page Views You can create customized Installation Expert page views that display only the page groups and pages that you use most often. You can customize the page view of custom installation templates or create customized page views that are not associated with a template. You cannot customize the predefined page views, but you can make a copy of a predefined page view and then customize it. When you customize a page view, you can specify how many page groups appear, what the group names are, and what pages appear under each group. Customized Page Views dialog box Buttons to edit page groups and pages are unavailable when a predefined page view is selected in Page View Name. These pages appear under the group selected in Page Groups. The page groups appear on the left side of Installation Expert. Windows Installer Editor Reference 21 Introduction To create a page view 1. From the Page Views drop-down list in Installation Expert, select . The Enter Name dialog box appears. 2. Enter a name for the page view. To create an access key for the name, type & (ampersand) before a letter in the name. The page view access keys appear only in the page group’s right-click menu, which you access from the context menu key (the key next to the right Ctrl key). 3. Click OK. On the Customized Page Views dialog box, the new page view is selected in Page View Name, but it has no page groups or page names. 4. To copy the page groups and pages of an existing page view: a. Click Copy View. The Copy View dialog box appears. b. Select the page view to copy and click OK. The Merge Module and Universal Transform page views do not appear on the list because they cannot be copied. You can now customize the page view by changing its page groups and pages. To customize a page view 1. From the Page Views drop-down list in Installation Expert, select . The Customize Page Views dialog box appears. 2. 3. Select the page view from Page View Name, and do any of the following: „ To add a new page group, click the Page Groups Add button and enter a name. „ To rename a page group, select the page group and click Rename. „ To add a page to a page group, select the page group and click the Add button to the right of Page Names. On the Select Pages to Add dialog box, select one or more pages and click OK. „ To delete a page group or a page name, select it and click its Delete button. Click OK on the Customize Page Views dialog box. To delete a page view, select it from Page View Name and click the top Delete button. See also: Using Installation Expert on page 18 Using the Current Feature Drop-Down List The Current Feature drop-down list appears on pages in the Feature Details page group. When it appears, you can set options on a per-feature or per-condition basis. You add features and conditions on the Features page, then select a feature from Current Feature before setting options on other pages. Windows Installer Editor Reference 22 Introduction Current Feature drop-down list Example: Suppose you have three features, and each feature requires different registry entries. On the Registry page, you select the first feature from Current Feature, create its registry entries, select the second feature in the list, create its registry entries, and so on. During installation, files, registry entries, and other system changes are installed only if the feature they belong to is installed. The same applies to conditions; add files, registry entries, and other changes to a condition, and during installation, those files and registry entries are installed only if the condition is true and the feature is installed. The All Features (Modify/Delete only) option in Current Feature displays information for all features at once. (Example: On the Files page this option displays all folders and files for all features.) Add and New buttons are unavailable while all features are displayed; you must select a single feature to add items. On some pages, Current Feature also contains numbers in parentheses, which represents the number of that page’s items (files or registry keys) that are assigned to each feature or condition. See also: Using the Current Release Drop-Down List on page 23 Using Installation Expert on page 18 Using the Current Release Drop-Down List The Current Release drop-down list appears on pages in the Release Definition page group. When it appears, you can set options on a per-release basis by selecting a feature from Current Release and then setting options on that page. Current Release drop-down list A release is a special version of your application. Example: a 30-day evaluation release for evaluators. Use Current Release to configure separate settings, media, and language options for each release. See also: Windows Installer Editor Reference 23 Introduction Using Installation Expert on page 18 Using the Current Feature Drop-Down List on page 22 Using the Task List When Windows Installer Editor encounters installation issues that could cause problems, it displays them in the Task List. You can manually display or hide the Task List from the View menu. The Task List gathers all installation issues into one place, and makes it easy to analyze their causes. If the issue is caused by an error in a table, you can quickly jump from the Task List to the row in the table that caused the error. See Finding Table Errors From the Task List on page 26. When you resolve the issue that corresponds to a task, the task is deleted the next time you run the procedure that generated the task. Example: If a task was added to the Task List because of a compile error and you resolve that error, the next time you compile the installation that task is deleted. How Tasks are Added to the Task List z Save or Compile If errors occur when you save or compile an installation, the errors are displayed in the Task List. z Package Validation When you run Package Validation, validation issues appear on the View / Correct dialog box. If you mark the Add to Task List check box on the View / Correct dialog box, each issue becomes a task in the Task List when you click Finish. If Package Validation encounters save or compile errors, the package validation process ends and the errors are added to the Task List. See About Package Validation in the Wise Package Studio Help. z Check Tables When you check tables, the installation is searched for component and table errors and results are placed in the Task List. To check tables, select Setup Editor > Tables tab, right-click in the left pane and select Check Tables. See Finding Validation Errors on page 380. z User-Defined You can add user-defined tasks to the task list. See Adding User-Defined Tasks on page 26. Note When you close an installation, all tasks, except user-defined tasks, are removed from the Task List. Task List Icons The following icons help you quickly identify the types of tasks in the Task List: Windows Installer Editor Reference 24 Introduction An error that will cause incorrect behavior and must be fixed Validation issues found by Package Validation See About Package Validation in the Wise Package Studio Help. A task you created This icon also appears with a task that reminds you to add the package meta data to the Software Manager database. Operations you can perform in the Task List z Filter tasks by type. See Filtering the Task List. z Find table errors. See Finding Table Errors From the Task List on page 26. z Sort a Task List column by clicking its header. z Copy a task’s description by right-clicking its description. z Delete a task by right-clicking its description. Filtering the Task List To filter the task list 1. Right-click in the Task List and select Show Tasks. 2. Select a filter. „ Save/Compile Tasks that correspond to errors that are generated when you save or compile. „ Validation Tasks that correspond to issues that are generated during Package Validation. „ Component Tasks that correspond to component errors that are generated when you check tables. See Using the Task List on page 24. „ Table Tasks that correspond to table validation errors that are generated when you check tables. See Using the Task List on page 24. „ User-Defined Tasks that you have created. When you set a filter, it is in effect until you change it. However, when you encounter installation issues, the filter is reset to All so installation issues can be displayed. Windows Installer Editor Reference 25 Introduction Finding Table Errors From the Task List If a task is associated with a table, you can access that table directly from the Task List, which helps you discover the problem that caused the issue. Example: If a source file for the installation was moved or deleted at its source, a WiseSourcePath table error appears during compile. When you double-click this task, the WiseSourcePath table appears in Setup Editor, and the row in the table that is the cause of the problem is highlighted. Use the source path information in the row to ascertain and resolve the problem. Warning Deleting, adding, or editing table data directly is not recommended unless you are an experienced Windows Installer developer with a clear understanding of Windows Installer database technology. Editing table data might cause unexpected, undesirable behavior, including damage to the installation. We cannot provide technical support for problems arising from table editing. To find table errors from the Task List: If the task has a table listed in the Table column, double-click the task. The table is displayed in Setup Editor > Tables tab, and the row in the table associated with the task is highlighted. If you need more information, check the task’s description or press F1 to display the help topic for the selected table in the Windows Installer SDK Help. See also: Tables Tab on page 376 Using the Task List on page 24 Adding User-Defined Tasks You can add tasks to the Task List. Example: Add user-defined tasks to define work that must be completed on the installation. Tasks you add to the Task List are saved with the installation. You can only add user-defined tasks to a .WSI; you cannot add them to an .MSI. To add a user-defined task 1. On the first line of the Task List, click Click here to add a new item twice and type the task. If Click here to add a new item does not appear in the Task List, save the installation file and it will appear. 2. Click anywhere outside the box that contains the new task. The task is added to the Task List and appears in the Description column. Userdefined tasks do not use the Tables column. See also: Using the Task List on page 24 Windows Installer Editor Reference 26 Introduction Generating Shared Resource Reports The following shared resource reports provide a quick way to review the resources that are shared by the current installation and other packages in the Software Manager database. z Shared Files Report Lists the files that are shared by the current installation and packages in the Software Manager database. For each file, the report lists each application that uses the file and shows detailed file information (examples: version, date/time, path, and so on). z Shared Registry Report Lists the registry keys that are shared by the current installation and packages in the Software Manager database. For each registry key, the report lists each application that uses the registry key and shows the key value. The reports are displayed in HTML format. The .XSL templates used to format these reports are in the Templates\Reports subdirectory of the share point directory. You can customize the .XSL templates to supply branding information, to filter data, or to transform the data to another format. To generate a shared resource report 1. Select Reports menu and select either Shared Files or Shared Registry. The Welcome dialog box appears. 2. In Data Source, specify the Software Manager database that contains the resources you want to review. If the Software Manager database you want is not listed, click Open to select it. 3. From Group, select the group that contains the packages to compare this installation to. 4. Click Next. The report is generated and displayed in the Shared Files Report or Shared Registry Report dialog box. You can save the or print the report from this dialog box. Saving to HTML is available only on computers that contain MSXML.DLL, which is included in Internet Explorer 5.x and higher. 5. When you finish reviewing, saving, or printing the report, click Finish. Installation Resources and Their Locations Windows Installer Editor uses various resources to create installations. (Example: installation templates, component rules, language files, and so on.) Most of these resources are installed with this product. Others must be created and placed in the appropriate directory before they can be used. (Standard Edition.) These resources are in subdirectories of the Windows Installer Editor installation directory. (Professional Edition.) These resources are stored in subdirectories of the share point directory. The share point directory also contains subdirectories that are specific to the Wise Package Studio Workbench. For a description of those subdirectories, see Wise Package Studio Directories in the Wise Package Studio Help. Windows Installer Editor Reference 27 Introduction You can specify alternate locations for storing resources. See Setting Repository Preferences in the Wise Package Studio Help. Directory Contents Custom Actions Files that you create to use in custom actions, such as WiseScripts, VBScripts, .DLLs, and so on, that you use in Windows Installer installations. Languages Language resource files that are used to change the language of installations. Merge Modules The default merge modules directory is Program Files\Common Files\Merge Modules\Wise Solutions. This is the default target location for downloading merge modules, and the default directory from which you select merge modules to add to an installation. Resources Installation resources such as bitmap and icon files. Templates Macros and additional template files that are used by Package Distribution. Also contains templates that are used to create a new installation. Templates\Dialogs The Wise Standard.MSI that provides information that is used by the New Dialog Wizard to add a new dialog box to an installation. Templates\Reports Templates that are used to format the shared resources reports in Windows Installer Editor. These reports are available only when you have a repository connection in Wise Installation Studio. Themes Themes.ini, which stores information about themes you have added or customized. Also contains subdirectories that store the images for each theme. Validation Predefined validation modules (.CUB files) that are used by Package Validation. Generating Package Contents Reports Package contents reports provide an overview of the contents of an installation file and make it easy to provide this information to end users. The following reports are available: z Package Contents Summary Lists detailed information for every resource in an installation, including files, registry keys, shortcuts, file associations, and merge modules. You can generate this report for .WSI, .MSI, .WSM, and .MSM files. z Package Contents By Feature Contains the same information as the Package Contents Summary report, but arranges it by feature. You can generate this report for .WSI and .MSI files. To generate a package contents report 1. Select Reports menu > Package Contents and select either Summary or By Feature. 2. The report is generated and opens in a dialog box. Use a report’s table of contents to quickly access information about a specific type of resource. You can print the report or save it as an HTML or XML file. Windows Installer Editor Reference 28 Introduction Downloading Redistributable Files The Download Redistributables wizard, available from the Help menu, lets you obtain merge modules, Windows Installer runtime installers, and .NET Framework runtime installers. You need the Windows Installer runtimes if you decide to pre-install Windows Installer with an installation. You need the .NET Framework if you are creating an installation that contains .NET elements. Because of size and obsolescence considerations, these files are distributed through the Internet or product CD. This wizard appears any time Windows Installer Editor detects a dependency on other merge modules or other redistributables. Example: If you run ApplicationWatch and it adds a file that must be installed with a certain merge module, the Download Redistributables wizard appears and prompts you to download the necessary merge module. This wizard might also appear if you install runtimes with the installation, or if you add files to the installation that are part of a merge module. Download redistributable files from the following locations: Wise Web Site Select and download one or more redistributables from the Wise Web site. See Downloading Redistributables From the Wise Web Site or Product CD on page 29. Other Vendors’ Web Sites Select and download a redistributable from a third-party vendor’s Web site. Available redistributables are authored by the respective vendor, and you need to contact the vendor for information or help on these redistributables. See Downloading Redistributables From Other Vendors’ Web Sites on page 30. Product CD Select and download one or more redistributables from the CD that was used to install this product. See Downloading Redistributables From Other Vendors’ Web Sites on page 30. If you need to go through a firewall or proxy server to get to the Internet, the Download Redistributables wizard uses your browser’s proxy settings. To change your Internet connection settings, refer to your browser’s documentation. Downloading Redistributables From the Wise Web Site or Product CD You must be in an active Wise installation to follow this procedure. To download redistributables from the Wise Web Site or product CD 1. Select Help menu > Download Redistributables. The Source Location dialog box appears. 2. Mark Wise Web Site or Product CD and click Next. 3. If you marked Product CD, specify the location of the CD on the Product CD Location dialog box. Then click Next. Windows Installer Editor Reference 29 Introduction A Download Files dialog box appears while all available redistributable files are retrieved. The Available Redistributable Files dialog box then appears. 4. From Redistributable Type, select the type of redistributable to download. 5. In the Modules Available or Versions Available list, mark one or more check boxes for the redistributables to download. 6. Click Next. If you chose to download any merge modules, the Target Location dialog box appears, where you specify merge modules’ download location; otherwise the download starts and you can skip the next step. Runtimes are downloaded to private directories where they are accessed as needed by Windows Installer Editor. 7. From Target Location, select the directory to download the selected merge modules to, then click Next. The drop-down list shows all merge module directories specified in Wise Options. See Setting Merge Module Directories on page 42. The selected redistributables are downloaded from the Internet or CD. 8. Click Finish on the Download Files dialog box to finish the wizard. The merge modules you selected are now in the directory you specified as the target location. If any merge modules had dependencies on other merge modules, those merge modules were also downloaded. Other runtimes are located in their required directories. See also: Downloading Redistributable Files on page 29 Downloading Redistributables From Other Vendors’ Web Sites You must be in an active Wise installation to follow this procedure. We have no control over other vendor’s redistributable files. Check with the vendor for product support. To download redistributables from other vendors’ Web sites 1. Select Help menu > Download Redistributables. The Source Location dialog box appears. 2. Mark Other Vendors’ Web Sites and click Next. When all available redistributables are retrieved, the Available Redistributable Files dialog box appears. 3. In the list box, select the redistributable to download and then click Download to connect to the vendor’s Web site. 4. Follow the links and prompts on the Web site to download the redistributable. Be sure to download merge modules to a directory specified in Wise Options. See Setting Merge Module Directories on page 42. 5. When the download is complete, return to the Available Redistributable Files dialog box and click Finish. The merge modules and other runtimes you selected are now in the directory you specified as the target location. If any merge modules had dependencies on other merge modules, those merge modules were also downloaded. Windows Installer Editor Reference 30 Introduction See also: Downloading Redistributable Files on page 29 Windows Installer Editor Reference 31 Chapter 2 Setting Up This chapter includes the following topics: z How you can set up Windows Installer Editor on page 32 z Setting Options on page 32 z Creating and Editing Installation Templates on page 47 z Component Rules on page 48 How you can set up Windows Installer Editor Before you create and edit installations, set up Windows Installer Editor to reflect your organization’s standards: z Set options that control the installations you create and determine the installation resources you use. See Setting Options on page 32. z Decide whether you need to customize the templates that installations are based on. See Creating and Editing Installation Templates on page 47. z Decide which rule set to use to help you manage the creation of components in installations. You can edit the predefined rule sets or create new rule sets. If the predefined rule sets do not meed your needs, you can duplicate them and modify the copies as needed, or you can create new rule sets. See Component Rules on page 48. Setting Options You can set options that control the installations you create and determine the installation resources you use. Some of the options are global; they are set for all files you open with Windows Installer Editor, including files you created previously. Other options provide defaults for new files and do not affect existing files. You set options on the Options dialog box, which you access by selecting Tools menu > Options. The Options dialog box contains the following tabs. See: Setting General Options Setting .NET Assembly Options on page 34 Setting Advertising Options on page 36 Setting Digital Signature Options on page 37 Setting ExpressBuild Options on page 39 Setting Installation Expert Options on page 41 Setting Merge Module Directories on page 42 Activating Suppressed Prompts on page 43 Windows Installer Editor Reference 32 Setting Up Setting Source Control Options on page 45 Setting Wildcard Groups on page 46 Setting General Options To set general options, select Tools menu > Options and click the General tab. Automatic Options z Create backup copy during save Mark this to create a new backup file every time you save. The backup file name consists of the current file name plus a number. (Example: if the current file name is Sample.wsi, the backups are named Sample1.wsi, Sample2.wsi, and so on.) Only the file you are working on is backed up. (Example: if you open a .WSI and save it, the corresponding .MSI is not backed up.) Use caution with this option if you are working with large installation files; if you save often, your disk space will quickly become depleted. This can be set automatically from Wise Package Studio Preferences; use this check box to override the Package Studio setting. z Add default remarks to installation sequences Although most Wise project (.WSI) files have remarks that explain the actions in the sequences, compiled .MSIs do not. Mark this to add remarks to the current .MSI and all .MSIs that you open subsequently. Remarks are added to .WSIs only if no remarks already exist. z Create XML copy during save Mark this to update a copy of the installation in XML format every time you save. If a copy does not exist, it is created. The copy has the same name as the installation file with the extension .XML appended, and it is saved in the same directory. (Example: If the current file name is Application.wsi, the XML copy is named Application.wsi.xml.) This lets you check the XML version of the installation into a source code control system and use text-based file comparison tools to find changes. See Saving an Installation as XML on page 76. Compiler Options The following options are default settings for all new compiles. Changing these settings does not affect installations that have already been compiled. z Add custom actions for predefined folders in merge modules This affects the merging of merge modules that place files in predefined directories, such as \Windows, \System32, and so on. Mark this to have the merge emulate the behavior of the Microsoft merge tool, mergemod.dll, which uses custom actions to handle predefined directories. Clearing this check box can fix potential problems with capitalization inconsistencies in the directory name. Windows Installer Editor Reference 33 Setting Up Note Windows Installer Editor has its own code for merging a module into an .MSI, but this check box causes your merge to follow the Microsoft conventions for merging. Microsoft’s merging code adds a custom action to the installation for each predefined directory referenced in each included merge module. The custom action uses a Set Property action to set the predefined directory name, whereas the Windows Installer Editor code sets the predefined directory name by adding an item to the Directory table of the Windows Installer database. z Display error if merge modules conflict with main installation rows Merge module errors occur if a merge module contains a row that has the same key as a row in the main installation. Clear this to ignore such errors and let the merge module row overwrite the row in the main installation. z Enable Quick Compile Mark this to speed the compile process by compressing only previously uncompressed or changed files. Quick Compile writes the .MSI table information. If a file or media has changed, a full compile will occur instead. Quick Compile is for project files only. You can also speed compile time by using ExpressBuild, a multiprocessor compile feature. See About ExpressBuild on page 38. Software Virtualization Options z Install into virtual layer from Run button Mark this to install an installation into a virtual layer when you click the Run button. This creates a new layer, installs the .MSI into the layer, and activates the layer. After you test the installation, you can delete the layer to restore your computer to its original state. See Running An Installation on page 80. Startup Options z Reload last project at startup Mark this to open the last installation you worked on when you start Windows Installer Editor. See also: Setting Options on page 32 Setting .NET Assembly Options ¾ Windows Installer 2.0 or later only. You can specify whether you create standard Win32 or .NET installations, and customize how Windows Installer Editor handles the .NET assemblies. To set options: Select Tools menu > Options and click the .NET Assemblies tab. Complete the tab. Windows Installer Editor Reference 34 Setting Up If the options on the .NET Assemblies tab are unavailable, install the .NET Framework and run a manual repair of the Windows Installer Editor .MSI from Add/Remove Programs. COM Interop Options z z Default Application Type This determines the default setting for the Application Type field on the Product Details page for new installations. Changing this field does not affect existing installations. „ Win 32 (non .NET) Select this if you typically create standard Win32 installations without .NET assemblies. „ .NET Application Select this if you typically create .NET installations with only .NET elements. „ Mixed (.NET and Win32) Select this if you typically create installations containing both Win32 and .NET elements. When this option is selected, .NET assemblies you add to an installation are registered so that they can be called as though they were COM components. For information on COM interoperability, search for “Interoperating with Unmanaged Code” in the MSDN Library (msdn.microsoft.com/library/). Rescan COM interop registry keys on compile Mark this to scan and update interop registry keys for .NET assemblies each time you compile. This check box is available only if the .NET Framework is installed on your computer. Assembly Scanning Options The scanning options are available only if the .NET Framework is installed on your computer. z Scan Dependencies Specify how dependency assemblies are added to an installation. You can add them manually or have Windows Installer Editor scan the assembly manifest for dependencies and add them automatically. Changing this option does not affect assemblies that have already been added to installations. „ Never scan dependencies If you select this, you must add dependency assemblies to installations manually on the Files or Web Files page. „ Prompt to scan dependencies When you add a .NET assembly to an installation, Windows Installer Editor scans its manifest for dependencies and prompts you to select which ones to add to the installation. „ Always scan dependencies When you add a .NET assembly to an installation, Windows Installer Editor scans its manifest for dependencies and adds them to the installation. z Rescan assembly dependencies on compile Mark this to scan for new assembly dependencies each time you compile. z Rescan assembly attributes on compile Mark this to rescan and update assembly attributes each time you compile. This check box is marked by default. Windows Installer Editor Reference 35 Setting Up Note On .NET Framework versions earlier than 1.1, the scan does not occur when you add an assembly from a UNC or mapped network drive (example: the share point directory). To enable scanning of such assemblies, either upgrade to .NET Framework version 1.1 or later, or change your .NET security so that the share point directory is fully trusted. See also: Setting Options on page 32 Setting Advertising Options You can specify how to gather self-registration and advertising information for files you add to an installation. Windows Installer considers some kinds of registry entries, such as file extension definitions, to be advertising information. See Platform Support of Advertisement in the Windows Installer SDK Help. The Advertising options are default settings for all new components. Changing these settings will not affect existing components. To set options: Select Tools menu > Options and click the Advertising tab. Complete the tab. z Advertising Setting Select one of the “scan” options to have Windows Installer Editor inspect your computer’s registry and the files in the installation and automatically add Windows Installer advertising information for the files that you add to the installation. The different scan options let you determine whether the advertising information is added to the advertising tables (AppId, Class, Extension, Mime, ProgId, TypeLib, Verb), to the registry, or both. The scan options also cause AppPath registry information to be added to the installation automatically, although it is not related to advertising. Only AppPath information at HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\App Paths\ is added. This registration method is preferred over self-registration because it does not depend on the presence of other files on the destination computer, nor does it depend on how well the .OCX or .DLL file adheres to self-registration conventions. However, the .OCX or .DLL files must already be registered correctly on your computer. If you prefer not to register installation files on your computer, you can run the scan routine as a stand-alone utility on a different computer. See Using WiseComCapture.exe on page 133. „ Do not scan advertising information Use self-registration for components that support it. Windows Installer Editor will not scan files or the registry. „ Scan advertising information into registry keys Add advertising information to the installation as registry keys only; do not create entries in advertising tables. This results in an installation that does not support advertising through COM. Windows Installer Editor Reference 36 Setting Up „ Scan advertising information into advertising tables Place registry entries that are considered to be advertising information into advertising tables. Create registry entries for any information that cannot be placed in the advertising tables. This results in an installation that supports advertising. „ Scan advertising into both advertising tables and registry Place registry entries that are considered to be advertising information into advertising tables and into registry keys. As a result, all advertising information is included in the installation; none is lost. Warning When registry entries are created for any information that cannot be placed in the advertising tables, the installation is more accurate because no information is lost. However, this might cause an error or warning when you run the Application Specification Logo test in Package Validation. z Automatically add self-registration Mark this to add self-registration information to the installation whenever you add an .OCX or .DLL file that supports self-registration. Typically, .OCX and .DLL files are self-registered dynamically on the destination computer by calling self-registration functions. If you mark this check box, Windows Installer registers your .OCX and .DLL files. The .DLL or .OCX may require certain files to be installed already in order to self-register properly. Scanning the advertising information into the advertising tables is recommended over self-registration. z Default to rescan advertising for new components If the advertising information contained in your files might change during the development process, mark this to scan the advertising information and update the installation every time you compile. The scan options in the Advertising Setting field above only read the advertising information that’s present in the file when you first add it to the installation. This field sets the default for new components; if you change it, existing components are not affected. The Rescan advertising information during compile check box on the Component Details dialog box can override this setting for individual components. See also: Setting Options on page 32 Setting Digital Signature Options You can add a digital signature to an installation on the Digital Signature page. You also can add a digital signature to a patch in Patch Creation. The Digital Signature options provide default settings for the Digital Signature page and Patch Creation. These options apply to all future installation and patch files. They do not affect existing files. To set options: Select Tools menu > Options and click the Digital Signature tab. Complete the tab. Windows Installer Editor Reference 37 Setting Up z z Signing with Public/Private Key Pair Files „ Signcode.exe Location Enter the path of the signcode.exe that performs the signing tasks. „ Credentials File Enter the path of the credentials file that contains your Digital ID. „ Private Key File Enter the path of the private key file (.PVK). If this key is lost or stolen, contact your certificate authority immediately. Signing with Personal Information Exchange Files „ Signtool.exe Location Enter the path of the signtool.exe that performs the signing tasks. „ Personal Information Exchange (.pfx) File Enter the path of your Personal Information Exchange file (.PFX). See also: Adding a Digital Signature to a Patch in the Wise Package Studio Help Adding a Digital Signature to an Installation on page 237 Setting Options on page 32 About ExpressBuild ¾ Not available in Standard Edition. Note For multi-processor compile to occur using distributed computers, all source files of the installation must be on a shared drive and must be specified in the installation with UNC paths. (Example: \\SERVER\File.exe). In addition, when you open the installation file, you must open it in such a way that it is referenced by a UNC path. Example: After you select File > Open, browse to the installation underneath the My Network Places icon or type the entire UNC path in the File Name field. These requirements do not apply to using multiple processors within one computer. With ExpressBuild™, you can use multiple processors to speed compile time for large builds. Use multiple processors on the local computer, and use the main processor of multiple distributed computers (called a build group). The processors on the local computer can be physical or virtual processors. You can also set up your own computer to provide processing power for another build computer. ExpressBuild speeds compile time by distributing the time-consuming task of compressing .CAB files among multiple processors. Therefore, the greatest time savings are realized when you have multiple .CAB files. Specify .CAB file creation rules in Installation Expert > Media page. See: Setting ExpressBuild Options How ExpressBuild Groups Work on page 40 Requirements for Using ExpressBuild on page 40 Windows Installer Editor Reference 38 Setting Up Setting ExpressBuild Options ¾ Not available in Standard Edition. If you turn ExpressBuild on, it is turned on globally; that is, it is in effect for all installation files you open, regardless of when they were created. Before you use ExpressBuild, verify that you meet the requirements for using ExpressBuild options and review the reasons why multi-processor compile might not work. See Requirements for Using ExpressBuild on page 40. To set options: Select Tools menu > Options and click the ExpressBuild tab. Complete the tab. You can mark any combination of the three check boxes below. After you mark either of the first two check boxes, compiles will try to use multi-processor compile unless prevented from doing so. If you mark Allow My Computer to Build for Others, your computer is immediately available to assist in compiles being performed on other computers. z Build Using Multiple Local Processors Mark this to have multiple processors within this computer help process compiles. The processors on this computer can be physical or virtual processors. You must also enter the number of local processors in the field below. There are several requirements for using this option. „ z Number of Local Processors Enter the number of physical or virtual processors available on the current computer. Build Using Multiple Distributed Computers Mark this to have more than one computer help process compiles. You must have previously set up a build group to use this option. There are several requirements for using this option. „ Build Group Name Enter the build group name. See How ExpressBuild Groups Work on page 40. „ z Build Group Domain Enter the NT domain name of the build group. All members of a single build group must be in the same NT domain. Allow My Computer to Build for Others Mark this to have this computer be available to help process compiles that are started on another build computer. Performance degrades while this computer helps to process compiles. This causes WiseExpressBuild.exe to start immediately. „ Build Group Name Enter the group name of the build group that your computer will be a member of. If another computer compiles using your build group name, then your processor will be used to help compile. See also: About ExpressBuild on page 38 Windows Installer Editor Reference 39 Setting Up Setting Options on page 32 How ExpressBuild Groups Work ¾ Not available in Standard Edition. You can specify a build group of computers within the same NT domain or workgroup to share processing of compiles. To specify a build group, first you select an arbitrary name for the build group. Then, on those computers that will be part of a build group, you do one of two things: z If Windows Installer Editor is not installed, then run WiseExpressBuild.exe, which is located in the share point directory. The Wise ExpressBuild dialog box opens. Specify the group name and whether the WiseExpressBuild.exe should open at system startup. WiseExpressBuild.exe runs in the background and responds to and manages compile requests from the build computer. You can open it and edit its properties by double-clicking on its icon in the Windows taskbar. z If Windows Installer Editor is installed, open it on that computer. Select Tools menu > Options, click the ExpressBuild tab, and mark the Allow My Computer to Build for Others check box. Then enter the group name of the build group your computer will build for. Do this on each computer that will share processing as part of a single build group. When you click OK on the Options dialog box, the WiseExpressBuild.exe immediately begins running on your computer, with its icon showing in the system tray area of your taskbar. Note Performance slowdowns will occur on computers in build groups when they are called upon to help process compiles. See also: About ExpressBuild on page 38 Setting ExpressBuild Options on page 39 Requirements for Using ExpressBuild Requirements for Using ExpressBuild ¾ Not available in Standard Edition. z In the following instances, because of .CAB formation issues, multi-processor compile does not take place and normal compiling occurs: „ If you select Uncompressed external files from the Compression Option field on the Media page. „ If you select One Cab in the Cab Options field on the Media page, or if the .MSI contains only one .CAB for some other reason. „ If you select any size other than zero in the Max Media Size field on the Media page. „ If you are in a merge module. Windows Installer Editor Reference 40 Setting Up z Because each processor compresses .CAB files, using multiple processors is more efficient if files are arranged into multiple, moderately-sized .CAB files. To achieve this, select One Cab per feature or One Cab per component in the Cab Options field on the Media page. Additional requirements for using the option to Build Using Multiple Distributed Computers: z All the installation source files must be shared so that all members of the build group have network privileges to access them. z The paths to all installation source files must be in UNC notation. Change paths to UNC notation using Tools menu > Convert Source Paths. If any source files have paths to the local drive (Example: C:\MyFiles\File.jpg) then multi-processor compile does not occur. See Source Paths in an Installation on page 315. z The path to the installation file must be referenced in UNC notation. When you open the installation file, open it in such a way that it is referenced by a UNC path. Example: When opening a file, browse to the installation underneath the My Network Places icon or type the entire UNC path in the File Name field. If you browse under the My Computer icon, the path will not be referenced in UNC notation. See also: About ExpressBuild on page 38 Setting ExpressBuild Options on page 39 How ExpressBuild Groups Work on page 40 Setting Installation Expert Options You can set options that control the behavior of Installation Expert. To set options: To set options for Installation Expert, select Tools menu > Options and click the Installation Expert tab. Complete the tab. z View directories for all features on Files page Mark this to display all directories on the Files page, regardless of what feature the directory was created for. Clear this to display only the directories that were created for the current feature (the feature selected in the Current Feature drop-down list.) Example: If you create a directory for FeatureA, and then use the Current Feature drop-down list to go to FeatureB, you no longer see the directory you made for FeatureA. This does not apply to the Web Files page. z View registry keys for all features on Registry page Mark this to display all registry keys on the Registry page, regardless of what feature the registry key was created for. This displays a composite view of all registry keys created for all features. If this check box is not marked, only keys created for the currently selected feature (in the Current Feature drop-down list) are displayed. Windows Installer Editor Reference 41 Setting Up z Show merge module components Mark this to view the files and registry entries from merge modules in Installation Expert. You can only view merge module components in an .MSI. By default, these items are hidden. z Listbox Compatibility Mode If your computer has certain video drivers, you might have problems selecting items from list boxes within Windows Installer Editor. If items that you select from list boxes are continually misinterpreted by Windows Installer Editor, mark this check box to eliminate list box problems. z Expand all features on Features page Display Feature title instead of name on Features page Display hidden features on Features page These check boxes determine how features are displayed on the Features page. You can override these settings using the right-click menu on that page. z Display the page view associated with a project when a project is opened Mark this to display an installation project’s default page view when the installation opens. If you clear this check box, the page view in Installation Expert does not change when you open a project regardless of its associated page view. z Use advanced drawing routines (restart required) If a black box appears at the bottom of the Installation Expert page group list, cutting off the last several pages in the list, mark this check box and restart your computer to eliminate the problem. z Display Project Summary Page when a project is opened Mark this to have the Project Summary page appear when an installation is opened. See also: Setting Options on page 32 Setting Merge Module Directories You can set default directories for storing merge modules. You can store merge modules on a local drive or a shared network drive. When you add a merge module to an installation, you can select from the merge modules in the directories you specify here. When you use the Download Redistributables wizard, you can download merge modules to directories you specify here. You can use merge modules that are in the Software Manager database, which helps ensure that team members always access approved versions of merge modules. (Not available in Standard Edition.) To set options: Select Tools menu > Options and click the Merge Modules tab. You also can access these options when you add a merge module to an installation; click the Directories button on the Select Merge Module dialog box. See Adding a Merge Module to an Installation on page 335. Complete the tab. Windows Installer Editor Reference 42 Setting Up z Default Merge Module Directory Shows the path to the default merge module directory. All merge modules that are in this directory—along with the merge modules that are in the directories shown in the Directory list below—are listed on the Select Merge Module dialog box that appears when you click the Add button at the right of the Merge Modules page. To exclude the merge modules in the default directory from the list, mark Do not show merge modules from the Default Merge Module Directory. z Read Merge Modules List From Software Manager Database (Not available in Standard Edition.) Mark this to include merge modules from the Software Manager database on the Select Merge Module dialog box that appears when you click the Add button on the Merge Modules page. z Directory Enter additional directories where merge modules are stored. Merge modules in these directories are listed on the Select Merge Modules dialog box. Example: If you save your organization’s user-created merge modules in the shared network directory V:\Modules, and you add V:\Modules to the Directory list, the merge modules in that directory will appear on the Select Merge Module dialog box. To add a directory to the list, click Add, browse for the directory, and click OK. To include subdirectories in the search, mark the check box in the Include Subdirs column. The next time you click the Add button on the Merge Modules page, modules in that directory appear on the Select Merge Module dialog box. To delete a directory from the list, click the directory and click Delete. Merge modules in that directory will no longer appear on the Select Merge Module dialog box. See also: Setting Options on page 32 Activating Suppressed Prompts Some of the prompts that appear in Windows Installer Editor contain a Don’t show this message again check box that lets you suppress the prompt in the future. To reactivate prompts that you previously suppressed 1. Select Tools menu > Options and click the Prompts tab. The dialog box lists the prompts you have suppressed and shows your last response to each prompt. If you have not suppressed any Windows Installer Editor prompts, nothing is listed. 2. Select the prompt message line and click Activate. The prompt is removed from the list. The next time you encounter a situation in which that prompt applies, the prompt will appear. See also: Setting Options on page 32 Windows Installer Editor Reference 43 Setting Up Setting Repository Options Use the Repository tab on the Wise Options dialog box to: z (Client installations only.) Connect to a different Wise Software Repository (the share point directory and any databases associated with it). Changing the share point directory or a specific path does not copy resources to the new location. Typically, you will specify a share point or path that is already in use. z Specify the directories that contain shared resources that are used to create and edit Windows Installer installations. Typically, you will use the default locations, but you can set individual share locations for specific resources. See Installation Resources and Their Locations on page 27. To connect to a different repository (Client installations only.) You can connect to a different repository by specifying the share point that is associated with it. When you change the default share point, you are logged off and prompted to log on. Because serial numbers and license assignments are stored in the Workbench database, you must have a different license assignment in the Workbench database that you change to. 1. Select Tools menu > Options. 2. On the Wise Options dialog box, click the Repository tab. 3. Click Browse. 4. On the Browse for Folder dialog box, browse to an existing share point directory and click OK. The Wise Software Repository that is associated with that share point becomes your default. To change a default resource location The resource locations are used for Windows Installer installations only. 1. Select Tools menu > Options. 2. On the Wise Options dialog box, click the Repository tab. 3. Click Advanced. 4. On the Repository Advanced Settings dialog box that appears, double-click one of the following items and browse to a new path. You can use the variable [WiseSharePoint] to represent the share point directory in the following paths. You also can use the predefined variables that appear on the Path Variables page. However, you cannot use other user-defined path variables because they are specific to a single installation and the following paths are global options. „ Windows Installer Editor Reference Component Rules Specify the location of ComponentRules.ini, which contains the rules that govern how components are created in installations. 44 Setting Up Warning If you are sharing component rules, be careful when editing existing rule sets because your changes will overwrite rule sets used by team members. „ Custom Actions Specify the location in which you will save files used in custom actions (examples: WiseScripts, .DLL files, JScript files, and VBScript files) that can be added to installations. This is the default location whenever you browse for a file on a custom action dialog box. „ Default Project Directory Specify the default directory in which all new installations will be saved. The default is the Projects subdirectory of the share point directory. Note Changes in this field do not take effect until you exit and restart the product. „ Dialogs Specify the location of the Wise Standard.MSI that contains information that the New Dialog Wizard uses to add a new dialog box to an installation. „ Languages Specify the location of language resource files. „ Resources Specify the location of the bitmaps and icons that are used in installations. „ Templates Specify the location of installation templates and WfWI macros. „ Themes Specify the location of the themes that are used to customize installation dialog boxes. „ Validation Modules Specify the location of the validation modules (.CUB files) and settings that are used in Package Validation. See also: Setting Merge Module Directories on page 42 Setting Options on page 32 Setting Source Control Options You can set options that enable source control functionality and set the levels of interaction Windows Installer Editor has with your source code control system (SCCS). See Using Source Control on page 305. The Source Control options apply to the current installation and all future installations. Changing these options does not affect existing installations. To set options: Select Tools menu > Options and click the Source Control tab. Complete the tab. Windows Installer Editor Reference 45 Setting Up Note If the following options do not appear on the Source Control tab, you probably don’t have a source code control system on your computer. It could also be that your SCCS is unrecognized or that there are communications problems between the SCCS server and your computer. z Enable source control Mark this to enable all source control functionality both in the current installation and all future installations. When you mark this check box, the following three check boxes are enabled, as well as the items in the Source Control menu. When source control is enabled, you can add files to source control, check files in and out, get the latest version of files, track history, and view differences. z Check out file when it is opened If this is marked, then each time you open a file that has been previously checked in, the file will be automatically checked out for you. If your source code control system is not available, you can cancel attempts to connect and work on the local copy of the file. z Check in file when it is closed If this is marked, then each time you open a file that has been previously checked out, the file will be automatically checked in for you. z Add new files to source control If this is marked, then each time you create a new installation file and save it, you will be prompted to add it to your source code control system. Enabling the source control options above does not implement source control in the installation. It merely enables you to add and remove files from the source code control system, and to check them in and out. Use the options on the Source Control menu to perform these tasks. See also: Setting Options on page 32 Setting Wildcard Groups On the Wildcard Groups tab, you can create groups of wildcards so you don’t have to type multiple wildcards repeatedly. On the Files and Web Files pages in Installation Expert, you use the wildcard groups when you add directory contents. Wildcard groups on the Wildcard Groups tab appear in the Include Wildcards list on the Add Contents and Wildcard Details dialog boxes. Select a wildcard group to add just a subset of the files in the directory whose contents you are adding. Several wildcard groups are predefined, which you can edit. If you delete them, they are recreated when the application starts. Also, wildcards that you enter in any Include Wildcards field are added to the list of wildcard groups. To add a wildcard group so it appears in Include Wildcards 1. Select Tools menu > Options and click the Wildcard Groups tab. 2. On the Wildcard Groups tab, click Add. The Wildcard Group Details dialog box appears. Windows Installer Editor Reference 46 Setting Up 3. Complete the dialog box and click OK: „ Group Name Enter a name to precede the wildcards in the Include Wildcards list. This is a visual identifier to help you quickly find the wildcards in the list. „ Wildcards Enter semi-colon delimited wildcards. (Example: Enter *.EXE;*.DLL for all .EXE and .DLL files. A ? represents any one character.) Later, when you add contents or set automatic updating on the Files or Web Files page, this wildcard group is available from the Include Wildcards list. See also: Setting Options on page 32 Creating and Editing Installation Templates When you create a new installation or merge module, it gets its configuration from a template file. Templates contain logical defaults and commonly used settings. Some template files are predefined and appear when you create a new installation. You also can create your own templates. Example: If all your installations have the same system configuration requirements and document file extensions, you can create a template with these changes preconfigured. Warning Editing predefined templates is not recommended, because they might be overwritten during upgrades. Instead, save customized templates with different names, or make copies of the predefined templates and edit the copies. Template Location Templates are in: z (Standard Edition.) The Templates subdirectory of the Windows Installer Editor installation directory. z (Professional Edition.) The Templates subdirectory of the share point directory. This lets multiple users access the same templates. See Installation Resources and Their Locations on page 27. To create a custom template 1. Select File menu > New. The New Installation File dialog box appears. 2. Select a template file on which to base the new template and click OK. Only icons that have a corresponding file in the Templates directory are templates; other icons cannot be used to create or edit templates. A new installation or merge module opens. 3. Make all the changes that should appear in installations that will be created with this template. Windows Installer Editor Reference 47 Setting Up 4. 5. To include a description that will appear on the New Installation File dialog box when you click this template: a. Select Setup Editor > Product tab. b. Click the Summary icon. c. In the upper-right pane, double-click Comments. d. On the Summary Details dialog box that appears, enter a description of this template in Value and click OK. Save the file: a. Select File menu > Save As. b. Name the file and save it in the Templates directory as a .WSI, .MSI, .WSM, or .MSM. When you save the template, a page view is created with the same name and is listed in the Page Views drop-down list. However, when you use the template to create an installation, the default page view is the page view that was displayed when the template was created. If the template’s default page view is a custom page view, you can customize it. See Customizing Page Views on page 21. 6. To test the new template, select File menu > New. The New Installation File dialog box appears and the file that you just created appears in the Custom Templates category. If the New Installation File dialog box does not contain the new template, verify that you saved it in the correct format and location. 7. Select the template you just created and click OK. 8. Verify that the changes you made in the template are present in this new installation. Component Rules You can select or create rules that help you manage the creation of components in an installation. Using component rules eliminates the need to specify component information for every individual resource you add to an installation and ensures that components are created consistently across all installations. Component rules can also help you align component GUIDs in an upgrade with component GUIDs in previous versions of the installation. When you first create an installation, you select a component rule set to manage components you add to that installation. Then, whenever you add a resource, such as a file, registry key, shortcut, or anything else that can be installed, components are created for those resources in accordance with the rule set you selected. Example: You can always create a new component for each new file added to the installation, or you can group related resources, such as help files, into one component. Two predefined rule sets are provided. You might find that they manage your components satisfactorily and no customization is necessary. If the predefined rule sets do not meed your needs, you can duplicate them and modify the copies as needed, or you can create new rule sets to reflect your organization’s standards. For descriptions of the predefined rule sets, see Microsoft Best Practices Component Rule Set on page 55 Windows Installer Editor Reference 48 Setting Up and One File Per Component Rule Set on page 56. For instructions on creating new rule sets, see Customizing Component Rules on page 52. You can share component rules with others in your organization through a share point directory. Sharing component rules ensures that you always use the most current set of rules and that your installations always adhere to company standards for creating components. To share component rules, in Workbench, select Edit menu > Preferences, click the Repository tab, and click the Advanced button. Make sure a shared directory is specified for the Component Rules path. See Setting Repository Preferences in the Wise Package Studio Help. See also: About Component Rules on page 49 Selecting a Component Rule Set on page 50 Using Component Rules to Align GUIDs in an Upgrade on page 51 About Component Rules A component rule set manages components that are added to installations. z A rule set is a collection of rules. z A rule consists of one or more conditions and one or more actions. z A condition determines the criteria that a resource must meet in order for an action to be performed. Example: If you select the condition Added resource is a Shortcut, the action is only performed for shortcut resources. z An action determines how a resource will be assigned to a component. Rule sets are stored in an .INI file located in the share point directory. You can change the location. See Setting Repository Preferences in the Wise Package Studio Help. Do not try to edit the .INI file other than through the Component Rules dialog boxes. Warning If you are sharing component rules, when you edit existing rule sets your changes will overwrite rule sets used by other members of the team. How Component Rules Are Applied Component rules are applied in the order they appear from top to bottom in the list of rules on the Customize Component Rules dialog box. When a rule has multiple conditions, only resources that meet all the conditions have the rule applied to them. Once an added resource matches the conditions in a rule, the action is applied and no subsequent rules are evaluated for that resource. If you add a resource that does not meet any of the conditions in the rule set, then the Microsoft Best Practices rule set is used for that resource. See also: Component Rules on page 48 Microsoft Best Practices Component Rule Set on page 55 Windows Installer Editor Reference 49 Setting Up Selecting a Component Rule Set Use the Component Rule Selection dialog box to select a rule set and component naming conventions for the current installation or to set the default rule options for all future installations. The component key values you enter on the Component Rule Selection dialog box can be overridden by specific rules. Example: If you use a rule set that contains rules for naming certain types of components, then only the components that do not meet the conditions in the rule set will be named using the component key value options you specify here. To select a component rule set 1. Select Component Rules menu > Select Rule Set. The Component Rule Selection dialog box appears. 2. From Rule Set Name, select the rule set to use for this installation. 3. To make the specified rule set the default for all future installations, mark Make this the default rule set for all Windows Installer files. 4. In the Component Key Values section, select an option from the Default list to determine the naming convention for new components. If the rule set you use specifies the component naming under certain conditions, the naming convention you specify here will be overridden when those conditions are met. „ Set component key to a named Base Select this to name new components with specified text plus an incremental number. Selecting this option enables the Base field. Enter text to serve as a base for the component name (example: Component). Component names will be incremented from this base (example: Component1, Component2, and so on). „ Set component key to key of keypath or first resource Select this to name components as follows: „  If the resource is a file, registry key, or ODBC data source, give the component the same name as the key of the keypath.  For any other type of resource, give the component the same name as the key of the first resource in the component. Set component key to table name of keypath or first resource Select this to give new components the name of the table in which the keypath or first resource resides. If multiple components are named for the same table, an incremental number is added to the component name (example: File1, File2, and so on). 5. From Files, you can select a different naming convention for components that are based on file resources. You can use the long file name of the keypath file, the short file name of the keypath file, or the naming convention specified in the Default field above. 6. To make the options in the Component Key Values section the defaults for all future installations, mark Make this the default key naming convention for all installations. 7. Click OK on the Component Rule Selection dialog box. Windows Installer Editor Reference 50 Setting Up All resources that you add to this installation from this time forward will be organized into components according to the rule set and other conventions you specified. See also: Component Rules on page 48 Using Component Rules to Align GUIDs in an Upgrade Component rules can help you align component GUIDs in an upgrade with component GUIDs in previous versions of the installation. If GUIDS or key paths for the same component don’t match between the new and old .MSI, the component could inadvertently get deleted because Windows Installer does not recognize the components as being the same. Aligning component GUIDs for matching components prevents upgrades from deleting necessary files in the newer version. If you are working on an upgrade installation, you specify the previous versions of the installation on the Previous Installation Versions dialog box. Then, make sure you use a component rule set that contains a rule for aligning component GUIDs with previous versions. Example: The two predefined rule sets contain a rule in which, if the keypath resource matches a resource in the previous .MSI list, the component layout of the previous .MSI is matched and the component key is set to match the previous version. All new resources you add to the upgrade installation will be checked against the previous installations. To ensure that all resources you add to an upgrade installation are aligned with previous versions, specify the previous installation versions before adding any resources to the installation. If you have already added resources to the installation, as is the case when you use a copy of a previous .WSI as a starting point for creating an upgrade installation, you must run UpgradeSync to align GUIDs for existing components. To use component rules to align GUIDs in an upgrade 1. Create or open the upgrade installation. 2. If you have already added resources to the upgrade installation, run UpgradeSync to align GUIDs for existing components. See Using UpgradeSync in the Wise Package Studio Help. 3. Select a rule set to use for this upgrade. See Selecting a Component Rule Set on page 50. Make sure the rule set you select contains a rule for aligning component GUIDs with previous versions; this should be the first rule in the rule set. For best results, use the same rule set, if any, that was used in the previous versions. That way, component creation in the upgrade will be consistent with the previous versions. 4. Select Component Rules menu > Previous Versions. The Previous Installation Versions dialog box appears. 5. On the Previous Installation Versions dialog box, specify the previous versions of this installation. „ Windows Installer Editor Reference To add a previous version .MSI to the list, click Add, click .MSI, and click Open. The .MSI is added to the list. to browse to the 51 Setting Up „ 6. The previous versions will be checked in the order they appear in this list. Click OK on the Previous Installation Versions dialog box. All new resources you add to the upgrade installation will be checked against and aligned with the previous installations you specified. See also: Component Rules on page 48 Customizing Component Rules If the predefined component rule sets do not reflect your organization’s standards, you can create a new rule set. The predefined rule sets, Microsoft Best Practices and One file per component, are read-only and cannot be modified. However, you can copy a predefined rule set and modify the copy. When creating new rules, refer to Microsoft’s rules for creating components. See Organizing Applications into Components and Changing the Component Code in the Windows Installer SDK Help. Warning If you are sharing component rules, when you edit existing rule sets your changes will overwrite rule sets used by other members of the team. To add a new component rule set 1. Select Component Rules menu > Customize. The Component Rules Manager dialog box appears, listing the predefined rule sets and custom rule sets you have created. 2. Click New. The Enter Rule Set Name dialog box appears. 3. Enter a unique Rule Set Name to identify this rule set and click OK. The new rule set name appears and is selected in the Component Rules Manager dialog box. 4. Click Modify. The Customize Component Rules dialog box appears. 5. On the Customize Component Rules dialog box, click Add to add the first rule for this rule set. This starts the Component Rule Wizard, which you step through to add the conditions and actions that comprise the rule. See Adding and Editing Component Rules on page 53. 6. When you finish adding rules to the rule set, click OK on the Customize Component Rules dialog box and then click OK on the Component Rules Manager dialog box. The new rule set is added to the list of available rule sets. To use the new rule set for the current installation or to make it the default for all future installations, you must select it. See Selecting a Component Rule Set on page 50. Windows Installer Editor Reference 52 Setting Up To customize an existing component rule set 1. Select Component Rules menu > Customize. The Component Rules Manager dialog box appears, listing the predefined rule sets and any custom rule sets you have created. 2. Click a rule set. „ To copy the rule set, click Copy, type the new name on the Enter Rule Set Name dialog box, and click OK. „ To modify the rule set, click Modify. The Customize Component Rules dialog box appears, where you can add, edit, and delete rules. See Adding and Editing Component Rules on page 53. Note If you selected a predefined rule set, all the buttons on the Customize Components Rules dialog box are unavailable because the predefined rule sets are read-only. However, you can use this dialog box to view the rules in a predefined rule set. 3. „ To rename the rule set, click Rename, type the new name on the Enter Rule Set Name dialog box, and click OK. „ To delete the rule set, click the Delete button to the right of the rule set name. Click OK on the Customize Component Rules dialog box. See also: Component Rules on page 48 Adding and Editing Component Rules You can add component rules to a rule set, edit existing component rules, and delete component rules. The predefined rule sets, Microsoft Best Practices and One file per component, are readonly and cannot be modified. Warning If you are sharing component rules, when you edit existing rule sets your changes will overwrite rule sets used by other members of the team. To edit a component rule 1. Select Component Rules menu > Customize. The Component Rules Manager dialog box appears, listing the predefined rule sets and any custom rule sets you have created. 2. Click a rule set and click Modify. The Customize Component Rules dialog box appears. „ Windows Installer Editor Reference To add a rule, click Add. This starts the Component Rule Wizard, which lets you define component rules. For details, see the procedure below. 53 Setting Up „ 3. To edit a rule, click the rule in the rules list and click Details. This starts the Component Rule Wizard, which you can step through to change the rule name or change any of the conditions or actions. For details, see the procedure below. When you finish, click OK on the Customize Component Rules dialog box. The Component Rules Manager dialog box reappears. 4. Click OK. To add or edit a component rule 1. On the Name page of the Component Rule Wizard, enter a name for the new rule and click Next. If this is an existing rule, the name is already entered and you can accept or change it. The Conditions page appears. 2. In the Which condition(s) do you want to check? list, mark the check box next to each condition to check. When there are no conditions for performing the action(s) in this rule, select the condition Always perform associated action. As you mark check boxes, the conditions appear in the Rule description list. If you select a condition that is incompatible with a condition you have already selected, the first condition you selected is removed from the list. 3. If a condition contains underlined text, click the underlined text to open a Rule Details dialog box. There you can select a value for the underlined text. Example: If you selected the condition Added resource is a file with name any, you would click the word any and enter a specific file name. Wildcards are allowed. 4. When you have added all conditions that comprise the rule, click Next on the Conditions page. The Actions page appears. 5. In the Which action(s) do you want to perform? list, mark the check box next to the action or actions to perform. The actions you mark appear in the Rule description list. If you select an action that is incompatible with an action you have already selected, the first action you selected is removed from the list. 6. If an action contains underlined text, click the underlined text to open a Rule Details dialog box. There you can specify a value for the underlined text. Example: If you selected the action Set component key to Component, you would click the word Component and enter specific text. 7. When you have added all actions to the rule, click Finish on the Actions page. The Customize Component Rules dialog box reappears. The rule is displayed in the upper list box and its details are displayed in the Rule description list. 8. You can continue to add and edit rules. When you finish, click OK on the Customize Component Rules dialog box. The new rules are added to the rule set and the Component Rules Manager dialog box reappears. 9. Click OK. Windows Installer Editor Reference 54 Setting Up See also: Component Rules on page 48 Microsoft Best Practices Component Rule Set When you use this predefined rule set, components are created using the Microsoft component creation guidelines. See Organizing Applications into Components and Changing the Component Code in the Windows Installer SDK Help. If an added resource does not meet the conditions in a rule, the next rule is evaluated for that resource. If the resource does not meet the conditions in any of the rules, the component is created according to the final rule. z Match components in previous versions of the .MSI If the keypath resource matches a resource in the previous .MSI list, match the component layout of the previous .MSI and set the component key to match the previous version. z Add all executable files to their own components If the added resource is a 32-bit executable file (.DLL, .OCX, or .EXE), create a new component. z Add all .TLB files to their own components If the added resource is a .TLB file, create a new component. z Group Matching .HLP and .CNT files together If resource file names are the same and their file extensions are .HLP or .CNT, add them to the same component. The .HLP will be the keypath file. z Group matching .CHM and .CHI files together If resource file names are the same and their extensions are .CHM or .CHI, add them to the same component. The .CHM will be the keypath file. z Put registry keys associated with files or components in matching components If the added resource is a registry key, and the registry value name or value refers to a file or component, add the resource to an existing component that contains the same type of resource. z Put Current User registry keys in their own component If the added resource is a registry key under HKEY_CURRENT_USER, add the resource to the component matching the conditions and set the component key base to CurrentUser. The component key base will be incremented for each new component matching this condition. Example: CurrentUser1, CurrentUser2, and so on. z Put non-Current User registry keys in their own component If the added resource is a registry key NOT under HKEY_CURRENT_USER, add the resource to an existing component that contains the same type of resource. z Group all non-executable files to their own component If the added resource is not a 32-bit executable file (.DLL, .OCX, or .EXE), add the resource to an existing component that contains the same type of resource. z Name new non-advertised shortcuts by destination directory If the added resource is a shortcut, add it to an existing component containing nonadvertised shortcuts in the same destination directory. Windows Installer Editor Reference 55 Setting Up z Group non-keypath resources by resource type If the added resource cannot be set to the keypath, that is, if it is not a file, registry key, or ODBC data source, add the resource to an existing component that contains the same type of resource. z Create new components for resources not matching other criteria For all other resources that do not match the criteria above, create a new component for the resource and set the component key to the table name of the keypath or the first resource. If multiple components are named for the same table, an incremental number is added to the component name. Example, File1, File2, and so on. See also: Component Rules on page 48 One File Per Component Rule Set When you use this predefined rule set, each file you add to the installation becomes its own component. If an added resource does not meet the conditions in a rule, the next rule is evaluated for that resource. If the resource does not meet the conditions in any of the rules, the component is created according to the final rule. z Match components in previous versions of the .MSI If the keypath resource matches a resource in the previous .MSI list, match the component layout of the previous .MSI and set the component key to match the previous version. z Add all files to their own components If the added resource is a file, create a new component. z Put registry keys associated with files or components in matching components If the added resource is a registry key, and the registry value name or value refers to a file or component, add the resource to an existing component that contains the same type of resource. z Put Current User registry keys in their own component If the added resource is a registry key under HKEY_CURRENT_USER, add the resource to the component matching the conditions and set the component key base to CurrentUser. The component key base will be incremented for each new component matching this condition. Example: CurrentUser1, CurrentUser2, and so on. z Put non-Current user registry keys in their own component If the added resource is a registry key NOT under HKEY_CURRENT_USER, add the resource to an existing component that contains the same type of resource. z Name new non-advertised shortcuts by destination directory If the added resource is a shortcut, add it to an existing component containing nonadvertised shortcuts in the same destination directory. z Group non-keypath resources by resource type If the added resource cannot be set to the keypath, that is, if it is not a file, registry key, or ODBC data source, add the resource to an existing component that contains the same type of resource. Windows Installer Editor Reference 56 Setting Up z Create new components for resources not matching other criteria For all other resources that do not match the criteria above, create a new component for the resource and set the component key to the table name of the keypath or the first resource. If multiple components are named for the same table, an incremental number is added to the component name. Example: File1, File2, and so on. Windows Installer Editor Reference 57 Chapter 3 Working With Wise Installation Files This chapter includes the following topics: z Before You Create an Installation on page 58 z File Types on page 59 z Project Files and Database Files on page 60 z Target Platforms: 32-bit and 64-bit on page 61 z Starting a New Installation (page 69) z Options for New Installations on page 72 z Opening an Installation Package on page 73 z Comparing Windows Installer Files on page 74 z Saving an Installation as XML on page 76 z Working With Installations in the Software Manager Database on page 76 z Compiling An Installation on page 77 z Testing and Running An Installation on page 79 Before You Create an Installation To avoid interruptions during installation development, gather the following information before you begin creating an installation in Windows Installer Editor. z All the files to install on the destination computer. This includes program files, files necessary for optional features, related .DLLs, drivers, and other support files. z Any third-party installations that the installation will provide. Example: Adobe Acrobat Reader. z Which files and other system changes comprise which features. (In Windows Installer, a feature is a distinct part of your application’s functionality. Examples: a spell-checker, a thesaurus, or a collection of clip art.) If the installation will let end users select optional components, you must organize files into features when you create the installation. z A list of the changes that must be made to system information files (examples: .INI files, the registry, and so on) for your application to run properly. z The application’s system requirements in as much detail as possible. Consider not only memory and disk requirements, but also the minimum screen depth and resolution, and the minimum required version of the operating system. z Any custom graphics, referred to as billboards, that should be displayed during installation. z Any changes that should be made to the dialog boxes that will be displayed during installation. Windows Installer Editor Reference 58 Working With Wise Installation Files See Using the Dialogs Page on page 398. z If applicable, a Readme file and a license agreement file. File Types In Windows Installer Editor, you can create and edit different types of Windows Installer database files. You can work in the Windows Installer database file or in a project file that contains instructions for compiling the Windows Installer database file. See Project Files and Database Files on page 60. Following are the types of Windows installer files. Extension Description .MSI Windows Installer database, which is a distributable installation. The .MSI extension is associated with the Windows Installer executable, MSIExec.EXE. When an .MSI is opened, Windows Installer executes it, thereby installing the application. You can open and edit an .MSI in Windows Installer Editor. However, options that have to do with creating an .MSI, such as those on the Releases, Release Settings, and Media pages, are unavailable. You can convert an .MSI to a project file (.WSI). See MSI to WSI Conversion on page 352. .WSI Windows Installer project file, which describes an .MSI but does not store contents. It is in the same format as an .MSI. You edit a .WSI in Windows Installer Editor and compile it to the corresponding .MSI. The .WSI file is smaller than an .MSI and you can set multiple options for the output of the .MSI. .MSM Windows Installer merge module, which is a pre-compiled library of components (files, registry changes, and other system changes) that installs a discrete part of your application. It cannot be run alone, but must be merged with an .MSI during the .MSI compile. See About Merge Modules on page 320. .WSM Windows Installer merge module project, which describes an .MSM, but does not store merge module contents. You edit a .WSM in Windows Installer Editor and compile it to the corresponding .MSM. See About Merge Modules on page 320. .MST Windows Installer transform, which changes a Windows Installer package at run time and must be applied from the command line. See About Transforms on page 338. .MSP Windows Installer patch, which updates an existing installed application. Patches contain only the differences between the old and new versions of an application. Create a patch with the Patch Creation tool, which creates an .MSP file that you distribute to end users. See Patch Creation in the Wise Package Studio Help. .PCP Windows Installer patch project, which describes and compiles to a Windows Installer patch. A .PCP file is created from the Patch Creation tool. See Patch Creation in the Wise Package Studio Help. Windows Installer Editor Reference 59 Working With Wise Installation Files Extension Description .EXE You can compile an .EXE that encapsulates the .MSI or that calls an external .MSI. Doing so gives you the option of pre-installing the Windows Installer runtime before performing your own installation, which ensures that the installation will run. See Setting Build Options for a Release on page 190 and Adding Prerequisites to a Release on page 195. Project Files and Database Files Typically, the installation you distribute is an .MSI. Windows Installer operates on .MSIs, which are a type of relational database that stores installation information and files in tables. See About Microsoft Windows Installer on page 490. On the Build Options page (see Setting Build Options for a Release on page 190) or on the Media page (see Setting Up Media for Distribution on page 207), you can specify to output an installation in different ways: z As a single-file .MSI, which contains compressed installation files. z As an .MSI that has external compressed .CAB files. z As an .MSI that has external uncompressed files. z As an .EXE that contains the .MSI and installation files. z As an .EXE that runs an external .MSI. If you to output an .EXE, you can then pre-install Windows Installer or other runtimes. When you create an installation, you can work in a .WSI (project) file or an .MSI file. The same applies to merge modules; you can work in a .WSM (project) file or an .MSM file. If you work in a .WSI or .WSM (Wise project) If you work in an .MSI or .MSM (Windows Installer database) How are installation files and paths stored? Externally. The project contains paths to the installation files. During compile, they are compiled into the resulting .MSI or .EXE. Inside the database file. Files are refreshed from disk unless Don’t update or recompress files when saving is marked on the Product Details page. Can you create releases? Yes. Use the Releases page and other Release Definition pages. No. Because you are already working in the final output file, options for multiple output files are unavailable, which includes all Release Definition pages. Compiling does what? Reads the project information and compiles a database file (.MSI or .MSM), which contains installation files. Refreshes files from disk unless Don’t update or recompress files when saving is marked on the Product Details page. Windows Installer Editor Reference 60 Working With Wise Installation Files Can you switch from working on one file type to the other? If you work in a .WSI or .WSM (Wise project) If you work in an .MSI or .MSM (Windows Installer database) You can switch from a project file to a database file by compiling the project, opening the resulting database file, and continuing development in the database file. However, an .MSI created by compiling a .WSI does not contain file paths; it contains only the files themselves. Therefore, any files added prior to the switch will not be refreshed from disk because they have no file path. Only those files you add after the switch contain file paths and are refreshed from disk. Use MSI to WSI Conversion to convert an .MSI to a .WSI. It extracts installation files from an .MSI, saves them to disk at locations you specify, and creates a .WSI that points to those files. See MSI to WSI Conversion on page 352. Target Platforms: 32-bit and 64-bit Windows Installer Editor supports the following types of installation packages: z 32-bit installations that contain only 32-bit components z 64-bit installations that contain only 64-bit components z 64-bit installations that contain some 32-bit components Windows Installer Editor supports both x64 (for AMD64 and Intel EM64T processors) and 64-bit Itanium platforms. z An Itanium installation will not run on an x64 platform, and vice versa. z A 64-bit installation will not run on a 32-bit platform. z A 32-bit installation will run on any 32-bit or 64-bit platform. Developing 64-bit Installations on a 32-bit Computer You can develop a 64-bit installation on a 32-bit computer, with these limitations: z On the Registry page, you cannot browse the 64-bit registry in the upper list boxes. However, you can add 64-bit registry keys in the lower list boxes, and you can import .REG files that contain 64-bit keys. z You cannot test, run, or debug a 64-bit installation on a 32-bit computer. See: How to Specify the Target Platform on page 62 What’s Different in a 64-bit Installation? on page 62 32-bit Applications on 64-bit Computers on page 64 Guidelines for Creating Platform-Specific Installations on page 65 Creating Multiple, Platform-Specific Installations from One Project File on page 66 Using 64-Bit Windows Installer Packages in the Windows Installer SDK Help Windows Installer Editor Reference 61 Working With Wise Installation Files How to Specify the Target Platform The target platform is stored in the Template Summary property of the .MSI or .MSM (merge module). For an installation to run, the platform in the Template Summary property must match the platform of the destination computer. The Template Summary property of the .MSI is set during compile based on the release’s Target Platform setting. The initial target platform for the Default release is set by the Target Platform option on the New Installation File dialog box. If the release’s Target Platform setting is then the Template Summary property value is 32-bit Intel 64-bit (x64) x64 64-bit (Itanium) Intel64 Viewing the Template Summary Property This setting is visible under Setup Editor > Product tab > Summary. Do not change the target platform setting there. When an installation project (.WSI) contains multiple releases that compile to 32-bit and 64-bit .MSIs, the Template Summary property reflects one platform or the other. The correct Template Summary property is set in each .MSI during compile. See Template Summary Property in the Windows Installer SDK Help. Additional Target Platform Settings z Feature Details dialog box To display this dialog box, double-click a feature in Installation Expert > Features page. At run time, the destination computer’s platform determines whether a feature is available for installation. (Example: On a 64-bit destination computer, a feature that is designated as 32-bit does not appear to the end user and is never installed.) This setting is used primarily to organize components by feature in a 64-bit installation that contains 32-bit components. See Configuring a Feature Using the Feature Details Dialog on page 96. z Component Details dialog box To display this dialog box, select Setup Editor > Components tab, right-click a component, and select Details. The 64-bit component check box designates a component as 64-bit. This is marked when you add 64-bit .EXE and .DLL files or 64-bit registry keys. If this is not marked, the component is registered as a 32-bit component. What’s Different in a 64-bit Installation? A 64-bit installation differs from a 32-bit installation in the following ways: Windows Installer Editor Reference 62 Working With Wise Installation Files General Information page The minimum version of Windows Installer is set to 2.00 in the Installer Version field. Do not override this setting in a 64-bit installation, because 64-bit installations are not supported by Windows Installer versions earlier than 2.0. Setup Editor > Product Tab > Summary icon The Template Summary property is set to x64 or Intel64, which indicates the platform that is supported by the installation. Condition Builder Condition Builder contains additional property values: z VersionNT64, which is set when the installation runs on a 64-bit platform. z Intel64, which is set when the installation runs on an Itanium platform. z Msix64, which is set when the installation runs on an x64 platform. Files Page Additional predefined directories appear in the lower-left list box: Program Files (x86) and Windows\SysWOW64. These are for 32-bit components in a 64-bit installation. See Installation Directories on page 108. Setup Editor > Tables tab The Directory table contains additional, 64-bit specific folders. Registry page z The upper list boxes can display the 32-bit or 64-bit registry. The 64-bit registry is visible only if your computer is running a 64-bit operating system. z The lower list boxes can display the 32-bit or 64-bit registry on any computer. z You can add registry keys and values to the 32-bit or 64-bit registry on any computer. See Registry Page on page 138. Component Details dialog box For a 64-bit component, the 64-bit component check box is marked and the Condition field contains (VersionNT64). See Adding and Editing a Component on page 370. System Search page The Read Registry Value dialog box, which you access from the System Search page, contains a check box that lets you include 64-bit components in a registry value search. See Searching For a Registry Value on page 171. Prerequisites page In a 64-bit installation, you can specify a prerequisite for the x64 or IA64 (Itanium) edition of version 2.0 of the .NET Framework. To download these runtimes, use the Wise Web Site option of the Download Redistributables wizard. Windows Installer Editor Reference 63 Working With Wise Installation Files Custom actions Windows Installer Editor does not contain 64-bit versions of custom actions, however: z When you create a custom action that calls a JScript or VBScript file, a check box lets you indicate that the script needs to access 64-bit functionality and run in a 64bit process. z The following Call Custom DLL actions can call 64-bit .DLLs: Call Custom DLL From Destination Call Custom DLL From Installation Call Custom DLL From Installed Files Because .DLLs are processor-specific, the .DLL that you call must target the same platform (32-bit, x64, or 64-bit Itanium) as the installation. In a mixed-target project file (.WSI), condition each Call Custom .DLL custom action for the appropriate platform. 32-bit Applications on 64-bit Computers WOW64 (Windows On Windows 64) is an emulator that lets 32-bit applications run on 64-bit versions of Windows. To prevent file and registry collisions, it isolates 32-bit applications from 64-bit applications by: z Redirecting 32-bit applications to the Program Files (x86) directory. z Redirecting system calls from 32-bit applications to the SysWOW64 directory. z Providing separate logical views of key portions of the registry, intercepting 32-bit registry calls to each logical registry view, and mapping them to the corresponding physical registry location. The reflection process is transparent to the application. Therefore, a 32-bit application can access registry data as if it were running on 32bit Windows even if the data is stored in a different location on 64-bit Windows. When an installation contains both 32-bit and 64-bit components, place files and registry keys in the appropriate location for the platform they target. Resource Place 32-bit versions in Place 64-bit versions in Program files (default directory) Program Files (x86) directory Program Files directory Operating system components and shared libraries Windows\SysWOW64 directory Windows\System32 directory Registry keys Do one of the following: Do one of the following: z z Place the keys in the 32bit registry view. They will be installed in the WOW6432Node (for hives that have a WOW6432 node). z Place the keys in the 62-bit registry view. z Mark the component as 64-bit on the Component Details dialog box. Do not mark the component as 64-bit. Search for “Running 32-bit Applications” and “WOW64 Implementation Details” in the MSDN Library (msdn.microsoft.com/library/). Windows Installer Editor Reference 64 Working With Wise Installation Files Guidelines for Creating Platform-Specific Installations The following guidelines refer to creating installations in Windows Installer Editor. For more general guidelines, see Using 64-Bit Windows Installer Packages in the Windows Installer SDK Help. 32-bit Installations That Contain Only 32-bit Components z On the New Installation File dialog box, select 32-bit as the target platform. This sets the initial target platform for the Default release. z Set the target platform for all features to 32-bit. A 64-bit feature in a 32-bit installation will never be installed. z Add resources to the installation as usual. Do not add 64-bit components to a 32-bit installation. z Set the target platform for all releases to 32-bit (this is the default). 64-bit Installations That Contain Only 64-bit Components z On the New Installation File dialog box, select one of the 64-bit options as the target platform. This sets the initial target platform for the Default release. z Select the appropriate 64-bit target platform for all features. z Add resources to the installation as usual. When you add 64-bit .EXE and .DLL files or 64-bit registry keys, they are designated as 64-bit components. (The 64-bit component check box is marked on the Component Details dialog box.) z Select the appropriate 64-bit target platform for all releases. z AMD 64-bit computers require Windows Installer version 3.0 or later. If your installation targets AMD 64-bit computers, include a system requirement to check the destination computer’s Windows Installer version. 64-bit Installations That Contain Some 32-bit Components z Select the appropriate target platform for each feature, and add the correct type of component to each one. Do not add a 64-bit component to a 32-bit feature, and vice versa, because it will never be installed. When you add 64-bit .EXE and .DLL files or 64-bit registry keys, they are designated as 64-bit components. (The 64-bit component check box is marked on the Component Details dialog box.) When you add 32-bit files or registry keys, the 64bit component check box is not marked. z Select the appropriate target platform for each release. z AMD 64-bit computers require Windows Installer version 3.0 or later. If your installation targets AMD 64-bit computers, include a system requirement to check the destination computer’s Windows Installer version. You can create a single installation project (.WSI) that can produce 32-bit and 64-bit installation files. See Creating Multiple, Platform-Specific Installations from One Project File on page 66. Platform-Specific Merge Modules z A 32-bit merge module can be merged into a 32-bit or 64-bit installation. Windows Installer Editor Reference 65 Working With Wise Installation Files z A 64-bit merge module can be merged into a 64-bit installation. The processor type (x64 or Intel64) of the merge module must match that of the installation. See also: How to Specify the Target Platform on page 62 Using 64-bit Merge Modules in the Windows Installer SDK Help Creating Multiple, Platform-Specific Installations from One Project File You can create a single installation project (.WSI) that can produce 32-bit and 64-bit installation files, or x64 and Itanium installation files. Example: You develop a graphics suite that consists of features for drawing, graphing, and page layout. The application was originally developed as a 32-bit application, and you will continue to support a 32-bit version, but you also will release a version that contains some 64-bit components. To save development time, you want to maintain a single installation project (.WSI) that can produce installation files for both platforms. Your options are: z Organize the project by feature. Do this to let the end user choose from different platform-specific features during installation. In a large installation, this method will work better than organizing the project by component. Note If you add a 64-bit component to a 32-bit feature, it will never be installed. A 64-bit component will be ignored during installation on a 32-bit computer, and a 32-bit feature will not be installed on a 64-bit computer. z Organize the project by component. This method results in fewer features and possibly less duplication. However, in a large installation, it might be less efficient to have to assign a target platform to each component. To organize a mixed-platform project by feature 1. On the New Installation File dialog box, select x64 as the target platform. 2. On the Features page, create separate features for the different target platforms. Example: This feature is used by both versions. 3. When you add files, registry keys, and other resources to the installation, be sure to select the appropriate feature. Example: Add Chart32.exe to the Charting32 feature, and add Chart64.exe to the Charting64 feature. Windows Installer Editor Reference 66 Working With Wise Installation Files 4. In MSI Script, add a custom action to set the value of the INSTALLDIR property. See Defining the INSTALLDIR Property in a Mixed-Platform Installation on page 68. 5. On the Releases page, create a release for each target platform. Example: Graphic32, Graphic64. 6. On the Release Settings page, select the features to include in each release. Example: Select the 64-bit release Select the features to be installed on 64-bit platforms 7. Compiling the project creates the following .MSIs: „ Graphic32.msi, which runs installs only 32-bit components and runs on any platform. Its Template Summary property is set to Intel, which represents a 32bit installation. „ Graphic64.msi, which installs both 32-bit and 64-components and runs on x64 platforms only. Its Template Summary property is set to x64. To organize a mixed-platform project by component 1. On the Features page, create a single set of features and set their target platform to All Processors. Example: 2. When you add files, registry keys, and other resources to the installation, put both 32-bit and 64-bit items in a single feature. Example: Add both Chart32.exe and Chart64.exe to the Charting feature. 3. In MSI Script, add a custom action to set the value of the INSTALLDIR property. See Defining the INSTALLDIR Property in a Mixed-Platform Installation on page 68. 4. On the Releases page, create a release for each target platform. Example: Graphic32, Graphic64. Windows Installer Editor Reference 67 Working With Wise Installation Files 5. On the Release Settings page, select the components to include in each release. Example: Select the 64-bit release. Select the features to be installed on 64-bit platforms. Within each feature, select the components to be installed on 64-bit platforms. 6. Compiling the project creates the following .MSIs: „ Graphic32.msi, which installs only 32-bit components and runs on any platform. Its Template Summary property is set to Intel, which represents a 32-bit installation. „ Graphic64.msi, which installs both 32-bit and 64-components and runs on 64bit platforms only. Its Template Summary property is set to x64. See also: Configuring a Feature Using the Feature Details Dialog on page 96 Customizing a Release on page 185 Defining a Feature and Component Set for a Release on page 187 Defining the INSTALLDIR Property in a MixedPlatform Installation The INSTALLDIR build property represents the main installation directory for the application. By default, it is set to the first directory you create under the Program Files folder on the Files page. A mixed platform project has two installation directories: one under Program Files and another under Program Files (x86). However, the INSTALLDIR property can have only one value. To see this, go to the Files page and view the subdirectories of Program Files and Program Files (x86); only one will be designated as the INSTALLDIR. To define the second installation directory, add a custom action to set the default value of INSTALLDIR based on the destination computer’s platform. Place the custom action at the beginning of the installation initialization. You only need a custom action for the undefined installation directory. Windows Installer Editor Reference 68 Working With Wise Installation Files Example: The installation directory is Program Files (x86)\QuickFacts. In MSI Script, enter the following custom action: If VersionNT64 then Set Property INSTALLDIR to [ProgramFiles64Folder]\QuickFacts End If the destination computer’s target platform is 64-bit, then the default installation directory is Program Files\QuickFacts. If it is 32-bit, then the original installation directory is used. See also: Creating Multiple, Platform-Specific Installations from One Project File on page 66 About MSI Script on page 436 Custom Action Reference on page 456 Starting a New Installation Follow the steps below to create a new standard Windows Installer installation. You can create other types of installations. See Options for New Installations on page 72. To start a new installation 1. In Wise Package Studio, do one of the following: „ On the Projects tab, click the Run link to the right of the task or tool associated with Windows Installer Editor. The installation associated with the current project might be opened by default. This tool might open to a different view based on command-line options defined in Process Templates Setup. „ On the Tools tab, double-click Windows Installer Editor. The New Installation File dialog box appears. If it does not appear, select File menu > New. 2. In the Categories list, click Predefined Templates. 3. In the Templates/Tools list, click the Windows Application icon. A Windows Application installation is a standard installation intended for a Windows computer or server. 4. In the File type section, specify the type of file to create: „ Create an .MSI (Windows Installer database), which is a distributable installation. „ Create a .WSI (Windows Installer project), which contains instructions for compiling an .MSI. See Project Files and Database Files on page 60. 5. Select a target platform: 32-bit, 64-bit (x64), or 64-bit (Itanium). See How to Specify the Target Platform on page 62. 6. If the application has been written to be installed and run by standard users without elevation, mark Create a Vista Standard User Installation. This clears the Windows Installer Editor Reference 69 Working With Wise Installation Files Enable User Account Control (UAC) check box in Installation Expert > Windows Installer Options page. See Creating an Installation for Standard Users on page 70. 7. Click OK. The new installation opens. About Standard User Installations ¾ Windows Installer 4.0 or later only. The User Account Control (UAC) that was introduced with Windows Vista provides a temporary privilege-elevation model. A standard user installation is one in which the UAC is disabled so that standard users can install it without elevation. The installation cannot contain actions that access a protected area on the destination computer. During development, a standard user installation behaves as follows: z z Windows Installer Editor warns you when you make a change in the installation that is incompatible with a standard user installation: „ On the Files page, the default installation folder in the lower-left list box is Windows\Profiles\Local Settings\Application Data instead of Program Files. „ On the Files page, a warning message appears when you try to add a file to a protected area. „ On the Registry page, a warning message appears when you try to add a registry key to a protected area. The DisableUAP property is set, which hides the option to install for all users or the current user on the installation’s User Information dialog box. See Creating an Installation for Standard Users on page 70. At run time, a standard user installation behaves as follows: z The Destination Folder dialog box does not appear because letting the end user change to a directory that is not per-user would cause the installation to fail. z The User Account Control dialog box that prompts end users for administrator credentials does not appear. z If the installation tries to access a protected area, it fails. Installations that were created in a Wise product earlier than Wise Package Studio 7.0 SP1 or Wise Installation Studio 7.0 run as if User Account Control is enabled. See also About UAC Elevation of Windows Installer Installations on page 176. Creating an Installation for Standard Users ¾ Windows Installer 4.0 or later only. A standard user installation is one in which the UAC is disabled so that standard users can install it without elevation. The installation cannot contain actions that access a protected area on the destination computer. See About Standard User Installations on page 70. Windows Installer Editor Reference 70 Working With Wise Installation Files To create a standard user installation 1. Do one of the following: „ In Installation Expert > Windows Installer Options page, clear the Enable User Account Control (UAC) check box. See Setting Version-Specific Windows Installer Options on page 174. „ 2. On the New Installation File dialog box, mark Create a Vista Standard User Installation. This clears the Enable User Account Control (UAC) check box in Installation Expert > Windows Installer Options page. As you develop the installation, do not access or install to protected areas. Example: the Program Files or Windows System directories, or the HKLM or HKCR sections of the registry. Creating a Device Driver Installation You can create an installation that supports Microsoft Driver Install Frameworks (DIFx). Microsoft created the Driver Install Frameworks to significantly improve the quality of device driver installations. For information on DIFx, search for “DIFx” in the MSDN Library (msdn.microsoft.com/library/). The Microsoft DIFxApp merge module simplifies the process of creating installations that install device drivers. This merge module adds custom actions to the installation that are needed to install and uninstall the driver package using Driver Install Frameworks for Applications (DIFxApp). After you add the merge module, you add the files that make up the driver package and specify the DIFxApp options for installing the driver. To create a device driver installation 1. Use the Download Redistributables wizard to download the latest version of the DIFxApp merge module from the Wise Web site, if you have not already done so. See Downloading Redistributable Files on page 29. Note Early versions of this merge module might be named “Binaries.” 2. Make sure the device driver you are installing meets the Microsoft DIFx driver requirements. 3. Do one of the following: „ Start a new installation and select the Device Driver icon on the New Installation File dialog box. See Starting a New Installation on page 69. „ 4. Open an existing installation. On the Merge modules page, add the Microsoft DIFxApp merge module to the installation. See Adding a Merge Module to an Installation on page 335. 5. On the Features page, add a feature for the installation’s driver package. See a Adding a New Feature on page 94. 6. On the Files page, do the following. See Adding Files to an Installation on page 109. Windows Installer Editor Reference 71 Working With Wise Installation Files a. Select the driver package feature. b. Create a unique directory for the driver package. c. Add the driver package’s .INF file to the directory you created. d. The driver package’s .INF file must be the first file added to this directory so that it becomes the key path of the component. e. Add the other files that make up the driver package to the same directory that contains the .INF file. f. In the lower-right list box, double-click the .INF file. g. The File Details dialog box appears. h. Click the Driver tab and edit the DIFxAPP options. See Editing DIFxApp Options on page 132. 7. To add additional driver packages repeat the preceding steps, except for adding the DIFxApp merge module. 8. Continue developing the installation. Options for New Installations When you create a new installation, the New Installation File dialog box appears and provides options for starting an installation. Most of the options use a template to start a specific kind of installation. If you have created custom templates, they appear as additional options for new installations. See Creating and Editing Installation Templates on page 47. This section describes the options that are available. Windows Application Creates a standard installation with default settings. See Starting a New Installation on page 69. Device Driver Creates an installation that installs a device driver. This template supports Microsoft Driver Install Frameworks (DIFx). Use it with the DIFxApp merge module that adds custom actions to the installation that are needed to install and uninstall the device driver package using Driver Install Frameworks for Applications (DIFxApp). See Creating a Device Driver Installation on page 71. Web Application Creates an installation intended to be run on Microsoft Internet Information Server (IIS). See About Web Installations on page 242. Server Application Creates an installation intended to be run on Microsoft IIS, with an additional dialog box for recording logon information. Windows Installer Editor Reference 72 Working With Wise Installation Files See Obtaining Logon Information From a Dialog on page 421. Windows Mobile Opens the Windows Mobile wizard, which lets you add Windows Mobile .CAB files to a desktop installation. The wizard is also accessible from the Mobile Devices page. See Adding Windows Mobile Files on page 217. Palm Application Opens the Palm OS wizard, which lets you add Palm OS files to a desktop installation. The wizard is also accessible from the Mobile Devices page. See Adding Palm OS Files on page 220. Transform Lets you change any aspect of an installation by creating a transform based on changes that you make to the installation. See Creating a Transform Based on an Existing .MSI on page 339. Universal Transform Lets you create a universal transform containing limited changes that can be applied to any .MSI. See Creating a Universal Transform on page 341. Merge Module See Creating a Merge Module As a New Installation on page 325. Import Tools The following tools open an import wizard, where you select a development project file to import. Target file information is extracted from the project file and added to the installation. See Import Visual Studio Projects on page 349. z Visual Basic z Visual C# z Visual J# Opening an Installation Package The Open dialog box might contain the following tabs that let you open different items: z File System tab: Opens a package from a directory on your computer. z Repository tab: Opens a package from the Wise Software Repository. The Repository tab on the Open dialog box provides a centralized list of installation packages and eliminates the need to navigate your file system to find an installation file. When you select a package from the repository: „ The package opens from its location in the repository. Typically, this is the Scripts, Projects, or Available Packages directory. Windows Installer Editor Reference 73 Working With Wise Installation Files „ If the package status is Available, you are prompted to change the status to Under Development. Warning Use caution when changing available packages, because they might have been deployed to end users. „ If you try to save the package, a prompt asks if you want to overwrite the file that is in the repository. „ If the package is checked into the Software Manager Revision Control, you might see additional prompts when you try to edit or save it. To open a package from a directory: Click the File System tab on the Open dialog box and navigate to a package. This is the same as the standard Windows Open dialog box. To open a package from the Wise Software Repository 1. Click the Repository tab on the Open dialog box. Packages are displayed in the list box if they have a valid path to an installation file (.MSI, .WSI, and so on). If a package’s path to its installation file is missing or broken, or is not accessible by the current computer, that package is not listed. Also, subscription packages are not listed. 2. Database displays the current Software Manager database. To select a package from a different database, click . The Select Data Source dialog box appears. This is a standard Windows ODBC connection wizard, which lets you connect to a database through an ODBC data source. 3. 4. Specify criteria for filtering the packages that are displayed above: „ Groups This lists the groups defined in Software Manager. „ Status This lists the possible package statuses. „ Package Type This lists the available package types. Select a package in the list and click Open. If you change an installation that you opened from the repository, re-import it into the Software Manager database. Otherwise, changes will not be reflected in the repository. The Select Data Source dialog box appears. This is a standard Windows ODBC connection wizard, which lets you connect to a database through an ODBC data source. Comparing Windows Installer Files Visual MSIDiff™ lets you compare the following types of files and see the differences in Setup Editor > Tables tab: .MSI, .WSI, .MSP, .MSM, .WSM, or .MST files. You can compare an .MSP file only with its base .MSI. Windows Installer Editor Reference 74 Working With Wise Installation Files Note Revision Control in Software Manager runs Visual MSIDiff to compare versions of a package. (Not available in Standard Edition.) See Revision Control in the Software Manager Help. Options for Comparing Files z Compare the current file to another file. z Compare any two files. z Compare a transform to its base .MSI, to see the items that the transform changes in the .MSI. To view differences between two Windows Installer files 1. Open a file. 2. Select Tools menu > Visual MSIDiff and then select an option. „ Compare Current File to Another File The Compare Windows Installer Files dialog box appears. Specify the file to compare to the current file. To have the file you specify in Compare To treated as the newer file in the comparison, mark the dialog box’s check box. To compare an .MSP to an .MSI, the current file must be the .MSI. An .MSP is always treated as the newer file. Click OK. „ Compare Any Two Files The Compare Windows Installer Files dialog box appears. Specify the files to compare. The file you specify in the Base File field becomes the current file. To compare an .MSP to an .MSI, the Base File must be the .MSI. To have the file you specify in Compare To treated as the newer file in the comparison, mark the dialog box’s check box. An .MSP is always treated as the newer file. Click OK. „ Compare Transform to Base .MSI (Transform files only.) Automatically compares the .MST to its base .MSI. You are taken to Setup Editor > Tables tab and the Visual MSIDiff Key dialog box appears, which describes icons that indicate changes. Changes are shown in the tables and rows where they occur. 3. On the Visual MSIDiff Key dialog box, take note of the symbols and colors that indicate changes and click OK. If the Visual MSIDiff Key dialog box does not appear, you might have marked its Do not show this dialog again check box. You can reactivate this prompt in Wise Options. 4. Scroll through tables on the Tables tab, looking for the symbols for changed tables. Click on changed tables to view differences in rows, which are indicated by symbols and colors. As you work in the installation file, the symbols indicating changed items are updated dynamically. The compare stays on until you end it. 5. To end the compare, select Tools menu > Visual MSIDiff > End Current Compare. This turns off compare symbols and closes the comparison file. Windows Installer Editor Reference 75 Working With Wise Installation Files You can also start Windows Installer Editor in the Visual MSIDiff mode from a command line. See Command Line Options For WFWI.EXE on page 235. See also: Tables Tab on page 376 Saving an Installation as XML You can save a copy of an installation (.WSI, .MSI, WSM, or .MSM) in XML format. This lets you check the XML version of the installation into a text-based source code control system (SCCS), use text-based file comparison tools to find changes, or perform analyses with XML reporting tools. You can set a global option in Wise Options to create an XML copy every time you save an installation file, or you can export to an XML file on an as-needed basis. Depending on the size of the installation file, creating an XML copy can take several minutes. You cannot open an XML-format file in Windows Installer Editor. To create an XML file during saves Use this method when you plan to check the XML file into an SCCS from Windows Installer Editor. This ensures that the XML copy is always synchronized with the original installation file. 1. Select Tools menu > Options and click the General tab. 2. Mark the Create XML copy during save check box. This global option causes an XML copy to be created every time you save an installation file. The copy has the same name as the installation file with the extension .XML appended, and it is saved in the same directory. (Example: If the current file name is Application.wsi, the XML copy is named Application.wsi.xml.) To export an XML file as needed Use this method when you do not have an integrated SCCS, or to compare the version of the installation you’re working in to the version that you checked out of your SCCS. 1. Select File menu > Export to XML. 2. In the Save As dialog box that appears, specify a file name with the extension .XML and click Save. If you have not named the installation file yet, name and save the installation file on the Save As dialog box. When the Save As dialog box reappears, specify the .XML file. The current installation is saved and exported to XML format. Working With Installations in the Software Manager Database There are restrictions on editing and saving an installation that has been added to the Software Manager database (either by adding its meta data or importing it). Windows Installer Editor Reference 76 Working With Wise Installation Files When the package path matches a package in the database If you open an installation file and the Software Manager database contains a package with the same package path, the application and package names on the Product Details page are unavailable. This is because the installation is connected to the package in the database. You can only edit these names on the Package Attributes dialog box in Software Manager. If you edit the installation’s meta data, the meta data in the database is updated when you save the installation. If you change the installation, re-import it to the Software Manager database to update its resources. Opening a copy of a package in the database If you open an installation file that is a copy of a package in the Software Manager database, the application and package names are populated and enabled. Change one or both of these names before saving the installation to avoid overwriting the package in the database. Then, when you then save the installation, a new package and its meta data are added to the Software Manager database. Example: You want to create a patch for an installation that is in the Software Manager database. You open a copy of the installation file to change it. Before you save the installation, you change its package name on the Product Details page. When you save the installation, a new package with the same application name, and its meta data, are added to the database. Duplicate package in Software Manager Database dialog box If you open an installation file that is a copy of a package in the Software Manager database, and you don’t change the application and package name on the Product Details page, the Duplicate Package in Software Manager Database dialog box appears when you try to save the installation. Select an option and click OK: z Create a New Package (recommended) Mark this to create a new package in the Software Manager database. The Product Details page opens so that you can change the application or package name before saving the installation file. z Overwrite Existing Package Mark this to overwrite the package in the Software Manager database. The meta data of the package in the database is overwritten, and its resources are removed from the database. z Work Disconnected Mark this to keep the installation file disconnected from the Software Manager database. When you save the installation, its meta data is not added to the database. To connect the installation file to the Software Manager database, change the application or package name on the Product Details page and save the installation. A new package and its meta data are added to the database. Compiling An Installation Compiling an installation compresses its files, builds .CABs if necessary, and creates the installation .MSI. Depending on the .EXE option you select on the Build Options page, compiling can also create an installation .EXE. Windows Installer Editor Reference 77 Working With Wise Installation Files Multiple Releases The number and type of files that are generated depend on the settings you select on the Build Options and Media pages. If the installation contains multiple releases, all releases in the installation are compiled. To compile a specific release, go to the Releases page, select one or more releases, and click the Compile button at the right of the Releases page. Speeding the Compile If you are working in a .WSI or .WSM file, you can use either of the following methods to speed the compile process: z Mark the Enable Quick Compile check box in Wise Options. Quick Compile compresses only previously uncompressed or changed files. If a file or media entry has changed, a full compile occurs instead. See Setting General Options on page 33. z Use ExpressBuild, a multi-processor compile feature. See About ExpressBuild on page 38. To compile an installation 1. Click Compile at the lower right of the main window. 2. Select the type of compile from the button menu. (Not available in Standard Edition.) With Enterprise Management Server, Security Setup determines whether these options appear. z Local Compile The package is compiled locally. If the installation contains files that have missing or invalid source paths, the Welcome dialog box of the Remove Missing Files tool appears. This lets you remove those files if they should not be in the installation. See Removing Files With Missing or Invalid Source Paths on page 357. z Remote Compile The package is compiled on the Wise Package Studio server and the operation is managed by the Wise Task Manager. The package must be in the share point directory, and its source files must have UNC or relative paths. Before the package is compiled, it is saved and closed in Windows Installer Editor. See Wise Task Manager in the Wise Package Studio Help. Compile Results If you are working in an .MSI or .MSM, compiling saves the file. If file paths are stored in the .MSI, compiling first refreshes the files with the latest version. If files cannot be read, or other errors occur, errors are listed in the Task List. Use the Task List to determine the source of the errors. See Using the Task List on page 24. If you see messages that files are missing, you can suppress the file refresh by marking the Don’t update or recompress files when saving check box on the Product Details page. Windows Installer Editor Reference 78 Working With Wise Installation Files If merge modules are missing, you can download them using Help menu > Download Redistributables. See also: Testing An Installation on page 79 Running An Installation on page 80 Running the Debugger on page 433 Testing and Running An Installation To test an installation, you can: z Test the installation, which appears to run but does not install files or change the system. See Testing An Installation on page 79. z Debug the installation in an .MSI debugger, which lets you step through the installation while viewing the property values and other table data. This actually runs the installation, and lets you see exactly what it is doing at any time. See Running the Debugger on page 433. z Run the installation on your computer, which installs files and changes the system. See Running An Installation on page 80. z Run the installation and install it into a virtual layer. After you test the installation, you can then delete the layer to restore your computer to its original state. See Running An Installation on page 80. Note When working in a .WSI, you can set the installation to generate more than one installation program by adding releases to the Releases page. If you test, debug, or run an installation that contains multiple releases, you are prompted to select a release. Testing An Installation You run an installation in test mode, which does not install files or change the system. This lets you run through the user interface and logic of an installation without making changes. To test an installation 1. Click Test at the lower right of the main window. 2. If you have added command lines to the Command Line page, a menu appears with further options. The menu contains the names of all command lines you created. You can test with a command line by selecting its name. To avoid having to select from the button menu, press Ctrl+T to test with no command line. 3. If you are working in a .WSI that contains multiple releases, you are prompted to select one. The installation is compiled and run in test mode. Windows Installer Editor Reference 79 Working With Wise Installation Files Note If you change the installation and then test it, but the change is not apparent, close the installation. Reopen it and compile it, and then run it again. Testing a transform or merge module You cannot test a transform or a merge module by itself. It can only be run in conjunction with an .MSI. To run a transform or merge module, run the base .MSI from the command line with the appropriate command-line options, which are documented in the Windows Installer SDK Help. See also: Compiling An Installation on page 77 Running An Installation on page 80 Running the Debugger on page 433 Running An Installation When you run an installation, you can either: z Install it on your computer. This runs the installation as it would run on the destination computer and makes changes to your computer. z Install it into a virtual layer. This creates a new virtual layer, installs the .MSI into the layer, and activates the layer. After you test the installation, you can delete the virtual layer to restore your computer to its original state. (Not available in the Visual Studio integrated editor.) To perform side-by-side testing of two versions of an application without them interfering with each other, install one version into a virtual layer and the other version on your computer. To run an installation and install it on your computer 1. Click Run at the lower right of the main window. 2. Select the type of installation from the button menu: „ Force Reinstall Normally, if an application is installed and you try to install it again, Windows Installer prompts you to remove it. This option uses command lines to bypass the uninstall. Existing resources are replaced, and new resources are laid down. (The command line msiexec.exe /FAMSUV [MSIFILENAME] is used. See Command Line Options in the Windows Installer SDK Help.) „ Uninstall --> Install If the application is already installed, this option first uninstalls it, then installs. „ Run Runs the installation normally. If the application is already installed, you are prompted to uninstall it. Windows Installer Editor Reference 80 Working With Wise Installation Files „ 3. Other command lines If you added command lines to the Command Line page, they also appear. To avoid having to select from the button menu, press Ctrl+R to run with no command line. If you are working in a .WSI that contains multiple releases, you are prompted to select one. The installation is compiled and run. Note If you change the installation and then run it, but the change is not apparent, close the installation. Reopen it and compile it, and then run it again. To run an installation and install it into a virtual layer 1. On the Wise Options dialog box, mark the Install into virtual layer from Run button option. See Setting General Options on page 33. 2. Click Run at the lower right of the main window. 3. If you are working in a .WSI that contains multiple releases, you are prompted to select one. The application is installed into a new virtual layer and activated. You can test the installation by viewing its installed files and running the application. If needed, you can edit the contents of the layer in the Virtual Package Editor. You might add or delete a file or registry key for testing purposes. You can then delete the layer to restore your computer to its original state. See About Installation Expert in the Virtual Package Editor Help. To delete an installation installed into a virtual layer Do one of the following: z Install another installation into a virtual layer. This removes the layer that was previously created and creates a new one. z Close Windows Installer Editor. z Delete the virtual layer from the Altiris SVS applet. The name of the virtual layer is WiseTemp_ProductName where ProductName is the value of the ProductName property. See About the Altiris SVS Applet in the Virtual Package Editor Help. Running a transform or merge module You cannot run a transform or a merge module by itself. It can only be run in conjunction with an .MSI. To run a transform or merge module, run the base .MSI from the command line with the appropriate command-line options, which are documented in the Windows Installer SDK Help. See also: Testing An Installation on page 79 Windows Installer Editor Reference 81 Working With Wise Installation Files Running the Debugger on page 433 Compiling An Installation on page 77 Windows Installer Editor Reference 82 Chapter 4 Defining an Installation Project This chapter includes the following topics: z Project Summary Page on page 83 z Product Details Page on page 83 z General Information Page on page 89 z Add/Remove Programs Page on page 89 z Features Page on page 90 z Managing Binary Resources on page 101 Project Summary Page The Installation Expert > Project Summary page provides the following information about the current installation project and quick access to areas of the installation: z Links to Installation Expert pages that have content in the current installation and, where appropriate, the number of items defined on each page. Examples: How many features are defined on the Features page, how many files have been added to the Files page, and so on. z Links to the Package Contents reports. z Installation package meta data (read-only). You can edit the meta data. See Product Details Page on page 83. A check box in Wise Options determines whether the Project Summary page appears when an installation is opened. Product Details Page Use the Product Details page to enter, edit, or view an installation’s meta data. Meta data is displayed for .MSI, .WSI, and .MST files. In the Value column of the Package Meta Data table, you can enter or edit meta data that is not read-only. Note The meta data that appears when you create a transform comes from the base .MSI. If you change a transform’s meta data, it is set when the transform is applied. Meta Data and the Software Manager Database If you define meta data fields in Software Manager, they appear on the Product Details page unless the Software Manager database cannot be found. You can edit these meta data fields on the Product Details page or in Software Manager. In Software Manager, you can also change the order in which the meta data fields appear on the Product Details page. Windows Installer Editor Reference 83 Defining an Installation Project See Defining Custom Meta Data Fields in the Software Manager Help. For an .MSI or .WSI, you can add the meta data that appears on the Product Details page to the Software Manager database. This lets you add package information to the Software Manager database early in the development or repackaging process. It also eliminates the need to enter the meta data manually in Software Manager and ensures that every package in the database has meta data that meets your corporate standards. See Adding Meta Data to the Software Manager Database on page 86. See How to Get Packages Into the Software Manager Database in the Software Manager Help. To set product details Select Installation Expert > Product Details page and complete the page: z Application Enter the name to use for this application in the Software Manager database. This can be the same as the Product Name meta data field. This field appears in an .MSI or .WSI only. z Package Enter a unique name to identify this package in the Software Manager database. Typically, you use the Application name plus specific version information. (Example: If the Application name is Product, the Package name might be Product 5.05.) This field appears in an .MSI or .WSI only. z Product Type (Read-only.) This displays Windows Installer for installations and Transform for transforms. z Product Name Enter the name of the application, which by default is the name of the first directory you create on the Files or Web Files page. The end user sees this name during installation and in the Add/Remove Programs dialog box. z Manufacturer Enter the manufacturer or publisher of the application. z Version Enter the version number of the application. Windows Installer uses this to identify this application when subsequent patches or upgrades are applied. The version should be in the format AA.BB.CCCC.DDDD, where AA is the major version, BB is the minor version, CCCC is the build version, and DDDD is optional and ignored. It is stored as a string data type. See Incrementing the Product Version on page 87. Warning If you are releasing a newer version of your application but are not using an upgrade or patch, it is very important to enter a new version on the Product Details page. Not doing so can cause the installation to open in maintenance mode instead of in normal installation mode. This can result in an installation that is a mixture of old and new files, which can cause errors in your application. The only exception is if the installation contains no new files, no deletion of files, and no other system changes, which means that only the contents of files are changed. Windows Installer Editor Reference 84 Defining an Installation Project z Default Directory During installation, this directory is displayed to the end user on the Destination Folder dialog box, and the end user can change the default location for the application. (The Destination Folder dialog box is called the Single Feature Destination dialog box in Windows Installer Editor.) This defaults to the first directory you create on the Files or Web Files page. To change the default directory, select its value, click the Change button, and select a new directory. See Setting the Default Installation Directory on page 88. z Package Path (Read-only.) This displays the installation file’s location. z Repository ID (Read-only.) This displays the package’s unique identifier in the Wise Software Repository, which Windows Installer Editor generates in the form of a GUID. This ID is generated when you save or compile an installation after entering the application and package names. It is also generated when you import a package in Software Manager, if it does not already exist. z Product Code Every Windows Installer installation must have a unique product code, which is used as the principal identification for the application. Windows Installer Editor generates a product code in the form of a GUID, which ensures that no two applications ever have the same product code. To change the product code: „ Select its value and click the Change button. „ On the dialog box that appears, click Yes to change the product code and the upgrade code, or click No to change just the product code. If the installation is an upgrade of an existing installation, then change the product code only. See Upgrades on page 302. Changing the product code also changes the package code. For information on the product and package codes, see ProductCode Property, Package Codes, and Product Codes in the Windows Installer SDK Help. See About GUIDs on page 493. z Application Type Specify whether this is a standard Win32 or a .NET installation. This also determines how Windows Installer Editor handles COM interoperability registry entries. This defaults to the Default Application Type that is specified in Wise Options. See Setting .NET Assembly Options on page 34. The ability to create .NET installations is supported only by Windows Installer 2.0 or later. „ Win 32 (non .NET) Select this if this is a standard Win32 installation without .NET assemblies. „ .NET Application Select this if this is a .NET installation with only .NET elements. „ Mixed (.NET and Win32) Select this if this installation contains both Win32 and .NET elements. When this option is selected, the Generate COM interop registry keys for .NET Assembly check box on the File Details dialog box > Self-registration tab is marked by default for all .NET assemblies you add to this installation. The Windows Installer Editor Reference 85 Defining an Installation Project assemblies will be registered so that they can be called as though they were COM elements. When the .NET Application or Mixed option is selected, entries are created in the MsiAssembly and MsiAssemblyName tables for each assembly you add to the installation. The Global Assembly Cache directory also appears on the Files page. z z Installation Target This value is for meta data purposes only. It does not change the installation. „ Windows-based desktop/server PC Mark this if the installation does not install a Web service to an IIS server. This is the default except for Web and server applications. „ Windows-based IIS Web server Mark this if the installation installs a Web application to an IIS server. This is the default for Web and server applications. Description Describe the package. This becomes part of the package meta data when the package is imported into the Software Manager database. z Don’t update or recompress files when saving (.MSI files only.) Files are stored in .MSI files either with a hard-coded path to the original, or without a path. For files with paths, Windows Installer Editor gets the latest copy of the file from the specified path when you save or compile the .MSI. Mark this to prevent Windows Installer Editor getting the latest copy of files that have paths. If you clear this check box, files that are set to be compressed are not recompressed when you save or compile. Compression options are on the Media page. z Increment version number on compile Mark this to increment the third section of the version when the installation is compiled. Examples: 3.0.3790 is incremented to 3.0.3791 2.5 is incremented to 2.5.0001 Adding Meta Data to the Software Manager Database To add meta data to the Software Manager database 1. Select Installation Expert > Product Details page. 2. Enter the Application and Package names. These fields appear in an .MSI or .WSI only. See Product Details Page on page 83. 3. Select File menu > Save to save the installation. If this is the first time you have saved the installation, the Save As dialog box appears. Enter a name for the file and click Save. 4. If a package with the same application and package name is already in the Software Manager database, a warning message appears. Click OK and change either the application or package name to create a new package in Software Manager. Windows Installer Editor Reference 86 Defining an Installation Project When you save the installation, its meta data is added to the Software Manager database and the Repository ID field is populated. What happens when you add meta data to the Software Manager database? z The meta data appears in Software Manager on the Package pane and the Package Attributes dialog box. See About the Software Manager Window and Viewing and Editing Package Attributes in the Software Manager Help. This only adds the package’s meta data to the Software Manager database. It does not import the package’s resources. The package’s resources are imported by the Import Wizard in Software Manager. z The package is assigned a status of New in Software Manager. You cannot change to or from this status manually. A New package is changed to Under Development only when you use the Import Wizard to import its resource information. z The package is assigned a repository ID in the form of a GUID. If you make a copy of the installation and change the copies application or package name, it is assigned a new repository ID. z The Application and Package fields on the Product Details page are unavailable. You can edit them on the Package Attributes dialog box in Software Manager. See Viewing and Editing Package Attributes in the Software Manager Help. If you open an installation file that is a copy of the package in the Software Manager database, the Application and Package fields are populated and enabled. Change one or both of these fields before saving the installation to avoid overwriting the package in the database. See Working With Installations in the Software Manager Database on page 76. z If you edit meta data on the Product Details page, the meta data in the Software Manager database is updated when you save the installation. If you edit meta data in Software Manager, your edits appear on the Product Details page the next time you open the installation. See How to Get Packages Into the Software Manager Database in the Software Manager Help. Incrementing the Product Version Windows Installer uses the version number of the application to identify the product when subsequent patches or upgrades are applied. How do you set the version number? The version number is stored in the Version field on the Product Details page. You can update the version number by changing the field. See Product Details Page on page 83. You can increment the version number automatically during compile by marking the Increment version number on compile check box on the Product Details page. Windows Installer Editor Reference 87 Defining an Installation Project When should you increment the version field? z When you add or delete files from the installation. z When you create, remove, or edit any other items besides files. Examples: services, ODBC, runtimes, registry, and so on. z If you plan to create a patch that updates earlier versions to this version. z When you include upgrade entries on the Upgrades page of versions that this installation will upgrade. When can you leave the version field the same? When you create an update that has all the same files as the original version, and only the contents of files have changed. Setting the Default Installation Directory During installation, this directory is displayed to the end user on the Destination Folder dialog box, and the end user can change the default location for the application. (The Destination Folder dialog box is called the Single Feature Destination dialog box in Windows Installer Editor.) On the Product Details page, you can: z Change the default installation directory. z Reset the default directory for features that use this directory. z Create a new directory as a child, or subdirectory, of an existing directory. Note When end users install your application, sometimes the installation directory defaults to the C drive, and other times it defaults to another drive. This happens because Windows Installer determines which drive has the most free space. To set the default installation directory 1. Select Installation Expert > Product Details page. 2. Select the Default Directory value and click the Change button. The Set Default Install Directory dialog box appears. The Default Directory dropdown list contains all the directories accessed by this installation, including predefined Windows directories. 3. From Default Directory, select a new default installation directory. If the directory you want is not listed, add it in Installation Expert > Files page. To create a new directory as a child of an existing directory, select a directory, click the New Folder button and, in the Create New Folder dialog box, enter a name for the new subdirectory. 4. Mark Change Feature configurable directories to have any features that explicitly reference the default directory change when you select a new default directory. To see if a feature explicitly references a directory, double-click the feature name on the Features page. If the Directory field does not contain , then the feature explicitly references a directory. Windows Installer Editor Reference 88 Defining an Installation Project 5. Click OK. General Information Page Use the General Information page to set the summary information and the required Windows Installer version for the installation file. End users can see the summary information by right-clicking the compiled .MSI or .EXE in Windows Explorer and selecting Properties. Note In Windows Vista, the file Properties dialog box does not contain summary information. For information on summary items, see Summary Property Descriptions in the Windows Installer SDK Help. Select Installation Expert > General Information and complete the page: z Title Enter the name of the application. This field often includes a version number. z Subject Enter a brief description of the application. z Author Enter the author or publisher of the application. This field often includes a copyright notice. z Keywords Enter a list of keywords that the end user can use to search for this installation in Windows Explorer. z Installer Version (Read-only.) This displays the minimum Windows Installer version required on the destination computer to run this installation. This is not the version of the application. If the destination computer has an earlier version of Windows Installer, the installation fails. To change this version, select Setup Editor > Product tab, click the Summary icon in the left pane, and double-click Minimum Installer Version in the upper-right pane. If this is a 64-bit installation, the minimum version of Windows Installer is set to 2.00 or later. Do not change this value in a 64-bit installation. Microsoft Restrictions: z „ Windows Installer version 3.0 requires Windows 2000 SP 3 or later, Windows XP, or Windows 2003. „ Windows Installer version 4.0 requires Windows Vista or later. Comments Enter comments about the application that this installation installs. Add/Remove Programs Page Windows operating systems have an Add/Remove Programs or Programs and Features applet that let end users uninstall, change, or repair programs. Use the Add/Remove Programs page to enter the information necessary to support these capabilities. Windows Installer Editor Reference 89 Defining an Installation Project Select Installation Expert > Add/Remove Programs and complete the page: z Do not display in Add/Remove Programs list Mark this to exclude your application from Add/Remove Programs. z Display in Add/Remove Programs list Mark this to include your application in Add/Remove Programs and to set the following: z „ Display Icon Specify an icon to appear next to the application name in Add/Remove Programs. If you leave this blank, a generic icon is used. Click Browse to select a file from the installation. If the file exists on disk, you also see an icon selection dialog box where you select the icon. „ Icon Number Enter the icon resource ID (preceded by -) or the icon number for the specified icon. Because a file can contain multiple icons, icons in a file are numbered, starting from zero. This is pre-filled if you selected an icon from the icon selection dialog box. „ Hide modify button Mark this to disable the Change button for your application in Add/Remove Programs. This prevents end users from changing the installation. „ Hide remove button Mark this to disable the Remove button for your application in Add/Remove Programs. End users will not be able to uninstall the application using Add/ Remove Programs. Support Information Page The following information appears under the Support Information link in Add/ Remove Programs. „ Product Updates URL Enter a URL where end users can get online support for the application. „ Contact Person Enter the name of a person or department that end users can contact if they have questions. Examples: a support technician or the support department. „ Phone Number Enter the phone number for the contact person specified above. „ Help URL Enter the path to a help file that will be installed on the destination computer. „ Comments Enter any additional comments for the end user. „ Hide repair button Mark this to disable the installation repair option under the Support Information link in Add/Remove Programs. Features Page Use Installation Expert > Features page to create the structure of an installation by defining: z What features make up the application. Windows Installer Editor Reference 90 Defining an Installation Project z How those features are presented to the end user during installation. z What conditions must be true for portions of features to be installed. z The target platform (32-bit, 64-bit, or both) for each feature. See How to Specify the Target Platform on page 62. Determine your application’s features and conditions before configuring other aspects of the installation, because many of the pages in Installation Expert have a Current Feature drop-down list that lets you set options on a per-feature and per-condition basis. See Working With Components and Features on page 492. Note WiseScript Package Editor and WiseScript Editor refer to features as “components.” To see a tree structure that lists all components, merge modules, files, registry entries, and other installation items associated with each feature, use Setup Editor > Features tab. To specify which features are installed by default if the end user selects a Complete, Typical, or Custom installation type on the Installation Type dialog, use the Installation Types page. See Setting Features for Installation Types on page 179. In an installation with multiple releases, you can deselect certain features for certain releases on the Release Settings page. See Defining a Feature and Component Set for a Release on page 187. About the Complete feature In a new installation, the Features page already contains a feature named Complete, because every installation must contain at least one feature. You can rename the Complete feature. You can delete it, but only after you create a second feature. See Strategies for Organizing Files Into Features on page 92. Working with the Features page The tree structure on the Features page displays features and conditions, and their hierarchical relationships. z To add a new feature, click its parent feature and click the Add button at the right of the page. See Adding a New Feature on page 94. z To configure installation options for a feature, click its icon ( option from its drop-down list. ) and select an See Configuring a Feature Using Its Drop-Down List. z To configure all items for a feature, click its name and click Details at the right of the Features page. See Configuring a Feature Using the Feature Details Dialog on page 96. z To delete a feature or condition, click its name and click Delete at the right of the page. When you delete a feature, all its child features and conditions are deleted also. Windows Installer Editor Reference 91 Defining an Installation Project z To rearrange features, click Move Up and Move Down at the right of the page. You can move features within their current level only, in their current sibling group. You cannot move features to their parent or child levels. z To add a condition to a feature, click its name and click Add Condition at the right of the page. See Using Conditions With Features on page 100 and Adding and Deleting Feature Conditions on page 101. Use the right-click menu to: z Expand or collapse a selected feature’s children. z Display hidden features. z Display the features’ titles as they appear on the Select Feature dialog box during installation rather than the features’ names, which are used by Windows Installer. Any display option you select from the right-click menu overrides the corresponding setting in Wise Options. To see how features appear during installation 1. In a sample installation file, add a second feature on the Features page. 2. On the Files page, add a file to each feature. Select the feature from the Current Feature drop-down list before adding the file. 3. On the Dialogs page, clear the check box for Installation Type Dialog, and mark the check box for Select Feature Dialog. 4. Click Test in the lower-right of the main window. The Select Feature dialog box in the installation reflects the options that you set on the Features page. Strategies for Organizing Files Into Features It is important to create and organize features and define conditions in a logical way; not doing so can result in non-functional versions of your application being installed. Features in an installation appear in a tree structure, which lets you place features in hierarchical relationships. You can add a feature at the same level as another feature (sibling level) or as a child of another feature. Sibling features can be installed independently of each other, while child features can be installed only if their parent feature is installed. The core resources for an application should always be in a top-level feature. The core feature should install a functioning version of your application; it should have no dependencies on resources that are in optional features. When Windows Installer repairs an installation due to corruption or deletion of a resource, it repairs the entire feature. Example: If an advertised shortcut is part of the top level feature, and that advertised shortcut gets deleted, the entire application is reinstalled during the repair. Therefore, isolate advertised shortcuts and their .EXEs into their own sub-features to avoid complete reinstallation and result in more efficient repairs. The following examples illustrate several strategies for organizing files into features. Windows Installer Editor Reference 92 Defining an Installation Project Place dependent features below required core files The features Internal_Text_Editor and Internal_Graphics_Editor, which are built into the application, are dependent on the presence of the core application files, which are assigned to the Core feature. Make them children of the Core feature to ensure that they are never installed without the Core feature. Dependent on Core feature Place dependent features as siblings to core files, but require core files The features Internal_Text_Editor and Internal_Graphics_Editor, which are built into the application, are dependent on the presence of the core application files, which are assigned to the Core feature. Because they are siblings of the Core feature, an end user might install the text editor feature or the graphics editor feature without installing the core feature, which would break the installation. To avoid this problem, make the Core feature required; double-click it and mark the Required Feature check box on the Feature Details dialog box. Required features cannot be turned off during installation. The advantage to this strategy is that during installation, the end user sees the optional features at the top level instead of buried in the tree structure. Place stand-alone features as siblings The features External_Text_Editor and External_Graphics_Editor are stand-alone applications, which can run independently of the core application. Therefore, you can make them siblings of the Core feature. An end user can install the text editor or the graphics editor without the core application. Windows Installer Editor Reference 93 Defining an Installation Project Independent of Core feature Use conditions with features The Core feature has two conditions. VersionNT specifies that the operating system must be Windows NT/2000/XP/2003/Vista, and Version9x specifies that the operating system must be Windows 95/98/Me. Because conditions appear in the Current Feature dropdown list, which appears on most Installation Expert pages, you can associate the same kinds of items with a condition that you can with a feature, including files, registry entries, shortcuts, services, and so on. Any items that you associate with either condition are installed only if the feature is installed and the condition is true. Conditions See also: Features Page on page 90 Creating Multiple, Platform-Specific Installations from One Project File on page 66 Adding a New Feature To add a new feature 1. Do one of the following: „ In Installation Expert > Features page, click the feature name under which the new feature should appear. Then click Add at the right of the Features page. To add the new feature at the top level, click Installation Features; to add the new feature under a feature, click the feature’s name. „ In Setup Editor > Features tab, right-click the feature under which the new feature should appear, and select New > Feature. To add the new feature at the top level, right-click the Features icon; to add the new feature under a feature, right-click the feature’s name. The Feature Details dialog box appears. 2. Complete the dialog box. See Configuring a Feature Using the Feature Details Dialog on page 96. Windows Installer Editor Reference 94 Defining an Installation Project 3. Click OK on the Feature Details dialog box. The new feature appears in the tree. 4. The order in which features appear on the Features page determines the order of the features on the Select Features dialog box that appears during installation. To rearrange the order, select a feature name and click Move Up or Move Down at the right of the Features page. To edit a feature’s settings, double-click its name. To rename a feature, right-click its name, select Rename, and enter a new name. To delete a feature and its child features, right-click its name and select Delete. See also: Features Page on page 90 Strategies for Organizing Files Into Features on page 92 Configuring a Feature Using Its Drop-Down List In Installation Expert > Features page, when you click the icon next to a feature name, a drop-down list that contains options for installing the feature appears. The option you set in this drop-down list determines the default state of the feature during installation. The drop-down list provides a way to set common options quickly. The icon itself provides a visual cue that indicating which options have been set. The drop-down list options are a subset of the options that are available in the Feature Details dialog box, which you access by clicking the Details button at the right of the Features page. Note The first four options in the feature’s drop-down list set the default only; the end user can change the default during installation. To prevent the end user from being able to change the defaults you set here, you can turn off the Select Feature dialog box on the Dialogs page, use the Feature Details dialog box to set features to be required, or set features to be hidden from the end user. To set options for a feature Click the feature’s icon and select an option. You can select only one of the first four options, but you can set the fifth option, Hidden from user, in combination with any of the first four options. z Will be installed on local hard drive Make the feature default to being installed on the local hard drive. (This option corresponds to setting Favor Local in the Attributes drop-down list on the Feature Details dialog box.) z Will be installed to run from source Make the feature default to being run from source. (This option corresponds to setting Favor Source in the Attributes drop-down list on the Feature Details dialog box.) If a feature is installed to run from source, it is available to the application and visible to the end user, but is not actually installed on the local hard drive. When the feature is invoked, your application must call Windows Installer functions, such as MsiGetComponentPath, to locate and read the necessary files from the installation Windows Installer Editor Reference 95 Defining an Installation Project source, which might be a CD-ROM or shared network directory. Example: Use this option to specify a clip art library to run from the source. Then you must code your application to try to read from the installation source when the end user tries to use the clip art library. z Feature will be installed when required Make the feature default to being advertised. (This option corresponds to setting Favor Advertising in the Advertising drop-down list on the Feature Details dialog box.) If a feature is advertised, it is available to the application and visible to the end user, but is not actually installed on the hard drive. If the installation source, such as a CD-ROM or shared network directory, is available to the destination computer, the feature is installed when the end user invokes the feature. If the installation source is not available, the end user is prompted for the installation source. z Entire feature will be unavailable Prevent the feature from appearing during installation and from being installed. (This option corresponds to setting Never Install This Feature on the Level dropdown list on the Feature Details dialog box.) z Hidden from user Prevent the feature from appearing to the end user on the installation’s Select Features dialog box. You can set this option in combination with any one of the other options above. (This option corresponds to setting Hidden in the Display dropdown list on the Feature Details dialog box.) See also: Features Page on page 90 Configuring a Feature Using the Feature Details Dialog on page 96 Configuring a Feature Using the Feature Details Dialog When you create a new feature or edit an existing feature, you can configure the feature using the Feature Details dialog box. Access this dialog box from Installation Expert or Setup Editor. See Adding a New Feature on page 94. For technical information on the fields on this dialog box, see Feature Table in the Windows Installer SDK Help. Note Some options on this dialog box set the default only; the end user can change the default during installation. To prevent the end user from being able to change the defaults you set, you can turn off the Select Feature dialog box on the Dialogs page, set features to be required, or set features to be hidden. To complete the dialog box z Name Enter the name of the feature, which is used internally by Windows Installer. The feature name is limited to 32 characters. Windows Installer Editor Reference 96 Defining an Installation Project z Title Enter text to identify the feature. This text appears on the Select Features dialog box during installation. z Parent This list contains all features in the installation. To change the feature’s parent, and therefore the feature tree, select from this list. This lets you change the feature tree in Installation Expert or Setup Editor instead of editing tables. z Target Platform Specify the platform on which this feature should be installed. Note If you add a 64-bit component to a 32-bit feature, it will never be installed. A 64-bit component will be ignored when installing on a 32-bit computer, and a 32-bit feature will not be installed on a 64-bit computer. „ All Processors The feature appears for installation on any computer, regardless of the platform. „ 32 Bit Processors The feature appears for installation on 32-bit computers only. „ 64 Bit Processors The feature appears for installation on 64-bit computers only. „ x64 Only The feature appears for installation on computers that support the x86 architecture (including AMD64 or EM64T). „ Itanium Only The feature appears for installation on computers that support the Itanium 64bit processor. z Description Enter a multi-line description of the feature. This appears if the end user selects a feature on the Select Features dialog box during installation. This text must fit in the Feature Description area of the Select Features dialog box. z Level If you are using the Installation Types page to determine which features to install for a Typical or Complete installation, you can skip this field. If not, specify whether this feature is installed for a Typical or Complete installation. The end user chooses Typical, Complete, or Custom on the Installation Type dialog box (also called Select Installation Type). During a Custom installation, the end user can turn features on or off individually. Each installation has an installation level, stored in the property INSTALLLEVEL. Each feature has its own installation level value, which is set by this field. If a feature’s level is less than or equal to the installation’s INSTALLLEVEL property, then the feature is installed. By default, INSTALLLEVEL is set to 3 for a Typical installation, and to 1000 for a Complete installation. „ Windows Installer Editor Reference Normal Set the feature’s level value to 3, which means that it gets installed by default for either Typical or Complete. 97 Defining an Installation Project z „ Never install this feature Set the feature’s level value to 0, which means that it won’t appear during installation, and won’t be installed. „ Always install this feature Set the feature’s level value to 1, which means that it gets installed by default for either Typical or Complete. „ Custom Set the feature’s installation level value yourself. Example: if you want a feature to be installed for a Complete installation, but not for a Typical installation, set a custom level value that’s greater than 3 and less than or equal to 1000. The Custom Value field becomes available. Custom Value If Custom is selected in Level above, enter the level value for the feature in this field. For details, read the description of Level, above. Note The end user’s action on the Installation Type dialog box determines the INSTALLLEVEL property. To see how this works, go to Setup Editor > Dialogs tab and click the Installation Type dialog in the list. Double-click the Typical/Complete/ Custom radio button, and you see that the end user’s choice in this radio group sets the property InstallMode. If you then double-click Next on the Installation Type dialog box and view the Events tab, you see that, based on the InstallMode value, the installation property INSTALLLEVEL is set to either 3 or 1000. z Display Specify if and how the feature is displayed to the end user on the Select Feature dialog box during installation. „ Invisible Do not display the feature. „ Visible and Expanded Display the feature and its children. „ Visible and Collapsed Display the feature but not its children. To expand or collapse a selected feature’s children, display hidden features, or display the features’ titles rather than the features’ names, use the right-click menu on the Features page. See Features Page on page 90. z Attributes Specify the default for the feature in the installation. The end user can change the default. „ Favor Local The feature should be installed on the destination computer. „ Favor Source The feature should be run from the source CD or network directory. This means the feature is available to the application, but is not installed on the local hard drive. When the feature is invoked, your application must call Windows Installer functions (example: MsiGetComponentPath) to locate and read the necessary files from the installation source, which might be a CD or shared network directory. A typical use of this option would be to specify a clip art library to run Windows Installer Editor Reference 98 Defining an Installation Project from the source. Then you must code your application to try to read from the installation source when the end user tries to use the clip art library. „ Favor Parent The feature should use the same attribute setting as its parent feature. If you select this option, you must also set the installation to generate uncompressed external files that can run from the source. See Adding a Media Item on page 208. z Advertising Specify the default setting for how this feature supports advertising. If a feature is advertised, it is not installed, but it appears to be installed to the end user. Example: The end user might see shortcuts or menu options for an advertised feature, or the system might have certain entry points to the feature, such as a registered file extension, that can perform installation-on-demand of an advertised feature. „ None By default, the feature is set to be installed, not advertised. „ Favor Advertising By default, the feature is set to be advertised. „ Disallow Advertising The feature is set to be installed, not advertised, and the end user cannot change the default. Note Advertising is only supported on certain platforms. To suppress advertising on unsupported platforms, mark Disable advertising if not supported by OS below. See Platform Support of Advertisement in the Windows Installer SDK Help. z Directory To let end users select the directory for this feature, select a directory from this list. When the end user selects this feature on the Select Feature dialog box during installation, the Browse button becomes enabled so that they can select a new directory. Child features of this feature inherit the new directory selected by the end user. If you leave the directory set to , then the files for this feature are installed in the directory structure specified on the Files page. To ensure that two features always get installed to the same directory, select the same option in Directory for both features. If you let end users select directories for individual features, you must code your application in such a way that it can locate the features wherever they might be placed by the end user. To do this, you can call Windows Installer functions, such as MsiGetComponentPath. Note Only the files that are in the directory you select or in its child directories will be installed in the new directory that the end user selects. Example: Suppose FeatureA installs File1 in the Sample\FeatureA\ directory and File2 in the Windows directory. During installation, the end user specifies Sample\A\ for the new directory. Only File1, which was originally in the FeatureA\ directory, is actually installed in the A\ directory. File2 is still installed in the Windows directory. Windows Installer Editor Reference 99 Defining an Installation Project z Required Feature Mark this if the feature is required for installation. During installation, end users cannot deactivate installation of a required feature. If you select Never install this feature in Level (above), it overrides this option. z Disable advertising if not supported by OS Mark this to ignore any choices you made in the Advertising drop-down list if the operating system on the destination computer does not support advertising. See Platform Support of Advertisement in the Windows Installer SDK Help. See also: Configuring a Feature Using Its Drop-Down List on page 95 Using Conditions With Features You can add conditions to features to specify different actions based on installation properties, system configuration, end user choices, and so on. Both conditions and features are listed in the Current Feature drop-down list, which appears on all Installation Expert pages in the Feature Details page group. Just as you can specify options on a per-feature basis, you can also specify options on a per-condition basis. Options on these pages that you associate with a condition are installed only if the condition is true and the feature is installed. Example: Suppose your core application files are stored in a feature named Application. If your application is installed on Windows 95, 98, or Me, you want to also install Application9x.dll, but if your application is installed on Windows NT, 2000, XP, Server 2003, or Vista you want to install ApplicationNT.dll. You do not want to install both .DLLs, but instead want to install one or the other based on the version of the operating system. To do this, you: z Add two conditions under the Web_Creator feature, Version9X (which specifies an OS of Windows 95, 98, or Me) and VersionNT (which specifies an OS of Windows NT, 2000, XP, Server 2003, or Vista). z On the Files page, select the VersionNT condition from the Current Feature dropdown list, then add the ApplicationNT.dll file. z On the Files page, select the Version9X condition from the Current Feature dropdown list, then add the Application9x.dll file. During installation, the files contained within the conditions are installed only if the condition is true. Version9X and VersionNT are properties that are set by Windows Installer. See VersionNT Property and Version9X Property in the Windows Installer SDK Help. See also: WiseFixConditions on page 386 Features Page on page 90 Adding and Deleting Feature Conditions on page 101 Windows Installer Editor Reference 100 Defining an Installation Project Adding and Deleting Feature Conditions To add a new condition to a feature 1. Select Installation Expert > Features page. 2. Click a feature name. 3. Click Add Condition at the right of the Features page. The Feature Condition dialog box appears. 4. Click Build, and create your condition on the Condition Builder dialog box. The Condition Builder dialog box lets you construct a conditional expression and check its syntax. See Creating Conditions With Condition Builder on page 387. Note If you add a component condition that checks the installed state of a component or feature, add the merge module CondFix.msm to the installation. This merge module fixes a Windows Installer limitation. See WiseFixConditions on page 386. 5. Click OK on the Feature Condition dialog box. The condition appears in the Current Feature drop-down list. If you want to make file changes or other system changes on the destination computer only if this condition is true, you first select this condition from the Current Feature drop-down list. To delete a condition 1. Select Installation Expert > Features page 2. Select a condition. 3. Click Delete at the right of the Features page. You are prompted to choose what to do with the components that are associated with the condition. Conditions can contain files, registry entries, and so on, all of which make up components. When you delete a condition, one of two things can happen: „ You can delete all the components that have been added to the condition. „ You can move all the components associated with the condition to the condition’s parent feature. If you choose to move the components, they are placed under the parent feature, and are installed unconditionally. See also: Features Page on page 90 Managing Binary Resources Use Installation Expert > Resources page to add and update binary resources, and to change the names or source files for existing binary entries. It provides an easy way to edit and update peripheral files. (Examples: graphics you might have added for an installation dialog box or .DLLs you might call with a custom action.) Any changes you Windows Installer Editor Reference 101 Defining an Installation Project make here are reflected in the Binary table that you can access in Setup Editor > Tables tab. The Resources page also lets you link binary data to its source files, by marking binary resources to be refreshed. As a result, the binary data is updated during compile with any modification that might have been made to the source file. Note The Resources page might contain entries you did not add, such as images, icons, and Wise .DLL files. The images and icons appear on wizard dialog boxes during installation. If you are using the default installation wizard, do not delete these resource entries; otherwise you might encounter errors during compile. The Wise .DLL files support advanced functionality that you add to an installation (example: custom actions). Removing or refreshing these files can result in advanced functionality ceasing to work correctly. Columns on the Resources page Name Name of the row in the Binary table File Name Path to the source file that contains the binary data in this column indicates that the source file is not known. (Example: This is the case when an installation includes a third-party .MSI.) Unspecified entries are stored in the .MSI and cannot be updated during compile. Last Modified Size Refresh Creation or modification date of the file that contains the binary data and its size Updates the binary data during compile, to reflect any changes made in the source file See Refreshing Binary Resources on page 103. Working with the Resources page z To change binary resource properties for a selected resource, click Details at the right of the page. See Adding Binary Resources on page 103. z To add binary resources to an installation, click Add at the right of the page. See Adding Binary Resources on page 103. z To delete a selected binary resource from the installation, click Delete at the right of the page. z To edit a selected source file, click Edit at the right of the page. The file opens in an appropriate application or you are prompted to select an application. Make the changes and save the file. z To copy binary data into a new source file, click Save As at the right of the page. You might do this to extract a file stored in an .MSI (with an file name) to your disk. Windows Installer Editor Reference 102 Defining an Installation Project Note If you have saved a resource with an unspecified source file to a new file, don’t save the installation until you verify that you selected the appropriate file extension. To do this, select the resource on the Resources page and click the Edit button at the right of the page. The file should open in an appropriate application. If it doesn’t, select Edit menu > Reset Page and save the resource again, using a different extension. Adding Binary Resources When you use the Resources page to add binary resources to an installation, Windows Installer Editor adds the appropriate rows to the Binary table. Select Installation Expert > Resources page, click Add at the right of the page, and complete the Resource Details dialog box: z Name Enter a descriptive name for the data you’re adding. This name appears on the Resources page and in the Binary table. If you leave this blank, the name of the source file is used instead. z File Name Specify the file that contains the binary data. z Create/update link to refresh data when file changes Mark this to update the data during compile with any modification you might have made to the source file. This also marks the check box in the Refresh column on the Resources page. See Refreshing Binary Resources on page 103. This check box is unavailable if you have selected a resource with an unspecified file name. Note You can create or remove this link later, by marking or clearing the check box in the Refresh column on the Resources page. See also: Managing Binary Resources on page 101 Refreshing Binary Resources When you mark a binary resource to be refreshed, you create a link between the binary data in the installation and its source file. As a result, each time you compile, the binary data is updated with any changes you might have made to the source file. In a project file (.WSI), the source file for a binary resource marked to be refreshed stays outside the project file, and therefore does not increase the size of the .WSI. To have a binary resource refreshed Do one of the following: z Mark the corresponding check box in the Refresh column on the Resources page. Windows Installer Editor Reference 103 Defining an Installation Project z Mark the Create/update link to refresh data when file changes check box on the Resource Details dialog box. You can only refresh binary resources with known source files. If you try to mark the Refresh check box for a resource whose source file is shown as unspecified, you are prompted to export the data to a new source file. To resolve compile errors for binary resources that appear in red If a binary resource marked to be refreshed appears in red, with question marks in the Last Modified and Size columns, the name or the location of its source file has changed. To compile without binary file errors, do one of the following: z Use the Resource Details dialog box to update the path for the source file. z Clear the Refresh check box and use the existing entry for the resource in the Binary table. If an error message appears when you try to clear the Refresh check box, it means that the Binary table does not have an entry for this resource. Example: This can happen if you’re working with a .WSI and the source file was changed while the project file was closed. In this case, you must use the Resource Details dialog box and set a source file for the binary resource, if you don’t want to delete it. See: Adding Binary Resources on page 103 Managing Binary Resources on page 101 Windows Installer Editor Reference 104 Chapter 5 Assembling an Installation This chapter includes the following topics: z Files or Web Files Page on page 105 z Resolving File Conflicts Within Windows Installer Editor on page 134 z Registry Page on page 138 z INI Files Page on page 147 z Shortcuts Page on page 149 z Adding an Environment Variable on page 152 z Adding File Associations on page 153 z Services Page on page 156 z Adding an ODBC Item on page 159 z Adding to the Windows Firewall Exception List on page 161 Files or Web Files Page On the Files or Web Files page, you specify the directories and files to be installed on the destination computer. You also can specify operations to remove, copy, or move files on the destination computer during the installation. On the Web Files page, you also can add Web sites, virtual directories, and Web folders, and set their options. The Web Files page displays items to be installed to a Microsoft Internet Information Services Web server, while the Files page displays all items to be installed. For a summary of differences between the two pages, as well as links to Webrelated functionality, see About Web Installations on page 242. See also: When to Use the File-Related Installation Expert Pages on page 107 You can detect and resolve conflicts between a package that is still in the authoring phase and those that have already been deployed, without importing the package into the Software Manager database. If you do this as you add files to an installation, you can identify conflicts at an earlier stage in the repackaging process. See Resolving File Conflicts Within Windows Installer Editor on page 134. Windows Installer Editor Reference 105 Assembling an Installation Files page in Windows Installer Editor Current Feature drop-down list Directories available to your computer Files in the directory selected on the left Directories to be installed on the destination computer Files or operations to be installed on the destination computer The Windows directory represents the system directory of the destination computer. Structure you add to the Web Files page is installed under the Web server root. Working With the Files or Web Files Page z If the installation has multiple features, specify the feature you are configuring by selecting it from the Current Feature drop-down list. z In the lower-left list box, use the right-click menu to expand or collapse folders, to hide or show empty folders, and to rename folders. z Drag directories or files to the page from Windows Explorer. z Drag directories or files from the upper list boxes to the lower list boxes. z Use the following buttons: „ Add Contents Add an entire directory and its contents to the installation, filter the directory using wildcards, and link the directory so that the installation’s contents change dynamically as the directory’s contents change. See Adding Contents of Directories to the Installation on page 114. „ Add File Add files to the directory that is selected in the lower-left list box. See Adding Files to an Installation on page 109. „ New Create directories to be installed on the destination computer. You also can create directories in Setup Editor. See Creating a Folder in Setup Editor on page 367. Windows Installer Editor Reference 106 Assembling an Installation „ Delete (lower left) Remove a directory from the installation. This does not delete it from the destination computer. „ Details (lower left) On the Files page, use this to set NTSF permissions. On the Web Files page, use this to set all IIS-related details about the item, as well as Web-based security. „ Wildcards Update settings of a directory in the installation. See Editing Settings for Automatic Updating on page 119. „ Operation Add operations to the installation. See: Removing a File From the Destination Computer on page 120 Copying and Moving Files on the Destination Computer on page 122 „ Delete (lower right) Remove a file or operation from the installation. „ Details (lower right) View details on the installation’s files or operations, including attributes, name and source, permissions, self-registration, and assembly options. See: Editing File Details on page 123. Removing a File From the Destination Computer on page 120. Copying and Moving Files on the Destination Computer on page 122 To learn about the Web-specific functionality of the Web Files page, see About Web Installations on page 242. See also: Installation Directories on page 108 Files or Web Files Page Icons on page 109 Adding Merge Modules Instead of Files on page 112 Adding Files From the Wise Software Repository on page 113 Adding .NET Assemblies to the Installation on page 115 How Self-Registration Information is Captured on page 133 When to Use the File-Related Installation Expert Pages You can add files to an installation on the Files page and the Web Files page. The following table describes when you should use each of these pages. Page When to use it Files z To add files to any installation See Files or Web Files Page on page 105. Windows Installer Editor Reference 107 Assembling an Installation Page When to use it Web Files z To create Web folders, virtual directories, and Web sites, and add files to them z To add files to a Web installation See About Web Installations on page 242. Installation Directories A new installation contains several predefined directories. They appear in the lower-left list box of the Files page, and in the left pane of the Components and Features tabs in Setup Editor. Program Files Represents the Program Files directory on the destination computer. Windows Represents the system directory (regardless of its actual name) on the destination computer. Some standard directories are already created under Windows, such as System32 and Fonts. To create a subdirectory of the system directory, create it under the Windows directory. (64-bit installations only.) The Windows directory has an additional subdirectory, SysWOW64, which stores 32-bit applications and components. Program Files (x86) (64-bit installations only.) A 64-bit system has two directories for program files: Program Files, in which 64-bit applications and components are installed; and Program Files (x86), in which 32-bit applications and components are installed. See 32-bit Applications on 64-bit Computers on page 64. Global Assembly Cache (.NET installation only.) This is used for assemblies that will be shared by many applications on the destination computer. It appears only if you select either .NET Application or Mixed (.NET and Win32) as the application type on the Product Details page. wwwroot Represents the root of the Web server on the destination computer, which is typically C:\InetPub\wwwroot\ See About Web Installations on page 242. Default directory If you specify the default directory on the Product Details page, it appears on the Files page followed by [INSTALLDIR]. This makes it easy to identify the installation directory. To enable or disable this option, select Show InstallDir from the right-click menu. You can add new directories on the Files page, the Web Files page, the Components tab, and the Features tab. Windows Installer Editor Reference 108 Assembling an Installation If the directory structure on your computer changes while you are assembling an installation, change the source directories in the installation, or convert them to relative or UNC-based source paths. See About source paths on page 305. See also: Files or Web Files Page on page 105 Files or Web Files Page Icons on page 109 Files or Web Files Page Icons The following icons appear in the lower-right list box on the Files or Web Files page to help you quickly identify different types of files on the destination computer. Installation file Duplicate installation file Installation file with permissions set File to be removed from the destination computer File to be moved on the destination computer New location of file to be moved on the destination computer File to be copied on the destination computer New location of file to be copied on the destination computer Web site These cannot be deleted or renamed from the Files page. Use the Web Files page instead. Virtual directory These cannot be deleted or renamed from the Files page. Use the Web Files page instead. See also: Files or Web Files Page on page 105 Installation Directories on page 108 Adding Files to an Installation If you add the same file to multiple locations, it is considered a duplicate file entry. See Creating Duplicate File Entries on page 367. Windows Installer Editor Reference 109 Assembling an Installation When you add files to a package that has already been distributed to the share point directory and imported, you are prompted to add the new files to the share point directory. If you do so, the .QUE file for that package is reset and you must re-import the package in Software Manager. If you have already detected conflicts for that package, you must also redo the conflict detection process. To add files from Installation Expert 1. Select Installation Expert > Files or Web Files page. 2. From Current Feature, select a feature or condition. (Because any item you add must be assigned to a specific feature, you cannot add an item when All Features is selected.) Items that you add to a feature are installed on the destination computer only if the feature is installed. Items that you add to a condition are installed only if the feature is installed and the condition is true. 3. If the directory where the file is to be added is not listed in the lower-left list box: a. Select the directory under which the new directory should be created. b. Click New, enter a directory name, and click OK. The directory you specify will be created on the destination computer if it does not exist. Note When you add a directory, you might not see it when you select another feature from Current Feature. To display directories for all features, mark the View directories for all features on Files page check box in Wise Options. 4. In the lower-left list box, select the directory to which the file will be added. 5. In the upper list boxes, navigate to a file and double-click it or drag it to the lowerright list box. You can select multiple files. If you try to add files to the Destination Computer icon or the Program Files directory, you are prompted to first create a folder to hold the files. The file is added to the selected directory and appears in the lower-right list box. Other dialog boxes might appear. See Additional dialog boxes on page 111. To add files from the Features tab in Setup Editor 1. On the Features tab, expand a feature and then expand its Combined folder. 2. Expand the Files icon. If the Files icon does not appear, right-click and select Hide Empty Folders/Items. 3. To add a new directory, right-click a directory and select New > folder. 4. To add a file, right-click a directory and select New > File. The Add Files to Installation dialog box appears. 5. Specify one or more files and click Open. The file is added to the selected folder and appears in the upper-right pane. Windows Installer Editor Reference 110 Assembling an Installation Other dialog boxes might appear. See Additional dialog boxes on page 111. To add files from the Components tab in Setup Editor 1. On the Components tab, expand a component. 2. Right-click the Files icon and select New > File. If the Files icon does not appear, right-click and select Hide Empty Folders/Items. The Add Files to Installation dialog box appears. 3. Specify one or more files and click Open. The file is added to the component’s installation directory and appears in the upper-right pane. Other dialog boxes might appear. See Additional dialog boxes on page 111. Additional dialog boxes z If you add a .NET assembly, and if Scan Dependencies in Wise Options is set to Prompt to scan dependencies, then Windows Installer Editor: „ Scans the assembly manifest for dependencies. „ Displays the Assembly Dependencies dialog box, which prompts you to select the dependencies to add to the installation. See Assembly Dependencies on page 117. z If a file that is part of a merge module is added, the Files in Merge Modules dialog box appears. It prompts you to add the merge module and, if necessary, download it. See Adding Merge Modules Instead of Files on page 112. z If a file that is used by a package in the Wise Software Repository is added, the Files in Repository dialog box appears and prompts you to add a version of the file that is in the repository. See Adding Files From the Wise Software Repository on page 113. z A File Details dialog box appears if you: „ Double-click a file. „ Select multiple files and click Details (Files or Web Files page). „ Right-click and select Details (Components and Features tabs). See Editing File Details on page 123. See also: Files or Web Files Page on page 105 Installation Directories on page 108 Files or Web Files Page Icons on page 109 Adding Contents of Directories to the Installation on page 114 Adding .NET Assemblies to the Installation on page 115 Editing Settings for Automatic Updating on page 119 Removing a File From the Destination Computer on page 120 Windows Installer Editor Reference 111 Assembling an Installation Copying and Moving Files on the Destination Computer on page 122 Adding Merge Modules Instead of Files The Files in Merge Modules dialog box appears when a file that is part of a merge module is added to an installation. Typically, it appears when you: z Add a file to the Files or Web Files page. z Run tools that add files to an installation. (Example: ApplicationWatch, SetupCapture.) The Files in Merge Modules dialog box lets you add the merge module that contains the file instead of adding the file. Example: The file olepro32.dll is part of a merge module named oleaut32.msm (Microsoft OLE 2.40). Because the file olepro32.dll is meant to function as part of a more comprehensive merge module, it is better to add the merge module instead of the individual file. The merge module might contain other files, registry keys, and dependencies on other merge modules. If it contains dependencies, the dependent merge modules are added also. Other files and registry keys that are in the merge module are removed from the installation to avoid duplication. To add the merge module that contains the file Mark the check boxes of merge modules to add. To see what dependent merge modules will be added, expand the folders. Then click OK. If the merge modules or their dependencies are not found, the Download Redistributables wizard opens with the appropriate merge modules selected. When you finish the download, the merge modules are added to the installation. To add the file instead of the merge module Clear the check boxes of all merge modules and click OK. Dependency merge modules are not added if you clear the parent merge module’s check box. To hide this dialog box in the future From Show this Dialog, select one of the following: z Hide; Replace files with merge modules matching version Avoid seeing this dialog box in the future and always replace files with the corresponding merge modules. This turns the dialog box off for all instances in which it would normally appear. z Hide; Don’t automatically add merge modules Avoid seeing this dialog box in the future and never replace files with the corresponding merge modules. This turns the dialog box off for all instances in which it would normally appear. To make the dialog box appear again, click the Prompts tab in Wise Options and activate the dialog box. See also: Downloading Redistributable Files on page 29 Windows Installer Editor Reference 112 Assembling an Installation Files or Web Files Page on page 105 Adding Files to an Installation on page 109 Adding Contents of Directories to the Installation on page 114 Adding Files From the Wise Software Repository ¾ Not available in Standard Edition. The Files in Repository dialog box appears when a file that is used by a package in the Wise Software Repository is added to an installation. Typically, it appears when you: z Add a file to the Files or Web Files page. z Run tools that add files to an installation. (Example: ApplicationWatch, SetupCapture.) The Files in Repository dialog box lets you add the version of the file that is in the repository, which ensures that you use the correct versions of file resources in applications you develop. Example: An approved version of the file Sample.dll is stored in the Wise Software Repository and is used by several packages in the Software Manager database. When you add Sample.dll to an installation, you can select the version in the repository as the source for the file. When you capture a large application with many files, the repository check can slow SetupCapture considerably. Therefore, you can disable this feature in SetupCapture. Clear the Enable checking of files against Wise Software Repository check box in the General Settings of SetupCapture Configuration. To add a file from the Wise Software Repository 1. 2. Do one of the following to display the Files in Repository dialog box: „ Add files to an installation so that the dialog box appears automatically. „ In Windows Installer Editor, select Tools > Check Repository Files. Mark the check boxes of files to add and click OK. The file’s source path is set to the same location as the version in the Wise Software Repository. You can see the source path on the File Details dialog box > General tab. To hide this dialog box in the future This option is available only when From Show this Dialog, select Hide. This turns the dialog box off for all instances in which it would normally appear. To make the dialog box appear again, click the Prompts tab in Wise Options and activate the dialog box. See also: Viewing Shared File Resources on page 130 Files or Web Files Page on page 105 Adding Files to an Installation on page 109 Windows Installer Editor Reference 113 Assembling an Installation Adding Contents of Directories to the Installation You can add the entire contents of a directory to an installation or use wildcard filters to add only specified files in the directory. You also can link a directory that you add to the installation so that it is dynamically updated when the source directory changes. To add contents of directories to the installation 1. Select Installation Expert > Files or Web Files page. 2. From Current Feature, select a feature or condition. (Because any item you add must be assigned to a specific feature, you cannot add an item when All Features is selected.) Items that you add to a feature are installed on the destination computer only if the feature is installed. Items that you add to a condition are installed only if the feature is installed and the condition is true. 3. In the upper-left list box, select a directory whose contents you want to add. 4. In the lower-left list box, select a directory where you want to add the contents. 5. Click Add Contents. The Add Contents dialog box appears. 6. Complete the dialog box: „ Dest. Directory Enter the name of the installation directory that will hold the contents of the directory you’re adding. If you don’t enter a directory name, the contents are added to the directory that’s selected in the lower-list box. „ Include Wildcards, Exclude Wildcards To add or exclude files based on specific criteria, enter a semicolon-delimited list of wildcards. Wildcards apply only at the moment you click OK on this dialog box unless you also mark the Update installation check box below. (Example: Enter *.EXE for all EXE files. A ? represents any one character.) If you leave the wildcard fields blank, all files in the directory are added. Groups of wildcards appear in Include Wildcards, which you can edit. See Setting Wildcard Groups on page 46. „ Include Subdirectories Mark this to add all the subdirectories within the directory you’re adding. The wildcard settings and update installation settings apply to the subdirectories also. „ Update installation as files are added or removed from source directory Mark this to dynamically update the installation when the contents of the directory you’re adding change on your computer. Otherwise, the wildcards apply only at the moment you add the directory. Note If you link a directory using this check box and if files originally added by the wildcard are now missing, a Wildcard Deleted Files dialog box appears when you save the installation. Click No to leave temporarily missing files in the installation. Windows Installer Editor Reference 114 Assembling an Installation If you mark this check box, each time you save the installation, it is synchronized with the current contents of the directory. If you specified wildcards, the installation is synchronized based on the wildcard criteria. If you included subdirectories, those directories are updated also. If you don’t mark this check box, you can turn automatic updating on later by using the Wildcard Details dialog box. See Editing Settings for Automatic Updating on page 119. 7. Click OK. The contents of the directory in the upper-left list box are added to the directory you selected in the lower-left list box or to the directory you specified in the Dest. Directory field. If you marked the Update installation as selected files are added or removed from source directory check box, the linked folder displays with a small magnifying glass ( ). Note When you add a directory, you might not see it when you select another feature from Current Feature. To display directories for all features, mark the View directories for all features on Files page check box in Wise Options. See also: Files or Web Files Page on page 105 Installation Directories on page 108 Adding Files to an Installation on page 109 Adding .NET Assemblies to the Installation Note The ability to create .NET installations is supported only by Windows Installer 2.0 or later. When you create a .NET installation, you can use the Files or Web Files page to add .NET assemblies. When you add a file that is a .NET assembly to an installation, the MsiAssembly and MsiAssemblyName tables are updated. If the .NET Framework is installed on your computer, the following tasks are performed automatically when you add a .NET assembly. If the .NET Framework is not installed, you must perform these tasks manually. See Creating a .NET Installation Without the .NET Framework on page 240. z Files contained in a multifile assembly are added when the main assembly file (containing the manifest) is added. z Depending on the Scan Dependencies option in Wise Options, you either enter assembly dependencies manually, or they are scanned and added automatically, or they are scanned and you are prompted to add them. See Assembly Dependencies on page 117. z Assembly attributes are added to the Assembly tab of the File Details dialog box. z In a mixed installation (.NET and Win32), registry keys are added to register .NET assemblies so that they can be called as though they were COM components. Windows Installer Editor Reference 115 Assembling an Installation You can install assemblies into the Global Assembly Cache, the WinSxS directory, or a private directory. Each of these directories is used in a different way: Global Assembly Cache Assemblies that will be shared by many applications on the destination computer should be installed into the Global Assembly Cache directory. Assemblies installed into the Global Assembly Cache must be strongly named. A strong name consists of an assembly’s identity—its simple text name, version number, and culture information (if provided)—strengthened by a public key and a digital signature generated over the assembly. The Global Assembly Cache directory appears only if .NET Application or Mixed (.NET and Win32) is selected as the application type on the Product Details page. See Installation of Assemblies to the Global Assembly Cache in the Windows Installer SDK Help. WinSxS To enable side-by-side sharing of a Win32 assembly, install it into the WinSxS directory, which is under the Windows directory on Windows XP or later. Assemblies installed into WinSxS must be strongly named. On Windows XP or later, shared assemblies are installed as side-by-side assemblies. See Side-by-Side Assemblies in the Windows Installer SDK Help. Private directory If an assembly is private, used by only one application, install it into any installation directory, provided its path contains a maximum of 256 characters. See Private Assemblies in the Windows Installer SDK Help. See also: Installation Directories on page 108 How Assembly Dependencies are Added to an Installation When you add a .NET assembly to an installation, and the assembly has dependencies on other files, you can add the dependency files to the installation in the following ways: z You can add the dependency files manually. z Windows Installer Editor can scan the assembly’s manifest and add the dependency files. z Windows Installer Editor can scan the assembly’s manifest and prompt you to add the dependency files. The scan feature is controlled by the following settings: z In Wise Options > .NET Assemblies tab, use the Scan Dependencies drop-down list. z In the Import Visual Basic, C#, or J# tool, on the Select Configuration dialog box, use the Automatically add Assembly Dependencies without prompting check box. You can exclude dependencies from the assembly scan for a specific installation or for all installations. See About Dependency Scan Exclusions on page 117. Windows Installer Editor Reference 116 Assembling an Installation Note On .NET Framework versions earlier than 1.1, the scan does not occur when you add an assembly from a UNC or mapped network drive (example: the share point directory). To enable scanning of such assemblies, either upgrade to .NET Framework version 1.1 or later, or change your .NET security so that the directory is fully trusted. Assembly Dependencies When you add a .NET assembly to an installation, Windows Installer Editor can scan the assembly’s manifest for dependencies and prompt you to add the dependency files to the installation. If the scan finds dependencies, the Assembly Dependencies dialog box lists dependencies for all the assemblies you added. In the Assembly Dependencies dialog box, you can check the checkbox next to a dependency name to add the dependency to the installation. If you uncheck the check box, the dependency is added to the project dependency exclusion list and is skipped by future scans of the current installation. See also: How Assembly Dependencies are Added to an Installation on page 116 About Dependency Scan Exclusions When you add a .NET assembly to an installation, Windows Installer Editor can scan the assembly’s manifest for dependencies and either add the dependencies to the installation or prompt you to select the dependencies to add. You can use the following exclusion lists to exclude dependencies from assembly scans: Project dependency exclusion list A project dependency exclusion list is maintained for every .NET installation project. A dependency is added to the list when you choose not to include the dependency during an assembly scan. Use this exclusion list to exclude specific dependencies from a single installation. Global dependency exclusion list By default, certain dependencies are excluded from assembly scans in all .NET installations. These global dependency exclusions are hard-coded. You can create an XML file that overrides the hard-coded dependency exclusions with exclusions that you define. Use this exclusion list to exclude specific dependencies, or dependencies that match a wildcard, from all installations. For example, dependency files that are part of the .NET Framework. See About the Global Dependency Exclusion List on page 118. Windows Installer Editor Reference 117 Assembling an Installation Assembly dependencies that are in an exclusion list are never added to an installation, even if the .NET assembly is rescanned, or if you add a new assembly that has the same dependency. About the Global Dependency Exclusion List By default, certain dependencies are excluded from assembly scans in all .NET installations. These global dependency exclusions are hard-coded. You can create an XML file that overrides the hard-coded dependency exclusions with exclusions that you define. Name the file dotnetexclude.xml and place it in one of the following locations: z The Windows Installer Editor subdirectory of this product’s installation directory on the local computer z The top level of the share point directory If you have multiple exclusion lists, they are used in the following order: z If dotnetexclude.xml is on the local computer, it is used instead of the hard-coded list. z If dotnetexclude.xml is on the share point directory, it becomes the primary exclusion list, which overrides any local exclusion lists and the hard-coded list. Use the following syntax in the XML file: < The regular expression represents a wildcard in regular expression syntax. For information on regular expression syntax, search for “Regular Expression Syntax” in the MSDN Library (msdn.microsoft.com/library/). The dotnetexclude.xml file overrides all the hard-coded exclusions. To retain the hardcoded exclusions, add them to the XML file. The following list of default exclusions is provided in the proper XML syntax. You can add your own exclusions to this list. < Windows Installer Editor Reference 118 Assembling an Installation See also: About Dependency Scan Exclusions on page 117 Editing Settings for Automatic Updating On the Files or Web Files page, if you link a source directory to a directory in the installation, the files in the installation are updated when the contents of the source directory change. To edit the settings for automatic updating of a directory 1. Select Installation Expert > Files or Web Files page. 2. From Current Feature, select a feature or condition. (Because any item you add must be assigned to a specific feature, you cannot add an item when All Features is selected.) 3. Click the directory name in the lower-left list box and click Wildcards at the lower left of the Files or Web Files page. The Wildcard Details dialog box appears. If the directory is currently linked to directories on your computer, those directories appear in the Source Directory list. 4. To link the contents of a source directory to this installation directory, click Add, select a directory from your computer, and click OK. Whenever the contents of directories in the Source Directory list change, the installation directory is updated, based on the wildcard settings. Example: Suppose you link the directory C:\Directory and enter *.exe in Include Wildcards. Later you add Editor.exe to C:\Directory and remove Paint.exe from C:\Directory. This installation is updated so that it contains Editor.exe and does not contain Paint.exe. If you also added Paint.dll to the source directory, it is not added to the installation directory because it does not match the wildcard criteria. 5. To turn off automatic updating for this installation directory, select each directory in the Source Directory list and click Delete. 6. To configure a particular source directory, select it in the Source Directory list and complete the Wildcard Details dialog box: „ Include Wildcards, Exclude Wildcards To include or exclude files based on specific criteria, enter a semicolon-delimited list of wildcards. (Example: Enter *.EXE for all EXE files or *.DLL for .DLL files.) If you leave the wildcard fields blank, all files in the directory are added. Groups of wildcards appear in Include Wildcards. To edit groups, use the Wildcards tab in Options. See Setting Wildcard Groups on page 46. „ Windows Installer Editor Reference Include Subdirectories Mark this to add all the subdirectories within the directory you’re adding. The wildcard settings and update installation settings apply to the subdirectories also. 119 Assembling an Installation „ Change existing components’ attributes When files are added because of changes in the source directory, new components are created to hold them. Mark this to reset the attributes of any pre-existing components to the settings that are specified on this dialog box. If you do not mark this check box, the files currently in the source directory do not have the component attributes you set below. „ Run location Specify whether new components are installed on the local hard drive (Run Locally), not installed on the local hard drive (Run From Source), or either. Change this option only if you plan to integrate Windows Installer function calls into your application to determine the installed location. „ Always increment shared DLL count Mark this to always increment the count of applications using .DLLs in this component when it is installed, even if the file is not already installed. Normally, Windows Installer only increments the shared DLL count on a file if the file is installed and has an existing shared DLL count. If a component is installed to the Global Assembly Cache, you cannot increment the shared DLL count. „ Leave installed on uninstall Mark this to leave the component installed when its parent feature is uninstalled. „ Check condition during reinstall Mark this to check conditions attached to the component when the application is reinstalled. If this is not marked, the conditions are checked only during the original installation. „ Never overwrite if key path exists Mark this to prevent the installation of this component if the file, registry entry, or ODBC data source specified as the key path is already present. 7. Click OK. 8. If a change in the wildcards causes files to be deleted, the Wildcard Deleted Files dialog box appears. Click Yes to remove the listed files from the installation. The files in the installation directory are updated immediately according to the changes you made on the Wildcard Details dialog box. See also: Files or Web Files Page on page 105 Files or Web Files Page Icons on page 109 Installation Directories on page 108 Adding Files to an Installation on page 109 Adding Contents of Directories to the Installation on page 114 Removing a File From the Destination Computer You can add an operation to remove one or more files from the destination computer during installation. This operation affects files that are already on the destination computer, not files that are part of the installation. You can use this operation to remove unneeded files on the destination computer to keep it in a cleaner state. You also can use it to work around Windows Installer version Windows Installer Editor Reference 120 Assembling an Installation rules. Example: If the latest release of an installation uses an older version of a .DLL than was used in the previous release, the version rules will not allow you to install the older .DLL. If the installation first removes the newer .DLL from the destination computer, then the version rules will not prevent the installation of the older .DLL. Warning Be very careful when removing files from the destination computer. Do not remove files unless you are sure that they are not used by another application. To remove a file from the destination computer 1. Do one of the following: „ Select Installation Expert > Files or Web Files page. a. From Current Feature, select a feature or condition. (Because any item you add must be assigned to a specific feature, you cannot add an item when All Features is selected.) Items that you add to a feature are installed on the destination computer only if the feature is installed. Items that you add to a condition are installed only if the feature is installed and the condition is true. b. Click Operation below the lower-right list box and select Remove File. „ In Setup Editor, on the Components or Features tab, right-click a component or feature and select New > Remove File. The Remove File Details dialog box appears. 2. 3. Complete the dialog box: „ Directory Specify the directory on the destination computer where the file is located or create a new subdirectory. To create a new subdirectory, select a directory and click New Folder. „ File Name Specify the name of the file to be removed. You can use wildcards to select multiple files or you can mark All Files to select all files in the selected directory. „ Remove During Specify when the file should be removed: during install, uninstall, or both install and uninstall. Click OK. The operation to remove a file from the destination computer appears, preceded by On the Files or Web Files page, the entry’s Type column contains “Remove.” . To edit it, double-click its name. To delete it, use the right-click menu. See also: Files or Web Files Page on page 105 Installation Directories on page 108 Files or Web Files Page Icons on page 109 Adding Files to an Installation on page 109 Windows Installer Editor Reference 121 Assembling an Installation Copying and Moving Files on the Destination Computer You can add an operation to copy or move a file on the destination computer during installation. This operation affects files that are already on the destination computer, not files that are part of the installation. You might copy or move files on the destination computer to reorganize the location of the installation files in a new release. Example: Your application installed graphic files to C:\Program Files\Application\Graphics, but your latest release installs them to C:\My Documents\Application. You can add an operation to copy or move the existing graphic files from the old directory to the new directory. Warning Be very careful when moving files on the destination computer. Do not move files unless you are sure that they are not used by another application. To copy and move files on the destination computer 1. Do one of the following: „ Select Installation Expert > Files or Web Files page. a. From Current Feature, select a feature or condition. (Because any item you add must be assigned to a specific feature, you cannot add an item when All Features is selected.) Items that you add to a feature are installed on the destination computer only if the feature is installed. Items that you add to a condition are installed only if the feature is installed and the condition is true. b. Click Operation below the lower-right list box and select Copy File or Move File. „ In Setup Editor, on the Components or Features tab, right-click a component or feature, select New, and select Copy File or Move File. The Copy File Details or Move File Details dialog box appears. 2. Complete the dialog box: „ Source Directory Specify the directory on the destination computer where the file is located or create a new subdirectory. To create a new subdirectory, select a directory and click New Folder. „ Source File Name Specify the name of the file to be copied or moved. You can use wildcards to select multiple files or you can mark All Files to select all files in the selected directory. „ Dest. Directory Specify the directory on the destination computer to copy or move the file to or create a new subdirectory. To create a new subdirectory, select a directory and click New Folder. To rename files on the destination computer, make the source and destination directory the same. „ Windows Installer Editor Reference Dest. File Name To change the name of a file when it is copied or moved, specify the new name. 122 Assembling an Installation To leave the file name unchanged when it is copied or moved, leave this field blank. This also works when you use wildcards in the Source File Name field to select multiple files. 3. Click OK. The operation to copy or move a file on the destination computer appears, preceded by the copy icon ( ) or move icon ( ). On the Files or Web Files page, the entry’s Type column contains “Copy to” or “Move to” followed by the directory to which the file will be copied or moved. To edit it, double-click its name. To delete it, use the right-click menu. See also: Files or Web Files Page on page 105 Files or Web Files Page Icons on page 109 Installation Directories on page 108 Adding Files to an Installation on page 109 Editing File Details When you add a file to an installation, it inherits the attributes of the original file. If you edit the attributes of a file in an installation, the file reflects your edits when it is installed on the destination computer. Note When you add an operation to remove, move, or copy a file on the destination computer, an entry for that operation appears on the Files or Web Files page in the lower-right list box. Because the entry is an operation to be performed on a file on the destination computer, you cannot edit its attributes. However, you can edit the details of the operation. To edit attributes for a single file On the Files or Web Files page, double-click a file in the lower-right list box. The File Details dialog box appears. It contains several tabs. See: Editing General File Details on page 124 Setting Permissions for Files and Directories on page 125 Editing Self-Registration Settings for Files on page 126 Editing Assembly Settings for Files on page 127 Viewing Shared File Resources on page 130 Editing XML Files During Installation on page 131 To edit attributes for multiple files 1. On the Files or Web Files page, select multiple files in the lower-right list box. 2. Click Details at the lower right of the page. The Multiple Files dialog box appears. Only a subset of the editing options are available.See Editing General File Details on page 124 and Setting Permissions for Files and Directories. Windows Installer Editor Reference 123 Assembling an Installation Note If you add a file to an installation, then add it again to a different directory, the second instance is added as a duplicate file. If you double-click the second file, the Duplicate File Details dialog box appears instead of the File Details dialog box. (See also Creating Duplicate File Entries on page 367.) With .NET assemblies, if you add the same file to the application directory and the Global Assembly Cache, a duplicate file is not created because they are treated as separate components. See also: Files or Web Files Page on page 105 Adding Files to an Installation on page 109 Editing General File Details To edit general file details 1. Do one of the following: „ In Installation Expert: On the Files or Web Files page, select one or more files and click Details. „ In Setup Editor: On the Components or Features tab, select one or more files and select Details from the right-click menu. The File Details or Multiple Files dialog box appears. 2. Click the General tab. 3. Complete the dialog box: „ Long Filename (File Details dialog box only.) The name of the file as displayed on computers running Windows 95 and later. „ Short Filename (File Details dialog box only.) The 8.3 file name as displayed in DOS or under older versions of Windows. Specify the short name your application will look for if it is installed on a shared network directory that doesn’t support long file names. „ Source Pathname The full path of the file on your computer. If this is blank, or if it is just a file name with no path, you might be working in an .MSI, which encapsulates the file itself. „ Font Name (File Details dialog box only.) The name of the font contained in the file, if it is a font file. „ Read Only Make the file read-only on the destination computer. „ Hidden Make the file hidden on the destination computer. „ System Designate this file as a system file on the destination computer. Windows Installer Editor Reference 124 Assembling an Installation „ Vital Mark this if this file must be installed correctly for the installation to succeed. If the file cannot be installed for any reason, the installation fails. „ Add to Hash Table (Not available for multiple files.) If this is an unversioned file, mark this to create an entry for this file in the MsiFileHash table. Windows Installer version 2.0 or later uses file hashing to detect and eliminate unnecessary file copying during reinstalls and repairs. It does this by comparing a file hash stored in the MsiFileHash table to a hash of an existing file on the destination computer. See MsiFileHash Table in the Windows Installer SDK Help. „ File has Valid Checksum Many executable files (examples: .EXE, .OCX, .DLL, etc.) store a checksum that can be checked against actual file contents to ensure the file is not corrupted. Mark this to have file contents verified during reinstall or repair. If the verification fails, the file is assumed to be corrupted and is replaced. For files that contain checksum information, this check box is marked automatically when you add the file to the installation. „ Self-Register OCX/DLL (Multiple Files dialog box only.) Many files support self-registration (examples: many .OCXs and some .DLLs). Mark this to self-register these files during the installation with an unordered registration method. „ Duplicate Files This appears only if this file was added to the installation more than once. The duplicates are listed here for informational purposes only. You can view and edit duplicate file entries on the Components and Features tabs in Setup Editor. See Creating Duplicate File Entries on page 367. 4. Click OK. Note With .NET assemblies, if you add the same file to the application directory and the Global Assembly Cache, a duplicate file is not created because they are treated as separate components. Setting Permissions for Files and Directories You can set NTFS (NT file system) permissions for a single file or folder or for multiple files. The permissions you set are applied to the domain and user you specify, so you can set different permissions for the same file or folder for different users. Set permissions only if you know your users and their domains. When you set permissions for a file, the file appears preceded by . Note The Permissions tab does not set Web-based security. To set Web-based security, go to Installation Expert > Web Files page, select the directory or virtual directory, and click the Details button. The Directory Security tab lets you set options for Microsoft Internet Information Server. See IIS documentation for details on options. Windows Installer Editor Reference 125 Assembling an Installation To set NTFS file or directory security 1. Do one of the following: „ In Installation Expert: On the Files or Web Files page, select a folder, file, or set of files and click the corresponding Details button. (On the Web Files page, you can set permissions for files but not for folders.) „ In Setup Editor: On the Components or Features tab, right-click a folder, file, or set of files and select Details. A dialog box appears with a Permissions tab. If you selected multiple files that have different permissions, you are prompted to reset the permissions to a common set when you click the Permissions tab. If you do not reset the permissions, the Permissions tab is unavailable. 2. On the Permissions tab, click Add. The Lock Permissions Details dialog box appears. a. Enter the Domain. b. Enter or select a User name. c. Click OK. The domain and user names appear in the upper list box, and the list of permissions is enabled. 3. To set permissions, mark the check boxes. You can add multiple users. Warning If you set permissions for a folder that is written to by this installation, be sure that the user installing this application has privileges to write to the folder. Example: Suppose you give write privileges to ASPNET_USER for Program Files\SampleFolder, which later in this installation has files written to it. If the current user profile running this installation is ADMINISTRATOR, then the installation will fail to write to SampleFolder, because only ASPNET_USER has write permissions to SampleFolder. ASPNET_USER is automatically set. See Run Time Properties on page 515. Editing Self-Registration Settings for Files Many files support self-registration (examples: many .OCXs and some .DLLs). You can edit these files so that they self-register during installation. To edit self-registration settings for files 1. Do one of the following: „ In Installation Expert: On the Files or Web Files page, double-click a file. „ In Setup Editor: On the Components or Features tab, double-click a file. The File Details dialog box appears. 2. Click the Self-registration tab. 3. Complete the dialog box: Windows Installer Editor Reference 126 Assembling an Installation „ Registration Method  Do not register  Unordered (normal Windows Installer behavior) Select this if the file does not require that other files in the installation be registered first for it to self-register properly.  Use order specified below (Not available in a merge module.) Select this if this file requires that other files in the installation be registered first for it to self-register properly. This enables the Registration Order field. „ Registration Order This section lists files you selected for self-registration with the Use order specified below method. Arrange files in the order in which they need to selfregister. You can only move the file for which you are viewing details. „ Generate COM interop registry keys for .NET Assembly If this installation contains both .NET and COM elements, mark this to register .NET assemblies so that they can be called as though they were COM elements. This check box is enabled only if you have the .NET Framework installed on your computer, and if the file you are viewing is an assembly that was written to allow COM interop. When the Application Type on the Product Details page is Mixed (.NET and Win32), this check box is marked by default. 4. Click OK. Editing Assembly Settings for Files Use the Assembly tab on the File Details dialog box to enter and edit information about .NET and Win32 assemblies. Windows Installer Editor uses this information to register the assembly files. z For a .NET assembly, use the Assembly tab to enter the assembly attributes. If the .NET Framework is installed on your computer, this information is filled in from the assembly manifest and you should not have to change it. Also use the Assembly tab to specify whether to display the .NET assembly as a reference in Visual Studio .NET on the destination computer. z For a Win32 assembly, use the Assembly tab to create and edit a manifest. See Creating a Win32 Assembly on page 128. To edit assembly settings for files 1. Do one of the following: „ In Installation Expert: On the Files page, double-click a file. „ In Setup Editor: On the Components or Features tab, double-click a file. The File Details dialog box appears. 2. Click the Assembly tab. The Assembly tab only appears for files that are keypaths to their components. 3. Complete the dialog box. If .NET is installed on this computer, some of these options may be preconfigured. If you don’t have .NET, enable options below by selecting .NET in Assembly Type. Windows Installer Editor Reference 127 Assembling an Installation „ Assembly Type Specify whether this file is a .NET assembly, a Win32 assembly, or neither. „ Manifest .NET and Win32 assemblies require a manifest. Select the file that contains the manifest for this assembly. For .NET assemblies, this often is the same as the file you are editing, because most manifests are embedded in the assembly file or in one of the files in a multifile assembly. For Win32 files, the manifest is often an external file with the same name plus “.manifest”. (Example: The manifest for My.exe would be named My.exe.manifest.) See Creating a Win32 Assembly on page 128. „ Assembly Attributes This displays the assembly’s culture, name, publicKeyToken, and version attributes. If this information has not been pre-filled, click Add to enter it. Enter the Name and Value for each of the assembly’s attributes. For information on obtaining assembly attributes, see Creating a .NET Installation Without the .NET Framework on page 240. 4. „ Show reference in Visual Studio .NET Mark this to add a registry key that displays this assembly as a reference in Visual Studio on the destination computer. (Visual Studio .NET 2002 or later only.) This lets you pull the assembly into a Visual Studio project without having to browse for it. „ Execute Install method on this assembly A .NET assembly can contain an install object that performs additional installation functions unique to the assembly. Mark this to execute this assembly’s install object after the file is installed. „ Generate native-code version during installation Mark this to run the Native Image Generator (ngen.exe) on the assembly after it is installed. The Native Image Generator precompiles portions of the assembly and caches it on the target computer so assemblies load and execute faster. For details, search for “Native Image Generator” in the MSDN Library (msdn.microsoft.com/library/). Click OK. See also: Editing File Details on page 123 Creating a Win32 Assembly Your can use Win32 assemblies to isolate applications on destination computers running under Windows XP or later. Isolating an application .EXE means its dependent, shared .DLL and .OCX files are placed in the application directory or in the WinSxS directory rather than in a non-side-by-side location. This ensures that your application always uses the version of .DLL or .OCX with which it was installed. It prevents overwriting of previous versions of the .DLL or .OCX and ensures that other applications do not overwrite your version of shared files. Windows Installer Editor Reference 128 Assembling an Installation You isolate a Win32 assembly by means of a manifest file, which describes the assembly and any resources it depends on. Options for adding a Win32 assembly and its manifest to an installation are: z Create a manifest for a Win32 assembly outside Windows Installer Editor, then add the assembly and its manifest to the installation as you would any other files. On the Assembly tab of the File Details dialog box, mark it as a Win32 assembly and specify the manifest file. z Use the procedure below to create a Win32 assembly and manifest on the Manifest File Details dialog box. This populates the MsiAssembly and MsiAssemblyName tables. Warning Isolation does not work on all applications. Applications must be written according to Microsoft programming guidelines to work with operating system isolation methods. (Example: If an application hard-codes paths to support files, isolation might not work.) For details, see the following topics in the Windows Installer SDK Help: Isolated Components, Installation of Win32 Assemblies, Side-by-Side Assemblies. Also, search for “assembly manifest” and “isolated applications” in the MSDN Library (msdn.microsoft.com). To create a Win32 assembly and manifest 1. Add the application file and its dependent files to the installation. 2. In Installation Expert > Files or Web Files page, double-click the application file in the lower-right list box. The File Details dialog box appears. 3. Click the Assembly tab. 4. From Assembly Type, select Win32. Attributes are read from the file and displayed in the Assembly Attributes list, and a manifest file name is entered in Manifest. 5. To add dependencies to the manifest file, click Edit. The Manifest File Details dialog box appears. 6. Click Add, then select an option: „ Installed File Adds a dependency to a file that is in the installation. On the Select File dialog box that appears, select the dependency file and click OK. The dependency file is added to the installation as a side-by-side assembly. It is marked as a Win32 assembly and a manifest is created for it. „ External Manifest Adds the attributes of an external manifest file as a dependency. Specify a manifest file and click OK. The manifest you specify and the file it points to must be present on the destination computer or in the installation. They must also be located in the application’s directory structure or the WinSxS directory. See Private Assemblies in the Windows Installer SDK Help. 7. To add more dependencies, repeat the preceding step. 8. Mark Use XP Common Controls to add a dependency on the Common Controls Version 6.0, which gives the Win32 assembly .EXE the look and feel of Windows XP. Windows Installer Editor Reference 129 Assembling an Installation For details, search for “Windows XP visual style” in the MSDN Library (msdn.microsoft.com). 9. Click OK, then click OK on the File Details dialog box. The manifest file is created in XML format and added to the installation with the same name as the dependent file plus “.manifest”. (Example: The manifest for My.exe would be named My.exe.manifest.) The manifest is also added to your computer with the extension .XML. (Example: If you add C:\Program Files\My.exe and make it a Win32 assembly, the file C:\Program Files\My.exe.xml is created.) See also: Editing File Details on page 123 Editing Assembly Settings for Files on page 127 Viewing Shared File Resources The Shared Resources tab on the File Details dialog box displays all packages in the Software Manager database that use a specific file, even if they install the file to a different location. This lets you: z Determine the correct version of the file to use in your application by checking whether the file is used by packages that have already been deployed. z Resolve potential file conflicts during the development cycle. When the file in the current installation conflicts with a file in the Software Manager database, you can replace the current file with the correct version from the repository. You also can view shared file resources in a report format. See Generating Shared Resource Reports on page 27. To view shared file resources 1. Do one of the following: „ In Installation Expert: On the Files or Web Files page, double-click a file. „ In Setup Editor: On the Components or Features tab, double-click a file. The File Details dialog box appears. 2. Click the Shared Resources tab. A white exclamation point to the left of the package indicates that the current file is already in the Software Manager database and it does not conflict with the file used by that package. A red exclamation point to the left of the package indicates that the current file conflicts with the file used by that package. Examples: The files have a different version, date/time, or size; the files are installed to the same directory, but component GUIDs do not match. To select a different file 1. On the Shared Resources tab of the File Details dialog box, select the package that contains the version of the file you want to use. 2. Click Use Instead. Windows Installer Editor Reference 130 Assembling an Installation This button is unavailable when: the package you selected above is the one that is currently open; there is no conflict; or the source file listed in the Wise Software Repository cannot be found (example: the file has been deleted). 3. Click OK. The current file is replaced with the version of the file in the Software Manager database. If a conflict existed, the exclamation point to the left of the package changes from red to white. See also: Editing File Details on page 123 Editing XML Files During Installation When you add an XML file, such as Web.config, to the Files or Web Files page, and then get details for the XML file, the Dynamic Content tab appears, which shows the file’s contents. The purpose of the Dynamic Content tab is to let you modify the XML file by inserting system-specific information such as local directory paths and user names. Because this information is different for each server, you use Windows Installer properties to specify dynamic items. Note If you add an XML file, but the Dynamic Content tab does not appear in the file’s details dialog box, the file was not recognized as a well-formed XML file. Check the file for irregularities and verify it adheres to XML and Microsoft authoring standards. To set values to be replaced in an XML file at run time 1. In Installation Expert > Files or Web Files page, add a valid XML file. 2. Double-click the XML file and select the Dynamic Content tab. The contents of the XML file appear in the list box. 3. Mark Enable Dynamic Content. The Edit button becomes enabled for editable lines only after you mark Enable Dynamic Content. 4. Select a line and click the Edit button. Not all lines are editable, only lines that have name-value attributes. (Example: .) The Attribute Editor dialog box appears. 5. To edit an XML attribute: a. Select the attribute in the top list box. b. In Dynamic Value, type a new value to replace the current value at run time. You can enter bracketed Windows Installer property names. You must have added a mechanism elsewhere in the installation to populate the property. (Example: Use the Custom Property dialog; see Adding the Custom Property Dialog on page 425. Or use properties defined in Run Time Properties on page 515.) c. Alternatively, you can select a property name from Property and click the Insert into Dynamic Value button. Windows Installer Editor Reference 131 Assembling an Installation 6. Click OK on the Attribute Editor dialog box when finished. At run time, the attribute is replaced with the dynamic value you specified. Windows Installer properties are resolved to their value. See also: Editing File Details on page 123 Editing DIFxApp Options When an installation contains a device driver that meets Microsoft Driver Install Frameworks (DIFx) driver requirements, you can use Microsoft’s Driver Install Frameworks for Applications (DIFxApp) to install the driver. See Creating a Device Driver Installation on page 71. You edit the DIFxApp options on the Driver tab of the File Details dialog box. This tab appears only if all of the following are true: z The DIFxApp merge module has been added to the installation. Note Early versions of this merge module might be named “Binaries.” z You selected an .INF file on the Files page. z The .INF file is the key path of the component. To edit DIFxApp options 1. Double-click the device driver’s .INF file on the Files page or on the Components or Features tab in Setup Editor. The File Details dialog box appears. 2. Click the Driver tab. 3. Complete the dialog box: „ Use DIFxApp to install this driver file When you mark this check box, the other options become enabled. They are all marked by default. „ Retain better-matching PnP function drivers Mark this to retain the device’s Plug and Play function driver if it is a better match for the device than the driver in the installation. If you clear this check box, the installation’s plug and play function driver is always installed. „ Prompt for missing device Mark this to prompt the end user to connect a device to the computer if the device matches this driver and is disconnected. „ Create entry under Add/Remove Programs Mark this to make this driver package removable through Add/Remove Programs. „ Driver Installation Order This list box displays the .INF file you selected on the Files page and every other .INF file in the installation that uses DIFxApp for its installation. Use the Move Up and Move Down buttons to move the .INF file you selected on the Files page. Windows Installer Editor Reference 132 Assembling an Installation 4. Click OK. How Self-Registration Information is Captured When you add a .DLL or .OCX file containing COM self-registration information to an installation, its registration information is scanned and the appropriate registry keys are added to the installation. This system of registration is more robust than letting the file self-register at installation time because it does not depend on the presence of other files on the destination computer or on how well the .OCX or .DLL file adheres to selfregistration conventions. How self-registration information is scanned z When a file is added to an installation, its type libraries are scanned for registration information and the appropriate registry keys are added to the installation. You can set options in Wise Options to rescan and update the installation each time you compile. Additional options determine whether the advertising information is added to the advertising tables (AppId, Class, Extension, Mime, ProgId, TypeLib, Verb), to the registry, or both. See Setting General Options on page 33. z A more powerful scanning method captures information not available in the type library, such as extensions, keys in hives other than HKEY_CLASSES_ROOT, and keys in sections other than CLSID, Interface, Mime, Typelib, or ProgIds. To use this method, do one of the following: „ On the Component Details dialog box, mark Self-register the key path file before compile. Each time you compile, files in the component are reregistered, the registration information is rescanned, and any new information is added to the installation. See Adding and Editing a Component on page 370. „ Use the WiseComCapture.exe utility to extract a file’s registration information to a .REG file, from which you can import registry keys into the installation. Use this method to avoid registering the files on your computer. See Using WiseComCapture.exe. Using WiseComCapture.exe before you can scan a file’s self-registration information and add it to an installation, the file must be registered on your computer. If you prefer not to register files on your computer, you can run the scan routine as a stand-alone utility on a different computer. This utility, WiseComCapture.exe, is in the Windows Installer Editor installation directory. It extracts the registration information to a .REG file, from which you can import registry keys into the installation. To scan a file’s self-registration information and add it to an installation 1. Copy or install the files to self-register onto a computer other than your build computer. 2. Copy WiseComCapture.exe to a location you can access from the other computer. 3. Run WiseComCapture.exe from the command line, using the following syntax: WiseComCapture.exe /r /u Input_COM_Full_pathname Output_REG_pathname Windows Installer Editor Reference 133 Assembling an Installation where: „ /r self-registers the files before extracting the registry information. „ /u self-unregisters the files after the extraction is finished. „ Input_COM_Full_pathname is the path to the file or files that should be selfregistered. „ Output_REG_pathname is the path and file name of the .REG file to which the registry information will be extracted. This file must be accessible to anyone who will be working on the installation. The files are registered and the registry information is extracted to the .REG file you specified. 4. On the build computer, do one of the following to import the .REG file: „ On the Registry page, import the .REG file you created. This method imports the information once but does not update it if the file’s registration information changes. See Importing and Exporting Registry Entries on page 143. „ In Setup Editor > Components tab, display the Component Details dialog box for the component containing the file. In Import .REG File, specify the .REG file you created. Mark Extract advertising information from registry file. See Adding and Editing a Component on page 370. If you rerun WiseComCapture.exe whenever the file’s registration information changes, its registry information will be imported from the .REG file. See also: How Self-Registration Information is Captured on page 133 Resolving File Conflicts Within Windows Installer Editor ¾ Not available in Standard Edition. You can detect and resolve conflicts between a package that is still in the authoring phase and those that have already been deployed, without importing the package into the Software Manager database. The best time to do this is as you add files to an installation. This lets you: z Streamline repackaging by identifying conflicts earlier in the process. z Maintain your Software Manager database as a pristine image of packages that have already been deployed in the production environment. Example: Suppose you are working on an update to Application A, which is scheduled for a future release. You import Application A into the Software Manager database to resolve conflicts. Another member of your team is working on Application B, which uses older versions of some of the files in Application A. When you import Application B into the Software Manager database, these files conflicts are found and resolved by pulling in the newer versions from Application A. You release Application B with files from Application Windows Installer Editor Reference 134 Assembling an Installation A that have not been released. You can avoid this situation by resolving conflicts without importing into the Software Manager database. How Windows Installer Editor detects conflicts Windows Installer Editor compares the files each application installs and records files that conflict. Resolving a conflict involves looking at each file that is installed by more than one package and selecting which version to install on the destination computer. You also can change the location of conflicting files so that each package can use its version of the file. When you resolve conflicts from Windows Installer Editor, all conflicts are resolved in the current installation only; the Software Manager database is never changed. Options for resolving conflicts z Resolve Conflicts with Rules Uses ConflictManager’s conflict resolution rules to resolve conflicts automatically. See Resolving Conflicts With Rules in Windows Installer Editor. z Resolve Conflicts Runs the Resolve wizard, which lets you review and resolve file conflicts one at a time. See Resolving Conflicts Individually in Windows Installer Editor on page 136. Resolving Conflicts With Rules in Windows Installer Editor ¾ Not available in Standard Edition. Using conflict resolution rules is the fastest way to resolve conflicts. The rules do the conflict analysis and resolve the conflicts automatically. This saves time, reduces errors, and provides consistency in conflict resolution. See Conflict Resolution Rules in the ConflictManager Help. To resolve conflicts with rules in Windows Installer Editor 1. Select Tools menu > Resolve Conflicts with Rules. The Resolve with Rules dialog box appears. 2. From Datasource, select the Software Manager database containing the applications to use for conflict resolution. If the database is not listed, click Open. The Select Data Source dialog box appears. This is a standard Windows ODBC connection wizard, which lets you connect to a database through an ODBC data source. 3. From Group, select the group that contains the packages to compare this installation to. 4. From Rule Set Name, select the rule set to use. 5. Click OK. The Resolving Conflicts dialog box appears, and conflicts are resolved. If there are few conflicts to resolve, the dialog box appears briefly. When the resolution is finished, you should see the changes in the installation. Example: If a file was moved to a private directory, that directory should appear on the Files page. Windows Installer Editor Reference 135 Assembling an Installation Rules that would change an application in the Software Manager database are ignored, because resolving conflicts from Windows Installer Editor affects the current installation only. As a result, some conflicts might not get resolved. Use the Resolve wizard to resolve any remaining conflicts. See Resolving Conflicts Individually in Windows Installer Editor on page 136. See also: Resolving File Conflicts Within Windows Installer Editor on page 134 Resolving Conflicts Individually in Windows Installer Editor ¾ Not available in Standard Edition. Use the Resolve wizard to resolve file conflicts without using resolution rules, or to resolve conflicts that cannot be resolved automatically with rules. When you resolve conflicts from Windows Installer Editor, all conflicts are resolved in the current installation only; the Software Manager database is never changed. To resolve individual conflicts in Windows Installer Editor 1. Select Tools menu > Resolve Conflicts. The Welcome page appears. 2. From Datasource, select the Software Manager database containing the applications to use for conflict resolution. If the database is not listed, click Open. The Select Data Source dialog box appears. This is a standard Windows ODBC connection wizard, which lets you connect to a database through an ODBC data source. 3. From Group, select the group that contains the packages to compare this installation to. 4. From Isolation method, select an option. Selecting an isolation method activates the Move button on the File Conflicts and File Conflicts in Registry pages. „ Do not move files Do not allow file isolation. „ Isolated Components (98 SE/Me/2000/XP/2003) Isolate files using Windows Installer isolated components. The isolation is managed by the operating system. This method works with Windows Installer packages only. „ Application Paths. Moves files out of the System directory and into a private directory. This method works for Windows Installer and WiseScript packages, and is supported by all Windows operating systems. By default, the files are placed in the application directory. To place files in a different directory, in Application Path Settings, specify a subdirectory of the application directory or the full path to a different directory. You can use variables in the path. 5. Click Next. Windows Installer Editor Reference 136 Assembling an Installation Depending on the number of packages in the Software Manager database and the speed of your computer, conflict detection can take several minutes. When conflict detection is complete, the File Conflicts page appears. The upper list box contains files in the selected package that have conflicts and are not listed in the registry. You usually can move such files without causing problems. The lower list box contains the conflicting files in other packages. 6. In the upper list box, select one or more files and take one of the following actions. See Guidelines for Resolving File Conflicts in the ConflictManager Help. When you resolve a conflict, the exclamation point to the left of the file name changes from red to white. „ To move the selected file to a private directory and change the file path in the package, click Move. This button is not available if you selected the Do not move files isolation method. Note In most cases, when you move a non-executable file, such as a help file, to an isolated or private directory, the application still uses the version in the shared directory. The advantage of using isolation is that the different versions of the file are saved in the isolated directories and will not be overwritten by other packages. You can add a shortcut to the application to point to the appropriate file location. „ To use the most recent version of the file for the active package, click Latest. If one file has a newer version but another has a newer date/time, the Latest File Selection dialog box appears, where you specify whether to use the file with the newest modified date or the highest internal version number. „ To change the file’s component, click Fix Comp.  If file is a KeyPath to a component in one package but not in another, the file becomes a KeyPath to its own component.  If the file has extra non-advertising resources, they are moved to a new component.  If the file’s shared .DLL counter is not set, it is set. If the component has more than one of these issues, a Fix Options dialog box appears, where you can select which actions to take. „ 7. To apply a file in the lower list box to the current installation, select a file in each list and click Copy Up. The file remains in its current location but will be used to install the installation in the upper list box. Click Next on the File Conflicts page. The File Conflicts in Registry page appears. The upper list box contains files in the selected package that have conflicts and are listed in the registry. The lower list box contains the conflicting files in other packages. 8. In the upper list box, select one or more files and take one of the following actions. See Guidelines for Resolving File Conflicts in the ConflictManager Help. When you resolve a conflict, the exclamation point to the left of the file name changes from red to white. Windows Installer Editor Reference 137 Assembling an Installation „ To move the selected file to a private directory and change the file path in the package, click Move. This button is not available if you selected the Do not move files isolation method. Warning When conflicting files are listed in the registry, moving them to a private application directory can cause problems. ConflictManager updates the registry when a file is moved to a private application directory. This can cause other packages to follow the moved file and result in a further conflict. 9. „ To use the most recent version of the file for the active package, click Latest. If one file has a newer version but another has a newer date/time, the Latest File Selection dialog box appears, where you select whether to use the file with the newest modified date or the highest internal version number. „ To apply a file in the lower list box to the current installation, select a file in each list and click Copy Up. The file remains in its current location but will be used to install the package in the upper list box. „ To open a separate dialog box listing the registry keys that contain the path to the selected file, click Reg Details. When you have resolved all file conflicts, click Finish on the File Conflicts in Registry page. The Resolve wizard makes the changes you specified and closes. The resulting changes should appear in the installation. Example: If a file was moved to a private directory, that directory should appear on the Files page. See also: Resolving File Conflicts Within Windows Installer Editor on page 134 Registry Page Use the Registry page to specify the registry entries to be installed, removed, or edited on the destination computer. You can either add registry entries manually or import a registry file (.REG). If you import a Visual Basic .VBR file, it will import the registry settings, but will not automatically set up for the installation of either a remote automation or DCOM™ server. You also can export to a registry file. When you import a registry entry that points to a standard directory, such as Win32 or Program Files, Windows Installer Editor replaces the path to the directory with formatted text in brackets. As a result, the registry entry automatically points to the correct directory, no matter where it is located. Example: References to C:\Program Files\ are replaced with [ProgramFilesFolder]. In addition, if the registry key points to a file in the installation, it is replaced by [#filekey]. Example: If you have C:\Program Files\MyApp\MyApp.exe in your installation, and you add a registry key that refers to that file, its value becomes [#myapp.exe], assuming myapp.exe is the key to the file in the File table. See Formatted in the Windows Installer SDK Help. Windows Installer Editor Reference 138 Assembling an Installation Registry page in a 32-bit installation Registry keys on your computer. Registry values in the key selected on the left. Registry values to be installed on the destination computer. Registry keys to be created on the destination computer. Registry page in a 64-bit installation On a 64-bit computer, the 64-bit registry is visible here. The button menu lets you add keys to the 32-bit or 64-bit registry. Windows Installer Editor Reference The button menu lets you add values to the 32-bit or 64-bit registry. 139 Assembling an Installation Working with the Registry page z If the installation has multiple features, specify the feature you are configuring by selecting it from the Current Feature drop-down list. z Use the right-click menu to expand or collapse directories, to hide or show empty directories, and to view the 32-bit or 64-bit registry. The upper panes can display the 32-bit or 64-bit registry, but the 64-bit registry is visible only when your computer is running a 64-bit operating system. The lower panes can display the 64bit view on any computer, but only in projects with 64-bit features or releases. z Drag and drop keys and values on the Registry page, or use the following buttons: „ Add Keys Copy a registry key, including all its subkeys and values, from your computer to the installation. In a 64-bit installation, this button contains a menu that lets you specify whether to add the key to the 32-bit or 64-bit registry. „ Add Values Copy values from your computer to the installation. In a 64-bit installation, this button contains a menu that lets you specify whether to add the value to the 32-bit or 64-bit registry. „ Add Create a new key or import a registry file into the installation. „ Delete Key, Delete Value Remove a registry key or value from the installation. „ Details Edit registry key settings. See also: Adding Registry Keys on page 140 Removing Registry Entries From the Destination Computer on page 142 Importing and Exporting Registry Entries on page 143 Configuring General Registry Settings on page 144 Setting Permissions for Registry Keys on page 146 Viewing Shared Registry Resources on page 147 Special Registry Keys on page 147 Adding Registry Keys Use Installation Expert or Setup Editor to add registry keys and values to any registry folder or subfolder. You also can change settings for selected registry keys and rename or delete files and folders. However, you cannot rename or delete a root folder. In Installation Expert, the Registry page displays only the registry keys for the feature in the Current Feature drop-down list. To display registry keys for all features, mark View registry keys for all features on Registry page in Wise Options. In Setup Editor, the Registry icon displays the registry keys and values that are included in the selected feature or component. To add an empty registry key 1. Select Installation Expert > Registry page. Windows Installer Editor Reference 140 Assembling an Installation 2. From Current Feature, select a feature or condition. (Because any item you add must be assigned to a specific feature, you cannot add an item when All Features is selected.) Items that you add to a feature are installed on the destination computer only if the feature is installed. Items that you add to a condition are installed only if the feature is installed and the condition is true. 3. In a 64-bit installation, right-click in the lower-left list box and select 32-bit View or 64-bit View. 4. In the lower-left list box, select the location for the key. 5. Click Add and select Key. The Registry Details dialog box appears. 6. From Operation, select Create empty key. 7. In Key, click at the end of the existing text, and add a backslash and the name of the new key. Example: Append \Preferences to the end of the existing key name. 8. Click OK. To add a registry value in Installation Expert 1. Select Installation Expert > Registry page. 2. From Current Feature, select a feature or condition. (Because any item you add must be assigned to a specific feature, you cannot add an item when All Features is selected.) Items that you add to a feature are installed on the destination computer only if the feature is installed. Items that you add to a condition are installed only if the feature is installed and the condition is true. 3. In a 64-bit installation, right-click in the lower-left list box and select 32-bit View or 64-bit View. 4. In the lower-left list box, select the key to contain the value you’re adding. 5. Click Add and select Key. The Registry Details dialog box appears. 6. Complete the dialog box and click OK. See Configuring General Registry Settings on page 144. To add a registry value in Setup Editor 1. Do one of the following in Setup Editor: „ On the Features tab, expand a feature and then expand its Combined folder. If the Combined folder does not appear, right-click and select Hide Empty Folders/Items. „ Windows Installer Editor Reference On the Components tab, expand a component. 141 Assembling an Installation When an installation contains both 32-bit and 64-bit components, place registry keys in the appropriate location for the platform they target. 2. Expand the Registry icon. 3. To add a new folder, right-click a folder and select New > Folder. Rename the new folder. 4. Right-click a folder and select New > Registry Key. The Registry Details dialog box appears. 5. Complete the dialog box and click OK. See Configuring General Registry Settings on page 144. The registry value is added to the selected feature or component and appears in the lower-right list box. To edit it, double-click its name. To delete it, use the right-click menu. Removing Registry Entries From the Destination Computer You can specify registry keys and values to be removed from the destination computer during installation. This operation affects registry entries that are already on the destination computer, not registry entries that are part of the installation. In Installation Expert, the Registry page displays only the registry keys for the feature in the Current Feature drop-down list. To display registry keys for all features, mark View registry keys for all features on Registry page in Wise Options. Warning Be very careful when removing registry entries from the destination computer. Do not remove registry entries unless you are sure that they are not used by another application. To add a remove registry operation in Installation Expert 1. Select Installation Expert > Registry page. 2. From Current Feature, select a feature or condition. (Because any item you add must be assigned to a specific feature, you cannot add an item when All Features is selected.) 3. Add the registry key and value to the installation. See Adding Registry Keys on page 140. 4. In a 64-bit installation, right-click in the lower-left list box and select 32-bit View or 64-bit View. 5. In the lower-left list box, select the key that contains the value to remove. 6. In the lower-right list box, double-click the value to remove. The Registry Details dialog box appears. 7. From Operation, select Remove value during install. 8. Click OK. A red exclamation point appears over the icon of the registry value you selected to indicate that this value will be removed during installation. Windows Installer Editor Reference 142 Assembling an Installation To add a remove registry operation in Setup Editor 1. Do one of the following in Setup Editor: „ On the Features tab, expand a feature and then expand its Combined folder. If the Combined folder does not appear, right-click and select Hide Empty Folders/Items. „ On the Components tab, expand a component. 2. Expand the Remove Registry icon. 3. Right-click a folder and select New > Remove Registry. The Remove Registry Details dialog box appears. 4. 5. Complete the dialog box: „ Root The top-level key from which the key will be removed. Example: HKEY_CURRENT_USER. „ Key The name of the key to remove. To create an entire key path, separate key names with backslashes (\). Example: NewDocument\Protocol\StdFileEditing. „ Value Name The value to remove. You can enter a formatted text string. For information about formatted text strings, see Formatted and Registry Table in the Windows Installer SDK Help. Click OK. The remove registry operation appears in the upper-right pane. To edit it, double-click its name. To delete it, use the right-click menu. To remove multiple registry keys from the destination computer 1. Select Installation Expert > Registry page. 2. From Current Feature, select a feature or condition. (Because any item you add must be assigned to a specific feature, you cannot add an item when All Features is selected.) 3. Add the registry keys and values to the installation. See Adding Registry Keys on page 140. 4. In the lower-left list box, right-click the key that contains the subkeys and values to remove, and select Remove all subkeys and values on install. A red exclamation point appears over the folder icon of the registry key you selected to indicate that all the subkeys and values of this registry key will be removed during installation. Importing and Exporting Registry Entries You can import registry files (.REG) into an installation. You also can export registry key settings from an installation to a .REG file. RegEdit 4.0 and 5.0 formats are supported for importing; RegEdit 4.0 formats are supported for exporting. Windows Installer Editor Reference 143 Assembling an Installation To import a registry file 1. Do one of the following: „ Select Installation Expert > Registry page. a. From Current Feature, select a feature or condition. (Because any item you add must be assigned to a specific feature, you cannot add an item when All Features is selected.) Items that you add to a feature are installed on the destination computer only if the feature is installed. Items that you add to a condition are installed only if the feature is installed and the condition is true. b. In a 64-bit installation, right-click in the lower-left list box and select 32-bit View or 64-bit View. c. Click Add at the lower left of the Registry page and select Import. „ 2. In Setup Editor, on the Components or Features tab, right-click the Registry icon or a registry folder and select Import from .REG File. On the dialog box that appears, specify a .REG file and click Open. The contents of the selected registry file, along with all corresponding folders, are placed in the appropriate root folder. To export to a registry file 1. Do one of the following: „ Select Installation Expert > Registry page. In the lower-left list box, right-click the key to export, and select Export to .REG File. To export all keys that you have designated for the destination computer, right-click the Destination Computer icon. „ In Setup Editor, on the Components or Features tab, right-click the Registry icon or a registry folder and select Export to .REG File. The Export to .REG File dialog box appears. 2. In File Name, specify the path of the registry file you are creating. 3. In Export As, select the version of RegEdit that the registry file should be compatible with. 4. „ Registration File (*.REG) Export to a Unicode file format. „ Win9x/NT 4 Registration File (*.REG) Export to a flat text file format. Click OK. The .REG file is saved in the location you specified. If the registry key you exported had a property name surrounded by brackets, and that property is defined in the Property table in the Windows Installer database, then the bracketed property name is replaced with the local computer value of the property in the exported .REG file. Configuring General Registry Settings Use the Registry Details dialog box to set or edit the general registry key settings. Windows Installer Editor Reference 144 Assembling an Installation To configure general registry settings 1. Do one of the following: „ In Installation Expert > Registry page, click Add > Key at the lower left of the page. „ Double-click a registry value on the Registry page in Installation Expert or on the Components or Features tab in SetUp Editor. The Registry Details dialog box appears. 2. Complete the dialog box: „ „ Operation Specify what operation will be applied to the key and its associated value.  Create/update key and value If the value exists, it is updated. If the key or value does not exist, it is created.  Create empty key An empty key is created. It is populated with a +.  Remove subkeys for uninstall During uninstall, all subkeys of this key are removed.  Create empty key and remove subkeys for uninstall During uninstall, all subkeys of this key and all named values of the key itself are removed.  Remove value during install This value is removed from the registry key. On the Registry page, a red exclamation point appears over the icon of the registry value you selected. This option appears only when you access the Registry Details dialog box from the Registry page. Root This is enabled only when you access the Registry Details dialog box from the Add button on the Registry page. The top-level key in which the new key will be added. (Example: HKEY_CURRENT_USER.) „ Key This is enabled only when you access the Registry Details dialog box from the Add button on the Registry page. Enter the name of the new key. Create an entire key path by separating key names with backslashes. (Example: Entering NewDocument\Protocol\StdFileEditing creates the StdFileEditing key inside the Protocol key, which is created inside the NewDocument key.) Any keys in the path that do not exist are created. „ Value Name Enter the name of a new named value. You can enter a formatted text string. For information about formatted text strings, see Formatted and Registry Table in the Windows Installer SDK Help. „ Data Value Enter the data for the value. You can enter a formatted text string. (Example: To return the directory that contains MyApp.exe, enter a value of [$component], where component is MyApp.exe; to return the directory and the file name, enter Windows Installer Editor Reference 145 Assembling an Installation a value of [#MyApp.exe].) For information about formatted text strings, see Formatted and Registry Table in the Windows Installer SDK Help. „ Data Type Select the type of data contained in the named value. The associated Windows API data types are in parentheses below.  String (REG_SZ) Identifies the value as an expandable string. To include a property, enclose the property name in square brackets.  Unexpanded string (REG_EXPAND_SZ) Identifies the value as a string that contains unexpanded references to environment variables that are expanded when the value is retrieved. Enclose the environment variables in single percent signs. For example, %PATH%. If you do not want the variable to be expanded, enclose it in double percent signs. For example, %%WIN%%. This allows Windows system variables to be embedded. 3.  Double word (REG_DWORD) Identifies the value as a 32-bit number in decimal notation.  Binary / Hex (REG_BINARY) Identifies the value as a binary in hexadecimal notation. Do not use spaces, commas, or other characters to separate the bytes. Example: AD30C0A94020A8FC4C0008. Click OK. Setting Permissions for Registry Keys Use the Registry Key Permissions dialog box to set permissions to protect your application’s registries against accidental deletion or changes. See Configuring General Registry Settings on page 144. The permissions you set are applied to the domain and user you specify, so you can set different permissions for the same registry key for different users. Set permissions only if you know your users and their domains. Example: If you are a system administrator and want to set permissions for registry keys in an .MSI as appropriate for your network. To add permissions for a domain and user 1. Do one of the following: „ In Installation Expert: On the Registry page, right-click a registry key and select Permissions. „ In Setup Editor: On the Components or Features tab, right-click a registry key and select Permissions. The Registry Key Permissions dialog box appears. 2. Click Add. The Lock Permissions Details dialog box appears. a. Windows Installer Editor Reference Enter the Domain. 146 Assembling an Installation b. Enter or select a User name. c. Click OK. The domain and user names appear in the upper list box, and the list of permissions is enabled. 3. To set permissions, mark the check boxes. You can add multiple users. Viewing Shared Registry Resources The Shared Resources tab on the Registry Details dialog box displays all packages in the Software Manager database that use a specific registry key and value. This lets you ensure that the registry keys that are set by your current application will not conflict with keys set by other packages. You also can view shared registry resources in a report format. See Generating Shared Resource Reports on page 27. To view shared registry resources 1. Double-click a registry value on the Registry page in Installation Expert or on the Components or Features tab in Setup Editor. The Registry Details dialog box appears. 2. Click the Shared Resources tab. See also: Registry Page on page 138 Special Registry Keys In addition to the standard top-level registry keys, a special registry key named HKEY_USER_SELECTABLE is provided. Depending on the operating system, during installation an end user can install an application for the current user only or for all the users of the computer. Registry changes under this key are made to either HKEY_CURRENT_USER or HKEY_LOCAL_MACHINE, based on the end user’s choice during installation. Windows Installer itself also provides registry keys with special functionality. (Example: You can install a key named AlwaysInstallElevated to force Windows Installer installations to always install with elevated privileges.) For a list of these special keys, see User Policies and Machine Policies in the Windows Installer SDK Help. INI Files Page Use the INI Files page to: z Update the contents of an existing .INI file, such as System.ini. z Create an .INI file and write installation properties to it. You cannot use this page to delete part or all of an .INI file. Windows Installer Editor Reference 147 Assembling an Installation The left list box on this page represents the directory tree of the destination computer, and the right list box contains .INI entries you add to the installation. Use the right-click menu to expand or collapse folders and to hide or show empty folders. Note To see the same directory structure that exists on the Files page, mark the View directories for all features on Files page check box in Wise Options. Tips for creating and editing .INI files z After you create an .INI file, you cannot edit its name. You must delete the .INI entry and create a new one. z When you edit an existing .INI file, new .INI file settings are merged into the existing settings. If you enter a section name that already exists, its new parameter assignment lines are added to the existing section. If a section and its variable already exist, the variable’s value is overwritten. z You can use formatted text strings to resolve special substrings in the Section, Key, or Value fields in the INI File table, entering the formatted text directly on the INI File Details dialog box. You also can edit the IniFile table in Setup Editor. For information on formatted text strings, see Formatted in the Windows Installer SDK Help. See Editing Existing Tables on page 379. Creating and Editing .INI Files Note When you change an .INI file and then view its contents, the lines within the changed section might not be in the same order as before the change. This is not a problem because the entries in an .INI file are not order dependent. To create and edit an .INI file from Installation Expert 1. Select INI Files page. 2. From Current Feature, select a feature or condition. (Because any item you add must be assigned to a specific feature, you cannot add an item when All Features is selected.) Items that you add to a feature are installed on the destination computer only if the feature is installed. Items that you add to a condition are installed only if the feature is installed and the condition is true. 3. To create a new folder for the INI file, click New Folder, enter a folder name, and click OK. 4. In the left pane, select a folder and click New File. The INI File Details dialog box appears. 5. Complete the dialog box; see below. 6. Click OK. The INI File entry appears in the right list box. To edit it, double-click its name. To delete it, use the right-click menu. Windows Installer Editor Reference 148 Assembling an Installation To create and edit an .INI file from Setup Editor 1. On the Components or Features tab, expand a component or feature. 2. To create a new folder for the INI file, right-click the INI Files icon or one of its subfolders and select New > Folder. Rename the folder. 3. Right-click a folder and select New > INI File. Note Add the .INI file immediately after creating the folder, because if you create the folder, but fail to put an .INI file entry inside it, the folder is deleted from the installation the next time you save it. The INI File Details dialog box appears. 4. Complete the dialog box; see below. 5. Click OK. The INI File entry is added to the selected feature or component and appears in the upper-right pane. To edit it, double-click its name. To delete it, use the right-click menu. To complete the INI File Details dialog box z INI Filename Enter a name for the new .INI file, or click Import to import an existing .INI file. This file will be created on the destination computer, if it does not already exist. If it exists, the .INI contents you enter will be used to edit the existing .INI file. Note Because Windows Installer does not support writing comments to .INI files, comments are removed from .INI files you import. z INI Settings Enter the information to add or change in the .INI file. The text must be in the correct syntax. Section names must be in brackets and contents must be in the form variable=value. Example: [SECTIONNAME] Color=Red You can enter Windows Installer property names (surrounded by brackets) for both the variable and value. Example: To set a variable named MyAppLocation to the installation directory and add it to the APPLICATIONPATH section, enter: [APPLICATIONPATH] MyAppLocation=[PRIMARYFOLDER] Shortcuts Page The Shortcuts page lets you add, edit, and delete shortcuts for files in the installation, and add icons for shortcuts you will install. You also can create a shortcut for a file on the destination computer that’s not in the installation. Shortcuts for files that have associated shortcuts are created automatically if you select one of the scan advertising options from the Advertising Setting drop-down list in Wise Options. Windows Installer Editor Reference 149 Assembling an Installation Adding a Shortcut to an Installation To add a shortcut 1. Do one of the following: „ Select Installation Expert > Shortcuts page. a. From Current Feature, select a feature or condition. (Because any item you add must be assigned to a specific feature, you cannot add an item when All Features is selected.) Items that you add to a feature are installed on the destination computer only if the feature is installed. Items that you add to a condition are installed only if the feature is installed and the condition is true. b. Click Add at the right of the Shortcuts page. „ In Setup Editor, on the Components or Features tab, right-click a component or feature and select New > Shortcut. The Shortcut Type dialog box appears. 2. Complete the dialog box: „ File in the installation Mark this to have the shortcut open a file in the installation. „ Advertised This is marked by default, which means this shortcut appears on the destination computer regardless of whether its target is installed or advertised. When the end user opens an advertised shortcut, installation of the target .EXE file is started. If you clear this check box, the shortcut appears only if its target is installed, but not if its target is advertised. Note If you designate a shortcut as advertised, and the shortcut’s target is deleted, selecting that shortcut performs self-repair. Self-repair is not performed for non-advertised shortcuts. „ Command Line Mark this to have the shortcut execute a command-line statement. Use this option to open a file that’s not part of the installation, but only if you’re sure the file exists on the destination computer.  Command Line Enter the entire command-line statement, including arguments and other command-line options. Enclose the statement in quotation marks if it contains spaces. See Editing a Shortcut Configuration on page 151.  3. Shortcut Name Enter a name for the shortcut. Click Next. If you created a shortcut for a file in the installation, the Shortcut File Selection dialog box appears. 4. Select the installation file to create a shortcut for and click Next. Windows Installer Editor Reference 150 Assembling an Installation Note Files added under the Duplicate Files icon in the Features or Components tabs of Setup Editor do not appear because you cannot add shortcuts for duplicate files. The Shortcut Destination Directory dialog box appears. 5. Specify a directory to contain the shortcut. The predefined directories on this dialog box represent standard system directories on the destination computer, regardless of their actual names. The most common location for application shortcuts is the Start menu’s Programs directory, which is selected by default. To put the shortcut in a new directory, click New Folder to create it. 6. Click Finish. The Shortcut Details dialog box appears, where you can specify further details for the shortcut. When the end user installs your application, this shortcut will appear in the location you specified. See Editing a Shortcut Configuration on page 151. The shortcut appears. To edit it, double-click its name. To delete it, use the right-click menu. Editing a Shortcut Configuration To edit a shortcut configuration 1. Do one of the following: „ Select Installation Expert > Shortcuts page. a. From Current Feature, select a feature or condition. (Because any item you add must be assigned to a specific feature, you cannot add an item when All Features is selected.) b. Double-click the shortcut. „ In Setup Editor, on the Components or Features tab, expand the component or feature that contains the shortcut. Click the Shortcuts icon and double-click the shortcut in the upper-right pane. If the Shortcuts icon does not appear, right-click and select Hide Empty Folders/ Items. The Shortcut Details dialog box appears. 2. Complete the dialog box: „ Name The name of the shortcut. If the name is longer than 8.3 characters, the short (8.3) file name appears first, followed by a pipe character (|) and the long (Windows 95) file name. „ Target File (Read-only.) This contains the file name of the target of this file. You specified this file when you created this shortcut. To create a shortcut to a different file, delete this shortcut entry and create a new one. If you created a command-line shortcut, this field is replaced by the Command Line field. Windows Installer Editor Reference 151 Assembling an Installation „ Command Line This appears only if you created a command-line shortcut. It contains the command-line statement. „ Dest. Directory This lists all predefined directories and directories that you have created. Select the location for the shortcut on the destination computer, or click New Folder to create a new directory. „ Arguments Enter command-line arguments to append to the command-line statement that is executed to start the target of this shortcut. You can enter property names surrounded by brackets to specify standard directories. (Example: To specify a file named Notes.txt in the Windows directory, enter [WindowsFolder]Notes.txt.) For a list of predefined directories, see System Folder Properties in the Windows Installer SDK Help. „ Description Enter a one-line description of the shortcut, which appears when an end user right-clicks on a shortcut file in Windows Explorer and selects Properties. „ Working Directory Select the directory that should be current when the target of this shortcut is started. „ Show Window Select whether the target file opens in a normal, minimized, or maximized window. „ Advertised Mark this to have the shortcut appear on the destination computer regardless of whether its target is installed or advertised. When the end user opens an advertised shortcut, installation of the target .EXE file is started. If you clear this check box, the shortcut appears only if its target is installed, but not if its target is advertised. You can select a new feature or icon only if this check box is marked. „ Feature To associate this feature with a different shortcut, select the feature. Because non-advertised shortcuts cannot be associated with a feature, this field is enabled for advertised shortcuts only. 3. To select a new icon, click New Icon and specify the icon. 4. Click OK. Adding an Environment Variable You can add, edit, and delete environment variables and values to be set by the operating system on the destination computer. You can add environment variables from Installation Expert or Setup Editor. To add an environment variable 1. Do one of the following: „ Windows Installer Editor Reference Select Installation Expert > Environment Variables page. 152 Assembling an Installation a. From Current Feature, select a feature or condition. (Because any item you add must be assigned to a specific feature, you cannot add an item when All Features is selected.) b. Click Add at the right of the page. „ In Setup Editor, on the Components or Features tab, right-click a component or feature and select New > Environment Variable. The Environment Variable Details dialog box appears. 2. Complete the dialog box: „ Name Enter a name for the environment variable. „ Value Enter a value for the environment variable. Note To read the value of an existing environment variable into a property, use the Set Property type of custom action to read it into a property. Enter [%ENVIRONMENT_VARIABLE_NAME] in the Property Value field on the Details tab of the Set Property dialog box while making the action (brackets required). 3. „ Operation Specify how to handle the variable during installation and uninstallation. „ Replacement Specify how to handle an existing value for the variable. „ Windows NT based system environment variable Mark this if this is a Windows NT/2000/XP/2003/Vista system environment variable. Click OK. The environment variable is added. To edit it, double-click its name. To delete it, use the right-click menu. Adding File Associations Use the File Associations page to associate file extensions with executables to determine which application to start when the end user double-clicks a file with a certain extension. You can associate file extensions with any executable file in an installation. File associations are a type of advertising and are stored in the registry. To add a file association 1. Do one of the following: „ Select Installation Expert > File Associations page. a. From Current Feature, select a feature or condition. (Because any item you add must be assigned to a specific feature, you cannot add an item when All Features is selected.) Items that you add to a feature are installed on the destination computer only if the feature is installed. Items that you add to a condition are installed only if the feature is installed and the condition is true. Windows Installer Editor Reference 153 Assembling an Installation b. Click Add at the right of the page and select New. „ In Setup Editor, on the Components or Features tab, right-click a component or feature and select New > File Association. The File Association Details dialog box appears. 2. On the Extension Details tab, select the executable to use for the extension, type an extension, and enter the program ID for the executable. See Determining Extension Settings on page 154. 3. (Optional.) On the Command Verbs tab, click Add, and on the Verb Details dialog box that appears, set the actions that will be available when the end user rightclicks an executable with this extension in Windows Explorer. See Adding Command Verbs on page 155. 4. (Optional.) On the MIME Types tab, mark Show All and mark check boxes to select the MIME types to associate with this extension. See Selecting MIME Types on page 156. 5. Click OK. The file association appears. To edit it, double-click its name. To delete it, use the rightclick menu. In Setup Editor, a new branch of folders is created under the Advertising icon to show the application folder, the Extensions folder, and the ProgId folder. To import a file association 1. Select Installation Expert > File Associations page. 2. From Current Feature, select a feature or condition. (Because any item you add must be assigned to a specific feature, you cannot add an item when All Features is selected.) 3. Click Add at the right of the File Associations page and select Import. The Import File Association dialog box appears. 4. Click Browse to select the executable to use for the extension. You can only select executables that you have already added to the installation. 5. From Extension, select the extension to use. This list shows all available extensions on your computer. 6. Click OK. All relevant information for the extension you select is imported into the Extension Details, Command Verbs, and MIME Types tabs. To edit those tabs, double-click the file association name. See also: Advertising Icon on page 366 Determining Extension Settings Use the Extension Details tab to determine file association settings. Windows Installer Editor Reference 154 Assembling an Installation To determine file association settings 1. Click the Extension Details tab on the File Associations Details dialog box. See Adding File Associations on page 153. 2. Complete the dialog box: „ Executable File Specify the executable to use for the extension. You can only select an executable that is in the installation. „ Extension Enter an extension. Do not include the period. „ ProgID Enter or select the program ID for the executable. This list contains the ProgIDs defined in this installation and the ProgIDs detected for the executable you specified above. „ Description Enter the type of file. The end user sees this description on the Properties dialog box for files of this type. „ Icon Click Change Icon and specify an icon. This icon will be displayed on files of this type on the destination computer. Note The Description and Icon fields are associated with the ProgID, not the extension. If no ProgID is specified, those fields are unavailable. 3. Click OK. Adding Command Verbs Use the Command Verbs tab to determine which actions are available when the end user right-clicks a file with your file association in Windows Explorer. The actions appear in the end user’s right-click menu in the same order that you set here. To add a command verb 1. Click the Command Verbs tab on the File Associations Details dialog box. See Adding File Associations on page 153. 2. Click Add to add a new action or double-click an action. The Verb Details dialog box appears. 3. Complete the dialog box: „ Verb Enter or select the action to be performed when the end user selects the corresponding command from the right-click menu. „ Command Enter the command as it should appear on the right-click menu. This entry is added to the text strings on the Languages page and can be localized. See About the Languages Page on page 263. Windows Installer Editor Reference 155 Assembling an Installation „ 4. Argument Enter command-line options that will be passed to the executable file when the action is performed. The default (%1) is a Windows variable that holds the path of the file that was opened. Click OK. Selecting MIME Types Use the MIME Types tab to select the MIME types to associate with your extension. To select MIME types 1. Click the MIME Types tab on the File Associations Details dialog box. See Adding File Associations on page 153. 2. 3. Complete the dialog box: „ Show All Mark this to display all available MIME types on your computer. To associate a MIME type with an extension, click its check box. If you are an experienced Windows Installer developer, you can add MIME types using the MIME table in Setup Editor. „ Show Associated Mark this to display the MIME types currently associated with the selected file extension. To disassociate a MIME type, clear its check box. Click OK. Services Page Use the Services page to define applications to be installed as a service. You also can start, stop, and delete services that are installed on the destination computer. For information on coding an application to run as a service, consult Microsoft developer documentation. Application files that can be installed as a service are: .EXE, .VXD, .SYS, or .386. Adding a Service to the Destination Computer You can add a service to an installation from Installation Expert or Setup Editor. After you add a service, you can set options to start, stop, and delete services on the destination computer. See Controlling Services on the Destination Computer. To add a service 1. Select Installation Expert > Files page. 2. From Current Feature, select a feature or condition. (Because any item you add must be assigned to a specific feature, you cannot add an item when All Features is selected.) Items that you add to a feature are installed on the destination computer only if the feature is installed. Windows Installer Editor Reference 156 Assembling an Installation Items that you add to a condition are installed only if the feature is installed and the condition is true. 3. Add the file that runs the service. Application files that can be installed as a service are: .EXE, .VXD, .SYS, or .386. 4. Do one of the following: „ Select Installation Expert > Services page. From Current Feature, select a feature or condition. Click Add at the right of the page and select Create Service. „ On the Features or Components tab in Setup Editor, right-click a feature or component and select New > Service. The Select File dialog box appears, which displays only the files that are associated with the currently-selected feature. The left list box displays the directory structure of the installation, and the right list box displays files in the selected directory. 5. Select a file in the right list box and click OK. The Create Service Details dialog box appears. 6. Complete the dialog box: The options you set on the Create Service Details dialog box are dependent on how you coded your service. Some of the options correspond to options in the Services application. For details, see ServiceInstall Table in the Windows Installer SDK Help. „ Service Name Enter the name of the service. This name is used internally by the service to register itself properly in the registry, so this value must match the internal name of the service that’s stored within the application file. You can see the internal name in Windows Task Manager or the SCList Windows utility. „ Display Name The name that appears in the Services application. „ Description Enter a description for the service. This appears only in the Windows 2000 Services application. „ Executable Displays the file you selected on the Select File dialog box, which runs the service. „ Arguments Enter any arguments to be passed to the service on the command line at startup. „ Login Username, Password Enter the Windows account information for the account the service is to run under. Example: .\Username or Domain\Username. „ Load Order Group Enter the group that this service will be a part of. Groups are loaded alphabetically at startup. „ Dependencies Enter the names of any other services that must be running before this service can start. Windows Installer Editor Reference 157 Assembling an Installation „ 7. Error Control Specify what happens if an error is reported while starting the service.  Ignore Error Logs the error in an error log and continues.  Normal Error Displays a message to the end user and logs the error in an error log.  Critical Error Restarts the system and sets it to the last known good menu. „ Service that runs in its own process Mark this if the service runs as its own process. „ Service that shares a process with others Mark this if the service runs as a shared process, such as a kernel driver or file system driver. „ Automatic Mark this to have the service always start when the destination computer is started. „ Manual Mark this to have the service enabled but not automatically started. If this option is marked, the end user can start the process manually using the Services control panel or Services application. „ Service interacts with desktop Mark this to have the service display UI (examples: an application window, an item on the taskbar, and so on) to the end user while it is running. Click OK. The service appears. To edit it, double-click its name. To delete it, use the right-click menu. Controlling Services on the Destination Computer You can start, stop, and delete services that are in the installation or services that are already installed on the destination computer. See Adding a Service to the Destination Computer on page 156. To control a service 1. Do one of the following: „ Select Installation Expert > Services page. a. From Current Feature, select a feature or condition. (Because any item you add must be assigned to a specific feature, you cannot add an item when All Features is selected.) Items that you add to a feature are installed on the destination computer only if the feature is installed. Items that you add to a condition are installed only if the feature is installed and the condition is true. b. Click Add at the right of the page and select Service Control. „ Windows Installer Editor Reference On the Features or Components tab in Setup Editor, right-click a feature or component and select New > Service Control. 158 Assembling an Installation The Service Control Details dialog box appears. 2. 3. Complete the dialog box: „ Service Name Select a service contained in the currently-selected feature, or enter the name of a service you expect to be installed on the destination computer. This name is used internally by the service to register itself properly in the registry, so this value must match the internal name of the service that’s stored within the application file. „ Arguments Enter any arguments to be passed to the service on the command line at startup. „ Install Action Mark the actions to perform on the service when your application is installed. „ Uninstall Action Mark the actions to perform on the service when your application is uninstalled. „ Wait for service action to complete before continuing Mark this if the installation should wait until the actions specified above finish before continuing with installation. Click OK. The service control item appears. To edit it, double-click its name. To delete it, use the right-click menu. Note To both stop and delete a service, do not mark both the Stop Service and Delete Service check boxes in the same control service action; instead, create two control service actions. On the first control service action, mark Stop Service and Wait for service action to complete before continuing. On the second control service action, mark Delete Service. This ensures that the service is completely stopped before the installation tries to remove it. Adding an ODBC Item You can use Installation Expert or Setup Editor to define the ODBC (Open Data Base Connectivity) data sources, drivers, and translators to include in an installation. For information about ODBC, consult technical documentation provided by Microsoft. To add an ODBC item 1. Do one of the following: „ Select Installation Expert > ODBC page. a. From Current Feature, select a feature or condition. (Because any item you add must be assigned to a specific feature, you cannot add an item when All Features is selected.) Items that you add to a feature are installed on the destination computer only if the feature is installed. Items that you add to a condition are installed only if the feature is installed and the condition is true. Windows Installer Editor Reference 159 Assembling an Installation b. Click Add at the right of the ODBC page and select Driver, Data Source, or Translator. „ On the Features or Components tab, right-click a feature or component, select New, and select ODBC Source, ODBC Driver, or ODBC Translator. The corresponding dialog box appears. 2. Complete the dialog box and click OK. For details, see: „ Setting ODBC Data Source Details on page 160 „ Setting ODBC Driver Details on page 160 „ Setting ODBC Translator Details on page 161. The ODBC entry appears. To edit it, double-click its name. To delete it, use the rightclick menu. Setting ODBC Data Source Details To set ODBC data source details 1. Access the ODBC Data Source Details dialog box. See Adding an ODBC Item on page 159. 2. 3. Complete the dialog box: „ Data Source Name Enter a name for the data source, or click Import to import data source information from a saved data source file. If you click Import, the Select Data Source dialog box appears, which displays a list of ODBC data sources that are currently registered on your computer. „ Driver Enter the driver name that will be used to access this data source. If you don’t know the exact spelling of the driver name, click Import to import the data source. „ Register Per Machine, Register Per User Mark Register Per Machine to give all users on the destination computer access to the data source, or mark Register Per User to give only the user who installs the application access to the data source. „ Source Attributes Enter attributes for the data source, one per line, in keyword=value format. Press Ctrl+Enter to move to the next line. Click OK. Setting ODBC Driver Details To set ODBC driver details 1. Access the ODBC Driver Details dialog box. See Adding an ODBC Item on page 159. 2. Complete the dialog box: Windows Installer Editor Reference 160 Assembling an Installation 3. „ Driver Name Enter a name for the driver, or click Import to import driver information from a saved driver file. If you click Import, the Select ODBC Driver dialog box appears, which displays a list of ODBC drivers that are currently installed on your computer. „ Driver .DLL Specify the path to the .DLL used for this driver. „ Setup .DLL Specify the path to the .DLL used to configure this driver. „ Driver Attributes Enter attributes for the driver, one per line, in keyword=value format. Press Ctrl+Enter to move to the next line. Click OK. Setting ODBC Translator Details To set ODBC translator details 1. Access the ODBC Translator Details dialog box. See Adding an ODBC Item on page 159. 2. 3. Complete the dialog box: „ Description Enter a description of the translator, or click Import to import an existing translator. If you click Import, the Select ODBC Driver dialog box appears, which displays a list of ODBC translators that are currently installed on your computer. „ Translator File Specify the file that contains the translator. „ Setup File Specify the file that contains configuration data for the selected translator. Click OK. Adding to the Windows Firewall Exception List The Windows Firewall that is included with Windows XP SP2, Windows Server 2003 SP1, and later, controls which applications and ports on the destination computer can accept incoming traffic from the Internet or a network. When Windows Firewall detects incoming traffic, it blocks the connection and prompts the end user to block or allow the connection. If the end user allows the connection, the application or port is added to the Windows Firewall exception list, so that future connections to that application or port are not blocked. On the Firewall Exceptions page, you can specify application files and ports to be added to the Windows Firewall exception list during installation. This adds custom actions to the installation, which add the exceptions to the Windows Firewall exception list. When your application is installed, it can accept incoming traffic and open required ports on the destination computer without end user intervention. This is useful for games and other similar applications. Windows Installer Editor Reference 161 Assembling an Installation If your installation contains an exception that is already in the Windows Firewall exception list on the destination computer, it will not overwrite that existing exception. Also, only exceptions that are installed with your application are removed when your application is uninstalled. Example: Your installation installs a multi-player network game, which requires multiple users to communicate with each other over the Internet. On computers that use Windows Firewall, end users are prompted the first time another player tries to communicate with them. If you add the port that the game uses to the Windows Firewall exception list, then the game communication can occur without prompting the end users. Operating system notes The ability to add Windows Firewall exceptions to an installation is not restricted by the operating system that is running on your build computer. The operating system on the destination computer determines whether the exceptions are implemented. z When the destination computer is running Windows XP SP2, Windows Server 2003 SP1, or later, the exceptions are added to the Windows Firewall exceptions list. z When the destination computer is running an operating system that does not have Windows Firewall, the installation runs normally and the Windows Firewall exceptions are ignored. To add to the Windows Firewall exception list 1. Select Installation Expert > Firewall Exceptions page. 2. From Current Feature, select a feature or condition. (Because any item you add must be assigned to a specific feature, you cannot add an item when All Features is selected.) Items that you add to a feature are installed on the destination computer only if the feature is installed. Items that you add to a condition are installed only if the feature is installed and the condition is true. 3. Click Add at the right of the Firewall Exceptions page. The Exception Type dialog box appears. 4. 5. Specify the type of exception to add: „ Application file. Do this to allow traffic to this specific file through any port. Go to step 5. „ Port. Do this to allow traffic from any application through this specific port. Go to step 6. To add an application file: a. On the Exception Type dialog box, mark Application and click Next. The Application Selection dialog box appears and displays files in the installation with the following extensions: .EXE, .COM, or .ICD. b. Select a file. A file can appear in the exception list only once. The Friendly Name defaults to the file name. You can edit this information. c. Windows Installer Editor Reference Click Finish. 162 Assembling an Installation 6. To add a port: a. On the Exception Type dialog box, mark Port. b. In Friendly Name, enter a descriptive name for the port. c. In Port Number, enter the number of the port to open. d. Mark TCP or UDP to specify the communications protocol. A combination of port number and protocol type can appear in the exception list only once. e. Click Finish. The exception appears. To edit it, double-click its name. To delete it, use the right-click menu. When you edit an application exception, you can only change the Friendly Name. When you edit a port exception, you can change the Friendly Name, the Port Number, and the protocol type. When a file that is specified in an exception is deleted from the installation, the exception entry and the associated custom actions are removed also. Windows Installer Editor Reference 163 Chapter 6 Your Installation on the Destination Computer This chapter includes the following topics: z About System Requirements on page 164 z Performing a System Search on page 167 z Setting Version-Specific Windows Installer Options on page 174 z Setting Features for Installation Types on page 179 About System Requirements You can define system requirements for an installation in two different areas of Windows Installer Editor: z System Requirements page You can use a point-and-click interface to set requirements for the operating system, the Internet Explorer version, and screen attributes. You can specify minimum hardware and software requirements for the installation and set warning messages that display to the end user if the destination computer does not meet specified requirements See Setting a Requirement on the System Requirements Page. z Launch Conditions icon This is in Setup Editor > Product tab. It lets you build complex conditions using Windows Installer run-time properties that test aspects of the destination computer. See Setting a Requirement by Creating a Launch Condition on page 166 Setting a Requirement on the System Requirements Page This procedure applies to any system requirement that you set on the System Requirements page. Notes on specific system requirements follow the procedure. To set a requirement on the System Requirements page 1. Select Installation Expert > System Requirements page. 2. Double-click a requirement. The Minimum System Requirements dialog box appears. 3. From the drop-down list at the top of the dialog box, select a requirement. Requirements that begin with “All” or “Do not check” indicate that this requirement is not checked. Any requirement you select includes not only the requirement but also any greater value. Example: Selecting a Windows version of Windows XP lets an installation run on any computer with Windows XP or any later versions of the same operating system. Windows Installer Editor Reference 164 Your Installation on the Destination Computer 4. In Message Text, enter the error message that appears if the destination computer doesn’t meet the system requirement. It should communicate to the user why the installation cannot run. 5. Click OK. Windows Version The requirements you set for the Windows version apply only if the destination computer is running one of the following operating systems: Windows 95 Window 98 Windows Me If the destination computer is running a version of Windows NT, the minimum system requirements specified under the Windows NT Version item are checked instead. Windows NT Version The requirements you set for the Windows NT version apply only if the destination computer is running one of the following operating systems: Window 2000 Windows XP Windows Server 2003 Vista If the destination computer is running Windows 95, Windows 98, or Windows Me, the minimum system requirements specified under the Windows Version item are checked instead. Screen Resolution The minimum required screen resolution. Screen Colors The minimum required screen depth. 24 Million Colors corresponds to True Color in the Display Control Panel. Internet Explorer Version The minimum required version of Microsoft Internet Explorer. Windows Installer Runtime Version The installation will fail if the destination computer lacks the required version of Windows Installer. To prevent this, you can use the Prerequisites page to set the installation to pre-install a later version of Windows Installer. See Adding Prerequisites to a Release on page 195. SQL Server Version Use this option to check for the presence of SQL Server. By default, this value is not checked. This option is useful if you have set up this installation to configure a Microsoft SQL Server on the SQL Server Scripts page. Windows Installer Editor Reference 165 Your Installation on the Destination Computer See Configuring a Microsoft SQL Server During Installation on page 254. .NET Framework Version This verifies the version of the Microsoft .NET Framework. IIS Version Use this option to check for the presence of a Microsoft Internet Information Services (IIS) server. By default, this value is not checked. This option is useful if you have set up this installation to configure a Microsoft Internet Information Services (IIS) server. See About Web Installations on page 242. If you set an IIS Version, then an additional list of requirements appears, which are settings available in IIS 4.0 and later. These requirements match those that are in Internet Services Manager under the Web Service Extensions folder icon. You can double-click any of these requirements to check its state as set on the destination IIS Web server. You can specify the order in which these launch conditions are evaluated in the WiseLaunchCondition table. See Wise Tables on page 504. See also: Importing .NET Framework Security Settings on page 258 About Microsoft .NET Technology on page 493 Requirements for Creating a .NET Installation on page 497 Setting a Requirement by Creating a Launch Condition You can use launch conditions to check system requirements on the destination computer. (Example: The value of properties or environment variables.) Windows Installer defines several properties at run time that are useful for defining conditions. See Hardware Properties and Operating System Properties in the Windows Installer SDK Help. To set basic requirements, use the System Requirements page. See Setting a Requirement on the System Requirements Page on page 164. To create new launch conditions and edit existing ones, use the Launch Conditions icon in Setup Editor > Product tab. To create a new launch condition 1. In Setup Editor > Product tab, right-click the Launch Condition icon and select New > Launch Condition. The Launch Condition Details dialog box appears. 2. Complete the dialog box: „ Condition Enter the new condition or click Build to create a condition in Condition Builder. See Creating Conditions With Condition Builder on page 387. Windows Installer Editor Reference 166 Your Installation on the Destination Computer „ 3. Message Text Enter the error message that appears if the destination computer doesn’t meet the condition. It should communicate to the end user why the installation cannot run. Click OK. The new condition appears in the list in the upper-right pane. Note If the launch condition depends on a system search, move the AppSearch action so that it precedes the LaunchCondtions action in the User Interface sequence. For silent installations, also move the AppSearch action in the Execute Immediate sequence. See About Installation Sequences on page 440. To edit or delete an existing launch condition In Setup Editor > Product tab, select the Launch Condition icon to display current launch conditions in the upper-right pane. z To edit a launch condition, double-click it. z To delete a launch condition, select it and press Delete. Performing a System Search Use the System Search page to search the destination computer: z To find a previous version of your application that wasn’t installed using Windows Installer technology. z To find any files, directories, .INI files, registry entries, or components of a previous version of your application. You can specify the items to search for and then code the installation so the new version is placed in the same location as the previous one, rather than in a default location. z To look for a specific third-party application. Example: You might want to include a feature in your application that is only installed if a certain application is already installed on the destination computer. At run time, the installation searches for the items that are specified on the System Search page and places the results in properties you specify. There is no order to the search, therefore you can’t make one entry depend on another. See: Searching Searching Searching Searching For For For For Files or Directories on page 168 Items in .INI Files on page 169 a Registry Value on page 171 a Previously-Installed Component on page 172 For information on searching for previous versions, see Searching for Existing Applications, Files, Registry Entries, or .ini File Entries in the Windows Installer SDK Help. You can get the product code GUID of the previous installation by filling in the Action Property field on the Upgrade dialog box. See Creating an Upgrade on page 303. Windows Installer Editor Reference 167 Your Installation on the Destination Computer Searching For Files or Directories On the System Search page, you can set up a search for a file or directory on the destination computer. To find a directory, you must search for a specific file contained inside the directory. When you search for a file, Windows Installer stops searching as soon as it finds the first file or directory that matches your specification. Therefore, it is important that you specify unique file or directory attributes for your search. You can specify to return either the full file path or just the directory that contains the file. To search for a file or directory 1. Select Installation Expert > System Search page. 2. Click Add at the right of the page and select File or Directory. The Search for File dialog box appears. 3. Complete the dialog box: „ Property Specify a property name. It will hold the result of the search, which is a file name or directory path. If you’ve already defined a new public property (all uppercase) in the Properties icon on the Product tab, then you can select it from the list; otherwise enter a new property name (all uppercase). If you enter a new property name, and the search fails to find a match, the property value will be null and will be false if used in a condition. „ Operation Select the type of entry for the property:  Search all fixed drives for a file Searches all permanent attached drives for the file. You determine how many levels down the search is performed by entering a search depth. This operation returns the entire path to the file. Example: C:\Program Files\Application\Application.exe.  Search for file: return full file name Searches a specific directory for a file, and returns a full path. (Example: C:\Program Files\Application\Application.exe.) If you select this option, Search Directory becomes enabled.  Search for file: return containing directory only Searches a specific folder for a file, and returns the path to the file without the file name. (Example: C:\Program Files\Application\.) If you select this option, Search Directory becomes enabled. „ Search Directory This is not available when you search all fixed drives for a file. Although you can enter a specific path here, it is best to enter one of the predefined folder properties that are listed in the Directory table of the Tables tab in Setup Editor. Example: Entering [Windows] searches the default Windows directory, regardless of its name or location. „ Search Depth Enter how many directories below the search directory to search. The default, 0, searches only the top level of the directory specified in Search Directory. If you are searching all fixed drives for a file, then 0 searches the root directories only. Enter 1 to search both the top level and the top level’s child directories, 2 to search two levels of child directories, and so on. Windows Installer Editor Reference 168 Your Installation on the Destination Computer „ File Name Enter the name of the file. „ Details Click to specify more details about the file. The Search File Details dialog box appears. 4. If you clicked Details, complete the dialog box: Because the file search stops with the first match, enter as much detail as possible to ensure that the installation finds the correct file. „ File Name Enter the name of the installed file. This is the only required search criteria. „ Min. Version (Optional.) The file’s binary version resource must be equal to or greater than this number. Leave both version fields blank to ignore the file version. „ Max. Version (Optional.) The file’s binary version resource must be equal to or less than this number. Leave both version fields blank to ignore the file version. Note When using the version fields, make sure you consider the binary version resource and not the string version resource. The Windows Properties dialog box for files displays only the string version, which can be different from the binary version. Only the first three segments of a four-segment version string are considered. Example: For 1.0.2.3, only 1.0.2 is considered. „ Min. Size The file’s size must be equal or greater than this number. Leave the default value of 0 to ignore the file size. „ Max. Size The file’s size must be equal or less than this number. Leave the default value of 0 to ignore the file size. „ Languages (Optional.) To search for a file with a particular language ID, enter the language ID. To enter multiple languages, separate the language IDs with commas. 5. Click OK on the Search File Details dialog box. 6. Click OK on the Search for File dialog box. To test the search, add a text box on one of the dialog boxes in the installation. In the text box’s Control Text field, enter the property name (surrounded by brackets) that you assigned to this search. (Example: [MY_PROPERTY].) This causes the value of the property to be displayed on the dialog box. When you run the installation, the property you specified will hold the results of the search. If it is empty, the search failed. Searching For Items in .INI Files On the System Search page, you can set up a search for an item in an .INI file on the destination computer. You can either search for a generic value, or do a special search that’s tailored specifically for a file path or directory path. Windows Installer Editor Reference 169 Your Installation on the Destination Computer Note When you use the System Search page to search for an .INI file, you can only search for .INI files that are inside the Windows or the Winnt directory. Windows Installer does not find .INI files that are located in other directories, even subdirectories within the Windows directory. .INI file terminology z An .INI file consists of sections with the following syntax: [DirectoriesAndFiles] SrcDir=E:\Application\ SrcFiles=E:\Application\Application.exe, E:\Sample\Sample.dll z In the section above, DirectoriesAndFiles is an INI Section Name and SrcDir is an INI Item Name. z Item Field refers to the number of the item in a comma-delimited list. Example: The Item Field for E:\Sample\Sample.dll in the section above is 2 because it is the second item in the list. To add an .INI file to the search list 1. Select Installation Expert > System Search page. 2. Click Add at the right of the page and select INI File. The Read INI File dialog box appears. 3. Complete the dialog box: „ Property Specify a property name. It will hold the result of the search, which is a file name, directory path, or other value, depending on the operation performed by the search. If you’ve already defined a new public property (all uppercase) in the Properties icon on the Product tab, then you can select it from the list; otherwise enter a new property name (all uppercase). If you enter a new property name, and the search fails to find a match, the property value will be null and will be false if used in a condition. „ Operation Select the type of entry for the property:  Read directory name from INI file Use this only if the .INI information you are searching for is a directory path. A search of this type returns the entire directory path. Example: E:\Application\. If you use this operation on .INI information that’s in the form of a file path, or any other form, then this type of search fails. The search also fails if there is more than one value listed for the item, separated by commas.  Windows Installer Editor Reference Read file pathname from INI file Use this only if the .INI information you are searching for is a file path. Example: E:\Application\Application.exe. However, the file name itself is dropped from the search result. A search of this type returns the directory path only, minus the file name. Example: E:\Application\. 170 Your Installation on the Destination Computer If you use this operation on .INI information that’s in the form of a directory path, or any other form, then this type of search fails. The search also fails if there is more than one value listed for the item, separated by commas.  Read raw value from INI file Use this to find any type of .INI information. This type of search has the added benefit of letting you specify the Item Field, which determines which value in a comma-delimited list of values to retrieve. Example: If you set the Item Field to 2 and search this item: Colors=red,blue,green “blue” is returned because it is the second field in the item.  4. INI File Name Enter the name of the .INI file. (Not case-sensitive.) „ INI Section Name Enter the section name that contains the item you’re searching for. Although section names are enclosed in brackets, don’t include the brackets. (Not casesensitive.) „ INI Item Name Enter the name of the item that contains the value you’re searching for. (Not case-sensitive.) „ Item Field This is enabled if you select Read raw value from INI file in the Operation field. If the item you’re searching for contains several values, separated by commas, enter the number of the value’s position in the list of values or enter 0 to get all values. Click OK. To test the search, add a text box on one of the dialog boxes in the installation. In the text box’s Control Text field, enter the property name (surrounded by brackets) that you assigned to this search. (Example: [MY_PROPERTY].) This causes the value of the property to be displayed on the dialog box. When you run the installation, the property you specified will hold the results of the search. If it is empty, the search failed. Searching For a Registry Value On the System Search page, you can set up a search for a registry value on the destination computer. You can either search for a generic value, or do a special search that’s tailored specifically for a file path or directory path. To search for a registry value 1. Select Installation Expert > System Search page. 2. Click Add at the right of the page and select Registry. The Read Registry Value dialog box appears. 3. Complete the dialog box: „ Windows Installer Editor Reference Property Specify a property name. It will hold the result of the search, which is a file name, directory path, or other value, depending on the operation performed by the search. If you’ve already defined a new public property (all uppercase) in the Properties icon on the Product tab, then you can select it from the list; 171 Your Installation on the Destination Computer otherwise enter a new property name (all uppercase). If you enter a new property name, and the search fails to find a match, the property value will be null and will be false if used in a condition. „ Operation Select the type of entry for the property:  Read directory name from registry Use this only if the registry information you are searching for is a directory path. A search of this type returns the entire directory path. Example: E:\Application\. If you use this operation on registry information that’s not in the form of a file path, the search fails.  Read file pathname from registry Use this only if the registry information you are searching for is a file path, such as E:\Application\Application.exe. However, the file name itself is dropped from the search result. A search of this type returns the directory path only, minus the file name. Example: E:\Application\. If you use this operation on registry information that’s not in the form of a directory path, the search fails.  4. Read raw value from registry Use this to find any type of registry information. „ Root Select the root folder that contains the registry value to search for. „ Key Enter an entire key path, separating key names with backslashes. Example: Software\Application\Common. „ Value Name Enter the name of the registry value. To find the default registry value, leave this blank. „ Search 64-bit portion of the registry (64-bit installations only.) Mark this to find registry keys that are designated as 64-bit components. Click OK. To test the search, add a text box on one of the dialog boxes in the installation. In the text box’s Control Text field, enter the property name (surrounded by brackets) that you assigned to this search. (Example: [MY_PROPERTY].) This causes the value of the property to be displayed on the dialog box. When you run the installation, the property you specified will hold the results of the search. If it is empty, the search failed. Searching For a Previously-Installed Component On the System Search page, you can set up a search for a component that was previously installed on the destination computer. The search looks for the component’s GUID in the registry to determine whether the component is installed. You might use this search to find the installation directory of a component installed by a different Windows Installer installation. Example: Suppose you want to find the installation directory of version 1.0 of your Sample1 application. You could use a file search to find the file, Sample1.exe, but it Windows Installer Editor Reference 172 Your Installation on the Destination Computer might take a long time to search all drives. Instead, you could search for the component ID of the component that contained Sample1.exe in the original installation. This type of search is much faster. To perform a component search, you must know the component’s ID. To obtain this ID, you must have access to the .WSI file of the previous installation. You can find the component’s GUID on the Component Details dialog box. See Adding and Editing a Component on page 370.) To add a component to your search list 1. Select Installation Expert > System Search page. 2. Click Add at the right of the page and select Component. The Read Component Settings dialog box appears. 3. Complete the dialog box: „ Property Specify a property. It will hold the result of the search, which is a file name, directory path, or other value, depending on the operation performed by the search. If you’ve already defined a new public property (all uppercase) in the Properties icon on the Product tab, then you can select it from the list; otherwise enter a new property name (all uppercase). If you enter a new property name, and the search fails to find a match, the property value will be null and will be false if used in a condition. „ Operation Select the type of entry for the property: „  Read directory name from component keypath Select this operation if the component you are searching for contains only an empty directory (a Create Directory item) and has an empty key path. This operation returns a directory path. (Example: C:\Program Files\Application\.) If the keypath for this component is a file, ODBC item, or registry item, this operation fails.  Read file pathname from component keypath Select this operation only if the component you are searching for has a file for a key path. In this case, it returns the directory path. Example: C:\Program Files\Application\. Component ID Enter the GUID for the component. See Adding and Editing a Component on page 370 and About GUIDs on page 493. 4. Click OK. To test the search, add a text box on one of the dialog boxes in the installation. In the text box’s Control Text field, enter the property name (surrounded by brackets) that you assigned to this search. (Example: [MY_PROPERTY].) This causes the value of the property to be displayed on the dialog box. When you run the installation, the property you specified will hold the results of the search. If it is empty, the search failed. Windows Installer Editor Reference 173 Your Installation on the Destination Computer Setting Version-Specific Windows Installer Options ¾ Windows Installer 4.0 or later only. Use the Windows Installer Options page to set options for installations that will run on Windows Installer 4.0 or later. The features that these options enable were introduced with Windows Vista. These options are ignored when you run the installation on earlier operating systems. UAC Compatibility Settings The User Account Control (UAC) that was introduced with Windows Vista provides a temporary privilege-elevation model. The settings in this section let you determine the elevation level of an installation. See About UAC Elevation of Windows Installer Installations on page 176. z No elevation required This option disables UAC. Check this check box only if the installation does not access a protected area on the destination computer. When User Account Control is disabled: „ The DisableUAP property is set, which hides the option to install for all users or the current user on the installation’s User Information dialog box. „ The entire installation runs without elevation. „ If the installation tries to access a protected area, it fails. See About Standard User Installations on page 70. z Elevate Deferred Execution sequence only This is the preferred option for most installations. Typically, actions that require elevation should be in the Execute Deferred sequence. At run time, when the installation reaches the Deferred Execution sequence, the user is prompted for administrator credentials. z Elevate entire installation Elevate the entire installation when it contains actions that require elevation but are outside the Execute Deferred sequence. See About UAC Elevation of an Entire Installation on page 178. Restart Manager Installations and updates often require computer restarts when files that are being updated are in use by a running application or service. In Windows Vista, Restart Manager can detect processes that have files in use and stop and restart them without requiring a restart of the computer. Applications that are written to take advantage of Restart Manager can be restarted and restored to the same state and with the same data as before the restart. To enable Restart Manager for this installation, mark the following options: z Use Restart Manager When this installation is run, use Restart Manager to shut down and restart applications and services that have files in use. The use of Restart Manager determines which dialog box appears if the installation tries to update files that are being used: Windows Installer Editor Reference 174 Your Installation on the Destination Computer z „ If Restart Manager is enabled, the Windows Vista Files in Use dialog box (MsiRMFilesInUse) appears. „ If Restart Manager is disabled, the Files in Use dialog box (used in earlier versions of Windows) appears. Restart registered applications that were shut down by Restart Manager When applications are shut down, only applications that are registered with Restart Manager for a restart are restarted. Applications that are not registered are not restarted even if this check box is checked. The following options determine which applications are shut down: „ Attempt to shut down all affected applications Restart Manager attempts to shut down all affected applications. If an application is written to ignore the shutdown request, it is not shut down. „ Shut down all affected applications Restart Manager forces a shut down of all affected applications, including those that are written to ignore the shutdown request. „ Shut down only if all affected applications are registered for a restart If at least one affected application is unregistered, then the attempt to shut down all applications, registered or not, fails and a restart is required at the end of the installation. Log file options If you include logging options, then when the installation is run on Windows Vista, the installation’s Exit dialog box contains an option to view the log file. To set logging options for installations that will run under Windows Installer 4.0 or later, mark the appropriate check boxes: z ! - Flush each line to the log z a - Start up of actions Logs actions as they are started. z c - Initial UI parameters Logs the initial user interface parameters. z e - All error messages z i - Status messages z m - Out-of-memory or fatal exit information z o - Out-of-disk-space messages z p - Terminal properties z r - Action-specific records z u - User requests z v - Verbose output Logs more detailed information about each event or error. z w - Non-fatal warnings z x - Extra debugging information (Windows Server 2003 only) You also can set these options from a command line. See Applying Logging Options to an Installation on page 230. Windows Installer Editor Reference 175 Your Installation on the Destination Computer About UAC Elevation of Windows Installer Installations ¾ Windows Installer 4.0 or later only. In pre-Vista versions of Windows, users frequently logged on as administrators, leaving their computers vulnerable to security breaches. The User Account Control (UAC) that was introduced with Windows Vista provides a temporary privilege-elevation model. A user who needs to run an administrative application can elevate their permissions by providing approval for that application. Installation actions that write to a protected area on the destination computer require elevation. When UAC is enabled and the installation tries to access a protected area, the user is prompted as follows: z A user who is logged on with administrator credentials is prompted to confirm that they want to continue. z A user who is logged on with standard user credentials is prompted to enter a password for an administrator account for the installation to continue. Installations that were created in a Wise product earlier than Wise Package Studio 7.0 SP1 or Wise Installation Studio 7.0 run as if UAC is enabled. Options for elevating Windows Installer installations Option Description Elevate the Deferred Execution sequence In a typical MSI, only the Deferred Execution sequence should contain actions that write to a protected area on the destination computer. The installation runs in standard user mode until it enters the Execute Deferred sequence. Then a UAC prompt appears and the Execute Deferred sequence runs in administrator mode. The prompt appears even if the installation runs silently. This option is the default for most installations. Set this option on the Windows Installer Options page, under the UAC Compatibility Settings section. See Setting Version-Specific Windows Installer Options on page 174. If custom actions do not run or if the installation fails for other elevation-related reasons, consider another elevation method. Windows Installer Editor Reference 176 Your Installation on the Destination Computer Option Description Elevate the entire MSI You can elevate an entire Windows Installer installation. At run time, a UAC prompt appears only when the installation begins. The remainder of the installation runs in an elevated mode. Set this option on the Windows Installer Options page, under the UAC Compatibility Settings section. See Setting Version-Specific Windows Installer Options on page 174. Elevate the entire MSI in the following situations: z When the installation contains custom actions that access protected areas and are located outside of the Execute Deferred sequence. Typically, such custom actions check launch conditions or obtain data to populate installation dialog boxes. z When you cannot or prefer not to wrap the MSI in an EXE. See About UAC Elevation of an Entire Installation on page 178. Wrap the MSI in a WiseScript EXE To elevate an entire Windows Installer installation, you can wrap the MSI in a WiseScript EXE that sets the run level with a manifest file. At run time, a UAC prompt appears only when the EXE begins. The MSI runs in an elevated mode. You can wrap the MSI in an EXE in Installation Expert on the Build Options page. Select one of the options that create an EXE. See Setting Build Options for a Release on page 190. Wrap the MSI in an EXE in the following situations: z When you need to add runtime or prerequisite files to the installation for preinstallation on the destination computer. z When the installation contains custom actions that access protected areas and are located outside of the Execute Deferred sequence. Typically, such custom actions check launch conditions or obtain data to populate installation dialog boxes. When the installation runs in maintenance mode, the MSI runs outside the EXE wrapper. Therefore, a UAC prompt appears when the MSI runs. Create a standard user installation with no elevation If an application is written to be installed and run by standard users without elevation, you can bypass UAC elevation issues. The installation cannot contain actions that access a protected area on the destination computer. If the installation tries to access a protected area, it fails. See Creating an Installation for Standard Users on page 70. See also: Setting Version-Specific Windows Installer Options on page 174 Guidelines for Custom Action Location on page 450 Windows Installer Editor Reference 177 Your Installation on the Destination Computer About UAC Elevation of an Entire Installation ¾ Windows Installer 4.0 or later only. To avoid elevation-related failures, you can elevate an entire installation. At run time, a UAC prompt appears only when the installation first begins. The remainder of the installation runs in an elevated mode. Use this method of elevation when an installation’s User Interface sequence contains the following types of custom actions: z Actions that access a restricted area to check launch conditions or obtain data to populate installation dialog boxes. z Actions that perform an IIS check. These actions usually appear in a Web or server installation. z Actions that access user information or other restricted information. These actions usually appear in a server installation. The option to elevate the entire MSI is on the Windows Installer Options page, under the UAC Compatibility Settings section. See Setting Version-Specific Windows Installer Options on page 174. When you elevate an entire MSI, the custom action WiseElevateCheck is added to the User Interface sequence. Do not remove this custom action from the installation. Note When you create a Web installation or a server installation, Wise IIS-related custom actions are added to the Execute Immediate sequence. These actions are coded to run in an elevated mode. Any other custom actions in the Execute Immediate sequence that access restricted areas are not elevated. Move them to the Execute Deferred sequence. The elevated MSI runs as follows: z A single UAC prompt appears when the MSI begins. No other prompts appear. z During the User Interface sequence, the WiseElevateCheck action determines whether the installation is running with elevated privileges and elevates it if necessary. z If the installation is set to create an installation log, two logs might be created. One log contains little information. The other log appears to contain entries for two installations. If you specified a name for the log file, only one log is created but it might appear to contain entries for two installations. This is normal. When the installation runs in maintenance mode, the installation is not elevated and a UAC prompt appears before the Execute Deferred sequence begins. If the installation contains the Wise IIS-related custom actions in the Execute Immediate sequence, a prompt appears before that sequence as well. You also can elevate an MSI by wrapping it in a WiseScript EXE that sets the run level with a manifest file. See About UAC Elevation of Windows Installer Installations on page 176. See also Guidelines for Custom Action Location on page 450. Windows Installer Editor Reference 178 Your Installation on the Destination Computer Setting Features for Installation Types Use the Installation Types page to determine which features are installed when the end user selects Complete, Typical, or Custom on the Installation Type dialog box. To display the Installation Type dialog box to the end user during installation, you must mark its check box on the Dialogs page. Example: Suppose your application contains three features. You could set the following defaults for the Installation Type dialog box: Installation Type Features Installed by Default Typical Core Complete Core Tutorial Samples Because the Installation Types page simply sets the defaults, the end user can still override these choices during installation by clicking Custom in the Installation Type dialog box, and then turning features on or off on the Select Feature dialog box. To display the Select Feature dialog box to the end user during installation, mark its check box on the Dialogs page. On the Installation Types page, the upper-left list box shows the default installation types: Typical, Complete, and Custom, which correspond to the radio buttons that are presented to the end user on the Installation Type dialog box during installation. The right list box shows the features in the installation. You can collapse or expand the features and their child features using the right-click menu. For each installation type, you can set the following: z Quick access key To change the underlined letter for the access key, double-click an installation type name to make it editable, then change the position of the & (ampersand). The letter that follows the & becomes underlined on the Select Installation Type dialog box. z Whether it is selected by default To set an installation type radio button to be selected by default, select the installation type name in the upper-left list and click Default Installation Type. z Description text This text appears next to the radio button on the Installation Type dialog box. To change the text for a specific installation type, select the installation type name in the upper-left list and change the text in the Description text box. z Default features To set which features are turned on by default during installation, select an installation type name in the upper-left list and mark the check boxes of the features in the list on the right. Warning If you are using the Installation Types page to manage the Installation Type dialog box, do not edit the Installation Type dialog box. Doing so causes the Installation Types page not to work properly. Windows Installer Editor Reference 179 Your Installation on the Destination Computer The following examples illustrate how the selections you make on the Installation Types page appear to the end user. Select Installation Type dialog box Selected by default Description text Access key Select Features dialog box Default features Windows Installer Editor Reference 180 Chapter 7 Organizing Your Installation Into Releases This chapter includes the following topics: z About Releases on page 181 z Customizing a Release on page 185 z Setting Build Options for a Release on page 190 z Adding Prerequisites to a Release on page 195 z Creating Web-Based Installations With WebDeploy on page 201 z Setting Up Media for Distribution on page 207 About Releases Note You can only create releases in a project file (.WSI). In any other file, the pages in the Release Definition page group are fully or partially unavailable. An exception is the Languages page. See About the Languages Page on page 263. You can create an installation that generates different installations for different releases of your application. You do this by creating and customizing releases within the installation. You can create releases that install different features, have different properties, have different output formats, and support different platforms. The Releases page lets you define multiple releases for an installation, edit releases, and delete releases you have created. If you haven’t created additional releases for the installation, the Releases page lists only one release: Default. Example 1: You want to have a standard and an evaluation edition for your application, and you want to release both editions on CD and as Internet downloads. To accomplish this, create four releases: z Standard edition on CD-ROM z Standard edition for the Internet z Evaluation edition on CD-ROM z Evaluation edition for the Internet Example 2: You want to create a single installation project (.WSI) that can produce installation files for 32-bit, x64, and 64-bit Itanium platforms. To accomplish this, create three releases and set the appropriate target platform for each one: z 32-bit edition z x64 edition Windows Installer Editor Reference 181 Organizing Your Installation Into Releases z Itanium edition See Creating Multiple, Platform-Specific Installations from One Project File on page 66. Multiple Releases From a Workbench Process The predefined Workbench process, Repackage for Windows Installer, works with a single .MSI that has the default project file name. If you create multiple releases for a package, you should either customize the process for that project to perform tasks on all .MSIs that are compiled, or write a macro to change the names of the additional .MSIs to the default file name. Working With the Releases Page Use the following buttons: z Details Edit a release. z Add Add a new release. See Creating a New Release. z Delete Delete a release. At least one release is required; if the installation only has one release, you cannot delete it. z Compile Compile a specific release without compiling the entire installation. Select one or more releases and click the Compile button at the right of the Releases page. The Compile button at the bottom of the main window compiles the entire installation. See Compiling An Installation on page 77. You can edit various aspects of each release on the other pages in the Release Definition page group. Creating a New Release Note This page is fully enabled in a .WSI only. In an .MSI or .MST, you cannot add or delete. To create a new release 1. Select Installation Expert > Releases page. 2. Click Add. The Release Details dialog box appears. 3. Enter the following: „ Release Name Enter a unique name that describes the release. Example: Standard_CD-ROM or Standard_Internet. This name appears on the Releases page. „ .MSI File Name Name the installation file for this release. Each release is saved as a separate .MSI. If you leave this blank, the release name defaults to the name of the .WSI Windows Installer Editor Reference 182 Organizing Your Installation Into Releases with the extension .MSI. When an installation has multiple releases, this can cause a compile error, because no two releases can have the same name.  To save the .MSI in a subdirectory of the installation project’s location, precede the file name with a \ and the subdirectory path. Example: \My_Directory\Sample.msi  To populate the file name or subdirectory with the value of one or more properties, enter one or more property names surrounded by brackets. Example: [ProductName].msi You can use one or more specific parts of a property’s value if its segments are period delimited. This is most useful for adding all or part of the product version number to the file name. The syntax is: [property_name.%segment_number%segment_number] You can add characters between the segments, except for periods, numerals, or the % symbol. Examples: If the value of ProductVersion is 1.05.07.25, the following .MSI names result. .MSI File Name Entry Compiled .MSI Name Application_[ProductVersion.%4].msi Application_25.msi Application_[ProductVersion.%1_%2].msi Application_1_05.msi „ Description Enter information to distinguish this release from others. Examples: Evaluation, Optimized for Internet Distribution. This description appears on the Releases page. „ Installation Theme Select the theme for the installation dialog boxes for this release. The theme controls the overall look of the dialog boxes by setting their top or side images and the fonts of the dialog box text. You can use different themes for different releases. Example: Use a different theme for an evaluation release to clearly distinguish it from your standard release. See Changing the Theme of Dialogs on page 399. The theme of the Default release on the Releases page corresponds to the Default Theme on the Dialogs page. Changing the theme on one page changes it on the other. Renaming or deleting the Default release breaks this relationship. „ Compression Type Select the amount of compression. This depends on the media you use to distribute the release. Examples: For an Internet release, use maximum compression for a faster download, but for a release on a CD, use no compression. Higher compression slows the compile. „ Release Type Select Terminal Server Enabled if this release is intended to be installed in a Microsoft Terminal Services or Citrix environment. This sets the installation to be installed per-machine and prevents keypaths for components from being assigned to per-user resources. This option might cause keypaths to be empty, and might cause a one-time repair. Environment variables are duplicated, creating a per-user set and a per-machine set, one of which is installed Windows Installer Editor Reference 183 Organizing Your Installation Into Releases depending on the value of ALLUSERS. Also see ALLUSERS Property in the Windows Installer SDK Help. „ Target Platform Select the target platform for this release. This determines the Template Summary property of the compiled .MSI. The initial default is set by the Target Platform option on the New Installation File dialog box. If the installation previously contained only 32-bit releases, designating a feature or release as 64-bit enables the 64-bit areas of the Files and Registry pages as well as other 64-bit-related areas of the interface. „ Build this release during compile Mark this to have this release compiled when you click Compile at the bottom of the main window. This corresponds to the check box in the Build column on the Releases page. Marking or clearing one check box affects the other check box. 4. To add or edit media settings, click Edit Media. The Media Details dialog box appears. The Edit Media button and the Media section appear only when you first add a new release. See Setting Up Media for Distribution on page 207. 5. Click OK. The release is added to the list on the Releases page. To edit a release, double-click its name. The other pages in the Release Definition page group let you further customize each release. See also: How to Specify the Target Platform on page 62 Outputting a Multiple-Language Release Note This page is fully enabled in a .WSI only. In an .MSI or .MST, you cannot add or delete. Normally, when you compile an installation containing multiple languages, a separate .MSI or .MST is created for each language. However, you can create a single installation that contains multiple languages, and either automatically installs in the destination computer’s language or prompts the end user to select a language. To create a multiple language installation, you must create a release that compiles to an .EXE file. To output a multiple-language release 1. On the Releases page, create a release to contain the multiple languages. See Creating a New Release on page 182. 2. On the Build Options page: „ Current Release Select the release that you just created „ .EXE Options Select one of the following: Windows Installer Editor Reference 184 Organizing Your Installation Into Releases  Single-file .EXE When you select this, you must create a language transform for each additional language. See Creating a Language Transform on page 266. During compile, the transforms are packaged inside the .EXE along with the .MSI.  .EXE that launches external .MSI When you select this, you can use language transforms or you can create a separate .MSI for each language. During compile, settings for the .EXE are stored in a separate .INI file. See INI File Properties on page 512. „ Include all languages in installation .EXE Mark this to embed all the languages that are marked on the Languages page in the output .EXE. „ Always prompt for installation language Mark this to prompt the end user to select a language. Clear this to have the resulting installation verify if one of the languages in the installation is on the destination computer. If so, the installation proceeds in the destination computer’s language. If not, the end user is prompted to select a language. 3. On the Languages page, select the languages you want to include in this release. See Creating a Translated .MSI on page 265. 4. Save and compile the installation. When the end user runs the installation .EXE, the installation either proceeds in the destination computer’s language or prompts the end user to select a language. If you created a single-file .EXE, the .MSI runs with the appropriate transform. If you created an .EXE that launches an external .MSI, the appropriate language .MSI runs. Customizing a Release When you create a new release, it has the same properties, summary items, and features list as the Default release. The Release Settings page lets you customize a particular release by: z Overriding the properties and summary items. These are set for the entire installation in Setup Editor > Product tab. z Selecting the features to include in the release. Features are set for the entire installation in Installation Expert > Features page. The tree structure on the Release Settings page displays features and their hierarchical relationships. Use the right-click menu to collapse or expand all features or child features of selected parents only. z Selecting the components to include in the release. Expand the feature tree structure on the Release Settings page to display the components in each feature. You can share settings between releases, so you can efficiently create releases that share all or most settings. Windows Installer Editor Reference 185 Organizing Your Installation Into Releases Example: Customize a release as an evaluation in which: z The application doesn’t allow the end user to save files. z The product’s name indicates it is an evaluation. z The product’s summary informs the end user that this evaluation release doesn’t allow saving files. Note This page is enabled in a .WSI only. Customizing Properties for a Release Note This page is enabled in a .WSI only. You can use the Release Settings page to override the value of an existing property or add a new property for a specific release. Example: Change the ProductName property to reflect that a particular release is an evaluation version rather than a full version. The property override does not affect property values in other languages in the installation. Example: If a property has a value of 0 in the Default language and a value of 5 in German, and you change the value to 12 on the Release Settings page, the value of the property in the German .MSI will be 5. Each release contains the properties listed under the Properties icon in Setup Editor > Product tab. Only those properties that you change or add for a specific release appear under the Properties icon on the Release Settings page. Properties that you add for a specific release do not appear in Setup Editor. Deleting a property from the Release Settings page removes the override for the specific release. To customize properties for a release 1. Select Installation Expert > Release Settings page. 2. From Current Release, select a release. 3. In the list box, click the Properties icon. 4. Click Add at the right of the Release Settings page. The Property Settings Override dialog box appears. 5. From Name, select an existing property or enter a name to create a new property. 6. In Value, enter an initial value for the property. During execution, the installation might change this value. 7. Click OK. The property appears in the list box. To edit it, double-click its name. Customizing Summary Items for a Release Note This page is enabled in a .WSI only. Windows Installer Editor Reference 186 Organizing Your Installation Into Releases You can use the Release Settings page to override the value of an existing summary item or edit customized summary items. Example: Change the Comment Summary item to reflect that a particular release is an evaluation version rather than a full version. End users can see the summary information by right-clicking the compiled .MSI or .EXE in Windows Explorer and selecting Properties. Note In Windows Vista, the file Properties dialog box does not contain summary information. For information on summary items, see Summary Property Descriptions in the Windows Installer SDK Help. Each release contains the summary items listed under the Summary icon in Setup Editor > Product tab. Only those summary items you change for a specific release appear under the Summary icon on the Release Settings page. You cannot create new summary items. Deleting a summary item from the Release Settings page removes the override for the specific release. To customize summary items 1. Select Installation Expert > Release Settings page. 2. From Current Release, select a release. 3. In the list box, click the Summary icon. 4. Click Add at the right of the Release Settings page. The Summary Settings Override dialog box appears. 5. From Name, select a summary item. 6. In Value, enter a new value or text for the summary item. 7. Click OK. The summary item appears in the list box. To edit it, double-click its name. See also: Specifying Summary Information on page 362 Defining a Feature and Component Set for a Release Note This page is enabled in a .WSI only. The Release Settings page lists all features in an installation. You can: z Select the features to include in a particular release. Example: Turn off a SpellCheck or a SaveAs feature for a evaluation release. z Select the components to include in a release. Example: In a platform-specific release, select only the components that target that platform. To define features and components for a release 1. Select Installation Expert > Release Settings page. 2. From Current Release, select a release. Windows Installer Editor Reference 187 Organizing Your Installation Into Releases 3. If necessary, expand the Features icon in the list box. 4. To include a feature in this release, mark its check box. To exclude a feature, clear its check box. 5. To select which components to include in this release: a. Click the feature name to display the feature’s components in the lower pane. b. Mark the check boxes of components to include. All check boxes are marked by default. See also: Creating Multiple, Platform-Specific Installations from One Project File on page 66 Sharing Settings Between Releases Note This page is enabled in a .WSI only. You can share settings from a release with other releases in the installation. After you initially share settings, the settings for the releases are linked. This means that any change you make to the release settings for any of the linked releases is applied to all other linked releases. At any time, you can break the link. To share settings between releases: 1. Select Installation Expert > Release Settings page. 2. From Current Release, select a release to copy settings to. 3. Click Share at the right of the Release Settings page. The Share Release dialog box appears. 4. From Copy/Share Settings From, select the release that contains the settings to copy. 5. Click OK. The settings of the release in Copy/Share Settings From immediately replace the settings of the release in Current Release. Any change you make to the release settings of either of the linked releases is applied to the other release, until you break the link. To break a link between releases 1. Select Installation Expert > Release Settings page. 2. From Current Release, select a release. 3. Click Share at the right of the Release Settings page. The Share Release dialog box appears. 4. From Copy/Share Settings From, select . 5. Click OK. The link between the selected release and other releases is broken. The current settings of the releases are not changed, but changing settings for one release no longer affects the settings of the other release. Windows Installer Editor Reference 188 Organizing Your Installation Into Releases Example: Creating an Evaluation Release This example describes how you could define an evaluation release for an application. In this example: z The release is named Sample Evaluation. z The application’s summary dialog box indicates that this is an evaluation release. z Potential customers can use the evaluation version indefinitely, but they can’t save any files. Assumptions z On the Features page, you have added a SaveAs feature with the appropriate resources for the default release. z The SaveAs feature includes resources that let end users save files. z On the Releases page, you have created a release named Evaluation. To create a sample evaluation release 1. Select Installation Expert > Release Settings page. 2. From Current Release, select Evaluation. 3. Click the Properties icon. 4. Click Add at the right of the Release Settings page. The Property Settings Override dialog box appears. 5. From Name, select ProductName. 6. In Value, enter Sample Evaluation. 7. Click OK. 8. Click the Summary icon. 9. Click Add at the right of the Release Settings page. The Summary Settings Override dialog box appears. 10. From Name, select Comments. 11. In Value, enter: This is an evaluation version; it does not allow you to save files. 12. Click OK. 13. If necessary, expand the Features icon in the list box. 14. Clear the SaveAs feature’s check box. Windows Installer Editor Reference 189 Organizing Your Installation Into Releases Setting Build Options for a Release Note This page is fully enabled in a .WSI only. In an .MSI or .MST, you cannot add or delete. On the Build Options page, you can customize a release by selecting the format of output files and language options. If the format of the output file is an .EXE, you can select an option to install the .MSI into an SVS layer. When you select this option, you can also specify end user data files to exclude from the SVS layer. See About the Installation of an .MSI into an SVS Layer on page 192 and About the Exclusion of Files on the Build Options Page on page 193. To set build options 1. Select Installation Expert > Build Options page. 2. From Current Release, select a release. 3. Complete the build options listed below. Build options z Use short file names for files uncompressed outside of the install Mark this to abbreviate file names to 8.3 format names. This is useful if you will distribute your installation on CDs with the 8.3 format. z .EXE Options This determines what kind of files are output when you compile this release. If you create an .EXE, you can install Windows Installer and .NET Framework runtimes and run prerequisite files on the destination computer before the main installation. In a 64-bit installation, the .EXE will always be 32-bit. For WebDeploy to be enabled, you must select one of the WebDeploy options. „ Do not create an .EXE file Create only the .MSI file. The installation will work only on computers that have Windows Installer installed. Selecting this disables the remaining options on the Build Options page. „ Single-file .EXE (only valid for files inside .MSI) Place the .MSI file inside an .EXE file. This is the preferred option if you plan to send an installation by email or place it on a Web page. „ .EXE that launches external .MSI Create an .EXE with the same name as the .MSI file. Settings for the .EXE are stored in a separate .INI file. The .EXE itself is small, because it doesn’t contain any runtimes or the .MSI file. This is the preferred option if you place the installation on a CD, because the .MSI does not need to be extracted to the hard drive. See INI File Properties on page 512. „ Windows Installer Editor Reference WebDeploy .EXE Create an .EXE that is optimized for direct downloading from the Internet. The installation will compile to an .EXE that contains the download information, and 190 Organizing Your Installation Into Releases an .MSI file that might or might not be embedded in the .EXE. This sets the Create a downloadable .EXE option on the WebDeploy page, and vice versa. „ WebDeploy .EXE and .INI Change the download information dynamically, perhaps as a result of end user input. The installation will compile to an .EXE, an external .MSI, and an external .INI file that contains the download information. This sets the Create an .EXE and .INI option on the WebDeploy page, and vice versa. Warning If you change the .EXE options after you edit the WiseScript on the Prerequisite Pages, you will lose all the changes you made to the script. z Password Enter a password. The user who installs the application is prompted to enter the password to start the installation. This password is the same for all users. You can protect only single-file .EXEs with a password. z Prompt to remove previous version before installing Mark this to have the installation check for previous versions of the same application and prompt the end user to uninstall the previous version before proceeding with the new installation. This option is disabled when the Install the .MSI into an SVS layer option is selected. For this to work, the previous version must have been installed using Windows Installer technology. If not, then use the System Search page to search for a previous version. Note For best results, use the Upgrades page rather than this option to deal with previous versions of your application. Do not mark this check box if you are using the Upgrades page or patches to update an application. z Include all languages in installation .EXE Mark this to embed all the languages that are marked on the Languages page in the output .EXE. See Outputting a Multiple-Language Release on page 184. z Always prompt for installation language Mark this to cause a multi-language installation to prompt the end user for the language at run time. Clear this to have the resulting installation verify if one of the languages in the installation is on the destination computer. If so, the installation proceeds in the destination computer’s language. If not, the end user is prompted to select a language. z Install the .MSI into an SVS layer Mark this to install the .MSI into an SVS layer if the SVS driver (Altiris Software Virtualization Agent) is installed on the destination computer. When you select this option, the other SVS options on the page are enabled. z Install normally if the SVS driver is not present Mark this option to install the .MSI normally if the SVS driver (Altiris Software Virtualization Agent) is not installed on the computer. If you clear this option and the SVS driver is not present, then the installation fails. Windows Installer Editor Reference 191 Organizing Your Installation Into Releases z Exclude all file extensions from the Extension table Mark this to exclude user data files from the SVS layer for all file extensions that appear in the Extension table. You add file extensions to the Extension table on the File Associations page. See Adding File Associations on page 153 and About the Exclusion of Files on the Build Options Page on page 193. z Exclude the following extensions Specify file extensions for user data files that you want to exclude from the SVS layer. Separate extensions with a comma. You can enter extensions with or without the preceding period. z Exclude all files in the following directories Use this option to exclude specific directories from an SVS layer. Any user data file that is saved in these directories is excluded from the SVS layer. When you specify a directory, you can also exclude its subdirectories. To exclude a directory, click Add and select the directory from the Directory drop-down list. The Directory dropdown list displays all built-in Windows Installer directories and any directories that you added on the Files page. To exclude subdirectories, mark Exclude all subdirectories under this directory. Directories that you exclude appear in the list pane on the Build Options page. See also: Adding Prerequisites to a Release on page 195 Creating a WebDeploy Installation on page 204 About the Installation of an .MSI into an SVS Layer You can create an .MSI installation that is installed into an SVS layer. You can then take advantage of the benefits of both an .MSI and an SVS layer. When you install an .MSI into an SVS layer, you eliminate the possibility of conflicts with other applications, including another version of the same application, and avoid changes to the base Windows installation. You also make it possible for an end user to quickly restore the application to its original state by resetting the layer from Add/Remove Programs. Before you create an installation that installs an .MSI into an SVS layer, you should be familiar with the following: z .EXE wrapper To create an installation that installs an .MSI into an SVS layer, you must first select an option to create an .EXE on the Build Options page. After you select an .EXE option, the Install the .MSI into an SVS layer option becomes enabled on this page. After you select the option to install the .MSI into an SVS layer and compile the .MSI, an .EXE file is created that has the same name as the .MSI file. This .EXE file contains the logic that is needed to install the .MSI into an SVS layer. See Setting Build Options for a Release on page 190 z WiseScript project file (.WSE) When you select the option on the Build Options page to install the .MSI into an SVS layer, a WiseScript project file (.WSE) is created, which when compiled creates the .EXE wrapper. You can edit this .WSE file from the Prerequisites page. See Editing the WiseScript That Creates the Installation .EXE on page 200. In addition to the logic needed to install the .MSI into an SVS layer, the WiseScript file contains installation error messages and the installation’s maintenance mode Windows Installer Editor Reference 192 Organizing Your Installation Into Releases dialogs. The maintenance mode dialog boxes appear when the end user clicks the application’s Change/Remove button in Add/Remove Programs. See About Maintenance of an .MSI Installed into an SVS Layer on page 194. Note Only English is supported for any dialogs that are controlled by this WiseScript file. z Exclusions When you install an .MSI into an SVS layer, you should also specify on the Build Options page the end user data files that should be excluded from the SVS layer. You exclude files so that end users data files are not lost when the application is reset from Add/Remove Programs. See About the Exclusion of Files on the Build Options Page on page 193. z Execution of .EXE wrapper When an end user runs the default WiseScript .EXE wrapper that is generated when the .MSI is compiled, the .EXE wrapper does the following on their computer: „ Determines whether the Virtual Software Package (VSP) is already installed. If a VSP with the same GUID is already installed, a message informs the end user and the installation ends. „ Installs any other prerequisites that are specified on the Prerequisites page. These prerequisites are not installed into an SVS layer. „ Determines whether a compatible version of the SVS Driver (Altiris Software Virtualization Agent) is installed. „ If a compatible version of the SVS Driver is not found one of the following happens: „  If you selected the option to install the .MSI normally on the Build Options page, the .EXE wrapper installs the .MSI normally and not into an SVS layer.  If you did not select the option to install the .MSI normally, the installation ends. Creates an SVS layer for the .MSI and installs the .MSI into the layer. The .MSI installation runs normally. This includes the installation dialog boxes that appear to the end user. The product code of the .MSI is used for the layer ID. „ Activates the virtual software layer. The virtualized application then looks and behaves like any other application to the end user. See also: About Virtual Software Packages in the Virtual Package Editor Help About the Exclusion of Files on the Build Options Page On the Build Options page, if you select Install the .MSI into an SVS layer, options to exclude file extensions or directories become enabled. Use these options to exclude end user data files from the SVS layer. You exclude files so that end users data files are not saved in the SVS layer but are saved to the base file system. End user data files that are Windows Installer Editor Reference 193 Organizing Your Installation Into Releases excluded from the layer are not lost when the application is reset from Add/Remove Programs. See About Maintenance of an .MSI Installed into an SVS Layer on page 194. Warning If an .MSI is installed into an SVS layer, any files that are generated by the application and saved locally are lost when the layer is reset unless those files were excluded on the Build Options page. The Build Options page contains options that let you use any of the following to exclude user data files from an SVS layer: z Files extensions that are listed on the Files Association page. These extensions appear in the Extension table on the Tables tab. z File extensions that you specify. z File directories that you select. You can select any of the pre-built Windows Installer directories or any directories that you added to your installation. When you select a directory, you can also select to exclude its subdirectories. Also see: Tables Tab on page 376 Adding File Associations on page 153 About Maintenance of an .MSI Installed into an SVS Layer When an .MSI is installed into an SVS layer, an end user can use Add/Remove Programs to perform maintenance on the application. Note Only English is supported for the maintenance mode dialogs. The end user can perform the following operations from Add/Remove Programs: z Remove This option deletes the SVS layer along with the application. z Repair This option runs Windows Installer repair. This reinstalls missing or corrupt files, registry keys, and shortcuts. Preferences stored in the registry may be reset to default values. z Advanced This option lets the end user access the following options: „ Modify This option displays the Select Feature dialog box and lets the end user change the application features that are installed. „ Reset This option resets the SVS layer and returns the application to its original state. Any customization that the end user made to the application is lost. Windows Installer Editor Reference 194 Organizing Your Installation Into Releases Warning If an .MSI is installed into an SVS layer, any files that are generated by the application and saved locally are lost when the layer is reset unless those files were excluded on the Build Options page. See About the Exclusion of Files on the Build Options Page on page 193. Adding Prerequisites to a Release On the Prerequisites page, you add runtime or prerequisite files to the installation for pre-installation on the destination computer. You can: z Select the Windows Installer and .NET Framework runtimes to add. Note SVS Driver runtime options appear if you open a Windows Installer package that was created with Wise Installation Studio that included these options. z Add prerequisite files to run before the main installation. Prerequisite files are usually .EXE or .MSI files, but there is no restriction on their type. z Add runtimes to run before the main installation. They are added as an include script to the WiseScript that creates the installation .EXE. Note The options on the Prerequisites page are unavailable if Do not create an .EXE file is selected from .EXE Options on the Build Options page. See Setting Build Options for a Release on page 190. To add prerequisites to a release 1. Select Installation Expert > Prerequisites page. 2. From Current Release, select a release. 3. Select the Windows Installer and .NET Framework runtime versions to pre-install. See Adding a Windows Installer or .NET Framework Runtime on page 195. 4. If necessary, add prerequisite files. See Adding a Prerequisite File on page 197. 5. If necessary, add runtime files. See Adding a Runtime Prerequisite on page 199. For each prerequisite file and runtime file that you add in the lower pane, script is added to the WiseScript that creates the installation’s .EXE. You can edit this script to enhance the functionality of the prerequisites. See Editing the WiseScript That Creates the Installation .EXE on page 200. Adding a Windows Installer or .NET Framework Runtime On the Prerequisites page, you can select the Windows Installer and .NET Framework runtimes to add to the installation for pre-installation on the destination computer. Windows Installer Editor Reference 195 Organizing Your Installation Into Releases If you specify a runtime that is not on your computer, the Download Redistributables wizard appears during compile. Use the Wise Web Site option to download that runtime, which should be pre-selected. See Downloading Redistributable Files on page 29. Note The options on the Prerequisites page are unavailable if Do not create an .EXE file is selected from .EXE Options on the Build Options page. See Setting Build Options for a Release on page 190. Which runtime files are installed? The version you select determines which runtime files are added to the installation. Version Runtime file name Windows Installer (9X) InstMsi.exe Windows Installer (NT) InstMsiW.exe Windows Installer (2000/XP/2003)—runtime earlier than 3.0 InstMsiW.exe Windows Installer (2000/XP/2003)—runtime 3.0 or later InstMsi3.exe .NET Framework dotnetfx.exe Note Prior to the release of Windows Installer 3.0, the .NET Framework included the version of the Windows Installer runtime that it required. However, Microsoft does not distribute Windows Installer 3.0 with the .NET Framework. If your application requires Windows Installer 3.0, configure the installation to pre-install it. To add a Windows Installer or .NET Framework runtime 1. Select Installation Expert > Prerequisites page. 2. From Current Release, select a release. 3. Select the Windows Installer runtime version to pre-install for Windows 2000/XP/ 2003. This adds a file to the installation that pre-installs Windows Installer if it is not on the destination computer. „ If you know that the operating system is not used on any destination computers, select None. „ Select Latest to add the latest runtime that you have downloaded and that works with that operating system. Example: If the latest runtime that you have downloaded is 2.0 and you select Latest (2000/XP/2003), then 2.0 is added to the installation. If later you download 3.0, then 3.0 would be added to the installation. 4. Select the .NET Framework runtime version to pre-install. If the .NET Framework includes a Windows Installer version that is later than the Windows Installer version you selected above, the later version is pre-installed. Windows Installer Editor Reference 196 Organizing Your Installation Into Releases 5. Select options for installing the Windows Installer and .NET Framework runtimes: „ Delay Windows Installer runtime reboot until after product installation Mark this to delay the restart to the end of the installation and minimize restarts for the end user. This is enabled only if one of the Windows Installer Runtime Version fields is set to 2.0 or later, or if a .NET Framework that includes Windows Installer 2.0 or later is selected. Normally, installing the Windows Installer runtime requires a restart at that point in the installation. „ 6. Show Microsoft .NET End-User License Agreement This is enabled if you selected an option to install the .NET Framework runtime. Mark this to display the end-user license agreement (EULA) to the end user during installation, or clear it to suppress the EULA. If necessary, add prerequisite files. See Adding a Prerequisite File on page 197. 7. If necessary, add runtime files. See Adding a Runtime Prerequisite on page 199. Adding a Prerequisite File On the Prerequisites page, you can add prerequisite files to run before the main installation. Prerequisite files are usually .EXE or .MSI files, but there is no restriction on their type. Note The options on the Prerequisites page are unavailable if Do not create an .EXE file is selected from .EXE Options on the Build Options page. See Setting Build Options for a Release on page 190. To add a prerequisite file 1. Select Installation Expert > Prerequisites page. 2. From Current Release, select a release. 3. To run the prerequisite files before checking the launch conditions of the .MSI installation, mark Don’t check the launch conditions of the .MSI installation until after running the prerequisites. By default, the .MSI launch conditions are checked after the installation of any runtimes that you select on the Prerequisites page and before any prerequisite files run. With this option you can delay checking the .MSI launch conditions until after the prerequisite files run. Use this option when the .MSI launch conditions will fail if the prerequisite files have not been run. 4. To add a prerequisite file, click Add at the right of the page and select Prerequisite. The Prerequisite Details dialog box appears. Windows Installer Editor Reference 197 Organizing Your Installation Into Releases Note If you compile an installation into an .EXE that launches an external .MSI, three files are generated: an .EXE, an .MSI, and an .INI. If you add prerequisite files to the installation, a subdirectory that is named after your installation file is also created. When you distribute the installation, you must include this subdirectory along with the three files that are generated or the installation will not run. 5. Complete the dialog box: „ File Path Specify the prerequisite file to be run before the main installation. „ Command Line Specify the command-line options to apply to the prerequisite file at run time. „ If the prerequisite’s launch conditions fail, stop the .MSI installation Mark this to stop the main installation if the prerequisite file fails to run because of its launch conditions. „ Add Launch Conditions Click this to add launch conditions to the prerequisite file. The Prerequisite Launch Conditions dialog box appears. You can add launch conditions for the destination computer’s operating system, display settings, and NT administrator rights. The prerequisite file runs only if all conditions are true. Conditions you add appear in the Condition section. If your prerequisite file is an .MSI, you cannot add launch conditions, but you can view its launch conditions on the Prerequisite Launch Conditions dialog box. 6.  To add a launch condition, select an option from both drop-down lists and click Add. Repeat to add additional launch conditions.  To delete a launch condition, select it in the Condition section and click Delete.  Click OK to save the launch conditions. Click OK on the Prerequisite Details dialog box. The prerequisite file is added to the Prerequisites page. To edit or delete it, use the right-click menu. 7. If necessary, add a Windows Installer, .NET Framework, or runtime. See: Adding a Windows Installer or .NET Framework Runtime on page 195 Adding a Runtime Prerequisite on page 199 8. If a prerequisite file or runtime requires a restart, you might need to edit the WiseScript to make the restart run smoothly. We recommend adding two Pause actions for 1000 milliseconds after a prerequisite or runtime that requires a restart. This works better than one Pause action for 2000 milliseconds. Adding the Pause actions prevents the WiseScript from trying to start the next prerequisite or runtime while the computer is shutting down. 9. During installation, any runtimes you selected at the top of the Prerequisites page run first, and then the prerequisite files and runtimes run in the order that they are listed. To rearrange the order, select an item in the lower pane and click Move Up or Move Down at the right of the page. Windows Installer Editor Reference 198 Organizing Your Installation Into Releases For each prerequisite file and runtime that you add in the lower pane, script is added to the WiseScript that creates the installation’s .EXE. You can edit this script to enhance the functionality of the prerequisites. See Editing the WiseScript That Creates the Installation .EXE on page 200. If the build options for this installation are set to create an .EXE that launches an external .MSI, then when this installation is compiled, the prerequisite .EXE is copied to a subdirectory of the installation’s project directory, named Msi_Name\FILEPATH1. Adding a Runtime Prerequisite If you need to distribute a runtime with an application, you can use the Prerequisites page to add the runtime to run before the main installation. A runtime is added as an include script to the WiseScript that creates the installation .EXE. Unlike prerequisite files, you do not set command-line options or launch conditions for a runtime because any options are built into the runtime. A runtime is always included in the installation .EXE, even if .EXE that launches external .MSI is selected on the Build Options page. Before you can add a runtime to an installation, you must add the runtime files to your computer. To download many of the runtimes, select Help menu > Download Redistributables and mark Other Vendors’ Web Sites. If a runtime is not available from Download Redistributables, you must download it directly from the vendor’s Web site. Note The options on the Prerequisites page are unavailable if Do not create an .EXE file is selected from .EXE Options on the Build Options page. See Setting Build Options for a Release on page 190. To add a runtime to an installation 1. Select Installation Expert > Prerequisites page. 2. From Current Release, select a release. 3. Click Add at the right of the page and select Runtime. The Runtime Details dialog box appears. 4. To add a runtime, mark its check box. For many runtimes, an additional dialog box appears where you specify settings for the runtime. 5. If a runtime-specific dialog box appears, complete it and click OK. 6. Click OK on the Runtime Details dialog box. The runtime is added to the Prerequisites page. To edit or delete it, use the rightclick menu. 7. If necessary, add a Windows Installer or .NET Framework runtime, or a prerequisite file. See: Adding a Windows Installer or .NET Framework Runtime on page 195 Adding a Prerequisite File on page 197 Windows Installer Editor Reference 199 Organizing Your Installation Into Releases 8. If a prerequisite file or runtime requires a restart, you might need to edit the WiseScript to make the restart run smoothly. We recommend adding two Pause actions for 1000 milliseconds after a prerequisite or runtime that requires a restart. This works better than one Pause action for 2000 milliseconds. Adding the Pause actions prevents the WiseScript from trying to start the next prerequisite or runtime while the computer is shutting down. 9. During installation, any runtimes you selected at the top of the Prerequisites page run first, and then the prerequisite files and runtimes run in the order that they are listed. To rearrange the order, select an item in the lower pane and click Move Up or Move Down at the right of the page. For each prerequisite file and runtime that you add in the lower pane, script is added to the WiseScript that creates the installation’s .EXE. You can edit this script to enhance the functionality of the prerequisites. See Editing the WiseScript That Creates the Installation .EXE on page 200. Editing the WiseScript That Creates the Installation .EXE If you select an option on the Build Options page to create an .EXE, a WiseScript project file (.WSE) is generated, which is used to compile the .EXE. After you add prerequisite files or runtimes to an installation on the Prerequisites page, you can edit this WiseScript to enhance the functionality of the prerequisites. You can also edit this WiseScript if you select Install the .MSI into an SVS layer on the Build Options page. In this case, you might edit this WiseScript to change the .MSI command line by changing the MSICMDLINE variable or to set the value of properties. Warning Make sure the .EXE options on the Build Options page are set correctly before you edit the WiseScript. If you change the .EXE options after you edit the WiseScript, you will lose all the changes you made to the script. To edit the WiseScript 1. Select Installation Expert > Prerequisites page. 2. Add prerequisites as needed. See Adding Prerequisites to a Release on page 195. After you edit the WiseScript, you cannot add or edit prerequisite files and runtimes on the Prerequisites page. You also cannot edit any of the Install the .MSI into an SVS layer options on the Build Options page. To enable these options, click Reset Script at the right of the page. 3. Click Edit Script at the right of the page. The Edit Script button is available only after you do one of the following: „ Add prerequisite files or runtimes on the Prerequisites page. „ Select Install the .MSI into an SVS layer on the Build Options page. See Setting Build Options for a Release on page 190. If you have not previously edited the script, a warning message appears. Click Yes. The installation is saved and compiled and the WiseScript that creates the installation’s .EXE opens in WiseScript Editor. Windows Installer Editor Reference 200 Organizing Your Installation Into Releases The name of the WiseScript file for the default release is the installation name with the extension .WSE. The WiseScript files for additional releases are named for the release. Warning Don’t change the name of the WiseScript file. It must have this name to create an .EXE that includes your edits. 4. Edit the WiseScript as needed and save it. The next time you compile the installation, an .EXE is generated using the WiseScript file that you edited. 5. Thoroughly test the WiseScript to make sure it executes as expected. To reset the WiseScript 1. Click Reset Script at the right of the page. This button is enabled only if you have used the Edit Script button. A warning message appears. 2. Click Yes. The changes you made to the WiseScript are deleted, and the ability to add and edit prerequisite files on the Prerequisites page is enabled. See also: About Script Editor in the WiseScript Editor Help Creating Web-Based Installations With WebDeploy ¾ Windows Installer version. For best results with WebDeploy, the destination computer should have Windows Installer 2.0 or later. Note This page is enabled in a .WSI only. WebDeploy™ lets you create Web-based installations that minimize bandwidth requirements by downloading only the files needed for the installation. Examples: z If you set the installation to pre-install the Windows Installer runtime, and the destination computer already has that runtime installed, then the runtime file is not downloaded. z If the installation contains multiple features, only the features that the end user selects during installation are downloaded and installed. Without WebDeploy, you could create a single-file .EXE, upload it to an FTP server, and let your end users download it by clicking on its link. The disadvantage of this is that a single-file .EXE can be very large. The entire installation, including Windows Installer runtimes, is downloaded whether or not it is needed on the destination computer. The resulting download can take a long time and tie up bandwidth. Windows Installer Editor Reference 201 Organizing Your Installation Into Releases Note You cannot use WebDeploy to run patches (.MSP) or transforms (.MST). To distribute updates with WebDeploy, format the installation as an upgrade using the Upgrades page. For information on using WebDeploy with WiseUpdate, see WiseUpdate Tips on page 296. You can use WebDeploy in several ways, depending on how you set the WebDeploy options: Create an .EXE that contains the .MSI Windows Installer and .NET runtimes, and prerequisite files, if any, are external to the .EXE. When an end user runs the .EXE from the Web, it runs the .MSI from the Web. The runtime and prerequisite files are downloaded only if they are needed on the destination computer. See The WebDeploy Process on page 203. Prerequisite and runtime files that you add on the Prerequisites page are always included in the .EXE. This is the best method to use when distributing installations over the Internet because, if a self-repair is needed, the .MSI is cached locally and no further downloads are ever required. Create an .EXE that runs an external .MSI Windows Installer and .NET runtimes, and prerequisite files, if any, are external to the .EXE. The resulting .EXE is very small. When an end user runs the .EXE, it connects to the Web location of the .MSI and runs the .MSI. The runtime and prerequisite files are downloaded only if they are needed on the destination computer. Prerequisite and runtime files that you add on the Prerequisites page are always included in the .EXE. This method is best used over a corporate intranet. Because the .MSI is run directly from the Web, if a self-repair or install-on-demand is needed, the end user must have immediate access to the original Web location of the .MSI. Create an .EXE that runs an external .MSI, and an external .INI that contains download and installation information Use this method to change the download information dynamically, perhaps as a result of end user input. You compile to an .EXE and .INI and then distribute the .EXE on a CD or other media along with an Autoplay program. Example: You want to let the end user select from multiple download sites. You write an Autoplay program that presents download site options to the end user. When the end user selects a site, the Autoplay program copies the .EXE and .INI to a temporary directory, then edits the .INI file, adding the URL of the selected download site. The Autoplay program then runs the .EXE, which connects to the appropriate Web site based on the updated information in the .INI file, and runs the .MSI file it finds there. See also: Windows Installer Editor Reference 202 Organizing Your Installation Into Releases Tips for Creating an Efficient WebDeploy Installation on page 204 Creating a WebDeploy Installation on page 204 Uploading a WebDeploy Installation to the Web on page 206 The WebDeploy Process The following diagram shows how the WebDeploy™ process works when you distribute an .EXE with an embedded .MSI over the Internet. Phase 1: Your Computer Your Web Server Upload files through FTP When you develop the installation, you: Compile the installation to an .EXE that contains the .MSI Configure WebDeploy by specifying the location of installation files on the Web server Upload the installation files to the Web server Notify end users of the Web link to the .EXE z z z z Phase 2: Destination Computer (HTTP Protocol) Your Web Server: z Contains the .EXE and other pieces of the installation ready for download The end user: z Runs the installation .EXE from your Web server Phase 3: Destination Computer (HTTP Protocol) Your Web Server: z Contains the .EXE and other pieces of the installation ready for download When the end user runs the .EXE, it: Runs the .MSI Runs an installation wizard Determines which pieces of the application are needed Installs the appropriate pieces of the application z z z z See also: Creating Web-Based Installations With WebDeploy Windows Installer Editor Reference 203 Organizing Your Installation Into Releases Tips for Creating an Efficient WebDeploy Installation ¾ Windows Installer version. For best results with WebDeploy, the destination computer should have Windows Installer 2.0 or later. z For more efficient downloading, organize the installation into components. Only the components that are needed for the installation are downloaded. See Working With Components and Features on page 492. z Make the installation download more efficiently. On the Installation Expert > Media page, display the Media Details dialog box and select One Cab per component in the Cab Options field. See Adding a Media Item on page 208. z It is a good idea to digitally sign installations that you plan to deploy over the Web. To add an authenticode digital signature to your installation files, use the Digital Signature page. This requires Windows Installer 2.0 or later. See Adding a Digital Signature to an Installation on page 237. See also: Creating Web-Based Installations With WebDeploy Creating a WebDeploy Installation ¾ Windows Installer version. For best results with WebDeploy, the destination computer should have Windows Installer 2.0 or later. Note This page is enabled in a .WSI only. The WebDeploy™ page lets you enable an installation for distribution through the Web. You do this by setting options for compiling the installation and for connecting to the Web server that will contain the installation files. For suggestions on how to set WebDeploy options to meet your requirements, see Creating Web-Based Installations With WebDeploy on page 201. Also see Tips for Creating an Efficient WebDeploy Installation on page 204. Note To avoid web connection errors when you use WebDeploy with IIS 6.0 or later, you must add a MIME type for “*” (asterisk) to allow the WebDeploy download files (such as .000, .001, .002). To create a WebDeploy installation 1. Select Installation Expert > WebDeploy page. 2. From Current Release, select a release. 3. Mark Create a Web-based installation. This enables the remaining options on the page. Windows Installer Editor Reference 204 Organizing Your Installation Into Releases 4. From .EXE Options, specify how the installation is created. This is linked to the .EXE Options field on the Build Options page. „ Create a downloadable .EXE Create an .EXE that is optimized for direct downloading from the Internet. The installation will compile to an .EXE that contains the download information, and an .MSI file that might or might not be embedded in the .EXE. This sets the WebDeploy .EXE option on the Build Options page, and vice versa. „ Create an .EXE and .INI Change the download information dynamically, perhaps as a result of end user input. The installation will compile to an .EXE, an external .MSI, and an external .INI file that contains the download information. This sets the WebDeploy .EXE and .INI option on the Build Options page, and vice versa.) See INI File Properties on page 512. 5. In the following fields, specify the URL to which you will upload various installation files. This information is included in the installation and determines where the installation looks for files to download. You must specify the full URL address, path, and file name. Include a user name and password if your Web server requires them. Use the format: http://user_name:[email protected]/file_name.msi Click the Edit button next to each field to display a URL Settings dialog box, which lets you enter the elements of the file location separately and then builds the full path from your entries. Note If you select the Create .EXE and .INI option, the password is stored in the .INI file. If you are concerned about the password being visible, select the Create a downloadable .EXE option instead, which stores the password in the .EXE. „ .MSI Download URL Enter the Web server address that points to the .MSI. This must match the name of the .MSI you upload later. To embed the .MSI in the .EXE, leave this field blank. „ 2000/XP Download URL To make the Windows Installer runtime installation for Windows 2000/XP available for pre-installation, enter the address of the runtime installation file. The runtime installation file is typically named: Windows 2000/XP: InstMsi3.exe Leave these fields blank to embed the Windows Installer runtime .EXE in the WebDeploy .EXE if the Prerequisites page is set to pre-install the Windows Installer runtime. „ .NET Runtime URL / .NET Update URL Getting the latest version of the .NET Framework runtime requires installing two files, the original installation and a patch installation. In .NET Runtime URL, enter the address that points to the .NET Framework runtime file (dotnetfx.exe). In .NET Update URL, enter the address that points to the .NET Framework upgrade file. Leave these fields blank to embed the .NET .EXE in the WebDeploy .EXE if the Prerequisites page is set to pre-install the .NET Framework runtime. Windows Installer Editor Reference 205 Organizing Your Installation Into Releases Note Be sure that the location you upload to does not violate the license agreement for the distribution of Microsoft runtime files. See also: Creating Web-Based Installations With WebDeploy on page 201 Uploading a WebDeploy Installation to the Web on page 206 Uploading a WebDeploy Installation to the Web ¾ Windows Installer version. For best results with WebDeploy, the destination computer should have Windows Installer 2.0 or later. Note This page is enabled in a .WSI only. To upload the files in a WebDeploy installation, you can use any FTP client. To upload a WebDeploy installation 1. Verify that directories exist on the Web server at the URL addresses you specified in the Download URL fields on the WebDeploy page. 2. Using an FTP client, upload the installation files: „ If you are distributing a single-feature .MSI over the Internet, the installation should be compiled to an .EXE that contains the .MSI. Create a Web page containing a link to the .EXE file, then upload the .EXE to the location of that Web page. Example: Upload Sample1.exe to http://www.Sample1.com/installs „ If you are distributing a multi-feature, install-on-demand application over a corporate intranet, the installation should be compiled to an .EXE that runs an external .MSI. Create a Web page containing a link to the .EXE file, then upload the .EXE to the location of that Web page. Then upload the .MSI and any external .CAB files to the URL address you specified in the .MSI Download URL field on the WebDeploy page. Example: UploadSample2.exe to http://www.Sample2.com/installations UploadSample2.msi to http://www.Sample2.com/downloads „ If you are distributing the installation through an Autoplay program, the installation should be compiled to an .EXE that runs an external .INI and .MSI. Save the Autoplay program and the .EXE and .INI files to a CD or other distribution media. Then upload the .MSI and any external .CAB files to the URL address you specified in the .MSI Download URL field on the WebDeploy page. Example: Upload Sample3.msi to http://www.Sample3.com/downloads Windows Installer Editor Reference 206 Organizing Your Installation Into Releases 3. If the installation will pre-install any Windows Installer or .NET runtimes, use an FTP client to upload the following files: „ If you specified a 2000/XP Download URL on the WebDeploy page, upload the file InstMsi3.exe to that Web address. „ If you specified a .NET Runtime URL on the WebDeploy page, upload the .NET Framework file dotnetfx.exe to that Web address. Likewise, if you specified a .NET Update URL, upload the .NET Framework update file to that Web address. If you do not have a copy of the appropriate runtime file, use the Download Redistributables wizard. See Downloading Redistributable Files on page 29. Note Be sure that the location you upload to does not violate the license agreement for the distribution of Microsoft runtime files. 4. Distribute the installation media or notify your end users of the Web link to the .EXE. See also: Creating Web-Based Installations With WebDeploy on page 201 Creating a WebDeploy Installation on page 204 Setting Up Media for Distribution Note This page is fully enabled in a .WSI only. In an .MSI or .MST, you cannot add or delete. The Media page lets you prepare an installation for distribution. Here, you specify compression, the media’s size, holding directories, and how features and components are organized on the media. You set media options per release. If the installation spans more than one media, you can determine which files are placed on which disk, or you can have it done for you. To prepare an installation for distribution, perform these tasks: z Add media items to apply different compression options to different files in components or features. See Adding a Media Item on page 208. During compile, the media items are placed in the destination directories in the order in which they’re listed on the Media page. To rearrange the order, select a media item and click Move Up or Move Down at the right of the Media page, or drag the media item to a new position. The .MSI file is an exception. It is always placed in the first destination directory, no matter where it appears in the list. z Add destination directories. Destination directories are holding places for the installation. They represent the disks, CDs, or server you use for distributing your application. See Adding a Media Destination on page 210. z Compile the installation. Windows Installer Editor Reference 207 Organizing Your Installation Into Releases z Copy the contents from the destination directories onto the media you will use for distribution. Note At least one media item is required. If the Media page contains only one item, you cannot delete it. Adding a Media Item Note This page is fully enabled in a .WSI only. In an .MSI or .MST, you cannot add or delete. You can add media items to apply different compression options to different files in components or features. Example: Leave a Readme file and a tutorial uncompressed, compress application files inside the .MSI file, and compress graphic files into external .CAB files. In this case, you would add these media items: z Uncompressed Readme z Uncompressed Tutorial z Compressed application files z Compressed graphic files To add a media item 1. Select Installation Expert > Media page. 2. From Current Release, select a release. 3. Click Add at the right of the Media page. The Media Details dialog box appears. 4. In Media Name, describe the media item you’re setting up. Examples: Compressed Application Files or Uncompressed Tutorial. This name appears on the Media page. The media name must be unique within a release. 5. In Compression Option, specify how to compress the installation files. This is unavailable if Single-file .EXE is selected on the Build Options page. „ Compress files inside .MSI Wrap all files inside the .MSI, including .CAB files if you select a .CAB option below. „ Compress files into external Cab files Compress all files into one or more .CAB files outside the .MSI file. CAB files are like .ZIP files; they contain one or more compressed files. When you select one of the above compression options, you must select one of the Cab Options below. „ Uncompressed external files Leave all files uncompressed and outside the .MSI file. If you configured part of the application to run from the source media, you must use this option. See the description of the Will be installed to run from source icon in Configuring a Feature Using Its Drop-Down List on page 95. Windows Installer Editor Reference 208 Organizing Your Installation Into Releases If you select this option, you also might want to use short file names for uncompressed files outside the installation. See the description of Use short file names for files uncompressed outside of the install in Creating a New Release on page 182. 6. In Cab Options, determine the makeup of your .CAB files. To minimize file size, use fewer .CAB files; to minimize installation time, use more .CAB files. This is unavailable if you select Uncompressed external files from Compression Option above, or if you are working in an .MSI. „ Quickest (new files and modules get cab file) Any new files that you add to the installation, including merge modules, get their own .CAB files. This is selected by default in an .MSI. „ One Cab (including modules) Create one large .CAB file for all files and merge modules in the installation. This option saves some file space by eliminating overlap in .CAB files, but installation is slower than installing from multiple .CAB files. „ One Cab per feature Every feature in the installation gets its own .CAB file. This option is most efficient on a CD or similar media, where file size is not an issue. „ One Cab per component Every component in the installation gets its own .CAB file. This option is best for WebDeploy installations, where only required components are downloaded. The remaining options on the Media page are enabled in a .WSI only. 7. In the Custom Media Settings area, specify settings that are related to the size of your media. Share media destination/size info with previous media entry Gives a media item the same size and destination settings as its predecessor’s, therefore, mark this for the second and subsequent media items only. Example: This makes it easier to create a CD where some files are compressed and others are not. You can create one or more media items with different compression options but have them all placed on the same CD. „ You can also use this option to have one distribution medium (example: a CD) filled up before starting to place media items on a second or third distribution medium. See Example: Spanning an Installation Across Media and Sharing Media Size Information on page 213. „ Max Media Size Enter the size of the distribution media as a whole number and select the appropriate unit (KB or MB) from the drop-down list. To indicate unlimited size, enter 0. „ Cluster Size Select the bytes per sector of the distribution media. Recommendations for common distribution media: Media Max Media Size Cluster Size CD-ROM 550 MB 2048 Bytes Windows Installer Editor Reference 209 Organizing Your Installation Into Releases 8. Media Max Media Size Cluster Size ZIP disk 100 MB or 250 MB 2048 Bytes Floppy disk 1440 KB 512 Bytes In the Media Destinations section, enter the directory where the installation is stored before you copy it to the distribution media. Enter one destination for each distribution medium. See Adding a Media Destination on page 210. 9. In the Include Features/Components section, select the features and components to include in this media item. See Including Features and Components in Media Items on page 211. 10. Click OK. The media item appears on the Media page, in the Media Name column. To edit it, double-click its name. Adding a Media Destination Note These settings are enabled in a .WSI only. A media destination is a holding directory for the installation. It has the same capacity as indicated in the Max Media Size field in the Media Details dialog box. During compile, all files for your installation are placed in one or more destination directories, and you copy them from there to your distribution media. Enter one destination for each distribution media. If you don’t create media destinations, that is, destination directories, the files are copied to the directory where the .WSI file is located. Example: If your installation is so large that it needs two CDs, enter two destination directories. Files are copied to the first destination directory in the list, until the directory is filled to the maximum media size. Then, the application starts copying files to the second destination directory. Note The .MSI file is always placed in the first directory in the list. To specify a destination directory 1. Select Installation Expert > Media page. 2. From Current Release, select a release. 3. Double-click a media item. The Media Details dialog box appears. 4. In the Media Destinations section, click Add. The Media Destination Details dialog box appears. 5. Complete the dialog box: „ Windows Installer Editor Reference Destination Directory Specify the holding directory in which the installation files are stored before they’re placed on the selected media. 210 Organizing Your Installation Into Releases If you specify a maximum media size on the Media Details dialog box and do not specify destination directories, installation files are placed in folders with generic names (Disk1, Disk2, and so on) in the directory that contains the project file. „ Volume Label This entry appears in the Label field when you right-click the icon for a volume in Windows Explorer and select Properties. It is very important to change volume labels for your disks or CDs to match this value. Failing to do so will prevent the installation from working properly. „ 6. Disk Name Enter the disk name that should appear when the installation prompts the end user to insert another disk or CD. Example: Disk2. This only pertains to installations that require multiple distribution media. Click OK. During compile, the installation is broken up into the directories you specify. Then, you must copy the contents of each directory to a disk or CD that has the same name that’s in the Volume Label field. Including Features and Components in Media Items Note These settings are enabled in a .WSI only. You can specify the features and components to include in each media item. By default, All Features/Components are selected to be included. Use this setting in any of the following instances: z The installation has only one media item. z You want to include every remaining feature and component that is not included in a previous media item. z It doesn’t matter which files are on which medium. In any other case, use the Include Items for Media dialog box to select the features and components to include in the current media item. During compile, an error message notifies you if you have failed to include a feature that has files added to it. Examples: z Suppose you want to have an uncompressed Readme file on your distribution media. In this case, you could create a media item called Uncompressed Readme. Then, from the list of components to include, you would select the Readme file’s component for inclusion in this media item. z Suppose the installation includes a graphic feature with sample images, and you want to compress these images into an external .CAB file. In this case, you could create a media item called Compressed graphic files. Then, from the list of features, you would select the graphic feature for inclusion in this media item. To include features and components in a media item 1. Select Installation Expert > Media page. 2. From Current Release, select a release. Windows Installer Editor Reference 211 Organizing Your Installation Into Releases 3. Double-click a media item. The Media Details dialog box appears. 4. In the Include Features/Components section, click Add. The Include Items for Media dialog box appears. 5. From the drop-down list, specify whether to include components or features. 6. In the list box, select one or more features or components and click OK. The features or components you selected appear in the Include Features/ Components section on the Media Details dialog box. To exclude a feature or component, select it and click Delete. If you delete all selected features and components, the default setting of All Features/Components returns. Sharing Media Settings Between Releases Note This page is fully enabled in a .WSI only. In an .MSI or .MST, you cannot add or delete. You can share media settings from a release with other releases in the installation. After you initially share settings, the settings for the releases are linked. This means that any change you make to the media settings for any of the linked releases is applied to all other linked releases. At any time, you can break the link. To share media settings between releases 1. Select Installation Expert > Media page. 2. From Current Release, select a release to copy settings to. 3. Click Share at the right of the Media page. The Share Release dialog box appears. 4. From Copy/Share Media Settings From, select the release that contains the settings to copy. 5. Click OK. The settings of the release in Copy/Share Media Settings From immediately replace the settings of the release in Current Release. Any change you make to the media of either of the linked releases is applied to the other release, until you break the link. To break a link between releases 1. Select Installation Expert > Media page. 2. From Current Release, select a release. 3. Click Share at the right of the Media page. The Share Release dialog box appears. 4. From Copy/Share Media Settings From, select . 5. Click OK. The link between the selected release and other releases is broken. The current settings of the releases are not changed, but changing settings for one release no longer affects the settings of other release. Windows Installer Editor Reference 212 Organizing Your Installation Into Releases Example: Spanning an Installation Across Media and Sharing Media Size Information You can span an installation across CDs and use the Share media destinations/size info with previous media entry option. Assume the following: z The files for your application use 1.5 GB of uncompressed disk space. z You want to distribute the application on two CDs. z For each of the two CDs, you can safely assume a maximum size of 550 MB, which means that you need to compress some, but not all of your files. z Your application includes some features that are always installed on the destination computer. These are the files you compress. z The application also includes some features that the end user can either install or run from the CD-ROM. These are the files you don’t compress. This scenario means that you need to create two media items: z One media item for those features and components that are always installed, compressed into one big .CAB file. z A second media item for those files that can be run from the CD and that you therefore don’t compress. To create media items with shared size information The following steps are for the first media item. 1. Select Installation Expert > Media page. 2. Click Add at the right of the Media page. The Media Details dialog box appears. 3. Complete the dialog box. „ Media Name Enter a name for the first media item. Example: Compressed Files. „ Compression Option Select Compress files into external Cab files. „ Cab Options Select One Cab (including modules). „ Max Media Size Enter 550 MB. „ Cluster Size Select 2048 Bytes. 4. In the Media Destinations section, click Add. The Media Destination Details dialog box appears. 5. Make the following entries for the first CD: „ Destination Directory C:\My Installation\CD 1 This assumes that you have a directory named My Installation on your C drive. „ Windows Installer Editor Reference Volume Label CD One 213 Organizing Your Installation Into Releases It is very important to change volume labels for your disks or CDs to match this value. Failing to do so will prevent the installation from working properly. „ Disk Name CD 1 6. Click OK. 7. In the Media Destinations section, click Add again. The Media Destination Details dialog box appears. 8. Make the following entries for the second CD: 9. „ Destination Directory C:\My Installation\CD 2 „ Volume Label CD Two „ Disk Name CD 2 Click OK. 10. In the Include Features/Components list, click Add and select the features and components to compress. 11. Click OK. The next steps are for the second media item. 12. On the Media page, click Add. The Media Details dialog box appears. 13. Complete the dialog box. „ Media Name Enter a name for the second media item. Example: Uncompressed Files. „ Compression Option Select Uncompressed external files. „ Share media destination/size info with previous media entry. Mark this check box. „ Include Features/Components section Click Add and select the features and components to leave uncompressed. 14. Click OK. After compile, the destination directory CD 1 contains the .CAB file and as many uncompressed files as can fit on the CD. All remaining uncompressed files are in the directory CD 2. Windows Installer Editor Reference 214 Chapter 8 Advanced Installations This chapter includes the following topics: z About the Mobile Devices Page on page 215 z Setting Administrator Options on page 222 z Specifying Search Locations on page 224 z Setting Options for an Administrative Installation on page 225 z About Command Lines on page 226 z Adding a Digital Signature to an Installation on page 237 z Creating an Installation for Microsoft SMS on page 238 z Creating a .NET Installation When You Have the .NET Framework on page 239 z Creating a .NET Installation Without the .NET Framework on page 240 z About Web Installations on page 242 z Configuring a Microsoft SQL Server During Installation on page 254 z Importing .NET Framework Security Settings on page 258 z MTS/COM+ Page on page 260 About the Mobile Devices Page Note To see the Mobile Devices page, select one of these views from the Page Views dropdown list in Installation Expert: All, Palm Application, or Windows Mobile Application. Use the Mobile Devices page to configure a Windows Installer installation to install files that support a mobile device application. This lets you install the main application to a desktop computer and simultaneously install support for any mobile device that the user has. The ability to install to multiple platforms at once, including Windows, simplifies the installation process for you and the end user. The Mobile Devices page supports the following platforms: z Microsoft® Windows Mobile™ platform for Pocket PC and Smartphone z Palm OS If the installation supports the Pocket PC 2002 platform, you also can install the .NET Compact Framework, a version of .NET designed for mobile devices. If you don’t have the .NET Compact Framework runtime, and you include it in the installation, the Download Redistributables wizard appears during compile and prompts you to download it. Windows Installer Editor Reference 215 Advanced Installations About the Mobile Device Package Editor tool Mobile Device Package Editor is a separate installation development tool that lets you create an .INF file and compile it to one or more .CAB files that install a mobile device application. It supports the Microsoft® Windows Mobile™ platform for Pocket PC and Smartphone devices. See About Mobile Device Package Editor in the Mobile Devices Package Editor Help. See also: Process for Adding Mobile Device Support to an Installation on page 216 About Windows Mobile Installations on page 216 About Palm OS Installations on page 219 Process for Adding Mobile Device Support to an Installation You can configure a Windows Installer installation to install files that support a mobile device application. 1. Obtain the mobile device installation file or files. „ For Windows Mobile applications, the installation consists of one or more .CAB files. Obtain the .CAB files from a vendor or other source, or use the Mobile Device Package Editor to create them. „ For Palm OS applications, the installation consists of one or more files in any of these formats: .PDB, .PRC, or .PQA. 2. In Windows Installer Editor, go to Installation Expert > Mobile Devices page and add the mobile device installation files. 3. Finish assembling the Windows Installer installation. Any resources that you add to the installation, other than those on the Mobile Devices page, are installed on the desktop computer, not the mobile device. 4. If you added one or more Palm OS files, and you selected the option to install to the Palm user folder, then verify that the installation contains the Installation Type and Palm User Information dialog boxes. 5. Compile the installation. The mobile device installation files are included in the compiled .MSI or .EXE. If you added Windows Mobile .CAB files, an .INI file that describes the .CABs is created and included in the compiled .MSI or .EXE. See also: About the Mobile Devices Page on page 215 About Mobile Device Package Editor in the Mobile Devices Package Editor Help About Windows Mobile Installations The Microsoft® Windows Mobile™ platform supports Pocket PC and Smartphone devices. A Windows Mobile device installation consists of a single, self-extracting .CAB file and an optional Setup.dll file. The .CAB file contains all the resources (files, registry keys, and shortcuts) that comprise the application. The Setup.dll file provides functions for performing certain operations during the installation and removal of your application. Windows Installer Editor Reference 216 Advanced Installations Mobile device .CAB files are generated by the CabWiz program from an information file (.INF). The .INF is a text file that specifies directories, files, settings, and configurations that are used to install a mobile device application. (Pocket PC applications only.) A single .INF file can contain information to produce multiple .CAB files. Example: An application supports the Windows Mobile and Pocket PC 2002 platforms, but several of the application files are platform-dependent. When you create the installation, you assign the files to the device that supports that platform. When you compile, the Windows Mobile-specific files are placed in the Windows Mobile .CAB file, and the Pocket PC 2002-specific files are placed in the Pocket PC 2002 .CAB file. A mobile device application can be installed in the following ways: z The .CAB file and an .INI file that describes the .CAB are included in an installation that runs on the desktop computer. The desktop computer contains Application Manager (CeAppMgr.exe), which is installed with ActiveSync. Application Manager installs the mobile device application on the device. z The end user copies the .CAB file to the mobile device and opens it. The .CAB file extracts its contents to the directories that were specified in the .INF file. Uninstall of the mobile device application is controlled by the mobile device and ActiveSync. Uninstalling the mobile device installation from the desktop computer does not affect the application that is installed on the mobile device. To add Windows Mobile .CAB files to a desktop installation, use Installation Expert > Mobile Devices page. See Adding Windows Mobile Files. See also: About the Mobile Devices Page on page 215 Process for Adding Mobile Device Support to an Installation on page 216 Adding Windows Mobile Files To add Windows Mobile .CAB files to a desktop installation, use the Windows Mobile wizard. To access the wizard: Do one of the following: z Select Installation Expert > Mobile Devices. Do this to add the mobile device installation to an existing installation. a. From Current Feature, select a feature or condition. (Because any item you add must be assigned to a specific feature, you cannot add an item when All Features is selected.) Items that you add to a feature are installed on the destination computer only if the feature is installed. b. Click Add at the right of the page and select Windows Mobile. If the Mobile Devices page is not visible, select All or Windows Mobile Application from the Page Views drop-down list in Installation Expert. Windows Installer Editor Reference 217 Advanced Installations z On the New Installation File dialog box, select the Windows Mobile template from the Predefined Templates category. Do this to add the mobile device installation to a new installation. The Application Information dialog box appears. To step through the wizard 1. Complete the Application Information dialog box and click Next: „ Application Name Enter the name of the application you are installing. This appears in the list of applications on the Mobile Devices page. It also appears in the desktop computer’s mobile device software (the Add/Remove Programs dialog box, which is accessible from the Microsoft ActiveSync window). „ Description This appears in the desktop computer’s mobile device software. The CAB Files dialog box appears. 2. Complete the dialog box and click Next: a. Click Add, select one or more files, and click Open. b. Mark the following options if applicable:  Include the .NET Compact Framework (Pocket PC 2002 or later only). Mark this to include the .NET Compact Framework runtime in the installation. This causes Application Manager to install the .NET Compact Framework on the device before it installs the mobile device application. If the .NET Compact Framework runtime is not in the Stub subdirectory of the Windows Installer Editor installation directory, the Download Redistributables wizard appears during compile and prompts you to download it.  c. .NET Compact Framework Runtime Version Select a version of the .NET Compact Framework. Click Next. The Desktop Computer dialog box appears. 3. Complete the dialog box: „ Desktop Directory Specify the directory on the desktop computer in which to store the .CAB and .INI files that are necessary for installation to the mobile device. Typically, this would be in the Program Files directory. These files are run from the Add/ Remove Programs option in ActiveSync. „ Install on the mobile device following the desktop installation If you mark this and the mobile device is connected during the desktop installation, then the end user is prompted to perform the mobile device installation immediately following the desktop installation. If installation onto the mobile device will not take place immediately following the desktop installation, then use the following fields to create a shortcut on the desktop computer. This shortcut starts installation onto the mobile device by calling the Application Manager. Windows Installer Editor Reference 218 Advanced Installations 4. „ Shortcut Name Enter a name for the shortcut on the mobile device. „ Shortcut Directory Select a directory on the desktop computer in which to place the shortcut. Typically, this is the Windows Start menu. „ Icon File To use a custom icon, enter the path to the .ICO, .EXE, or .DLL file that contains the icon. „ Icon Index Enter the resource number of the icon (in the .ICO, .EXE, or .DLL file specified above) to use from the icon file above. This icon appears in the Shortcut Directory you selected above. Click Finish. To edit the mobile device entry, select it and click Details. After you create a mobile device entry, you might notice changes throughout Installation Expert, such as files added on the Files page, a shortcut on the Shortcuts page, and new custom actions added to MSI Script. Do not change or delete these items because doing so will cause the mobile device installation to fail. See also: About the Mobile Devices Page on page 215 About Windows Mobile Installations on page 216 Process for Adding Mobile Device Support to an Installation on page 216 About Palm OS Installations A Palm OS® application consists of a file in one of the following formats: z .PDB (Palm database), which stores data for an application. z .PQA (Palm query application), which is a .PDB that contains world-wide web content. z .PRC (Palm resource), which contains resources. To install a Palm OS application, the end user installs or downloads its file to the desktop computer, runs the Palm Desktop software to specify the new application, and performs a HotSync operation to install the application on the mobile device. To add Palm OS files to a desktop installation, use Installation Expert > Mobile Devices page. You can specify where the Palm OS files are installed. See Adding Palm OS Files on page 220. Installing to the Add-on folder When the end user runs the Palm Desktop software to specify a new application to install, the contents of the Palm\Add-on folder are displayed first. This lets the end user install the Palm application manually, and gives all Palm users of the desktop computer access to the application. Windows Installer Editor Reference 219 Advanced Installations Installing to the Palm User folder Palm applications that are in the Palm user folder (Palm\User) are installed on that end user’s device whenever a HotSync operation is performed. The end user does not have to specify the application in the Palm Desktop. When multiple Palm users use the desktop computer, the end user who runs the Windows Installer installation can specify which Palm users should be able to access the new Palm application. To install to the Palm user folder: 1. 2. When you create the Windows installer installation: a. Mark the Install File to Palm User Folder During Installation check box on the Palm File Details dialog box. b. Add the Installation Type and Palm User Information dialog boxes to the installation. During installation, the end user: a. Selects Custom on the Install Type dialog box. This causes the Palm User Information dialog box to appear. b. Selects users on the Palm User Information dialog box, which lists all Palm users on the desktop computer. The Palm files are installed in the directories for the specified users. If the steps above are not followed, the files are installed for all Palm users. Installations that were created in a product earlier than Wise for Windows Installer 5.0 or Windows Installer Editor 4.5 might not contain the Palm User Information dialog box. You can add this dialog box. See Creating a New Dialog on page 406. Uninstalling Uninstall of the mobile device application is controlled by the Palm device. Uninstalling the application from the desktop computer does not affect the application that is installed on the mobile device. For information about Palm OS applications, search for “developer documentation” at www.palmos.com. See also: About the Mobile Devices Page on page 215 Process for Adding Mobile Device Support to an Installation on page 216 Adding Palm OS Files To add Palm OS files to a desktop installation, use the Palm OS wizard. To access the wizard Do one of the following: z Select Installation Expert > Mobile Devices. Do this to add the mobile device installation to an existing installation. Windows Installer Editor Reference 220 Advanced Installations „ From Current Feature, select a feature or condition. (Because any item you add must be assigned to a specific feature, you cannot add an item when All Features is selected.) Items that you add to a feature are installed on the destination computer only if the feature is installed. „ Click Add at the right of the page and select Palm OS. If the Mobile Devices page is not visible, select All or Palm Application from the Page Views drop-down list in Installation Expert. z On the New Installation File dialog box, select the Palm Application template from the Predefined Templates category. Do this to add the mobile device installation to a new installation. The Application Information dialog box appears. To step through the wizard 1. Complete the Application Information dialog box and click Next: „ Application Name Enter the name of the application you are installing. This appears in the list of applications on the Mobile Devices page. „ Desktop Directory Specify a directory on the desktop computer in which to store the files that will be added to the Palm device. Typically, this is a subdirectory of the Program Files directory. If you select one of the folder options on the Palm File Details dialog box, the files are copied to the Palm-specific directories. The files in this directory are uninstalled when the .MSI is uninstalled from the desktop computer. The Palm OS Files dialog box appears. 2. Click Add, specify a file, and complete the Palm File Details dialog box: „ File Name Specify the name for the file when it is installed onto the Palm device. „ Source Pathname This specifies the source path for the file you added. „ Install File to Palm “Add-on” Folder During Installation Copy the file to the Palm\Add-on folder. When the end user runs the Palm Desktop software to specify a new application to install, the contents of the Palm\Add-on folder are displayed first. This lets the end user install the Palm application manually, and gives all Palm users of the desktop computer access to the application. „ Install File to Palm User Folder During Installation Copy the file to the Palm user folder (Palm\user) for each user that is selected on the Palm User Information dialog box, which appears during installation on the desktop computer. Palm applications that are in the Palm user folder are installed to the device whenever a HotSync is performed on the Palm device. See Installing to the Palm User folder on page 220. Note Files that are installed in the Add-on folder or Palm user folders are not uninstalled when the desktop application is uninstalled. Windows Installer Editor Reference 221 Advanced Installations 3. Click OK. To add more files, repeat the preceding step. 4. Click Finish on the Palm OS Files dialog box. To edit the mobile device entry, select it and click Details. See also: About the Mobile Devices Page on page 215 About Palm OS Installations on page 219 Process for Adding Mobile Device Support to an Installation on page 216 Setting Administrator Options Use the Administrator Options page to specify installation and reinstallation options. The options on this page actually set Windows Installer properties under the Properties icon in Setup Editor > Product tab. Select Installation Expert > Administrator Options and complete the page: z Install for Profile Select the profile for installing the application. This controls where some items are stored (examples: shortcuts, desktop items, and HKEY_USERS registry entries). It can also affect uninstall and repair. Example: If an application is installed under an administrator account, regular users cannot uninstall or repair the application. z „ Per-user installation The application is installed under the profile of the end user who installs it. If another user logs in, shortcuts and other personalized information are not available and the application may not run. „ Per-machine installation The application is installed under the All Users profile and is available to any end user. When you select this option, the configuration information, such as Start menu shortcuts, is stored in the All Users location. The user who installs the application must have administrator privileges. „ Determined by user access The application is installed according to the privileges of the end user who installs it. If an administrator installs the application, it is installed for all users. If a regular user installs the application, it is installed only for that user. Reboot Option Specify how restarts are handled at installation completion: „ Reboot if required Restarts if necessary. Example: If the installation needs to replace an in-use file. „ Always reboot A message prompts the end user to restart at the end of the installation. If there is no user interface, the system restarts itself. See Do not display reboot prompts below. „ Never reboot The end user is not prompted to restart even if a restart is needed to replace inuse files. Use this if you are installing several packages at the same time and plan to restart after the final installation. Windows Installer Editor Reference 222 Advanced Installations z Do not display reboot prompts Mark this to restart without end user interaction. This does not perform a restart, but suppresses the prompt if a restart occurs. z Rollback Option Specify how the installation should handle rollbacks. A rollback is the process of returning the computer to its original state in the event that an installation in progress is canceled. A rollback requires the installation to back up existing files instead of just replacing or deleting them and therefore takes more disk space. „ Prompt user to continue without rollback if out of disk space If the destination computer has insufficient disk space for the copies of replaced and deleted files, the end user is asked whether to continue without a rollback. „ Disable rollback without prompting only if out of disk space The installation continues without a rollback if the destination computer has insufficient disk space for a rollback. „ Fail if out of disk space The installation is canceled if the destination computer has insufficient disk space for a rollback. A message informs the end user of the failed installation. „ Rollback if possible with no prompting This is the default behavior for rollbacks, which is to roll back if possible without prompting the user. „ Disable rollback The installation does not create a rollback script and does not support rolling back a canceled installation. z Create advertised shortcuts as regular shortcuts Mark this to have the installation generate regular shortcuts rather than shortcuts supporting installation-on-demand and advertisement. This disables self-repair on shortcuts, which can prevent problems with application repairs occurring when the shortcut is moved or deleted. z Reinstallation Options Reinstallation occurs if Windows Installer determines that an application needs to be repaired. Specify the reinstallation options: „ File Replacement Specify how the installation handles reinstallation of a file. „ Reinstall all per-user based registry keys Mark this to reinstall registry keys the installation places in the HKEY_CURRENT_USER or HKEY_USERS directory on the destination computer. „ Reinstall all shortcuts Mark this to reinstall all shortcuts and re-cache all icons. This also overwrites existing shortcuts and icons. „ Re-cache local copy of installation By default, the installation is stored on the destination computer, without the actual installation files. Mark this to run the installation, when a reinstallation occurs, from the original source instead of the cached copy on the local computer. Then, the installation on the source media is copied to the local computer. See also: Windows Installer Editor Reference 223 Advanced Installations Setting Options for an Administrative Installation on page 225 Specifying Search Locations on page 224 Specifying Search Locations Use the Search Locations page to specify paths to search for installation files during a reinstall or repair. Adding new source locations on the Search Locations page replaces the default location. This feature is intended for system administrators who want to dynamically replace the default search location for self-repair, reinstall, and installationon-demand. By default, if an application needs to be repaired or reinstalled, Windows Installer searches the original source path (stored in the property [SOURCEDIR]), which is the original location from which the application was installed. For a mobile end user, the original source path might not be a good choice for reinstalls and repairs because the user might be at a different location when the reinstall or repair is started. Example: You have a department of mobile end users who travel around the world with their notebook computers. Jim installed Norton AntiVirus from the Applications server while at his home base of Chicago, Illinois. But while Jim is in Amsterdam, you release an update to the Norton installation that neutralizes a new virus. It is more efficient for Jim to be able to reinstall from the Amsterdam Applications server. To solve this problem, you could: z Use your network logon script to always set an environment variable with the nearest Applications server name. z Complete the Search Locations page, but instead of hard coding a server name, specify the environment variable that points to a local server. In addition to using an environment variable to specify a search location, you can use Windows Installer properties, URLs, mapped drive letters, and UNC formatted paths. Search locations are searched in the order they are listed, and the first found instance is used. To specify a search location 1. Select Installation Expert > Search Locations page. 2. Click Add. The Search Location Details dialog box appears. 3. Enter an alternate location that this application should search for the installation package if a repair or reinstall is necessary. You can use the following formats: „ To specify a property, you must set the property to contain an appropriate server location. Example: [APPS_SERVER]\Apps. „ To specify an environment variable, you must set the environment variable to contain an appropriate server location. Example: %CLOSEST_SERVER%\Apps. „ To specify a URL, enter the URL. Example: http:\\intranet.mycompany.com\Apps. „ To specify a mapped drive letter, enter the drive letter and path. Example: X:\Apps „ To specify a UNC formatted path, enter the location in UNC notation. Example: \\APPS_SERVER_AMSTERDAM\Apps. Windows Installer Editor Reference 224 Advanced Installations 4. Click OK. To include the original source directory If you add directories to the Search Locations page, the installation's original source directory is replaced, but you can add it to your search locations. 1. Add [SOURCEDIR] to the Search Locations page. 2. Select MSI Script > Execute Immediate tab and click the Standard tab. 3. Add ResolveSource, a standard Windows Installer action, to the Execute Immediate sequence immediately after the CostInitialize action. 4. Find the action named Set Property WiseModifySourceList and move it below the ResolveSource action. To avoid performing this for each new installation, add these modifications to a template. See Creating and Editing Installation Templates on page 47. See also: Setting Options for an Administrative Installation on page 225 Setting Administrator Options on page 222 Setting Options for an Administrative Installation Use the Administrative Install page to specify the property values to be set during an installation from an administrative image. Properties that you set on this page are only in effect during installation from an administrative image. If an end user runs this installation directly, not from an administrative image, then this page has no effect. For information on administrative installations, see Administrative Installation in the Windows Installer SDK Help. Development computer. Use Package Distribution to perform an administrative installation to a shared network server. Administrative Installation. Properties defined under the Properties icon in Setup Editor > Product tab are stored in the .MSI and applied during installation. Shared network server. Server stores the administrative image. Regular Installation. Properties set on Administrative Install page are applied during installation. These values override properties defined in the .MSI. End user computer. User, logon script, or other mechanism starts installation by running the administrative installation on the server. Windows Installer Editor Reference 225 Advanced Installations To set a property for the administrative image 1. Select Installation Expert > Administrative Install. 2. In Default Installation Folder, specify the directory on the destination computer where the installation should be copied. During installation from the administrative image, this is the default destination directory on the Destination Folder dialog box. You cannot enter bracketed property names in this field. 3. Click Add. The Property Settings Override dialog box appears. 4. Complete the dialog box: „ Name Select an existing property or enter a property name. You can create your own unique property, or enter a Windows Installer property name. Do not surround the property name with brackets. Properties can either be public (uppercase) or private (mixed case). For descriptions of properties in this installation, see Build Properties on page 508. For a complete list of Windows Installer Properties, see Property Reference in the Windows Installer SDK Help. „ 5. Value Enter the value for the property. You cannot enter properties because they will not be resolved into their values. Click OK. See also: Setting Administrator Options on page 222 Specifying Search Locations on page 224 About Command Lines Command lines change the behavior of an .EXE for different work environments and user requirements. You can work with two sets of command lines for installations: Command lines that you can apply to installations at run time Command lines that you can apply to Windows Installer Editor for compiling Call MSIExec.EXE. Call WFWI.EXE. Are applied to Windows Installer installations or patches at run time. Are applied to Windows Installer Editor at run time to compile an installation. Options let you specify UI, logging, advertising, and repair options. They also let you edit public properties, apply transforms, and apply or remove patches. Options let you control logging and UI, and set default values for properties in the compiled installation. Windows Installer Editor Reference 226 Advanced Installations Command lines that you can apply to installations at run time Command lines that you can apply to Windows Installer Editor for compiling Are documented fully in Command Line Options and Standard Installer Command Line Options in the Windows Installer SDK Help. Are documented in Wise product documentation. Can be built automatically with the Command Line page. z See Command Line Options For WFWI.EXE on page 235. Must be built manually. See Creating a Command Line To Apply to an Installation on page 227. Can be built manually. z See Command-Line Options in the Windows Installer SDK Help. See also: WFWI.EXE Command Line Option Example on page 236 Automating the Build Process on page 237 Creating a Command Line To Apply to an Installation ¾ Not available in a transform. Command lines cannot be applied to a transform. Use the Command Line page in Installation Expert to create syntactically correct command lines to apply to an installation at run time. These are applied to MSIExec.EXE on the destination computer. Command lines that you create appear in a popup menu for the Test and Run buttons so you can test them. To create a command line to apply to an installation 1. Select Installation Expert > Command Line page. 2. Click Add. The Command Line Details dialog box appears. Note Although you can enter a command line in the Command Line field, we recommend that you use the options provided in this utility for an optimal, errorfree installation. 3. Click the General tab and complete the dialog box: „ Name Enter the name of the command line. „ Shortcut File Specify the full path of the shortcut file (.LNK) you are creating to execute the command line. The default location is the Temp directory. You also can create a batch file by changing the file extension to .BAT. Windows Installer Editor Reference 227 Advanced Installations „ 4. Install Mode Select an install mode:  Install Installs or configures the installation package. Select this option to remove patches.  Advertised Advertises the installation on the destination computer.  Repair Repairs an application that is installed on the destination computer.  Network Install Extracts the files in the installation package to a network location.  Uninstall Uninstalls the installation package.  Update Updates the installation package by applying patches. Depending on the install mode you select, additional tabs appear on the Command Line Details dialog box. Following are the tabs that appear and how you can use them to modify the command line: „ UI Options Make the installation run in silent mode and set the user interface level. See Applying UI Options to an Installation on page 229. „ Logging Generate a log when the installation is run and select logging options. See Applying Logging Options to an Installation on page 230. „ Advertising Advertise applications and apply a transform to the advertised package. See Applying an Advertising Option to an Installation on page 231. „ Repair Repair installed files. See Applying a Repair Option to an Installation on page 232. „ Properties Change the value of public properties. See Changing Public Properties in an Installation on page 233. „ Transforms Apply transforms to the installation package using the TRANSFORMS property. See Applying Transforms to an Installation on page 234. „ Patches Add or remove patches using the PATCH and MSIPATCHREMOVE properties. See Applying or Removing Patches With a Command Line on page 234. 5. After you modify the command line, click OK. The command line is added to the Command Line page. To edit it, double-click its name. To delete it, select it and click Delete. Windows Installer Editor Reference 228 Advanced Installations See also: About Command Lines on page 226 Applying UI Options to an Installation ¾ Not available in a transform. Command lines cannot be applied to a transform. You can use a command line to set the UI options, which determine how much the end user interacts with the installation. See User Interface Levels in the Windows Installer SDK Help. You can set UI options for all versions of Windows Installer or for Windows Installer 3.0 only. To apply UI options to an installation 1. On the Command Line Details dialog box, click the UI Options tab. See Creating a Command Line To Apply to an Installation on page 227. 2. To enable the UI Options check boxes, mark Set User Interface level. 3. By default, qn - No UI is marked in the All Windows Installer versions section. To set options for all versions of Windows Installer, mark the appropriate options in this section. „ qn - No UI Displays no user interface during the installation. „ qb - Basic UI Displays built-in modeless dialog boxes that show progress messages during the installation. Note Modal dialog boxes require user input whereas modeless dialog boxes don’t. „ qr - Reduced UI Displays authored modeless dialog and built-in modal error-message boxes during the installation. „ qf - Full UI Displays both modal and modeless dialog boxes that have been authored into the internal user interface, and built-in modal error-message boxes during the installation. „ qn+ - No UI Displays no user interface, except for a modal dialog box at the end of the installation. „ qb+ - Basic UI Displays built-in modeless dialog boxes that show progress messages during the installation and a modal dialog box at the end of the installation. „ qb- - Basic UI Displays built-in modeless dialog boxes that show progress messages and no modal dialog boxes during the installation. Windows Installer Editor Reference 229 Advanced Installations 4. If you mark the qb, qb+, or qb- option, then the Hide the Cancel Button check box is enabled. Check this to add the ! switch to the command line, which removes the Cancel button from the installation dialog boxes. 5. To set options for Windows Installer 3.0 only, mark one of the following options in the Windows Installer 3.0 only section. This overrides any options you mark in the All Windows Installer versions section. (These options are enabled only if Windows Installer 3.0 or later is installed on your computer.) 6. 7. „ Quiet - No UI Displays no user interface during the installation. „ Passive - display a progress bar but no other prompts or messages If you mark Quiet or Passive in the Windows Installer 3.0 only section, you can also control how Windows Installer handles restarts. „ Default (Restart if required) Restarts the computer when necessary with no prompts or warnings to the user. „ No restart Never restarts the computer after the installation. „ Force restart Always restarts the computer after the installation. „ Prompt restart (Passive only.) Displays a message that a restart is required to complete the installation and asks the user if they want to restart the computer now. Click OK. See also: Creating a Command Line To Apply to an Installation on page 227 Applying Logging Options to an Installation ¾ Not available in a transform. Command lines cannot be applied to a transform. You can use a command line to set logging options that determine what activities are logged during the installation. For information on logging options, see Logging in the Windows Installer SDK Help. You can set logging options for all versions of Windows Installer or for Windows Installer 3.0 and later. In Windows Installer 4.0 and later, you can set logging options in the installation instead of with a command line. See Setting Version-Specific Windows Installer Options on page 174. To apply logging options to an installation 1. Click the Logging tab on the Command Line Details dialog box. See Creating a Command Line To Apply to an Installation on page 227. 2. To enable the Logging Options check boxes, mark Create Log File. This enables the field to its right, which displays the default location for a log file created during installation. The default location is the Temp directory. Windows Installer Editor Reference 230 Advanced Installations 3. To change the location of the log file, specify a new path. 4. To set logging options for all versions of Windows Installer, mark the appropriate check boxes in the All Windows Installer versions section: 5. „ * - Wildcard, log all information Logs all information, but does not use verbose output. This is marked by default. When this check box is marked, the first four options in this section are enabled. Clear this check box to enable all the other options in this section. „ v - Verbose output Logs more detailed information about each event or error. „ + - Append to existing file Appends the log to an existing log file. „ ! - Flush each line to the log „ i - Status messages „ w - Non-fatal warnings „ a - Start up of actions Logs actions as they are started. „ r - Action-specific records „ u - User requests „ c - Initial UI parameters Logs the initial user interface parameters. „ m - Out-of-memory or fatal exit information „ o - Out-of-disk-space messages „ p - Terminal properties „ e - All error messages To set logging options for Windows Installer 3.0 or later, mark log - log all information in the Windows Installer 3.0 or later section. This overrides any options you mark in the All Windows Installer versions section. Note This option is enabled only if Windows Installer 3.0 or later is installed on your computer. It will work on the destination computer only if it has Windows Installer 3.0 or later installed. 6. Click OK. See also: Creating a Command Line To Apply to an Installation on page 227 Applying an Advertising Option to an Installation ¾ Not available in a transform. Command lines cannot be applied to a transform. Windows Installer Editor Reference 231 Advanced Installations Windows Installer can advertise the availability of an application to end users and to other applications without actually installing the application. If an application is advertised, only the interfaces required for installing the application are presented to the end user or other applications, saving time and disk space. End users install the application by activating the advertised interface. You can use a command line to set advertising options that determine who sees the advertised application and whether a transform is applied to it. For information on advertising options, see Advertisement in the Windows Installer SDK Help. To apply advertising options to an installation 1. Click the Advertising tab on the Command Line Details dialog box. See Creating a Command Line To Apply to an Installation on page 227. Note The Advertising tab appears only when Install Mode on the General tab of the Command Line Details dialog box is set to Advertised. 2. Complete the dialog box: „ m - Advertise to all users of machine „ u - Advertise to the current user „ t - Applies transform to advertised package Add a transform to the advertised installation. In the field below the check box, specify the transform file to include in the installation. 3. Click OK. See also: Creating a Command Line To Apply to an Installation on page 227 Applying a Repair Option to an Installation ¾ Not available in a transform. Command lines cannot be applied to a transform. You can use a command line to set a repair option for an installation that determines the files that are reinstalled during a repair. You also can specify whether files are rewritten, overwritten, or run from the source. For information on repair options, see REINSTALLMODE Property in the Windows Installer SDK Help. To apply repair options to an installation 1. Click the Repair tab on the Command Line Details dialog box. See Creating a Command Line To Apply to an Installation on page 227. Note The Repair tab appears only when Install Mode on the General tab of the Command Line Details dialog box is set to Repair. Windows Installer Editor Reference 232 Advanced Installations 2. 3. Complete the dialog box: „ p - Reinstall only if file is missing „ o - Reinstall if file is missing or if an older version is installed „ e - Reinstall if file is missing or an equal or older version is installed „ d - Reinstall if file is missing or a different version is installed. „ c - Reinstall if file is missing or the stored checksum doesn’t match the calculated value „ a - Force all files to be reinstalled „ u - Rewrite all required user specific registry entries „ m - Rewrite all required machine specific registry entries „ s - Overwrite all existing shortcuts „ v- Run from source and re-cache the local package Click OK. See also: Creating a Command Line To Apply to an Installation on page 227 Changing Public Properties in an Installation ¾ Not available in a transform. Command lines cannot be applied to a transform. For information on public properties, see Public Properties in the Windows Installer SDK Help. To change public properties in an installation 1. Click the Properties tab on the Command Line Details dialog box. See Creating a Command Line To Apply to an Installation on page 227. Note The Properties tab appears only when Install Mode on the General tab of the Command Line Details dialog box is set to Install or Network Install. 2. Select a property in the left pane and click Add to copy it to the right pane. 3. In the right pane, enter the value for the property. 4. Click OK. See also: Creating a Command Line To Apply to an Installation on page 227 Windows Installer Editor Reference 233 Advanced Installations Applying Transforms to an Installation ¾ Not available in a transform. Command lines cannot be applied to a transform. For information on transforms, see TRANSFORMS Property in the Windows Installer SDK Help. To apply transforms to an installation 1. Click the Transform tab on the Command Line Details dialog box. See Creating a Command Line To Apply to an Installation on page 227. Note The Transforms tab appears only when Install Mode on the General tab of the Command Line Details dialog box is set to Install. 2. Click Add and specify the transform file (.MST). The full path appears in Transform List. 3. Repeat the preceding step to specify additional transforms. 4. Because Windows Installer applies transforms in the order specified, adjust the order of the transforms as needed. 5. Click OK. See also: Creating a Command Line To Apply to an Installation on page 227 Applying or Removing Patches With a Command Line ¾ Not available in a transform. Command lines cannot be applied to a transform. You can use a command line to update an installation by applying or removing patches. For information on patches, see PATCH Property and MSIPATCHREMOVE Property in the Windows Installer SDK Help. Prior to Windows Installer 3.0, you could only remove a patch by uninstalling the entire application. Beginning with Windows Installer 3.0, you can remove a single patch or a set of patches in any order without uninstalling the application. See Removing Patches and Uninstallable Patches in the Windows Installer SDK Help. To apply or remove patches with a command line 1. On the General tab, select one of the following from Install Mode. See Creating a Command Line To Apply to an Installation on page 227. „ Windows Installer Editor Reference Install Use this option to remove or apply patches. You can apply patches to an installed package or to the package being installed by the command line 234 Advanced Installations „ Update Use this option to update installed applications. 2. Click the Patches tab on the Command Line Details dialog box. 3. Mark whether to add or remove patches. The option to remove patches is enabled only if Windows Installer 3.0 or later is installed on your computer. 4. Click Add and specify a patch file (.MSP). The full path appears in the Patch List. 5. Repeat the preceding step to specify additional patches. (Windows Installer 3.0 or later only.) 6. Windows Installer applies patches in the order listed. To rearrange the order, click Move Up or Move Down. If you used patch sequencing with Windows Installer 3.0 when you created the patches, that sequencing would override the order you specify here. 7. Click OK. See also: Creating a Command Line To Apply to an Installation on page 227 Command Line Options For WFWI.EXE You can invoke Windows Installer Editor (WfWI.exe) with command-line options and pass it the name of your project file (.WSI or .WSM) as a parameter. WFWI.exe command lines let you compile an installation or merge module, while setting options that have to do with the compile. You can also set the default value of Windows Installer properties within the installation. Use the following syntax: “path\WFWI.EXE” “path\project file” /option You can also start Windows Installer Editor (WfWI.exe) in the Visual MSIDiff mode using the following command line: WFWI.EXE base_file compare_file See Comparing Windows Installer Files on page 74. Do not confuse this list of command-line options with the command-line options that you can apply at run time to an .MSI through the executable msiexec.exe. For a list of those command-line options, see Command Line Options in the Windows Installer SDK Help. Command-line options Description /c Compile only and exit This option compiles a .WSI to an .MSI, or a .WSM to an .MSM. This option must be the first one in the command-line statement. Windows Installer Editor Reference 235 Advanced Installations Command-line options Description /c=“release_name” Compile only the specified release from an installation containing multiple releases /p name=value Set property values The property name and value must immediately follow the /p. You can use as many property name and value switches as you like in a command line. Do not enter any spaces in the name=value construction, unless they are enclosed in double quotes. /o path Specifies the compiled output file You cannot specify a relative path; specify an absolute path. The path must immediately follow the /o. /F Has the same effect as clearing the Don’t update or recompress files when saving check box on the products Details page See Product Details Page on page 83. /s Compile silently If you don’t include this, error or informational messages might appear that require user intervention. /l log_file_name Creates an additional compile log file in addition to compile.log, which is created automatically WFWI.EXE Command Line Option Example The following example shows how to compile an installation from the command line. “path\WFWI.EXE” C:\Installers\MyApp.wsi /c /s /p CURRENT_FILES="E:\Test Development" /o C:\MyAppInstaller.msi The preceding command line does the following: z Invokes the executable z Specifies the .WSI to compile (C:\Installers\MyApp.wsi) z Sets it to compile (/c) z Sets all error messages to be suppressed (/s) z Sets the property CURRENT_FILES (/p CURRENT_FILES="E:\Test Development") z Sets the output location (/o C:\MyAppInstaller.msi) If you set multiple properties, separate the property value pairs with spaces. Enclose the values with double quotes. Windows Installer Editor Reference 236 Advanced Installations Automating the Build Process You can use the WFWI.exe command-line options in conjunction with other processes to create an automated build process. Enter the following command-line statement into a batch file or any other program that has the ability to run command-line statements, such as Scheduled Tasks in Control Panel: “path\WFWI.EXE” “path\project file” /c /o “path\output file” /s where: z “path\WfWI.exe” is the path to the Wise executable z “path\project file” is the path to the installation (.WSI) or merge module (.WSM) project file to compile z “path\output file” is the location of the compiled installation (.MSI) or merge module (.MSM) Adding a Digital Signature to an Installation Use the Digital Signature page to add an Authenticode digital signature to an installation file so its integrity and authenticity can be verified. Digital signature methods The file signing tool that is used to digitally sign a file depends on the type of your digital certificate: z Public/private key pair files This method requires a credentials file (.SPC or .CER) and a private key file (.PVK). This method is supported by the signcode.exe tool. For details, search for “Signcode” in the MSDN Library (msdn.microsoft.com/library/). z Personal Information Exchange file This method requires a Personal Information Exchange file (.PFX), which is a container file for the public/private key information. This method is supported by the signtool.exe tool. For details, search for “Signtool” in the MSDN Library (msdn.microsoft.com/library/). Requirements z You must have a valid code signing certificate, which you can obtain from a commercial certificate authority such as Verisign. For a list of certificate authorities, search for “Microsoft Root Certificate Program Members” in the MSDN Library (msdn.microsoft.com/library/). z You must have the signtool.exe or signcode.exe tool on your computer. z Signtool.exe requires the CAPICOM 2.0 redistributable to be installed and registered on your computer. CAPICOM provides services for digitally signing applications, and is available from the Microsoft Web site. z The location of signtool.exe or signcode.exe must be specified on the Digital Signature tab in Wise Options, or they must be available on the system path. Windows Installer Editor Reference 237 Advanced Installations To add a digital signature Select Installation Expert > Digital Signature page, mark Add a digital signature, and complete the page: z Web URL Enter your organization’s Web site address. z Descriptive Name Enter the name of your application. This name is embedded in your Authenticode certificate to let end users verify the name of the application they are installing. z TimeStamp URL Specify the URL you use for your timestamping service. Timestamping lets end users distinguish between a certificate that has expired but was valid when it was used to sign the installation, and a certificate that was used to sign an installation while it was expired. The timestamping service must be available on your computer to build the installation but does not need to be available to the end user running the installation. z Certificate options „ Signtool.exe with Personal Information Exchange file Mark this to use signtool.exe and then specify the Personal Information Exchange file (.PFX) to use. This option requires a password. You will be prompted for the password during compile. „ Signcode.exe with public/private key pair files Mark this to use signcode.exe and then specify the credentials file (.SPC or .CER) that contains your Digital ID, and your private key file (.PVK). z Digital Signature for Specify which output files should be digitally signed. If you select a type of output file that is not selected on the Build Options page, this drop-down list is ignored. Example: If you specify Do not create an .EXE file in .EXE Options on the Build Options page, and in this drop-down list you select Installation .EXE only, no digitally signed installation is created, because the installation doesn’t create an .EXE file. Note The ability to add a digital signature to .MSI and external .CAB files is supported by Windows Installer 2.0 or later only. See also: Setting Digital Signature Options on page 37 Creating an Installation for Microsoft SMS If an installation will be run in a Microsoft Systems Management Server (SMS) environment, you can have the installation create a status .MIF file in the Windows directory to describe the application. In order to use an installation in an SMS environment, you must also create a package definition file (.PDF or .SMS), which contains information about the installation. You can create the package definition file Windows Installer Editor Reference 238 Advanced Installations manually, or configure the installation to create it when compiled. For information about SMS, visit the Microsoft Developer Network (msdn.microsoft.com). The Microsoft SMS page specifies the information for the .MIF file and package definition file. Alternatively, you can apply the /m command-line option to msiexec.exe to create a status.mif file. See Command Line Options in the Windows Installer SDK Help. To have the installation create a status .MIF file and a package definition file, mark Create Status MIF and complete the page. z Install MIF Filename Enter the name of the application being installed. Example: sample.mif. z Uninstall MIF Filename Enter the name of the application being uninstalled. Example: uninstall_sample.mif. z Serial Number Enter the serial number of the application being installed. z Package Definition File To create a package definition file when the installation is compiled, mark one of the following check boxes. Verify that the installation’s name, version, and manufacturer are entered on the Product Details page, because that information is included in the package definition file. Note To move the installation to Microsoft SMS using Package Distribution in Wise Package Studio, one of the Package Definition File options must be selected. See Preparing a Package for Microsoft SMS Deployment in the Wise Package Studio Help. „ Create .PDF File (SMS 1.2 or earlier) Mark this to create a package definition file of file type .PDF. In Version, enter the SMS version. „ Create .SMS File (SMS 2.0 or later) Mark this to create a package definition file of file type .SMS. In Version, enter the SMS version. You can also import an existing Microsoft SMS installation. See Legacy Setup Conversion in the Wise Package Studio Help. Creating a .NET Installation When You Have the .NET Framework ¾ Windows Installer 2.0 or later only. The .NET Framework helps automate the process of building a .NET installation by extracting most of the assembly details from the assembly manifests and adding them to the installation. To create a .NET installation when you have the .NET Framework 1. Select Installation Expert > Product Details page. 2. In the Application Type field, select either .NET Application or Mixed (.NET and Win32). Windows Installer Editor Reference 239 Advanced Installations This designates the installation as .NET and determines how Windows Installer Editor handles COM interop registry entries. See Product Details Page on page 83. 3. Add assemblies and their dependency files to the installation, using the Files page. See Adding .NET Assemblies to the Installation on page 115. Windows Installer Editor finds all multifile assemblies and adds them automatically. Depending on the Scan Dependencies option in Wise Options, dependency assemblies might be added automatically, or you might be prompted to add them. If the option to Never scan dependencies is selected, you must add the dependencies. 4. If the destination computer’s operating system is not Windows XP or later, add support for the .NET Framework to the installation. On the Prerequisites page, select the desired release and then select the runtime from .NET Framework Runtime Version. See Adding Prerequisites to a Release on page 195. 5. Finish building the installation as usual, then compile and distribute it. See also: About Microsoft .NET Technology on page 493 Requirements for Creating a .NET Installation on page 497 Frequently Asked Questions About Microsoft Windows Installer on page 491 Creating a .NET Installation Without the .NET Framework on page 240 Setting a Requirement on the System Requirements Page on page 164 (for information on setting the required .NET Framework version) Creating a .NET Installation Without the .NET Framework ¾ Windows Installer 2.0 or later only. You can build an installation for a .NET application even if you do not have the .NET Framework installed on your computer. Perhaps your company’s development computers have the .NET Framework, but the computer you use to build installations does not. If you do not have the .NET Framework, you must do manually what the .NET Framework normally does automatically. To create a .NET installation without the .NET Framework 1. Select Installation Expert > Product Details page. 2. In Application Type, select either .NET Application or Mixed (.NET and Win32). This designates the installation as .NET and determines how Windows Installer Editor handles COM interop registry entries. See Product Details Page on page 83. 3. Add assemblies to the installation, using the Files or Web Files page. Be sure to add all files in multifile assemblies. Windows Installer Editor Reference 240 Advanced Installations See Adding .NET Assemblies to the Installation on page 115. 4. Add attributes and dependencies for each assembly. a. Use a computer that has the .NET Framework installed and has the assemblies. This typically is a development computer. b. For each assembly, run the ildasm tool from the Visual Studio .NET command prompt. When you run ildasm, you select an assembly and the program displays the assembly’s attributes. Write down the assembly’s culture, name, publicKeyToken, and version, as well as any dependencies. c. On the Files or Web Files page, add the dependency assemblies to the same directory as the assembly that has the dependencies. Repeat for each assembly. d. In the lower right pane of the Files or Web Files page, double-click an assembly to display the File Details dialog box. Click the Assembly tab. Click Add to add the Name and Value of the assembly’s culture, name, publicKeyToken, and version. Repeat for each assembly. See Editing Assembly Settings for Files on page 127. 5. If the installation contains both .NET and Win32 components, register the .NET components for COM interop. a. Use a computer that has the .NET Framework installed and has the assemblies. This typically is a development computer. b. For each .NET assembly, run the Assembly Registration tool (regasm) from the Visual Studio .NET command prompt. Run regasm with the argument /regfile and specify a file name. Example: regasm AssemblyFileName /regfile:RegFileName.reg. This command generates a .REG file containing the registry entries you need to allow the .NET assembly to be called as a COM component. Search for “Assembly Registration Tool (Regasm.exe)” in the MSDN Library (msdn.microsoft.com/library/). c. On the Registry page, import the .REG file you created for each assembly. See Adding Registry Keys on page 140. 6. If the destination computer’s operating system is not Windows XP or later, add support for the .NET Framework to the installation. On the Prerequisites page, select the desired release and then select the runtime from .NET Framework Runtime Version. See Adding Prerequisites to a Release on page 195. 7. Finish building the installation as usual, then compile and distribute it. See also: About Microsoft .NET Technology on page 493 Requirements for Creating a .NET Installation on page 497 Frequently Asked Questions About Microsoft Windows Installer on page 491 Creating a .NET Installation When You Have the .NET Framework on page 239 Windows Installer Editor Reference 241 Advanced Installations About Web Installations You can create an installation that installs Web resources to a Microsoft Internet Information Server (IIS) by using the Web Files page in Installation Expert. To learn about file-related functionality on the Web Files page, see Files or Web Files Page on page 105 and its subtopics. To learn about Web-related functionality, see: Features That Support Web Installations on page 243 Creating a Web Site on page 244 Creating a Virtual Directory on page 246 Creating a New Web Folder on page 248 Setting Installation Options for a Web Installation on page 249 Setting Installation Options for a Child Virtual Directory on page 250 About the Web Site Details Dialog on page 252 Installing Web Settings From a File on page 253 Note If you cannot see the Web Files page in the list of pages in Installation Expert, select Web Application or All from the Page Views drop-down list in the upper-left corner. Differences between the Files page and Web Files page Files page Web Files page You can create directories and add files to them You can create Web folders, virtual directories, and Web sites, and add files to them You can set NTFS-based (NT file system) permissions on directories You can set Web-based security on directories It shows all directories and files that will be installed, including Web items It shows only directories and files that will be accessible through an IIS Web server It shows Web sites under the physical directory where they will be installed It shows Web sites in the hierarchy as they will appear in IIS Internet Services Manager It contains the wwwroot directory, which represents the physical InetPub\wwwroot directory on the destination computer It does not contain wwwroot, but you can map a virtual directory to a physical directory that you created under wwwroot on the Files page You cannot delete a physical directory that is mapped to a virtual directory or Web site You can delete a virtual directory or Web site, and a message asks if you want to delete the corresponding mapped physical directory and files You can delete a non-Web directory You cannot delete a non-Web directory, except in the instance described above See also: When to Use the File-Related Installation Expert Pages on page 107 Windows Installer Editor Reference 242 Advanced Installations Features That Support Web Installations In addition to the Web Files page, the following features throughout the product specifically support Web application installations: Dynamic editing of XML files The Dynamic Content tab appears for valid XML files, such as Web.config, that you add to the installation. Use it to edit the attributes in an XML file by substituting the value of Windows Installer properties at run time. Gather the values of properties using the Custom Property dialog below. See Editing XML Files During Installation on page 131. Custom Property dialog The Custom Property dialog provides an easy way to let the end user specify values for Windows Installer properties. You can use these properties to populate an XML file, as described above. See Adding the Custom Property Dialog on page 425. SQL Connection dialog Let the end user select a SQL Server name and security credentials to generate a valid SQL Server connection string. The connection string can then be used elsewhere, such as in a Web.config file or on the SQL Server Scripts page. See About the SQL Connection Dialog on page 422. ASPNET properties The default ASP .NET users that are set by .NET installations are put into Windows Installer properties: ASPNET_USER, ASPNET1.0_USER, and ASPNET1.1_USER. You can use these for setting directory security. See Run Time Properties on page 515. Directory security You can set NTFS directory security, which enhances Web site security. See Setting Permissions for Files and Directories on page 125. Wildcard groupings To make it easier to quickly add all files of specific types, such as all Web file types, you can set up Wildcard groups in Wise Options. Then, when you add the contents of a directory on the Files or Web Files page, you can choose a wildcard group to filter on. See Setting Wildcard Groups on page 46. Check for IIS version Windows Installer Editor Reference On the System Requirements page, you can require a specific version of Microsoft Internet Information Server (IIS). Once you set an IIS version, a list of Web extensions appears, and you can check whether they are enabled. However, the Web extensions are only valid on destination computers with IIS 6.0 later. 243 Advanced Installations Instance transforms You can install more than one instance of a Web application to multiple virtual directories using instance transforms. See Multiple Instance Installations on page 343. See also: About Web Installations on page 242 Creating a Web Site New Web sites that you add to an installation appear under the Program Files directory by default. Prior to Windows Vista, Microsoft Internet Information Server (IIS) supported the creation of new Web sites only on server operating systems, which excluded Windows 2000 Professional and Windows XP. For workstation operating systems that do not support the creation of a Web site, you can let end users create a virtual directory instead of a Web site. When you set the installation options for a Web installation, you can select an option to install it as a virtual directory. See Setting Installation Options for a Web Installation on page 249. To create a Web site 1. Select Installation Expert > Web Files page. If you don’t see the Web Files page, select All from the Page Views drop-down list. 2. From Current Feature, select a feature or condition. (Because any item you add must be assigned to a specific feature, you cannot add an item when All Features is selected.) 3. If the Web installation requires a Web server restart, mark Restart IIS service during installation. This check box does not appear when All Features is selected above. 4. In the lower-left list box, select a parent node. 5. Click New and select New Web Site. The New Web Site dialog box appears. 6. 7. Complete the dialog box: „ Description Enter a description for the directory, which serves as an identifying name in Internet Information Services. „ Local Path Specify the physical directory to which the Web site is mapped. You can browse to any directory that has already been added to the installation. Example: Change this to a directory under wwwroot to have this item reside under wwwroot. Click OK. The site appears in the lower-left list box. 8. Select the new site and click Details. Windows Installer Editor Reference 244 Advanced Installations The details dialog box appears with several tabs. 9. Click the Installation Settings tab and complete the tab: „ Override Existing Settings If an installation with the same name as this one is already on the destination computer, specify whether to retain existing settings (None) or override existing settings (All). „ Support IIS 7.0 (Vista) This option enables IIS 7.0, which is available only with Vista and later. If you create a new installation, this check box is checked by default. If you open an installation created with a previous version of Windows Installer Editor, it is not checked. When this option is checked, a web.config file is added to the installation although it is not saved until you save or compile the installation. The web.config file contains the settings that you select on the Details dialog box. This web.config file is required for the support of virtual directory creation in IIS 7.0 and later. 10. Click the Web Site UI tab. Use this tab to specify the installation options that will be available to the end user at run time. See Setting Installation Options for a Web Installation on page 249. 11. Complete the remaining tabs on the details dialog box. These tabs correspond to options on the properties dialog box in IIS, version 5.0. Use them to specify which options are user-configurable at run time. Use the IIS help for information about these tabs. See About the Web Site Details Dialog on page 252. 12. Click OK on the details dialog box. Note Clicking OK on the details dialog box regenerates the Web dialog boxes in the installation. To delete a Web site z On the Web Files page, in the lower-left list box, select a Web site and click Delete. At the prompt that appears: „ Click Yes to delete the corresponding physical directory and files. „ Click No to clear the Web Folder settings but leave the folders and files in the installation and the lower-left pane. If the Delete button is unavailable, it means you have selected a normal folder instead of a Web site. To delete a normal folder from the installation, use the Files page. On the Files page, you cannot delete a physical directory that is linked to a Web site. To change a Web site to a virtual directory z On the Web Files page, in the lower-left list box, right-click a Web site and select Change to Virtual Directory. Any Web dialog boxes in this installation are regenerated. Settings on the details dialog box that do not apply to virtual directories are unavailable. However, if you change this back to a Web site, those settings are retained. Windows Installer Editor Reference 245 Advanced Installations See Setting Installation Options for a Web Installation on page 249 and About the Web Site Details Dialog on page 252. See also: About Web Installations on page 242 Creating a Virtual Directory This section covers creating a virtual directory, converting an existing installation directory to a virtual directory, adding a directory from your computer as a virtual directory, and deleting a virtual directory. A virtual directory is considered top-level if it is directly under Destination Computer, and is considered a child if it is under a Web site. To create a virtual directory 1. Select Installation Expert > Web Files page. If you don’t see the Web Files page, select All from the Page Views drop-down list. 2. From Current Feature, select a feature or condition. (Because any item you add must be assigned to a specific feature, you cannot add an item when All Features is selected.) 3. If the Web installation requires a Web server restart, mark Restart IIS service during installation. This check box does not appear when All Features is selected above. 4. In the lower-left list box, select a parent node. 5. Click New and select New Virtual Directory. The New Virtual Directory dialog box appears. 6. 7. Complete the dialog box: „ Alias Enter an alias for the directory. This typically appears in the URL to this Web resource. „ Local Path Specify the physical directory to which the alias is mapped. You can browse to any directory that has already been added to the installation and create an additional directory (optional) by typing its name in this field. Click OK. The virtual directory appears in the lower-left list box. 8. Select the new virtual directory and click Details. The details dialog box appears with several tabs. For a top-level virtual directory, the Web Site, Web Site UI, and Home Directory tabs appear. For a child virtual directory, the Virtual Directory and Virtual Directory UI tabs appear. The remaining tabs are the same for both types of virtual directory. 9. Click the Installation Settings tab and complete the tab: Windows Installer Editor Reference 246 Advanced Installations „ Override Existing Settings If an installation with the same name as this one is already on the destination computer, specify whether to retain existing settings (None) or override existing settings (All). „ Remove on Uninstall (Top-level virtual directories only.) Mark this to have this virtual directory removed (unregistered) from IIS during uninstall. This does not uninstall the physical directory and files—the normal uninstall mechanism handles that. „ Support IIS 7.0 (Vista) This option enables IIS 7.0, which is available only with Vista and later. If you create a new installation, this check box is marked by default. If you open an installation created with a previous version of Windows Installer Editor, it is not checked. When this option is checked, a web.config file is added to the installation although it is not saved until you save or compile the installation. The web.config file contains the settings that you select on the Details dialog box. This web.config file is required for the support of virtual directory creation in IIS 7.0 and later. 10. To specify the installation options that will be available to the end user at run time, do one of the following: „ If this is a top-level virtual directory, click the Web Site UI tab. See Setting Installation Options for a Web Installation on page 249. „ If this is a child virtual directory, click the Virtual Directory UI tab. See Setting Installation Options for a Child Virtual Directory on page 250. 11. Complete the remaining tabs on the details dialog box. These tabs correspond to options on the properties dialog box in IIS, version 5.0. Use them to specify which options are user-configurable at run time. Use the IIS help for information about these tabs. See About the Web Site Details Dialog on page 252. 12. Click OK on the details dialog box. Note Clicking OK on the details dialog box regenerates the Web dialog boxes in the installation. To add a directory from your computer as a virtual directory 1. On the Web Files page, manually create a virtual directory with the name of the directory on your computer. 2. In the upper-left list box, navigate to and select the directory on your computer. 3. Click Add Contents. The Add Contents dialog box appears. 4. In Dest. Directory, clear the name and then click OK. The contents are added into the virtual directory. If you don’t first clear the Dest. Directory field, then the directory is added as a Web folder. Windows Installer Editor Reference 247 Advanced Installations To map an existing physical directory to a virtual directory Use this procedure if you have already created a directory on the Files page or a Web folder on the Web Files page, and you now want to map that directory to a virtual directory. 1. On the Web Files page, in the lower-left list box, select a parent node. 2. Click New and select New Virtual Directory. The New Virtual Directory dialog box appears. 3. 4. Complete the dialog box: „ Alias Enter an alias for the directory. This appears in the URL to this Web resource. „ Local Path Browse to the existing directory to be mapped to a virtual directory. Click OK. To delete a virtual directory z On the Web Files page, in the lower-left list box, select a virtual directory and click Delete. A message asks if you want to delete the corresponding physical directory and files. On the Files page, you cannot delete a physical directory that is linked to a virtual directory. To change a virtual directory to a Web site z On the Web Files page, in the lower-left list box, right-click a top-level virtual directory and select Change to Web Site. (You cannot change a child virtual directory.) Any Web dialog boxes in this installation are regenerated. Settings on the details dialog box that do not apply to Web sites are unavailable. However, if you change this back to a virtual directory, those settings are retained. See Setting Installation Options for a Web Installation on page 249 and About the Web Site Details Dialog on page 252. See also: About Web Installations on page 242 Creating a New Web Folder To create a new Web folder 1. Select Installation Expert > Web Files page. If you don’t see the Web Files page, select All from the Page Views drop-down list. 2. From Current Feature, select a feature or condition. (Because any item you add must be assigned to a specific feature, you cannot add an item when All Features is selected.) 3. In the lower-left list box, select a Web site or virtual directory. Windows Installer Editor Reference 248 Advanced Installations 4. Click New and select New Web Folder. 5. Enter a name for the directory and click OK. 6. Select the new directory and click Details. The details dialog box appears with several tabs. 7. Complete the tabs on the details dialog box. These tabs correspond to options on the properties dialog box in IIS, version 5.0. For information on these tabs, see the IIS help. Also see About the Web Site Details Dialog on page 252. See also: About Web Installations on page 242 Setting Installation Options for a Web Installation An important part of setting up a Web installation is specifying the installation options that will be available to the end user at run time. To do so, use the Web Site UI tab, which appears on the details dialog box for Web sites and top-level virtual directories. If the virtual directory is under a Web site, then see Setting Installation Options for a Child Virtual Directory on page 250. You set options for each Web site or virtual directory you have added on the Web Files page. Setting installation options adds Web (IIS) dialog boxes to the installation. If you omit the procedure below, no Web dialog boxes appear to the end user, and the installation tries to apply the defaults for all items. Warning Do not edit the Web (IIS) dialog boxes, except to change their order (as a group) in the installation sequence. Editing the Web dialog boxes might cause unexpected, undesirable behavior, including damage to the installation. Also, any operation within this product that affects the installation’s user interface will regenerate the Web dialog boxes, therefore, any changes you make to them will be lost. To set installation options 1. Select Installation Expert > Web Files page. 2. In the lower-left list box, select a Web site or a top-level virtual directory and click Details. If you don’t see the item you want, make sure you have the correct feature selected in Current Feature. The details dialog box appears. 3. Click the Web Site UI tab. 4. To display installation dialog boxes to the end user at run time, mark Display RunTime UI. This adds Web dialog boxes to the installation. If this is a top-level virtual directory, no other options are available. Skip the remaining steps and click OK. If this is a Web site, the remaining options on the tab are enabled when you mark this check box. Windows Installer Editor Reference 249 Advanced Installations Note If the current installation was built in an older version of Windows Installer Editor, you are prompted to first convert the dialog boxes on the Dialogs page. Converting resets navigation and conditions, so if you customized the dialog boxes, back up this installation before converting. 5. 6. Complete the User Installation Options section: „ New Web Site Mark this to let end users install Web resources to a new Web site. However, even if you mark this, this will not be an available option if the operating system of the destination computer does not support the creation of new Web sites. Workstation operating systems prior to Vista do not support the creation of a new Web site. „ Existing Web Site Mark this to let end users install Web resources to an existing Web site. They will see a list of existing Web sites to choose from. „ Virtual Directory Mark this to let end users install Web resources to a virtual directory. If you select only this option, then this Web site will be installed as a virtual directory. „ Install as Virtual Directory on Workstation This applies only if the New Web Site option above is marked, and the installation is installed to an operating system whose IIS version does not support creation of a new Web site. This option ensures that end users can install to a virtual directory even if you did not mark it above. Otherwise, the installation will fail because it is trying to force a Web site to be created when the IIS version disallows it. Complete the New Web Site Prompts section. These options are enabled if you mark New Web Site above. Mark the items that the end user should be able to configure during installation. These items correspond to options on the properties dialog box in IIS. See About the Web Site Details Dialog on page 252. 7. Click OK. Note Clicking OK on the details dialog box regenerates the Web dialog boxes in the installation. See also: About Web Installations on page 242 Setting Installation Options for a Child Virtual Directory An important part of setting up a Web installation is specifying the installation options that will be available to the end user at run time. To do so, use the Virtual Directory UI tab, which appears on the details dialog box for child virtual directories. If the virtual directory is directly under Destination Computer, then see Setting Installation Options for a Web Installation on page 249. Windows Installer Editor Reference 250 Advanced Installations You set options for each Web site or virtual directory you added on the Web Files page. Setting installation options adds Web (IIS) dialog boxes to the installation. If you omit the procedure below, no Web dialog boxes appear to the end user, and the installation tries to apply the defaults for all items. Warning Do not edit the Web (IIS) dialog boxes, except to change their order (as a group) in the installation sequence. Editing the Web dialog boxes might cause unexpected, undesirable behavior, including damage to the installation. Also, any operation within this product that affects the installation’s user interface will regenerate the Web dialog boxes, therefore, any changes you make to them will be lost. To set installation options 1. Select Installation Expert > Web Files page. 2. In the lower-left list box, select a child virtual directory and click Details. If you don’t see the item you want, make sure you have the correct feature selected in Current Feature. The details dialog box appears. 3. Click the Virtual Directory UI tab. 4. To display installation dialog boxes to the end user at run time, mark Display RunTime UI. This adds Web dialog boxes to the installation. When you mark this check box, the remaining options on the tab are enabled. Note If the UI is unavailable for the parent Web site, then Web dialog boxes are not generated for this child virtual directory. Note If the current installation was built in an older version of Windows Installer Editor, you are prompted to first convert the dialog boxes on the Dialogs page. Converting resets navigation and conditions, so if you have customized the dialog boxes, back up this installation before converting. 5. Complete the tab: „ „ 6. Web Resources Location:  New Virtual Directory Mark this to let end users install Web resources in the named virtual directory to a new virtual directory.  Existing Virtual Directory Mark this to let end users choose to install Web resources to an existing virtual directory. They will see a list of existing virtual directories to choose from. Let End Users Rename Virtual Directory at Run Time Mark this to let end users enter a new name and parent directory for the virtual directory, other than the name you set by default on the Web Files page. Click OK. Windows Installer Editor Reference 251 Advanced Installations Note Clicking OK on the details dialog box regenerates the Web dialog boxes in the installation. See also: About Web Installations on page 242 About the Web Site Details Dialog If you select a directory, virtual directory, or Web site on the Web Dialogs page and click Details, a multi-tabbed Details dialog box appears. Most tabs on this dialog box correspond to those in Internet Services Manager in Microsoft Internet Information Server (IIS), version 5.0. For information on these tabs, see the IIS help. Tabs that do not appear in IIS Installation Settings Lets you override existing settings when installing over an existing Web site or virtual directory See Creating a Web Site on page 244 or Creating a Virtual Directory on page 246. Web Site UI (Web sites and top-level virtual directories) Lets you specify the installation options that will be available to the end user at run time See Setting Installation Options for a Web Installation on page 249. Virtual Directory UI (Child virtual directories only) Lets you specify the installation options that will be available to the end user at run time See Setting Installation Options for a Child Virtual Directory on page 250. ASP.NET Lets you specify the version of ASP.NET to register with IIS When the installation installs the Web site, it registers that version of ASP.NET with IIS for the Web site. It will register the highest available version of ASP.NET that matches the selected version. (Example: If you select version 2.0 and there are two versions of 2.0, it will register the highest version.) To specify a specific version, select User Specified from the drop-down list and enter the version. To pre-install the .NET Framework if it is not installed, use the Prerequisites page. See Adding Prerequisites to a Release on page 195. Options in Windows Installer Editor that are different from IIS z On the Web Site tab, you can specify only one identity for a Web site (consisting of an IP address, port, and host header), whereas in IIS you can specify multiple identities. Windows Installer Editor Reference 252 Advanced Installations z The Web Site tab lacks the Connections and Logging sections. z The Home Directory and Virtual Directory tabs lack the options to specify where the content should come from. z The Directory Security tab lacks the IIS options for IP address and domain name restrictions and Secure communications. The navigation of this tab is also different from IIS. z The HTTP Headers tab lacks the ability to edit content ratings. How options are set on the Web server When you install a Web site or virtual directory that already exists, you can control whether settings are changed on the Web server. Use the Override Existing Settings drop-down list on the Web site Details dialog box > Installation Settings tab. See also: About Web Installations on page 242 Installing Web Settings From a File You can let the end user run your Web installation on multiple computers and set the same settings on each one without having to step through the Web dialog boxes. Example: An end user, who operates a Web farm, wants to run your installation with the same Web site settings on 12 computers. This is accomplished by a Web settings XML file that is generated by the end user from a special command line. The end user can edit this XML file to set the Web installation options they want. When the end user runs the installation with another special command line, the Web installation settings are obtained from the XML file. The XML file can be created and used during the initial installation only. Using the command lines during a reinstall or uninstall does not work. Instead, the .MSI runs as it normally would for the reinstall or uninstall. About the Web settings XML file z The XML file is generated for a specific operating system type. If the end user creates the XML file on a server-class computer, those settings cannot be installed on a workstation, and vice versa. z The XML file is generated for a specific .MSI and should only be used with that .MSI. z The XML file is generated for a specific version of Windows Installer Editor and can only be used with that version. z The XML file contains the default Web site settings that you set in the installation. z If the installation contains a Web site, the XML file cannot be generated on a workstation that runs on an operating system earlier than Windows Vista. z End users should limit their editing to the sections in the XML file that are commented. These generally are settings that appear in the Web dialog boxes, that is, settings that appear on the Installation Settings, Web Site UI, and Virtual Directory tabs on the Web site details dialog box. Editing non-commented settings can cause the installation to fail or cause IIS to be configured improperly. We cannot provide technical support for such problems. Windows Installer Editor Reference 253 Advanced Installations To install Web settings from a file This procedure is performed by end users. If you will let your end users use this feature, you must provide them with this information. 1. Run the installation with the following command line: msiexec.exe /i "PathToMsi.msi" WISE_CONFIG_OUTPUT_PATH="PathToWebSettingsFile.xml" where PathToMsi.msi is the full path to the installation and PathToWebSettingsFile.xml is the full path to where the XML should be created. The default Web site settings are written to the XML file that is specified in the command line. The installation itself is not performed and a Setup Canceled dialog box appears. 2. Edit the XML file to set the desired options and then save the changes. Follow the guidelines at the beginning of the XML file. Only edit settings that are commented. 3. On the destination computer, run the installation with the following command line: msiexec.exe /i "PathToMsi.msi" WISE_CONFIG_INPUT_PATH="PathToWebSettingsFile.xml" where PathToMsi.msi is the full path to the installation and PathToWebSettingsFile.xml is the full path to the edited XML file. The installation uses information in the XML file to configure the Web settings. Web dialog boxes do not appear during installation. Configuring a Microsoft SQL Server During Installation Use the SQL Server Scripts page to create or configure Microsoft SQL Server databases. You might use this page if the application you are installing is a database application and depends on certain database content and configuration. This page eliminates the need to require end users to configure databases manually. On this page, you specify a connection string and SQL statements, which are executed during installation. Therefore, you have the ability to do any configuration that is possible with SQL statements. You can generate SQL statements in the following ways: z Type or paste SQL statements. z Import SQL statements from a file. z Specify a database to recreate, and the necessary SQL statements are generated automatically. To configure an installation to run a SQL script 1. Select Installation Expert > SQL Server Scripts page. See Tips for Using the SQL Server Scripts Page on page 255. 2. From Current Feature, select a feature or condition. (Because any item you add must be assigned to a specific feature, you cannot add an item when All Features is selected.) Windows Installer Editor Reference 254 Advanced Installations Items that you add to a feature are installed on the destination computer only if the feature is installed. Items that you add to a condition are installed only if the feature is installed and the condition is true. 3. Click Add at the right side of the page. The SQL Script Details dialog box appears. 4. Click the Connection tab and specify a name for the SQL script and a connection string that connects to the database the installation modifies. See Setting SQL Connection Strings on page 256. 5. Click the Statements tab and specify SQL statements to be executed on the destination computer. See Specifying SQL Statements on page 256. 6. Click the Replacement tab and specify text strings to be found and replaced within the SQL statements at install time. See Specifying Replacements in SQL Statements on page 258. 7. Click OK on the SQL Script Details dialog box. The script is added to the list on the SQL Server Scripts page. 8. The SQL scripts are executed in the order they appear on the SQL Server Scripts page. To rearrange the order, select a statement name and click Move Up or Move Down. For information on setting the required SQL Server version, see Setting a Requirement on the System Requirements Page on page 164. Tips for Using the SQL Server Scripts Page z Add the SQL Connection dialog box to an installation to create a valid connection string for a SQL Server located anywhere on the network of the destination computer. See About the SQL Connection Dialog on page 422. z Uninstall won’t roll back the changes performed by the SQL statements. z Databases are connected to and configured through the ODBC driver on the destination computer. z The SQL scripts you specify are saved to a file with the same name as the script name you specify, with the extension .SQL The file is added to the installation. This file appears on the Files page under a Temp directory. During installation, this file is installed, its statements are executed, and then it is deleted. Do not remove this file from the installation. z The SQL Server Scripts page does not provide error checking for valid SQL syntax or debugging for failed statements. Make sure the SQL code you enter is well-tested before deployment. If errors occur during installation, the end user will see SQL error messages. Note These tips assume familiarity with SQL Server statement syntax and debugging. Technical Support does not provide assistance with debugging SQL statements. Windows Installer Editor Reference 255 Advanced Installations See also: Configuring a Microsoft SQL Server During Installation on page 254 Setting SQL Connection Strings To set SQL connection strings 1. Click the Connection tab on the SQL Script Details dialog box. See Configuring a Microsoft SQL Server During Installation on page 254. 2. Complete the dialog box: „ Name A name for the SQL script is generated and displayed here. You can accept the default or enter a more descriptive name. If you later change this field, the script file is not renamed. A file with this name and the extension .SQL is added to the installation. „ Connection String Enter a connection string that connects to a specific Microsoft SQL Server and database. The default connection string works for most locally installed SQL Server databases. If you use the SQL Connection dialog box in this installation, enter the Windows Installer property WISE_SQL_CONN_STR enclosed in brackets. This property is populated with a valid connection string when the end user completes the SQL Connection dialog box and clicks Next. See About the SQL Connection Dialog on page 422. If your application connects to more than one SQL Server during installation, add a SQL Connection dialog box for each additional server, edit the additional dialog boxes, and use a different property for each connection string. See Editing Additional SQL Connection Dialogs on page 424. The database you specify here must be accessible through ODBC on the destination computer. If you have a database registered in ODBC on your own computer, you can click Browse to select it, and the connection string is generated. For this to work, the destination computer must have access to the same database. 3. Click OK. See also: Tips for Using the SQL Server Scripts Page on page 255 Specifying SQL Statements To specify SQL statements 1. Click the Statements tab on the SQL Script Details dialog box. See Configuring a Microsoft SQL Server During Installation on page 254. 2. To import a file containing SQL statements, click Import SQL File and specify a .SQL or .TXT file that contains SQL statements. Windows Installer Editor Reference 256 Advanced Installations The statements appear on the Statements tab, where you can edit them. If you later change the file on disk, you must re-import the file to include the changes in the installation. 3. To generate statements that recreate a database, click Recreate Database. The Recreate Database dialog box appears. 4. 5. Complete the dialog box: „ Connection String Specify a connection string to the Microsoft SQL Server and database. It must be accessible to your computer. If it is registered as an ODBC data source on your computer, click Browse to select it, and the connection string is generated. „ Database Name Enter a name for the database to be created on the destination computer. „ Import Data Rows Mark this to populate the database’s tables with all its current data. This is unavailable until you mark the Import Tables check box below. „ Import Views Mark this to import the defined views of the database. „ Import Procedures Mark this to import the defined procedures of the database. „ Import Tables Mark this to import blank tables from the database. This does not import the data (mark Import Data Rows to import data). You can import all tables, only certain tables, or all tables except certain tables. For the last two options, enter a list of table names delimited by commas. „ Refresh when installation is compiled Mark this to have the SQL statements regenerated from the actual database when you compile this installation. This causes the compile to take longer. Do not edit the SQL statements on the Statements tab, because they will be overwritten during compile. „ Remove this database first Mark this to delete this database, if it already exists on the SQL Server, before execution of the SQL statements. If this check box is cleared, and the database already exists, then any overlapping tables are overwritten on the destination computer, new tables are added, and non-overlapping tables are left as-is. This results in a composite database that is mixture of new and old. Click OK. Note Error checking or debugging is not available for statements that you type or import. Make sure the SQL code you enter is well-tested before deployment. If errors occur during installation, the end user will see SQL error messages. See also: Tips for Using the SQL Server Scripts Page on page 255 Windows Installer Editor Reference 257 Advanced Installations Specifying Replacements in SQL Statements You can specify text strings to be found and replaced within the SQL statements during installation. To specify replacements in SQL statements 1. Click the Replacement tab on the SQL Script Details dialog box. See Configuring a Microsoft SQL Server During Installation on page 254. 2. Click Add. The Add Replacement dialog box appears. 3. 4. Complete the dialog box: „ Text to Find Enter regular text or formatted text, such as a bracketed property name. If you enter formatted text, it is resolved before the find and replace takes place. Example: If you enter [INSTALLDIR], the find and replace searches for the value of INSTALLDIR. „ Replace With Enter regular text or formatted text, or select a current Windows Installer property from the drop-down list. If you enter formatted text, items are replaced with the value of the formatted text. This is useful for creating dynamic installations. Example: Suppose you are creating a new database on the server. Place an edit field on a dialog box asking for the new database name. The answer is stored in a property, which you could then use in this field, replacing the current database name. Click OK. Note Keep in mind that any matching string is replaced, so only replace strings you know to be unique. Example: If you replace “Red” with “Blue,” a “PreparedStatement” object in a SQL statement becomes “PrepaBlueStatement” and breaks the code. See also: Tips for Using the SQL Server Scripts Page on page 255 Importing .NET Framework Security Settings Use the .NET Framework Security page to import .NET Framework security settings from your computer into an installation for a .NET application that you are deploying using no-touch deployment. No-touch deployment lets system administrators deploy .NET desktop applications through a remote Web server without altering the end user’s registry or shared system components. Search for “No-Touch Deployment in the .NET Framework” in the MSDN Library (msdn.microsoft.com/library/). When an end user downloads your .NET application using no-touch deployment, they need specific security settings to be able to run the application. You import these security settings from your computer into the installation. When the application is downloaded, the settings you imported into the installation change the client’s security settings and enable the application to run. Windows Installer Editor Reference 258 Advanced Installations To be able to import security settings using the .NET Framework Security page, you must have the .NET Framework installed on your computer. You create and configure .NET Framework security settings using the Microsoft .NET Framework Configuration tool, which is in Administrative Tools in your computer’s Control Panel. The .NET Framework security settings consist of a hierarchy of code groups. When you import .NET Framework Security settings, you import one or more of these code groups. .NET Framework Security page Properties and values of the code group last selected in the upper-left pane. Code groups on your computer. Properties and values of the code group last selected in the lower-left pane. Code groups you have imported from your computer into the installation. To import .NET Framework security settings 1. Select Installation Expert > .NET Framework Security page. 2. From Current Feature, select a feature or condition. (Because any item you add must be assigned to a specific feature, you cannot add an item when All Features is selected.) Items that you add to a feature are installed on the destination computer only if the feature is installed. Items that you add to a condition are installed only if the feature is installed and the condition is true. 3. In the upper-left list box, navigate to and select the code group that contains the security settings. 4. Click Add Code Group to add the code group to the installation. The code group appears in bold type in the lower-left pane. If you import a child code group, any parent code groups also appear but are not in bold type. These parent code groups contain no security settings, but maintain the correct hierarchical structure for the code groups. To delete a .NET Framework security code group from the installation, select it in the lower-left list box and click Delete. If the code group has parent code groups that are Windows Installer Editor Reference 259 Advanced Installations not in bold type, they do not need to be deleted. They are removed when you exit the .NET Framework Security page. See also: About Microsoft .NET Technology on page 493 MTS/COM+ Page Use the MTS/COM+ page to add MTS or COM+ application packages to an installation. The MTS/COM+ page is intended for software developers who know the computer names of the servers that contain MTS or COM+ server applications. Both MTS (Microsoft Transaction Server) and COM+ are steps in the evolution of the Component Object Model (COM) technology. MTS, which was developed first, is a transaction processing system for developing, deploying, and managing server applications. MTS runs on Windows NT Server 4.0 or later. COM+, the next generation of COM technology, is shipped with and requires the Microsoft Windows operating system. It provides a standard that lets any two components communicate with each other regardless of what computer each is running on, the operating systems that are running, and the language in which the components are written. All computers can communicate through COM if they have support for DCOM (Distributed Component Object Model) installed. MTS or COM+ packages generally consist of server software and client software. When you add an MTS or COM+ package to an installation, you must designate it as either a server installation or a client installation. You cannot add both the server and client installation for a given MTS or COM+ application to the same feature. If you need to install both the server and client of the same application, either create two .MSI files, or put the server installation in one feature, and the client installation in another feature. If the MTS or COM+ application contains roles, those roles are not installed on destination computers. See also: Adding an MTS or COM+ Application on page 260 Adding an MTS or COM+ Application To add an MTS or COM+ application 1. Make sure that you have either MTS or COM+ on your computer, and that the MTS or COM+ server application is installed and configured on your computer exactly as it should be configured on the destination computer. Note (Optional) You can add the files that make up the MTS/COM+ application on the Files page. This lets you place the files in any directory structure. Otherwise, the files are placed in the Program Files\{GUID}\ directory. If you add the files yourself, you must mark the Use Existing Source Paths check box later in this procedure. 2. Select Installation Expert > MTS/COM+ page. Windows Installer Editor Reference 260 Advanced Installations 3. From Current Feature, select a feature or condition. (Because any item you add must be assigned to a specific feature, you cannot add an item when All Features is selected.) Items that you add to a feature are installed on the destination computer only if the feature is installed. Items that you add to a condition are installed only if the feature is installed and the condition is true. 4. Click Add at the right of the MTS/COM+ page. The MTS/COM+ Application Details dialog box appears. 5. 6. Complete the dialog box: „ Application Name Specify the MTS/COM+ application. You can only select from currently installed applications. „ GUID (Read-only.) This contains the GUID of the MTS/COM+ application that you select. „ Installation Type Select the installation type:  Client Installs the client portion of the MTS/COM+ application. This installation type requires a remote server name. In Remote Server Name, enter the name of the computer on the network that will contain the MTS/COM+ server application the client will connect to. If you design the installation so that the server name is placed into a property dynamically during the installation wizard dialog boxes, you can enter that property name here, surrounded by brackets.  Server Installs the server portion of the MTS/COM+ application. „ Refresh/Update Application on Compile Mark this to refresh the MTS/COM+ application from your computer's Component Services control panel each time you compile the installation. If you clear this check box, the MTS/COM+ application information is copied immediately to this installation and is not refreshed during compile. Example: You might use this option if you need to transfer the installation to a computer that does not have the same MTS/COM+ application installed. If it is set to refresh and the MTS/COM+ application is not found, an error occurs during compile. „ Use Existing Source Paths Use this option to prevent the MTS/COM+ files from being added to the default location on the Files page. This lets you place the files on the Files page in the directory you choose. You must add the files that make up the MTS/COM+ application to the Files page before marking this check box. Otherwise, you will get an error during compile. Click OK. The information you entered above is stored in the WiseComPlusApp and WiseComPlusComponent tables in the Windows Installer database. See also: Windows Installer Editor Reference 261 Advanced Installations MTS/COM+ Page on page 260 Windows Installer Editor Reference 262 Chapter 9 Translating an Installation This chapter includes the following topics: z About the Languages Page on page 263 z Defining and Translating Into Additional Languages on page 269 z Translating Text Strings You Have Added or Changed on page 275 z Resizing Dialog Controls After Translation on page 280 z About the Language Menu on page 281 z About the Language Strings Dialog on page 283 z Keeping Track of Changed Text Strings on page 283 z What Pre-Translated Languages Are Available? on page 284 z Language IDs on page 285 About the Languages Page You can translate the default dialog boxes in an installation into any language. Windows Installer Editor contains 25 pre-translated languages in addition to English. You can add any language that is not already pre-translated. The Languages page displays pre-translated languages. Pre-translated languages contain translations for all default text in the installation’s user interface elements. Examples: error messages; disk prompts; text and controls on dialog boxes; descriptions or names for launch conditions, features, or shortcuts; property values, file names, and directory names. Use the Languages page to: Translate an installation into one or more languages This translates the default text in the installation’s user interface elements. It does not translate your application or any user interface elements that you customize in the installation. See Creating a Translated .MSI on page 265. Define a new language Do this when the language you need is not one of the pre-translated languages. See Defining and Translating Into Additional Languages on page 269. Windows Installer Editor Reference 263 Translating an Installation Export text strings to a file that you can send to a translator Do this when you define a new language, or when you add or change any user interface elements in an installation. See Exporting Selected Text Strings to a File on page 276. Import translated text strings from a file to the installation See Importing All Text Strings After Translation on page 272 and Importing All Text Strings With the New Language Wizard on page 273. Translate customized user interface elements See Translating Text Strings You Have Added or Changed on page 275. Keep track of changed, exported, and imported strings See Keeping Track of Changed Text Strings on page 283. Columns on the Languages page The Languages page has two columns: z The Language Name column lists all available languages. To translate an installation, you mark the check box for one or more languages. This adds translated strings for that language to the installation. Translated installations are generated during compile. z When you mark the check box for a language, the Text Translated column displays Yes to indicate that the installation contains a translation for that language. All languages that show Yes in this column are listed on the Language menu. Options for compiling a translated installation z Compile to a separate .MSI file for the default language plus each language that is marked on the Languages page. See Creating a Translated .MSI on page 265. z Compile to a language transform (.MST). The compile creates an .MSI for the default language and a separate .MST for each language that is marked on the Languages page. At installation, the appropriate .MST must be applied to the .MSI to change the installation language. See Creating a Language Transform on page 266. When translations are not compiled When you mark a language check box, then clear it, the translation remains in the installation but no .MSI or .MST is created in that language during compile. This lets you omit a language from the compile without losing any translated text strings. This is especially important when you have added custom translated text. Additional translation options You can create a multiple-language installation that installs in the destination computer’s language or prompts the end user to select a language. See Outputting a Multiple-Language Release on page 184. A Share option makes it easy to translate several releases into the same language or set of languages, with the same language settings. See Sharing Language Settings Between Releases on page 267. Windows Installer Editor Reference 264 Translating an Installation Note The Languages page is unavailable for transforms. Edit languages in the base .MSI. Creating a Translated .MSI You can translate an installation to another language and have it compile to one or more .MSI files. A separate .MSI is created for the default language plus each language that is marked on the Languages page. z You can compile all languages into one installation file. See Outputting a Multiple-Language Release on page 184. z If you have customized any of the user interface elements of this installation, you must translate the changed text before translating the installation. See Translating Text Strings You Have Added or Changed on page 275. z If the language you need is not listed on the Languages page, you must define a new language and translate its text strings. See Defining and Translating Into Additional Languages on page 269. Note If the installation contains Web resources, adding or changing a language regenerates the Web dialog boxes in the installation. To create a translated .MSI 1. Select Installation Expert > Languages page. 2. From Current Release, select a release. 3. Mark the check box next to each language to translate this installation to. Some .MSI files might not have languages listed on the Languages page. In that case, you must use the .WSI that compiled the .MSI. Note If this installation was created in a previous version of Windows Installer Editor, but you did not update the path variables when you first opened the installation in the newer version, you will receive an error when you mark a language check box. To fix this, close the installation, reopen it, and click Yes in the prompt that asks you to update variables. The remaining steps are optional. 4. Double-click the marked language. The Language Details dialog box appears. 5. Complete the dialog box: „ Destination File Specify the full path for the translated .MSI; be sure to include the .MSI file extension. If you leave this field blank, this language is always compiled to an .MSI whose name is created by adding an underscore and the language name to the installation file name. Example: If you mark the check box for German and the Windows Installer Editor Reference 265 Translating an Installation installation file is named Sample, a file named Sample_German.msi is created during compile. If you specify an .MST file instead of an .MSI, this language is compiled to a language transform. See Creating a Language Transform on page 266. „ Codepage, Language ID Leave the defaults in these fields. You typically only change these fields when you define a new language. „ Default release language (.WSI files only.) Mark this to use this language as the default language for this release. During compile, the default release language overrides the Default language on the Language menu. Note Only one language per release can be the default release language. An error message lets you know if you mark this check box for a second language. See About the Default Release Language on page 282. 6. Click OK. 7. If needed, complete the Language Details dialog box for any other languages that are marked. Default text strings for the selected release are translated into the selected languages. You can share these language settings with other releases in this installation. See Sharing Language Settings Between Releases on page 267. Creating a Language Transform You can create one or more language transforms that change the language in the dialog boxes that appear during installation. The compile creates an .MSI for the default language and a separate .MST for each language that is marked on the Languages page. During installation, the appropriate .MST must be applied to the .MSI to change the installation language. See Applying a Transform to an Installation on page 342. z If you have customized any of the user interface elements of this installation, you must translate the changed text before translating the installation. See Translating Text Strings You Have Added or Changed on page 275. z If the language you need is not listed on the Languages page, you must define a new language and translate its text strings. See Defining and Translating Into Additional Languages on page 269. Note If the installation contains Web resources, adding or changing a language regenerates the Web dialog boxes in the installation. To create a language transform 1. Select Installation Expert > Languages page. Windows Installer Editor Reference 266 Translating an Installation 2. From Current Release, select a release. 3. Mark the check box next to each language to create a language transform for. Some .MSI files might not have languages listed on the Languages page. In that case, you must use the .WSI that compiled the .MSI. 4. Double-click the marked language. The Language Details dialog box appears. 5. In Destination File, specify the full path for the translated .MST; be sure to include the .MST file extension. If you specify an .MSI file instead of an .MST, this language is compiled to an installation database. See Creating a Translated .MSI on page 265. 6. Leave the defaults in Codepage and Language ID. You typically change these fields only when you define a new language. The Default release language check box is unavailable when you specify an .MST as the destination file. 7. Click OK. 8. If needed, complete the Language Details dialog box for any other languages you marked. Default text strings for the selected release are translated into the selected languages. You can share these language settings with other releases in this installation. See Sharing Language Settings Between Releases on page 267. Sharing Language Settings Between Releases You can translate several releases into the same language or languages, with the same settings you define in the Language Details dialog box. To do this, you share language settings between releases. After you initially share language settings, the settings for the releases are linked. This means that any change you make to the language settings for any of the linked releases is applied to all other linked releases. At any time, you can break the link. Breaking the link does not change the current settings for the releases. To share settings between releases 1. Translate the installation to another language. See Creating a Translated .MSI on page 265. 2. Select Installation Expert > Languages page. 3. From Current Release, select the release to copy settings to. 4. Click Share at the right of the page. The Share Release dialog box appears. 5. From Copy/Share Languages From, select the release that contains the settings to copy. 6. Click OK. The settings of the release in Copy/Share Languages From immediately replace the settings of the release in Current Release. Any change you make to the language Windows Installer Editor Reference 267 Translating an Installation settings of either of the linked releases is also applied to the other release, until you break the link. To break a link between releases 1. Select Installation Expert > Languages page. 2. From Current Release, select a release. 3. Click Share at the right of the page. The Share Release dialog box appears. 4. From Copy/Share Languages From, select . 5. Click OK. The link between the selected release and other releases is broken. The current settings of the releases are not changed, but changing settings for one release no longer affects the settings of the other release. Removing a Language from an Installation You can disable a language in an installation. This means the installation still contains the translated strings for the disabled language but the installation is not compiled to that language. You also can delete a language entirely from an installation. This means the language is removed from the Languages page and its translated strings are deleted from the installation. This is not recommended if you have added or changed text strings in a language, because the customized strings are lost. Note If the installation contains Web resources, adding or changing a language regenerates the Web dialog boxes in the installation. To disable a language in an installation 1. Select Installation Expert > Languages page and clear the check box next to the language to disable. The translated text strings for that language remain in the installation, but the installation is not translated to that language during compile. To compile the installation to that language again, simply mark its check box. In this way you can easily turn a language off and on. To delete a language entirely from an installation 1. Select Installation Expert > Languages page, click a language, and click Delete at the right of the page. The language is removed from the Languages page in the installation. Text strings for the deleted language are deleted from the installation, unless that language is selected in another release. The language will still be available in other installations if it is one of the pre-translated languages or if you added it to the installation template. Warning When you delete a language this way, all custom translated text strings in that language are lost. Windows Installer Editor Reference 268 Translating an Installation To restore a language that was deleted If you use the Delete button on the Languages page to delete a language and its text strings from an installation, you can later restore that language to the installation if you have a file containing translated text strings for that language. Add the language to the Languages page and import translated text strings. See Importing All Text Strings With the New Language Wizard on page 273. z To restore one of the pre-translated languages, select the appropriate resource file from the Languages subdirectory. To restore a language that you added and had translated, specify the resource or text file containing the translated text strings. The location of the Languages subdirectory varies. See Installation Resources and Their Locations on page 27. The language is restored to the Languages page. Note This process does not restore any custom translated text. Defining and Translating Into Additional Languages If the language you need is not one of the 25 pre-translated languages, you can add it to the Languages page and add translated text for that language. Then you can translate installations into the new language. Example: Suppose you want to translate an installation into Swiss French. However, that language is not one of the pre-translated languages. You can add Swiss French to the Languages page and add Swiss French text strings to the installation. Then, you can compile an installation that displays Swiss French on all dialog boxes and error messages. The new language and its translated strings are added to the current installation only. To make the new language available for future installations, add it to an installation template instead of to a specific installation. See Creating and Editing Installation Templates on page 47. Process for defining and translating into a new language 1. If you plan to customize or add new elements to the user interface of the installation, do so first. That way, the customized strings will be included when you export text strings for translation. 2. Add the new language to the list on the Languages page by defining language settings, then export the text strings in the installation to a resource or text file. See Defining a New Language and Exporting All Text for Translation on page 271. 3. Have the text strings translated to the new language. The translator should translate the strings in place in the same file, to ensure the returned file is formatted identically. Windows Installer Editor Reference 269 Translating an Installation Warning If you export the strings to a text file, make sure that the first two fields in the text file are not translated. These are the table and key names for the text strings and must remain intact. 4. Import the translated resource or text file. See Importing All Text Strings After Translation on page 272. Now you can compile the installation to the new language. See Creating a Translated .MSI on page 265 and Creating a Language Transform on page 266. After the initial translation, whenever you add or change text strings, you must have them translated if you want them in the new language. See Translating Text Strings You Have Added or Changed on page 275. About the New Language Wizard Use the New Language wizard to: z Define a new language on the Languages page. z Export text strings to a file that you can send to a translator. z Import translated text strings from a file to the installation. To use the New Language wizard 1. Select Installation Expert > Languages page. 2. Click Add at the right of the page. The Specify Language Details page appears. 3. Complete the page. The information you need to enter depends on what you plan to do; for details, see the topics listed in the next step. Then click Next. The Export/Import Text Strings for Language page appears. 4. Mark one of the following options: „ Export Export all text strings to a file for translation into this new language. This is the option most typically used. See Defining a New Language and Exporting All Text for Translation on page 271. „ Import Import a file containing translated text strings for this language. Do this if you already have translated text strings for this language. See Importing All Text Strings With the New Language Wizard on page 273. „ Windows Installer Editor Reference None Add a new language with text strings in the default language. Do this when you want to add a new language to the Languages page now and translate the strings later. 270 Translating an Installation 5. If you select None, click Finish to add the language to the Languages page and exit the wizard. If you select Export or Import, click Next. Additional pages appear; for details, see the topics listed in the preceding step. Defining a New Language and Exporting All Text for Translation If the language you need is not one of the 25 pre-translated languages, you can define the new language on the Languages page, then export strings from the installation. Later, you have the strings translated and import the translated strings. To define a new language and export all text for translation 1. Select Installation Expert > Languages page. 2. From Current Release, select a release. 3. Click Add at the right of the page. The New Language wizard appears with the Specify Language Details page. 4. Complete the page: „ Language Name Enter a name for the new language. „ Destination File (Optional.) Specify the full path for the translated installation file. You can create an .MSI or a transform (.MST). If you leave this field blank, this language is always compiled to an .MSI whose name is created by adding an underscore and the language name to the installation file name. Example: If the new language is named NewLanguage, and the installation file is named Sample, the translated installation is compiled to Sample_NewLanguage.msi. „ Codepage A code page ensures that the correct character set is used for the language you are adding. In most cases, it is best to specify 0, which is a language-neutral code page. If the language you are adding uses a multi-byte character set, then select the appropriate code page from the drop-down list. See Setting the Code Page of a Database in the Windows Installer SDK Help. „ Language ID Specify only one language ID for the language you are adding. Windows Installer supports only one language in this field. Language IDs are standardized. See Language IDs on page 285. „ Default release language (.WSI files only.) Mark this to use this language as the default language for this release. During compile, the default release language overrides the Default language on the Language menu. Note Only one language per release can be the default release language. An error message lets you know if you mark this check box for a second language. See About the Default Release Language on page 282. Windows Installer Editor Reference 271 Translating an Installation 5. Click Next. The Export/Import Text Strings for Language page appears. 6. If you have not had the strings translated, mark Export and click Next. The Export Default Strings page appears. 7. Complete the page: „ 8. Export As Select a file type for the text strings:  Resource File Exports the strings to a Visual C++ style resource file; this includes an .H (header) file. With a resource editor, you or the translator can resize dialog boxes appropriately for each language.  Text File Exports the strings to a standard text file, in which they are separated by tabs. „ File Name Specify the full path for the file to export text strings to. „ Export File and Directory Names Mark this to include the installation’s file and directory names in the export file. Click Finish. The text strings are exported to the file you specified, which you can send to a translator. When you receive the translated file from the translator, you import the text strings into the installation. See Importing All Text Strings After Translation. Importing All Text Strings After Translation Typically, while adding a new language to the Languages page, you export the text strings from the installation to a file and send them to a translator. After the text strings for the new language are translated, you must import them into the installation. In this procedure, you use the Language Strings dialog box to import translated text strings. This procedure assumes that you have added the new language to the Languages page, defined its settings, and exported text strings. See Defining a New Language and Exporting All Text for Translation on page 271. If you have not defined language settings for the new language, you can use the New Language wizard to define the language settings and import the text strings at the same time. See Importing All Text Strings With the New Language Wizard on page 273. Note In .TXT files, if tab characters for one or more text strings are added or deleted during translation, the text strings cannot be imported. To determine whether there are any text strings that are not imported and therefore not translated, go to the Language Strings dialog box and compare the entries in the Changed and Exported columns. They should match. See Keeping Track of Changed Text Strings on page 283. Windows Installer Editor Reference 272 Translating an Installation To import all text strings using the Language Strings dialog box 1. Select Installation Expert > Languages page. 2. From Current Release, select a release. 3. Click Strings at the right of the page. The Language Strings dialog box appears. 4. From Language, select the language for which you will replace all text strings. 5. At the bottom left of the Language Strings dialog box, click Import. The Import Language Strings dialog box appears. 6. In Translated Strings File, specify the name of the file that contains the translated text strings for the new language. 7. Make sure the Do not compare with current strings option is marked. You only need to compare strings when you import strings you add or change after you have imported all strings. 8. Click OK. The translated text strings are imported into the installation and you can translate the installation to the new language. See Creating a Translated .MSI on page 265 and Creating a Language Transform on page 266. Importing All Text Strings With the New Language Wizard You can use the New Language wizard to import text strings at the same time you define a new language on the Languages page. Do this only when you already have a file containing translated text strings for the language you are adding. Example: If you added the language Swiss French to a previous installation, and now you want to use it in a new installation, you can use the New Language wizard to import Swiss French translations to the new installation. Note A better way to make a new language available for multiple installations is to add it to an installation template instead of to a specific installation. See Creating and Editing Installation Templates on page 47. You might also use this process to restore a language that you deleted from the Languages page. You must have access to the original file that contains the translated text strings. This process does not restore any custom translated text. Typically, you do not have a translated text file at the time you define a new language. Instead, you use the New Language wizard to define a new language and export text strings to a file, you have the file translated, and you import the translated strings at a later time. See Defining and Translating Into Additional Languages on page 269. To import all text strings with the New Language wizard 1. Select Installation Expert > Languages page. 2. From Current Release, select a release. Windows Installer Editor Reference 273 Translating an Installation 3. Click Add at the right of the page. The New Language wizard appears with the Specify Language Details page. 4. Complete the page: „ Language Name Enter a name for the new language. „ Destination File (Optional.) Specify the full path for the translated installation file. You can create an .MSI or a transform (.MST). If you leave this field blank, this language is always compiled to an .MSI whose name is created by adding an underscore and the language name to the installation file name. Example: If the new language is named NewLanguage, and the installation file is named Sample, the translated installation is compiled to Sample_NewLanguage.msi. „ Codepage A code page ensures that the correct character set is used for the language you are adding. In most cases, it is best to specify 0, which is a language-neutral code page. If the language you are adding uses a multi-byte character set, then select the appropriate code page from the drop-down list. See Setting the Code Page of a Database in the Windows Installer SDK Help. „ Language ID Specify only one language ID for the language you are adding. Windows Installer supports only one language in this field. Language IDs are standardized. See Language IDs on page 285 or visit msdn.microsoft.com. „ Default release language (.WSI files only.) Mark this to use this language as the default language for this release. During compile, the default release language overrides the Default language on the Language menu. Note Only one language per release can be the default release language. An error message lets you know if you mark this check box for a second language. See About the Default Release Language on page 282. 5. Click Next. The Export/Import Text Strings page appears. 6. Mark Import and click Next. The Import Translated Text Strings page appears. 7. In Translated Strings File, specify the file containing the translated strings. 8. Click Finish. The translated text strings are imported into the installation and you can translate the installation to the new language. See Creating a Translated .MSI on page 265 and Creating a Language Transform on page 266. Windows Installer Editor Reference 274 Translating an Installation Translating Text Strings You Have Added or Changed When you add or change any user interface elements in an installation, you must translate those changes if you want them to appear in another language. Examples: error messages; disk prompts; text and controls on dialog boxes; descriptions or names for launch conditions, features, or shortcuts; property values, file names, and directory names. You have several options for finding out which strings need to be translated and getting the translated text into the installation: z If you change multiple strings and need to send them to a translator, export only the changed strings to a file. Send the file to a translator, then import the translated strings back into the installation. See Translating Text Strings by Exporting to a File on page 275. z If you make just a few small changes and you know the translations, you can edit the text directly. See Translating Text Directly Without Exporting It on page 278. z If you are adding an entire new language, you can export all text strings in the installation, have them translated, and then import the translated strings to the installation. See Defining and Translating Into Additional Languages on page 269. The translated text might require more space than the default language. (Example: Most languages require more space than English.) Therefore, you might need to resize dialog box controls to accommodate text expansion. See Resizing Dialog Controls After Translation on page 280. Note dialog box controls are shared across all languages, which means that a control you add to one language is added to all other languages as well. Similarly, a control you delete in one language is deleted in all other languages. However, you can add conditions to show or hide certain controls in certain languages. See Conditions for controls on dialog boxes on page 384. Also see UserLanguageID Property in the Windows Installer SDK Help. Translating Text Strings by Exporting to a File When you add or change any user interface elements in an installation, you must translate those changes if you want them to appear in another language. To do so, you export the new or changed text strings to a file, have them translated, then import the translated strings back into the installation. See Exporting Selected Text Strings to a File on page 276 and Importing Selected Text Strings From a File on page 277. Example: Suppose an installation is in English and Spanish. You decide to add a new dialog box to the installation wizard. You add the dialog box in the default language (in this case, English). That way, the dialog box is added to all languages in the installation (English and Spanish). However, because the Spanish text for the new dialog box does not exist, Windows Installer Editor Reference 275 Translating an Installation the new dialog box displays in English, even in the Spanish version of the installation. You must export all the text on the new dialog box to a file, have it translated to Spanish, and then import the Spanish version of the text back into the installation. z If you are translating the entire installation to a new language, you can export, translate, and import all text strings in the installation. See Defining and Translating Into Additional Languages on page 269. z If you make just a few small changes and you know the translations, you can edit the text directly. See Changing Text in Installation Expert and Setup Editor on page 279. z You can use the Language Strings dialog box on the Languages page to keep track of changed and exported text strings. See Keeping Track of Changed Text Strings on page 283. Exporting Selected Text Strings to a File Export selected text strings when you add or change text strings in an installation that is translated to another language. Example: When you add a custom dialog box, you must translate the text in that dialog box to all other languages used in the installation. To export selected text strings 1. Select Installation Expert > Languages page. 2. From Current Release, select a release. 3. Click Strings at the right of the page. The Language Strings dialog box appears. 4. From Language, select the language to export text strings for. The drop-down list shows those languages that have translated text strings in this installation; they are indicated by a Yes in the Text Translated column on the Languages page. 5. On the Language Strings dialog box, click Export. The Export Language Strings dialog box appears. 6. From Export As, select a file type for the text strings: „ Resource File Exports the dialog boxes and strings to a Visual C++ style resource file; this includes an .H (header) file. With a resource editor, you or the translator can resize dialog boxes appropriately for each language. „ Text File Exports the strings to a standard text file, in which fields are separated by tabs. Warning Make sure that the first two fields in the text file are not translated. These are the table and key names for the text strings and must remain intact. 7. In File Name, specify the full path for the file to export text strings to. 8. From Export Options, select which strings to export: „ Windows Installer Editor Reference New or changed strings since last export Export strings that were added or changed since you last exported text strings for translation. 276 Translating an Installation 9. „ New or changed strings in installation Export all strings that were added or changed in this installation. „ All strings in current language Export all the text strings in the language you selected from the Language drop-down list. „ All strings in default language Export the text strings in the default language for the .WSI. This is either the Default language on the Language menu or the default release language defined on the Language Details dialog box. To include the installation’s file and directory names in the export file, mark Export File and Directory Names. 10. Click OK. The text strings are exported to the file you specified, which you can send to a translator. When you receive the translated file from the translator, you import the text strings into the installation. See Importing Selected Text Strings From a File. Importing Selected Text Strings From a File When you add or change text strings in an installation that is translated to another language, you must export the changed text strings and have them translated. See Exporting Selected Text Strings to a File on page 276. When you receive translated text strings from the translator, you import them into the installation so that those text strings appear in the correct language in the compiled installation. To import selected text strings 1. Select Installation Expert > Languages page. 2. From Current Release, select a release. 3. Click Strings at the right of the page. The Language Strings dialog box appears. 4. From Language, select the language to import text strings for. 5. In the Language Strings dialog box, click Import. The Import Language Strings dialog box appears. 6. In Translated Strings File, specify the name of the file that contains the translated text strings. 7. If additional text changes might have been made since the text strings were exported, you can compare the strings in the installation to the strings in the original export file. If the strings don’t match, the corresponding translated strings are not imported. To enable the compare: 8. a. Mark Compare current strings with original strings. b. In Original Strings File, specify the name of the file you exported for translation. Click OK. Windows Installer Editor Reference 277 Translating an Installation The translated text strings are inserted into the installation. If you chose to compare the text strings during the import, an error message informs you when one or more text strings in the installation have been changed since the export. In that case, the translated strings that correspond to the changed strings are not imported. You should re-export the changed text strings for additional translation. Note In .TXT files, if tab characters for one or more text strings are added or deleted during translation, the text strings cannot be imported. To find out if there are any text strings that are not imported and therefore not translated, go to the Language Strings dialog box and compare the entries in the Changed and Exported columns. They should match. See Keeping Track of Changed Text Strings on page 283. Translating Text Directly Without Exporting It Typically, you export all text strings, file names, and directory names to a file to have them translated. Then you import the translations back into the installation. However, in some instances you might need to translate a small amount of text, such as a single dialog box control or a single file name. Rather than going through the process of exporting and importing changed text strings, you can make these changes yourself for each language. Example: Suppose you have translated an installation to German. Then you add a Cancel button to an existing dialog box. You already know the German translation for “Cancel” because other dialog boxes contain a Cancel button. In this case, you don’t need to export, translate, and import the changed string; you can change the text for the new Cancel button. You have the following options for translating changed text: z Translate specific text in the Language Strings dialog box. This lets you see at a glance the translation status of text strings in the installation. See Translating Text on the Language Strings Dialog. z Change specific text in Installation Expert and Setup Editor. See Changing Text in Installation Expert and Setup Editor on page 279. Both of the above procedures assume that you already have the translation for the changed text. z If you are adding an entire new language, you can export, translate, and import all text strings in the installation. See Defining and Translating Into Additional Languages on page 269. z If you change several strings and need to put them in a file for the translator, you can export, translate, and import only the strings you changed. See Translating Text Strings by Exporting to a File on page 275. Translating Text on the Language Strings Dialog In the Language Strings dialog box, you can change translated text for any of the selected languages. Do this when you have only a small amount of text to be changed and you know the translation for that text. Windows Installer Editor Reference 278 Translating an Installation If you need to translate larger amounts of text, export the text strings to a file. See Translating Text Strings by Exporting to a File on page 275. To translate a small amount of text 1. Select Installation Expert > Languages page. 2. From Current Release, select a release. 3. Click Strings at the right of the page. The Language Strings dialog box appears. 4. From Language, select a language. The Language Strings dialog box shows the text strings for that language. 5. In the Translated Text column, click the text to change and press Enter. 6. Enter new text or change the existing text. 7. Press Enter. You can observe the change in the corresponding table in the Tables tab in Setup Editor. Similarly, you can change text in the Tables tab or the Dialogs tab, then observe the change here in the Language Strings dialog box. See Changing Text in Installation Expert and Setup Editor. Changing Text in Installation Expert and Setup Editor You can change translated text for any of the selected languages in certain areas of Installation Expert and Setup Editor. Do this when you have only a small amount of text to be changed and you know the translation for that text. If you need to translate larger amounts of text, export the text strings to a file. See Translating Text Strings by Exporting to a File on page 275. To change translated text 1. From the Language menu, select a language. 2. Go to the table, dialog box, or Installation Expert page that contains the text string, file name, or directory name to edit. 3. Change the text. Note that the text is changed only for the language you selected from the Language menu. You can observe the change in the Language Strings dialog box. Similarly, you can change translated text in the Language Strings dialog box, then observe the change in Installation Expert or Setup Editor. See Translating Text on the Language Strings Dialog on page 278. Tables and columns that contain text strings you can translate You can edit the strings in Setup Editor > Tables tab, in other Setup Editor tabs, or in Installation Expert. Windows Installer Editor Reference 279 Translating an Installation Table Columns you can translate and edit ActionText Description, Template BBControl Text ComboBox Text Control Text, Help Dialog Title Directory DefaultDir DuplicateFile DestName Error Message Feature Title, Description File FileName LaunchCondition Description ListBox Text ListView Text Media DiskPrompt Property Value RadioButton Text, Help Shortcut Name, Description UIText Text WiseReleaseMediaDest DiskPrompt Resizing Dialog Controls After Translation Because some languages require more space than others, you might need to resize dialog box controls (examples: buttons and text boxes) to accommodate text expansion. To resize dialog box controls 1. From the Language menu, select a language. To resize dialog box controls across all languages, select the Default language. 2. Select Setup Editor > Dialogs tab. 3. Click the dialog box to change. 4. Select a dialog box control and resize it. See Types of Dialog Controls on page 407. Note dialog box controls are shared across all languages, which means that a control you add to one language is added to all other languages as well. Similarly, a control you delete in one language is deleted in all other languages. However, you can add conditions to show or hide certain controls in certain languages. Windows Installer Editor Reference 280 Translating an Installation See Conditions for controls on dialog boxes on page 384. Also see UserLanguageID Property in the Windows Installer SDK Help. About the Language Menu The Language menu lists all languages that have text translated in the installation. Use the Language menu to display translatable items in another language. Examples: error messages; disk prompts; text and controls on dialog boxes; descriptions or names for launch conditions, features, or shortcuts; property values, file names, and directory names. Example: Suppose you have translated an installation to German, and you want to resize buttons and text boxes on a dialog box to accommodate the longer German text. In Setup Editor, click the Dialogs tab and display a dialog box. Its text is in the default language. Now select Language menu > German. The dialog box is displayed in German, and you can resize dialog box controls as needed. When you add or change text in the installation’s user interface elements, make sure Language menu > Default is selected. That way, the items are added or changed for all languages. If you change the user interface while a different language is selected, the change is made for that language only. The Language menu does not affect the basic information in the installation, such as files added or dialog boxes selected. This means you cannot add files or select dialog boxes for a certain language in this manner. Any file you add in Installation Expert or any dialog box you select in the Dialogs tab in one language is added and selected for all languages in the overall installation. To add files or select dialog boxes for a certain language only, use features and the Release Settings page. See Customizing a Release on page 185. The default language is initially English, however, you can change it. You also can override the default language for a specific release by designating a default release language. See Changing the Default Language on page 281 and About the Default Release Language on page 282. Changing the Default Language The Default language that appears on the Language menu is initially English and is the same for all new installations. During compile, an .MSI is always created for the default language regardless of how many other languages are marked on the Languages page. When you translate an installation into one or more language transforms, the base .MSI is always compiled in the default language. The exception is when you define a default release language. See About the Default Release Language on page 282. You can change the default language for new installations by creating a new installation template. Although templates must be in .MSI format, you must start with a .WSI because you cannot specify the default language in an .MSI. To create a template with a different default language 1. Select File menu > New. Windows Installer Editor Reference 281 Translating an Installation The New Installation File dialog box appears. 2. In the Categories list, click Predefined Templates. 3. In the Templates/Tools list, click the Windows Application icon. 4. Mark Create .WSI or .WSM project file that can be compiled into an .MSI or .MSM and click OK. 5. Select Installation Expert > Languages page and mark the check box next to the language that should be the default. 6. Double-click the language name to display the Language Details dialog box. 7. Mark Default release language and click OK. 8. Click Compile. 9. In the Save As dialog box that appears, a. Navigate to the Templates subdirectory and enter a file name. The location of the Templates subdirectory varies. See Installation Resources and Their Locations on page 27. b. From Save as Type, select Installer Projects (*.wsi). c. Click Save. The .WSI is saved and then is compiled to an .MSI. Only .MSIs appear in the New Installation File dialog box as templates. To test the new template: 1. Select File menu > New. The New Installation File dialog box appears and the file you just created appears in the Custom Templates category. If the New Installation File dialog box does not contain the new template, check to make sure you saved the installation as an .MSI in the Templates directory. 2. Select the template you just created and click OK. 3. Check that the default language has been changed: „ The Default language should be the only one listed on the Language menu. „ In Installation Expert > Dialogs page, display any dialog box. The dialog box should appear in the new default language rather than in English. You can use this template to create installations in which the default language is the one you selected. About the Default Release Language The default release language is defined for a specific installation. It overrides the Default language on the Language menu during compile. Example: Suppose you’re creating an installation named Sample and you only want to create one .MSI, in German. Mark the Default release language check box on the Language Details dialog box for German. When you compile, Sample.msi will be in German. If you don’t mark the check box, the compile will create two files: Sample.msi, which is in the default language, and Sample_German.msi. Windows Installer Editor Reference 282 Translating an Installation You can also use the default release language to change the language of a base .MSI, against which you will apply other language transforms. Example: Suppose you create an installation named Sample2. On the Languages page, you mark the check box for German and, on the Language Details dialog box for German, you mark the Default release language check box. Then, back on the Languages page, you mark the check box for Spanish. On the Language Details dialog box for Spanish, you enter Sample2_Spanish.mst as the Destination File. When you compile, the following files result: Sample2.msi, which is in German, and Sample2_Spanish.mst, which is a Spanish language transform. The Default release language check box is on the Language Details dialog box and the Specify Language Details page of the New Language wizard. It appears in .WSI files only. Note Only one language per release can be the default release language. About the Language Strings Dialog The Language Strings dialog box, which appears when you click the Strings button at the right of the Installation Expert > Languages page, displays all translated and default text strings side by side. Use the Language Strings dialog box to translate strings and keep track of changed text strings. Columns on the Language Strings dialog box Translated text Lists all text strings in the selected language Default Text Lists all text strings in the default language Table Indicates the table in the database that contains the string Key Shows the key to the table Column Indicates which column of the table is translated Changed Yes indicates that a text string has been added or changed See Keeping Track of Changed Text Strings on page 283. Exported Yes indicates that a text string has been exported See Keeping Track of Changed Text Strings. See also: Exporting Selected Text Strings to a File on page 276 Importing All Text Strings After Translation on page 272 Importing Selected Text Strings From a File on page 277 Translating Text on the Language Strings Dialog on page 278 Keeping Track of Changed Text Strings Two columns in the Language Strings dialog box help you keep track of changed, exported, and imported strings: the Changed column and the Exported column. Both columns should contain No when you are ready to compile a translated installation. Windows Installer Editor Reference 283 Translating an Installation When you do this the Changed column contains and the Exported column contains Add or change a text string Yes No Export strings Yes Yes Import strings No No The same stages apply when you add or change files or directories, if you export file and directory names for translation. If you do not export file and directory names, then the entry in the Changed column remains Yes. If the Changed column still reads Yes after you have imported text strings, one of two things happened: z Formatting for the corresponding text string in the resource or text file was changed. (Example: This can happen if a tab in a text file was deleted or moved.) Try to reformat the resource or text file and then import it again. z When you imported, you chose to compare current strings with original strings, and you have made changes to the strings in the interim. In this case, export changed text strings again. Translate the strings that have changed, then import them. What Pre-Translated Languages Are Available? Pre-translated text strings let you instantly translate an installation into the following languages: Chinese (PRC) Chinese (Taiwan) Czech Danish Dutch (Netherlands) Finnish French French (Canadian) German Greek Hindi Hungarian Indonesian Italian Japanese Korean Norwegian Polish Portuguese Portuguese (Brazil) Romanian Russian Spanish Spanish (Basque) Spanish (Catalan) Swedish Windows Installer Editor Reference 284 Translating an Installation Thai Turkish If the language you need is not listed here, you can send the installation text strings to a translator and then add the new language and the translated strings to the Languages page. See Defining and Translating Into Additional Languages on page 269. The default language for all installations is English, unless you change it. See Changing the Default Language on page 281. Language IDs Windows Installer uses language IDs to determine whether the destination computer supports the language that is used for the installation dialog boxes. Example: If you create an installation with the language ID for Greek, that installation only runs on a computer with Greek fonts. Language IDs and Locale Codes for Common Languages For additional language codes, search for “locale ID chart” in the MSDN Library (msdn.microsoft.com/library). Language Sublanguage Language ID (decimal notation) ANSI codepage Languageneutral 0 Process or User Default Language 1024 Czech 1029 1250 Danish Danish 1030 1252 Dutch Belgian (Flemish) 2067 1252 Dutch Dutch (Standard) 1043 1252 English American 1033 1252 English Australian 3081 1252 English British 2057 1252 English Canadian 4105 1252 English Ireland 6153 1252 English New Zealand 5129 1252 Finnish Finnish 1035 1252 French Belgian 2060 1252 French Canadian 3084 1252 French French (Standard) 1036 1252 Windows Installer Editor Reference 285 Translating an Installation Language Sublanguage Language ID (decimal notation) ANSI codepage French Swiss 4108 1252 German Austrian 3079 1252 German German (Standard) 1031 1252 German Swiss 2055 1252 Greek 1032 1253 Hindi 1081 0 Hungarian 1038 1250 Icelandic Icelandic 1039 1252 Italian Italian (Standard) 1040 1252 Italian Swiss 2064 1252 Norwegian Norwegian (Bokmal) 1044 1252 Norwegian Norwegian (Nynorsk) 2068 1252 1045 1250 Polish Portuguese Portuguese (Brazilian) 1046 1252 Portuguese Portuguese (Standard) 2070 1252 Romanian 1048 1250 Russian 1049 1251 Slovak 1051 1250 Spanish Mexican 2058 1252 Spanish Spain (Modern Sort) 3082 1252 Spanish Spain (Standard/Traditional Sort) 1034 1252 Swedish Swedish 1053 1252 Thai 1054 874 Turkish 1055 1254 Windows Installer Editor Reference 286 Chapter 10 Distributing an Installation This chapter includes the following topics: z Package Distribution on page 287 z WiseUpdate on page 287 Package Distribution When you complete and compile an installation, you can use Package Distribution to share or deploy it by: z Copying a Package to the Share Point Directory z Copying a Package to a Network Directory z Copying a Compiled Installation to an FTP Server z Performing an Administrative Installation of a Windows Installer Package. z Distributing to Altiris Software Delivery Solution z Distributing a Package to IBM Tivoli z Distributing a Package to LANDesk Management Suite z Moving a Package into Microsoft Active Directory z Preparing a Package for Microsoft SMS Deployment z Moving an .MSI Into Novadigm Radia z Moving an .MSI Into NetInstall z Moving an .MSI Into Novell ZENworks z Passing an .MSI Into ON Command CCM For details, see these topics in the Wise Package Studio Help. WiseUpdate WiseUpdate® offers an easy method for updating your application on your end users’ computers, ensuring that end users are always working with the most current version of your application. Based on settings you specify on the WiseUpdate page, WiseUpdate installs a small client application (WiseUpdt.exe) along with your application. You can place a shortcut to this application in the end user’s Startup group so that it checks for updates when the destination computer is started or an end user logs on to Windows. WiseUpdate Client checks for newer versions of your application at the Web location you specified. If it finds a new installation, it downloads and runs it. WiseUpdate, by itself, does not deploy the current version of your application; it simply adds a Web-based update mechanism to your end users’ computers. The first time you configure WiseUpdate, you enable that version to check for later versions over the Windows Installer Editor Reference 287 Distributing an Installation Internet. Once WiseUpdate is integrated into your application, it simplifies the upgrade process for you and your end users for future updates to your application. See Configuring the WiseUpdate Page on page 290. When WiseUpdate runs on the destination computer, the end user can change proxy server information or the check interval by clicking the Advanced button on the first page of the wizard. You can customize the wizard dialog boxes that appear during WiseUpdate. See Customizing the WiseUpdate Dialog Boxes on page 293. See also: The WiseUpdate Process on page 289 Using WiseUpdate in an Installation on page 290 Options for Running WiseUpdate Client on page 295 WiseUpdate Tips on page 296 Troubleshooting WiseUpdate on page 297 Windows Installer Editor Reference 288 Distributing an Installation The WiseUpdate Process Phase 1: Your Computer When you first use WiseUpdate, you: 1. Develop the installation 2. Configure WiseUpdate and specify: „ Location of updates on the Web server „ Current version of the application (FTP) 3. Upload to the Web server: „ WiseUpdate update file „ Installation files and Readme Phase 2: Your Web Server (FTP/HTTP): z Contains the WiseUpdate update file that stores: „ The current version number „ URLs to the installation files z Contains the installation files and Readme Destination Computer The end user: 1. Obtains your application through normal distribution channels 2. Installs your application: „ WiseUpdate Client is copied to the application directory „ A shortcut to WiseUpdate client is placed on the destination computer Phase 3: Your Computer When you update your application to a new version, you: 1. Develop an upgrade or patch 2. Configure WiseUpdate and specify: „ Same Web location as the original „ New version of the application Phase 4: (FTP) 3. Upload to the Web server: „ WiseUpdate update file „ Installation files and Readme Destination Computer Your Web Server (FTP/HTTP): z Contains the WiseUpdate update file that stores: „ The new version number „ URLs to the new installation files z Contains the new installation files and Readme Your Web Server (FTP/HTTP) (HTTP) When WiseUpdate Client is run on the destination computer, it: z Runs an upgrade wizard z Reads the WiseUpdate update file on the Web server z Determines that a new version exists z Displays the Readme z Downloads and runs new installation files z Updates the local version See also: WiseUpdate Windows Installer Editor Reference 289 Distributing an Installation Using WiseUpdate in an Installation To use WiseUpdate® effectively, you must use it in two or more successive versions of your application. Using it in one version of your application only enables that version to check for later versions over the Internet. Note To avoid web connection errors when you use WiseUpdate with IIS 6.0 or later, you must add a MIME type to the IIS server for each type of file that you let users download from the Internet. Process for using WiseUpdate effectively 1. Select Installation Expert > WiseUpdate page. 2. Mark Include WiseUpdate Client. This causes WiseUpdate Client, a small executable file (WiseUpdt.exe), to be included in the installation and installed on the destination computer in the main application directory along with your application. 3. Configure the WiseUpdate page. See Configuring the WiseUpdate Page on page 290. 4. When the installation is tested and ready for distribution, upload the installation files, the Readme file, and the update file to a Web server. See Uploading WiseUpdate Files With an FTP Client on page 294. Warning If you do not upload the files before deploying your application to end users, an error occurs when they check for upgrades. 5. Test the WiseUpdate process. See Testing WiseUpdate on page 294. 6. Distribute your application using your usual method. Examples: CD or WebDeploy. 7. The next time you update your application, do the following: a. Format it as an upgrade or a patch. b. Update the Version field on the Product Details page, otherwise the maintenance mode will be entered. c. Upload the updated installation files to the Web server. After you upload the updated application, end users who have WiseUpdate will be prompted to update their application over the Internet. See also: WiseUpdate Configuring the WiseUpdate Page Completing the WiseUpdate page causes the WiseUpdate Client to be installed in the application directory on the destination computer along with your application. Most of the fields on this page specify information to be embedded inside WiseUpdate Client. Windows Installer Editor Reference 290 Distributing an Installation This information tells the client when, how, and where to check the Web location for new versions. The first time you configure WiseUpdate, you enable that version to check for later versions over the Internet. To enable the Internet updating capability, you must use WiseUpdate for each successive version of your application. To configure the WiseUpdate page 1. Select Installation Expert > WiseUpdate page. 2. Mark Include WiseUpdate Client. 3. Complete the page: „ Host Address Enter the Web server address where you plan to store updated installation files. (Example: www.company.com.) You can also enter the server’s IP address. Note The Web location you select should be accessible through both the FTP and the HTTP protocols—you typically use FTP to transfer files to it, and end users use HTTP (WiseUpdate Client) to read and download files from it. See WiseUpdate Tips on page 296. „ Host Username If necessary, enter the user name that’s required to connect to the host address. Typically, Web servers don’t require user names and passwords. This is used for basic HTTP authentication. „ Host Password If necessary, enter the password that’s required to connect to the host address. Enter this only if the Host Username is entered above. „ Host Directory Enter the directory on the Web server where you plan to store updated installation files, including the WiseUpdate update file. To put the files in the root directory of the host, leave this blank. If you are working in an update, the directory must be the same as in the original version of the installation. „ Update Filename Enter a name for the WiseUpdate update file and use the extension .INI. (Example: WiseUpdate.ini.) This file is created during compile. In subsequent versions of this installation, the file name must be the same as in the original version of the installation. See About the WiseUpdate Update File on page 292. „ Product Version Enter the current version of the installation. This version is stored with your application on the destination computer and is compared to the version stored in the update file on the Web server. „ Check Interval (days) Enter the frequency at which to remind the end user to check for updates. This works in conjunction with the Add client to StartUp group check box below. Windows Installer Editor Reference 291 Distributing an Installation If you place the WiseUpdate shortcut in the StartUp group on the destination computer, WiseUpdate Client runs when the destination computer is started or the end user logs on to Windows. If the check interval has been reached, WiseUpdate Client runs normally, prompting the end user to check for updates. If the check interval has not been reached, WiseUpdate Client runs silently and quits. „ Alternate Web Page Enter a URL to direct the end user to if WiseUpdate Client cannot check for updates or download the installation files. You might direct the end user to a Web page that contains technical support information, upgrade information, or a discussion of possible problems. „ Start Menu Icon This is enabled when you mark the Add client to StartUp group check box below. Enter a name for a shortcut to be created in the Startup group of the destination computer’s Windows Start menu. This name cannot contain special characters such as /, :, *, or ?. „ Add client to StartUp group Mark this to have the installation add a shortcut for WiseUpdate Client to the Startup group of the Windows Start menu on the destination computer. Then, when the destination computer is started or the end user logs on to Windows, the shortcut runs WiseUpdate Client according to the Check Interval (days) setting described above. If you do not mark this check box, then WiseUpdate Client will never run on the end user’s computer unless you code your application to run it. „ Only display UI if there is an update to install Mark this to run the update check silently and prompt the user only when an update is available. If you leave this blank, the end user is prompted every time an update check occurs. „ Keep a log of WiseUpdate checks Mark this to create a log of all update attempts on the destination computer. The log file is created in the application’s installation directory, using the name that you specify in Log Filename. See also: Using WiseUpdate in an Installation on page 290 Options for Running WiseUpdate Client on page 295 Customizing the WiseUpdate Dialog Boxes on page 293 About the WiseUpdate Update File On the WiseUpdate page, you enter a name for the WiseUpdate update file, which is created during compile. Later, the update file is uploaded to a Web server. When WiseUpdate Client runs on the destination computer, it reads the update file to determine if a new version exists, and if so, where to find the new version and its Readme. The update file is in .INI format and contains information you enter on the WiseUpdate page. It is formatted as follows: [WiseUpdate] Version=2.0 Windows Installer Editor Reference 292 Distributing an Installation Size=1095391 Install=http://www.company.com/updates/Application.exe ReadMe=http://www.company.com/updates/Readme.rtf where: z Version is the version of installation that is available on the server. z Size is the size of the installation in bytes. z Install is the URL to the installation. z ReadMe is the URL to the installation’s Readme file. If there is no Readme file, the Readme line is omitted. See also: Using WiseUpdate in an Installation on page 290 Customizing the WiseUpdate Dialog Boxes You can customize the dialog boxes that appear during a WiseUpdate. You might want to customize the dialog boxes for the following reasons: z To add your organization’s logo to the dialog boxes. z To change some of the text on the dialog boxes. z To change the text on the dialog boxes in another language. When you add WiseUpdate support to an installation, the merge module WiseUpdate.msm is added to the installation on the Merge Modules page. That merge module contains a WiseScript named WiseUpdt.exe, which contains the WiseUpdate dialog boxes. To customize the WiseUpdate dialog boxes 1. In Windows Explorer, go to the following directory: Program Files\Altiris\Wise Package Studio\Windows Installer Editor\WiseUpdt 2. Right-click WiseUpdt.wse, select Properties, uncheck Read-only, and click OK. 3. In WiseScript Editor or WiseScript Package Editor, open WiseUpdt.wse. 4. (WiseScript Package Editor only) To edit text in a language other than English, add support for that language. When you are on the Languages page, be sure to check Copy Default. See Processes for Adding Language Support in the WiseScript Package Editor or WiseScript Editor documentation. 5. To edit text in English or to make other changes, edit the dialog boxes as needed. See Editing Dialog Boxes in the WiseScript Package Editor or WiseScript Editor documentation. 6. Compile the WiseScript to an .EXE and place it in the same directory as the .WSE. You must use the default name, WiseUpdt.wse, and overwrite the existing file. 7. In Windows Installer Editor, open WiseUpdt.msm from the following directory: Program Files\Altiris\Wise Package Studio\Windows Installer Editor\WiseUpdt Windows Installer Editor Reference 293 Distributing an Installation If the prompt about the Windows Installer SDK merge module naming convention appears, click No. 8. In Installation Expert, on the Files page, delete WiseUpt.exe from the INSTALLDIR directory and add the one that you just edited. 9. Compile WiseUpdt.msm. 10. In Windows Installer Editor, open your WiseUpdate installation project (WSI). 11. In Installation Expert, on the Merge Modules page, delete the WiseUpdate merge module and then add the one that you just edited. 12. Compile your WiseUpdate installation. Uploading WiseUpdate Files With an FTP Client Use an FTP client to upload the following items to the Host Address and Host Directory you specified on the WiseUpdate page: z The compiled installation file or files. z An optional Readme file. z The WiseUpdate update file, which specifies the current version of the application, the URL to the installation files, and the URL to the Readme. See About the WiseUpdate Update File on page 292. You can place the installation files and Readme at any Web location, provided their URLs are recorded correctly in the WiseUpdate update file. When you enter the URLs in the FTP client, make sure they match the case of the actual path on the Web server. Some HTTP servers are case-sensitive and display errors if the case does not match exactly. Using WiseUpdate in an Installation on page 290. Testing WiseUpdate After you configure the WiseUpdate page and upload files to the FTP server, you should test the WiseUpdate process. To test how WiseUpdate works when an update is not needed In this test, the end user’s version of your application matches the version on the Web server. 1. Install the first version of your application on a testing computer (not your development computer). 2. On the testing computer, open your application’s installation directory and doubleclick the file WiseUpdt.exe. Normally, this file is run automatically at prescribed intervals at startup, but for testing purposes, you run the .EXE directly. WiseUpdate Client opens, customized with your application’s name. 3. Click Next. WiseUpdate Client uses the HTTP connection information that you specified on the WiseUpdate page to read the WiseUpdate update file on the Web server. If you are Windows Installer Editor Reference 294 Distributing an Installation running the same version of your application as that on the server, a message notifies you that you are running the latest version. 4. Close the WiseUpdate Client window. 5. If this test is not successful, try to determine the problem. See WiseUpdate Tips on page 296 and Troubleshooting WiseUpdate on page 297. 6. If this test is successful, follow the next procedure to test what happens when the version of your application on the Web server is later than the end user’s version. To test how WiseUpdate works when an update is needed 1. 2. To make the application on the server appear to be a later version: a. On your development computer, on the WiseUpdate page, enter a later product version. (Example: If the original version was 1.0.0, enter 1.0.2.) b. Compile the installation to create a new update file. c. Upload the new update file to the Web server. On the testing computer, open your application’s installation directory and doubleclick the file WiseUpdt.exe. Then click Next. Because the version on the Web server is now later than the version on the testing computer, WiseUpdate Client displays the Readme file and then displays an option to download and run the installation. 3. You can download and run the installation, but installation will fail unless the version on the server is an upgrade or patch that updates the currently installed version. In a real-life scenario, when you put updates on the server, they must be configured as upgrades or patches. 4. To restore the correct version information to the server, repeat step 1, except enter the original product version. 5. If this test is not successful, try to determine the problem. See WiseUpdate Tips on page 296 and Troubleshooting WiseUpdate on page 297. 6. If you see the Web page you entered in the Alternate Web Page field on the WiseUpdate page, then there was a problem connecting to the host through HTTP, or the necessary files were not found on the host. See also: Using WiseUpdate in an Installation on page 290 Options for Running WiseUpdate Client Options on the WiseUpdate page determine how WiseUpdate Client (WiseUpdt.exe) is run on the destination computer. Run from a shortcut on the destination computer z On the WiseUpdate page, mark the Add client to Startup group check box and enter a value in the Check Interval (days) field. z The installation adds a shortcut for WiseUpdate Client to the Startup group of the Windows Start menu on the destination computer. Windows Installer Editor Reference 295 Distributing an Installation z When the destination computer is started or the end user logs on to Windows, WiseUpdate Client silently checks the time elapsed since it last ran. If the number of days elapsed is greater than the check interval value, WiseUpdate Client prompts the end user to check for updates. Run from your application z On the WiseUpdate page, clear the Add client to Startup group check box. Entering a value in the Check Interval (days) field is optional. z Code your application to open the file WiseUpdt.exe from the application directory, in either of the following ways: „ Run WiseUpdate Client when the application is run. To use the check interval value from the WiseUpdate page, run WiseUpdate Client with the /c command-line option. Then WiseUpdate Client silently checks the time elapsed since it last ran. If the number of days elapsed is greater than the check interval value, WiseUpdate Client prompts the end user to check for updates. „ Add a menu command in your application to run WiseUpdate Client. Run silently You can use this option with either of the options above. z On the WiseUpdate page, mark the Only display UI if there is an update to install check box. z On the destination computer, WiseUpdate Client silently checks the time elapsed since it last ran. If the appropriate amount of time has elapsed, WiseUpdate Client silently checks for updates. If an update is available, WiseUpdate prompts the end user to download the update. See also: WiseUpdate WiseUpdate Tips Can WiseUpdate be used with WebDeploy? Yes. Make sure that update installations you release are formatted as upgrades (use the Upgrades page). You cannot use WebDeploy to run patch files (.MSP). WebDeploy embeds connection information into the .EXE of the .MSI/.EXE pair, so that the .EXE can run the .MSI from a location on the Web. WiseUpdate provides for regular checking for updates that are performed by the application on the destination computer. If you plan to put all compiled files in the same location on the Web, then specify the same directory on both the WebDeploy and WiseUpdate pages. Because the .EXE of an .MSI/.EXE pair might contain optional runtimes (examples: Windows Installer or .NET runtimes), WiseUpdate always tries to open the .EXE, not the .MSI. Follow these guidelines: z The .EXE of the .MSI/.EXE pair must be located somewhere on the Web and must be accessible to WiseUpdate users. It cannot be distributed through email or other mechanisms. Windows Installer Editor Reference 296 Distributing an Installation z On the WiseUpdate page, the connection information you enter must point to the location of the WiseUpdate update file on the Web server. See Creating Web-Based Installations With WebDeploy on page 201. Does WiseUpdate work if the Web location of the WiseUpdate update file changes? No. Once you start using WiseUpdate, all subsequent versions of the WiseUpdate update file must be located in the same directory as the original. This is because the WiseUpdate Client that’s already on end users’ computers only knows to look at the Web location you set when you originally configured it. Therefore, when you configure the WiseUpdate page for subsequent versions of the same application, make sure that the Host fields and the Update Filename field are the same as in the original version of the installation. Why are there two different fields that accept the product version? During the WiseUpdate process, you encounter two different fields that require a product version. How are these fields related? z The Version field on the Product Details page sets the version for the application, and is used by Windows Installer to determine whether updates and patches are valid upgrades for the installed version. z The Product Version field on the WiseUpdate page sets the version in the registry of the destination computer, which WiseUpdate Client checks against the update file on the FTP server. It also sets the version that is stored in the WiseUpdate update file. Typically, both fields should have the same version number, but you can change the versions to force upgrades. See also: WiseUpdate Troubleshooting WiseUpdate Troubleshooting WiseUpdate If you encounter problems with WiseUpdate during testing or after deploying your application, check the following suggestions. z Use an FTP client to observe what files are the on the Web server and where they are located. Open the WiseUpdate update file that is located on the Web server and see if the referenced paths are valid. z WiseUpdate Client uses HTTP to connect to the Web server specified on the WiseUpdate page. You typically use the FTP protocol to upload the installation .EXE, an optional Readme file, and a WiseUpdate update file. Both operations access the same location on the same server. Therefore, both protocols must have access to the directory, and the host must be able to process both HTTP and FTP requests. Also, the Host Directory, the Host Username, and the Host Password might be different for using the FTP protocol than for using the HTTP protocol. This is because the Web server and the FTP server might have different alias and user information, but point to the same directory. z Updates for Windows Installer installations must be in the form of an upgrade or patch. If the end user has version 1.0.0 of your application installed, and you make Windows Installer Editor Reference 297 Distributing an Installation some changes to it and upload it with a new version number, the WiseUpdate upgrade will fail unless you configured the updated package as an upgrade (using the Upgrades page) or a patch (using Patch Creation). z If end users cannot view the Readme file in WiseUpdate Client, make sure the Readme file does not have embedded graphics, which are not supported. See also: WiseUpdate Tips WiseUpdate Windows Installer Editor Reference 298 Chapter 11 Upgrading Applications This chapter includes the following topics: z About Upgrading Applications on page 299 z Preparing for Software Updates on page 299 z UpgradeSync on page 302 z Patch Creation on page 302 z Upgrades on page 302 About Upgrading Applications Windows Installer provides two main methods for upgrading installations: patching and upgrading. You can also have the end user upgrade by uninstalling and then reinstalling, although this method is not recommended. You can create upgrades for installations using the Upgrades page. Patching and the UpgradeSync tool are covered in the Wise Package Studio Help. For information on upgrading, see the following topics in the Windows Installer SDK Help. Patching and Upgrades Preparing an Application for Future Major Upgrades Small Updates Minor Upgrades Major Upgrades UpgradeCode Property Patching Changing the Product Code Preparing for Software Updates Preparing for updates starts when you ship the first version of your application. Use the following steps to prepare for a software update: 1. Archive the Shipping Version of the .MSI on page 299. 2. Determine the Form of the Update on page 300. 3. Determine the Product Code and Product Version on page 301. 4. Check the Installation With UpgradeSync on page 301. Archive the Shipping Version of the .MSI This is the first step in preparing for an update. Windows Installer Editor Reference 299 Upgrading Applications Planning for the next software update should start when you ship the first version of your application. To create an update, you must have access to previous versions of the installation. Always archive the shipping installation in a place that is accessible. Even if you compile and ship the installation as an .EXE, archive the .MSI, which is created alongside the .EXE. If the installation included .CABs or other files, archive those also. Determine the Form of the Update This is the second step in preparing for an update. An update can be a patch, an upgrade, or a reinstall. You can create both a patch and an upgrade of the same installation. If you do not create a patch or an upgrade, your update is a reinstall by default. You can also use command-line options to cause an upgrade to completely or partially reinstall. About patches z Can only update an existing application. z Can update multiple previous versions to the current version. z Can only update an application originally installed with Windows Installer technology. z Are small, containing only the changes between the original and updated applications. z Are created with Patch Creation, available in Wise Package Studio. See Patch Creation in the Wise Package Studio Help. z Allow little flexibility in customizing an update. Example: You cannot change feature states, leave certain features installed, or perform custom actions based on the version of the installed application. About upgrades z Used when you make major changes to an installation. z Update an existing application or install the entire application. z Are at least as large as a stand-alone installation. z Can update multiple versions of an installed application. z After installing the new version, check for components of the previous version that are no longer needed and remove them. z Allow flexibility in customizing an update. Example: You can run custom actions and specify features to leave on the destination computer based on what version is already installed. z Are created on the Upgrades page. See Upgrades on page 302. About reinstalls z Are required by default if you don’t provide for another method of updating, such as a patch or upgrade. Reinstalls are forced by the operating system if the version and the product code are the same. Windows Installer Editor Reference 300 Upgrading Applications z If the product code is changed, then the updated application can be installed alongside the original application, or can inadvertently be installed over the original application. z Are not recommended for updating an application. z Should only be used to update if one of the following is true: „ The update is so small that only the contents of a few files changed. No new files or registry keys were added, and none were removed. „ The update is so large that you want the old and new versions to be able to coexist on the same computer. If you make changes to the installation (Example: adding or removing files), you must change the product version. If you do not change the product version and the end user tries to reinstall, it can result in a mix of old and new files. If the product version is incremented, the installation displays a message stating that the application is already installed and installation cannot continue. The end user must uninstall the application and run the installation to install the new version. To avoid this, use patches or upgrades. Determine the Product Code and Product Version This is the third step in preparing for an update. Before deploying an updated installation, you must determine whether you need to change the product code and the product version. Windows Installer uses the product code and product version to determine how to handle an upgrade. Also, your organization’s support department might need to differentiate updates based on product version. You change the product code and product version on the Product Details page. For information on when to change them, see: Incrementing the Product Version on page 87 Patching and Upgrades in the Windows Installer SDK Help Changing the Product Code in the Windows Installer SDK Help Warning If you are releasing a newer version of your application but are not using an upgrade or patch, it is very important to enter a new version on the Product Details page. Not doing so can cause the installation to open in maintenance mode instead of in normal installation mode. This can result in an installation that is a mixture of old and new files, which can cause errors in your application. The only exception is if the installation contains no new files, no deletion of files, and no other system changes, which means that only the contents of files are changed. Check the Installation With UpgradeSync This is the fourth step in preparing for an update. UpgradeSync changes the current installation in preparation for creating either a patch or upgrade. UpgradeSync compares the current installation to the previous version of the installation and prepares the current installation for a patch or upgrade. UpgradeSync is a tool in Wise Package Studio. Windows Installer Editor Reference 301 Upgrading Applications See UpgradeSync. UpgradeSync Using UpgradeSync is one of the steps in preparing software for updates. See Preparing for Software Updates on page 299. UpgradeSync compares the current package with the previous version of the package, and does the following to prepare the current package for a patch or upgrade: z Changes the PackageCode, ProductCode, and ProductVersion properties if necessary. z Aligns component GUIDs. If GUIDs or key paths for the same component don’t match between the new and old .MSI, the component could inadvertently get deleted because Windows Installer does not recognize the components as being the same. Aligning component GUIDs for matching components prevents upgrades from deleting necessary files in the newer version. z Detects errors that could cause problems with a patch or upgrade and, if possible, fixes them. See Using UpgradeSync in the Wise Package Studio Help. Patch Creation Use Patch Creation to create a Windows Installer patch file (.MSP) that updates installed versions of a Windows Installer-based application. A patch file can update one or several previous versions. Unlike full installations, a patch installation contains only the information necessary to update an installed version of the application. See the following topics in the Wise Package Studio Help: Creating a Patch File Specifying Previous Versions for Patches Advanced Upgrade Version Details Adding a Digital Signature to a Patch Specifying the Patch Sequence Specifying Advanced Patch Settings Specifying Patch Removal Settings Upgrades Use the Upgrades page to create an installation that upgrades previous versions of an application. During an upgrade, the installation searches the destination computer for applications that can be upgraded, and upon detection, retrieves its version information from the registry. The installation uses this information along with the criteria on the Upgrades page to determine whether the installed application should be upgraded. Then the installation silently uninstalls the previous version and installs the new version. Note Upgrading is only supported in Windows Installer runtime v1.1 or later. Windows Installer Editor Reference 302 Upgrading Applications What you need to create an upgrade z The previous version or versions, which you are upgrading, must have been installed using Windows Installer. z You need access to the .MSI of each version you are upgrading. z If you do not have access to the .MSI files, you must have the upgrade code and version information from the .MSI files. The upgrade code is stored in the UpgradeCode property, which is in the Properties icon in Setup Editor > Product tab. The version is located on the Product Details page. z The product code of this installation should be different from the product codes of the installations you will upgrade. What is the upgrade code? The upgrade code is a property that is set when you create a new installation. It should be the same for a related set of applications. When the end user runs an installation on the destination computer, Windows Installer searches for applications with the same upgrade code. The upgrade code is the only information required for creating an upgrade. If no other upgrade specifications are entered, it is used as the sole factor for determining whether the upgrade takes place. You can see the upgrade code under the Properties icon in Setup Editor > Product tab. It is in GUID format. Creating an Upgrade To create an upgrade 1. Select Installation Expert > Upgrades page. 2. Click Add at the right of the page and specify the .MSI or .WSI for the previous version of the application. If you see a warning to update the current installation’s product code, click Yes. The Upgrade Details dialog box appears. 3. Complete the dialog box: „ Upgrade Code If you specified an .MSI or .WSI to upgrade, this is filled in with that .MSI’s upgrade code. If you did not specify an .MSI, you must enter the upgrade code of the installation you want to upgrade. See What is the upgrade code? on page 303. „ Minimum Version Enter the minimum version that should be upgraded by this installation. The version you enter here is not upgraded unless you mark the Include minimum version in range check box. „ Include minimum version in range Mark this to include the minimum version as a valid upgrade. If you clear this, only versions greater than the minimum version are upgraded. „ Maximum Version Enter the maximum version that should be upgraded by this installation. The version you enter here is not upgraded unless you mark the Include maximum version in range check box. Windows Installer Editor Reference 303 Upgrading Applications „ Include maximum version in range Mark this to include the maximum version as a valid upgrade. If you clear this, only versions below the maximum version are upgraded. „ Languages This determines if an application should be upgraded based on its language. Enter a semicolon-delimited list of languages that should be upgraded by this installation. If this is left blank, all languages are included. Example: To upgrade only the American English version, enter 1033. See Language IDs on page 285. „ Exclude languages in list Mark this to reverse the function of the Languages field, causing this installation to upgrade only the versions not listed in the Languages field. Example: To upgrade every version except the American English version, enter 1033 in the Languages field and mark this check box. „ Features to remove If this is left blank, the upgrade removes all existing features from the installed application, and then installs the features specified in the new installation. To prevent the removal of a feature or features, you specify the features to remove. Then the upgrade removes only the features you specify and leaves any other features. The list of features should be comma-delimited. The feature names must exactly match those in the previous version. Example: Suppose Application 1.0 contains Feature1, Feature2, and Feature3. Application 2.0 contains Feature1, Feature2, and Feature4; Feature3 has been dropped. When you upgrade 1.0 users, you enter Feature1, Feature2 in Features to remove. When the upgrade occurs, Windows Installer first removes Feature1 and Feature2 from the existing installation, then installs Feature1, Feature2, and Feature4. Therefore, users of 1.0 still have Feature3. 4. „ Action Property Specify a property to run a particular custom action based on which product version is already installed. During installation, if an application with the same upgrade code is found on the destination computer, its product code is placed into this property. You can set conditions on custom actions so that they execute based on the contents of this property. If you choose to create a new property, enter its name in all uppercase letters, and add it to the list of restricted public properties, which is stored in the SecureCustomProperties property. Only restricted public properties appear in this list. „ Continue installation after a remove failure Mark this to continue the installation, even if it is unable to remove one or more features of the installed application. „ Migrate feature states Mark this to retain the feature states of the installed application during the upgrade. Example: If the end user chose not to install a feature, such as a spell checker, in the initial installation, the upgrade will not install it either. „ Do not uninstall previous version Mark this to keep the previous version of the application on the destination computer when the upgrade is installed. This lets the end user have two versions of the application installed. Click OK. Windows Installer Editor Reference 304 Chapter 12 Working With Source Paths This chapter includes the following topics: z Using Source Control on page 305 z About Path Variables on page 312 z Source Paths in an Installation on page 315 About source paths You might find that you need to work with source paths during installation development. Project files (.WSI) reference files you add to the installation by their source path. Each time you compile, the files are copied from the source path to the .MSI. You can use Package Distribution in Workbench to distribute an installation to the share point directory so that it can be imported into the Software Manager database. When you distribute to the share point, all the installation’s source files are copied to the share point and the source paths for those files are updated in the installation. See Copying a Package to the Share Point Directory in the Wise Package Studio Help. Using Source Control Source code control is the control, tracking, and recording of all changes made to a set of source code files. Various commercial and open-source software applications, such as Microsoft Visual SourceSafe, act as source code control systems (SCCS). All SCCS applications have similar functionality: tracking who is working on what file; allowing for retrieval of previous versions, backing out of changes, adding and removing files from the SCCS; and recording the history of files. They might also provide functionality for viewing the differences between versions of files. Windows Installer Editor integrates with leading SCCS applications to let you perform source control tasks on an installation. Windows Installer Editor determines the SCCS that you are using and calls APIs that interact with it. The API functions display dialog boxes and functionality directly from your SCCS. On the Source Control tab in Wise Options, you enable source code control and set the global level of interaction between your SCCS and Windows Installer Editor. See Setting Source Control Options on page 45. Whereas source control manages source files, the Software Manager Revision Control protects and tracks changes to packages. You cannot use both the Software Manager Revision Control and a third-party source control product for Wise Package Studio projects. You must choose one or the other. See Choosing to Use Revision Control in the Software Manager Help. To use source control, you must: z Have an SCCS installed on your computer, have a valid account, and you might need permissions to create new directories and add files. Because Windows Installer Windows Installer Editor Reference 305 Working With Source Paths Editor works though your existing user account, the permissions you experience in Windows Installer Editor are the same as those you already have set in your SCCS. z Enable the Source Control menu by marking the Enable source control check box in Wise Options. If you do not have an SCCS installed on your system, the Source Control menu is hidden and the Source Control tab in Wise Options displays an informational message. z Choose to use source control, rather than the Software Manager Revision Control, in the Wise Repository Manager. See Choosing a Revision Control System in the Wise Package Studio Getting Started Guide. Note If your installation is already located in your source control system, you can connect to the existing installation. Do a Get of all the installation files to your hard drive, then follow the procedure in Adding an Installation to Source Control on page 306. How XML Files Integrate With Source Code Control To ensure that the XML copy is always synchronized with the original installation file, be sure to mark the Create XML copy during save check box in Wise Options. If an XML copy of an installation is in the same directory as the installation file: z Source control tasks that you perform on the current installation file are also performed on its XML copy. This ensures that both versions remain synchronized. (The XML copy does not appear on the SCCS dialog boxes.) z When you show history, the XML file is used instead of the installation file. z When you compare differences, the XML file is used instead of the installation file. See Saving an Installation as XML on page 76. See also: Adding Files to an Installation in Source Control on page 307 Checking Files Into Source Control on page 308 Checking Files Out from Source Control on page 309 Getting Latest Version of Files on page 309 Removing Files from Source Control on page 310 Undoing the Check Out of Files on page 310 Showing History of the Installation File on page 310 Showing the Differences Between Installation Files on page 311 Comparing the Current Installation to the Latest in Source Control on page 311 Adding an Installation to Source Control To use source control, you must have a source code control system (SCCS) installed on your computer. See Using Source Control on page 305. To add an installation to source control 1. If the commands in the Source Control menu are unavailable, do the following: a. Select Tools menu > Options > Source Control tab. b. Mark Enable source control. This enables the Source Control menu. Windows Installer Editor Reference 306 Working With Source Paths c. 2. Click OK to exit Wise Options. Select Source Control menu > Add. Dialog boxes from your SCCS appear, in which you connect to your SCCS and select the location where this installation should be stored. To get further help on any of these options, see the help system for your SCCS. If this installation is already located in your SCCS, you can connect to it by selecting its current location when prompted. After the SCCS-related dialog boxes appear, the Add to Source Control dialog box appears. This dialog box contains the files that you add to the installation and resource files from the Windows Installer Editor directory that are part of every new installation. Note If you are working in a .WSI, only the .WSI can be added to source control; there is no way to add the corresponding compiled .MSI. The .WSI or .MSI you are working in does not appear on the Add to Source Control dialog box because it is added automatically. Only files that are currently part of the installation appear. If you later add more files, repeat this process to add those files to the SCCS. 3. On the Add to Source Control dialog box, mark the check boxes of the files to add to source control and click OK. Comments, which are stored as an attribute of the file in the SCCS, are optional. If necessary, scroll to the right to view the Type and File Path columns. The Copy Files to New Location dialog box appears if any files are not in the directory tree of the installation file. Because all files that you add to source control must be in the same directory tree as the installation file, this dialog box prompts you to move the files to a new directory under the installation file directory. 4. Mark the check boxes of the files to copy to the same directory tree as the installation file. To change the new location, click Change Dir and select another directory within the same directory tree. The New Location column indicates the directory to which files will be copied. (Scroll right to see the New Location column.) If you later edit a file, you must edit the file that is copied to the new location, because that is the file that is compiled into the installation. Note To avoid moving files, cancel this operation, remove this project from source control, and move the installation file into the same directory tree as its source files. 5. Click OK. After the installation is added to your SCCS, use the options in the Source Control menu to coordinate file transactions between your computer and the SCCS. Whenever you add files to the installation, repeat the process above to add them to your SCCS. See also: Adding Files to an Installation in Source Control on page 307 Adding Files to an Installation in Source Control When you add files to an installation, you must also add them to your source code control system (SCCS), even if you previously added the installation to source control. Windows Installer Editor Reference 307 Working With Source Paths Example: Suppose you add an installation to source control, along with source files A.dll, B.txt, and C.jpg. Later, you add the file D.gif to the installation. To get D.gif into source control follow the procedure below. To add files to an installation in source control 1. Select Source Control menu > Add. The Add to Source Control dialog box appears. This dialog box shows files in the installation that have not yet been added to source control. 2. On the Add to Source Control dialog box, mark the check boxes of the files to add to source control and click OK. Comments, which are stored as an attribute of the file in the SCCS, are optional. If necessary, scroll to the right to view the Type and File Path columns. The Copy Files to New Location dialog box appears if any files are not in the directory tree of the installation file. Because all files that you add to source control must be in the same directory tree as the installation file, this dialog box prompts you to move the files to a new directory under the installation file directory. 3. Mark the check boxes of the files to copy to the same directory tree as the installation file. To change the new location, click Change Dir and select another directory within the same directory tree. The New Location column indicates the directory to which files will be copied. (Scroll right to see the New Location column.) If you later edit a file, you must edit the file that is copied to the new location, because that is the file that is compiled into the installation. Note To avoid moving files, cancel this operation, remove this project from source control, and move the installation file into the same directory tree as its source files. 4. Click OK. After the installation is added to your SCCS, use the options in the Source Control menu to coordinate file transactions between your computer and the SCCS. Whenever you add files to the installation, repeat the process above to add them to your SCCS. See also: Using Source Control on page 305 Adding an Installation to Source Control on page 306 Checking Files Into Source Control You can use this feature only if you’ve added the current installation to your source code control system (SCCS). If you check a file in, then try to work on it, you are prompted to save it with a new name because the file is locked for changes unless it is checked out first. To check files into source control 1. Select Source Control menu > Check In. The Check In dialog box appears, listing all files that have previously been checked out. Windows Installer Editor Reference 308 Working With Source Paths Note When you add an installation to source control, the installation file (.WSI or .MSI) is added and is also checked out, so it might appear in this dialog box even if you previously did not check it out. 2. Mark the check boxes of the files to check into source control and click OK. Comments, which are stored as an attribute of the file in the SCCS, are optional. See also: Using Source Control on page 305 Adding an Installation to Source Control on page 306 Checking Files Out from Source Control You can use this feature only if you’ve added the current installation to your source code control system (SCCS). If you check a file in, then try to work on it, you are prompted to save it with a new name because the file is locked for changes unless it is checked out first. To check files out from source control 1. Select Source Control menu > Check Out. The Check Out dialog box appears, listing all files that have previously been checked in. Note When you add an installation to source control, all files except the installation file (.WSI or .MSI) are checked in, so they might appear in this dialog box even if you previously did not check them in. 2. Mark the check boxes of the files to check out from source control and click OK. Comments, which are stored as an attribute of the file in the SCCS, are optional. See also: Using Source Control on page 305 Adding an Installation to Source Control on page 306 Getting Latest Version of Files You can use this feature only if you’ve added the current installation to your source code control system (SCCS). To get the latest version of a file 1. Select Source Control menu > Get Latest Version. The Get Latest Version dialog box appears, listing all files in the installation. 2. Mark the check boxes of the files to get from source control and click OK. You cannot select a new location to copy files you get; they replace the existing files at the check in/check out location. Windows Installer Editor Reference 309 Working With Source Paths See also: Using Source Control on page 305 Adding an Installation to Source Control on page 306 Removing Files from Source Control You can use this feature only if you’ve added the current installation to your source code control system (SCCS). To remove files from source control 1. Select Source Control menu > Remove. The Remove dialog box appears, listing all files in the installation. 2. Mark the check boxes of the files to remove from source control and click OK. Comments, which are stored as an attribute of the file in the SCCS, are optional. See also: Using Source Control on page 305 Adding an Installation to Source Control on page 306 Undoing the Check Out of Files You can use this feature only if you’ve added the current installation to your source code control system (SCCS). To undo check out 1. Select Source Control menu > Undo Check Out. The Undo Check Out dialog box appears, listing all files that have been checked out. Note When you add a installation to source control, the installation file (.WSI or .MSI) is added and is also checked out, so it might appear in this dialog box even if you previously did not check it out. 2. Mark the check boxes of the files for which to undo check out. This backs out your changes to the file, and checks the file back into source control. See also: Using Source Control on page 305 Adding an Installation to Source Control on page 306 Showing History of the Installation File You can use this feature only if you’ve added the current installation to your source code control system (SCCS). You can view the history of an installation in terms of its check in/check out activity in the SCCS. You can only view the history of the installation file (.WSI or .MSI), not the other source files associated with the installation. If an XML copy of the installation exists, the Show History command displays the history of the XML file instead of the Windows Installer Editor Reference 310 Working With Source Paths installation file. To view the history of files other than the installation file, use your SCCS directly. To view the history of the installation file, select Source Control menu > Show History. Dialog boxes from your SCCS appear. For information on these dialog boxes, consult the documentation for your SCCS. In Microsoft Visual SourceSafe, the History Options dialog box appears, followed by the History of ProjectFileName.wsi dialog box. See also: Using Source Control on page 305 Adding an Installation to Source Control on page 306 Showing the Differences Between Installation Files You can use this feature only if you’ve added the current installation to your source code control system (SCCS). SCCS applications commonly have functionality to let you see the differences between the installation located on your local computer and the installation in the SCCS. To access this feature from Windows Installer Editor, select Source Control menu > Show Differences. Dialog boxes from your SCCS appear. For help using these dialog boxes to show differences, consult the documentation for your SCCS. Note If you are using Microsoft Visual SourceSafe, the Difference Options dialog box appears. You might need to select the SourceSafe folder and the Windows folder to compare in the Compare and To fields. Then click the Project button for differences. To perform a compare using Visual MSIDiff instead, use the Compare to Latest menu command. It performs a table-by-table, row-by-row comparison of the current installation file to the installation file in your SCCS. See Comparing the Current Installation to the Latest in Source Control. See also: Using Source Control on page 305 Adding an Installation to Source Control on page 306 Comparing the Current Installation to the Latest in Source Control You can use this feature only if you’ve added the current installation to your source code control system (SCCS). You can perform a table-by-table, row-by-row comparison of the database tables that make up an installation file (.MSI or .WSI). The current installation file is compared to the latest installation file that is checked into your SCCS. To compare the current installation to the latest in source control 1. Select Source Control menu > Compare to Latest. You are taken to Setup Editor > Tables tab and the Visual MSIDiff Key dialog box appears, which describes icons that indicate changes. Changes are shown in the tables and rows where they occur. Windows Installer Editor Reference 311 Working With Source Paths 2. On the Visual MSIDiff Key dialog box, take note of the symbols and colors that indicate changes and click OK. If the Visual MSIDiff Key dialog box does not appear, you might have clicked its Do not show this dialog again check box. You can reactivate this dialog box on the Prompts tab in Wise Options. 3. On the Tables tab, scroll through tables, looking for the symbols for changed tables. Click changed tables to view differences in rows, which are indicated by symbols and colors. As you work in the installation file, the symbols indicating changed items are updated dynamically. 4. To turn the compare off, which closes the comparison file and returns to the current file, select Tools menu > Visual MSIDiff > End Current Compare. Closing the file also ends the compare. Another command in the Source Control menu, Show Differences, lets you use the compare technology offered by your SCCS. See Showing the Differences Between Installation Files on page 311. See also: Using Source Control on page 305 Adding an Installation to Source Control on page 306 About Path Variables When you add a file to an installation, its source path is stored. During compile, the source path information is used to find the file and compile it into the .MSI or .EXE. The Path Variables page lets you define variables to replace commonly-used source paths. However, it has no effect on files that are already part of the installation. For these files, see Source Paths in an Installation on page 315. If you add a file, and its source path matches one of the paths defined on the Path Variables page, the variable that represents the path is stored instead of the hard-coded path. Example: Suppose the source files for your test build are in C:\Application\Test, and the source files for your production build are in C:\Application\Production. You could create a user-defined path variable named Application_Files and set it to C:\Application\Test. If you then add the test build source files, their source path would contain the variable name. You could then change this path variable to C:\Application\Production for your production build. Note Do not create more than one variable that refers to the same path, because only one of them is used when you add files. Predefined Path Variables Commonly used paths, particularly system-related paths, are predefined on the Path Variables page. By default, they are enabled, which means all files you add from common folders contain path variables as part of the source path. You cannot modify predefined path variables, but you can turn substitution off. See Turning Path Variable Substitution On and Off on page 313. Windows Installer Editor Reference 312 Working With Source Paths Use to Replace Substrings You can also use path variables to replace any matching substring in a path. Example: If files are in C:\Development\Application\Version1.0, you could create a path variable named Version and set it to Version 1.0. Each time an instance of “Version 1.0” was found in a path, it would be replaced with [Version]. Options for Creating a Path Variable z Creating a User-Defined Path Variable on page 313. z Creating a Path Variable Based on an Environment Variable on page 314. z Creating a Path Variable Based on a Registry Value on page 314. Turning Path Variable Substitution On and Off The Path Variables page lets you define variables to replace commonly-used source paths. Once these variables are defined, you can turn them on and off. To turn path variable substitution on and off 1. Select Installation Expert > Path Variables page. 2. Mark or clear the check box in the Replace column. Turning substitution off does not remove the path variable from paths for files added previously; it only affects paths for files added subsequently. See also: About Path Variables on page 312 Creating a User-Defined Path Variable You can create a user-defined path variable that is set to a directory on your computer. To create a user-defined path variable 1. Select Installation Expert > Path Variables page. 2. Click Add at the right of the page and select User-Defined Path Variable. The User-Defined Path Variable Details dialog box appears. 3. Complete the dialog box: „ Variable Name Enter any name, but do not use special characters or spaces. Because this is not a Windows Installer property, you do not need to follow Windows Installer property naming conventions. This variable is inserted into the paths of files that are pulled from the directory that appears in Current Value. „ Current Value (Read-only) This displays what you enter in Defined Value. „ Defined Value Specify the directory to replace with a variable. When you add a file from this directory, the variable name replaces the path. Windows Installer Editor Reference 313 Working With Source Paths „ 4. Replace When Matched Mark this to activate this path variable. If this is cleared, this path variable has no effect on files you add to the installation. Click OK. See also: About Path Variables on page 312 Creating a Path Variable Based on an Environment Variable You can create a path variable that is set to the value of an environment variable. To create a path variable based on an environment variable 1. Select Installation Expert > Path Variables page. 2. Click Add at the right of the page and select Environment Path Variable. The Environment Variable Path Variable Details dialog box appears. 3. 4. Complete the dialog box: „ Variable Name Enter any name, but do not use special characters or spaces. Because this is not a Windows Installer property, you do not need to follow Windows Installer property naming conventions. This variable is inserted into the paths of files that are pulled from the directory that appears in Current Value. „ Current Value (Read-only) This displays the current value of the environment variable you select below. „ Env. Variable This list contains the environment variables that are currently defined on your computer. Select an environment variable that contains a directory path. „ Replace When Matched Mark this to activate this path variable. If this is cleared, this path variable has no effect on files you add to the installation. Click OK. See also: About Path Variables on page 312 Creating a Path Variable Based on a Registry Value You can create a path variable that is set to a registry value. When a registry path value is displayed on the Path Variables page, a double slash precedes the value name. This is normal. (You might have to scroll to the right to see this value in the Defined Value column.) To create a path variable based on a registry value 1. Select Installation Expert > Path Variables page. 2. Click Add at the right of the page and select Registry Path Variable. Windows Installer Editor Reference 314 Working With Source Paths The Registry Path Variable Details dialog box appears. 3. 4. Complete the dialog box: „ Variable Name Enter any name, but do not use special characters or spaces. Because this is not a Windows Installer property, you do not need to follow Windows Installer property naming conventions. This variable is inserted into the paths of files that are pulled from the directory that appears in Current Value. „ Current Value (Read-only.) This shows the current data of the registry value specified below. „ Reg. Key Specify the complete key name of the registry value that contains a directory path. The registry browser that appears shows only key names (folder icons). You specify the value in Reg. Value below. „ Reg. Value Select the value to pull a directory name from. This list shows the values contained in the key you selected above. „ Replace When Matched Mark this to activate this path variable. If this is cleared, this path variable has no effect on files you add to the installation. Click OK. See also: About Path Variables on page 312 Source Paths in an Installation Paths to files in an installation can break if you: z Move files that are part of the installation to a new directory on your computer or network. z Move the installation file itself from your computer to another computer. z Use relative paths and then move the installation file. z Rename a directory. An installation can also contain broken paths if it was created with SetupCapture. Sometimes, SetupCapture captures references to temporary files that are deleted after the installation is finished. If paths are broken, then during compile, error messages appear in the Task List concerning the files that could not be opened. Rather than adding the files again, you can specify new source directories for these files. If files with broken paths should not be in the installation, you can use the Remove Missing Files tool to remove them. See Removing Files With Missing or Invalid Source Paths on page 357. The Convert Source Paths dialog box lets you change the directories that contain an installation’s files. You can also change all the directories to either relative or UNC (Uniform Naming Convention) paths. If you change directories to relative paths, then the installation can be opened on any computer that has the same relative directory Windows Installer Editor Reference 315 Working With Source Paths structure. If you change the directories to UNC paths, you can leave the source files on a server but open the installation from any computer on the local network. Whether the path to a file is stored depends on what kind of file you’re working in. When you add a file to an .WSI or .MSI, the path to the file is stored, and each time you compile, the file is recompressed into the resulting .MSI. However, if you open an .MSI that was compiled from a .WSI, it does not store paths to the files because the files are encapsulated inside the .MSI. You cannot change the source paths of files encapsulated inside an .MSI. To see a file’s path, go to the Files or Web Files page and double-click a file in the lowerright list box. The File Details dialog box appears, which displays the path for the file in the Source Pathname field. If this field only displays a file name or is blank, then you are working in an .MSI that was compiled from a .WSI. If files do not have paths, you can either double-click on each file and define a path, or convert the .MSI to a .WSI by using MSI to WSI Conversion. See also: Changing Source Directories on page 316 Converting to Relative Source File Paths on page 317 Converting to UNC-Based Source File Paths on page 318 Changing the Source Directory Dynamically During Compile on page 318 Changing Source Directories When you change source directories, you can specify a new path for a selected directory or for multiple directories. To change source directories 1. Select Tools menu > Convert Source Paths. The Convert Source Paths dialog box appears with a list of all the directories that are referenced in the installation. 2. Select a directory from the list. To change multiple directories, select a high-level directory so that you can change all of its subdirectories. 3. Click Change Selected Path. The Change Selected Path dialog box appears. 4. 5. Complete the dialog box: „ Change to Specify the new path. „ Change Sub-Directories Mark this to change the subdirectories of the current directory. Click OK. The Change Source Directories to column displays the new path. If you marked Change Sub-Directories, all directories that start with the same name as the one you changed are renamed. Windows Installer Editor Reference 316 Working With Source Paths Example: If you change C:\Program Files\Application\Manual to C:\Program Files\Application\Online Manuals, all the directories that begin with C:\Program Files\Application\Manuals are changed. 6. To make additional changes, repeat the preceding steps. 7. To set the path type for files that you add to the installation later, make a selection from Path Type on the Convert Source Paths dialog box. You can set paths to absolute, relative, or UNC-based. 8. Click OK. All parts of the installation that reference these directories are updated. See also: Source Paths in an Installation on page 315 Converting to Relative Source File Paths You can convert the paths of source files to relative paths. You might do this to keep all your source files in a central version and source control system. (Example: Microsoft Visual SourceSafe. In Microsoft Visual SourceSafe, if you copy the installation files to a different directory each time you do a Get, you can use this feature to ensure that the paths are always valid, even though the directory structure changes.) A relative path uses .\ in the path to indicate the current directory, and it uses ..\ to indicate one directory up. All paths are relative to where the .WSI or .MSI file is located. Example: If the path to the .WSI is C:\Development\Application.wsi, and you add the file C:\Program Files\Application.ini, the relative path of Application.ini is ..\Program Files\Application.ini. To convert to relative source file paths 1. Select Tools menu > Convert Source Paths. The Convert Source Paths dialog box appears. 2. Click Change All Paths to Relative. The Change Source Directories to column displays the new paths. A one-time conversion of the paths in the installation is performed. To change the directories back to absolute paths, select high-level directories and change the paths. See Changing Source Directories on page 316. Paths to files that are not on the same drive as the installation file are not converted, because they cannot be written as relative paths. Predefined paths, such as [ProgramFiles], cannot be changed to relative paths. 3. To convert all directories you add to the installation later to relative paths, select Relative Paths from Path Type. 4. Click OK. Windows Installer Editor Reference 317 Working With Source Paths Converting to UNC-Based Source File Paths You can convert the mapped drive paths of source files to UNC-based (Uniform Naming Convention) paths. This helps prevent compile errors when installation source files are on a central file server. Example: If you add files to an installation from your Y drive, which is mapped to a file server, paths of files you add to the installation start with Y:\. If a co-worker opens and compiles the installation on another computer that doesn’t have its Y drive mapped to the same file server, the compile fails because the installation cannot find the source files on the Y drive. However, if you first convert all network paths to UNC paths, coworkers on the same network can open and compile the installation without encountering errors. Instead of a path such as Y:\Application.ini, a file has a fully qualified path such as \\Server\Development\Application\Application.ini. To convert to UNC-based source file paths 1. Select Tools menu > Convert Source Paths. The Convert Source Paths dialog box appears. 2. Click Change All Paths to UNC. This button is only available if at least one of the paths in the installation is from a mapped network drive. The Change Source Directories to column displays the new paths. Only the source paths that are from mapped drives are changed to UNC. 3. To convert all directories you add subsequently to UNC paths, select UNC Paths from Path Type. 4. Click OK. A one-time conversion of all the network paths in the installation is performed. Paths to files that are on local drives are not converted. However, if the local drive is shared, it is converted to the shared drive name. See also: Source Paths in an Installation on page 315 Changing the Source Directory Dynamically During Compile You can define a source directory as a property, so you can easily reassign the location of source files when you compile a .WSI or .MSI. Use this feature if you: z Frequently change the location of source files. z Frequently move the installation to other computers. z Need to point to a different source directory each time you compile. Use the procedures below to change the source directory dynamically during compile. To create a property to hold the source directory value 1. Select Setup Editor > Product tab and click the Properties icon in the left pane. 2. In the right pane, select New > Property from the right-click menu. The Property Details dialog box appears. Windows Installer Editor Reference 318 Working With Source Paths 3. Complete the dialog box and click OK: „ Name Enter a new property name. „ Value Enter the directory path that currently contains the source files. Example: Enter SourceFiles in the Name field and enter C:\Development in the Value field. The directory path you enter here can be changed by commandline options during compile. To point source directories to the value of the property 1. Select Tools menu > Convert Source Paths. The Convert Source Paths dialog box appears. 2. Select the source directory to change dynamically. 3. Click Change Selected Path. The Change Selected Path dialog box appears. 4. Complete the dialog box: „ Change to Enter the name of the property, surrounded by square brackets. The property name is case-sensitive. Example: [SourceFiles]. You can add other directories to the end of the property name to create other locations. Example: [SourceFiles]Libraries\Visual Basic [SourceFiles]Libraries\C++ „ 5. Change Sub-Directories Mark this to change the subdirectories of the current directory. Click OK. The Change Source Directories to column displays the property name in brackets. 6. Click OK. To change the source directory by compiling from the command line 1. Select Windows Start menu > Run. The Run window appears. 2. Enter the following: „ The path of the WfWI.exe program. „ The path to the .WSI or .MSI to be compiled. „ The command-line options to compile and set the property value. Example: "C:\Program Files\Windows Installer Editor\WfWI.exe" C:\Installers\Application.wsi /c /p SourceFiles="E:\Development\" See About Command Lines on page 226 and Source Paths in an Installation on page 315. Windows Installer Editor Reference 319 Chapter 13 Merge Modules and Transforms This chapter includes the following topics: z About Merge Modules on page 320 z Available Tabs and Pages in Merge Modules on page 321 z Creating a Merge Module As a New Installation on page 325 z Creating a Merge Module From Existing Components on page 326 z Creating a Configurable Merge Module on page 328 z About the Merge Modules Page on page 334 z Adding a Merge Module to an Installation on page 335 z About Transforms on page 338 z Creating a Transform Based on an Existing .MSI on page 339 z Creating a Universal Transform on page 341 z Applying a Transform to an Installation on page 342 z Multiple Instance Installations on page 343 About Merge Modules A merge module is a special kind of Windows Installer database that contains the components needed to install a discrete software bundle. A merge module cannot be installed alone, but must be merged into a standard Windows Installer installation during compile of the installation. Typically, a merge module or a collection of merge modules related by dependencies installs an application or portion of an application at run time. The purpose of merge modules is to let you add self-contained software modules to multiple installations. See Merge Modules in the Windows Installer SDK Help. Example: Suppose you have five applications that require a specifically configured version of the Visual Basic runtime. You could create a merge module that installs and configures the Visual Basic runtime. Then you add the merge module to each installation that requires that particular Visual Basic runtime. This saves you from having to add the necessary files, registry entries, and other components to every installation individually. It also saves time if you update the merge module; instead of updating the five installations for all applications, you update only the merge module, then recompile the five installations. When deploying software through a merge module, keep update considerations in mind. Example: If you deploy MSDE through a merge module, end users cannot use Microsoft’s MSDE security patches to update that installation of MSDE. Microsoft patches only operate on software packages installed by .MSI. You would have to incorporate the MSDE patch changes in an update to your own application and distribute it to your end users. This could cause security and timing issues for your end users. You can obtain merge modules from several sources: Windows Installer Editor Reference 320 Merge Modules and Transforms z Merge modules that you create. See Adding a Merge Module to an Installation on page 335. z Predefined merge modules that install commonly-used software packages. You can download these from the Wise Web site or from other vendors’ Web sites. See Downloading Redistributable Files on page 29. z Configurable merge modules that you create. See Creating a Configurable Merge Module on page 328. Note When you view MSI Script in a merge module, you’ll notice that you cannot select an installation mode, that there are no actions in the right pane, and that there are no sequence tabs at the bottom. This is because any custom action you add to a merge module does not contain its own sequence tables and must be merged into the CustomAction table and the sequence tables of the main installation. See All Custom Actions on page 438 and Using the Custom Action Location Tab for Merge Modules on page 485. Configurable merge modules Configurable merge modules contain certain values that the installation author can configure to specify how the module behaves in an installation. Example: A configurable merge module might let you set attributes on components, enable or disable isolated components, specify a bitmap for a dialog box, or specify how a custom action is run. When you add a configurable merge module to an installation, an additional dialog box appears, on which you specify values for the configurable items. You also can create configurable merge modules. Configurable merge modules are supported only by Windows Installer 2.0 or later. See Configurable Merge Modules in the Windows Installer SDK Help. See also: Available Tabs and Pages in Merge Modules on page 321 Creating a Merge Module As a New Installation on page 325 Creating a Merge Module From Existing Components on page 326 About the Merge Modules Page on page 334 Editing Merge Module Details on page 337 Available Tabs and Pages in Merge Modules When you work in a merge module, you have access to a limited set of pages in Installation Expert. Some of these pages are unique to merge modules. You cannot add features to a merge module, therefore, the Features tab does not appear in Setup Editor when you are in a merge module. Instead, the Module tab appears, which contains information similar to that found on the Features tab. It lets you manipulate the components, files, registry entries, and other items in the merge module. Items you add to the merge module are listed under this tab. See Items you can add on the Features tab on page 363. The panes on the Module tab show only the items you have added, unless you select to show empty folders and items from the right-click menu. The upper-right pane shows Windows Installer Editor Reference 321 Merge Modules and Transforms the contents of the item selected in the left pane. For an expanded view of a selected item, double-click the item in the right pane. See also: Setting Merge Module Details on page 322 Setting Dependencies for a Merge Module on page 323 Setting Exclusions for a Merge Module on page 324 Creating a Merge Module As a New Installation on page 325 Creating a Merge Module From Existing Components on page 326 Creating a Configurable Merge Module on page 328 Setting Merge Module Details ¾ Available in merge module files (.WSM, .MSM) only. Use the Module Details page to specify the name, version, language, and type of a merge module. Windows Installer uses this information to identify the merge module. To set merge module details 1. Select Installation Expert > Module Details page. If there is no Module Details page, you are not in a merge module file. 2. Complete the page: „ Module Name Enter a name that Windows Installer and Windows Installer Editor can use internally to identify the merge module. „ Version Enter the version of the module. Windows Installer and Windows Installer Editor use this number to check versions of dependency and exclusion merge modules. You can use the format xxxxx.xxxxx.xxxxx.xxxxx, where x is a digit. See Version in the Windows Installer SDK Help. „ Language Enter the language ID for the merge module. English is 1033. Language neutral (meaning the merge module works with all languages) is 0. See Language IDs on page 285. „ Module Type Select the module type. This defaults to the Default Application Type that is specified in Wise Options. See Setting .NET Assembly Options on page 34. Note The ability to create .NET installations is supported only by Windows Installer 2.0 or later. Windows Installer Editor Reference  Win 32 (non .NET) A standard Win32 merge module without .NET assemblies.  .NET Application A .NET merge module with only .NET elements. 322 Merge Modules and Transforms  Mixed (.NET and Win32) A merge module that contains both Win32 and .NET elements. When this option is selected, the Generate COM interop registry keys for .NET Assembly check box on the Self-registration tab of the File Details dialog box is marked by default for all .NET assemblies you add to this merge module. The assemblies will be registered so that they can be called as though they were COM elements. When the .NET Application or Mixed option is selected, entries are created in the MsiAssembly and MsiAssemblyName tables for each assembly you add to the merge module. Also, the Global Assembly Cache appears on the Files page. See also: Available Tabs and Pages in Merge Modules on page 321 Setting Dependencies for a Merge Module ¾ Available in merge module files (.WSM, .MSM) only. The Dependencies page lets you add, edit, and remove the dependencies for a merge module. A dependency is a merge module that is required for the current merge module to work. Dependencies can have their own dependencies, which means that the module you designate as a dependency could itself have a dependency on another module, and so on. Use dependencies to compartmentalize different components of software. When you compile an installation that contains a merge module that has a dependency, both the original merge module and all its dependencies are merged into the installation. Example: Suppose you have a merge module that consists of a library of database drivers, but for those drivers to work, MDAC must also be installed. You designate the MDAC merge module as a dependency to the database driver module. Then, whenever you add the database driver module to an installation, Windows Installer Editor tries to add the dependency merge module, MDAC. Windows Installer Editor looks for dependency merge modules in the default merge module directory specified in Wise Options, and also looks at the list of previously added merge modules. If Windows Installer Editor does not find the dependent module in either of these places, it prompts you to add the dependency merge module yourself. To add a dependency to a merge module 1. Select Installation Expert > Dependencies page. If there is no Dependencies page, you are not in a merge module file. 2. Click Add at the right of the Dependencies page and specify one or more merge modules. If you select one merge module, the Dependency Module Details dialog box appears. If you select multiple merge modules, they’re listed on the Dependencies page. Double-click a module name to open the Dependency Module Details dialog box for a specific merge module. Windows Installer Editor Reference 323 Merge Modules and Transforms Fields are populated with information extracted from the merge module. 3. 4. Complete the dialog box: „ Module ID To specify a different merge module, click Browse. „ Language ID To specify a different language for the dependent merge module, change Language ID. (Example: Do this if the merge module you selected includes a complete language group but you want your merge module to be dependent on only one language in this group.) To ignore any language considerations, enter 0. „ Version To ignore any version considerations for the merge module upon which the new merge module will be dependent, leave Version blank. Click OK. The merge module is added to the Dependencies page. Note The information on the Dependency Module Details dialog box fills the ModuleDependency table, which you can see in Setup Editor > Tables tab. See ModuleDependency Table in the Windows Installer SDK Help. See also: Available Tabs and Pages in Merge Modules on page 321 Setting Exclusions for a Merge Module ¾ Available in merge module files (.WSM, .MSM) only. The Exclusions page lets you add, edit, and remove the exclusions for a merge module. Exclusions are a way of preventing two incompatible merge modules from being merged into the same installation. You can set merge modules to be exclusions of each other. Example: Suppose you have two versions of the same merge module: version 1.0 and version 1.1. These two merge modules should never be installed together, so you make each an exclusion of the other. Completing the Exclusions page enters the exclusion information in the ModuleExclusion table in the Windows Installer database and triggers compile and verification error messages if both merge modules are included in the same installation. To add an exclusion to a merge module 1. Select Installation Expert > Exclusions page. If there is no Exclusions page, you are not in a merge module file. 2. Click Add at the right of the Exclusions page and specify one or more merge modules to exclude from the current merge module. If you select one merge module, the Exclusion Module Details dialog box appears. Windows Installer Editor Reference 324 Merge Modules and Transforms If you select multiple merge modules, they’re listed on the Exclusions page. Doubleclick a module name to open the Exclusion Module Details dialog box for a specific merge module. Fields are filled in with information extracted from the merge module. 3. 4. Complete the dialog box: „ Module ID To specify a different merge module, click Browse. „ Language ID To specify a different language for the merge module to be excluded, change the number in Language ID. (Example: Do this if the merge module you selected includes a complete language group but you want to exclude one language in this group only.) To ignore any language considerations, enter 0. „ Min Version and Max Version To exclude multiple versions of the same merge module, edit the Min Version and Max Version fields to reflect the versions to exclude. If you leave these fields blank, all versions of the merge module are excluded. Click OK. The merge module is added to the Exclusions page. Note The information on the Exclusion Module Details dialog box fills the ModuleExclusion table, which you can see in Setup Editor > Tables tab. See ModuleExclusion Table in the Windows Installer SDK Help. See also: Available Tabs and Pages in Merge Modules on page 321 Creating a Merge Module As a New Installation You can create a merge module in much the same way that you create a new installation. To start a new merge module 1. Select File menu > New. The New Installation File dialog box opens. 2. From the Categories list, select Other Templates. 3. From the Template/Tools list, select the Merge Module icon. 4. Select a file type and a target platform, and click OK. For information on file types, see File Types on page 59. The Target Platform section on the New Installation File dialog box appears only if Select platform in New Installation File dialog is selected in Wise Options. See How to Specify the Target Platform on page 62. A new merge module opens. In Installation Expert, four page groups appear, showing the pages that apply to merge modules. Windows Installer Editor Reference 325 Merge Modules and Transforms See To assemble the merge module. To assemble the merge module 1. Assemble the merge module by adding files, registry entries and so on using the pages under the Details page group. Because merge modules cannot have multiple features, you don’t select a feature on these pages. Note The Files page includes an extra folder named Application. By default, files that you add to this folder are copied to the default installation directory of the installation into which the merge module is merged. Example: If you merge the merge module into an installation that installs files to C:\Program Files\Product, all files you add to the Application folder will also be installed to C:\Program Files\Product. 2. If you’re creating a configurable merge module, specify which items can be modified when the module is merged into an installation. See Creating a Configurable Merge Module on page 328. 3. Select the dependencies and exclusions for this merge module. Dependencies are other merge modules that must be included with this merge module, and exclusions are other merge modules that cannot be included with this merge module. See Setting Dependencies for a Merge Module on page 323 and Setting Exclusions for a Merge Module on page 324. 4. Configure the summary information for the merge module. See General Information Page on page 89. 5. Configure the Module Details page, which contains the merge module name, language, and version. See Setting Merge Module Details on page 322. After you create the merge module, you can add it to a standard installation. See Adding a Merge Module to an Installation on page 335. See also: About Merge Modules on page 320 Creating a Merge Module From Existing Components on page 326 Available Tabs and Pages in Merge Modules on page 321 Creating a Merge Module From Existing Components You can create a merge module by moving components from a feature in an existing installation file or merge module into a new merge module. Note All the components you plan to move to the new merge module must be in the same feature. If they are not, create a feature temporarily and add the components to it in Setup Editor > Features tab. Windows Installer Editor Reference 326 Merge Modules and Transforms To create a merge module from existing components 1. Open the installation file or merge module to move components from. 2. Select Tools menu > Move Components to Merge Module. You can also select Setup Editor > Features tab (in an installation) or Setup Editor > Modules tab (in a merge module), right-click the feature containing the components to move, and select Move Components to Merge Module. The Merge Module Information dialog box appears. 3. Complete the dialog box: „ Merge Module Path Specify a full path for the new merge module. „ Module Name Enter a name that Windows Installer and Windows Installer Editor can use internally to identify the merge module. „ Version Enter the version of the module. Windows Installer and Windows Installer Editor use this number to check versions of dependency and exclusion merge modules. You can use the format xxxxx.xxxxx.xxxxx.xxxxx, where x is a digit. See Version in the Windows Installer SDK Help. „ Language Enter the language ID for the merge module. English is 1033. Language neutral (meaning the merge module works with all languages) is 0. See Language IDs on page 285. 4. Click Next. The Merge Module Components dialog box appears. 5. From Export from Feature, select the feature that contains the components to move. If you are moving components from a merge module, there are no features. 6. Mark the check boxes of the components to move into the new merge module. 7. Click Finish. The components you select are removed from this installation, compiled into the new merge module, and re-inserted in the form of a merge module. The new merge module is also available to other installations. See also: Setting Merge Module Details on page 322 Setting Dependencies for a Merge Module on page 323 Setting Exclusions for a Merge Module on page 324 About Merge Modules on page 320 Available Tabs and Pages in Merge Modules on page 321 Windows Installer Editor Reference 327 Merge Modules and Transforms Creating a Configurable Merge Module ¾ Available in merge module files (.WSM, .MSM) only. To create a configurable merge module, you add configuration items to a standard merge module. On the Substitutions page, you specify the: z Substitution item, which is the field that can be configured. z Configuration item, which determines how a field can be configured. This creates a substitution value, which consists of one or more values specified by configuration items. When a configurable merge module is added to an installation, the installation author can specify values for the substitution item based on the configuration item settings. See Adding a Merge Module to an Installation on page 335. Configurable merge modules are supported only by Windows Installer 2.0 or later. For information on creating a standard merge module, see Creating a Merge Module As a New Installation on page 325. To add a configuration item to a merge module 1. Select Installation Expert > Substitutions page. If there is no Substitutions page, you are not in a merge module file. 2. Click Add at the right of the page. The Module Substitution dialog box appears. 3. From Table, select the table that contains the item to be configured when the merge module is added to an installation. 4. In the table, click a table cell to select the substitution item. 5. Click Add and select from the button menu: „ Configurable Item Select to add a configuration item to the selected substitution item. See Setting Configuration Item Details on page 329. „ 6. Constant Select to add a constant value in combination with configurable items. Example: After adding a configuration item, select this option to add a pipe character (|) before adding another configuration item. Click OK. The value you defined for the configurable item appears in the Value field, and the item appears in the Configuration Items list box. 7. To add more values for the item, repeat the preceding two steps. If you add multiple values, multiple rows appear in the list box and the values are concatenated to create the entire substitution value. See Example: Configuring an Item for a Merge Module on page 333. 8. Click OK. The new configuration item is listed on the Substitutions page. Windows Installer Editor Reference 328 Merge Modules and Transforms See also: Specifying Drop-Down List Values for Substitution on page 330 Specifying a Bitfield for Substitution on page 331 Specifying a Key for Substitution on page 332 Setting Configuration Item Details To set configuration item details 1. Access the Configuration Item Details dialog box from the Module Substitution dialog box. See Creating a Configurable Merge Module on page 328. 2. Complete the dialog box: „ Name Enter a name to represent the item in the Configuration Items list box on the Module Substitution dialog box. „ Display Name Enter the name that should appear on the Merge Module Configuration dialog box when the merge module is added to an installation. „ Description Describe what can be modified. „ Type Select the type of configurable data that is appropriate for the item you allow to be substituted.  Arbitrary Text The installation author can enter any text to replace the default value. Example: Use this when you allow a file name to be modified. See Example: Configuring an Item for a Merge Module on page 333.  Formatted Text The installation author can enter any text in Windows Installer formatted text format to replace the default value. Example: Use this when you allow a registry value to be modified.  RTF Text The installation author can enter any text in rich text format to replace the default value. Example: Use this when you allow a different license agreement to be selected.  Text Drop-down List The installation author can select from a drop-down list to replace the default value. This list displays only the name you gave the value, not the actual value. This is useful when the values are not self-explanatory. (Example: Use this option to make a property configurable. Possible choices for the installation author could be to let all end users or only selected end users install this particular file.) Additional fields appear when you select this option. See Specifying Drop-Down List Values for Substitution on page 330. Windows Installer Editor Reference 329 Merge Modules and Transforms  Windows Installer Identifier The installation author can enter text in the format of a Windows Installer identifier to replace the default value. This text can contain ASCII characters, digits, underscores, or periods, and must begin with either a letter or an underscore. Example: Use this to allow a key to be changed or entered into any table. For information on the format types like the ones listed above, see Text Format Types in the Windows Installer SDK Help.  Bitfield (Drop-down List) The installation author can select from a drop-down list to replace the default value. This list displays only the name you gave the value, not the actual value. This is useful when you provide values that are not selfexplanatory. Use the bitfield type only on columns that are bit flags. (Example: In the Files table, the Attribute column contains bit flags representing the file attributes. Therefore, you can use the bitfield type to make a file’s attributes configurable. Possible choices for the installation author could be for the file to be read-only; read-only and hidden; or readonly, hidden, and vital.) Additional fields appear when you select this option. See Specifying a Bitfield for Substitution on page 331 and Bitfield Format Types in the Windows Installer SDK Help.  Integer The installation author can enter any integer to replace the default value. Example: Use this to make the size of a control or a dialog box configurable. See Integer Format Types in the Windows Installer SDK Help.  Key Into a Table The installation author can select a key into a table from a drop-down list to replace the default value. (Example: Use this to let the installation author change the directory for a component when adding a merge module to an installation.) Additional fields appear when you select this option. See Specifying a Key for Substitution on page 332 and Key Format Types in the Windows Installer SDK Help. 3. „ Non-nullable Mark this if a value is required for this configuration item. „ Default Value Enter the value that should appear on the Merge Module dialog box when the configurable merge module is added to an installation. This is the value that can be changed. Click OK. Specifying Drop-Down List Values for Substitution When you add a configuration item to a configurable merge module as a text drop-down list, you must specify values and the text that describes them. When adding the merge module to an installation, the installation author selects from a list that displays the descriptive text. See Text Format Types in the Windows Installer SDK Help. Windows Installer Editor Reference 330 Merge Modules and Transforms To specify drop-down list values for substitution 1. Access the Configuration Item Details dialog box from the Module Substitution dialog box. See Creating a Configurable Merge Module on page 328. 2. Complete the Configuration Item Details dialog box. See Setting Configuration Item Details on page 329. 3. From Type, select Text Drop-down List. 4. Click Add. The Drop-down List Value dialog box appears. 5. 6. Complete the dialog box: „ Name Enter text to describe the substitution value. The installation author sees this value in the Value drop-down list on the Merge Module Configuration dialog box. „ Value Enter the value to be substituted for the current value of the configuration item. Click OK. The Configuration Item Details dialog box lists the text and value you defined. 7. Repeat the preceding three steps to add additional values. 8. Click OK. The Module Substitution dialog box appears. The values you defined for the configurable item appear in the Value field, and the items appear in the Configuration Items list box. 9. Click OK. Specifying a Bitfield for Substitution When you add a configuration item to a configurable merge module as a bitfield dropdown list, you must specify values and the text that describes them. When adding the merge module to an installation, the installation author selects from a list that shows the descriptive text. See Bitfield Format Types in the Windows Installer SDK Help. To specify a bitfield for substitution 1. Access the Configuration Item Details dialog box from the Module Substitution dialog box. See Creating a Configurable Merge Module on page 328. 2. Complete the Configuration Item Details dialog box. See Setting Configuration Item Details on page 329. 3. From Type, select Bitfield (Drop-down List). 4. In Bitmask, enter the decimal value of the bit flag to set. To set multiple bit flags, enter the sum of their decimal values. Windows Installer Editor Reference 331 Merge Modules and Transforms Example: Suppose you want to let the installation author set the attributes of a file to system and vital. The decimal value of the system attribute is 4. The decimal value of the vital attribute is 512. You would add these values and enter a bitmask of 516. 5. Click Add. The Drop-down List Value dialog box appears. 6. 7. Complete the dialog box: „ Name Enter text to describe the substitution value. The installation author sees this value in the Value drop-down list on the Merge Module Configuration dialog box. „ Value Enter the value to be substituted for the current value of the configuration item. Click OK. The Configuration Item Details dialog box lists the text and value you defined. 8. Repeat the preceding three steps to add additional values. 9. Click OK. The Module Substitution dialog box appears. The values you defined for the configurable item appear in the Value field, and the items appear in the Configuration Items list box. 10. Click OK. Specifying a Key for Substitution When you add a configuration item to a configurable merge module as a key into a table, you must specify a table for the key to make configurable. When adding the merge module to an installation, the installation author selects from a list that appears. For information on this format type, see Key Format Types in the Windows Installer SDK Help. To specify a key for substitution 1. Access the Configuration Item Details dialog box from the Module Substitution dialog box. See Creating a Configurable Merge Module on page 328. 2. Complete the Configuration Item Details dialog box. See Setting Configuration Item Details on page 329. 3. From Type, select Key Into a Table. 4. Mark Delete Unreferenced Rows to have the row that is referenced by the default value merged if the installation author selects the default value when adding the merge module to an installation. Example: Suppose the merge module includes a dialog box with a graphic. You select Binary (Bitmap) from Key Table and set the Default Value to the bitmap in the merge module. If the installation author selects a different bitmap when adding the merge module to an installation, then the default bitmap is no longer Windows Installer Editor Reference 332 Merge Modules and Transforms referenced. If Delete Unreferenced Rows is marked, the default bitmap is not merged into the installation. 5. From Key Table, select the type of table to make available for selection for this key. 6. Click OK. The Module Substitution dialog box appears. The values you defined for the configurable item appear in the Value field, and the items appear in the Configuration Item list box. 7. Click OK. Example: Configuring an Item for a Merge Module Suppose your merge module includes a file named ReleaseNotes. Here is how you can let installation authors select a long or a short file name when they merge the module into an installation. To configure an item for a merge module 1. Select Installation Expert > Substitutions page. 2. Click Add at the right of the page. The Module Substitution dialog box appears. 3. From Table, select File. 4. In the FileName column, click the cell that contains the ReleaseNotes file name. It should look something like this: RELEAS~1.TXT|ReleaseNotes.txt 5. Click Add and select Configurable Item. The Configuration Item Details dialog box appears. 6. 7. Complete the dialog box: „ Name Enter “short name.” „ Display Name Enter “Short file name.” „ Description Enter “Choose whether to use a short or a long file name for this file.” „ Type Select Arbitrary Text. „ Default Value Enter “RELEAS~1.TXT.” Click OK. On the Module Substitution dialog box, your configuration item appears as short_name in the Configuration Items list box. 8. Click Add and select Constant. The Substitution Constant dialog box appears. 9. In Constant Substitution Value, enter the pipe character (|) and click OK. Windows Installer Editor Reference 333 Merge Modules and Transforms On the Module Substitution dialog box, the pipe character (|) appears in the Configuration Items list box, below short_name. 10. Click Add and select Configurable Item. The Configuration Item Details dialog box appears. 11. Enter the following: „ Name Enter “long name.” „ Display Name Enter “Long file name.” „ Description Enter “Choose whether to use a short or a long file name for this file.” „ Type Select Arbitrary Text. „ Default Value Enter “ReleaseNotes.txt.” 12. Click OK. On the Module Substitution dialog box, long_name appears in the Configuration Items list box, below the pipe character. Value shows the substitution options for the file name: [=short_name]|[=long_name]. 13. When you add this merge module to an installation, the configuration items will appear in the order they are listed here. To rearrange the items click move up and move down. When you add this configurable merge module to an installation, the Merge Module Configuration dialog box displays the following: z In the list box at the top: Short file name and Long file name. z Description: Choose whether to use a short or a long file name for this file. z Text Value: either RELEAS~1.TXT or ReleaseNotes.txt, depending on the selection in the list box. This value can be modified. See also: Creating a Configurable Merge Module on page 328 About the Merge Modules Page The Merge Modules page lets you add merge modules to an installation, edit settings for merge modules that you already added, and remove merge modules from an installation. See: Adding a Merge Module to an Installation on page 335 Editing Merge Module Details on page 337 About Merge Modules on page 320 Windows Installer Editor Reference 334 Merge Modules and Transforms Adding a Merge Module to an Installation Use the Merge Modules page to add merge modules to an installation. By default, merge modules are not installed with Windows Installer Editor. However, you can create merge modules or use the Download Redistributables wizard to obtain third-party merge modules. See Downloading Redistributable Files on page 29. When deploying software through a merge module, keep update considerations in mind. Example: If you deploy MSDE through a merge module, end users cannot use Microsoft’s MSDE security patches to update that installation of MSDE. Microsoft patches only operate on software packages installed by Microsoft .MSIs. You would have to incorporate the MSDE patch changes in an update to your own application and distribute it to your end users. This could cause security and timing issues for your end users. To add a merge module 1. Select Installation Expert > Merge Modules page. 2. From Current Feature, select a feature or condition. (Because any item you add must be assigned to a specific feature, you cannot add an item when All Features is selected.) Items that you add to a feature are installed on the destination computer only if the feature is installed. Items that you add to a condition are installed only if the feature is installed and the condition is true. 3. Click Add at the right of the Merge Modules page. The Select Merge Module dialog box appears and lists available merge modules in the directories specified in Wise Options. See Setting Merge Module Directories on page 42. (Professional Edition.) The Select Merge Module dialog box can also include merge modules that are in the Software Manager database. You must have access to the Software Manager database and the Read Merge Modules List From Software Manager Database check box must be marked in Wise Options. 4. If the merge module you want is not in the list, do one of the following: „ To add directories to search for merge modules, click Directories and the Merge Modules tab from Wise Options appears. Click Add to add the directory that contains the merge module. The merge modules in this directory are added to the list of available merge modules. See Setting Merge Module Directories on page 42. „ Click Download to add merge modules from the Wise Web site, other vendors’ Web sites, or from the product CD. If you download the merge modules to a directory that is specified in Wise Options, they are added to the list of available merge modules. See Downloading Redistributable Files on page 29. 5. Select one or more merge modules from the list by marking the corresponding check boxes. 6. Click Next. The Merge Module File Directory dialog box appears. Windows Installer Editor Reference 335 Merge Modules and Transforms 7. To change the destination for a merge module, select one or more merge modules and click Change. The Select Merge Module Destination Directory dialog box appears. 8. Select a directory and click OK. Select the destination directory for files in the merge module that are not installed to a predefined directory. If there are no files in the merge module’s Application directory and you want to leave this blank, select . 9. If the installation contains only one feature and the merge module is not configurable, the Merge Module File Directory dialog box contains a Finish button. Click Finish to complete this process. 10. If the installation contains multiple features, the Merge Module File Directory dialog box contains a Next button. Click Next to continue. The Merge Module Features dialog box appears. 11. To add this merge module to other features besides the one you selected in the Current Feature drop-down list, select them in the list box. You can select multiple features. If multiple features in the installation depend on this merge module, you should add it to all of them. Only one copy of the merge module is installed on the destination computer regardless of how many features include it. 12. If none of the merge modules you’re adding is configurable, the Merge Module Features dialog box contains a Finish button. Click Finish to complete the process. 13. If any of the merge modules you’re adding is configurable, the Merge Module Features dialog box contains a Next button. Click Next to continue. The Merge Module Configuration dialog box appears. 14. In the list box, select the name of the item to configure. If the Value drop-down list appears, select a value. If a text field appears, its label indicates the type of data you can enter. See Editing Merge Module Details on page 337. 15. If you’re adding more than one configurable merge module, a Next button appears at the bottom of the dialog box. Click Next and repeat the preceding step. The Next button changes to a Finish button when the Merge Module Configuration dialog box shows the last configurable merge module to be added. 16. Click Finish. The merge modules are added to this installation. If any of the merge modules contain dependencies, Windows Installer Editor tries to add them by looking in the default merge module directory. See Setting Dependencies for a Merge Module on page 323. If a dependency merge module cannot be found, you are prompted to download it. During compile, the merge modules are merged into the installation, so that the resulting .MSI contains both the changes defined in the standard installation as well as the changes defined in the merge modules. If your compile fails because of merge module errors, the errors appear in the Task List. To remove a merge module from an installation, select the merge module on the Merge Modules page and click Delete. If the module is included with more than one feature, it is only removed from the installation when you remove it from all features. Windows Installer Editor Reference 336 Merge Modules and Transforms See also: About the Merge Modules Page on page 334 Editing Merge Module Details To edit merge module details 1. Select Installation Expert > Merge Modules page. 2. From Current Feature, select the feature or condition that contains the merge module to edit. 3. Double-click a merge module. The Merge Module Details dialog box appears. It has one tab if you double-clicked a standard merge module and two tabs for a configurable merge module. 4. Click the Settings tab and change the dialog box’s settings as needed: „ Module Source Path To get the same merge module (with the same GUID) from a different location, enter a full path to the merge module. „ Destination Directory Select the destination directory for files in the merge module that are not installed to a predefined directory. If there are no files in the merge module’s Application directory and you want to leave this blank, select . „ Feature If the installation contains multiple features, a list of features appears. To add this merge module to other features, mark their check boxes. If multiple features in the installation depend on this merge module, you should add it to all of them. Only one copy of the merge module is installed on the destination computer regardless of how many features include it. 5. If the merge module is configurable, the Merge Module Details dialog box has a Configuration tab. To change configuration values: „ Click the configuration tab. „ In the list box, select the name of the item to configure. „ If the Value drop-down list appears, select a value. It will be either a bitfield value, a table, or text. If a text field appears its label indicates the type of data you can enter: Windows Installer Editor Reference  Text Value Enter any text.  Formatted Text Value Enter any text in Windows Installer formatted text format.  RTF Value Enter any text in rich text format.  Windows Installer Identifier Value Enter text in the format of a Windows Installer identifier, which may contain ASCII characters, digits, underscores, or periods, and must begin with either a letter or an underscore. 337 Merge Modules and Transforms For information on the format types listed above, see Text Format Types in the Windows Installer SDK Help.  Integer Value Enter any integer. See Integer Format Types in the Windows Installer SDK Help. For general information on configurable item types, see Semantic Types in the Windows Installer SDK Help or see Creating a Configurable Merge Module on page 328. Note During compile, if the installation contains a merge module that cannot be located on your system, you are prompted to download the merge module. This can happen if the installation was created on a different computer or if you have moved your merge modules directory. See also: Adding a Merge Module to an Installation on page 335 About Transforms A transform is a special kind of Windows Installer file (.MST) that customizes a Windows Installer installation. You use it to change the installation in some way for a specific group of end users. When you create a new transform, you must specify a standard installation database (.MSI) on which to base the transform. Typically, a transform works only with a specific installation. However, a universal transform can be applied to any installation. Transforms must be run from the command line. See Applying a Transform to an Installation on page 342. Because it would be unwieldy to install all options for all groups of end users, you can create one base .MSI, along with several transforms, each of which modifies the .MSI database at installation to customize it for different groups. Example: Suppose you are a system administrator who’s deploying a new version of workgroup software. You can use transforms to customize the installation for the needs of different departments. In each transform, you make changes to customize an installation for a particular department. Then during installation, you make sure that the appropriate transform is applied for each department. You can create the following types of transforms: z A transform based on changes that you make to an existing installation. This lets you change any aspect of an installation. See Creating a Transform Based on an Existing .MSI. z A universal transform containing limited changes that can be applied to any .MSI. See Creating a Universal Transform on page 341. z A language transform that lets you change the language on the dialog boxes that appear during installation. See Creating a Language Transform on page 266. Windows Installer Editor Reference 338 Merge Modules and Transforms z A transform that lets you change the way the installation runs. Use InstallTailor to run the installation and record the installation options you select. Example: Turn off a specific dialog box or set certain features to be on by default. See Creating a Transform with InstallTailor in the Wise Package Studio Help. z A transform that captures first use settings. First use settings are the changes made by an .MSI-based application the first time it is started on a computer after being installed. Create this type of transform with SetupCapture. See Using SetupCapture to Capture First Use Settings in the Wise Package Studio Help. Note The Languages pages is unavailable for transforms. Edit languages in the base .MSI. See also: Transforms in the Windows Installer SDK Help Setting Transform Details on page 340 Creating a Transform Based on an Existing .MSI You can change any aspect of an installation by creating a transform based on changes that you make to the installation. When you select a standard installation file, a temporary copy of that installation file opens in Windows Installer Editor, where you make the changes for the transform. This is the most flexible way to create a transform. Example: Suppose you want a transform that changes the application name, changes what registry entries are installed, and changes what system requirements are necessary to run the installation. Because these changes affect multiple areas of the product, you use this method to create the transform. To create a transform based on an existing .MSI 1. Select File menu > New. The New Installation File dialog box appears. „ From the Categories list, select Other Templates. „ In the Templates/Tools list, select the Transform icon, then click OK. The Open File dialog box appears. 2. Specify the .MSI on which this transform should be based. The transform opens with the exact settings of the installation on which it is based. 3. Make changes to the installation, such as adding files, or changing any other settings. Note If you add files when editing a transform, a .CAB file is created along with the transform. When you apply the transform, make sure the .CAB file, the original .MSI, and the .MST are all in the same directory. 4. Save the transform, using the .mst extension. The Transform Details dialog box appears. 5. Complete the Transform Details dialog box and click OK. Windows Installer Editor Reference 339 Merge Modules and Transforms See Setting Transform Details on page 340. The transform appears in the location you specified. See also: Applying a Transform to an Installation on page 342 Setting Transform Details The Transform Details dialog box, which appears when you save a transform file, contains options that flag error conditions of a transform. You set the error conditions to ignore. It also contains validation options. Normally, if the error conditions exist, errors are generated when the transform is applied to the standard installation. In most cases, if you create the transform using Windows Installer Editor, you can leave the defaults on the Transform Details dialog box. See MsiCreateTransformSummaryInfo in the Windows Installer SDK Help. z Base database (Read-only) This is the .MSI on which this transform is based. If this transform is applied to a database other than the one specified here, an error is generated during installation. z Suppress Transform Application Errors The following check boxes let you suppress certain errors if the transform tries to perform certain operations on the base database. In most cases, you can leave the default settings in this section. z „ Add existing row Suppress errors from occurring if the transform tries to add a row that already exists in the base .MSI. „ Delete missing row Suppress errors from occurring if the transform tries to remove a row that doesn’t exist in the base .MSI. „ Add existing table Suppress errors from occurring if the transform tries to add a table that already exists in the base .MSI. This is marked by default when you create a transform. „ Delete missing table Suppress errors from occurring if the transform tries to delete a table that doesn’t exist in the base .MSI. This is marked by default when you create a transform. „ Update missing row Suppress errors from occurring if the transform tries to update a row that doesn’t exist in the base .MSI. „ Code page mismatch Suppress errors from occurring if the code page (language) setting of the transform does not match that of the base .MSI. Validation The following check boxes and fields let you require certain conditions to be true for the transform to be applied to the base .MSI. Windows Installer Editor Reference 340 Merge Modules and Transforms „ Match Language Mark this if the language of the transform must match the language of the base .MSI. „ Match Product Mark this if the product code of the transform must match the product code of the base .MSI. „ Match Upgrade Code Mark this if the upgrade code of the transform must match the upgrade code of the base .MSI. „ Version Matching The version of the installation (set on the Product Details page) is in the form AA.BB.CCCC.DDDD, where AA represents the major version, BB represents the minor version, CCCC represents the update version, and DDDD represents the build version. Select an item in the list to have the version of the transform checked against the version of the base .MSI. If the versions do not match, an error is generated during installation. „ Version Relationship If you chose to check versions, specify what version relationship must be true in order not to generate an error. Creating a Universal Transform Normally, a transform is based on a specific .MSI and can change that base .MSI only. However, in some circumstances you might want to apply the same change to multiple .MSIs. (Example: to add a registry key that holds the company name.) To do so without creating multiple transforms, you can create a universal transform containing limited changes that can be applied to any .MSI. A universal transform is based on schema.msi (a blank installation database) instead of a specific .MSI. You do not create or assign features in a universal transform. Instead, everything you add to a universal transform is added to a top-level, hidden feature. You cannot make complex changes to installations with a universal transform (example: adding files). Therefore, only a limited set of Installation Expert pages are available in a universal transform. However, if you import the universal transform to the Software Manager database, distribute it to the share point directory, and then open it in Windows Installer Editor from the repository, then all the Installation Expert pages appear. This happens because, when you apply the transform to an .MSI or a blank database during the import, the copy in the repository is no longer a “universal” transform. GUIDs added to item names When you add the following items to a universal transform, a GUID is appended to the item name: Path variables Resources Environment variables Registry entries Properties Shortcuts You can see these GUIDs in the MSI tables. You cannot remove the GUIDs from the names. Windows Installer Editor Reference 341 Merge Modules and Transforms To create a universal transform 1. Select File menu > New. The New Installation File dialog box appears. a. From the Categories list, select Other Templates. b. In the Templates/Tools list, select the Universal Transform icon and then click OK. A new installation opens. 2. Complete the Installation Expert pages or otherwise edit the transform as needed. The following Installation Expert pages are available: General Information Page Path Variables page (see About Path Variables on page 312) Resources page (see Managing Binary Resources on page 101) Registry Page INI Files Page Shortcuts Page Environment Variables page (see Adding an Environment Variable on page 152) System Search page (see Performing a System Search on page 167) 3. Save the transform, using the .mst extension. The transform appears in the location you specified. See also: Applying a Transform to an Installation on page 342 About Transforms Applying a Transform to an Installation A transform must be applied to a base .MSI during installation using a command-line option; it cannot be applied beforehand. On the command line, type the following: msiexec /i Application.msi TRANSFORMS=TransformName.mst where Application.msi is the name of the .MSI, and TransformName.mst is the name of the transform. Because it is not practical to have end users type a line on the command line to run a transform, we suggest you use one the following methods to run the transform: z Write a batch file that runs the .MSI along with the appropriate transform. z Use the shortcut that was created with the transform. If you used InstallTailor to create a transform, a shortcut with the same name as the transform is created along with the transform file. This shortcut’s target is set to run the base .MSI and apply the transform. z Output the installation as an .EXE that launches an .MSI, which lets you send command-line options to the .MSI. Do this on the Build Options page. See the example below. Example: Applying a transform with an .EXE In this example, you output the installation as an .EXE that launches an .MSI and applies the transform. Windows Installer Editor Reference 342 Merge Modules and Transforms 1. Select Installation Expert > Releases page. 2. Create a new release. See Creating a New Release on page 182. 3. Select the Build Options page, select the new release from the Current Release drop-down list, and select .EXE that launches external .MSI from the .EXE Options drop-down list. 4. Compile the installation, which creates an .EXE, an .MSI, and an .INI file. 5. Open the .INI file, and add the following line: CmdLine=TRANSFORMS="TransformName.mst" /i where TransformName.mst is the name of the transform. When you double-click the .EXE file, it reads the .INI file of the same name. (Example: Application.EXE reads Application.INI.) When it runs the installation, it applies the command-line option specified in the CmdLine property and the transform is applied. These command-line options are passed to msiexec.exe, the Windows Installer executable. If you have multiple transforms, you can make multiple releases, and manually edit the .INI file for each release. Multiple Instance Installations Note Multiple instance installations are supported only by the versions of Windows Installer released with Windows XP SP1 (2.0.2600.1106), Windows Server 2003 (2.0.3790.0), or later. Windows Installer permits one instance of a product code to be installed per machine and one instance to be installed per user. To install multiple instances of a product without creating a separate installation for each instance, you can create instance transforms to change the product code for each instance. An instance transform changes the product code of an installation or patch and can isolate its data so that multiple instances of the application can be installed. Example: A Web server administrator can install multiple instances of a web site template on the same server to different virtual directories. Guidelines z Code the application so that it can locate resources based on the instance identifier. To create the instance identifier, you define an instance property in the base installation and have the instance transform set the property value. z Create a base installation. For each instance to be installed, create an instance transform. The base installation may install its own instance. z Each instance must have a unique product code and an instance identifier. z To isolate resources for each instance, install them into a location that depends on the instance identifier. For additional guidelines, see Authoring Multiple Instances with Instance Transforms in the Windows Installer SDK Help. Windows Installer Editor Reference 343 Merge Modules and Transforms Creating an instance transform 1. Open the base installation or patch for which you are creating an instance transform. 2. Select Installation Expert > Instance Transforms page. 3. In Instance Property, enter a property that will be replaced by a unique value in this instance of the installation. 4. Product Name is pre-filled with the product name from the Product Details page. If you change it here, it is changed on the Product Details page. 5. Click Add at the right of the page. The Instance Transform Details dialog box appears. 6. Complete the dialog box: „ Instance Property Value The base product name is incremented by 1 for each new instance transform. You can change this but the value must be unique. This value will replace the instance property and serve as the instance identifier. „ Product Code Windows Installer Editor generates a product code in the form of a GUID, which ensures that no two applications ever have the same product code. To change the product code, click Generate; typing or editing a GUID does not generate a valid GUID. „ Product Name The base product name is incremented by 1 for each new instance transform. You can change this but the name must be unique. The end user sees this name during installation and in the Add/Remove Programs dialog box. „ File Name The base product name is incremented by 1 for each new instance transform. You can change this but the name must be unique. This becomes the name of the transforms that is created. The transform is saved in the same directory as the base installation file. „ Change install directory to Instance Property Value? Mark this to change the value of the directory property INSTALLDIR to the value in the Instance Property Value field above. INSTALLDIR is the main installation directory for the application (example: Program Files\Application). This helps you isolate files for each instance. Example: Suppose you want to install test, beta, evaluation, and production versions of your application on the same destination computer. To do this, code your application to look for these instances. Add files to the installation. On the Instance Transforms page, add instances for each version of your application and define an instance property value for each (examples: 1, 2, 3, 4). Mark the Change install directory to Instance Property Value check box for each instance. When each instance transform is applied to the installation, files are installed into INSTALLDIR, but the value of INSTALLDIR changes based on the instance property value. (Examples: Program Files\Application1, Program Files\Application2, and so on.) If you did not mark the Change install directory to Instance Property Value check box, then files for each instance would be installed on top of each other in the same directory as for the base installation. Windows Installer Editor Reference 344 Merge Modules and Transforms 7. Click OK. The instance transform is added to the list on the Instance Transforms page. To edit an instance transform, double-click its name. The actual transform files (.MST) are created during compile. See also: Installing Multiple Instances on page 345 Installing Multiple Instances Note Multiple instance installations are supported only by the versions of Windows Installer released with Windows XP SP1 (2.0.2600.1106), Windows Server 2003 (2.0.3790.0), or later. Like other types of transforms, an instance transform must be applied to a base .MSI or patch during installation using a command-line option; it cannot be applied beforehand. On the command line, type the following: msiexec /i Application.msi TRANSFORMS=Instance.mst MSINEWINSTANCE=1 /qb where Application.msi is the name of the .MSI, and Instance.mst is the name of the transform. For additional examples, see Installing Multiple Instances with Instance Transforms in the Windows Installer SDK Help. See also: Multiple Instance Installations on page 343 Windows Installer Editor Reference 345 Chapter 14 Tools This chapter includes the following topics: z About Windows Installer Editor tools on page 346 z ApplicationWatch on page 347 z Convert SMS Installer or WiseScript Installation on page 347 z Import Visual Studio Projects on page 349 z MSI to WSI Conversion on page 352 z Package Validation on page 356 z Removing Files With Missing or Invalid Source Paths on page 357 About Windows Installer Editor tools Windows Installer Editor contains the following tools that perform specialized functions. You can start a tool in several ways (some options are available for specific tools only). z By selecting its name from the Tools menu. z By clicking its icon on the Tools toolbar. To display the Tools toolbar, select View menu > Tools. z By clicking its icon on the New Installation File dialog box, which puts the results from the tool into a new installation file. z By running it from the Wise Package Studio Workbench. Windows Installer Editor Tools z ApplicationWatch See ApplicationWatch in the Wise Package Studio Help. z Check Repository Files See Adding Files From the Wise Software Repository on page 113. (Not available in Standard Edition) z Convert SMS Installer or WiseScript Installation See Convert SMS Installer or WiseScript Installation on page 347. z Convert Source Paths See About source paths on page 305. z Import Visual Studio Projects z Move Components to Merge Module See Creating a Merge Module From Existing Components on page 326. z MSI to WSI Conversion z Package Distribution Windows Installer Editor Reference 346 Tools Copy a compiled installation to an FTP server, to a local area network, or to removable media. You can also perform an administrative installation to a shared network directory. In the Standard Edition, you also can distribute an installation to the share point directory. See Package Distribution in the Wise Package Studio Help. z Package Validation See About Package Validation in the Wise Package Studio Help. z Patch Creation See Patch Creation in the Wise Package Studio Help. z Remove Missing Files. See Removing Files With Missing or Invalid Source Paths on page 357. z Resolve Conflicts See Resolving Conflicts Individually in Windows Installer Editor on page 136. z Resolve Conflicts with Rules See Resolving Conflicts With Rules in Windows Installer Editor on page 135. z Software Manager Provides the interface for working with packages in the Software Manager database. See About Software Manager in the Software Manager Help. z UpgradeSync See UpgradeSync in the Wise Package Studio Help. z Visual MSIDiff™ See Comparing Windows Installer Files on page 74. ApplicationWatch ApplicationWatch™ monitors your computer as you execute an application or run an installation and determines which .DLL, .OCX, and .EXE files were accessed. It then adds these files to a new installation. You can use this tool for informational purposes or to facilitate the creation of a new installation. See Creating a Package with ApplicationWatch in the Wise Package Studio Help. Convert SMS Installer or WiseScript Installation Use the Convert SMS Installer or WiseScript Installation tool to convert the following types of setup programs into Windows Installer packages: z Microsoft SMS (.IPF or .EXE) z WiseScript (.WSE or .EXE) See Converting an SMS Installer or WiseScript Installation on page 348. Conversion Guidelines Following are guidelines for using Convert SMS Installer or WiseScript Installation: Windows Installer Editor Reference 347 Tools z You cannot convert all .EXEs—only those that were created with Microsoft SMS or a WiseScript-based product. z If you do not have the original installation project file, you can convert the compiled .EXE instead, because it contains an embedded copy of the script. z Because script installations are based on a different technology than Windows Installer, not all elements of the script are converted to Windows Installer format. „ Only the installation of files, registry changes, and other system changes are converted. „ Custom dialog boxes, custom logic, and other settings are not converted. z All the files that are available to the original installation must be available to the converted Windows Installer package at the same locations. z Components are converted to features, and Execute Program script actions are converted to Execute Program custom actions. z Some script actions can cause problems with the conversion process. z To edit an .IPF file without converting it to a Windows Installer package, open it in WiseScript Editor or WiseScript Package Editor. The WiseScript tools natively support Microsoft SMS files. Converting an SMS Installer or WiseScript Installation When you convert an SMS or WiseScript installation, its contents are added to the Windows Installer installation that is currently open. To convert an SMS Installer or WiseScript installation 1. Before you convert a script, open it and delete all Display Billboard, Display Graphic, and Add Icon script actions. 2. In Windows Installer Editor, open a new or existing installation. 3. Select Tools menu > Convert WiseScript Installation or SMS Installer. (In Visual Studio: Project menu > Convert WiseScript Installation or SMS Installer.) The Welcome page appears. 4. Complete the page: „ Installation Script Specify the full path of the .IPF or .EXE to convert. „ Extract Directory If you specified an .EXE file above, specify a directory in which to hold the extracted files and click Next. Files must be extracted from the .EXE before the conversion can begin. This becomes the source directory for the new package. 5. Click Next to start the conversion. The .IPF or .EXE is converted to Windows Installer format. When the conversion is finished, the Conversion Complete page appears. It shows the results of the conversion and lists any errors or problems that might have occurred. (Example: An error occurs when files that were referenced by the source installation cannot be found.) Windows Installer Editor Reference 348 Tools 6. To obtain a record of any conversion errors, click Save Errors or Print Errors. 7. Click Finish. More errors might appear at this point, which have to do with saving in Windows Installer format. If a file that is part of a merge module is added, the Files in Merge Modules dialog box appears. It prompts you to add the merge module and, if necessary, download it. See Adding Merge Modules Instead of Files on page 112. 8. Open the resulting package in Windows Installer Editor to view the converted file and to resolve reported problems. Pages in Installation Expert, such as the Files page, are populated based on the contents of the source installation. If you converted an .IPF, files are referenced from their original locations. If you converted an .EXE, files from the converted installation are stored in and referenced from the extract directory that you specified above. See also: Convert SMS Installer or WiseScript Installation on page 347 Import Visual Studio Projects The Import Visual Basic, Visual C#, or Visual J# tools let you import a Visual Basic, C#, or J# project file into an installation file. You specify information about the project, and the tool extracts information, such as source file paths, and integrates it into a new or existing installation. See Importing an Installation From a Visual Studio Project on page 350. z These tools only support projects of these types: Microsoft Visual Basic 5 Microsoft Visual Basic 6 Microsoft Visual Basic .NET, version 2003 or earlier Microsoft C#, version 2003 or earlier Microsoft J#, version 2003 or earlier z These types of files are supported: .VBP, .VBPROJ, .CSPROJ, .VJSPROJ, or .SLN. z When you import a solution, any project types other than those listed above are skipped. If your VB, C#, or J# projects depend on files that are in projects that are skipped, the installation might not work. z For Visual Basic projects, the Visual Basic Import tool only supports file types of the Standard EXE project type. z For Visual Basic .NET, C#, or J# projects, if a project file has dependencies on other projects, you cannot import just the project file. You must import the entire solution that contains the project and its dependencies. z There is no link between a project or solution and the installation you create for the project or solution. If your solution or project is updated with new files, you must make those changes in the installation manually. Windows Installer Editor Reference 349 Tools z These tools are not designed to set up a remote automation or a DCOM™ server automatically. Importing an Installation From a Visual Studio Project Use the following procedure to create a Windows Installer package from a Visual Basic, Visual C#, or Visual J# project, version 2003 or earlier. See Import Visual Studio Projects on page 349. To import from a Visual Studio project 1. Do one of the following: „ Select File menu > New. On the New Installation File dialog box, select Import Tools from the Categories list, and in the Templates/Tools list, double-click the type of project to import. This creates an installation that contains only the information from the imported installation. „ Select Tools menu > Import Tools and select the type of project to import. This adds the imported installation’s information to the current installation file. The Project or Solution File dialog box appears. 2. In Project or Solution File, specify the path to the project or solution file and click Next. „ (Visual Basic .NET, C#, or J# projects.) The Select Configuration dialog box appears. This displays the configurations that are in the solution or project, which correspond to build configurations in your Microsoft development environment. a. Select the configuration to import. b. To be prompted at the end of this wizard to select which assembly dependencies get added to which feature, clear Automatically add Assembly Dependencies without prompting. Otherwise dependencies are added silently. „ (Visual Basic 5 or 6 project.) The Select Visual Basic Directory dialog box appears. Specify the directory on your computer where Visual Basic 5 or 6 is installed. This directory contains the support files that must be included in the installation because they are needed by the Visual Basic program. 3. Click Next on the Select Configuration or Select Visual Basic Directory dialog box. The Scanning Project Files page appears. During or after the scan, additional prompts and pages might appear: „ If the project is out of date or missing, a prompt appears. You can try to rebuild the project from this tool, or open the development environment and rebuild the project from there. „ If the project has a reference to another project, an error message appears and the import ends. Restart the import and select the solution file (.SLN) that contains both projects. „ If dependency files (.DEP) for Win32 target files are missing, the Dependency Files Not Found page appears. Dependency files list referenced files. This page usually does not apply to .NET projects, which use assembly manifests instead of dependency files, unless the .NET project depends on a COM .DLL that has a Windows Installer Editor Reference 350 Tools dependency. If the dependency files cannot be read, then the files they refer to cannot be added to the installation you are creating. If any files on the Dependency Files Not Found page are crucial to this installation: a. Cancel the import. b. Locate the files and move them to the System or System32 directory. c. Restart the import. 4. Click Next. If target files were not found during the scan, the Files Not Found page appears. Files might be missing if the configuration of the solution that you selected has not been built. Missing files will cause compile errors in the installation that results from this import process. Otherwise, the Installation Files page appears. 5. If the Files Not Found page appears: a. Select a file and click Browse to locate missing files. b. Click Next. The Installation Files page appears. 6. The Installation Files page lists the files that were detected during the scan and will be added to the installation. 7. To add or remove files in the installation, click Add or Delete and then click Next. The Application Installation Information page appears. 8. 9. Complete the dialog box: „ Name Enter a name for the installation. This overwrites the Name field on the Product Details page. If you don’t want to overwrite the current installation name, leave this blank. „ Installation Directory Enter the default installation directory where files from this import should be placed. All added files are placed in this directory in Installation Expert > Files page. Click Finish. 10. Additional dialog boxes might appear: „ (Visual Basic .NET, C#, or J# projects.) If you cleared the Automatically add Assembly Dependencies without prompting check box, the Assembly Dependencies dialog box appears. It prompts you to select which dependencies to add to the installation. See Assembly Dependencies on page 117. „ If a file that is part of a merge module is added, the Files in Merge Modules dialog box appears. It prompts you to add the merge module and, if necessary, download it. See Adding Merge Modules Instead of Files on page 112. Windows Installer Editor Reference 351 Tools „ If a file that is used by a package in the Wise Software Repository is added, the Files in Repository dialog box appears and prompts you to add a version of the file that is in the repository. See Adding Files From the Wise Software Repository on page 113. The project is integrated into an installation file, which contains all the information it needs to install the project. Options are pre-filled on the Files and Product Details pages. As with any installation, you should compile and test the installation thoroughly to ensure it operates correctly. MSI to WSI Conversion Use MSI to WSI Conversion to convert existing .MSI files to Windows Installer project files (.WSI). An .MSI is a distributable installation. Because an .MSI typically encapsulates all the files in the installation, it is larger and takes longer to save. A project file (.WSI) compiles to an .MSI. Instead of compressed files, a .WSI contains paths to source files. A .WSI file is smaller and you can set multiple options for the output of the .MSI. For information on the differences between project files and installation database files, see Project Files and Database Files on page 60. If you have an installation .MSI, you can open and edit it in Windows Installer Editor. However, to take advantage of some Windows Installer Editor features, you can convert the .MSI to a project file. See: Converting an .MSI to a .WSI File on page 352 Specifying Merge Module Source Directories on page 353 Specifying File Source Directories on page 355 Converting an .MSI to a .WSI File By default, MSI to WSI Conversion extracts files and merge modules from an .MSI to a directory you select. It then creates a project file (.WSI) that references those files and merge modules. The project file, in turn, can be edited in Windows Installer Editor, and then compiled to a new .MSI file. Alternately, instead of extracting files from the .MSI and creating the new .WSI to point to them, you can redefine source paths so they point to source files already on your computer. In this case, the files from the .MSI are not extracted, but are substituted by files on your computer. A .WSI file records the files and merge modules that should be compiled into the .MSI by storing source paths. (To see the source path for a file in the installation, display its File Details dialog box.) When you open a .WSI and compile, Windows Installer Editor reads the source paths, and then compiles them into the .MSI. Running MSI to WSI Conversion involves redefining source paths, either by extracting files and merge modules from the .MSI itself, or by redefining the source paths to point to files and merge modules that already exist on your computer. To convert an .MSI to a .WSI 1. Open an .MSI. If a message appears asking you to convert this Windows Installer database to a Wise project file, click Yes. Otherwise, select Tools menu > MSI to WSI Conversion. The Welcome page appears. Windows Installer Editor Reference 352 Tools 2. In New Source Directory, specify the directory to which all files and merge modules in the .MSI will be extracted. In the converted .WSI file, all source paths will point to the files and merge modules located in this directory. You can override this directory for individual files and merge modules later in this wizard. If the .MSI contains any merge modules, the Merge Module Sources page appears; otherwise, the File Sources page appears. 3. On the Merge Module Sources page, you can change the default for extracting merge modules, which is to extract them from the .MSI into the default source directory you specified on the Welcome page. To accept the default, click Next. You can change the default. See Specifying Merge Module Source Directories on page 353. 4. On the File Sources page, you can change the default for extracting files, which is to extract them from the .MSI into the default source directory you specified on the Welcome page. To accept the default, click Next. You can change the default. See Specifying File Source Directories on page 355. The Create WSI File page appears. 5. In New .WSI File, specify the path of the new .WSI to create. Do not select a directory that already contains an .MSI of the same name, because when you compile this .WSI file, it overwrites any .MSI of the same name that resides in the same directory. 6. Click Finish. If any source files or associated .CAB files are not in the location specified in the .MSI, they are listed on the Files Not Found page and source paths are not created for those files. You must find them and add them to the new .WSI. The new .WSI is created at the location you specified, the current .MSI is closed, and the new .WSI is opened. Compile and test this installation thoroughly before deploying. Specifying Merge Module Source Directories During MSI to WSI Conversion, merge modules are extracted from the .MSI to the default source directory specified on the Welcome page. The source files are pulled from the source directory when the .WSI is compiled. On the Merge Module Sources page, you can override the default source directory for specific merge modules. See MSI to WSI Conversion on page 352. You can override the default source directory in the following ways: z Change Source Directory Extract merge modules to a directory other than the default directory. z Replace With Local File Select merge modules on your computer to replace the merge modules in the .MSI. The merge modules you select on your computer must have identical GUIDs as those you are replacing. z Search Module Directories Search for merge modules by GUID in all the merge module directories defined in Wise Options. Windows Installer Editor Reference 353 Tools z Reset to Default After changing the source path through any of the above methods, you can reset a merge module to its default, which is to extract to the default source directory. To change the directory to which merge modules will be extracted 1. On the Merge Module Sources page, select one or more merge modules. 2. Click Change Path and select Change Source Directory. The Select Directory dialog box appears. 3. Select a directory and click OK. The merge modules you selected will be extracted to this directory instead of the default source directory. 4. Complete the .MSI to .WSI Conversion wizard. To replace merge modules with merge modules on your computer by specifying the merge module location 1. On the Merge Module Sources page, select one or more merge modules to replace. 2. Click Change Path and select Replace With Local File. If multiple merge modules are selected, the Select Directory dialog box appears. If one merge module is selected, the Choose Replacement Merge Module dialog box appears. 3. Select either a directory or a specific merge module: „ On the Select Directory dialog box, select the directory that contains replacement merge modules for all the merge modules you have selected and click OK. Merge modules are matched by GUID, a unique identifier attached to Windows Installer files, rather than by name. If the search is unsuccessful, a dialog box lists the merge modules that were not found. „ On the Choose Replacement Merge Module dialog box, specify the merge module to replace the selected merge module. You must specify a merge module whose GUID matches the GUID of the original merge module; otherwise an error occurs. The Source column on the Merge Module Sources page changes to Local to indicate that a local merge module will be used instead of the merge module in the .MSI. 4. Complete the MSI to WSI Conversion wizard. To replace merge modules with merge modules on your computer by searching 1. On the Merge Module Sources page, select one or more merge modules to replace. 2. Click Change Path and select Search Module Directories. A search of module directories is performed. Merge Module directories are defined in Wise Options. Merge Modules are matched by GUID, a unique identifier attached to Windows Installer files, rather than by name. The first found instance is used. The Source column changes to Local to indicate that local merge modules will be used instead of merge modules from the .MSI. If the search is unsuccessful, a dialog box lists the merge modules that were not found. 3. Complete the MSI to WSI Conversion wizard. Windows Installer Editor Reference 354 Tools Specifying File Source Directories During MSI to WSI Conversion, files are extracted from the .MSI to the default source directory specified on the Welcome page. The source files are pulled from the source directory when the .WSI is compiled. On the File Sources page, you can override the default source directory for specific files. See MSI to WSI Conversion on page 352. You can override the default source directory in the following ways: z Change Source Directory Extract files to a directory other than the default directory. z Replace With Local File Select files on your computer to replace the files in the .MSI. This option lets you search your computer for matching files. z Reset to Default After changing the source path through any of the above methods, you can reset a file to its default, which is to extract to the default source directory. To change the directory to which files will be extracted 1. On the File Sources page, select one or more files. 2. Click Change Path and select Change Source Directory. The Select Directory dialog box appears. 3. Select a directory and click OK. The selected files will be extracted to this directory instead of the default source directory. 4. Complete the MSI to WSI Conversion wizard. To replace one file with a file on your computer 1. On the File Sources page, select a file to replace. 2. Click Change Path and select Replace With Local File. The Choose Replacement File dialog box appears. 3. Specify a file to replace the selected file. The Source column on the File Sources page changes to Local to indicate that a local file will be used instead of the file in the .MSI. 4. Complete the MSI to WSI Conversion wizard. To replace multiple files with local files by searching 1. On the File Sources page, select multiple files to replace. 2. Click Change Path and select Replace With Local File. The Replace With Local Files dialog box appears. 3. Select an option from Search Options and click OK. „ Selected Directory Only Search only the current directory for the selected files. „ Selected Directory and Sub-Directories Search the current directory and all its subdirectories for the selected files. Windows Installer Editor Reference 355 Tools Note For the following two options, the Destination Path column is appended to whatever directory you select. Example: Suppose you are repackaging Application.msi, and you have it installed in C:\Program Files\Application, you would select the C drive, then select Selected Directory Contains Destination Directory Structure and click OK. If you selected the Application directory itself, it would result in searching C:\Program Files\Application\Program Files\Application because the Destination Path column on the File Sources page is appended to the end of the directory you select. „ Selected Directory Contains Destination Directory Structure Select this if a directory on your computer or network contains the application’s files in a directory structure that mimics the directory structure in which they will be installed. You might have this directory if you have the application installed, or you might just have a directory that contains the same directory structure as that of the installed application. Using this option, the Duplicate Files Details dialog box might appear if the installation you are converting contains instances of duplicate files. An installation can contain multiple copies of a file and the copies can be set to install to the same directory. Example: Suppose the installation Application.msi contains both a Windows NT version and a Windows 98 version of the file pshop.dll. Only one file gets installed, depending on the operating system the installation runs on. In an installation with duplicate files, MSI to WSI Conversion cannot change the paths to point to your local computer, because your local computer only contains one copy of the file. For these files, either leave them set to the default, which will extract all copies of the file from the .MSI, or individually replace them with the appropriate files from your computer. „ Selected Directory Contains Administrative Install Select this if a directory on your computer or network contains an administrative installation. Select the same directory you selected as the root directory for the administrative installation. An administrative installation mimics the directory structure of the installed application and allows for network installations. Unlike a normal installation, an administrative installation has a copy of every file that the installation contains. This option pulls files from the directory structure created by an administrative installation. Files are matched by name. The first found instance is used. The Source column on the File Sources page changes to Local to indicate that local files will be used instead of files from the .MSI. If the search is unsuccessful, a dialog box lists the files. Package Validation Package Validation checks a Windows Installer package for errors based on rules in one or more validation modules. It validates installation files (.MSI and .WSI), merge modules (.MSM and .WSM), and transforms (.MST). See the following topics in the Wise Package Studio Help: z Validating a Package z Customizing Validation Modules Windows Installer Editor Reference 356 Tools z Adding a Validation Module to Package Validation z Adding a Rule That Calls a Custom Action z Adding a Validation Rule Set Removing Files With Missing or Invalid Source Paths When you compile an installation that contains files with missing or broken source paths, the compile fails. The Remove Missing Files tool reduces compile errors by searching an installation for such files and letting you remove those files from the installation. If you decide to leave a file in the installation, you can fix its source path. Paths to files in an installation can break if you: z Move files that are part of the installation to a new directory on your computer or network. z Move the installation file itself from your computer to another computer. z Use relative paths and then move the installation file. z Rename a directory. An installation can also contain broken paths if it was created with SetupCapture. Sometimes, SetupCapture captures references to temporary files that are deleted after the installation is finished. To remove files with missing or broken source paths 1. Access the Remove Missing Files tool in either of the following ways: „ Perform a local compile of an installation that contains files with missing or broken source paths. „ Select Tools menu > Remove Missing Files. The Welcome page appears. 2. Click Next. The installation is searched and the Results page appears. 3. Select the files to remove from the installation and click Next. The Removing Files page appears. 4. If you ran this tool from the Tools menu, the Compile This Installation check box appears when the removal process finishes. Clear the check box to continue without compiling. 5. Click Finish. If you marked the Compile This Installation check box, or if you ran this tool from within the compile process, the installation is compiled. 6. If you compiled the installation but you did not remove all the files with missing or broken source paths, the Welcome page reappears. Do one of the following: „ Step through the pages and remove the remaining files. „ Click Cancel on the Welcome page, fix the source paths, and recompile. Windows Installer Editor Reference 357 Tools To fix source paths If a file in the installation has a missing or broken source path, but the file should remain in the installation, you must fix its source path before you can compile successfully. Do either of the following: z z Select Installation Expert > Files page. a. In the lower-left list box, navigate to the directory that contains the file. b. In the lower-right list box, double-click the file to display the File Details dialog box. c. On the General tab, enter the correct path in Source Pathname. Use the Convert Source Paths tool. See Source Paths in an Installation on page 315. Windows Installer Editor Reference 358 Chapter 15 Setup Editor This chapter includes the following topics: z About Setup Editor on page 359 z Product Tab on page 361 z Features Tab on page 363 z Components Tab on page 368 z Tables Tab on page 376 About Setup Editor Setup Editor provides an in-depth view of all changes that you make to an installation. You can make those changes in Setup Editor or Installation Expert. However, there are certain advanced tasks that you can perform in Setup Editor only: z Edit the text on installation dialog boxes. z Create components and assign them to features. z Build complex conditions that must be met for installation to occur. z Select dialog boxes to appear during maintenance installations (uninstalls). z Edit the raw table data of the Windows Installer database. Note This documentation does not discuss Windows Installer tables, functions, or properties. Before you edit raw table data, read the Windows Installer SDK help for that table. On the Tables tab, click a table and press F1. Windows Installer Editor Reference 359 Setup Editor Setup Editor window in Windows Installer Editor The upper-right pane displays contents of the item selected in the left pane. Double-click items to edit them. The left pane lists items for the selected tab. Expand folders to see their contents in the upper-right pane. To show or hide empty items, right-click and select Hide Empty Folders/ Items. The lower-right pane contains context-sensitive help. To hide the help, select View menu and clear Help Pane. Note Check the right-click menu frequently when you are working in Setup Editor. It provides access to most of the tasks that you can accomplish in Setup Editor. Setup Editor tabs Product Set and edit the summary information to be stored with the installation file, properties that are used during compile, and launch conditions that determine whether the installation can run on the destination computer. See Product Tab on page 361. Features Add, edit, and delete features. Assign components to features; add and remove components to and from features; and arrange the features of the installation. See Features Tab on page 363. Dialogs Select and customize dialog boxes the installation uses. See Using the Dialogs Tab on page 402. Tables Edit tables in the .MSI database. You can access most of the data in these tables through Installation Expert pages or other tabs of Setup Editor. Deleting, adding, or editing table data directly is not recommended unless you are an experienced Windows Installer developer with a clear understanding of Windows Installer database technology. See Tables Tab on page 376. Windows Installer Editor Reference 360 Setup Editor Components Add, edit, and delete individual components of the installation. Each component is one action the installation performs. Example: installing a file, changing the registry, and so on. See Components Tab on page 368. Module This tab appears only when you are in a merge module file. Add, edit, and delete the components, files, registry entries, and other installation modifications contained in the merge module. See Available Tabs and Pages in Merge Modules on page 321. Product Tab On the Product tab in Setup Editor, you set and edit the following information for an installation: Summary Use the Summary icon to set the value of a summary item. End users can see the summary information by right-clicking the compiled .MSI or .EXE in Windows Explorer and selecting Properties. See Specifying Summary Information on page 362. Properties Use the Properties icon to add, edit, and delete properties in an installation. Properties are variables that are initialized by the installation and are used by Windows Installer. The property values can change during run time. Some of the properties that appear are required Windows Installer properties, so use caution in editing or deleting them. See: Properties on page 391 Creating a New Property on page 393 Properties in the Windows Installer SDK Help Launch Conditions Use the Launch Conditions icon to create new launch conditions and edit existing launch conditions. Launch conditions are system requirements that must be met on the destination computer for the installation to proceed. See Setting a Requirement by Creating a Launch Condition on page 166. Windows Installer Editor Reference 361 Setup Editor Specifying Summary Information Use the Summary icon in Setup Editor to set the value of a summary item. End users can see the summary information by right-clicking the compiled .MSI or .EXE in Windows Explorer and selecting Properties. Note In Windows Vista, the file Properties dialog box does not contain summary information. For information on summary items, see Summary Property Descriptions in the Windows Installer SDK Help. You can use the Release Settings page to override the value of an existing summary item or edit customized summary items. See Customizing Summary Items for a Release on page 186. To view all available summary items, click the Summary icon in the left pane on the Product tab. A list of summary items appears in the upper-right pane, and you can edit an item by changing its value. You cannot create or delete summary items, because they are defined by Windows Installer. The following summary items are named differently in the Windows Installer SDK Help: Name in Setup Editor Name in Windows Installer SDK Source Type Word Count Minimum Installer Version Page Count Package Code Revision Number Template Summary Template The Template Summary determines the target platform of the compiled .MSI. See How to Specify the Target Platform on page 62. To set the value of a summary item 1. In Setup Editor > Product tab, click the Summary icon. 2. In the upper-right pane, double-click a summary item. The Summary Details dialog box appears. In a transform, some summary items are not editable because they keep the value of the base .MSI. 3. In Value, enter a new value. 4. Click OK. You also can edit several of the summary items in Installation Expert > General Information page. See General Information Page on page 89. Windows Installer Editor Reference 362 Setup Editor Features Tab The Features tab lets you manipulate an installation’s features and all corresponding items. It displays a tree structure that lists all components, merge modules, files, registry entries, and other installation items associated with each feature. See Working With Components and Features on page 492. Features you add in Installation Expert are displayed on this tab. However, the features’ conditions are not displayed in Setup Editor. By default, the Features tab displays only items that are in the installation. Example: If the installation contains a file, a Files icon appears. If you have not added any items to the installation, only the Features and Complete icons appear. (Complete is the default feature that is included in new installations.) Working with the features tree z To display all empty items, right-click in the left pane and select Hide Empty Folders/ Items. z To display a feature’s contents, click the feature in the left pane. The contents appear in the upper-right pane. z To display all items in a feature, click the feature’s Combined icon. All items appear in the upper-right pane. z To display all items in a feature grouped by type, expand the feature’s Combined icon and click the type icon. z To expand or collapse a selected feature’s children, use the right-click menu. z To customize how items appear in the features tree, right-click in the left pane and select Customize View. In the Customize View dialog box that appears, mark the check boxes of the items to display, and rearrange items by clicking Move Up or Move Down. z To quickly organize the items on the Features tab: „ Drag a feature to a new parent feature. „ Drag components from one feature to another. Adding an item to a feature Do either of the following in Setup Editor > Features tab: z Right-click the feature name. Select New and the item to add. z Expand the feature and expand the Combined folder. If necessary, show empty folders. Right-click the icon for a particular item and select New. If an icon does not appear, right-click and use the Customize View dialog box to show the icon. Items you can add on the Features tab Most of these items can also be added in Installation Expert. Feature See Adding a New Feature on page 94. Component assignment See Assigning a Component to a Feature on page 364. Windows Installer Editor Reference 363 Setup Editor Folder See Creating a Folder in Setup Editor on page 367 Duplicate file entry See Creating Duplicate File Entries on page 367 Environment variable See Adding an Environment Variable on page 152. File association See Advertising Icon on page 366. See Adding File Associations on page 153. File See Adding Files to an Installation on page 109. INI file See Creating and Editing .INI Files on page 148. ODBC source, driver, or translator See Adding an ODBC Item on page 159. Registry key See Adding Registry Keys on page 140. Service control See Controlling Services on the Destination Computer on page 158. Service See Adding a Service to the Destination Computer on page 156. Shortcut See Adding a Shortcut to an Installation on page 150. Remove Registry operation See Removing Registry Entries From the Destination Computer on page 142. Remove Files operation See Removing a File From the Destination Computer on page 120. Move Files operation See Copying and Moving Files on the Destination Computer on page 122. Copy Files operation See Copying and Moving Files on the Destination Computer on page 122. You also can view merge modules that are included in specific features. See Modules Icon on page 365. Assigning a Component to a Feature The Components icon in Setup Editor lets you: z Assign components to features z Remove (unassign) components from features z Move components between features z Add new components and edit the details of existing ones See Adding and Editing a Component on page 370. When a component is assigned to a feature, the component is installed on the destination computer only if the feature is installed. The Components icon on the Features tab shows items in each component. To access installation items organized by component, use the Components tab. See Components Tab on page 368. Windows Installer Editor Reference 364 Setup Editor To assign a component to a feature 1. In Setup Editor > Features tab, right-click a feature and select New > Component Assignment. The Assign Components to Feature dialog box appears. The dialog box lists all components in the installation, except those already assigned to the currently selected feature. 2. Select one or more components to add to the feature. 3. Click OK. You can add the same component to more than one feature; the component is in the installation only once. Example: If your application includes a grammar check feature and a spell check feature that both depend on the same file, you might want to assign that file’s component to both features. That way the file is available even if only one of the features is installed on the destination computer. To unassign a component 1. In Setup Editor > Features tab, expand the folder for the feature that contains the component to unassign. 2. Click the Components icon. All components for the feature appear in the upper-right pane. 3. In the upper-right pane, right-click a component and select Unassign. Components that are not assigned to any feature are not installed on the destination computer. To move a component to a different feature 1. In Setup Editor > Features tab, expand the folder for the feature that contains the component to move. 2. Click the Components icon. All components for the feature appear in the upper-right pane. 3. In the upper-right pane, click a component and drag it to a different feature in the left pane. The component is moved to the new feature. See also: Features Tab on page 363 Modules Icon The Modules icon in Setup Editor displays merge modules included in specific features. However, you cannot add merge modules here. To add or edit merge modules in an installation, use Installation Expert > Merge Modules page. See Adding a Merge Module to an Installation on page 335 and Editing Merge Module Details on page 337. To view merge modules in a feature 1. In Setup Editor > Features tab, expand a feature. Windows Installer Editor Reference 365 Setup Editor 2. Click the Modules icon. The merge modules in the selected feature appear in the upper-right pane. If the Advertising icon does not appear, right-click and select Hide Empty Folders/ Items. See also: About Merge Modules on page 320 Features Tab on page 363 Advertising Icon The Advertising icon in Setup Editor contains information that Windows Installer uses when publishing and assigning applications to the destination computer. The Advertising icon: z Shows the entry points that are installed if you are using advertising to make applications available to end users. z Lets you edit and create new file associations. See Adding File Associations on page 153. Note The Advertising icon might contain other advertising items besides file extensions but you can add extensions only. z Lets you view and edit AppID and ProgID information. Advertisement, which is a way to deploy applications in large organizations, is available with Windows Installer, but only for supported platforms. See Advertisement and Platform Support of Advertising in the Windows Installer SDK Help. To view or edit AppID or ProgID information 1. In Setup Editor, on the Components or Features tab, expand the Advertising icon under a feature or component and select the AppID or ProgID folder. If the Advertising icon does not appear, right-click and select Hide Empty Folders/ Items. 2. In the upper-right pane, double-click an AppID or ProgID. The AppID or ProgID dialog box appears, which displays information from the AppID or ProgID table. 3. You can edit the entries in the Value column. See AppID Table or ProgID Table in the Windows Installer SDK Help. Warning Editing table data directly is not recommended unless you are an experienced Windows Installer developer with a clear understanding of Windows Installer database technology. See also: Features Tab on page 363 Windows Installer Editor Reference 366 Setup Editor Creating a Folder in Setup Editor The Create Folder icon in Setup Editor lets you add a new empty directory under an existing directory. You also can create directories on the Files or Web Files pages in Installation Expert, where you can also use wildcards to add files to directories automatically. See Editing Settings for Automatic Updating on page 119. To create a new folder 1. In Setup Editor, on the Components or Features tab, right-click a component or feature and select New > Create Folder. The Create Folder Details dialog box appears. 2. From Directory, select a parent directory. 3. At the end of the existing path, type \ (backslash) followed by the name of the new directory. Example: To create a folder named Sample in the Program Files directory, the Directory field should contain Program Files\Sample. 4. Click OK. The Create Folder entry appears in the upper-right pane. 5. You can add permissions to the new folder. See Setting Permissions for Files and Directories on page 125. See also: Installation Directories on page 108 Features Tab on page 363 Creating Duplicate File Entries Duplicate files are files that must be copied to more than one location during installation. According to Windows Installer rules, you cannot install the same file multiple times. The Duplicate File icon in Setup Editor lets you: z Place the same file in different directories. z Place a file in the same directory with a different name. See DuplicateFile Table in the Windows Installer SDK Help. You can create a duplicate file entry only for files that are already in the installation. Note Duplicate files are not created for .NET assemblies added to both the application directory and the Global Assembly Cache. Instead, they are treated as separate components. To add a duplicate file entry 1. In Setup Editor, on the Components or Features tab, right-click a component or feature and select New > Duplicate File. 2. The Duplicate File Details dialog box appears. Windows Installer Editor Reference 367 Setup Editor 3. 4. Specify the following: „ Existing File Specify the path for the file to be duplicated. „ Dest. Directory Specify the directory on the destination computer in which the duplicate file should be installed. To add a subdirectory to the directory you selected, click New Folder and enter a folder name. „ Long File Name Enter a name for the duplicate file. „ Short File Name (Optional.) Enter a short file name in 8.3 format to accommodate systems that don’t support long file names. Click OK. The duplicate file entry appears in the upper-right pane. If you added the duplicate file to a different feature and a different directory than the original file, then a new component is created for the duplicate file. You cannot have two components install the same file to the same destination directory. If the file is already set to be installed to the same directory by a component assigned to another feature, you are prompted to create a component assignment to the current feature. If you do this, then any future changes to the component will affect all features to which it is assigned. To edit a duplicate file entry, double-click its name. To delete it, right-click its name and select Delete. See also: Features Tab on page 363 Components Tab The Components tab lets you manipulate an installation’s components. It displays a tree structure that lists all files, registry entries, and other installation items contained in each component. It also indicates any component errors. Installation Expert automatically creates the appropriate components for each item you add and organizes them according to a component rule set you select. Example: You can always create a new component for each new file added to the installation, or you can group related resources, such as help files, into one component. See Component Rules on page 48. By default, the Components tab displays only items that are in the installation. Example: If the installation contains a file, a Files icon appears. If you have not added any items to the installation, only the Components icon appears. Working with the components tree z To display all empty items, right-click in the left pane and select Hide Empty Folders/ Items. Windows Installer Editor Reference 368 Setup Editor z To display a component’s contents, click the component in the left pane. The contents appear in the upper-right pane. You also can expand the component so that its contents appear in the components tree. z To expand or collapse a selected component’s children, use the right-click menu. z To customize the icons that appear in the components tree, right-click in the left pane and select Customize View. In the Customize View dialog box that appears, mark the check boxes of the items to display, and rearrange items by clicking Move Up or Move Down. z To quickly organize the items on the Components tab: „ Drag an item from the upper-right pane to a different component on the left pane. „ In the left pane, drag an entire component item group from one component to another. Adding an item to a component Do either of the following in Setup Editor > Components tab: z Right-click the component name. Select New and the item to add. z Expand the component. If necessary, show empty folders. Right-click the icon for a particular item and select New. If an icon does not appear, right-click and use the Customize View dialog box to show the icon. Items you can add on the Components tab Most of these items can also be added in Installation Expert. Component See Adding and Editing a Component on page 370. Folder See Creating a Folder in Setup Editor on page 367. Duplicate file entry See Creating Duplicate File Entries on page 367. Environment variable See Adding an Environment Variable on page 152. File association See Advertising Icon on page 366. See Adding File Associations on page 153. File See Adding Files to an Installation on page 109. INI file See Creating and Editing .INI Files on page 148. Isolated component See Isolating a .DLL With an .EXE on page 374. ODBC source, driver, or translator See Adding an ODBC Item on page 159. Published component See Adding Published Components on page 375. Registry key See Adding Registry Keys on page 140. Service control See Controlling Services on the Destination Computer on page 158. Service See Adding a Service to the Destination Computer on page 156. Windows Installer Editor Reference 369 Setup Editor Shortcut See Adding a Shortcut to an Installation on page 150. Remove Registry operation See Removing Registry Entries From the Destination Computer on page 142. Remove Files operation See Removing a File From the Destination Computer on page 120. Move Files operation See Copying and Moving Files on the Destination Computer on page 122. Copy Files operation See Copying and Moving Files on the Destination Computer on page 122. See also: Component Errors on page 370 Moving Items Between Components on page 373 About the Key Path on page 374 Component Errors As you work on the Components tab, Setup Editor continually monitors components for common errors. When it detects an error, it changes the color of the component’s icon to red. To view a component error message 1. In Setup Editor > Components tab, right-click the red component icon and select Show Errors. Typical causes of component errors z The component has an empty key path but contains files, registry entries, or ODBC data sources. z The component has more than one executable (.EXE, .DLL, .OCX). z The same file is assigned to multiple components. z A shortcut is assigned to the component, but the key path for the shortcut is not a file. z Registry keys are created in HKEY_CURRENT_USER, but the key path is not for a registry key in HKEY_CURRENT_USER. See also: Components Tab on page 368 Adding and Editing a Component Warning To work with items on the Components tab, you should be proficient in the Windows Installer development environment. See Windows Installer Components in the Windows Installer SDK Help. Windows Installer Editor Reference 370 Setup Editor Installation Expert automatically creates the appropriate components for each item you add to an installation. However, you can add and edit components yourself in Setup Editor > Components tab. z To edit a component, double-click its name. z To edit multiple components, first select the Components icon in the upper-left pane. In the upper-right pane, select components, right-click, and select Details. On the Multi-Component Details dialog box, you can edit a subset of the fields found in the Component Details dialog box. z To delete or rename a component, use the right-click menu. To add a new component 1. In Setup Editor > Components tab, right-click and select New > Component. The Component Details dialog box appears. 2. Complete the dialog box: „ Component Enter a name for the new component. Components generated by Installation Expert have automatically generated names that usually reflect the first file added to a particular directory. „ Directory Enter the directory on the destination computer where the files in this component will be installed. To create a new folder, click New. „ GUID (Optional.) To replace the automatically-generated GUID (globally unique identifier) for this component with a new one, click Generate. „ Condition Enter the condition required to install this component. To always have the component installed, leave this blank. To enter a condition that must evaluate to true before the component can be installed, click Build. The Condition Builder appears. See Creating Conditions With Condition Builder on page 387. For some conditions, you might need to add a special merge module that addresses a limitation of Windows Installer. See Using Conditions With Features on page 100. When you add a 64-bit component to the installation, the 64-bit component check box below is marked automatically and the condition (VersionNT64) is added to this field. This must be the first condition in the condition string. If you add conditions, add them after the (VersionNT64) and enclose them in parentheses. Example: (VersionNT64) AND (TEST = 1) As long as the 64-bit check box is marked, you cannot delete the (VersionNT64) condition. This ensures that the component is installed only on a 64-bit platform. „ Windows Installer Editor Reference Run Location Select the location from which the component should run: 371 Setup Editor „ „  Run Locally The component is installed and runs from the destination computer’s hard drive. This setting overrides the corresponding feature’s attribute.  Run from Source The component runs from the media or the server that contains the installation. This setting overrides the corresponding feature’s attribute.  Run from Source or Locally The component takes on the feature’s attribute. Key Path Type Select the type of item Windows Installer should use as a key path:  File Key Path Use a file as the component’s key path.  Registry Key Path Use a registry entry as the component’s key path.  ODBC Data Source Key Path Use an ODBC data source as the component’s key path. Key Path Select the item Windows Installer should use as a key path. The drop-down list shows files, registry entries, or ODBC data sources that are included in the component, depending on your selection in the Key Path Type field. See About the Key Path on page 374. „ Always increment shared .DLL count Mark this to increment the count of applications using .DLLs in this component when installing it, even if the component is already installed. If a component is installed to the Global Assembly Cache, you cannot increment the reference count. „ Leave installed on uninstall Mark this to leave the component installed when its feature is uninstalled. „ Check condition during reinstall (Transitive) Mark this to check the condition not only on the original installation but also when the component is re-installed. „ Never overwrite if key path exists Mark this to prevent the component from being installed if the item specified as the key path already exists. „ 64-bit component When this is marked, it designates the component as 64-bit. The target directory and the component must both be either 32-bit or 64-bit. If one is 32bit and the other is 64-bit, a warning message appears, giving you the option to change the target directory to match the component. Example: If this check box is marked and the Directory is Program Files (x86), you are prompted to change this target directory to its 64-bit counterpart, Program Files. This is marked automatically for 64-bit .EXE or .DLL files and 64-bit registry keys that you add to the installation. „ Windows Installer Editor Reference Self-register key path file before compile Mark this so that, each time you compile, the file referenced in the Key Path field is re-registered, the registration information is rescanned, and any new information is added to the installation. 372 Setup Editor If you clear this check box, then the file is not self-registered; instead, registration information is scanned from its type library and added to the installation. Registering the file enables its advertising information to be drawn into the installation—if the file is not registered, then this advertising information might not be present on the current computer, which means it cannot be automatically added. See How Self-Registration Information is Captured on page 133. „ Rescan advertising information during compile Mark this to gather advertising information from the registry for the file referenced in the Key Path field each time you compile the installation. This overrides the Default to rescan advertising for new components check box in Wise Options for this component. „ Import REG File Specify a .REG file that contains registry information about the key path file. This information is read into the component each time you compile. Example: If the programmer who creates the key file for this component is not the author of the installation, the programmer can place all required information into a .REG file and give this file to the installation author for inclusion into the component. You can use WiseComCapture.exe to create this .REG file. See Using WiseComCapture.exe on page 133. „ 3. Extract advertising information from registry file Mark this to take information from the .REG file and places it into the advertising tables instead of the registry tables if possible. Click OK on the Component Details dialog box. If the installation has only one feature, the component is added to that feature. If the installation has more than one feature, the Select Feature(s) to Assign Component to dialog box appears. 4. Mark one or more check boxes for the features to assign the new component to and click OK. The component appears in the upper-right pane. See also: Components Tab on page 368 Moving Items Between Components Warning To work with items on the Components tab, you should be proficient in the Windows Installer development environment. See Windows Installer Components in the Windows Installer SDK Help. On the Components tab, you can move items from one component to another. The procedure below works for all types of items, and also warns you when a key path must be changed. For files and registry entries, you can drag between components, but you are not warned if a key path is changed. Windows Installer Editor Reference 373 Setup Editor To move items between components 1. In Setup Editor > Components tab, navigate to an item so that it appears in the upper-right pane. 2. In the upper-right pane, select one or more items, right-click, and select Move. Note If an item you select is the component’s key path, a message informs you that the item will become the destination component’s key path, even if that component already has a key path. To reset the destination component’s key path, click Yes. To cancel the move, click No. You can reset key paths manually by right-clicking an item and selecting Set as Key. The Move to a Different Component dialog box appears. 3. Click the component to move the selected item to. 4. Click OK. If the component icon is colored red after you move an item to it, the change you made causes an error. Right-click the component and select Show Errors to see a description of the problem. See also: Components Tab on page 368 About the Key Path To determine whether a specific component is installed, Windows Installer looks for the component’s key path rather than looking for every item in the component. If it finds the item that is specified as the key path, it assumes that all other items that make up the corresponding component, and therefore, the component, are installed. Some items require a key path (example: advertised shortcut). Setup Editor indicates key paths by placing a yellow key icon over the item’s icon. To set an item as key path z In Setup Editor > Components tab, right-click the item and select Set as Key. OR z Select the item as key path on the Component Details dialog box. See Adding and Editing a Component on page 370. See also: Components Tab on page 368 Isolating a .DLL With an .EXE To prevent .DLL conflicts, you can associate a .DLL file in the installation with a specific .EXE file in the installation. Then Windows Installer automatically associates the .DLL with the .EXE, even if the destination computer already has a .DLL with the same name installed. See Isolated Components in the Windows Installer SDK Help. Windows Installer Editor Reference 374 Setup Editor Add the .DLL to the System32 directory, as you normally would, and then create an isolated component that moves the .DLL to your application’s directory. Note Before you isolate a .DLL with an executable, make sure that you have added all files to the installation, especially .EXE and .DLL files. To isolate a .DLL with an .EXE 1. In Setup Editor > Components tab, right-click a .DLL and select New > Isolated Component. The Isolated Component Details dialog box appears, where you select a file for isolation from the feature that contains the component. „ If the key path for the current component is not an .EXE, the drop-down list shows all .EXEs in the containing feature that are key paths of .DLL files. „ If the key path for the current component is an .EXE, the drop-down list shows all files from the containing feature that are key paths other than the current component. 2. From Associated File, select the .EXE to assign to this .DLL. 3. Click OK. The isolated component entry appears in the upper-right pane. To edit it, double-click its name. To delete it, right-click its name and select Delete. See also: Components Tab on page 368 Adding Published Components Published components let applications written specifically for Windows Installer refer to one or more components by a single identifier. Example: Do this to add the same published component to each component in a feature. At run time, the installation only needs to check for one published component to determine if the feature is installed. See PublishComponent Table and Qualified Components in the Windows Installer SDK Help. To add published components 1. In Setup Editor > Components tab, right-click a component and select New > Published Component. 2. The Publish Component Details dialog box appears. 3. Complete the dialog box: „ Publish GUID (Optional.) To replace the automatically-generated GUID (globally unique identifier) for this component with a new one, click Generate. „ Feature Select the feature to have published. „ Component Select the component to have published. Windows Installer Editor Reference 375 Setup Editor 4. „ Qualifier Enter a text string to distinguish multiple forms of the same component. „ Application Data Enter a text string that describes the qualified component, that is, the combination of component and qualifier. This string can be displayed to the end user. Click OK. The published component entry appears in the upper-right pane. To edit it, double-click its name. To delete it, right-click its name and select Delete. See also: Components Tab on page 368 Tables Tab The Tables tab lists every table in the Windows Installer database. Most of this data is accessible in Installation Expert or in the other tabs of Setup Editor. The Tables tab lets you edit existing table data, add new data, add new tables, and delete tables. In addition to standard Windows Installer tables, the Tables tab also lists Wise tables. See Wise Tables on page 504. Reasons to edit tables directly z To use the few features, such as ReserveCost, that are not available anywhere but on the Tables tab. z To add a table to store data that is non-Windows Installer standard. Example: If you create a custom action that stores data, you must create a new table in which to store it. Or you might write a .DLL that reads the new table and performs certain actions. z To edit the data created in Installation Expert or on the other tabs of Setup Editor. Warning Deleting, adding, or editing table data directly is not recommended unless you are an experienced Windows Installer developer with a clear understanding of Windows Installer database technology. Editing table data might cause unexpected, undesirable behavior, including damage to the installation. We cannot provide technical support for problems arising from table editing. Windows Installer Editor Reference 376 Setup Editor Tables tab in Setup Editor Key field. Table headings. Column information List of tables in the Windows Installer database. Table contents. Working with tables By default, the left pane of the Tables tab lists all the tables in the Windows Installer database, even those that don’t contain data. z To hide empty tables, right-click in the left pane and select Show Empty Tables. To redisplay the empty tables, right-click and select Show Empty Tables again. z To display a table’s contents, click its name in the left pane. The table’s contents appear in the upper-right pane, arranged in columns by field. The column width and sort order are retained when you leave the Tables tab. The top heading row of the table displays field names. Key fields are indicated by a key symbol. By convention, database columns that are external keys take the name of the primary key column with an added underscore character. Example: An external key to the File column of the File table is always named File_. z An optional, second heading row shows the field’s data type, string length if applicable, and whether the field can be null. To display or hide the second heading row, right-click the table and select Column Info. z Initially, tables are not sorted. To sort a table, click the heading for the column to sort. z You can select rows in tables, then copy and paste them into any program that supports SYLK format, such as Excel. You also can paste the rows into a text editor, where they appear as comma-delimited text. See: Creating a New Table on page 378 Creating a New Row in a Table on page 379 Editing Existing Tables on page 379 Searching for Table Data on page 380 Windows Installer Editor Reference 377 Setup Editor Finding Validation Errors on page 380 Editing Binary Data in the Icon Table on page 381 Creating a New Table Warning Deleting, adding, or editing table data directly is not recommended unless you are an experienced Windows Installer developer with a clear understanding of Windows Installer database technology. Editing table data might cause unexpected, undesirable behavior, including damage to the installation. We cannot provide technical support for problems arising from table editing. To create a new table 1. In Setup Editor > Tables tab, right-click and select Create Table. The Create Table dialog box appears. 2. In Table Name, enter the name of the new table. 3. Click Add to add a field. The Field Definition dialog box appears. 4. Complete the dialog box: „ Field Name Enter the name of the field. „ Data Type Specify whether this field is a long integer, short integer, or string. „ String Length If this field is a string, enter the length of the string in this field. The default is 255 characters; a length of 0 indicates no length limit. „ Nullable Mark this to indicate that this field can be null. „ Primary Key Mark this to indicate that this field is a primary key in this table. A table can have more than one primary field. „ Localizable Mark this to indicate that this field should be translatable. If you distribute this installation in another language, the data in this field will be translated. „ Value Range Min/Value Range Max Enter minimum and maximum allowed values for an integer field. These fields are available only when the data type is a long or short integer. „ Value Set Enter a list of acceptable values for this field, separated by semicolons. „ Key Table Select the table to which this column is linked. Example: The SelfReg table has a column File_ that is linked to the File table. „ Key Column Select the column in the linked table. Example: The SelfReg table File_ column is linked to the File column in the File table. Windows Installer Editor Reference 378 Setup Editor „ Category Select the type of information stored in this column. „ Description Enter a short text description of the information stored in this column. 5. Click OK on the Field Definition dialog box. 6. Continue to add fields as needed. 7. On the Create Table dialog box, click OK to add the table. See also: Tables Tab on page 376 Creating a New Row in a Table on page 379 Creating a New Row in a Table Warning When you add a row to a table this way, additional rows are not added to related tables. Be sure you understand relational databases and Windows Installer database technology before adding rows. To create a new row in a table 1. In Setup Editor > Tables, in the left pane, select a table. 2. In the upper-right pane, right-click the row above which the new row should appear and select New Row. A message appears. 3. Click OK. A new row is added to the table. 4. Click in each field to select it for entry. (If you click away from the row, you might have to triple-click to access a field.) Editing Existing Tables On the Tables tab, you can directly edit any data in the Windows Installer database. You also can delete rows from tables and delete tables. Warning Deleting, adding, or editing table data directly is not recommended unless you are an experienced Windows Installer developer with a clear understanding of Windows Installer database technology. Editing table data might cause unexpected, undesirable behavior, including damage to the installation. We cannot provide technical support for problems arising from table editing. To edit table data 1. In Setup Editor > Tables tab, in the left pane, select a table. 2. In the upper-right pane, do one of the following: „ Windows Installer Editor Reference Click the field to change and press Enter or F2. 379 Setup Editor „ 3. If a field is already active, press Tab to move from left to right or Shift+Tab to move from right to left within the table. Type new data or change the existing data. Some table columns have drop-down lists that you can use for editing. Example: The drop-down list for the Feature_Parent column in the Feature table lets you select a new parent for the current feature. Drop-down lists for columns that contain formatted data type show the properties from the Property table. You can either select from the list or enter a new property. To delete a row from a table In Setup Editor > Tables tab, in the upper-right pane, right-click a row and select Delete. To delete a table: 1. In Setup Editor > Tables tab, in the left pane, right-click a table and select Delete Table. 2. Click Yes on the warning dialog box that appears. If you later add an item that requires the deleted table, Windows Installer Editor automatically recreates the table. Searching for Table Data On the Tables tab, you can search for and replace strings. Search the entire database, a single table, or a single column. Example: The product name changes and you need to find and replace it everywhere it occurs. Find and Replace commands are in the Edit menu. See also: Finding Validation Errors on page 380 Finding Text in MSI Script on page 440 Assigning a Component to a Feature on page 364 Finding Validation Errors On the Tables tab, you can search for tables that contain errors and you can search for individual validation errors. These are quick ways to search for validation errors while you are working on a package. A validation error occurs when the data in a field does not comply with the requirements assigned to the field. Examples: null fields in columns that are not nullable, foreign key mismatches, and strings that are too long for the field. Alternatively, when a project is complete and all changes are saved, you can run the Package Validation tool to check the entire package against a set of rules, such as the Windows Installer SDK Internal Consistency rules. To find tables that contain errors In Setup Editor > Tables tab, right-click the left pane and select Check Tables. Windows Installer Editor Reference 380 Setup Editor The installation is searched for tables that contain errors. Any table that contains an error is shown in red in the left pane and the error becomes a task in the Task List. You can use the Task List to review the errors (see Using the Task List on page 24) or you can click a red table name and use the Find Error menu item to find the row that contains the error. See the following procedure. To find individual validation errors in a database 1. In Setup Editor > Tables tab, right-click and select Find Error. The Find dialog box appears. 2. In the Direction section, mark either Up or Down to specify the search direction. 3. Click Find Next. If the database contains one or more validation errors, the first one is highlighted in red in the upper-right pane. 4. To find the next error, click Find Next again. To find validation errors in a package z Select Tools menu > Package Validation. Package Validation appears. See About Package Validation in the Wise Package Studio Help. When validation is complete, the View / Correct dialog box appears. It lists validation issues that represent areas where the package might not comply with the specifications in the validation modules you selected. The icon to the left of each issue indicates the issue type. When you close Package Validation, validation errors that were not corrected are added to the Task List. See also: Tables Tab on page 376 Searching for Table Data on page 380 Editing Binary Data in the Icon Table On the Tables tab, you can edit binary data in the Icon table. Most items in this table are graphics (example: shortcut icons). You can export binary files for editing and then import them back into the installation. Exported binary files are formatted as Windows bitmaps. The Binary table also contains binary data. To edit binary data in the Binary table, use the Resources page. See Managing Binary Resources on page 101. Warning Deleting, adding, or editing table data directly is not recommended unless you are an experienced Windows Installer developer with a clear understanding of Windows Installer database technology. Editing table data might cause unexpected, undesirable behavior, including damage to the installation. We cannot provide technical support for problems arising from table editing. Windows Installer Editor Reference 381 Setup Editor To edit binary data 1. In Setup Editor > Tables tab, click the Icon table. The table’s data appears in the upper-right pane. You can change the data in the Name fields as you would in any other table. 2. In the Data column, click a binary field (displayed as {binary data}) and press F2 or Enter. The Edit Binary Data dialog box appears. 3. 4. 5. In the Action section, mark an option: „ Read binary data from file Import binary data from an external file. „ Write binary data to file Export binary data to an external file so it can be edited. In File Name, do one of the following: „ If you are reading from an external file, specify the full path of a file to read. „ If you are writing to a file, enter the full path of the file. By default, this file is exported to the directory where the Windows Installer database file is stored. To export to a different directory, specify a full path, such as C:\TEMP\FILENAME. Click OK. Windows Installer Editor Reference 382 Chapter 16 Using Conditions and Properties This chapter includes the following topics: z Conditions on page 383 z Properties on page 391 Conditions Conditions are like expressions: they evaluate to a true or false value. You associate conditions with different elements of an installation such as features, components, actions, dialog boxes, and dialog box controls to determine whether something happens or not. Based on whether the condition is true or not, you can determine whether to: z Allow the installation to continue z Install certain features and components z Display certain dialog boxes or dialog box controls z Execute custom actions you add in MSI Script When you create a new installation, conditions are already created throughout the installation where appropriate. You often use properties inside conditions. Properties are named values that are any of the following: z Predefined in Windows Installer Editor. z Defined by Windows Installer, by you in the installation file, or by the end user during installation. z Based on the system configuration of the destination computer. See Properties on page 391. See also: Where Can You Use Conditions? on page 383 Condition Guidelines on page 385 Examples of Conditions on page 386 WiseFixConditions on page 386 Creating Conditions With Condition Builder on page 387 Where Can You Use Conditions? Conditions on the Features page You can add conditions on the Features page. These conditions appear in the Current Feature drop-down list that appears at the top of pages in the Feature Details page group. Using the Current Feature drop-down list, you can add system changes to a Windows Installer Editor Reference 383 Using Conditions and Properties condition or feature. These changes can include adding files, registry entries, services, and ODBC. Items that you add to a feature are installed on the destination computer only if the feature is installed. Items that you add to a condition are installed only if the feature is installed and the condition is true. See Using Conditions With Features on page 100. Conditions for actions You can set conditions on the actions in MSI Script by using If Statements. MSI Script contains standard Windows Installer actions, dialog boxes, and custom actions. In general, you should not set or change conditions for standard actions, but you’ll probably set conditions for any custom actions or dialog boxes you create. See About MSI Script on page 436 and Guidelines for Custom Action Conditions on page 451. Launch conditions Launch conditions are system requirements that must be met for the installation to proceed. You set launch conditions in the Launch Conditions icon in Setup Editor > Product tab. When you set system requirements on the System Requirements page, they are added to the Launch Conditions icon. Example of a possible launch condition: ScreenX >= 800 AND ScreenY >= 600 This condition specifies that the screen resolution must be 800 x 600 in order for the installation to proceed. ScreenX and ScreenY are Windows Installer properties that are set according to the screen resolution on the destination computer. See ScreenX Property and ScreenY Property in the Windows Installer SDK Help. Conditions for controls on dialog boxes In Setup Editor > Dialogs tab, you can use conditions with dialog box controls. Controls are the items that appear on dialog boxes, such as text boxes, radio buttons and check boxes. Because many conditions are already set on the default installation dialog boxes, you can use those for examples of how you might use conditions in dialog boxes. View them in Setup Editor > Dialogs tab. z Conditions that set the state of controls You can create a condition that sets a control to be enabled, disabled, shown, hidden, or set as the default control. Example: If you double-click the Next button on the License dialog in Setup Editor > Dialogs tab, then on the Conditions tab on the Properties dialog box you see three conditions attached to the Next button. These conditions determine the state of the Next button. They are all based on the value of a property named Accept. The Accept property is set to “Yes” when the end user clicks the I accept the license agreement radio button. As soon as Accept equals “Yes”, the Next button becomes enabled and set to the default control. (To see how the Accept property is set, double-click the radio buttons on the License dialog, then view the Items tab on the Properties dialog box.) Windows Installer Editor Reference 384 Using Conditions and Properties z Conditions attached to control events You can attach an event to a control. The event can have an associated condition. You might attach events to Next buttons that specify what event happens if the Next button is clicked. Example: Click the Installation Type dialog in Setup Editor > Dialogs tab. Doubleclick the Next button and click the Events tab on the Properties dialog box. Depending on what the property InstallMode is set to, different dialog boxes appear, as specified in the NewDialog events. If the end user selects the Custom radio button, InstallMode is set to Custom, and the Select Feature dialog appears. If the end user does not select the Custom radio button, the Start Installation dialog appears. The value of the InstallMode property is determined by the end user’s radio button choice. Conditions attached to components You can attach conditions to components in Setup Editor > Components tab. (You can also add them to components on the Features tab.) If you attach a condition to a component, the component is installed only if the condition is true. To add or change a condition attached to a component, right-click a component icon and select Details. Use the Condition field on the Component Details dialog box that appears to add or change a condition. If you add conditions to the Features page, and add items to the conditions using the Current Feature drop-down list at the top of Installation Expert pages, then some of the components on the Components tab will have conditions set. Note If you add a component condition that checks the installed state of a component or feature, add the merge module CondFix.msm to the installation. This merge module fixes a Windows Installer limitation. See WiseFixConditions on page 386. Condition Guidelines Before creating conditions, become familiar with the following Windows Installer guidelines for creating conditions. z z You can use the following types of values inside a condition: „ The name of the property. This is case-sensitive. You do not need to enclose the property name in square brackets. See Using Properties in Conditional Statements in the Windows Installer SDK Help. „ Any integer between -32,767 and 32,767. You cannot use floating point values. „ String literal. Enclose text in quotation marks. Properties that have not been set evaluate to an empty string “” (null). „ Environment variable. Precede the variable name with a percent symbol (%). If a property is set, it evaluates to true in a Boolean expression. Example: If the installation runs on a destination computer whose operating system is Windows 2000, XP, 2003, or Vista, the property VersionNT is set to the version number of the operating system. However, if you want to set a condition to check for these operating systems, you can enter the condition as VersionNT. If VersionNT is set to anything at all, even 0, the condition evaluates to true. Windows Installer Editor Reference 385 Using Conditions and Properties z When adding conditions to the Launch Conditions icon, you can add conditions that check properties or environment variables, but you cannot add conditions that check the installed state of a component or feature. z You might need to include the merge module CondFix.msm, that fixes certain Windows Installer limitations related to component conditions. See WiseFixConditions on page 386. Property names and values, by default, are case-sensitive. To make them caseinsensitive, precede the operator with ~= instead of =. z Example: If you enter the condition REMOVE=ALL but the value of the REMOVE property is currently “All” (with upper- and lowercase), the condition is false. To write the condition so that it is case-insensitive, type the condition as follows: REMOVE~=”All” z Environment variable names are not case-sensitive. z Non-existent property values are treated as empty strings and evaluate to false. z Operators and precedence are the same as in the BASIC and SQL languages, but you can override precedence with parentheses. z Arithmetic operators and floating point numeric values are not supported. For details, see Conditional Statement Syntax in the Windows Installer SDK Help. Examples of Conditions You can build conditions using property names, environment variables, and feature and component states. Conditions can contain both Windows Installer properties and properties that you create. A complete list of Windows Installer properties is available in Property Reference in the Windows Installer SDK Help. Condition The condition is true if SystemLanguageID=1033 The installation is running on a computer whose language is set to English. REMOVE~=”ALL” The product is being uninstalled. The ~ makes the condition case-insensitive. NOT Installed The product is being installed for the first time. CHECKBOX_IS_MARKED You make a check box and associate the property CHECKBOX_IS_MARKED with it, and during installation, the end user marks the check box. VersionNT The installation is running on Windows 2000, XP, Server 2003, or Vista. VersionNT AND NOT Installed The installation is running on Windows 2000, XP, Server 2003, or Vista, and the application is not yet installed. WiseFixConditions Windows Installer Editor contains a special merge module, WiseFixConditions (CondFix.msm), that fixes certain Windows Installer limitations: Windows Installer Editor Reference 386 Using Conditions and Properties Add CondFix.msm to an installation if you add a component condition that checks the installed state of a component or feature. The Windows Installer Editor installation places CondFix.msm in the default merge modules directory, or you can download it with the Download Redistributables wizard. This merge module appears on the Select Merge Module dialog box when you add a merge module on the Merge Modules page. If you don’t see it, you have marked the Do not show merge modules from the Default Merge Module Directory check box in Wise Options. See Setting Merge Module Directories on page 42. See also: Downloading Redistributable Files on page 29 Using Conditions With Features on page 100 Creating Conditions With Condition Builder Use the Condition Builder to build conditions that test the installed state of components and features and the value of properties and environment variables. You can access the Condition Builder from different areas of Windows Installer Editor. See Where Can You Use Conditions? on page 383. Condition Builder dialog box Scrolling text box. Enter or build conditions here. Click to check the syntax of conditional statements. Operator buttons Mark Ignore Case to make conditions case-insensitive. This inserts a ~ when you click a comparative operator button. Lists Operator buttons Most of the operator buttons in the middle of the dialog box, starting with the = button, are described in Conditional Statement Syntax in the Windows Installer SDK Help. They include logical, comparative, string, and bitwise operators. z Use the ~ button before an operator to make the condition case-insensitive. Windows Installer Editor Reference 387 Using Conditions and Properties z Use the () buttons to enclose parts of the condition, which changes the order of precedence. z Use the " button to enclose literal text. Lists z Fields Select the kind of item the condition checks. You can check the installed state for features and components, and you can check the value of properties and environment variables. z Values If you selected Environment Variable or Property in the Fields list, double-click the name of an environment variable or a property to insert it into a condition. See Checking the Value of a Property on page 388 or Checking the Value of an Environment Variable on page 389. Note The following two lists let you check the current or future installed state of a feature or component. See Checking If and How a Feature or Component is Currently Installed on page 390 and Checking If and How a Feature or Component Will Be Installed by This Installation on page 390. z State Use this list only to check the installed state of a component or feature. Action refers to what occurs during installation, and Installed refers to the current state of the destination computer. z Install/Action state Use this list only to check the installed state of a component or feature. Absent means the feature or component is not installed, Advertised means it is advertised, Local means it is installed on the local hard drive, and Source means it is installed to run from the installation source. See also: Condition Guidelines on page 385 Examples of Conditions on page 386 Checking the Value of a Property To check whether a property evaluates to true You do not need to use the Condition Builder. Enter the name of the property in the Condition field, wherever it appears. Example: To create a condition that checks whether a Windows NT operating system is running, you enter the condition, VersionNT, which evaluates to true when VersionNT is set. For examples of where the Conditions field appears, see Where Can You Use Conditions? on page 383. To check whether the property equals a certain value 1. Open the Condition Builder. Windows Installer Editor Reference 388 Using Conditions and Properties See Creating Conditions With Condition Builder on page 387. 2. In the Fields list, click the Property folder. The Values list displays a list of properties and directories that are initialized by this installation. More properties appear than in other lists of properties, such as the Properties icon in Setup Editor > Product tab. It includes Windows Installer properties that are set at run time based on system configuration, such as ScreenX and ScreenY. For information on Windows Installer properties, see Property Reference in the Windows Installer SDK Help. 3. In the Values list, double-click the name of the property. If the property you want does not appear in this list, enter the property name in the condition list box at the top of the Condition Builder dialog box. 4. Click the = button. An equals sign is inserted in the condition list box. 5. Click in the condition list box after the equals sign and enter a value. 6. Click OK. Checking the Value of an Environment Variable Environment variables are system or end user variables that are set by the operating system running on the destination computer. They contain values specific to that computer. Note This procedure lets you check the value of an environment variable. To read the value of an environment variable into a property, use the Set Property type of custom action. Enter [%ENVIRONMENT_VARIABLE_NAME] in the Property Value field on the Custom Action Target dialog box while creating the action (brackets required). To check the value of an environment variable 1. Open the Condition Builder. See Creating Conditions With Condition Builder on page 387. 2. In the Fields list, click the Environment Variable folder. The Values list displays the environment variables that currently exist on your computer. If the environment variable you want is not in the list, enter its name in the condition list box at the top of the Condition Builder dialog box. For information on available environment variables, consult Microsoft Windows developer documentation. 3. In the Values list, double-click the name of the environment variable. 4. Click the = button. 5. Click in the condition list box after the equals sign and enter a value. 6. Click OK. Windows Installer Editor Reference 389 Using Conditions and Properties Checking If and How a Feature or Component is Currently Installed A feature or component might be installed to run locally, from the source, or advertised, which are all options you can set when installing a component or feature. Note You cannot add this type of condition to the Launch Conditions icon in Setup Editor > Product tab. Also, when you add this type of condition, add the merge module CondFix.msm to the installation. This merge module fixes a Windows Installer limitation. See WiseFixConditions on page 386. To check if and how a feature or component is currently installed 1. Open the Condition Builder. See Creating Conditions With Condition Builder on page 387. 2. In the Fields list, click the Feature or Component folder. 3. In the Values list, click the name of the feature or component. 4. In the State list, double-click Installed. 5. Click the = button. 6. In the Install/Action state list, double-click one of the following to check the current installation state of the feature or condition: „ Absent Not installed. „ Advertised Installed in an advertised state. „ Local Installed locally. „ Source Installed to run from installation source. When you finish, a condition appears in the condition list box. Based on the choices you make, the appropriate Windows Installer codes are inserted. Example: !Complete = 3 7. Click OK. Checking If and How a Feature or Component Will Be Installed by This Installation A feature or component might be installed to run locally, from the source, or advertised, which are all options you can set when installing a component or feature. Note You cannot add this type of condition to the Launch Conditions icon in Setup Editor > Product tab. Also, when you add this type of condition, add the merge module CondFix.msm to the installation. This merge module fixes a Windows Installer limitation. See WiseFixConditions on page 386. Windows Installer Editor Reference 390 Using Conditions and Properties To check if and how a feature or component will be installed by this installation 1. Open the Condition Builder. See Creating Conditions With Condition Builder on page 387. 2. In the Fields list, click the Feature or Component folder. 3. In the Values list, click the name of the feature or component. 4. In the State list, double-click Action. 5. Click the = button. 6. In the Install/Action state list, double-click one of the following to check the action state of the feature or condition: „ Absent Will not be installed by this installation. „ Advertised Will be installed in an advertised state. „ Local Will be installed locally by this installation. „ Source Will be installed to run from installation source by this installation. When you finish, a condition appears in the condition list box. Based on the choices you make, the appropriate Windows Installer codes are inserted. Example: &Complete = 3 7. Click OK. Properties Properties are variables that are used by Windows Installer during installation. You often use properties inside conditions. You can hard-code the value of a property, but you can also make properties more flexible by manipulating them at run time based on user input, system configuration, or other situations. Properties are set by the following methods and in the following order: Included in the installation database Some properties are included in all installations you create in Windows Installer Editor. These include required Windows Installer properties, properties that are used on the installation dialog boxes, predefined Wise properties, and the directories listed in the Directory table on the Tables tab in Setup Editor. You can see these properties by clicking the Properties icon in Setup Editor > Product tab. See Build Properties on page 508. Windows Installer Editor Reference 391 Using Conditions and Properties Created by you in the installation database You can create properties in the Properties icon in Setup Editor > Product tab. Also, some dialog boxes that contain a property drop-down list also contain a New button with which you can create a new property. See Creating a New Property on page 393. Set on the command line Properties can be set on the command line. Set by Windows Installer at run time Some properties are set by Windows Installer according to the configuration of the destination computer. See Command Line Options For WFWI.EXE on page 235. See Property Reference in the Windows Installer SDK Help. Set by end user input You can author the user interface so that end user input sets property values. Example: You can associate a property name with a dialog box control. The results of the end user’s action on the dialog box control are put into the property. Because each method of setting properties can be overridden by the methods that come after it, property values might change during installation. You can see the value of properties during installation in the Properties pane of Debugger for Windows Installer, which appears when you click the Debug button. Properties that are authored into the installation database’s Property table, which appear in the Properties icon in Setup Editor > Product tab, represent initial values of properties. Changing the Properties table after installation begins has no effect on the values of properties that are stored in memory. During installation, properties can be changed only by actions that are running in immediate execution mode. User interface actions are in immediate execution mode, and you can set your custom actions to run in immediate execution mode. See also: How Do You Use Properties? on page 392 Creating a New Property on page 393 Property Reference on page 508 How Do You Use Properties? You can use properties in the following ways: To interact with the user You can attach properties to controls on dialog boxes, which puts the results of the control into the property. Then, use the property in a condition. Example: In Setup Editor > Dialogs tab, the Installation Type dialog has a set of radio buttons. The radio buttons are associated with a property named InstallMode, and based on the value of InstallMode, the Next button displays a different dialog box. Double-click the radio buttons and the Next button, to view their Properties dialog boxes. See About Dialog Controls on page 407. Windows Installer Editor Reference 392 Using Conditions and Properties In conditions You can use properties inside conditions. You do not need to enclose the property name in brackets. Conditions determine whether something happens or not. As formatted text on dialog boxes To display the value of a property or write the value of a property to a file, you must enclose the property name in square brackets. Example: [Property]. Example: In Setup Editor > Dialogs tab, right-click a dialog box name, and select Details. The Dialog Details dialog box appears with [ProductName] [_WiseDialogSuffix] in the Dialog Title. To display a bracket, you must enclose it in square brackets. Example: [[]. To change the way the installation is run You can set properties that change the way Windows Installer runs. Example: To force or suppress a restart at the end of installation, you could create a Set Property custom action that sets the Windows Installer property named REBOOT. Creating a New Property Note Before you create a new property, search the Windows Installer SDK Help to make sure the property name is not already used by Windows Installer. See Property Reference in the Windows Installer SDK Help. To create a new property 1. In Setup Editor > Product tab, right-click the Properties icon and select New > Property. The Property Details dialog box appears. 2. Complete the dialog box: „ Name Enter a name for the property. Properties can contain only letters, numbers, underscores, and periods and must begin with a letter or underscore. A public property name consists of all uppercase letters. The value of public properties can be passed from the UI Sequence to the Execute Sequence. In most cases, barring security issues, you should designate properties as public properties. (See Public Properties in the Windows Installer SDK Help.) A private property name includes lowercase letters. (See Private Properties in the Windows Installer SDK Help.) „ Value Enter an initial value for the property. According to Windows Installer guidelines, you should always enter an initial value. However, in some cases you might not want to. Example: If the property is associated with a check box, and you want the check box to appear unchecked initially. Windows Installer Editor Reference 393 Using Conditions and Properties Note You cannot enter other properties to set the value of a new property because text you enter is interpreted literally. This is not true for some specific Windows Installer properties, such as DiskPrompt and PrimaryFolder. To set a property to the value or values of other properties, use the Set Property custom action. See Set Property on page 483. 3. „ Hidden property Mark this to designate this property as hidden. This Windows Installer 2.0 feature prevents the property’s value from being written to the installation log file. Use this for properties that contain information, such as serial numbers or passwords, that you don’t want end users to see. „ Add to the list of restricted public properties Mark this to designate this property as a restricted public property. Do this if the installation is to be performed on locked-down Windows computers and you want the ability to change and pass its value from the UI Sequence to the Execute Sequence. (See Restricted Public Properties in the Windows Installer SDK Help.) This is unavailable if you entered any lowercase letters in the name. Click OK. The property is added to the list of properties initialized by this installation. You can also create a new property from any dialog box in the product that has a Property drop-down list with a New button next to it. To edit a property, double-click its name under the Properties icon in Setup Editor > Product tab. Warning You can edit and delete properties, but many of the properties you see in the Properties icon are Windows Installer properties. You should be proficient in the Windows Installer development environment before you edit or delete Windows Installer properties. If you change the name of a property, make sure you update any dialog box controls or conditions that reference the property name. Windows Installer Editor Reference 394 Chapter 17 Working With Dialogs This chapter includes the following topics: z About Dialogs on page 395 z Using the Dialogs Page on page 398 z Using the Dialogs Tab on page 402 z Editing Dialog Details on page 404 z Creating a New Dialog on page 406 z About Dialog Controls on page 407 z About Billboards on page 418 z Obtaining Logon Information From a Dialog on page 421 z About the SQL Connection Dialog on page 422 z Adding the Custom Property Dialog on page 425 About Dialogs You can select, edit, and rearrange dialog boxes that appear to the end user during installation. This lets you determine the level of control the end user has over the installation. You also can select the theme that controls the overall look of the installation dialog boxes. For most installations, the Dialogs page provides all the options that are needed for selecting and editing dialog boxes. The Dialogs tab in Setup Editor contains advanced tools for editing the appearance as well as the behavior and logic of installation dialog boxes. You can access dialog boxes from the following places: z Dialogs page (Installation Expert) The dialog boxes on the Dialogs page are those in the Welcome Dialog Wizard, which appear to the end user during a normal installation. Turn the dialog box boxes on or off, rearrange them, view conditions, and select the dialog box theme. Click the Dialog Editor button to display a dialog box on the Dialogs tab. z Dialogs tab (Setup Editor) Edit any dialog boxes in the installation and create new dialog boxes. z Display Dialog actions (MSI Script) View dialog box sequences as they are ordered in the installation sequences, as well as the conditions under which the dialog boxes display. The conditions are within If statements surrounding the Display Dialog actions. One Display Dialog action represents an entire dialog box sequence. Example: Welcome_Dialog in MSI Script represents the entire Welcome Dialog Wizard, as shown on the Dialogs tab. In MSI Script, if you double-click the script line for Welcome_Dialog, the first dialog box of the Welcome Dialog Wizard displays on the Dialogs tab. Windows Installer Editor Reference 395 Working With Dialogs The Dialogs tab shows all dialog boxes that are part of an .MSI. Any of these dialog boxes can appear in different situations: Install Dialogs The Install Dialogs appear during a normal installation, if no command-line options are used to run an advertisement, administrative, or silent installation. Maintenance Dialogs The Maintenance Dialogs appear when the installation is run in maintenance mode, that is, when it is run after the application is installed. Maintenance mode lets the end user change, repair, or uninstall the application. Admin Dialogs The Admin Dialogs appear during an administration installation. An administrative installation copies a source image of the application to a network, for later installation by end users. To run an administrative installation, use the command-line option /a. See About Installation Modes on page 437. See also: About Installation Sequences on page 440 Types of Actions in MSI Script Sequences on page 441 About the Wizard Dialogs on page 396 Using the Dialogs Page on page 398 Using the Dialogs Tab on page 402 About the Wizard Dialogs Some dialog boxes in the Welcome Dialog Wizard are probably familiar to you, because they appear in almost all installations. Others only appear in certain situations: z If you add them with the New Dialog Wizard. See Creating a New Dialog on page 406. z If you add certain features to your installation, corresponding dialog boxes are added. Example: IIS dialog boxes are added if you add Web resources to the Web Files page. z If you create an installation based on a certain template that has special dialog boxes. (Example: The Server Application template contains the SQL Connection dialog.) You select the installation template in the New Installation File dialog box. Dialog boxes that can appear in installations Welcome dialog License dialog Windows Installer Editor Reference See Importing Text into License and Readme Dialogs on page 401. 396 Working With Dialogs Readme dialog See Importing Text into License and Readme Dialogs on page 401. User Information dialog Lets end users enter their name, company, and product ID, and indicate whether the software should be installed for all users or only for the current user. The Product ID field does not appear to the end user if the ProductID property (select Product tab > Properties icon) is set to none. See ProductID Property and PIDTemplate Property in the Windows Installer SDK Help. Single Feature Destination dialog Sets the installation directory. Installation Type dialog Lets the end user select a typical, complete, or custom installation, which you define on Installation Expert > Installation Types page. Select Feature dialog Lets the end user select which features to install and how to install them. Palm User Information dialog If you add Palm OS files on the Mobile Devices page, and if the desktop computer has multiple Palm users, this dialog box appears and lets the end user specify which Palm users should be able to access the new Palm application. For additional criteria for displaying this dialog box, see Installing to the Palm User folder on page 220. SQL Connection dialog Appears in installations that are started from the Server Application template in the New Installation File dialog box. It lets end users select a SQL Server name and security credentials, and puts the resulting connection string into a property. You can use this connection string on Installation Expert > SQL Server Scripts page. See Adding the SQL Connection Dialog to an Installation on page 423. IIS dialogs Several dialog boxes that begin with “IIS” are added if you install Web files. See About Web Installations on page 242. Warning Do not edit the Web (IIS) dialog boxes, except to change their order (as a group) in the installation sequence. Editing the Web dialog boxes might cause unexpected, undesirable behavior, including damage to the installation. Also, any operation within this product that affects the installation’s user interface will regenerate the Web dialog boxes, therefore, any changes you make to them will be lost. Windows Installer Editor Reference 397 Working With Dialogs Logon Information dialog Appears in installations that are started from the Server Application template in the New Installation File dialog box. You can add it to any installation by using the New Dialog Wizard. See Adding the Logon Information Dialog on page 421. Custom Property dialog Lets end users set the values of Windows Installer Properties. You can only add this dialog box through the New Dialog Wizard, where you set the properties that appear during installation. See Adding the Custom Property Dialog on page 425. See also: Using the Dialogs Page on page 398 Using the Dialogs Tab on page 402 About Dialogs on page 395 Using the Dialogs Page Use Installation Expert > Dialogs page to view, activate, and rearrange installation dialog boxes that are part of the Welcome Dialog Wizard. The dialog boxes that you activate determine the level of control the end user has over the installation. Warning Do not edit the Web (IIS) dialog boxes, except to change their order (as a group) in the installation sequence. Editing the Web dialog boxes might cause unexpected, undesirable behavior, including damage to the installation. Also, any operation within this product that affects the installation’s user interface will regenerate the Web dialog boxes, therefore, any changes you make to them will be lost. The Dialogs page looks different based on the version of the Wise product that the current installation was created in. If the installation was created in Wise for Windows Installer 6.0 or later, or Windows Installer Editor 5.5 or later, or any version of Wise MSI Editor, it has more options, which are documented below. If the installation was created in earlier versions, it has fewer options and contains a Convert button. Using the Convert button The Convert button converts the button navigation to a more flexible and robust system, which facilitates changing the order of dialog boxes. However, converting may cause problems with legacy installations if you have extensively customized the dialog boxes and their settings. Make a backup of the installation before converting if such customization exists. Click Convert and the dialog boxes are instantly converted to the new system with no undo. At that point, new options appear on the Dialogs page. To activate a dialog box Mark the check box next to the dialog box’s name. Windows Installer Editor Reference 398 Working With Dialogs Warning If this installation contains Web resources, then the list of dialog boxes might include Web (IIS) dialog boxes. Only enable or disable the Web dialog boxes as a group. Enabling individual Web dialog boxes can prevent the installation from working properly. To view a dialog box Click the dialog box name in the Dialogs list. To edit dialog box details and attributes Select the dialog box and click Details. See Editing Dialog Details on page 404. To change the order of dialog boxes during installation Use the Move Up and Move Down buttons. Warning If this installation contains Web resources, then the list of dialog boxes might include Web (IIS) dialog boxes. The Web dialog boxes must always remain in their original order, so they should only be moved as a group. See Changing the Order of Web Dialogs on page 402. To add a dialog box Click the Add button and complete the wizard. See Creating a New Dialog on page 406. To turn off all installation dialog boxes Do one of the following: z Use a silent installation. See User Interface Levels in the Windows Installer SDK Help. z In Setup Editor > Dialogs tab, clear the check box next to Welcome Dialog Wizard. About changing conditions On the Dialogs page, you see the conditions attached to each dialog box. You can change these conditions by double-clicking the dialog box name and editing the Conditions field, but this is not recommended. Most of the Windows Installer properties referenced in conditions are documented in the Windows Installer SDK Help. Changing the Theme of Dialogs The theme controls the overall look of installation dialog boxes by setting their top or side images and the fonts of the dialog box text. You can choose from predefined themes or themes that you have created. Windows Installer Editor Reference 399 Working With Dialogs Warning Changing themes might delete dialog box customizations in installations that were created in previous versions of this Wise product. To preserve dialog box customizations, leave None selected in Default Theme. To change the dialog box theme 1. Select Installation Expert > Dialogs page. 2. From Default Theme, select a new theme. „ The None option appears in Default Theme for installations created in previous versions of this Wise product. If the installation you previously created has dialog box customizations that you do not want to lose, leave the Default Theme set to None. „ Select No Graphics to omit top or side images from dialog boxes. Use this option to minimize the size of an installation that is always run silently. The dialog box in the Preview pane displays the new theme. Applying Themes to Releases You can apply different themes to different releases. The theme of the Default release on the Releases page corresponds to the Default Theme on the Dialogs page. Changing the theme on one page changes it on the other. Renaming or deleting the Default release breaks this relationship. See Creating a New Release on page 182. Adding and Editing Dialog Themes The theme controls the overall look of installation dialog boxes by setting their top or side images and the fonts of the dialog box text. You can edit themes and create customized dialog box themes. If an installation was imported or converted from a non-Wise product, the ability to edit the themes is limited and varies depending on the product. To add or edit a dialog box theme 1. Select Installation Expert > Dialogs page. 2. Click Edit Themes. The Edit Themes dialog box appears. 3. 4. Specify a theme: „ To edit an existing theme, click the theme name in the list on the left. „ To create a new theme, click New and enter the theme’s name in Name. „ To create a new theme based on an existing theme, click a theme in the list, click Copy, and enter the new theme’s name in Name. To add images to a new theme or to change an existing theme’s images, click Browse to the right of Top Image Preview or Side Image Preview and select a new image file. The image you select appears in the preview pane. Windows Installer Editor Reference 400 Working With Dialogs When you create a new theme, the images you specify are copied to a new subdirectory in the Themes directory. The location of the Themes subdirectory varies. See Installation Resources and Their Locations on page 27. Theme images you create must be in .BMP format. To quickly create theme images, copy and edit a set of predefined images. These images are in the subdirectories of the Themes directory. 5. To remove an image from a theme, click the Remove button to the right of the image. 6. To edit a theme’s fonts, click the Set Font button to the right of the font to change and select a new font from the Font dialog box. Select a font that will be on the destination computer. If the font you select is not on the destination computer, the font is set to a recognized system font. The selected font appears on the Edit Themes dialog box next to the Set Font button. „ The Title Font settings control the font for the title of all dialog boxes that have a top image. (Example: the title “License Agreement” on the License dialog.) The Title Font settings do not control the font for the title of the Welcome dialog or any other dialog boxes that have a side image. „ The Main Font settings control the font for the rest of the text on the dialog boxes. You cannot edit the font of individual sections of a dialog box from the Edit Themes dialog box. „ If you create a new theme and do not set the fonts for that theme, it uses the default font settings in the Properties table. „ To edit the font of the Welcome dialog box title or of any individual sections of dialog box text, use Setup Editor > Dialogs tab. See Basic Control Settings on page 409. If you change one or more themes on the Edit Themes dialog box, and then click OK, all the changes are saved, but if you click Cancel, all the changes are canceled. Importing Text into License and Readme Dialogs You can import an .RTF or .TXT file to appear on the License and Readme dialog boxes. After you import the text, you can edit it in its dialog box. To import text into License and Readme dialog boxes 1. Select Installation Expert > Dialogs page. 2. Select the dialog box in the Dialogs list. 3. Click Import Text and select an .RTF or .TXT file. This button is available only when you select the License or Readme dialog boxes. The text is imported into the dialog box but any embedded graphics are removed. Windows Installer Editor Reference 401 Working With Dialogs Note If you encounter error messages or formatting problems when you import the file, open it in Wordpad, save it as .RTF, and re-import it. Some computers cannot import files with formats other than .RTF. Also, only the standard .RTF settings are supported for the License and Readme dialog boxes. Changing the Order of Web Dialogs If this installation contains Web resources, then it might contain Web (IIS) dialog boxes. These dialog boxes must always remain in their original order, so they should only be moved as a group. To change the order of Web dialog boxes 1. Select Installation Expert > Dialogs page. 2. Click Web Dialogs. The Web Dialog Sequence dialog box appears. If the Web Dialogs button does not appear, either this installation does not contain Web resources, or the user interface has been disabled for those Web resources. 3. In the list of dialog boxes, WEB DIALOGS represents the entire group of Web-related dialog boxes, which must be moved as a group. Use the Move Up and Move Down buttons to move the group of Web dialog boxes. Warning Do not edit the Web (IIS) dialog boxes, except to change their order (as a group) in the installation sequence. Editing the Web dialog boxes might cause unexpected, undesirable behavior, including damage to the installation. Also, any operation within this product that affects the installation’s user interface will regenerate the Web dialog boxes, therefore, any changes you make to them will be lost. See also: About Web Installations on page 242 Using the Dialogs Tab Use Setup Editor > Dialogs tab to select, edit, rearrange, and create the dialog boxes that will appear in an installation. It shows the complete list of dialog boxes and provides more options for working with dialog boxes than are available in Installation Expert > Dialogs page. The Dialogs tab contains a Layout menu, a right-click menu, and a toolbar that let you add new controls to dialog boxes, edit existing controls, and organize dialog box content. z To expand or collapse a selected dialog set’s children, use the right-click menu. z If the toolbar is not visible, select View menu > Controls. Windows Installer Editor Reference 402 Working With Dialogs Warning Do not edit the Web (IIS) dialog boxes, except to change their order (as a group) in the installation sequence. Editing the Web dialog boxes might cause unexpected, undesirable behavior, including damage to the installation. Also, any operation within this product that affects the installation’s user interface will regenerate the Web dialog boxes, therefore, any changes you make to them will be lost. To activate dialog boxes for an installation Mark the check box next to the dialog’s name. This works consistently for wizard dialog boxes that appear under a wizard set, such as the Welcome Dialog Wizard. It does not work for some required dialog boxes, such as the User Exit and Fatal Error dialog boxes, which can appear whether you mark their check boxes or not. If you turn off the Cancel dialog boxes that appear as children of wizard dialog boxes, the Cancel button that calls the Cancel dialog box becomes unavailable in the wizard dialog box. Warning If this installation contains Web resources, then it might contain Web (IIS) dialog boxes. Only enable or disable the Web dialog boxes as a group. Enabling individual Web dialog boxes can prevent the installation from working properly. To edit dialog box details and attributes Right-click the dialog box name in the left pane and select Details. See Editing Dialog Details on page 404. Warning If you are using the Installation Types page to manage the Installation Types dialog box, you cannot change any details on the Installation Types dialog box. Doing so causes the Installation Types page not to work properly. To change the order of dialog boxes during installation Right-click the dialog box name in the left pane and select. Move Up or Move Down Warning If this installation contains Web resources, then it might contain Web (IIS) dialog boxes. The Web dialog boxes must always remain in their original order, so they should only be moved as a group. See Changing the Order of Web Dialogs on page 402. To add a dialog box to the installation 1. In the left pane, right-click where the new dialog box should appear, and select New > Dialog. 2. Complete the wizard. See Creating a New Dialog on page 406. To turn off all installation dialog boxes Do one of the following: z Use a silent installation. Windows Installer Editor Reference 403 Working With Dialogs See User Interface Levels in the Windows Installer SDK Help. z In Setup Editor > Dialogs tab, clear the check box next to Welcome Dialog Wizard. Adding Controls to Dialogs Add controls to dialog boxes on the Dialogs tab in Setup Editor. Because of limitations with Windows Installer, do not place dialog box controls on top of graphics. Although you can place objects on top of one another, controls that are placed on top of graphics often do not appear at run time. Warning Do not edit the Web (IIS) dialog boxes, except to change their order (as a group) in the installation sequence. Editing the Web dialog boxes might cause unexpected, undesirable behavior, including damage to the installation. Also, any operation within this product that affects the installation’s user interface will regenerate the Web dialog boxes, therefore, any changes you make to them will be lost. To add controls to dialog boxes 1. In Setup Editor > Dialogs tab, select a dialog box in the left pane. The dialog box appears in the right pane. 2. Select Layout menu > Add, and then select the type of control to insert. If the controls in the Add menu are unavailable, click the dialog box to make it active, and try adding the control again. Depending on the type of control you select, a Properties dialog box appears so you can configure the control’s properties, position, and attributes. For information on each tab of the Properties dialog box, see: Basic Control Settings on page 409 Setting an Event on a Control on page 412 Assigning Help to a Control on page 413 Assigning Conditions to a Control on page 413 Setting the Graphic for a Control on page 414 Setting the Items in a Control on page 414 3. Click OK to add the control to the dialog box. 4. Use other commands on the Layout menu to help organize and arrange the new controls. When you perform an operation on multiple controls at once (example: aligning controls), the last control you select is the master control, which the other selected controls will conform to. The master control is surrounded with solid handles instead of hollow handles. Editing Dialog Details You can edit the general details of any installation dialog box from: z Setup Editor > Dialogs tab: Right-click the name of a dialog box in the left pane, and select Details. Windows Installer Editor Reference 404 Working With Dialogs z Installation Expert > Dialogs page: Select the dialog box and click the Details button. The Dialog Details dialog box appears. Warning If you are using the Installation Types page to manage the Installation Types dialog box, do not change any details on the Installation Type dialog box. Doing so causes the Installation Types page not to work properly. Warning Do not edit the Web (IIS) dialog boxes, except to change their order (as a group) in the installation sequence. Editing the Web dialog boxes might cause unexpected, undesirable behavior, including damage to the installation. Also, any operation within this product that affects the installation’s user interface will regenerate the Web dialog boxes, therefore, any changes you make to them will be lost. z Dialog Title Enter the title of the dialog box. You can include an installation property in the title by enclosing it in square brackets. Example: [ProductName] inserts the name of the product at run time. z X and Y Centering Enter X and Y values from 1 to 100 to indicate where on the screen the dialog box should be centered. Values of 50 in both fields mean that the dialog box should be exactly centered on the screen. If the Y Centering value is set to 33, the center of the dialog box will be 1/3 of the way from the top of the screen. z Visible Mark this to make the dialog box visible. z Minimize Button Mark this to add a minimize button. z Track Disk Space Mark this to have the dialog box periodically call Windows Installer to update any disk space fields on the dialog box. z Error Dialog Mark this if the dialog box is an error dialog box. The property named ErrorDialog determines which specific dialog box is called if errors occur during installation. The dialog box must contain a text control named ErrorText to receive the contents of the error message. An installation can contain only one error dialog box. z Modal Mark this if the dialog box should be modal, which means the dialog box is the front window of the installation until the end user clicks OK or Cancel. The end user cannot access other windows or dialog boxes of the installation until the modal dialog box is dismissed. z Keep Modeless Mark this if non-modal dialog boxes that are displayed when this dialog box appears should remain on the screen. z Use Custom Palette Mark this to use a custom color palette on displays with 256 colors or less. This usually makes the dialog box look better, provided only one dialog box is on the screen at a time. Windows Installer Editor Reference 405 Working With Dialogs Note If you get details for the Custom Property dialog box, an Edit button appears on the Dialog Details dialog box. This lets you change the Windows Installer properties for the Custom Property dialog box. Creating a New Dialog The New Dialog Wizard guides you through the process of adding a new dialog box to an installation. To create a new dialog box 1. Start the New Dialog Wizard: „ Select Setup Editor > Dialogs tab. In the left pane, right-click where the new dialog box should appear, and select New > Dialog. OR „ Select Installation Expert > Dialogs page > Add button. The Select Dialog Type page appears. Note The dialog box templates that appear are in Wise Standard.msi, which is stored in \Templates\Dialogs. To make additional dialog boxes available in each new installation, open Wise Standard.msi and add the dialog boxes to the All Dialogs branch on the Dialogs tab. The location of the Templates subdirectory varies. See Installation Resources and Their Locations on page 27. 2. Select the type of dialog box and click Next. The Dialog Properties page appears. 3. Edit any values by clicking the item in the Type column and then clicking Edit. This page lets you change any properties the new dialog box inherits from the template. Example: Each dialog box must have a unique name. The wizard assigns a unique name to the new dialog box by appending a number to the template’s name, but you might want a more descriptive name. 4. When you finish editing values, click Next. If you added the Custom Property dialog box, the Select Custom Properties page appears, where you can select properties that can be set by the end user during installation. See Adding the Custom Property Dialog on page 425. The Select Installation Placement page appears, which differs slightly based on what version of Windows Installer Editor the current installation was created in. Read about the Convert button in Using the Dialogs Page on page 398. 5. Specify where in the sequence the new dialog box should appear. „ Windows Installer Editor Reference If Move Up and Move Down buttons appear, use them to move the new dialog box within the list. 406 Working With Dialogs „ 6. If they do not appear, then you must select a dialog box in both the After and Before columns. The new dialog box will appear after the dialog box you select in After, and before the dialog box you select in Before. Click Finish to add the new dialog box to the dialog box list. Now you can add and edit controls on the dialog box. See: Adding Controls to Dialogs on page 404 Editing Dialog Details on page 404 Organizing and Aligning Controls on Dialogs on page 415 About Dialog Controls Installation dialog boxes contain standard controls, which you can add and edit. Most controls are configured by completing their Properties dialog box. See Editing Dialog Controls on page 409. dialog box controls often have an associated property. The result from the dialog box control is put into the property. To have a dialog box control be deselected by default, associate the control with a property whose value is not defined (null). Example: Suppose you create a check box, and you want the check box to be initially cleared. In the Properties dialog box for the check box, click the New button next to the Property field, create a new property named CHECKBOX1, and leave its value blank. Although this results in error messages during compile (which you can safely ignore), it ensures that the check box is initially cleared when initially cleared when it appears to the end user. (Delete the property from the Properties icon on the Product tab to eliminate error messages.) To test whether the end user marked the check box, you use a condition that consists of the property’s name, that is, CHECKBOX1. If the check box was not marked, the value of the property remains null, and therefore CHECKBOX1 is false. If the check box was marked, its value is now non-null, and therefore CHECKBOX1 is true. Types of Dialog Controls Billboard A static field that defines the area of the dialog box where a sequence of text and images is displayed during installation Billboards require special setup. See About Billboards on page 418. Bitmap A static image field for displaying graphics Button A clickable button Check box A single check box for on/off, true/false settings Combobox A combination edit field and drop-down list control that lets the end user select a predefined value or enter a value Directory Combobox Displays a combination directory list and path edit field to let the end user specify a directory Windows Installer Editor Reference 407 Working With Dialogs Directory Listbox Displays the folders below the main part of the current path This is intended to be used with the path edit control. Edit Field A single line input field Group Box A boundary box drawn around related controls Icon A static image control for displaying icons Line A separator line drawn between groups of controls Listbox. Displays a single column of values without icons The end user can select one value from the list. Listview Displays a single column of values with an icon next to each The end user can select one value from the list. Masked Edit Field A text edit field with a mask that creates a template for end user data entry, specifying default values for some positions and specifying the proper type of character (numeric or alpha) for others You can enter certain characters in the Control Text field of the Masked Edit control to constrain which characters can be used at each character position of the control. See MaskedEdit Control in the Windows Installer SDK Help. Path Edit A single line input field that accepts only a valid path This is intended to be used in conjunction with the directory list box or directory combobox controls. Progress Bar A control that displays the progress of an installation or other operation Radio Button A group of mutually exclusive options with a separate radio button for each option Scrollable Text A multi-line text entry field Selection Tree Displays the feature selection tree Text Static text field for displaying messages The end user cannot change text in this type of field. You can enter a property name surrounded by brackets in this type of control to display a property’s current value. Volume Cost Listbox A static text control that shows information about the disk space requirements of different volumes (referred to as “cost” in Windows Installer terminology) for the currently selected features Volume Combobox Lets the end user select a volume for installation Windows Installer Editor Reference 408 Working With Dialogs Editing Dialog Controls Warning Do not edit the Web (IIS) dialog boxes, except to change their order (as a group) in the installation sequence. Editing the Web dialog boxes might cause unexpected, undesirable behavior, including damage to the installation. Also, any operation within this product that affects the installation’s user interface will regenerate the Web dialog boxes, therefore, any changes you make to them will be lost. To edit dialog box controls 1. In Setup Editor > Dialogs tab, select a dialog box in the left pane. The dialog box appears in the right pane. 2. Double-click a control. A multi-tabbed Properties dialog box appears. The tabs that appear vary depending on the type of control. See: Basic Control Settings on page 409 Setting an Event on a Control on page 412 Assigning Help to a Control on page 413 Assigning Conditions to a Control on page 413 Setting the Graphic for a Control on page 414 Setting the Items in a Control on page 414 To see the results of these settings, compile and run the installation. Basic Control Settings The Control tab, which appears on the Properties dialog box for dialog controls, determines the appearance and basic behavior of controls. See Editing Dialog Controls. The settings available on this tab vary depending on the type of control. z Property The name of the property associated with this control. The property determines the initial state of the control, and holds the result from the control after end user input. This property can determine the initial state of the control. Example: If a check box is associated with a property whose value is not defined (null), the check box is initially cleared when it appears to the end user. After the end user has interacted with a control by marking it, entering text into it, or selecting an option, the result of the user input is stored in this property. You can create a new property. See Creating a New Property on page 393. z Control Text The text in the control. For bitmap and icon controls, this stores the key in the binary table in which the bitmap or icon is stored. Click Import to import text from an existing text file (.TXT or .RTF). Windows Installer Editor Reference 409 Working With Dialogs Note If you encounter error messages or formatting problems when you import the file, open it in Wordpad, save it as .RTF, and re-import it. Some computers cannot import files with formats other than .RTF. z Max Characters (This replaces the Control Text field for an edit field control.) Enter the maximum number of characters the end user can enter. z Default Mark this to activate this control when the user presses Enter while on this dialog box. Example: If you mark this check box for an OK button on a dialog box, then when the user presses Enter, the event associated with the OK button is activated. z Cancel Mark this to activate this control when the user presses Esc while on this dialog box. Example: If you mark this check box for a Cancel button on a dialog box, then when the user presses Esc, the event associated with the Cancel button is activated. z Font Property (Not available for a scrollable text control.) Select the property that defines a font. In most cases, select _WiseDialogFontDefault to match the default text of other text on dialog boxes. To define a new font style, add a new row to the TextStyle table in Setup Editor > Tables tab. Then create a new property, and enter the new text style’s name, surrounded by curly brackets, as the property value. z Control Font You can click Set Font and select a font for the control. The Font Property field, if set, overrides this field. z X Position, Y Position The location of the control within the dialog box. The upper-left corner is represented by X,Y values of 0,0. You also can drag the control to position it on the dialog box. z Width, Height The size of the control in installation units, which are equal to 1/12 the height of the system font on the destination computer. General Attributes z Visible Makes the control visible. z Sunken Makes the control beveled to appear pushed into the dialog box. z Right Aligned Text Right-aligns text in the control. z Enabled Enables the control, that is, display it in a state the end user recognizes as clickable. z Indirect If you mark this, the information for the control is not stored directly in the property for the control. Instead, the value of the control’s property is used as the real property name to store the information in. Example: Suppose a dialog box has three radio buttons and a check box. The radio buttons set the property RADIO to FIRST, SECOND, or THIRD. The check box also Windows Installer Editor Reference 410 Working With Dialogs uses the property RADIO but has the Indirect check box marked. The property FIRST, SECOND, or THIRD is set to the check box state based on the setting of the radio button. z Scrollbar on left side On a scrolling field control, places the scrollbar on the left instead of the right. (Usually used with the Right-To-Left Reading check box below.) z Integer Restricts end users to entering only integers in this control. z Right-To-Left Reading Indicates that the text in this control is in a language that is read right to left. z Has Border Displays a group box frame around the radio buttons in a radio button control. z Check Value If the end user marks the control, the value of the property in the Property field is set to this value. Control Attributes z Transparent Makes the background of the control transparent. z Format Size Tries to format displayed text as a number representing a count of bytes. The control’s text must be set to a number in units of 512 bytes. KB, MB, or GB is added to the end of the text depending on how large the number is. z No Prefix Displays any & (ampersand) characters in the control’s text. Otherwise, & characters do not appear and cause the next character to be underscored. z Users Language Makes the text control use fonts created in the end user's default UI codepage. If this is cleared, the fonts are created in the database’s codepage. z No Word Wrap Text is not wrapped to fit the control area. Instead, it is clipped at the right edge of the control. z Multiline Lets an edit field control accept multiple lines of text. If this is cleared, it accepts only a single line. z Image Handle Obtains the image from a handle rather than from the Binary table. z Icon Control Replaces the control’s text with an icon. The control’s text is used as a key to the Binary table to point to the icon data. z Pushbutton (Check Boxes and radio button groups only.) Draws the control as if it were a pushbutton, although its behavior is not changed. z Fixed Size Prevents the image associated with the control from being scaled to fit the control size. Instead, the image is cropped or centered in the control. Windows Installer Editor Reference 411 Working With Dialogs z Password Makes an edit control display asterisks instead of the characters that the end user types. This is typical of controls that require entry of a password. z Bitmap Replaces the control’s text with a bitmap. The control’s text is used as a key to the Binary table to point to the bitmap data. z Icon Size Determines how icons are displayed in the control. Select a size, or select First Icon to set scaling according to the first icon. z Sorted By default, the items in the control are sorted alphabetically before they are displayed. Mark this to sort the items in the order they appear on the Items tab of the Properties dialog box. z Droplist Makes the control display a drop-down list rather than a multi-line selection list. z Removable Volumes, CD-ROM Volumes, Fixed Volume, RAM Disk Volumes, Remote Volumes, Floppy Volume Mark the check boxes to determine which types of volumes are listed in the control. z Windows 95 Style Displays the control using a Windows 95 appearance. z Elevation Shield Adds the Windows Vista shield icon (User Account Control elevation icon) to a pushbutton control. Setting an Event on a Control The Events tab, which appears on the Properties dialog box for dialog box controls, determines the events that the control can send and receive. See Editing Dialog Controls on page 409. Use events to control the display of other dialog boxes, and to control the way Windows Installer displays dialog boxes. When an event is generated (either by a dialog box control or by Windows Installer) it is published. The published event is sent to Windows Installer and to all dialog box controls that have subscribed to it. Publish events The top section of the Events tab lists the events published by the control. z To add a new published event, click Add. z To edit a selected event, click Details. z To remove a selected event from this control, click Delete. z To rearrange the order in which the events are sent, click Move Up or Move Down. When you click Add or Details, the Publish Event Details dialog box appears, where you set the following options: z Event Select the event to be published. See the following in the Windows Installer SDK Help: ControlEvent Overview for general information on control events. Windows Installer Editor Reference 412 Working With Dialogs Control Events for details on each control event. z Argument Enter the argument for the event. If no value is passed for that argument, the event is ignored. See Control Events in the Windows Installer SDK Help; click an event name to see valid arguments. z Condition If you enter a condition for the event, the event occurs only if the condition is true. If there is no condition, the event always occurs. See Conditions on page 383. Subscribe to events The bottom section of the Events tab lists the events accepted by the control. z To add a new subscribed event, click Add. z To edit a selected event, click Details. z To remove a selected event from this control, click Delete. When you click Add or Details, the Subscribe Event Details dialog box appears, where you set the following options: z Event Select the event to be subscribed to. See the following in the Windows Installer SDK Help: ControlEvent Overview for general information on control events Control Events for details on each control event z Attributes Select an attribute that should be set for the control when the subscribing control receives the ControlEvent. For information on valid attributes, see Control Attributes in the Windows Installer SDK Help. Assigning Help to a Control The Help tab, which appears on the Properties dialog box for dialog box controls, lets you set tooltip help for the control. See Editing Dialog Controls on page 409. Note The Help tab is not available for radio button controls. Instead, enter tooltip help for radio button controls in the Help Text field on the Radio Button Details dialog box, which you access from the Items tab. z Tooltip A short phrase that appears when the end user points to the control and pauses. This is also used by screen reading programs. Assigning Conditions to a Control The Conditions tab, which appears on the Properties dialog box for dialog box controls, lets you set conditions for a control. The conditions let you assign specific attributes to a control. Conditions determine whether the control is the default control, and whether it is disabled, enabled, hidden, or visible. You can add multiple conditions to a control. Windows Installer Editor Reference 413 Working With Dialogs z To add a new condition, click Add. z To edit a selected condition, click Details. z To remove a selected condition from this control, click Delete. When you click Add or Details, the Control Condition Details dialog box appears, where you set the following options: z Action The action to take when the condition is true. z Condition If you enter a condition for the event, the event occurs only if the condition is true. If there is no condition, the event always occurs. See Conditions on page 383. Setting the Graphic for a Control The Graphic tab, which appears on the Properties dialog box for graphical dialog box controls, lets you specify a graphic file for the control. It determines the image displayed in the control. Not all controls can display graphics. See Editing Dialog Controls on page 409. z Graphic Name The drop-down list displays graphics stored in the Binary table. Select a graphic or click Set to import a new graphic. Graphics must be in .BMP format. z Information Displays information about the graphic, including the number of colors in its palette, its width and height, and its size. z Preview Displays the image. If necessary, the image is scaled down to fit in the preview area. Setting the Items in a Control The Items tab, which appears on the Properties dialog box for list box controls, comboboxes, listview controls, and radio button controls, determines the items that are listed in the control. It also lets you determine the tab order of the items, and set the vertical position (which determines the order of the items on the dialog box). See Editing Dialog Controls on page 409. All controls that share the same property name also share the same list of items. Example: Suppose you make a radio button control, associate the property ITEM_LIST with it, and add three items to it. Then on another dialog box, you make a listview control and associate ITEM_LIST with it. If you view the Items tab for the listview control, it contains the same items as for the radio button. z To add a new item, click Add. z To edit a selected item, click Details. z To remove a selected item from this control, click Delete. z To rearrange the order in which the items are displayed, click Move Up or Move Down. To change the order in which the items appear on the dialog box, double-click each item and set its Y coordinate. Windows Installer Editor Reference 414 Working With Dialogs When you click Add or Details, a details dialog box appears, where you can specify the text that appears in the control. The settings available on this tab vary depending on the type of control. z Text The text of the button or list item. z Value The value returned to the control’s property when the item is selected. z Help Text A short phrase that appears when the end user points to the control and pauses. z Icon Name Select an icon from the list or click Set and select an icon file on your hard drive. The icon you set appears next to this item in the list control. This option does not appear for all types of controls. z Font Property Select the property that defines a font. In most cases, select _WiseDialogFontDefault to match the default text of other text on dialog boxes. To define a new font style, add a new row to the TextStyle table in Setup Editor > Tables tab. Then create a new property, and enter the new text style’s name, surrounded by curly brackets, as the property value. z Control Font You can click Set Font and select a font for the control. The Font Property field, if set, overrides this field. z X Position, Y Position The location of the item within the control. The upper-left corner is represented by X,Y values of 0,0. To rearrange items within the control (example: to reorder the items for radio buttons), change the Y position. z Width, Height The size of the control in installation units, which are equal to 1/12 the height of the system font on the destination computer. Organizing and Aligning Controls on Dialogs You can align, center, and evenly space controls on installation dialog boxes. You also can constrain controls so they are the same size and set the tab order. You perform these functions using commands on the Layout or right-click menu. When you perform an operation on multiple controls at once (example: aligning controls), the last control you select is the master control, which the other selected controls will conform to. The master control is surrounded with solid handles instead of hollow handles. Warning Do not edit the Web (IIS) dialog boxes, except to change their order (as a group) in the installation sequence. Editing the Web dialog boxes might cause unexpected, undesirable behavior, including damage to the installation. Also, any operation within this product that affects the installation’s user interface will regenerate the Web dialog boxes, therefore, any changes you make to them will be lost. Windows Installer Editor Reference 415 Working With Dialogs Overlapping graphics and controls When dialog box controls are layered on top of a graphic or other control, the tab order determines the layer order. During compile, any item that is not included in the tab order is layered over items that are included in the tab order, causing certain controls to be hidden at run time. This layering can change from compile to compile. This is a Windows Installer limitation. To prevent unexpected control layering, set the dialog box’s tab order to include any graphic or control that is overlapped by another control. The higher the item is in the tab order, the closer to the top layer it will be. See Setting Dialog Tab Order on page 418. Example: On the sample dialog box shown below, the image covers most of the dialog box, and is overlapped by text and check box controls. Because the graphic and static text controls are not included in the tab order, they might be layered over the check box control at run time. Incorrect tab order on a dialog box Graphic and static text controls are not included in the tab order Aligning Dialog Controls You can align controls on a dialog box in relation to each other. To align dialog box controls 1. In Setup Editor > Dialogs tab, select a dialog box in the left pane. 2. In the right pane, select two or more controls. The last control you select is the master control that the other controls will be aligned with. 3. Select Layout menu > Align > Lefts/Rights/Tops/Bottoms, depending on which edge of the controls should align. Windows Installer Editor Reference 416 Working With Dialogs All selected controls are aligned with the master control. Centering Dialog Controls You can center controls on a dialog box in relation to the dialog box boundaries. To center dialog box controls 1. In Setup Editor > Dialogs tab, select a dialog box in the left pane. 2. In the right pane, select two or more controls. 3. Select Layout menu > Center in Form > and then select one of the following. „ Vertically. Center within the top and bottom edges of the dialog box. „ Horizontally. Center within the left and right edges of the dialog box. All selected controls are centered on the dialog box. Making Dialog Controls the Same Size You can make multiple controls on a dialog box the same size. To make dialog box controls the same size 1. In Setup Editor > Dialogs tab, select a dialog box in the left pane. 2. In the right pane, select two or more controls. The last control you select is the master control that the other controls will be sized to. 3. Select Layout menu > Make Same Size and then select one of the following. „ Width. „ Height. „ Both. All selected controls are sized to the master control. Spacing Dialog Controls Evenly You can space controls on dialog boxes evenly between the leftmost and rightmost controls (for horizontal spacing) or the topmost and bottommost controls (for vertical spacing.) To space dialog box controls evenly 1. In Setup Editor > Dialogs tab, select a dialog box in the left pane. 2. In the right pane, select two or more controls. 3. Select Layout menu and then select one of the following. „ Horizontal Spacing > Make Equal. Space items left to right. „ Vertical Spacing > Make Equal. Space items up and down. All selected controls are spaced evenly on the dialog box. Windows Installer Editor Reference 417 Working With Dialogs Setting Dialog Tab Order You can determine the tab order of controls on dialog boxes. To prevent unexpected control layering, set the dialog box’s tab order to include any graphic or control that is overlapped by another control. The higher the item is in the tab order, the closer to the top layer it will be. See Overlapping graphics and controls on page 416. To set the dialog box tab order 1. In Setup Editor > Dialogs tab, select a dialog box in the left pane. 2. Click anywhere on the dialog box to set focus. 3. Select Layout menu > Set Tab Order. This is unavailable unless you set the focus on the dialog box first. A black box appears for each control. The numbers on the boxes indicate the tab order. 4. To set the new tab order for the dialog box, click the controls in order. Each control turns blue as its new tab order is assigned. If the first several items have the correct tab order, and you want to begin renumbering the tab order at a later number, hold down the Ctrl key and click the control after which you want to renumber. Example: If controls 1 through 7 have the correct tab order, and you want to start renumbering from 8, press Ctrl and click control 7. Then continue setting tab order starting from control 8. About Billboards Billboards consist of a series of text and images that are dynamically displayed on a dialog box during installation. Typically, billboards highlight features of the program being installed, promote related products, or encourage product registration. A billboard is associated with an action, and is displayed while that action is performed during installation. A billboard consists of: The billboard The billboard defines the area of the dialog box where a sequence of text and images is displayed. The billboard is like a screen on which bitmaps, icons, or text controls are projected. The billboard control The billboard control is associated with a feature and an installation action. It also defines how many bitmaps, icons or text controls are displayed, and in what order. You create one billboard control for each bitmap, icon, or text control. Bitmap/Icon/Text control Bitmap, icon, or text controls are associated with a billboard control, and you place them inside the billboard area. Windows Installer Editor Reference 418 Working With Dialogs Where to use billboards Billboards typically are used on the Progress dialog under the Install Dialogs, and are associated with the InstallFiles action. You can add billboards to other dialog boxes, if: z The dialog box is displayed to the end user while the installation is performing an action. z You associate the billboard with an action that takes some time to perform. If the action is completed in a fraction of a second, the end user will not see the billboard. A billboard typically consists of several bitmaps, icons or text controls. If you want to display only one control, add it to the dialog box directly instead of within a billboard. Windows Installer does not support the display of billboards outside installation dialog boxes. Adding Billboards to a Dialog In the following steps, bitmaps, icons, and text controls are referred to as content items. To add billboards to a dialog box 1. Select Setup Editor > Dialogs tab. 2. In the left pane, select the Progress dialog under Install Dialogs. By default, the Progress dialog contains a billboard, which is represented by a small outline in the lower left of the dialog box. Content items you add will be bounded by this outline. 3. Click the small outline and resize and move it to accommodate the content items you plan to add. You can adjust it later. Windows Installer Editor Reference 419 Working With Dialogs Note Although a default billboard area is already created, you also can create your own. Right-click the dialog box and select Add > Billboard. On the Properties dialog box that appears, click the Events tab. Make sure the Subscribe to Event list contains an entry where Event is set to SetProgress and Attribute is set to Progress. 4. Create one or more billboard controls: a. Right-click the dialog box and select Billboards > New. The Billboard Details dialog box appears. b. Complete the dialog box:  Name Enter a descriptive name for this control.  Feature Select a feature from the list. This control’s content item only appears during installation if this feature is installed.  Action Select an action from the list. We strongly recommended that you leave the default, InstallFiles, because usually only this action takes time to complete. The control’s content items are displayed while this action is performed during installation.  Display After If this is the first control, select . Otherwise, select the control that this one should appear after. c. Click OK. d. Repeat this step to add as many controls as you have content items. The controls you create do not appear on the dialog box. You can only see their content items, which you add in the next step. 5. Add content items to each billboard control: „ Right-click the dialog box and select Billboards > BillboardControlName, where BillboardControlName is the name of the control. This makes the control active. „ Right-click the dialog box, select Billboards > Add Control, and select Bitmap, Icon, or Text. A properties dialog box appears. The tabs that appear vary depending on the type of control. „ For bitmaps or icons, click the Graphic tab and select a graphic or click Set to import a new graphic. Graphics must be in .BMP format. See Setting the Graphic for a Control on page 414. For text controls, enter text in the Control Text field. See Basic Control Settings on page 409. „ You can add multiple content items to each control. „ Make sure each content item is within the outline that represents the billboard area. Windows Installer Editor Reference 420 Working With Dialogs If you add large content items, you can resize the Progress dialog box itself to accommodate them. Also, you might need to resize bitmap items for them to display correctly. 6. To preview the billboard, select each billboard in order from the Billboard submenu of the right-click menu. 7. To see the billboard work, compile and run the installation. Note Billboards do not appear when you test the installation. This is because files are not installed during a test, so the InstallFiles event is never triggered. To view the billboards, you must run the installation. See Running An Installation on page 80. To edit an existing billboard Always select the billboard control name first by right-clicking and selecting Billboards > BillboardControlName, where BillboardControlName is the name of the billboard control. This makes the control active, which means that any editing you do is applied to that billboard. Obtaining Logon Information From a Dialog Often, server software must be configured after installation to run under a particular user with certain permissions. To help with this process, you can add the Logon Information dialog box to an installation. The Logon Information dialog box is fully customizable, which lets you communicate its purpose to the user. Use the Logon Information dialog box to: z Let the end user create a new NT user account during installation, if the end user has the privileges to do so. z Let the end user specify an existing NT user account during installation. z Populate the properties MYUSERNAME and MYPASSWORD with the logon information specified by the user. Although this dialog box captures the logon information, it does not use it in any way or apply it to your executables or services. You must do that yourself by using the properties elsewhere in the installation. Example: To have a service run under the specified user account, you can enter the property names MYUSERNAME and MYPASSWORD, enclosed in brackets, in the Service Details dialog box (Installation Expert > Services page). See also: Adding the Logon Information Dialog on page 421 Adding the Logon Information Dialog The Server Application template (Server Application.msi) contains the Logon Information dialog box by default. For all other installations, you can add the Logon Information dialog box by using the New Dialog Wizard in Setup Editor > Dialogs tab. Windows Installer Editor Reference 421 Working With Dialogs To create a new installation that contains the Logon Information dialog box 1. Select File menu > New. 2. In the Categories list, select Predefined Templates. 3. In the Templates/Tools list, select Server Application and click OK. 4. In Setup Editor > Dialogs tab, select the Logon Information dialog and edit the dialog box text as needed to communicate its purpose to the end user who installs your application. To add the Logon Information dialog box to any installation 1. In Setup Editor > Dialogs tab, expand the Install Dialogs tree, then expand the Welcome Dialog Wizard tree. 2. Right-click on a dialog box under the Welcome Dialog Wizard and select New > Dialog. 3. On the Select Dialog Type dialog box, select Logon Information and click Next. 4. Step through the wizard to create a new dialog box. See Creating a New Dialog on page 406. 5. Edit the dialog box text as needed to communicate the purpose of the user account to the end user who installs your application. Guidelines for using the Logon Information dialog box z Make sure you customize the text on the Logon Information dialog box to communicate the logon information’s purpose to the end user. z If the end user chooses to create a new user, the end user must have user creation privileges on the server or domain. z If the end user creates a user with this dialog box, then cancels the installation, the created user still exists and is not deleted. z During installation, the end user cannot progress through the installation until a valid NT account is entered on this dialog box. There is no mechanism for the end user to skip this part of the installation. z Do not use this dialog box to capture logon information to be used in a SQL Server connection string on the SQL Server Scripts page; the Microsoft SQL Server logon mechanism prevents this from working. See also: Adding a Service to the Destination Computer on page 156 About Web Installations on page 242 Obtaining Logon Information From a Dialog on page 421 About the SQL Connection Dialog Add the SQL Connection dialog box to an installation to: z Let the end user select a SQL Server name and security credentials to generate a valid SQL Server connection string. Windows Installer Editor Reference 422 Working With Dialogs z Populate the WISE_SQL_CONN_STR property with the valid connection string. When the end user completes the SQL Connection dialog box and clicks Next, the installation creates and tests the connection string. If the connection string is not valid, an error message appears. Note The SQL Connection dialog box only validates the connection string; it cannot verify that the user has permission to execute all SQL statements in a SQL script. SQL Connection dialog box requirements z Use the WISE_SQL_CONN_STR property for the connection string in Installation Expert > SQL Server Scripts page. See Configuring a Microsoft SQL Server During Installation on page 254. z The ODBC SQL Server driver must be on the destination computer for this dialog box to work. Use the Prerequisites page to pre-install MDAC, which includes the ODBC SQL Server driver. See Adding Prerequisites to a Release on page 195. z The Browse button appears on the SQL Connection dialog box only if SQL Client Tools (osql.exe) is installed on the destination computer. When the end user clicks the Browse button, a drop-down list appears with the SQL Servers on their network. If the Browse button does not appear, the end user must enter the SQL Server name. z This dialog box requires no modification to output a valid connection string to the property WISE_SQL_CONN_STR. However, if your application connects to more than one SQL Server during installation, add a SQL Connection dialog box for each additional server, edit the additional dialog boxes, and use a different property for each connection string. See Editing Additional SQL Connection Dialogs on page 424. See also: Adding the SQL Connection Dialog to an Installation on page 423 Adding the SQL Connection Dialog to an Installation The Web Application and Server Application templates contain the SQL Connection dialog box. For all other installations, you can add the SQL Connection dialog box. To create a new installation that contains the SQL Connection dialog box 1. Select File menu > New. 2. In the Categories list, select Predefined Templates. 3. In the Templates/Tools list, select Server Application or Web Application and click OK. 4. In Setup Editor > Dialogs tab, select SQL Connection Dialog and edit the dialog box text as needed to communicate its purpose to the end user who installs your application. Windows Installer Editor Reference 423 Working With Dialogs To add the SQL Connection dialog box to any installation 1. Select Installation Expert > Dialogs page. 2. Click Add. The Select Dialog Type dialog box appears. 3. Select SQL Connection Dialog and click Next. 4. Step through the wizard to create a new dialog box. See Creating a New Dialog on page 406. 5. Edit the dialog box text as needed to communicate its purpose to the end user who installs your application. See also: About the SQL Connection Dialog on page 422 Editing Additional SQL Connection Dialogs In most cases, an application connects to only one SQL Server during installation. However, if your application connects to more than one SQL Server during installation, add a SQL Connection dialog box for each additional server and edit the additional dialog boxes as follows: To add and edit SQL Connection dialog boxes 1. Start the New Dialog Wizard to add an additional SQL Connection dialog box. See Adding the SQL Connection Dialog to an Installation on page 423. 2. On the Dialog Properties dialog box of the New Dialog Wizard, edit the dialog box’s default control properties. Example: Edit the dialog box’s control properties as follows: From: To: WiseSqlServerName WiseSqlServerName1 WiseSqlAuth WiseSqlAuth1 WiseSqlUser WiseSqlUser1 WiseSqlPass WiseSqlPass1 3. Finish the New Dialog Wizard. 4. In Setup Editor > Dialogs tab, select SQL Connection Dialog1 in the left pane. 5. In the right pane, edit the Argument of the [WiseSqlParam] event for the Browse and Next buttons using the new control properties and a new property for the connection string. See Setting an Event on a Control on page 412. Example: Edit the Argument of the [WiseSqlParam] event for the Browse and Next buttons as follows: Windows Installer Editor Reference 424 Working With Dialogs From: To: WiseSqlServerName|WiseSqlAuth|WiseSqlUser|WiseSq lPass|WISE_SQL_CONN_STR WiseSqlServerName1|WiseSqlAuth1|WiseSqlUser1|Wis eSqlPass1|WISE_SQL_CONN_STR1 6. Use the new property for the connection string in the SQL script that executes the connection with the additional SQL Server. See Setting SQL Connection Strings on page 256. Example: Use the WISE_SQL_CONN_STR1 property for the connection string. See also: About the SQL Connection Dialog on page 422 Adding the Custom Property Dialog The Custom Property dialog box lets you specify Windows Installer properties that can be set by the end user during installation. You might use this if there are environmentdependent values that you cannot predict, which must be provided by the end user, such as user names and passwords. You can use this dialog box to gather property values to replace in an XML file. See Editing XML Files During Installation on page 131. This dialog box does not appear in any installation by default, and must be added through the New Dialog Wizard. Warning Do not add more than one Custom Property dialog box to a single installation; only one per installation is supported. If an installation contains multiple Custom Property dialog boxes, then multiple, identical dialog boxes appear to the end user at run time. To add the Custom Property dialog box 1. Select Installation Expert > Dialogs page. 2. Click Add. The New Dialog Wizard appears. See Creating a New Dialog on page 406. 3. On the Select Dialog Type page, select Custom Property Dialog and click Next. 4. Leave the defaults on the Dialog Properties page and click Next. The Select Custom Properties page appears, where you can either choose existing Windows Installer properties or create new properties. 5. Complete the page: „ Existing Properties To add an existing property, select it from this list and click Add. To create a new property, select from this list, and define the new property. See Creating a New Property on page 393. Windows Installer Editor Reference 425 Working With Dialogs 6. „ End User-Configurable Properties This list, which you build with the Add button, contains the properties that will be editable by the end user in the Custom Property dialog box during installation. „ Property Description For each property you added in End User-Configurable Properties, select the property name and add a description here to help the end user understand how to set the property. This is limited to about 275 characters, because of the size of the field that appears on the Custom Property dialog box. „ Display property value as asterisks during installation To mask the property value during installation, select the property name in End User-Configurable Properties and mark this check box. If the end user sets this value during installation, their entry is masked, and they must enter the property value a second time to verify the entry. This also omits the property value from the installation log. Use this feature when the property value includes sensitive information (example: a password). Finish the New Dialog Wizard. The Custom Property dialog box now appears in the list of dialog boxes on the Dialogs page. When you run this installation, the Custom Property dialog box appears. To edit the properties on the Custom Property dialog box 1. Select Installation Expert > Dialogs page. 2. In the list of dialog boxes, select Custom Property Dialog. 3. Click Details. 4. On the Dialog Details dialog box, click the Edit button. The Edit Custom Properties dialog box appears, where you can change the properties. Windows Installer Editor Reference 426 Chapter 18 Macro Editor This chapter includes the following topics: z About the Macro Editor on page 427 z About Macro Files on page 427 z About the Macro Editor Window on page 430 About the Macro Editor The Macro Editor provides access to Wise Automation, which programmatically controls Windows Installer Editor. Use Wise Automation to perform tasks that occur regularly and require multiple steps in the user interface. Example: You can write Wise Automation in the Macro Editor to automate daily builds. To view the Wise Automation Reference, open WiseAutomation.chm, which is in the Technical Documentation subdirectory of this product’s installation directory. Warning You should be familiar with macros and comfortable with Visual Basic to use this feature. For information on Visual Basic, visit msdn.microsoft.com/vbasic/. Note You can use Wise Automation with Visual Studio or other scripting environments. About Macro Files Use the Macro Editor to create and edit macro files. The default macro file in the Templates folder (Macros.wbs) contains sample macros. These samples are commented out, which means that you can view the script in the Macro Editor but you can’t run the macros unless you uncomment the script. You can add macros to Macros.wbs, and edit and delete its macros. Each new file you start in Windows Installer Editor has Macros.wbs attached. When you open the Macro dialog box, you can attach a different macro file. You can create the following types of macros: z Event macros that run when you fire the corresponding event. z Macros that you run manually. If your .WBS files include event macros, you might encounter a situation in which you want to create a new project that doesn’t run these macros. Example: You might have a macro that runs on the New event and adds a specific set of files to a specific set of directories every time you start a new project. To start a new project that does not include these files and directories, you can create a new .WBS file that doesn’t contain any macros. Then, attach this macro file to your project. Windows Installer Editor Reference 427 Macro Editor The Macro Editor doesn’t let you save a .WBS file under a different name. To rename a macro file, change the file name in Windows Explorer. See also: Creating, Editing, and Running a Macro on page 428 About the Macro Editor Window on page 430 Creating, Editing, and Running a Macro The Macro Editor is similar to the Microsoft Visual Basic Editor. For information on Visual Basic, visit msdn.microsoft.com/vbasic/. To create a macro 1. Select Edit menu > Macros. The Macro dialog box appears. 2. Complete the dialog box: „ 3. Macro Is Run Select:  Manually to create a manually-run macro.  On Windows Installer Editor event to create a macro that runs on an event. „ Event Name For a manually-run macro, enter a name for the new macro. Do not include spaces in the name. For an event macro, select an event. „ Pathname When you create a new macro, it is added to the macro file displayed. To add the new macro to a different .WBS file, browse to the file’s location. To create a new .WBS file, click New and specify the file. Click Create. The Macro Editor window appears. See About the Macro Editor Window on page 430. 4. In the script box, write the macro. 5. In the Macro Editor, select File menu > Save. 6. To create another macro, select Script menu > Add New Macro, enter a name for the macro on the dialog box that appears, write the macro, and save it. 7. When finished, exit the Macro Editor. To edit a macro 1. Select Edit menu > Macros. The Macro dialog box appears. 2. From Macro Is Run, select: „ Manually to edit a manually-run macro. „ On Windows Installer Editor event to edit a macro that runs on an event. Windows Installer Editor Reference 428 Macro Editor 3. In the list box, select the macro to edit. If the macro is in a file other than the one shown in Pathname, browse to the file’s location. 4. Click Edit. The Macro Editor window appears. See About the Macro Editor Window on page 430. 5. Edit the macro. 6. In the Macro Editor, select File menu > Save. 7. Exit the Macro Editor. To run a macro manually 1. Select Edit menu > Macros. The Macro dialog box appears. 2. From Macro Is Run, select Manually. 3. In the list box, select the macro to run. If the macro is in a file other than the one shown in Pathname, browse to the file’s location. 4. Click Run. See also: About Macro Files on page 427 Events That Can Trigger a Macro on page 429 Events That Can Trigger a Macro Using the Macro Editor, you can write macros for OLE Automation events. Example: If you write a macro for the AddFile event, the macro runs every time you add a file to an installation. See Creating, Editing, and Running a Macro on page 428. Event What you could do with a macro AddFile Have each .DLL or .EXE file you add marked Read-only or have all .DLL files placed into the System directory. New Have a specific set of files added each time you start a new installation. You could also add a message box so you can choose not to have the files added. Open Replace all previously-added files with any updated files in a certain folder each time you open an installation. QueryDisplayValidation Have Package Validation not display certain ICE error messages. To do this, set the variable bDisplay to FALSE for that error. Windows Installer Editor Reference 429 Macro Editor Event What you could do with a macro QueryFixValidation Have Package Validation determine if an ICE error is fixable and supply code to fix it. It is first called when bCheckOnly = TRUE. If bFix is set to TRUE, it determines that the error is fixable and the Correct button on the Package Validation View / Correct dialog box is enabled. When the user clicks the Correct button, the macro is called again with bCheckOnly = FALSE. The macro should then execute the changes needed to fix the ICE error. Run If an installation requires files that are accessed by a custom action, the macro can ensure that these files are copied to the proper location before you run the installation. Save Run several checks to ensure an installation adheres to your corporate standards. SetupCapture Have your standards imposed on an installation when you finish running SetupCapture in Wise Package Studio. Test Same as Run. VBImport Have all relevant entries in the database tables changed to comply with your corporate standards. About the Macro Editor Window Warning You should be familiar with macros and comfortable with Visual Basic to use this feature. For information on Visual Basic, visit msdn.microsoft.com/vbasic/ The Macro Editor window with all its functions is very similar to the Microsoft Visual Basic window. Buttons These are unique to the Macro Editor or are in some way different from those in Visual Basic: Options Opens the Script Editor Options dialog box, where you set and change the appearance of a script Members Is context-sensitive and gives you properties and methods in the context of a clicked object If your pointer is not on an object when you select this item from the right-click menu, then it lists all available properties and methods. Properties and methods for an object are all predefined in Windows Installer Editor. The global list also contains Visual Basic functions. Windows Installer Editor Reference 430 Macro Editor Repeat Finds text again Exit Closes the Macro Editor window; if you have made changes to the current macro, a message prompts you to save or discard your changes Event View Shows only one macro at a time Object View Shows all macros you have written for a particular object Full Module View Shows all macros you have defined for both Windows Installer Editor events and general functions Additional right-click menu options z List Objects Displays a global list of objects. Objects are predefined in Windows Installer Editor. For help on Wise functions, see the Wise Automation Reference, which is in the Help directory under the Windows Installer Editor installation directory. z List Functions Displays a global list of Wise and Visual Basic functions. For help on Visual Basic functions, visit msdn.microsoft.com/vbasic/. For help on Wise functions, see the Wise Automation Reference, which is in the Help directory under the Wise product installation directory. z Check Syntax Checks the macro for the correct syntax. z Revert to Saved Reverts the current macro to the last saved version, to undo any changes you made since you last saved. There are two drop-down lists along the top of the script box. The drop-down list on the left lets you select the type of macro: (General) for manually run macros, and WFWIEvents for event macros. The drop-down list on the right lets you select corresponding macros. Windows Installer Editor Reference 431 Chapter 19 Debugger for Windows Installer This chapter includes the following topics: z About the Debugger on page 432 z Running the Debugger on page 433 About the Debugger The Debugger for Windows Installer is an easy-to-use tool that lets you step through an installation to isolate and resolve problems. You can view the installation’s actions and their properties, the installation database tables, and the Windows Installer log file, and you can evaluate conditions. Use the debugger when an installation doesn’t perform as you anticipated and you can’t readily determine why. The Debugger for Windows Installer runs an installation, which can be an .MSI, a .WSI, or a transform (.MST), and lets you see exactly what it is doing at any time. As the installation runs, the debugger displays temporary Windows Installer properties that you can change to see how they affect the installation. Example: You can test a radio button’s conditions by changing its current values, or change the current value of an installation directory. The debugger does not fix problems in the installation. Once you have used the debugger to test the installation, use Windows Installer Editor to make the appropriate changes in the .MSI, .WSI, or .MST file. You cannot edit the installation within the debugger; you can only change temporary values to see how they affect the installation. See Working With Temporary Tables and Columns on page 435. See also: Running the Debugger on page 433 The Debugger Window To start the Debugger for Windows Installer, see Running the Debugger on page 433. To show or hide any pane, use the View menu. Parts of the Debugger window The debugger window consists of the following panes: Actions Windows Installer Editor Reference Lists the actions in the installation. These correspond to the actions in the Normal Installation mode of MSI Script. Dialog box actions can change depending on whether you are installing or uninstalling your application. 432 Debugger for Windows Installer Table List Lists all the tables in the installation in a window named _Tables. To open a table, double-click its row in the Table List. Move from one open table to another by clicking the corresponding tab at the bottom of this window. You can edit temporary table fields only. See Working With Temporary Tables and Columns on page 435. Log Displays a record of the actions that are processed during the installation. This installation log is generated by Windows Installer and is displayed for informational purposes only. Properties Displays the properties of the action selected in the Actions pane. It shows current values of the action’s condition, condition state, sequence, and type. You cannot change any of the properties in this pane. Condition Evaluator Lets you test conditions without adding them to the installation. When you enter conditions and run the installation, the Condition Evaluator displays the conditions’ values. See Evaluating Conditions on page 435. You can customize the debugger window by rearranging the panes. Any changes you make to the panes are retained the next time you run the debugger program. Use the right-click menu in the Actions, Properties, Condition Evaluator, and Log panes for these additional options: z Float as MDI Window Change the pane to a window with a tab in the Table List pane. To dock it again, right-click in the window and clear this option. z Allow Docking Dock a pane when you drag it near an edge of the screen. When this option is not marked, the pane does not dock regardless of where you drag it. You can also prevent docking by pressing Ctrl while dragging the pane. z Hide Remove the selected pane from the screen. To restore the pane, select it in the View menu. Running the Debugger The debugger runs through the actions in the Normal Installation mode only. It cannot debug the Administrative or Advertisement installations. To run the debugger 1. In Windows Installer Editor, open the .WSI, .MSI, or .MST to debug. 2. Click the Debug button at the lower right of the main window. The installation is saved and compiled if you made changes since the last compile. You are prompted to select an .MSI if you defined more than one release. The debugger window opens. Windows Installer Editor Reference 433 Debugger for Windows Installer 3. Set breakpoints if desired. See Setting and Clearing Debugger Breakpoints. 4. To run the installation, do one of the following: „ Run through the actions Select Debug menu > Go. This executes all actions up to the first breakpoint, if any. As each action is processed, a white arrow appears to its left. When the installation pauses at a dialog box for end user input, the white arrow stops at the next action to be processed. „ Run one action at a time Select Debug menu > Step Over or Step Into to execute only the action with the arrow to its left. After the action is processed, the arrow moves to the next line and the debugger waits for another command. Use Step Into if the installation contains one or more custom actions that call VBScript, and you have the VBScript Debugger or Visual Studio with InterDev installed. This opens the VBScript Debugger or Visual Studio and lets you debug the VBScript. When you are finished, you can return to the installation in the Debugger for Windows Installer. Step Over runs VBScript actions but does not open the VBScript Debugger. „ 5. Run to a selected action Select the action, then select Debug menu > Run to Selection. This executes all the actions up to the selected action. After the actions are processed, the arrow moves to the selected action and the debugger waits for another command. To stop the installation, select Debug menu > Stop Debugging or click Cancel in the installation’s user interface. Setting Properties and Applying Transforms in the Debugger You can set properties and apply transforms to installations that you test in the debugger by running the debugger (Debugger.exe) from the command prompt and using standard Windows Installer command-line options. Examples: z To change the value of a public property: path\debugger.exe /package path\package_name INSTALLLEVEL=1 z To apply a transform to the installation package using the TRANSFORMS property: path\debugger.exe /package path\package_name TRANSFORMS=path\transform_name.mst For more information on using Windows Installer command-line options, search for “Command-Line Options for the Microsoft Windows Installer Tool Msiexec.exe” in the MSDN Library (msdn.microsoft.com/library). Setting and Clearing Debugger Breakpoints A breakpoint is a place in the installation where you temporarily halt the execution. You set breakpoints in the Actions pane of the debugger. When you set a breakpoint and then run the installation, it pauses at the breakpoint and waits for another command. You can set multiple breakpoints. Windows Installer Editor Reference 434 Debugger for Windows Installer To set a breakpoint Click the action at which you want to set a breakpoint, then press F9. You can set breakpoints on sequences and control events only. To clear a breakpoint Click an action with a breakpoint and press F9. To clear all breakpoints at once, press Ctrl+Shift+F9. Evaluating Conditions To display the Condition Evaluator pane, select View menu > Condition Evaluator. This pane lets you test conditions without having to add them to the installation. You enter the condition or conditions in the Condition Evaluator, and then run the installation in the debugger. The Condition Evaluator returns the values, either TRUE or FALSE, for the conditions you entered. To enter a condition, click in the Condition column of the Condition Evaluator pane, then enter the condition. Conditions you enter are saved from session to session. To delete a condition, click its Condition column and press Delete. Working With Temporary Tables and Columns As you run the installation in the Debugger for Windows Installer, the Windows Installer runtime creates a temporary table named _Property and adds temporary columns to the Component, Feature, and File tables. The fields in these temporary columns represent the current values of directories, user-defined properties, and Windows Installer properties. This is where you do most of your debugging. Stop the installation to view a particular value and make sure it’s set correctly, or to change a temporary value to see how that affects the installation. To change a temporary field’s value, triple-click in its column and type the new value. Changing temporary values does not affect the installation file; it just provides a way to try different values. When you decide what changes need to be made, update the installation in Windows Installer Editor. When you change a setting in an installation dialog box, the corresponding property value in the _Property table changes. As you step through the installation, you’ll notice that certain tables and fields display in red. This means they have changed since the last step or, if you are not stepping over, since the beginning of the installation or the last breakpoint. Searching For Text in Tables Within the Debugger for Windows Installer, you can search for text in the entire database, the current table only, or the current column only. To do so, select Edit menu > Find. Windows Installer Editor Reference 435 Chapter 20 Using MSI Script This chapter includes the following topics: z About MSI Script on page 436 z The MSI Script Window on page 437 z Editing Sequences on page 441 z Calling WiseScripts with Custom Actions on page 443 z Guidelines for Using Custom Actions on page 449 z Launching a Custom Action from a Dialog on page 454 z Troubleshooting Custom Actions on page 455 About MSI Script MSI Script™ provides an easy-to-use environment for editing Windows Installer installation sequences, even if you are not familiar with the underlying Windows Installer technology. MSI Script™ contains the sequences of actions that make up an installation. The action sequences are pre-defined following the Windows Installer guidelines for creating sequences. The actions are in the recommended order, and, where appropriate, conditions are set. We recommend that you do not delete or move any standard actions. See Standard Actions Reference in the Windows Installer SDK Help. The existing action sequences are sufficient for most installations. If you need specialized functionality not offered by Windows Installer, you can add custom actions to an installation. With custom actions, you can call .EXEs, .DLLs, WiseScripts, JScripts, and VBScripts. You can set installation properties and directories and call nested .MSI files. You can also perform many other functions such as opening a Web page or downloading a file from a Web site. See Custom Action Reference on page 456. Windows Installer Editor uses custom actions to add functionality that is not available with the Windows Installer standard actions. When you use certain features, such as custom actions that call a .DLL, Wise custom actions are added to the installation. See Wise Custom Actions on page 498. Warning Removing Wise custom actions might cause problems with the installation. See also: About Installation Modes About Installation Sequences on page 440 Finding Text in MSI Script on page 440 Windows Installer Editor Reference 436 Using MSI Script The MSI Script Window To access MSI Script™, click the MSI Script tab at the bottom of the main application window. Installation Mode Restricted Areas Actions Sequences z Installation Mode Installation modes represent the different ways an installation can be run. Choose whether to work on a normal installation, an advertisement installation, or an administrative installation. See About Installation Modes on page 437. z Actions You can select from standard actions, which are built-in Windows Installer functions, or custom actions, which you configure yourself. To learn about an action, doubleclick it and press F1. z Restricted Areas If you select an action that has restrictions on its placement, the restricted area is shaded. z Sequences Below the sequence area are tabs that let you switch between sequences. Each installation mode is comprised of sequences, which, in the Windows Installer database, correspond to sequence tables. About Installation Modes MSI Script contains three installation modes: Normal Installation, Administrative Installation, and Advertisement Installation. Access these modes from the Installation Mode drop-down list in MSI Script. They represent the actions that are performed during each type of installation. They contain standard Windows Installer actions, dialog box actions, and custom actions. All installation modes are included in every Windows Windows Installer Editor Reference 437 Using MSI Script Installer installation you create, but each mode is run only under certain circumstances. Installation modes are not used with merge modules. For information on dialog box groupings, see About Dialogs on page 395. Normal Installation Select this installation mode to edit the sequences that are run during a normal installation. This is the most common type of installation. If the application is not already installed when an end user double-clicks the installation .MSI, the standard installation wizard appears (Install Dialogs), which installs the product. If the application is already installed when an end user double-clicks the installation .MSI or if the end user selects it from the Add/Remove control page, the installation runs in maintenance mode (Maintenance Dialogs), which provides options to modify, repair, or uninstall an application. Administrative Installation Select this installation mode to edit the sequences that are run during an administrative installation. An administrative installation copies a source image of the application to a network; the source image resembles the directory structure of the installed application. End users who have access to the administrative installation can then install the application from the network location. To run an administrative installation, use the command-line option /a. (Example: msiexec /a “C:\path\Sample.msi”.) An administrative installation uses the Admin Dialogs. See also: Performing an Administrative Installation of a Windows Installer Package in the Wise Package Studio Help Command Line Options in the Windows Installer SDK Help Advertisement Installation Select this installation mode to edit the sequences that are run during an advertisement installation. An advertisement installation places entry points, such as shortcuts, on the destination computer without actually installing the application. When an installation is opened in advertising mode, only the Execute sequences are run because it does not have a User Interface sequence, and therefore no dialog boxes appear. See Advertisement in the Windows Installer SDK Help. To run an advertisement installation, use the command-line option /j. Example: msiexec /j “C:\path\Sample.msi”. All Custom Actions Select All Custom Actions from the Installation Mode drop-down list to view the All Custom Actions list. The All Custom Actions list does not represent an installation mode, but instead is a repository of all custom actions stored in the CustomAction table of this installation. Use All Custom Actions to do the following: Windows Installer Editor Reference 438 Using MSI Script z Add a custom action outside a sequence See Adding a Custom Action Outside a Sequence. z Add a custom action to multiple sequences See Adding a Custom Action to Multiple Sequences on page 439. z Quickly review and edit custom actions If your custom actions are scattered, you can quickly review and edit them without scanning through each sequence to find them. Adding a Custom Action Outside a Sequence You can add a custom action that is not invoked unless you provide a mechanism to call it during installation, such as creating an event that triggers the custom action. Example: You might want a custom action to run if an end user clicks a button on a dialog box during installation. See Launching a Custom Action from a Dialog on page 454. To add a custom action outside a sequence 1. Select MSI Script. 2. From Installation Modes, select All Custom Actions. This displays a list of all custom actions in this installation. 3. In the Actions list, double-click the action. 4. Complete the Details and Properties tabs as you would normally. If the action does not have these tabs, then you cannot add it outside a sequence. 5. On the Location tab, mark No Sequence. This tab is only available in the All Custom Actions mode. 6. Click OK. Adding a Custom Action to Multiple Sequences When you copy and paste an action between sequences, an entirely new copy of that custom action is stored in the installation database. To avoid this duplication and possible use of extra disk space, you can assign an action to multiple sequences. To add a custom action to multiple sequences 1. Select MSI Script. 2. From Installation Modes, select All Custom Actions. This displays a list of all custom actions in this installation. 3. In the Actions list, double-click the action. 4. Complete the Details and Properties tabs as you would normally. If the action does not have these tabs, then you cannot add it to multiple sequences. 5. On the Location tab, clear No Sequence. This tab provides another way to perform tasks that you normally perform in the User Interface, Execute Immediate, or Execute Deferred sequences. Windows Installer Editor Reference 439 Using MSI Script See Using the Custom Action Location Tab on page 484. 6. From Sequence, select a sequence. 7. In the list box of actions, select an action and click Add. The action is added to the sequence, below the action you selected. If you are in a merge module, the layout of the Location tab is different. See Using the Custom Action Location Tab for Merge Modules on page 485. 8. Select other sequences and add the action to them. 9. Click OK. About Installation Sequences Installation sequences are represented by tabs below the Installation Sequence section in MSI Script. Windows Installer has two main types of sequences: User Interface and Execute. The User Interface sequence, which is executed at the beginning of installation, gathers system information, displays dialog boxes to the end user, and records end user choices. It is suppressed during silent installations. The Execute sequence installs the application and makes changes to the system. During installation, Windows Installer first goes through each action in the Execute sequence and builds an internal installation script to follow. You cannot see or access this internal script. This first pass is referred to as immediate mode and is represented by the Execute Immediate tab. After it creates the internal installation script, it runs the script it created, performing the actions that change the system. The second pass is referred to as deferred mode, and encompasses all the actions between InstallInitialize and InstallFinalize. It is represented by the Execute Deferred tab. This makes it easier to specify in which mode to run an action. For information on where to place a custom action, see Guidelines for Custom Action Location on page 450. When Windows Installer generates the installation script, it generates a rollback script that will undo the actions of the installation script. The rollback script is executed if the installation is canceled or is unsuccessful, and is also run in deferred mode. Although you cannot view or edit the rollback script, you can specify that custom actions you add be added to it; use the In-Script Options field on the Properties tab of the custom action details dialog box. On Windows 2000/XP/2003/Vista, Windows Installer runs as a service, which is registered in the Services control panel. When an .MSI is run, it is run by the service. The Windows Installer service can run with elevated privileges based on policies, and the Windows Installer database runs with the current user’s privileges. When you add custom actions, you can specify whether they should be run with elevated privileges (system context) or with user privileges (user context). Set privileges to user context or system context in the In-Script Options field on the Properties tab of the custom action details dialog box. For information on Windows Installer sequence tables, see Using a Sequence Table in the Windows Installer SDK Help. Finding Text in MSI Script Press Ctrl+F and enter a text string to find lines that contain that string. All installation sequences are searched, and you can select which installation mode to search. Windows Installer Editor Reference 440 Using MSI Script Note You cannot replace text using this feature, but you can replace text in Setup Editor > Tables tab. See Searching for Table Data on page 380. See also: About Installation Modes on page 437 About Installation Sequences on page 440 About MSI Script on page 436 Editing Sequences Use the commands on the Edit menu, the right-click menu, or the tools on the toolbar to edit an MSI Script™ sequence. You can edit only one action at a time, but you can cut, copy, or paste several actions at a time. To edit an action, select its installation mode, click its sequence tab, and select the action from the Installation Sequence pane. See: Types of Actions in MSI Script Sequences on page 441 About the Standard and Custom Tabs on page 442 Adding and Editing Actions on page 442 Commenting Out Script Lines on page 443 About MSI Script on page 436 Types of Actions in MSI Script Sequences z Windows Installer standard actions (gray) These built-in actions are defined by the Windows Installer SDK. Double-click a standard action in the Installation Sequence list and press F1 to access the Windows Installer SDK help for the action. These actions perform basic installation tasks, such as creating shortcuts and writing files. You cannot edit standard actions, and you should not move or delete them. See Standard Actions in the Windows Installer SDK Help. z Dialog box actions (violet) Dialog box actions display dialog boxes or groups of dialog boxes. Often, one Display Dialog action includes several dialog boxes. To edit or view all the dialog boxes associated with a Display Dialog action, double-click the Display Dialog line, and the dialog box opens in Setup Editor > Dialogs tab. See Using the Dialogs Tab on page 402. z Custom actions (black) You can add custom actions to an installation to perform actions that are not available using the Windows Installer standard actions. Custom actions are sometimes added automatically to enhance some capabilities of Windows Installer. See Wise Custom Actions on page 498. z If Statements - Conditions (blue) Use If Statements to indicate that a condition is attached to the actions between the If Statement and its corresponding End statement. Windows Installer Editor Reference 441 Using MSI Script z Remarks (green) Remark statements document the script. Remarks that explain how the script works are already added to new scripts you create. Removing these remarks has no adverse affect. About the Standard and Custom Tabs You can add both custom actions and standard actions to an MSI Script sequence. At the lower left of the Actions list, the Custom tab displays custom actions, and the Standard tab displays Windows Installer built-in actions. The Standard tab displays only those Windows Installer actions that are not already in the selected sequence. Display Dialog actions are not displayed on either the Standard or Custom tab. To add a dialog box, use Setup Editor > Dialogs tab. After you add a dialog box, it appears in MSI Script as an action. Adding and Editing Actions To add an action to an MSI Script sequence, do one of the following: z Drag and drop the action Drag the action from the Actions list onto a line in the Installation Sequence list. The new action appears before the line that is highlighted when you drop the action. z Double-click the action In the Installation Sequence list, select the line above which the new action should appear and double-click the action in the Actions list. z Type and select the action In the Installation Sequence list, select the line above which the new action should appear. Type the first few letters of the action name. As you type, the current line becomes a drop-down list containing all the action names. Select an action and press Enter. About restricted areas If an action has restrictions on its placement in the sequence, the restricted areas are shaded in the Installation Sequence list when you select that action in the Actions list. Place the action in a non-restricted area. Editing custom action settings When you add a custom action, a dialog box appears that lets you enter settings for the custom action. To access this dialog box for an existing custom action, double-click it. For information on these dialog boxes, see Custom Action Reference on page 456. If you double-click Display Dialog actions, the dialog box opens in Setup Editor > Dialogs tab. To move an action, select Move Up or Move Down from the Edit menu. Note You cannot edit Windows Installer standard actions, which are displayed in gray, and you should not move or delete them. You can also copy and paste actions to other locations in the installation sequence. However, each time you copy and paste an action, an entirely new copy of the action is stored in the installation. To avoid this duplication, see Adding a Custom Action to Multiple Sequences on page 439. Windows Installer Editor Reference 442 Using MSI Script See also: Guidelines for Using Custom Actions on page 449 Types of Actions in MSI Script Sequences on page 441 Commenting Out Script Lines While you are working in MSI Script, you can temporarily disable certain actions to help you with your debug process. You do this by commenting out actions. Commented actions remain in the sequence, but are skipped when the sequence is executed. z To comment out an action, select the line or lines in the sequence that you want to disable and select Edit menu > Comment. The commented lines appear in green. z To reactivate commented lines, select them again and select Comment a second time. Calling WiseScripts with Custom Actions The Run WiseScript custom actions provide the ability to call WiseScripts. WiseScript™ technology provides many specialized functions that are not available in or are difficult to do with Windows Installer technology. In a WiseScript, you can use special actions that let you pass information between the main Windows Installer installation and the WiseScript .EXE that is being called. Note If the main Windows Installer installation is run silently, a called WiseScript is called silently. About WiseScript Editor WiseScript Editor is a WiseScript™ authoring environment that you can use to automate administrative tasks. You also can use it to create .EXEs to use as custom actions in Windows Installer installations. These custom actions can extend the capabilities of Microsoft Windows Installer and simplify installation tasks (example: parsing and arithmetic functions) that are difficult to accomplish with Windows Installer. WiseScript Editor is embedded within Windows Installer Editor and appears when you create a custom action that calls a WiseScript. WiseScript Editor contains the same scripting interface as WiseScript Package Editor, but it does not contain the Installation Expert interface or other installation development tools. Calling a WiseScript .EXE versus calling a regular .EXE Creating a custom action that calls a WiseScript .EXE is similar to calling a regular .EXE, except that communication can take place between Windows Installer and WiseScript. This is possible through the use of the Get Windows Installer Property, Set Windows Installer Property, and Evaluate Windows Installer Condition actions in the WiseScript. For information on these actions, see About WiseScript Actions in the WiseScript Editor Help. See also: Windows Installer Editor Reference 443 Using MSI Script Troubleshooting: When WiseScript Custom Actions Fail on Windows Vista on page 448 Run WiseScript From Destination on page 479 Run WiseScript From Installation on page 479 Run WiseScript From Installed Files on page 481 About Script Editor in the WiseScript Editor Help Examples of WiseScripts You Run From an .MSI This section provides examples of how to use WiseScripts that are called by a Windows Installer installation. For script examples, see: z Using a WiseScript to Parse a Path on page 444 z Using a WiseScript to Install a License File on page 445 z Uninstalling Changes Made by a WiseScript on page 446 Using a WiseScript to Parse a Path Because the Microsoft Windows Installer technology does not allow for parsing, you cannot use it to create an installation that extracts a path from the registry and then parses the path to isolate the file name into a property. However, you can send the path to a WiseScript executable, do the parsing, then send the file name back in a Windows Installer property. Example: You extract the path C:\Program Files\Application\Application.exe, use WiseScript to parse the file name, Application.exe, and send the file name back in a Windows Installer property. To use a WiseScript to parse a path 1. Write a WiseScript that uses: „ Get Windows Installer Property script action to get the property named APPLICATION_PATH into a temporary variable. „ Parse String script action on the temporary variable to put the file name into another temporary variable. „ Set Windows Installer Property script action to put the file name back into the Windows Installer property APPLICATION_PATH. 2. In Installation Expert, use the System Search page to get a registry entry that consists of a full path. Put the path into a property named APPLICATION_PATH. 3. In MSI Script, add a custom action to Run a WiseScript from Installation and specify the WiseScript you wrote. 4. When an end user runs the Windows Installer installation, it calls the WiseScript, which parses the path. When the Windows Installer installation continues running, APPLICATION_PATH contains Application.exe. The sample WiseScript looks like this (the script lines are numbered for clarity): 1. Get Windows Installer Property APPLICATION_PATH into TEMP 2. Parse String "%TEMP%" into PATH and FILE 3. Set Windows Installer Property APPLICATION_PATH to %PATH% Windows Installer Editor Reference 444 Using MSI Script Using a WiseScript to Install a License File Virtually anyone can open an installation .MSI and see the files and other information it contains. Usually, this is an advantage, but it can be a disadvantage when you need to include sensitive information such as passwords or a license file. To hide sensitive files, install them with a WiseScript and save them within the WiseScript .EXE. Example: Your application comes in two editions: Regular and Super. Serial numbers for the Regular edition begin with the letter R, and serial numbers for the Super edition begin with S. The serial number the end user enters during installation determines the license file that gets installed, which determines which features are turned on. You set up the installation to have the license files installed by the WiseScript instead of the .MSI so that the license files are embedded in the WiseScript .EXE and cannot be opened. To use a WiseScript to install a license file 1. Write a WiseScript that uses: „ Get Windows Installer Property script action to get the property named SERIALNUM into a temporary variable named SERIALNUMBER. „ Set Variable script action, with the Evaluate Expression operation, to place the first character of the serial number in a variable named EDITION. „ If Statements and Install File(s) script actions to install the appropriate license file based on the value of the EDITION variable. 2. In MSI Script, add a custom action to Run a WiseScript from Installation and specify the WiseScript you wrote. 3. During the Windows Installer installation, the WiseScript runs, gets the first character of the serial number, and installs the appropriate license file. Windows Installer Editor Reference 445 Using MSI Script The sample WiseScript looks like this (the script lines are numbered for clarity): 1. Get Windows Installer Property SERIALNUM into SERIALNUMBER 2. Get Windows Installer Property INSTALLDIR into MAINDIR 3. Set Variable EDITION to LEFT$(SERIALNUMBER,1) 4. Check free disk space 5. If EDITION Equals "R" then 6. Install File c:\Development\Source\RLicense.exe to %MAINDIR%\RLicense.exe 7. Else 8. If EDITION Equals "S" then 9. 10. Install File c:\Development\Source\SLicense.exe to %MAINDIR%\SLicense.exe Else 11. If EDITION Equals "" then 12. Display Message "Invalid serial number" 13. 14. End End 15. End To ensure the license file is uninstalled when the application is uninstalled, add actions to the script to handle the uninstall. See Uninstalling Changes Made by a WiseScript. Uninstalling Changes Made by a WiseScript You can use the Run WiseScript custom actions to make changes to the destination computer when the script is run from your .MSI. (Example: You can use the Install File(s) script action to add files or you can use the Edit Registry script action to add, edit, or delete keys or values in the registry.) However, the Windows Installer installation does not recognize any changes the WiseScript makes to the system and therefore will not uninstall any of these changes during uninstall of the main Windows Installer installation. To solve this problem, do the following: z In the WiseScript, include steps to install an installation log and Unwise32.exe. z In the .MSI, during an uninstall, use a custom action to call the Unwise32.exe that is in the WiseScript. Example: You have an .MSI named Core and a WiseScript named CorePlus. CorePlus includes an Install File(s) script action that installs a file named A.dll. You want to make sure that A.dll gets uninstalled when Core is uninstalled. In the Core .MSI, do the following: 1. Select MSI Script and click the Execute Immediate tab. 2. Scroll down and click directly below the RemoveExistingProducts action. 3. Add an If Statement with a value of NOT Installed. This condition causes it to run only during initial installation of Core. Windows Installer Editor Reference 446 Using MSI Script 4. 5. Add a Run WiseScript From Installation custom action and set the following: „ Custom Action Name: ActionInstallCorePlus „ WiseScript .EXE File: C:\Plus\CorePlus.EXE „ Command Line: Leave this blank. On the Properties tab, leave the defaults. Add an End Statement. The above script lines install CorePlus, which in this example is A.dll. In the following script lines, you make provisions for the uninstall. 6. Add an If Statement with a value of REMOVE~=“ALL”. This condition causes it to only run during uninstall of Core. 7. Add an Execute Program From Destination custom action and set the following: „ Custom Action Name: RemoveCorePlus „ Working Directory: INSTALLDIR „ EXE and Command Line: [INSTALLDIR]Unwise32.exe /S install.log On the Properties tab, leave the defaults. 8. Add an End Statement. The MSI script looks like this (the script lines are numbered for clarity): 1. If NOT Installed then 2. Run WiseScript From Installation C:\Plus\CorePlus.EXE 3. End 4. If REMOVE~=”ALL” then 5. Execute Program From Destination [INSTALLDIR]unwise32.exe /S install.log Default Directory Program Files\Core 6. End In the CorePlus WiseScript, do the following: 1. Add a Get Windows Installer Property script action and set the following: „ Dest. Variable: MAINDIR „ Property Name: INSTALLDIR INSTALLDIR is the installation directory of Core, the main Windows Installer installation. This sets the WiseScript installation directory to the same value as the main installation’s installation directory. 2. Add a Set Variable script action and set the following: „ Variable: MAINDIR „ New Value: %MAINDIR% „ Operation: Remove trailing backslashes. INSTALLDIR has a trailing backslash, but to be compatible with WiseScript, MAINDIR cannot have a trailing backslash. 3. Add an Open/Close INSTALL.LOG script action with Open new installation log marked and the log file path specified as %MAINDIR%\install.log. Windows Installer Editor Reference 447 Using MSI Script This causes the WiseScript to create a log in the installation directory. 4. Add an Install File(s) script action and set the following: „ Source Pathname: path to Unwise32.exe Unwise32.exe is in the WiseScript Editor subdirectory of this product’s installation directory. „ 5. Destination Pathname: %MAINDIR%\Unwise32.exe. Add an Install File(s) script action and set the following: „ Source Pathname: path to A.dll „ Destination Pathname: %MAINDIR%\A.dll. Add any other necessary script actions. (Example: You could edit registry entries, check if a certain file or directory exists, or rename a file or directory.) For this example, the CorePlus script installs only A.dll. For troubleshooting purposes, you might also want to add a Display Message script action that shows the value of %MAINDIR%. This lets you know when the WiseScript runs, and also gives you debugging abilities. The sample WiseScript looks like this (the script lines are numbered for clarity): 1. Get Windows Installer Property INSTALLDIR into MAINDIR 2. Set Variable MAINDIR to %MAINDIR% 3. Open new installation log file %MAINDIR%\install.log 4. Install File C:\Program Files\Unwise32.exe to %MAINDIR%\Unwise32.exe 5. Install File C:\Plus\A.dll to %MAINDIR%\A.dll Troubleshooting: When WiseScript Custom Actions Fail on Windows Vista The User Account Control (UAC) that was introduced with Windows Vista provides a temporary privilege-elevation model. When a program requires elevated privileges, an administrator is prompted for approval and a standard user is prompted to provide administrator credentials. Even if you have coded an installation to bypass the UAC prompting, the installation might fail if it contains WiseScript custom actions. When Windows Vista encounters a WiseScript .EXE, it interprets that .EXE as an installation and triggers User Account Control. To prevent UAC prompting on the WiseScript custom action, add a manifest to the WiseScript to indicate its run level. In Wise Package Studio 7.0 SP3 or later: z If you create the WiseScript in WiseScript Editor, the manifest is added automatically and the run level is set to asInvoker, which runs the WiseScript as the user who runs the .MSI. z If you create the WiseScript in WiseScript Package Editor, go to Installation Expert > Build Settings page and set the manifest file option to asInvoker or specify a custom manifest file. To update a legacy installation If you created the Windows Installer installation or the WiseScript in a Wise product earlier than Wise Package Studio 7.0 SP3: Windows Installer Editor Reference 448 Using MSI Script 1. Open the installation in Windows Installer Editor. a. Windows Installer Editor checks for custom actions that run a WiseScript. b. Each WiseScript .EXE is updated in memory with a manifest specifying the asInvoker run level. c. A task appears in the Task List to record each change. d. If the WiseScript .EXE had an associated row on the Windows Installer Editor Resources page, the Refresh check box for that resource is cleared so that the .EXE on disk is not used during the next compile. See Refreshing Binary Resources on page 103. 2. In WiseScript Editor or WiseScript Package Editor, open each WiseScript .WSE from its original location and recompile. 3. In Windows Installer Editor, go to Installation Expert > Resources page and re-select the Refresh check box for each WiseScript .EXE. 4. Clear the custom action-related tasks from the Task List. 5. Compile the Windows Installer installation. See also: Creating an Installation for Standard Users on page 70 Guidelines for Using Custom Actions When you use Windows Installer to install a file, it takes care of the repair and management of the file. When you use a custom action to change an installation, you take Windows Installer out of the loop. (Example: If you use a custom action to install a file, you must also include custom actions to repair or uninstall the file because Windows Installer is unaware of the file.) Therefore, use custom actions conservatively when making permanent changes on the destination computer, and use them only for actions that cannot be accomplished through Windows Installer. Warning Although you can change the order and conditions for standard actions and dialog boxes, we recommend that you do not change these settings unless you are proficient in the Windows Installer development environment. Many actions have restrictions that determine where they must appear in the sequence. See Actions with Sequencing Restrictions in the Windows Installer SDK Help for more details. The following topics provide guidelines for using custom actions: Guidelines Guidelines Guidelines Guidelines Guidelines Windows Installer Editor Reference for for for for for Custom Action Location Custom Action Conditions on page 451 Nested Installation Custom Actions on page 451 Calling VBScripts and JScripts on page 452 Calling .DLLs on page 453 449 Using MSI Script Guidelines for Custom Action Location General z Place the custom action as high in the sequence as possible where it executes properly. If it doesn’t execute properly when you test it, keep moving it lower in the sequence until it works. z If the custom action uses information that’s gathered during the User Interface sequence, place it after the actions that gather the information you need. z If the installation is run silently, items in the User Interface sequence do not execute. Note The User Account Control (UAC) that was introduced with Windows Vista affects the execution of custom actions that access protected areas on the destination computer. You might need to elevate part or all of the installation to prevent the failure of such custom actions. See About UAC Elevation of Windows Installer Installations on page 176. Correct Sequence If the action does this Place it in this sequence Gathers input from an end user User Interface Needs to change properties User Interface or Execute Immediate Is an Install MSI custom action Execute Immediate Is to be executed sometime during the installation of files Execute Immediate or Execute Deferred Makes a change to the system Execute Deferred Depends on a previous action Execute Deferred Place it between the InstallInitialize and InstallFinalize actions, near the InstallFiles action. The InstallFiles action installs files during deferred mode. Windows Installer does not perform the action when it runs in Immediate mode. If a custom action depends on a change to the system, and the change has not yet been made, the custom action fails. Requires elevated privileges to run Execute Deferred Actions run in Deferred mode can be run under the system context. See the description of the In-Script Options field in Using the Custom Action Properties Tab on page 486. Windows Installer Editor Reference 450 Using MSI Script Restricted Areas in the Sequence z If an action has restrictions on its placement in the sequence, the restricted areas are shaded in the Installation Sequence list when you select the action in the Actions list. Place the action in a non-restricted area. Restrictions are defined by Windows Installer functionality. Example: You can’t run an action that depends on an installed file if the file is not yet installed. z If you use the Move Up and Move Down commands on a custom action that has restricted placement, keep in mind that the restricted areas will not be shaded. Before moving an action, select the action in the Actions list to view its restricted areas. Formatted Text z If you use formatted text in a custom action, such as a bracketed property name, the custom action must be placed after the CostFinalize action in the User Interface sequence. This is a Windows Installer requirement. z If you use formatted text in a custom action, do not put the custom action in the Execute Deferred sequence. Formatted text strings do not convert in the Execute Deferred sequence. The exceptions to this rule are the CustomActionData and ProductCode properties. See Formatted and Obtaining Context Information for Deferred Execution Custom Actions in the Windows Installer SDK Help. Guidelines for Custom Action Conditions Place a custom action between conditional If Statements to run it only if a certain condition is true. A condition can check whether the product is installed, the value of a property is true, if specific system requirements are met, and more. See Conditions on page 383 and Conditional Statement Syntax in the Windows Installer SDK Help. To Run Only During Initial Installation The Execute sequences under the Normal Installation mode run during initial installation and later during maintenance and uninstall installations. To run a custom action during the initial installation only, set its condition to NOT Installed. Installed is a Windows Installer property that is true if the product is installed. Example: If you add a custom action that opens a Readme file and set the action’s condition to NOT Installed, then the Readme opens during initial installation, but does not open during maintenance installations (reinstall, modify, and repair operations). To Run Only During Uninstall If the product is being uninstalled, the REMOVE property is set to All or ALL. To run a custom action during uninstall only, set its condition to REMOVE~=”ALL”. (The ~ causes the comparison to be case-insensitive.) Guidelines for Nested Installation Custom Actions You can call another installation from within the running installation with an Install MSI custom action. Use this type of custom action to deploy or uninstall one product from within the installation of another product. See Nested Installation Actions in the Windows Installer SDK Help. Windows Installer Editor Reference 451 Using MSI Script Limitations Nested installations are supported according to the Windows Installer specification. While nested installations may sometimes be necessary, we do not recommend using them because of the restrictions on their use. See a list of restrictions at the end of Nested Installation Actions in the Windows Installer SDK help. Usage According to the Windows Installer SDK, Install MSI custom actions should be placed between InstallInitialize and InstallFinalize of the main installation’s action sequence. Install MSI custom actions must be set to run synchronously. Example: Suppose your main installation, Main.MSI, has a button on a dialog box that, if clicked, installs Second.MSI. You can use an Install MSI custom action to run the second .MSI. Then you can use another Install MSI custom action to provide for uninstallation if the main installation is uninstalled. To specify the circumstances in which a nested .MSI is called, set conditional If Statements around the Install MSI custom action in the sequence. See Guidelines for Custom Action Conditions on page 451. Note Getting a nested installation to install is straightforward, but getting it to uninstall properly when the calling application is uninstalled requires that you add two custom actions. Set the first custom action to call the nested installation, and set its condition to NOT Installed (Custom Action Location dialog box). Set the second custom action to call the nested installation also, set its Property Settings field to REMOVE=ALL (Custom Action Target dialog box), and set its condition to REMOVE~=”All”. With this type of custom action, you can call only Windows Installer installations. To call an installation that was created with a WiseScript product, use a Run WiseScript custom action. To call an installation that was created with any other installation technology, use an Execute Program custom action type. A nested installation file can be accessed from the following locations: z It can be stored within the main installation file. See Install MSI From Installation on page 474. z It can be distributed along with the main installation file. See Install MSI From Relative Path on page 475. z It can be an installed or advertised application that already exists on the destination computer. See Install MSI From Destination on page 473. The return values for nested installation actions are the same as for other custom actions. See Custom Action Return Values in the Windows Installer SDK Help. Guidelines for Calling VBScripts and JScripts You can create a custom action that calls a JScript or VBScript file that you have written. You cannot pass parameters to JScript or VBScript. You must use your script to read and write properties to the installation—your script can access the current installation session. The exceptions are the Call JScript From Embedded Code and Call VBScript Windows Installer Editor Reference 452 Using MSI Script From Embedded Code. They let you store the script inside the custom action and resolve formatted property names and other references. Make sure the destination computer contains the runtime for JScript or VBScript. You can call scripts using custom actions, but you must author the JScript or VBScript. The built-in Macro Editor is not meant to author JScripts and VBScripts that you call from custom actions. For help authoring the script, see the following topics in the Windows Installer SDK Help: Scripts Obtaining Context Information for Deferred Execution Custom Actions Downloading an Installation From the Internet Return Values of JScript and VBScript Custom Actions Accessing the current installer session from inside a custom action? Guidelines for Calling .DLLs The types of custom actions that call .DLLs from an installation are Call DLL Custom Actions and Call Custom DLL Custom Actions. Call DLL Custom Actions Two custom actions—Call DLL From Installed Files, Call DLL From Installation—use the Windows Installer method for calling .DLLs, which does not allow you to send any specific parameters to the .DLL. The only parameter you can send is the handle (of type MSIHANDLE) for the current installation session. From within your .DLL, you must use Windows Installer function calls to access the current installer session and database properties. Also, the return value for the .DLL is limited to a constant specifying whether the .DLL call was successful. See Custom Action Return Values in the Windows Installer SDK Help. Your function declaration statement should look something like this: UINT__stdcall CustomActionName(MSIHANDLE hInstall) To write your .DLL function according to Windows Installer guidelines, see the following topics in the Windows Installer SDK Help: Dynamic-Link Libraries Accessing the current installer session from inside a custom action? Custom Action Type 1 Custom Action Type 17 Call Custom DLL Custom Actions Three custom actions—Call Custom DLL From Installation, Call Custom DLL from Installed Files, Call Custom DLL From Destination Computer—allow variable parameter lists to be sent to the .DLL. These actions are passed through a Wise .DLL. This method for calling .DLLs is an alternative to the Windows Installer method. This method works with the way you typically code .DLL functions, and does not require you to code your functions according to Windows Installer guidelines. However, if you use this method, you should be aware that your .DLL call gets passed through a Wise-created .DLL that handles the passing of parameters. A Wise-created custom action is added to the installation to enable this passing of parameters. See Wise Custom Actions on page 498. Windows Installer Editor Reference 453 Using MSI Script In the User Interface or Execute Immediate sequences, you can send Windows Installer properties to the .DLL function as parameters. The property’s current value is passed to the function, and, if the function changes that value, the new value is put into the corresponding property. In the Execute Deferred sequence, the number of properties you can access is limited. You can only access UserSID, CustomActionData, and ProductCode. CustomActionData is filled with the property value of any Windows Installer property that has the same name as the Custom Action. See Obtaining Context Information for Deferred Execution Custom Actions in the Windows Installer SDK Help. Debugging a Call Custom DLL Custom Action You can debug .DLL functions while you are running an installation. Debugging a .DLL is different from using the Debugger for Windows Installer, which shows the run-time environment of the .MSI. Debugging a .DLL shows your .DLL code in Microsoft Visual Studio. The following are requirements for using .DLL debugging: z You authored the .DLL and have its source code on your computer. z You have Microsoft Visual Studio installed. z You are using one of the Call Custom DLL custom action types. z MSDEV.EXE is in your path for debugging. To enable debugging, use Setup Editor > Product tab to set the property named _WiseDebugMode to 1. Then test or run the installation. Microsoft Visual Studio opens and attaches to the installation process, and a breakpoint is invoked near the start of your .DLL. You need to step a few times to get out of Windows Installer compiled code and into your .DLL code. Note The debugging method described above only works with the Call Custom DLL custom action types. It does not work with the Call DLL custom action types. Launching a Custom Action from a Dialog You can use a control on a dialog box to run a custom action. Example: You can set a button so that if the end user clicks it, the custom action runs. 1. Select MSI Script. 2. From Installation Mode, select All Custom Actions. 3. Create a new custom action and configure it normally, but mark No Sequence on the Location tab. The action is not added to any sequence. 4. In Setup Editor > Dialogs tab, right-click a dialog box and select Add > Button. Make sure the button is not on top of a graphic. You can add other controls besides buttons. 5. On the Control tab of the button’s Properties dialog box, enter the label for the button in the Control Text list box. Windows Installer Editor Reference 454 Using MSI Script 6. On the Events tab, in the Publish Events group box, click Add and complete the dialog box: „ Event Select DoAction. „ Argument Enter the name of the custom action. The name is case-sensitive. When the installation is run, the button you added appears on a dialog box. When the end user clicks the button, the custom action you specified is run. Troubleshooting Custom Actions If a custom action doesn’t work: z Try moving it to a different sequence, or to a lower position in the current sequence. z Does the custom action require elevated privileges? If so, try running it in the Execute Deferred sequence. On the custom action’s Properties tab, set the InScript Options drop-down to Deferred Execution - System Context. z Make sure the custom action name is unique. To quickly survey your custom actions, select All Custom Actions from Installation Mode. z Does the custom action reference a Windows Installer property, such as REMOVE? Windows Installer standard actions set Windows Installer properties. It could be that the property your custom action is referring to is not set yet. Use the debugger to discover whether the property is set at the point where you expect it to be set. Keep moving the custom action down in the sequence until it works. z Is the installation trying to change restricted public properties? The ability to do this depends on several factors. See Restricted Public Properties in the Windows Installer SDK Help. Windows Installer Editor Reference 455 Chapter 21 Custom Action Reference This chapter includes the following topics: z About Custom Actions on page 457 z Call Custom DLL From Destination on page 457 z Call Custom DLL From Installation on page 458 z Call Custom DLL From Installed Files on page 459 z Call DLL From Installation on page 461 z Call Custom DLL From Installed Files on page 459 z Call JScript From Embedded Code on page 463 z Call JScript From Installation on page 463 z Call JScript From Installed Files on page 464 z Call JScript From Property on page 465 z Call VBScript From Embedded Code on page 466 z Call VBScript From Installation on page 466 z Call VBScript From Installed Files on page 467 z Call VBScript From Property on page 468 z Display Message on page 468 z Download File From Internet on page 469 z End Statement on page 470 z Execute Program From Destination on page 470 z Execute Program From Installation on page 471 z Execute Program From Installed Files on page 472 z Execute Program From Path on page 472 z If Statement on page 473 z Install MSI From Destination on page 473 z Install MSI From Installation on page 474 z Install MSI From Relative Path on page 475 z Launch Web Page on page 476 z Open Document From Installed Files on page 477 z Pause Installation on page 477 z Post Data to HTTP Server on page 477 z Remark on page 478 Windows Installer Editor Reference 456 Custom Action Reference z Run WiseScript From Destination on page 479 z Run WiseScript From Installation on page 479 z Run WiseScript From Installed Files on page 481 z Set Directory on page 482 z Set Feature State on page 482 z Set Property on page 483 z Terminate Installation on page 484 z Using the Custom Action Location Tab on page 484 z Using the Custom Action Location Tab for Merge Modules on page 485 z Using the Custom Action Properties Tab on page 486 z Using the Custom Action Description Tab on page 489 About Custom Actions While Windows Installer provides standard actions that perform most functionality you need in an installation, occasionally you might need additional functionality not available in standard actions. In that case, Windows Installer supports a variety of custom actions, which let you call code from other development environments, display a message, download a file from a Web site, open a Web page, post information over the Internet to your organization’s server, run another installation, set directories, set a feature state, set properties, and more. These custom actions let you add extensive functionality to an installation without having to write the code yourself. For technical details on custom actions, see Custom Actions in the Windows Installer SDK Help. For help using the MSI Script interface, see The MSI Script Window on page 437. Call Custom DLL From Destination This custom action calls a .DLL file that already resides on the destination computer. Tips z You can send a variable parameter list to the .DLL. z Because .DLLs are processor-specific, the .DLL that you call must target the same platform (32-bit, x64, or 64-bit Itanium) as the installation. In a mixed-target project file (.WSI), condition each Call Custom .DLL custom action for the appropriate platform. Example: Your .WSI contains a 32-bit release, an x64 release, and an Itanium release. You add three Call Custom .DLL actions to the project: one to call ABC32.dll, one to call ABCx64.dll, and one to call ABCItanium.dll. Place each custom action inside a condition block that checks for the appropriate platform. z The .DLL should be common to all Windows computers, such as user32.dll. Note Before being passed to Windows Installer, calls you make with Call Custom DLL actions are passed through a .DLL that facilitates the passing of parameters. Windows Installer Editor Reference 457 Custom Action Reference Usage Double-click the custom action and complete the Details tab: z DLL File Specify a .DLL file that exists on the destination computer to call during installation. Type the path to the .DLL as it will be on the destination computer, but use a Windows Installer directory property (enclosed in brackets) to specify the beginning of the path. You can use a predefined directory property, or a property representing a directory you created in this installation. To see directories defined in this installation, go to Setup Editor > Tables tab and click the Directories table. Example: This specifies a .DLL in the System32 directory: [SystemFolder]user32.dll z 64-bit Mark this if you are calling a 64-bit .DLL from a 64-bit installation. z Function Name Type the name of the function within the .DLL file to call. z Parameter List In the parameter list, specify the parameters to send to the .DLL. z Return Value Type Select the data type of the return value that is returned from the .DLL. z Returned Property Type or select a property name. The return value of the function call will be put into this property. In the Execute Immediate or User Interface sequences only, you can send Windows Installer properties to the .DLL function as parameters. See Configuring .DLL Parameter Settings on page 460. See also: Guidelines for Calling .DLLs on page 453 Guidelines for Custom Action Location on page 450 Using the Custom Action Properties Tab on page 486 Using the Custom Action Location Tab on page 484 Call Custom DLL From Installation This custom action stores a .DLL file in the Binary table of this installation file and calls it during installation. Use this to call a .DLL that does not reside on the destination computer. During installation, the .DLL is extracted to a temporary directory, is called, and is deleted. It is not registered. Tips z You can send a variable parameter list to the .DLL. z Because .DLLs are processor-specific, the .DLL that you call must target the same platform (32-bit, x64, or 64-bit Itanium) as the installation. In a mixed-target project file (.WSI), condition each Call Custom .DLL custom action for the appropriate platform. Example: Your .WSI contains a 32-bit release, an x64 release, and an Itanium release. You add three Call Custom .DLL actions to the project: one Windows Installer Editor Reference 458 Custom Action Reference to call ABC32.dll, one to call ABCx64.dll, and one to call ABCItanium.dll. Place each custom action inside a condition block that checks for the appropriate platform. z Manage the .DLL on the Resources page, which reflects the Binary table. Note Before being passed to Windows Installer, calls you make with Call Custom DLL actions are passed through a .DLL that facilitates the passing of parameters. Usage Double-click the custom action and complete the Details tab: z Custom Action Name Enter a unique name that begins with a letter or underscore. It can contain numbers and periods. It must not match the name of any Windows Installer standard action. See Standard Actions Reference in the Windows Installer SDK Help. z DLL File Specify a .DLL from your hard drive or local network to call during installation. z Function Name Type the name of the function within the .DLL file to call. z Parameter List In the parameter list, specify the parameters to send to the .DLL. z Return Value Type Select the data type of the return value that is returned from the .DLL. z Returned Property Type or select a property name. The return value of the function call will be put into this property. In the Execute Immediate or User Interface sequences only, you can send Windows Installer properties to the .DLL function as parameters. See Configuring .DLL Parameter Settings on page 460. See also: Guidelines for Calling .DLLs on page 453 Guidelines for Custom Action Location on page 450 Using the Custom Action Properties Tab on page 486 Using the Custom Action Location Tab on page 484 Call Custom DLL From Installed Files This custom action calls a .DLL file that is installed by this installation. Use this custom action to call the .DLL during installation, while leaving the .DLL on the destination computer as part of the installation. Tips z You can send a variable parameter list to the .DLL. z Because .DLLs are processor-specific, the .DLL that you call must target the same platform (32-bit, x64, or 64-bit Itanium) as the installation. In a mixed-target project file (.WSI), condition each Call Custom .DLL custom action for the Windows Installer Editor Reference 459 Custom Action Reference appropriate platform. Example: Your .WSI contains a 32-bit release, an x64 release, and an Itanium release. You add three Call Custom .DLL actions to the project: one to call ABC32.dll, one to call ABCx64.dll, and one to call ABCItanium.dll. Place each custom action inside a condition block that checks for the appropriate platform. z Before you add this custom action, add the file to be called to the Files page in Installation Expert. z Shaded areas of MSI Script indicate restricted placement for this custom action; because this custom action calls an installed file, it must run after files are installed. Note Before being passed to Windows Installer, calls you make with Call Custom DLL actions are passed through a .DLL that facilitates the passing of parameters. Usage Double-click the custom action and complete the Details tab: z Custom Action Name Enter a unique name that begins with a letter or underscore. It can contain numbers and periods. It must not match the name of any Windows Installer standard action. See Standard Actions Reference in the Windows Installer SDK Help. z DLL File Specify a .DLL file to call during installation. It must have already been added to this installation. z Function Name Type the name of the function within the .DLL file to call. z Parameter List In the parameter list, specify the parameters to send to the .DLL. z Return Value Type Select the data type of the return value that is returned from the .DLL. z Returned Property Type or select a property name. The return value of the function call will be put into this property. In the Execute Immediate or User Interface sequences only, you can send Windows Installer properties to the .DLL function as parameters. See Configuring .DLL Parameter Settings on page 460. See also: Guidelines for Calling .DLLs on page 453 Guidelines for Custom Action Location on page 450 Using the Custom Action Properties Tab on page 486 Using the Custom Action Location Tab on page 484 Configuring .DLL Parameter Settings When you add a Call Custom .DLL custom action, use the DLL Parameter Details dialog box to add parameters. Windows Installer Editor Reference 460 Custom Action Reference In the Execute Immediate or User Interface sequences only, you can send Windows Installer properties to the .DLL function as parameters. The property’s current value is passed to the function and, if the function changes that value, the property is updated back in the installation. To send a property, set Value Source to Property and type or select the property name in Property Name. To create a parameter: Double-click one of the Call Custom .DLL actions in MSI Script and click the Add button. Then complete the DLL Parameter Details dialog box: z Parameter Type This lists standard data types and two Windows Installer-specific items. Check the .DLL function for its required parameter data types. The option MsiHandle to Install gives you the handle hInstall, which is a handle to the running installation; the option MsiHandle to Database gives you the handle hDatabase, which is a handle to the running database. Some Windows Installer function calls and database calls require these handles as parameters. z Value Source A parameter’s value can be set from a Windows Installer property, a constant, or a constant with a NULL value. When you select a value source, the appropriate field below becomes enabled. z Property Name If you selected Property in Value Source, enter or select a Windows Installer property here to send as a parameter. This only works in the Execute Immediate or User Interface sequences. z Constant Value „ If you selected Constant in Value Source, enter a constant value. „ If you selected Constant with NULL value, the value of NULL is passed regardless of the parameter type, so Not applicable is displayed for the parameter type. „ If you selected Formatted Constant in Value Source, enter a formatted text string. This lets you pass the path of a file, feature, or directory to the custom action. Example: To pass a file path, enter [#filekey] as the constant value. See Formatted in the Windows Installer SDK Help. See also: Call Custom DLL From Destination on page 457 Call Custom DLL From Installation on page 458 Call Custom DLL From Installed Files on page 459 Call DLL From Installation This custom action stores a .DLL file in the Binary table of this installation file and calls it during installation. During installation, the .DLL is extracted to a temporary directory, is called, and is deleted. It is not registered. Tips z Manage the .DLL on the Resources page, which reflects the Binary table. Windows Installer Editor Reference 461 Custom Action Reference z You cannot send a variable parameter list to the .DLL. You can send only the handle to the installation, which means the .DLL must be written specifically for Windows Installer. To avoid these restrictions, use a “Call Custom DLL...” action instead. Usage Double-click the custom action and complete the Details tab: z Custom Action Name Enter a unique name that begins with a letter or underscore. It can contain numbers and periods. It must not match the name of any Windows Installer standard action. See Standard Actions Reference in the Windows Installer SDK Help. z DLL File Specify a .DLL from your hard drive or local network to call during installation. z Function Name Type the name of the function within the .DLL file to call. See also: Guidelines for Calling .DLLs on page 453 Guidelines for Custom Action Location on page 450 Using the Custom Action Properties Tab on page 486 Using the Custom Action Location Tab on page 484 Custom Action Type 1 in the Windows Installer SDK Help Call DLL From Installed Files This custom action calls a .DLL file that is installed by this installation. Use this if the .DLL should remain on the destination computer after installation. Tips z You cannot send a variable parameter list to the .DLL. You can send only the handle to the installation, which means the .DLL must be written specifically for Windows Installer. To avoid these restrictions, use a “Call Custom DLL...” action instead. z Before you add this custom action, add the file to be called to the Files page in Installation Expert. z Shaded areas of MSI Script indicate restricted placement for this custom action; because this custom action calls an installed file, it must run after files are installed. Usage Double-click the custom action and complete the Details tab: z Custom Action Name Enter a unique name that begins with a letter or underscore. It can contain numbers and periods. It must not match the name of any Windows Installer standard action. See Standard Actions Reference in the Windows Installer SDK Help. z DLL File Specify a .DLL file to call during installation. It must have already been added to this installation. Windows Installer Editor Reference 462 Custom Action Reference z Function Name Type the name of the function within the .DLL file to call. See also: Guidelines for Calling .DLLs on page 453 Guidelines for Custom Action Location on page 450 Using the Custom Action Properties Tab on page 486 Using the Custom Action Location Tab on page 484 Custom Action Type 17 in the Windows Installer SDK Help Call JScript From Embedded Code This custom action runs JScript code that is embedded inside this custom action. Tips z The script is limited to 255 characters; use other JScript custom actions for longer scripts. z The destination computer must contain the script’s runtime. Usage Double-click the custom action and complete the Details tab: z Custom Action Name Enter a unique name that begins with a letter or underscore. It can contain numbers and periods. It must not match the name of any Windows Installer standard action. See Standard Actions Reference in the Windows Installer SDK Help. z Run Script in Win64 Process (64-bit installations only.) Mark this if the script needs to access 64-bit functionality and run in a 64-bit process. z Enter the JScript to execute Type or paste the script text. Code elements, such as function names, declarations, and values, are color-coded. You can use bracketed property names, table keys, environment variable references, and other special substrings. See Formatted in the Windows Installer SDK Help. See also: Guidelines for Calling VBScripts and JScripts on page 452 Guidelines for Custom Action Location on page 450 Using the Custom Action Properties Tab on page 486 Using the Custom Action Location Tab on page 484 Custom Action Type 37 in the Windows Installer SDK Help Call JScript From Installation This custom action stores a JScript file in the Binary table of this installation file and runs it during installation. During installation, the JScript file is extracted to a temporary directory, is run, and is deleted. Windows Installer Editor Reference 463 Custom Action Reference Tips z Manage the file on the Resources page, which reflects the Binary table. z Use the script to read and write properties to the installation. z The destination computer must contain the script’s runtime. Usage Double-click the custom action and complete the Details tab: z Custom Action Name Enter a unique name that begins with a letter or underscore. It can contain numbers and periods. It must not match the name of any Windows Installer standard action. See Standard Actions Reference in the Windows Installer SDK Help. z Script File Specify a script file from your hard drive or local network to call during installation. z Script Function Call (Optional.) Type the name of the function within the script to call. z Run Script in Win64 Process (64-bit installations only.) Mark this if the script needs to access 64-bit functionality and run in a 64-bit process. See also: Guidelines for Calling VBScripts and JScripts on page 452 Guidelines for Custom Action Location on page 450 Using the Custom Action Properties Tab on page 486 Using the Custom Action Location Tab on page 484 Custom Action Type 5 in the Windows Installer SDK Help Call JScript From Installed Files This custom action runs code from a JScript file that is installed by this installation. Use this to call the script file during installation, while leaving the file on the destination computer as part of the installation. Tips z Before you add this custom action, add the file to be called to the Files page in Installation Expert. z Shaded areas of MSI Script indicate restricted placement for this custom action; because this custom action calls an installed file, it must run after files are installed. z Use the script to read and write properties to the installation. z The destination computer must contain the script’s runtime. Usage Double-click the custom action and complete the Details tab: z Custom Action Name Enter a unique name that begins with a letter or underscore. It can contain numbers and periods. It must not match the name of any Windows Installer standard action. Windows Installer Editor Reference 464 Custom Action Reference See Standard Actions Reference in the Windows Installer SDK Help. z Script File Specify a script file to call during installation. It must have already been added to this installation on the Files page. z Script Function Call (Optional.) Type the name of the function within the script to call. z Run Script in Win64 Process (64-bit installations only.) Mark this if the script needs to access 64-bit functionality and run in a 64-bit process. See also: Guidelines for Calling VBScripts and JScripts on page 452 Guidelines for Custom Action Location on page 450 Using the Custom Action Properties Tab on page 486 Using the Custom Action Location Tab on page 484 Custom Action Type 21 in the Windows Installer SDK Help Call JScript From Property This custom action runs JScript code that is stored inside a Windows Installer property. You might store the script in a property if part or all of the script needs to be generated dynamically based on end user input or system configuration. Tips z The script is limited to 32 Kb, which is the size limit for Windows Installer properties. z Use the script to read and write properties to the installation. z The destination computer must contain the script’s runtime. Usage Double-click the custom action and complete the Details tab: z Custom Action Name Enter a unique name that begins with a letter or underscore. It can contain numbers and periods. It must not match the name of any Windows Installer standard action. See Standard Actions Reference in the Windows Installer SDK Help. z Property Specify a property that stores the script, either by selecting a property or typing a new property name. Elsewhere in the installation, you must provide a mechanism for populating this property with the script text. z Script Function Call (Optional.) Type the name of the function within the script to call. z Run Script in Win64 Process (64-bit installations only.) Mark this if the script needs to access 64-bit functionality and run in a 64-bit process. See also: Guidelines for Calling VBScripts and JScripts on page 452 Windows Installer Editor Reference 465 Custom Action Reference Guidelines for Custom Action Location on page 450 Using the Custom Action Properties Tab on page 486 Using the Custom Action Location Tab on page 484 Custom Action Type 53 in the Windows Installer SDK Help Call VBScript From Embedded Code This custom action runs VBScript code that is embedded inside this custom action. Tips z The script is limited to 255 characters; use other VBScript custom actions for longer scripts. z The destination computer must contain the VBScript runtime. Usage Double-click the custom action and complete the Details tab: z Custom Action Name Enter a unique name that begins with a letter or underscore. It can contain numbers and periods. It must not match the name of any Windows Installer standard action. See Standard Actions Reference in the Windows Installer SDK Help. z Run Script in Win64 Process (64-bit installations only.) Mark this if the script needs to access 64-bit functionality and run in a 64-bit process. z Enter the VBScript to execute Type or paste the script text. Code elements, such as function names, declarations, and values, are color-coded. You can use bracketed property names, table keys, environment variable references, and other special substrings. See Formatted in the Windows Installer SDK Help. See also: Guidelines for Calling VBScripts and JScripts on page 452 Guidelines for Custom Action Location on page 450 Using the Custom Action Properties Tab on page 486 Using the Custom Action Location Tab on page 484 Custom Action Type 38 in the Windows Installer SDK Help Call VBScript From Installation This custom action stores a VBScript file in the Binary table of this installation file and runs it during installation. During installation, the VBScript file is extracted to a temporary directory, is run, and is deleted. Tips z Manage the file on the Resources page, which reflects the Binary table. z Use the script to read and write properties to the installation. z The destination computer must contain the script’s runtime. Windows Installer Editor Reference 466 Custom Action Reference Usage Double-click the custom action and complete the Details tab: z Custom Action Name Enter a unique name that begins with a letter or underscore. It can contain numbers and periods. It must not match the name of any Windows Installer standard action. See Standard Actions Reference in the Windows Installer SDK Help. z Script File Specify a script file from your hard drive or local network to call during installation. z Script Function Call (Optional.) Type the name of the function within the script to call. z Run Script in Win64 Process (64-bit installations only.) Mark this if the script needs to access 64-bit functionality and run in a 64-bit process. See also: Guidelines for Calling VBScripts and JScripts on page 452 Guidelines for Custom Action Location on page 450 Using the Custom Action Properties Tab on page 486 Using the Custom Action Location Tab on page 484 Custom Action Type 6 in the Windows Installer SDK Help Call VBScript From Installed Files This custom action runs code from a VBScript file that is installed by this installation. Use this to call the script file during installation, while leaving the file on the destination computer as part of the installation. Tips z Before you add this custom action, add the file to be called to the Files page in Installation Expert. z Shaded areas of MSI Script indicate restricted placement for this custom action; because this custom action calls an installed file, it must run after files are installed. z Use the script to read and write properties to the installation. z The destination computer must contain the script’s runtime. Usage Double-click the custom action and complete the Details tab: z Custom Action Name Enter a unique name that begins with a letter or underscore. It can contain numbers and periods. It must not match the name of any Windows Installer standard action. See Standard Actions Reference in the Windows Installer SDK Help. z Script File Specify a script file to call during installation. It must have already been added to this installation on the Files page. z Script Function Call (Optional.) Type the name of the function within the script to call. Windows Installer Editor Reference 467 Custom Action Reference See also: Guidelines for Calling VBScripts and JScripts on page 452 Guidelines for Custom Action Location on page 450 Using the Custom Action Properties Tab on page 486 Using the Custom Action Location Tab on page 484 Custom Action Type 22 in the Windows Installer SDK Help Call VBScript From Property This custom action runs VBScript code that is stored inside a Windows Installer property. You might store the script in a property if part or all of the VBScript needs to be generated dynamically based on end user input or system configuration. Tips z The script is limited to 32 Kb, which is the size limit for Windows Installer properties. z To use this option, you must also provide some mechanism for populating the property with the script text. z Use the script to read and write properties to the installation. z The destination computer must contain the script’s runtime. Usage Double-click the custom action and complete the Details tab: z Custom Action Name Enter a unique name that begins with a letter or underscore. It can contain numbers and periods. It must not match the name of any Windows Installer standard action. See Standard Actions Reference in the Windows Installer SDK Help. z Property Specify a property that stores the script, either by selecting a property or typing a new property name. Elsewhere in the installation, populate this property with the script text. z Script Function Call (Optional.) Type the name of the function within the script to call. z Run Script in Win64 Process (64-bit installations only.) Mark this if the script needs to access 64-bit functionality and run in a 64-bit process. See also: Guidelines for Calling VBScripts and JScripts on page 452 Guidelines for Custom Action Location on page 450 Using the Custom Action Properties Tab on page 486 Using the Custom Action Location Tab on page 484 Custom Action Type 54 in the Windows Installer SDK Help Display Message This custom action displays a message to the end user. You can also use it for debugging by displaying the value of properties while the installation runs. Windows Installer Editor Reference 468 Custom Action Reference Tips z If this custom action is within a condition, the message is displayed only when the specified condition is met. Example: You could display a message if end users marked a check box on a dialog box. You would associate the check box with a property and then set up a condition to check if the property was true. To create a condition, use an If Statement. See If Statement on page 473. z You can use formatted text strings, such as bracketed property names, in Message Title or Message Text. However, formatted text strings only work in the Execute Immediate or User Interface sequences. See Guidelines for Custom Action Location on page 450 and Formatted in the Windows Installer SDK Help. Usage Double-click the custom action and complete the dialog box: z Message Title Enter text to be displayed in the title bar of the message. z Message Text Enter the text to be displayed in the message dialog box. Press Ctrl+Enter to add line breaks in the displayed text. z Message Icon Select an appropriate icon for your message dialog box. See also: Remark on page 478 Guidelines for Custom Action Conditions on page 451 Download File From Internet This custom action downloads a file from the Internet. Tips z If you place this action in the User Interface or Execute Immediate sequences, you can use formatted text strings, such as [INSTALLDIR], in the Source URL and Destination Directory fields. See Formatted in the Windows Installer SDK Help. z If you place this action in the User Interface or Execute Immediate sequences, you cannot display progress bar text. z If you place this action in the Execute Deferred sequence, you must hard-code the destination and source paths. z Downloaded files are not uninstalled when the product is uninstalled because Windows Installer only uninstalls files installed with standard actions, not custom actions. Windows Installer Editor Reference 469 Custom Action Reference Usage Double-click the custom action and complete the dialog box: z Source URL Enter the URL of the file to download, including the name of the file. Example: http://www.site.com/readme.pdf. z Destination Directory Specify the file path, including file name, on the destination computer where the file should be downloaded. Example: [INSTALLDIR]readme.pdf. z Error Handling Determine how errors in the download operation are handled. z „ Ignore Errors The installation continues regardless of errors. „ Abort Installation The installation stops if the download operation cannot be completed. Progress Bar Text Enter the text to display in the progress bar during the download. Progress bar text appears only if this custom action is in the Execute Deferred sequence. You cannot enter properties or formatted text. The field length is limited to 64 characters and two lines. See also: Launch Web Page on page 476 Post Data to HTTP Server on page 477 Guidelines for Custom Action Location on page 450 End Statement The End Statement action marks the end of an If action, which specifies conditions to attach to an action or a set of actions. The End Statement action takes no parameters, and double-clicking it in the Actions list immediately inserts it into the script above the selected script line. See also: If Statement on page 473 Execute Program From Destination This custom action calls an .EXE file that already resides on the destination computer. Use it to call .EXE files that are common to all Windows computers, such as notepad.exe. Usage Double-click the custom action and complete the Details tab: z Custom Action Name Enter a unique name that begins with a letter or underscore. It can contain numbers and periods. It must not match the name of any Windows Installer standard action. See Standard Actions Reference in the Windows Installer SDK Help. Windows Installer Editor Reference 470 Custom Action Reference z Working Directory Using a non-bracketed Windows Installer directory property (Example: INSTALLDIR), specify the working directory of the .EXE file to call. When the .EXE file is run on the destination computer, its current working directory is set to the directory you specify here. This must be set to a directory that can be specified with a Windows Installer directory property, which are listed when you click Browse. z EXE and Command Line Using a bracketed Windows Installer directory property to specify location, enter the full path to the .EXE file that exists on the destination computer. Example: [INSTALLDIR]TextEditor\MyEditor.EXE. If the .EXE file is registered or is in the PATH environment variable, you might not need to type the entire path. Example: To specify Notepad, just type NOTEPAD.EXE, because it is in the PATH variable. (Optional) To pass command-line options to the .EXE file, enter them after the name of the .EXE file. The command-line options are executed in relation to the working directory. Example: If you type INSTALLDIR in Working Directory, and type NOTEPAD.EXE README.TXT in this field, the README.TXT file that is in INSTALLDIR is opened. See also: Guidelines for Custom Action Location on page 450 Using the Custom Action Properties Tab on page 486 Using the Custom Action Location Tab on page 484 Custom Action Type 34 in the Windows Installer SDK Help Execute Program From Installation This custom action stores an .EXE file in the Binary table of this installation file and calls it during installation. During installation, the .EXE is extracted to a temporary directory, is run, and is deleted. You can manage the file you specify from the Resources page, which reflects the Binary table. Usage Double-click the custom action and complete the Details tab: z Custom Action Name Enter a unique name that begins with a letter or underscore. It can contain numbers and periods. It must not match the name of any Windows Installer standard action. See Standard Actions Reference in the Windows Installer SDK Help. z Executable File Specify an .EXE file from your computer or local network. The .EXE file will be stored in the Binary table of the installation. z Command Line (Optional) Enter any command-line options to pass to the .EXE file. See also: Guidelines for Custom Action Location on page 450 Using the Custom Action Properties Tab on page 486 Using the Custom Action Location Tab on page 484 Custom Action Type 2 in the Windows Installer SDK Help Windows Installer Editor Reference 471 Custom Action Reference Execute Program From Installed Files This custom action calls an .EXE file that is installed by this installation. Tips z Before you add this custom action, add the file to be called to the Files page in Installation Expert. z Shaded areas of MSI Script indicate restricted placement for this custom action; because this custom action calls an installed file, it must run after files are installed. Usage Double-click the custom action and complete the Details tab: z Custom Action Name Enter a unique name that begins with a letter or underscore. It can contain numbers and periods. It must not match the name of any Windows Installer standard action. See Standard Actions Reference in the Windows Installer SDK Help. z Executable File Specify the .EXE file to run. It must have already been added to this installation. z Command Line (Optional) Enter command-line options to pass to the .EXE file. On the Properties tab, In-Script Options is unavailable for this custom action. See also: Guidelines for Custom Action Location on page 450 Using the Custom Action Properties Tab on page 486 Using the Custom Action Location Tab on page 484 Custom Action Type 18 in the Windows Installer SDK Help Execute Program From Path This custom action calls an .EXE file whose path is specified by the value of a property. It is useful if the path to the .EXE file is dependent on end user input or system configuration. To use this option, you must provide a mechanism for setting a property with the value of the .EXE path. Example: You could use the Set Property custom action and set a path based on the operating system. Or you could use the System Search page to set a property to the path of a found file. Usage Double-click the custom action and complete the Details tab: z Custom Action Name Enter a unique name that begins with a letter or underscore. It can contain numbers and periods. It must not match the name of any Windows Installer standard action. See Standard Actions Reference in the Windows Installer SDK Help. z Property Specify a property that will store the path and name of the .EXE. Select a property or type a new property name. Windows Installer Editor Reference 472 Custom Action Reference z Command Line (Optional) Enter command-line options to pass to the .EXE file. See also: Guidelines for Custom Action Location on page 450 Using the Custom Action Properties Tab on page 486 Using the Custom Action Location Tab on page 484 Custom Action Type 50 in the Windows Installer SDK Help If Statement Use If Statements to set conditions on actions. An If Statement marks the beginning of a If block, which is a conditional block of actions. The If block must be concluded by an End Statement. If the condition specified in the If Statement is true, the actions inside the If block are executed; if false, the actions are not executed. You can nest If Statements to create complex conditions. The condition you enter in the Condition field is subject to Windows Installer guidelines for creating conditions. See Conditional Statement Syntax in the Windows Installer SDK Help. To use the Condition Builder to create a syntactically correct Windows Installer condition, click Build. See Creating Conditions With Condition Builder on page 387. See also: Conditions on page 383 Using Conditions With Features on page 100 Install MSI From Destination This custom action runs a Windows Installer installation that is already advertised or installed on the destination computer (referred to as a nested installation). This is useful for reinstalling or uninstalling an application that was originally installed with an Install MSI custom action. Tips z The installation being called must already be advertised or installed on the destination computer. z You must know the product code of the installation to call. z This custom action is not available in an Administrative Installation. z The installation being called must be a Windows Installer installation. z On the Properties tab, In-Script Options is unavailable for this custom action and Processing only allows synchronous execution. z For best results, place this custom action in the Execute Immediate sequence after the InstallFinalize action. Windows Installer Editor Reference 473 Custom Action Reference Usage Double-click the custom action and complete the Details tab: z Custom Action Name Enter a unique name that begins with a letter or underscore. It can contain numbers and periods. It must not match the name of any Windows Installer standard action. See Standard Actions Reference in the Windows Installer SDK Help. z Product Code Either enter or copy and paste the product code of the nested installation. The product code is stored in a property named ProductCode. To find the product code of the nested .MSI, view its Product Code field on the Product Details page. z Property Settings Enter properties to set for the nested installation. You can set Windows Installer properties or private properties. Example: To set the main installation directory for the nested installation to be the same as for the current installation: INSTALLDIR="[INSTALLDIR]" If the directory represented by the property might contain spaces, as is typical with the installation directory, enclose the property in quotes as shown above. To set the nested installation to be advertised, enter: ADVERTISE=ALL To uninstall the nested installation, enter: REMOVE=ALL For a list of properties, see Property Reference in the Windows Installer SDK Help. See also: Guidelines for Nested Installation Custom Actions on page 451 Guidelines for Custom Action Location on page 450 Using the Custom Action Properties Tab on page 486 Using the Custom Action Location Tab on page 484 Custom Action Type 39 in the Windows Installer SDK Help Nested Installation Actions in the Windows Installer SDK Help Install MSI From Installation This custom action stores an .MSI in the Binary table of this installation and runs it during installation (referred to as a nested installation). This is useful for deploying a second application from within the main installation. Tips z Manage the .MSI on the Resources page, which reflects the Binary table. z This custom action is not available in an Administrative Installation. z The installation being called must be a Windows Installer installation. z On the Properties tab, In-Script Options is unavailable for this custom action and Processing only allows synchronous execution. z For best results, place this custom action in the Execute Immediate sequence after the InstallFinalize action. Windows Installer Editor Reference 474 Custom Action Reference Usage Double-click the custom action and complete the Details tab: Custom Action Name Enter a unique name that begins with a letter or underscore. It can contain numbers and periods. It must not match the name of any Windows Installer standard action. See Standard Actions Reference in the Windows Installer SDK Help. z Installation to Run Specify the .MSI to run from your computer or local network. The installation must be in .MSI format, and must not include external compressed or uncompressed files. z Property Settings Enter properties to set for the nested installation. You can set Windows Installer properties or private properties. Example: To set the main installation directory for the nested installation to be the same as for the current installation: INSTALLDIR="[INSTALLDIR]" If the directory represented by the property might contain spaces, as is typical with the installation directory, enclose the property in quotes as shown above. To set the nested installation to be advertised, enter: ADVERTISE=ALL To uninstall the nested installation, enter: REMOVE=ALL For a list of properties, see Property Reference in the Windows Installer SDK Help. See also: Guidelines for Nested Installation Custom Actions on page 451 Guidelines for Custom Action Location on page 450 Using the Custom Action Properties Tab on page 486 Using the Custom Action Location Tab on page 484 Custom Action Type 7 in the Windows Installer SDK Help Nested Installation Actions in the Windows Installer SDK Help Install MSI From Relative Path This custom action runs an .MSI from the main installation (referred to as a nested installation). This is useful to deploy or uninstall a second application from within this installation. This custom action assumes that both the main installation file and the nested installation file are stored on the same installation media. Example: You could place the main and nested installations on a CD. The path to the nested installation must be specified using a relative path from the main installation. Tips z This custom action is not available in an Administrative Installation. z The installation being called must be a Windows Installer installation. z On the Properties tab, In-Script Options is unavailable for this custom action and Processing only allows synchronous execution. Windows Installer Editor Reference 475 Custom Action Reference z For best results, place this custom action in the Execute Immediate sequence after the InstallFinalize action. Usage Double-click the custom action and complete the Details tab: z Custom Action Name Enter a unique name that begins with a letter or underscore. It can contain numbers and periods. It must not match the name of any Windows Installer standard action. See Standard Actions Reference in the Windows Installer SDK Help. z Installation to Run Enter the relative path of the .MSI to run. Example: If this installation is located at the top level of a CD (F:\), and the nested installation is at F:\SubInstall\second.msi, enter the following: SubInstall\second.msi z Property Settings Enter properties to set for the nested installation. You can set Windows Installer properties or private properties. Example: To set the main installation directory for the nested installation to be the same as for the current installation: INSTALLDIR="[INSTALLDIR]" If the directory represented by the property might contain spaces, as is typical with the installation directory, enclose the property in quotes as shown above. To set the nested installation to be advertised, enter: ADVERTISE=ALL To uninstall the nested installation, enter: REMOVE=ALL For a list of properties, see Property Reference in the Windows Installer SDK Help. See also: Guidelines for Nested Installation Custom Actions on page 451 Guidelines for Custom Action Location on page 450 Using the Custom Action Properties Tab on page 486 Using the Custom Action Location Tab on page 484 Custom Action Type 23 in the Windows Installer SDK Help Nested Installation Actions in the Windows Installer SDK Help Launch Web Page This custom action displays a Web page during installation using the end user’s default browser. In Web Page URL on the Launch Web Page dialog box, designate the URL to open during installation. The URL must be complete. Example: http://www.symantec.com. See also: Download File From Internet on page 469 Post Data to HTTP Server on page 477 Windows Installer Editor Reference 476 Custom Action Reference Guidelines for Custom Action Location on page 450 Open Document From Installed Files This custom action opens a document installed by the installation. On the Open Document From Installed Files dialog box, specify the name of the file to open from this installation. Tips z Before you add this custom action, add the file to be called to the Files page in Installation Expert. z Shaded areas of MSI Script indicate restricted placement for this custom action; because this custom action calls an installed file, it must run after files are installed. See also: Guidelines for Custom Action Location on page 450 Pause Installation This custom action temporarily stops a sequence from executing. After the specified number of seconds, the sequence continues running. This action must be placed in the Execute Deferred sequence. Usage Double-click the custom action and complete the dialog box: z Seconds to Pause Number of seconds for the sequence to pause. z Progress Bar Text Text to display in the progress bar during the pause. You cannot enter properties or other formatted text. The field length is limited to 64 characters and two lines. See also: Guidelines for Custom Action Location on page 450 Post Data to HTTP Server This custom action posts information over the Internet to a Web server. Example: Use it to record user registration information or other data. Tips z You must have an ASP or CGI program set up to accept data from HTTP POST operations. z The computer running the installation must have a valid Internet connection (such as dial-up networking). z If you place this action in the User Interface or Execute Immediate sequences, you can use formatted text strings, such as [PROPERTY], in the Destination URL and Text to Post fields. However, because of Windows Installer limitations, if you place Windows Installer Editor Reference 477 Custom Action Reference it in the Execute Deferred sequence, you must hard-code the destination and source paths. See Guidelines for Custom Action Location on page 450 and Formatted in the Windows Installer SDK Help. z Because of Windows Installer limitations, to display progress bar text to the user, you must place the action in the Execute Deferred sequence. z To give end users control over whether to post data to your HTTP server, put this custom action in a conditional block. Set the conditional block so that it only posts data if the end user has agreed to this posting. Example: Add a check box the user marks to accept posting of data. Associate the check box with a property and set up the conditional block to run if the property is true. To create a condition, use an If Statement. See If Statement on page 473. Usage Double-click the custom action and complete the dialog box: z Destination URL The URL of the CGI program or ASP page that will accept the posted data. z Text to Post The text to post should be one or more lines in the format field=data, where field is the name of the field expected by the Web application, and data is the data to populate the field. If a line does not appear to contain a field name followed by =, it is assumed to be a continuation of the previous line, and the data on the two lines is concatenated and sent with a single field identifier. For information on using formatted text, see the tips above . z Error Handling Determines how errors in the posting operation are handled. z „ Ignore Errors The script continues regardless of any errors. „ Abort Installation The installation stops if the posting operation cannot be completed. Progress Bar Text Enter text to display in the progress bar while data is posted to the server. This action must be placed in the Execute Deferred sequence for progress bar text to work. See also: Download File From Internet on page 469 Launch Web Page on page 476 Guidelines for Custom Action Conditions on page 451 Remark The Remark action lets you put comments in sequences to document what is happening in the script. In Remark, type the comment. To place a blank line in the sequence, add a Remark action, but leave Remark blank. Windows Installer Editor Reference 478 Custom Action Reference Run WiseScript From Destination This custom action runs a WiseScript .EXE that already resides on the destination computer. If you use both WiseScript and Windows Installer technology, you can integrate them with this custom action. Use this to leverage past WiseScripts or to gain access to unique WiseScript technology. Tips z In the WiseScript, use special script actions—Get Windows Installer Property, Set Windows Installer Property, and Evaluate Windows Installer Condition—to communicate between the Windows Installer installation and the WiseScript. For details, see the WiseScript documentation. z If the WiseScript being called uses a Set Windows Installer Property action, place this custom action in the User Interface or Execute Immediate sequence. Usage Double-click the custom action and complete the Details tab: z Custom Action Name Enter a unique name that begins with a letter or underscore. It can contain numbers and periods. It must not match the name of any Windows Installer standard action. See Standard Actions Reference in the Windows Installer SDK Help. z WiseScript .EXE File Specify an executable file on the destination computer that was compiled in a WiseScript editing tool. You must type a path to the file using a predefined directory name, such as [CommonFilesFolder], to specify the location on the destination computer. A trailing slash after a predefined directory name is not necessary. Example: [INSTALLDIR]Directory\Setup.exe. z Options button This is unavailable for this custom action. z Command Line (Optional) Enter the command-line options to send to the .EXE. Example: Enter /s to make the WiseScript run silently. For a list of valid command-line options, see the WiseScript documentation. See also: Examples of WiseScripts You Run From an .MSI on page 444 Calling WiseScripts with Custom Actions on page 443 Guidelines for Custom Action Location on page 450 Using the Custom Action Properties Tab on page 486 Using the Custom Action Location Tab on page 484 Troubleshooting: When WiseScript Custom Actions Fail on Windows Vista on page 448 Run WiseScript From Installation This custom action stores a WiseScript .EXE in the Binary table of this installation file and runs it during installation. Windows Installer Editor Reference 479 Custom Action Reference If you use both WiseScript and Windows Installer technology, you can integrate them with this custom action. Use this to leverage past WiseScripts or to gain access to unique WiseScript technology. Tips z In the WiseScript, use special script actions—Get Windows Installer Property, Set Windows Installer Property, and Evaluate Windows Installer Condition—to communicate between the Windows Installer installation and the WiseScript. For details, see the WiseScript documentation. z If the WiseScript being called uses a Set Windows Installer Property action, place this custom action in the User Interface or Execute Immediate sequence. z Manage the file you specify on the Resources page, which reflects the Binary table. Usage Double-click the custom action and complete the Details tab: z Custom Action Name Enter a unique name that begins with a letter or underscore. It can contain numbers and periods. It must not match the name of any Windows Installer standard action. See Standard Actions Reference in the Windows Installer SDK Help. z WiseScript .EXE File Specify an executable file on your computer or network that was compiled in a WiseScript editing tool. The file you select will be copied into the Binary table of this installation. Optionally, you can use the Options button below. z Options button z „ Browse for WiseScript Select a WiseScript .EXE file on your hard drive or network and place its path in the WiseScript .EXE File field. „ Create New WiseScript Open a new WiseScript in WiseScript Editor. „ Edit Existing WiseScript If you specified a WiseScript .EXE in WiseScript .EXE File, and that .EXE has a corresponding .WSE file with the same name in the same folder as the .EXE, this option opens that .WSE file in WiseScript Editor. This option is unavailable if WiseScript .EXE File is empty or if a corresponding .WSE file does not exist. Command Line (Optional) Enter the command-line options to send to the .EXE. Example: Enter /s to make the WiseScript run silently. For a list of valid command-line options, see the WiseScript documentation. See also: Examples of WiseScripts You Run From an .MSI on page 444 Calling WiseScripts with Custom Actions on page 443 Guidelines for Custom Action Location on page 450 Using the Custom Action Properties Tab on page 486 Using the Custom Action Location Tab on page 484 Troubleshooting: When WiseScript Custom Actions Fail on Windows Vista on page 448 Windows Installer Editor Reference 480 Custom Action Reference Run WiseScript From Installed Files This custom action runs a WiseScript .EXE that is installed by this installation. If you use both WiseScript and Windows Installer technology, you can integrate them with this custom action. Use this to leverage past WiseScripts or to gain access to unique WiseScript technology. Tips z In the WiseScript, use special script actions—Get Windows Installer Property, Set Windows Installer Property, and Evaluate Windows Installer Condition—to communicate between the Windows Installer installation and the WiseScript. For details, see the WiseScript documentation. z If the WiseScript being called uses a Set Windows Installer Property action, place this custom action in the User Interface or Execute Immediate sequence. z Before you add this custom action, add the file to be called to the Files page in Installation Expert. z Shaded areas of MSI Script indicate restricted placement for this custom action; because this custom action calls an installed file, it must run after files are installed. Usage Double-click the custom action and complete the Details tab: z Custom Action Name Enter a unique name that begins with a letter or underscore. It can contain numbers and periods. It must not match the name of any Windows Installer standard action. See Standard Actions Reference in the Windows Installer SDK Help. z WiseScript .EXE File Specify an executable file contained in this installation that was compiled in a WiseScript Editing tool. Optionally, you can use the Options button below. z Options button z „ Browse for WiseScript Select a WiseScript .EXE file on your hard drive or network and place its path in the WiseScript .EXE File field. „ Create New WiseScript Open a new WiseScript in WiseScript Editor. „ Edit Existing WiseScript If you specified a WiseScript .EXE in the WiseScript .EXE File field, and that .EXE has a corresponding .WSE file with the same name in the same folder as the .EXE, this option opens that .WSE file in WiseScript Editor. This option is unavailable if the WiseScript .EXE File field is empty or if a corresponding .WSE file does not exist for the specified .EXE file. Command Line (Optional) Enter the command-line options to send to the .EXE. Example: Enter /s to make the WiseScript run silently. For a list of valid command-line options, see the WiseScript documentation. See also: Windows Installer Editor Reference 481 Custom Action Reference Examples of WiseScripts You Run From an .MSI on page 444 Calling WiseScripts with Custom Actions on page 443 Guidelines for Custom Action Location on page 450 Using the Custom Action Properties Tab on page 486 Using the Custom Action Location Tab on page 484 Troubleshooting: When WiseScript Custom Actions Fail on Windows Vista on page 448 Set Directory This custom action sets a new value for a directory property. Example: Set a new value for a directory based on end user input during installation. Tips z For best results, place this action in the User Interface or Execute Immediate sequence. z On the Properties tab, the In-Script Options and Processing drop-down lists are unavailable for this custom action. Usage Double-click the custom action and complete the Details tab: z Custom Action Name Enter a unique name that begins with a letter or underscore. It can contain numbers and periods. It must not match the name of any Windows Installer standard action. See Standard Actions Reference in the Windows Installer SDK Help. z Directory Specify the directory to change the value of. It must be a directory you added to this installation or a predefined Windows system directory, which appears when you browse. Do not enclose the directory property with brackets. z Directory Value Enter the new path of the directory. You can use property and directory names by enclosing them in brackets. Example: To indicate a directory named Data in the installation directory, enter: [INSTALLDIR]Data See also: Guidelines for Custom Action Location on page 450 Using the Custom Action Properties Tab on page 486 Using the Custom Action Location Tab on page 484 Custom Action Type 35 in the Windows Installer SDK Help Set Feature State This custom action sets the installation state of a feature at run time. The installation state determines how or whether a feature is installed. Example: Use this custom action to omit features during upgrade of limited versions of the product. On the Set Feature State dialog box, select the feature from Feature, then mark an installation state option for that feature. Windows Installer Editor Reference 482 Custom Action Reference Tips z This custom action has restrictions on its placement, indicated by shaded areas in the Installation Sequence. z If you set a feature to run from source and the files are compressed, Windows Installer sets the feature to run from the local drive. z For information on how Windows Installer sets feature states when features share components, see MsiSetFeatureState in the Windows Installer SDK Help. See also: Configuring a Feature Using Its Drop-Down List on page 95 Configuring a Feature Using the Feature Details Dialog on page 96 Guidelines for Custom Action Location on page 450 Set Property This custom action sets a Windows Installer property. This custom action is useful for setting a property based on end user input or on system configuration. Tips z For best results, place this action in the User Interface or Execute Immediate sequence. z On the Properties tab, the In-Script Options and Processing drop-down lists are unavailable for this custom action. Usage Double-click the custom action and complete the Details tab: z Custom Action Name Enter a unique name that begins with a letter or underscore. It can contain numbers and periods. It must not match the name of any Windows Installer standard action. See Standard Actions Reference in the Windows Installer SDK Help. z Property Select a property from the list, or enter a new property name. Do not enclose this property name with brackets. z Property Value Enter the value to set the property to. Because this value is of the data type Formatted, you can use property and directory names by enclosing them in brackets. For information on formatted text strings, see Formatted in the Windows Installer SDK Help. See also: Guidelines for Custom Action Location on page 450 Using the Custom Action Properties Tab on page 486 Using the Custom Action Location Tab on page 484 Custom Action Type 51 in the Windows Installer SDK Help Windows Installer Editor Reference 483 Custom Action Reference Terminate Installation This custom action terminates the installation and displays a message explaining the termination. Typically, you would place this custom action within a conditional block, which begins with an If Statement. See If Statement on page 473. Tips z This custom action has restrictions on its placement, indicated by shaded areas in the Installation Sequence. z The Properties tab is unavailable for this custom action. Usage Double-click the custom action and complete the Details tab: z Custom Action Name Enter a unique name that begins with a letter or underscore. It can contain numbers and periods. It must not match the name of any Windows Installer standard action. See Standard Actions Reference in the Windows Installer SDK Help. z Termination Message Enter a message to explain to the end user why the installation terminated. Use plain text, formatted text strings, or enter an integer that is indexed to an entry in the error table. See also: Formatted in the Windows Installer SDK Help Guidelines for Custom Action Location on page 450 Custom Action Type 19 in the Windows Installer SDK Help Using the Custom Action Location Tab The Location tab appears for custom actions only if you are working in the All Custom Actions installation mode. The All Custom Actions installation mode lists all the custom actions that are part of this installation, which are stored in the CustomAction table. Note The Location tab is an alternate way to perform tasks that you normally perform in the User Interface, Execute Immediate, or Execute Deferred sequences. You can move and copy custom actions by using editing functions in these sequences. The main use for this tab is to click the No Sequence option, which causes this action to not run unless an event invokes it. z No Sequence Omits the custom action from all sequences, and stores it in the CustomAction table. If you mark this, the custom action is only invoked if you set an event to run the custom action. See Launching a Custom Action from a Dialog on page 454. If you clear No Sequence, enter the following information: Windows Installer Editor Reference 484 Custom Action Reference z Sequence Select a sequence to which to add this custom action. The options here correspond to the sequences available with each of the three installation modes. z Location list box This displays all the custom actions that are part of this installation. Click on an action in the list box and click one of the following buttons: z „ Click Add to add the custom action to the sequence below the action you selected. „ Click Remove to remove it from the sequence. „ Click Move Up and Move Down to specify where in the sequence the custom action is stored. Condition For this action to run only if a certain condition is true, enter a condition. In the User Interface, Execute Immediate, and Execute Deferred sequences, the condition you enter is displayed as an If Statement preceding the custom action. To use the Condition Builder to create a syntactically correct Windows Installer condition, click Build. See Creating Conditions With Condition Builder on page 387. See also: All Custom Actions on page 438 Using the Custom Action Location Tab for Merge Modules The merge module version of the Location tab only appears for custom actions if you are working in a merge module (.WSM or .MSM file). It is a different version of the Location tab than the one that displays in a standard installation (.WSI or .MSI file). Use this tab to set the location for a custom action in a merge module. Note When you add a custom action to a merge module, you’ll notice that the Custom Action Name field automatically contains the GUID of the merge module. You should leave the GUID as part of the custom action name to ensure adherence to Windows Installer guidelines for naming custom actions in merge modules. Because a merge module is merged into a standard installation, you must specify where the custom action should be merged into the action sequence of the standard installation. To specify where this custom action is merged into the main action sequence, set the following options: z No Sequence Clear this to add this action to an action sequence. If the action is not in an action sequence, it is never executed. If you clear the No Sequence, enter the following information: Windows Installer Editor Reference 485 Custom Action Reference z Sequence Select a sequence to which to add this custom action. The options here correspond to the sequences available with each of the three installation modes of a standard installation (.WSI or .MSI file). z Reference Action This drop-down list contains all the standard Windows Installer actions from the sequence that you selected in the Sequence drop-down list. This custom action, when merged into a standard installation, will be placed relative to the action you select in this list. z Sequence Number If the reference action you select above is not found, this custom action will be placed using this sequence number. In most cases, you can ignore this field. You can view sequence numbers for a particular sequence by viewing the sequence in the Tables tab in Setup Editor. In the Placement section, mark an option to specify where to place this action: z „ Before Action Click this option to place this action before the Reference Action you selected above. „ After Action Click this option to place this action after the Reference Action you selected above. Condition If you want this action to run only if a certain condition is true, enter a condition. In the User Interface, Execute Immediate, and Execute Deferred sequences, the condition you enter is displayed as an If Statement preceding the custom action. To use the Condition Builder to create a syntactically correct Windows Installer condition, click Build. See Creating Conditions With Condition Builder on page 387. See also: All Custom Actions on page 438 Using the Custom Action Properties Tab The Properties tab appears on the details dialog box for most custom actions. However, sometimes options are unavailable or display different choices based on what kind of custom action you added and where you added it. In this dialog box, you set options that determine when and how the custom action is run. In-Script Options This determines when the custom action is executed. When Windows Installer runs the installation, it first reads the action sequences and creates its own internal installation script to follow, then later it executes that script. You can have the custom action executed immediately when Windows Installer first encounters it, or later during execution of the internal script. See Custom Action In-Script Execution Options in the Windows Installer SDK Help. Windows Installer Editor Reference 486 Custom Action Reference Note The In-Script Options drop-down list is unavailable if this custom action is located in the User Interface or Execute Immediate sequences because both these sequences already run in immediate execution mode, making this drop-down list redundant. It is unavailable for Set Property and Set Directory because they must be run in immediate execution mode in order to work. z Immediate Execution If you place an action in the User Interface or Execute Immediate sequence, this is set to Immediate Execution and is unavailable, because those two sequences always run in immediate execution. This action will be executed during the first pass that Windows Installer makes through the installation database, before the internal script is generated and executed. Actions in immediate execution mode can change properties; actions in any type of deferred mode cannot. Actions in immediate execution mode always run under User Context, which means that they run with the same privilege level as the currently logged-in user. If the custom action needs to be run under a higher privilege level, place it in the Execute Deferred sequence and set this field to Deferred Execution - System Context. Note The following four options all apply to deferred custom actions, and are available only if the custom action is placed in the Execute Deferred sequence. Otherwise the drop-down list is unavailable. z Deferred Execution - User Context Select this if the action should be executed later during installation, during the time when all other system changes are performed by Windows Installer. This runs under user context, so if the current user doesn't have elevated privileges, and the action needs elevated privileges to succeed, it might fail. Use this option if the custom action depends on a file that is installed with the installation. Custom actions that change the system directly should be run in Deferred Execution. Deferred custom actions cannot change properties in the Property table. See Deferred Execution Custom Actions in the Windows Installer SDK Help. z Rollback only Select this if the action should be executed later, during installation of the rollback script, which is invoked if the end user cancels the installation or if the installation is unsuccessful. Use rollback actions to undo previous custom actions that made changes to the system. Rollback actions run in deferred execution mode and cannot run asynchronously. See Rollback Custom Actions in the Windows Installer SDK Help. z Commit only Select this if the action should be executed later, during installation of the commit script, which is invoked upon successful completion of the installation script. Commit actions run in deferred execution mode. See Commit Custom Actions in the Windows Installer SDK Help. z Deferred Execution - System Context If execution of the custom action requires elevated privileges, set this option. You must also set AlwaysInstallElevated keys in the registry. See AlwaysInstallElevated in the Windows Installer SDK Help. This makes the custom action run as though it were logged on as a system account, similar to the way services can log on as a system account. Windows Installer Editor Reference 487 Custom Action Reference Note User context and system context are relevant only on locked-down computers. Actions run in system context are run with elevated privileges by the Windows Installer service. Actions run in user context are run with the current user’s privileges. Processing The main installation thread can control the custom action thread in different ways. Options in this drop-down list determine how the custom action thread is controlled. See Custom Action Return Processing Options and Synchronous and Asynchronous Custom Actions in the Windows Installer SDK Help. The Processing options are not available if the custom action type is Set Property or Set Directory and are limited to synchronous for Install MSI custom actions. z Synchronous Run the custom action synchronously to the main installation thread. Windows Installer waits for the custom action to complete before continuing the main installation. The exit code of the custom action must be 0 to indicate success. Use this method for Windows Installer to wait for the success of the action before continuing. z Synchronous, Ignore exit code Run the custom action synchronously to the main installation thread. Windows Installer waits for the custom action to complete before continuing the main installation. Use this option if success of the action is unnecessary to continue with the installation. The exit code of the custom action is ignored. z Asynch, Wait at end of sequence Run the custom action asynchronously to the main installation thread. Windows Installer runs the custom action simultaneously with the main installation. At the end of the script, Windows Installer waits for the exit code from the custom action before continuing. Use this if the installation is not dependent on completion of this action, but you want to check the exit code. This option is not available for Install MSI custom actions or if you selected Rollback Only in the In-Script Options list above. z Asynch, No wait Run the custom action asynchronously to the main installation thread. This means that Windows Installer runs the custom action simultaneously with the main installation. Windows Installer does not wait for completion of the custom action and does not check the exit code. This option is not supported for Install MSI custom actions. This option is not supported for Install MSI custom actions or if you selected Rollback Only in the In-Script Options list above. Scheduling Options If you add the custom action to both the UI Sequence and the Execute Sequence, but you want to limit the number of times it actually runs, select an option here. See Custom Action Execution Scheduling Options in the Windows Installer SDK Help. z Always Execute Select this to have the action execute in all sequences that you added it to. z Run first time Select this to have the custom action execute only the first time Windows Installer encounters it. Windows Installer Editor Reference 488 Custom Action Reference z Run once per process Select this option to prevent the custom action from running twice if the custom action modifies property or database data. Use for custom actions in either Execute sequence that should not run if the installation is running in silent mode. z Run only if UI sequence was run Select this option if the custom action should run only if either Execute sequence is run following User Interface sequence. Progress Bar Text Enter the text to display with the progress bar while the action runs. The action must be placed in the Execute Deferred sequence for the text to be displayed. You cannot enter properties or other formatted text; see Formatted in the Windows Installer SDK Help. The field length is limited to 64 characters and two lines. Using the Custom Action Description Tab The Description tab appears on the details dialog box for all custom actions. The Windows Vista Logo Program requires you to document every custom action in an installation. The Windows Vista Compatibility Checks validation module in Package Validation includes a check for custom action descriptions. If you plan to certify an installation for Windows Vista, use the Description tab to document custom actions. This requirement applies to the Wise custom actions as well as the ones you add. For information you can use to document Wise custom actions, see Wise Custom Actions on page 498. To obtain a report of each custom action and its description, select Reports menu > Custom Actions. Windows Installer Editor Reference 489 Chapter 22 Windows Installer and .NET Technologies This chapter includes the following topics: z About Microsoft Windows Installer on page 490 z About Microsoft .NET Technology on page 493 About Microsoft Windows Installer Wise products integrate closely with Microsoft Windows technologies. The installations you create are in Microsoft Windows Installer format and are run on the destination computer by the Windows Installer engine. Windows Installer Editor is an authoring environment for the Microsoft Windows Installer service. Although a comprehensive discussion of Windows Installer is not possible here, it is important that you understand some basic concepts about Windows Installer and how Windows Installer Editor supports it. To create a streamlined process for installing and managing applications, Microsoft developed the Windows Installer service. It consists of a set of guidelines, an Application Programming Interface, and a run-time service to help make application installation and ongoing management part of the basic Windows system services. The Windows Installer service is not an installation-authoring tool, but rather an installation engine and rule set for installation packages. The Windows Installer engine resides on the destination computer, reads the installation database (.MSI), and performs the installation and any subsequent management, such as self-repair. Instead of an installation executable (such as setup.exe), your installation is in the form of a database file (.MSI), which contains instructions and can also enclose installation files. Because this database uses highly structured, uniform data tables, there is 100% accountability of where each file is installed and a thorough log of which files belong to which applications. As a result, individual files can readily be restored to repair damaged applications. Each table is dedicated to a particular type of installation information such as Class, Components, Features, Files, Execution Sequence, and Registry. Certain logic is built in to the Windows Installer engine, such as when to prompt for a restart, disk space checking, and file version replacement rules. When an .MSI is opened, msiexec.exe reads the data stored in the database and builds an internal script to follow. It then performs the actions in the script to complete the installation. Microsoft Windows Installer has its own help system, which contains detailed information on every aspect of Windows Installer. Access the Windows Installer SDK Help by selecting Help menu > Windows Installer SDK Help. Windows Installer Editor Reference 490 Windows Installer and .NET Technologies Frequently Asked Questions About Microsoft Windows Installer How is Windows Installer different from Windows Installer Editor? Microsoft Windows Installer is a Microsoft technology for writing, managing, and installing applications. The Microsoft Windows Installer service, which resides permanently on the destination computer as part of the operating system, includes a Windows Installer executable named msiexec.exe. The executable runs installation files, called Windows Installer database files (.MSI files), that are written especially for Windows Installer. Windows Installer Editor is an installation authoring application for creating and editing Windows Installer database files. When you build an installation in Windows Installer Editor, you populate tables within a Windows Installer database file. The Windows Installer Editor user interface exposes the functionality offered by Windows Installer. How are files stored on the destination computer? When an application is installed on the destination computer, Windows Installer stores copies of .MSI files in a hidden directory named Installer, which is in the Windows or Winnt directory. These copies are used if the end user tries to remove, repair, or reinstall the application from the Add/Remove Programs dialog box. However, these .MSI files do not necessarily store application files, so if the end user tries a repair or reinstall, Windows Installer might prompt the end user for the original installation source (shared network directory or CD). If you output an.MSI file compressed in an .EXE file, Windows Installer uncompresses a copy of the .MSI into \Program Files\Common Files\Wise Installation Wizard\ on the destination computer. These .MSI files do not have to be left on the destination computer, but if they are, the end user does not need the source media to repair or reinstall an installation. What if your end users don’t have Windows Installer? Because the Windows Installer runtime might not be installed on some computers, Windows Installer Editor lets you create an .EXE file that installs the Windows Installer runtime before beginning the application installation. See Setting Build Options for a Release on page 190 and Adding Prerequisites to a Release on page 195. What is advertisement? Advertisement is a way to deploy applications in large organizations. It is available with Windows Installer, but only for supported platforms. (See Platform Support of Advertisement in the Windows Installer SDK Help.) During installation development, you can set features or entire applications to be advertised. End users invoke advertised items by running a shortcut, opening a file with an advertised file extension, or by accessing any other entry point. If a feature or application is advertised, only the entry points to the feature or application are installed. Example: If the application Microsoft Word is advertised to destination computers, the end users still see the Microsoft Word icons in their Start menu and Desktop, and the file extension .doc is registered, but none of the files that make up Microsoft Word are actually installed. Windows Installer Editor Reference 491 Windows Installer and .NET Technologies How does Windows Installer Editor support advertisement? In Windows Installer Editor, you can set default advertisement on a per-feature basis on the Feature Details dialog box. If you advertise features, however, you must include Windows Installer function calls within the application to perform a feature-level installation of the necessary files when an advertised entry point is invoked. For information on coding an application for advertisement, see Advertisement in the Windows Installer SDK Help. Microsoft Windows Installer provides command lines for advertising an entire application. See Command Line Options in the Windows Installer SDK Help. How do I use advanced features? Most advanced Windows Installer features require you to use Windows Installer function calls in an application. Other features require specific operating systems, such as Windows 2000 or Windows 2000 Server. Example: You could add a menu option for a spell checker, but design the installation so that the files necessary for the spell checker are not installed by default. When the end user selects the spell checker menu option, your code can use Windows Installer functions to install the necessary files on demand. While Windows Installer Editor can help you bundle an application into an installation package, it cannot help you design, develop, and code an application to use Microsoft Windows Installer APIs. Use the Windows Installer Software Development Kit (SDK) online help, which is installed with Windows Installer Editor, as a reference for coding Windows Installer functionality into an application. See also: About Microsoft Windows Installer on page 490 Working With Components and Features In Microsoft Windows Installer terminology, a feature is a distinct part of an application’s functionality, which end users can usually choose to install. (Example: A feature could be a spell-checker, a thesaurus, or a collection of clip art.) You create and organize features yourself. See Strategies for Organizing Files Into Features on page 92. A component is a basic installation unit that is always installed or uninstalled as a coherent piece. Windows Installer tracks each component by the component ID, a GUID. See About GUIDs. Only one instance of a component is installed on a destination computer, allowing several features or applications to share the same component without installing multiple instances of it. Components include single files, a group of related files, COM objects, registry keys, shortcuts, resources, libraries grouped in a directory, or shared pieces of code such as DAO. When you add files to an installation, components are created based on a component rule set you select. (Example: You can create a new component for each new file added to the installation, or you can group related resources, such as help files, into one component.) You can reorganize components or create them manually by using Setup Editor > Components tab. See Component Rules on page 48. Windows Installer Editor Reference 492 Windows Installer and .NET Technologies For information on how Windows Installer handles components and features, see the following topics in the Windows Installer SDK Help: Windows Installer Components Component Management Components and Features Organizing Applications into Components See also: About Microsoft Windows Installer on page 490 About GUIDs GUID stands for globally unique identifier. It is a data type comprised of a text string that represents a Class identifier (ID). The purpose of a GUID is to provide a unique identifying string that differentiates products, packages, components, features, upgrades, patches, and so on. By reading GUIDs, Windows Installer can determine what is installed on a destination computer and take appropriate action. Examples: z When you create an upgrade, you enter the upgrade codes, which are GUIDS, for the versions of the application that can be upgraded. Then during installation, Windows Installer searches the destination computer for these upgrade codes to determine whether an upgrade should occur. z Each component of an application has an assigned GUID. You can use the System Search page to quickly search for components on the destination computer to determine if a previous version exists. A GUID must be in the format: {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX} where X is a hex digit (0,1,2,3,4,5,6,7,8,9,A,B,C,D,E,F). Windows Installer Editor generates GUIDs whenever necessary, using an algorithm that reduces the chances of generating a duplicate GUID to almost zero. If you need to change a GUID, Windows Installer Editor provides a Generate button that generates a new, valid GUID. Warning Do not try to create a GUID by typing random hex characters. See also: About Microsoft Windows Installer on page 490 About Microsoft .NET Technology The Microsoft .NET platform is a family of products that provide tools for developing, server infrastructure for managing, and building block services and client software for using XML services. The .NET Framework, which is a .NET development tool, is an environment for building, deploying, and running XML Web services. It consists of several parts, including the common language runtime, which is the engine at the core of managed code execution. Microsoft Visual Studio .NET is a development tool that exploits the capabilities of the .NET Framework to build powerful Windows applications. Windows Installer Editor Reference 493 Windows Installer and .NET Technologies Windows Installer Editor simplifies the process of creating installations for .NET applications, automating the process by extracting most of the installation details from your assemblies. Windows Installer 2.0 or later only The ability to create .NET installations is supported only by Windows Installer 2.0 or later. See also: Frequently Asked Questions About Microsoft .NET on page 494 Requirements for Creating a .NET Installation on page 497 Creating a .NET Installation When You Have the .NET Framework on page 239 Creating a .NET Installation Without the .NET Framework on page 240 Importing .NET Framework Security Settings on page 258 For information on setting the required .NET Framework version, see Setting a Requirement on the System Requirements Page on page 164 Frequently Asked Questions About Microsoft .NET This section covers important concepts you should understand before you use Windows Installer Editor to build .NET installations. What does the common language runtime do? The common language runtime manages the execution of code and provides services such as cross-language integration, code access security, object lifetime management, and debugging and profiling support. Search for “Common Language Runtime” in the MSDN Library (msdn.microsoft.com/library/). What’s the difference between managed and unmanaged code? Code developed with a language compiler that targets the common language runtime is called managed code. All code based on Microsoft intermediate language (MSIL) executes as managed code. Managed code is self-describing; it contains metadata that describes every element managed by the common language runtime. The runtime uses the metadata to provide services. Code that runs outside the runtime and does not contain metadata is called unmanaged code. Examples of unmanaged code are COM components, ActiveX interfaces, and Win32 API functions. Unmanaged code executes in the common language runtime environment with minimal services. Can I add managed code to an existing application? Few developers are able to rewrite existing applications completely as managed (.NET) code. Instead, you can combine managed and unmanaged components in one installation. Code that contains a mix of managed and unmanaged elements is called interoperable code. The common language runtime supports COM interoperability (interop). For backward compatibility, COM interop provides access to existing COM components without requiring you to modify the original components. COM interop also enables your COM clients to access managed code as easily as they access other COM objects. This is accomplished by adding information to the system registry so .NET components are Windows Installer Editor Reference 494 Windows Installer and .NET Technologies called as though they were COM components. At run time, the common language runtime marshals data between COM objects and managed objects as needed. Search for “Interoperating with Unmanaged Code” in the MSDN Library (msdn.microsoft.com/library/). What is an assembly? An assembly is the primary building block of a .NET application. An assembly contains its own naming, binding, versioning, deployment, and configuration information. It consists of two elements: a manifest, which is the meta data that describes information about the assembly and any resources it depends on; and a set of instructions in the form of Microsoft Intermediate Language (MSIL) code that is executed when the assembly is referenced. You can group assembly elements into a single file assembly, which incorporates the manifest into a portable executable (PE) file, which can be an .EXE or .DLL, with the source code. You also can create a multifile assembly consisting of modules of compiled code, resources, or other files required by the application. In a multifile assembly, the manifest can be a stand-alone file or it can be incorporated into one of the PE files in the assembly. When you add a .NET assembly to an installation, Windows Installer Editor creates entries in the MsiAssembly and MsiAssemblyName tables. See Assemblies in the Windows Installer SDK Help. How does .NET reduce file sharing conflicts? An important benefit of .NET installations is the reduction of file sharing conflicts. With the common language runtime, the assembly is described by a manifest; the registry is no longer relied upon for storing and accessing the COM activation data. This allows components to be fully isolated from each other. Assembly sharing is accomplished in several ways: z Global Assembly Cache To install .NET assemblies that are intended to be shared by many applications on the computer, make sure they are strongly named and install them into the Global Assembly Cache, which is a machine-wide code cache. Do not install assemblies into the Global Assembly Cache unless they specifically need to be shared. The Global Assembly Cache is available only if the .NET Framework is installed on the destination computer. z Side-by-side To safely share COM or Win32 assemblies among multiple applications and to minimize .DLL conflicts, use side-by-side assembly sharing. Instead of having a single version of an assembly that assumes backward compatibility with all applications, side-by-side assembly sharing enables multiple versions of a COM or Win32 assembly to run simultaneously on the destination computer. Side-by-side assembly sharing is available only on Windows XP or later. See Side-by-Side Assemblies in the Windows Installer SDK Help. z Private assembly To reserve a Win32 assembly for the exclusive use of one application, install it in a directory that is private to the application, typically the application directory. This is called a private assembly. The dependency of the application on the private assembly is specified in an application manifest file. On operating systems earlier than Windows XP, a copy of the private assembly and a .local file is installed into a Windows Installer Editor Reference 495 Windows Installer and .NET Technologies private directory for the exclusive use of the application. A version of the assembly is also globally registered on the system and made available for any application that binds to it. The global version of the assembly can be the version installed with the application or an earlier version. I thought .NET meant I could use XCOPY to install applications without registration. Why do I need to build a Windows Installer installation? For a .NET application that uses only managed code and private assemblies, the installation process can be as simple as copying files to the destination computer. Most developers, however, still need to create a compressed, single-file installation that is easy to deploy and that provides a friendly interface to the end user. .NET applications that use shared assemblies, or that have a mix of managed and unmanaged code, cannot be installed with XCOPY. You should use the Windows Installer service for installations that do any of the following: z Install COM files z Install assemblies to the Global Assembly Cache z Require user information during the installation z Require security z Create a shortcut z Require elevated privileges to install on a locked-down computer By creating a Windows Installer installation for your .NET applications, you can take advantage of the services Windows Installer provides: installation, repair, and removal of assemblies; roll back; install-on-demand; patching; and advertisement. How does Windows Installer Editor support .NET installations? Windows Installer Editor lets you install .NET assemblies into the Global Assembly Cache, or as side-by-side or private assemblies. It also lets you create mixed installations by registering .NET assemblies with COM. If the .NET Framework is installed on your computer, Windows Installer Editor can automate the process as follows: z Find all files in multifile assemblies and add them to the installation. z Scan for assembly dependencies and add them to the installation. z Determine attributes for registering the assembly files and add them to the MsiAssemblyName table. z Add registry keys for COM interop. See also: About Microsoft .NET Technology on page 493 Requirements for Creating a .NET Installation on page 497 Creating a .NET Installation When You Have the .NET Framework on page 239 Creating a .NET Installation Without the .NET Framework on page 240 For information on setting the required .NET Framework version, see Setting a Requirement on the System Requirements Page on page 164 Windows Installer Editor Reference 496 Windows Installer and .NET Technologies Requirements for Creating a .NET Installation The ability to create .NET installations is supported only by Windows Installer 2.0 or later. When you create a .NET installation, you should have the .NET Framework installed on your computer. If the .NET Framework is installed on your organization’s development computers, but not on the computer used to build installations, it is possible to create a .NET installation. However, you must enter certain information manually. See Creating a .NET Installation Without the .NET Framework on page 240. You can build .NET installations without having Windows XP or later on your computer. However, in order to take advantage of side-by-side assembly sharing, the destination computer must have Windows XP or later installed. To use the Global Assembly Cache, the destination computer must have the .NET Framework installed. Before you begin to create an installation for your .NET application, do the following: To prepare to create a .NET installation 1. Gather all your assemblies, both Win32 and .NET, and their manifests into a common location. 2. Determine the directories in which the assemblies are to be installed. You can install assemblies into the Global Assembly Cache, the WinSxS directory, or a private directory. For information on how each of these directories is used, see Adding .NET Assemblies to the Installation on page 115. 3. For assemblies that are to be installed into the Global Assembly Cache or WinSxS, generate publicKeyTokens and sign the assemblies. See also: About Microsoft .NET Technology on page 493 Frequently Asked Questions About Microsoft .NET on page 494 Creating a .NET Installation When You Have the .NET Framework on page 239 Creating a .NET Installation Without the .NET Framework on page 240 For information on setting the required .NET Framework version, see Setting a Requirement on the System Requirements Page on page 164 Windows Installer Editor Reference 497 Appendix A Wise Custom Actions Windows Installer Editor uses custom actions to add functionality that is not available with the Windows Installer standard actions. When you use certain features, such as custom actions that call a .DLL, Wise custom actions are added to the installation. Warning Removing Wise custom actions might cause problems with the installation. The Windows Vista Logo Program requires you to document every custom action in an installation. This applies to the Wise custom actions as well as the ones you add. If you plan to certify an installation for Vista, use the information in the following table to document the Wise custom actions. You document the custom actions on the Description tab that appears on the details dialog box for all custom actions. See Using the Custom Action Description Tab on page 489. See also: About MSI Script on page 436 Guidelines for Using Custom Actions on page 449 Wise Custom Actions Custom action Description ClearDisableUAP Checks the version of Windows on the destination computer. If it is less than 6 (earlier than Windows Vista), then it clears the DisableUAP property. When User Account Control is disabled, the option to install for all users or for the current user on the installation’s User Information dialog box is hidden. If the installation has User Account Control disabled, but is run on a version of Windows Installer earlier than 4.0, then that option on the User Information dialog box is shown. This is the default behavior for earlier versions of Windows Installer. ConfigureWebUI Windows Installer Editor Reference z Inspects the destination computer to see if the Web installation can be installed. z Loads all the information out of the tables and configures the properties needed to properly display the Web dialog boxes based on the destination computer. z Populates the list of existing Web sites that appears on the Web dialog boxes when installing to an existing site. z Checks for WISE_CONFIG_INPUT_PATH and WISE_CONFIG_OUTPUT_PATH to determine if Windows Installer Editor should generate or read in settings to or from a configuration file. 498 Wise Custom Actions Custom action Description DiagnosticAppSearch Enumerates the entries in the AppSearch table and evaluates the expressions using the MSIEvaluate Property function. It then retrieves the value of the property and reports the results. DiagnosticCheckDiskSpace Evaluates the disk costing and identifies computers that don’t meet the requirements. The MsiVerifyDiskSpace function calculates the costing and validates the amount of disk space. The following properties are used to display the amount of disk space required and available on the destination computer: DiagnosticCheckDotNet z PrimaryVolumePath z PrimaryVolumeSpaceAvailable z PrimaryVolumeSpaceRequired z PrimaryVolumeSpaceRemaining Determines if .NET is required by this installation. The Preflight Instrumentation determines if this check is required by checking the MsiAssembly table for entries with 0 in the Attributes column. If the check is not required, the Preflight Instrumentation does not insert this check. The test first ensures that there is a .NET assembly in the package. It then retrieves from the registry the versions of .NET that are installed. If a version of .NET is installed, it returns success and lists the versions installed. If no version is installed the test fails. This check is inserted after the launch condition check. DiagnosticCheckExecuteLocally Evaluates type 34 or type 50 custom actions, which run a file that is expected to exist on the destination computer. Once the test obtains the application path and ensures that it is valid, it calls the load library to ensure the application can be loaded and returns success if the application succeeded, failure if not. DiagnosticCheckInUseFiles Tells the user how many files in the preflight installation are in use. The message it returns is: Checked x files (OCX, EXE, and DLL files only), y are in use. DiagnosticCheckLaunchCondition Determines which launch conditions succeed and which fail. It enumerates the LaunchCondition table and evaluates the condition using the MsiEvaluateCondition API function. During preflight instrumentation, Windows Installer Editor determines if any actions were removed in the InstallExecuteSequence before the LaunchCondition action. If actions were removed, Windows Installer Editor cannot determine if the launch condition failed because of the removed action or because of the condition. Preflight instrumentation sets the property WISEDIAGLAUNCHWARN to 1 to indicate that Windows Installer Editor cannot determine the reason the launch condition failed. DiagnosticCheckPatchExistence Windows Installer Editor Reference Based on the patch GUID, checks if the patch is already installed. If it is, it returns a failure; otherwise, the test passes. 499 Wise Custom Actions Custom action Description DiagnosticFileAssociationConflict Processes the Extension table and checks the registry for support for each extension. This test opens the registry key for the extension. If the key exists, then the extension is already registered. The existing value of the key is compared with the ProgId to be registered; if they match, the same application re-registers the same extension. If they do not match, the application being installed overwrites the existing extension. If the key is empty, the extension is registered but no application is associated with it. DiagnosticLaunchWeb During Preflight Instrumentation, extracts URLs from the DisplayURL, DownloadFile, and PostToHttp custom actions. It puts them in a table, WiseUrlDiag, which is processed on the destination computer. First, the test ensures that the connection can be opened to the specified URL; then, the content is downloaded. The test then translates the result into text. DiagnosticManagedFileCheck Ensures that files that have been distributed throughout the environment are known and tested. This test ensures that a given computer is in a well known, managed state and that testing and conflict management operations are valid in the production environment. DiagnosticMarkBeginRun Indicates the beginning of the preflight test. Also determines if the application that the preflight package is testing is already installed. DiagnosticMarkEndRun Indicates the end of the preflight test and that the .MSI was fully processed. Preflight Analysis uses the DiagnosticMarkEndRun test to determine if a run is incomplete. DiagnosticOpenDocExtChec During Preflight Instrumentation, builds a list of document extensions from the OpenDocument custom action and saves the list in the WiseExtDiag table. On the destination computer, checks the registry for support for each extension. This test tries to open the registry key associated with the extension. If it successfully opens the key, then an association exists. Otherwise, no association exists. Diagnostic Payload Installed Determines which files can be installed based on Windows installer file versioning rules. The message it returns is: There are x files in this installation, y files will be installed. DiagnosticSecurityCheckFileRead Iterate through the files or registry keys and values that can be installed by the installation and query the system for permissions to create, access, and update files or values. DiagnosticSecurityCheckFileWrite DiagnosticSecurityCheckRegistry Read DiagnosticSecurityCheckRegistry Write NalpLaunchCA Windows Installer Editor Reference Build a list of all securable objects from the File and Registry tables. For objects that exist, the test reads the security descriptor. For each profile on the system (read tests) or the installer’s account (write tests), the test reads each security descriptor’s access control list and determines the user’s level of access to the object. For objects that do not exist (Example: objects that will be installed), the parent object’s access control list is used to determine the access level. The test also reads and applies information from the LockPermissions table to gather additional security information (read test only). If you add Nalpeiron support to an installation, and you choose to add support for Control Activation, this runs the Control Activation.exe after your installation finishes on the destination computer. 500 Wise Custom Actions Custom action Description NalpRemoveLicense If you add Nalpeiron support to an installation, these deactivate the Nalpeiron license when your application is uninstalled from the destination computer. NalpRemoveLicenseSetProp PopulateVirDirs Populates the list of existing virtual directories for a given site when installing to an existing virtual directory. SetARPINSTALLLOCATION Sets the ARPINSTALLLOCATION property to the value of INSTALLDIR. SetPatchMode Sets the REINSTALL property to the list of features in the previous version of the user’s application and sets the ADDLOCAL property to the list of features, if any, that were added to the installation in the new version of the application. This action is added to all installations but affects only installations that use patching. SetPatchReinstallMode Sets the REINSTALLMODE property to “omus” (the Windows Installer default) for patches. See REINSTALLMODE Property in the Windows Installer SDK Help. This action is added to all installations but affects only installations that use patching. SetWizardProperty Determines what user interface wizard to display in the maintenance mode. SetWizardProperty1 Determines what user interface wizard to display in the regular installation mode. ViewLog (Windows Installer 4.0 or later only.) Displays the installation log when any of the logging options on the Windows Installer Options page are marked, and the end user marks the View the install log check box on the installation’s Exit dialog box. WiseAltStartup When you add a custom action that calls a .DLL with parameters, this action is added to save the current state of properties for use by the custom actions running in deferred mode. WiseCleanup When you add a custom action that calls a .DLL with parameters, this action is added to clean up any temporary files left over from the custom action. Wise textreplacementinit Immediate mode custom action that reads Dynamic XML data and stores it in a file for use by the deferred custom action Wise textreplacementmodify. Wise textreplacementmodify Deferred mode custom action that reads data stored by Wise textreplacementinit and performs the appropriate XML substitutions. WiseElevateCheck (Windows Vista or later only) Determines whether the installation is running with elevated privileges and elevates it if necessary. Caution If this custom action appears in an installation, do not remove or move it. WiseFindSqlClientTools Sets the property WiseOsqlCmd to the command line to run the Osql tool. WiseFirewallInfo Gathers information about the Windows Firewall during installation on Windows XP SP2, Windows Server 2003 SP1, and later. WiseGetASPNETUser Sets Windows Installer properties (ASPNET1.0_USER, ASPNET1.1_USER, and ASPNET_USER) containing the names of the ASP.Net users. These can be used to grant access to a user during installation. WiseGetDotNetVersion Sets the property DOTNETFX to 1 if at least one version of .NET framework is installed. Also sets various properties to 1 to indicate which versions of .NET framework are installed (Example: DOTNETV1.0.3705). Windows Installer Editor Reference 501 Wise Custom Actions Custom action Description WiseGetIEVersion Sets Windows Installer properties containing the version of Internet Explorer installed on the destination computer. These can be used for launch conditions to ensure that the computer has a required version of Internet Explorer installed. IEVERSION contains the version in simplified form, and IEVERSIONEX contains the complete version. WiseGetIISFeaturesEnabled Sets properties (CGIENABLED, ISPAIENABLED, ASPENABLED, ASPDOTNETENABLED, SSIENABLED, IDCENABLED, FPEXTENABLED, and WebDAVENABLED) to show which features are enabled in IIS. This is useful for setting launch conditions to ensure that the destination computer has the required environment for the installation. WiseGetIISVersion Set a property with the major IIS version (IISVERSION). WiseGetSQLServers Uses the WiseOsqlCmd property to call osql to get the list of available SQL servers. Then it reads the property WiseSqlParam to get the name of a property that is used by a combo box in the ComboBox table. It then fills that combo box with the list of SQL servers. WiseGetSQLServerVersion Sets the property SQLSERVERVERSION to the version of SQL Server (or MSDE) installed on the destination computer. WiseIISValidateInput Validates input for the Web dialog boxes. (Example: It verifies that port numbers are within range and IP addresses are formatted correctly.) WiseNextDlg Determines the dialog box to display when the end user selects the Next button. WisePrevDlg Determines the dialog box to display when the end user selects the Back button. WiseRegComPlus Add Remove Deferred mode custom action that reads data stored by WiseRegComPlus In it and creates or deletes MTS/COM+ components that are specified on the MTS/COM+ page. WiseRegComPlus In it Immediate mode custom action that reads MTS/COM+ data and stores it in a file for use by the deferred custom action WiseRegComPlus Add Remove. WiseRemoveFirewall During an uninstall, undoes changes that the installation made to the Windows Firewall. (Windows XP SP2, Windows Server 2003 SP1, and later.) Wise Set Assembly Framework Properties Scans the MsiAssemblyName table to find the .NET Framework version associated with each component and its related .NET assembly and then sets a property with the results. This ensures that, when the Execute Install method on this assembly check box is marked on the File Details dialog box, the utility from the correct .NET Framework version is used for each assembly. WiseSetFirewall Configures the Windows Firewall during installation on Windows XP SP2, Windows Server 2003 SP1, and later. WiseSingleFileCheck Adds functionality for creating single-file .EXE installations. It removes cached copies of the .MSI that are extracted during uninstalls. WiseSQLCallDLL Reads a file of SQL commands and executes them. This is how Windows Installer Editor executes SQL scripts on the SQL Scripts page. WiseStartup When you add a custom action that calls a .DLL with parameters, this action enables parameter passing for actions that call a .DLL file and extracts the necessary Wisescript .EXE and .DLL files. Windows Installer Editor Reference 502 Wise Custom Actions Custom action Description WiseTestSqlConn Reads the property WiseSqlParam to get the names of properties to use for the SQL connection test. It then reads those properties to get the user name, password, and so on, and tries to connect to the SQL server. If it is successful, it sets the value of the last property in WiseSqlParam to the full connection string. If it fails, it sets the property WiseSqlError to an error message. WiseUpgradeCheck When you add upgrade information to the Upgrades page, this action is added to work around issues where the Windows Installer runtime does not detect previous versions of the application. WiseUpgradeCheckEx When you add upgrade information to the Upgrades page, this action is added to work around issues where the Windows Installer runtime does not detect previous versions of the application. WiseVirtDirCallDll Creates, modifies, or removes the appropriate Web sites and virtual directories based on the XML generated by WiseWriteWebXmlDll. WiseWriteWebXMLDll Generates XML for operations that must take place during the installation, based on table information and properties set on the Web dialog boxes. The generated XML is stored in the registry under a Wise subkey of the installation’s uninstall key in HKEY_LOCAL_MACHINE. Windows Installer Editor Reference 503 Appendix B Wise Tables Wise tables contain information that is related to items you added in Windows Installer Editor. Most of these tables do not appear in the compiled .MSI, unless noted otherwise or unless you use an .MSI file as the project file. Some of the tables listed below are available in certain Wise products only. Warning Deleting, adding, or editing table data directly is not recommended unless you are an experienced Windows Installer developer with a clear understanding of Windows Installer database technology. Editing table data might cause unexpected, undesirable behavior, including damage to the installation. We cannot provide technical support for problems arising from table editing. See also: Tables Tab on page 376 Wise table Remains in .MSI? Description WiseAdvertising Contains the advertising information you select in the Compiler Options section of the Component Details dialog box WiseCommandLine Contains the information that is used on the Command Line page WiseComPlusApp Yes Contains a list of MTS/COM+ applications that are in the installation WiseComPlusComponent Yes Contains information relating to MTS/COM+ applications that are in the installation WiseCustomActionDoc Yes Contains descriptions of custom actions in the installation, which are required for Windows Vista certification You enter these descriptions on the Description tab on each custom action’s details dialog box. WiseDlgSequence Yes WiseFeatureCondition Contains information about the sequence and display conditions of wizard pages Contains a list of the conditions you added to features on the Installation Expert’s Features page WiseFileAttributes Yes Contains bit fields associated with a file that is a part of an installation WiseFileHash Yes Speeds compiles by storing the hash information used to populate the MsiFileHash table Windows Installer Editor Reference 504 Wise Tables Wise table Remains in .MSI? Description WiseFirewallSetup Yes Stores options that are configured on the Firewall Exceptions page WiseInstanceTransforms Contains information about instance transforms that are defined in Installation Expert > Instance Transforms page. WiseLangString Contains all strings for all languages currently defined in the installation. WiseLanguage Contains a list of all languages defined for the installation, along with the corresponding releases. WiseLaunchCondition Yes WiseMediaOptions Contains a list of all the launch conditions you specify on the System Requirements page for IIS Version and its subentries. You can specify the order in which these conditions will be evaluated in the order column. If the attributes condition is set and the condition fails, then the processing of the WiseLaunchCondition table stops and the current message is displayed along with the messages from any previous conditions that might have failed. Contains a list of values for development environment display purposes Also contains assembly dependencies that have been excluded from assembly dependency scans WiseMetaDataCache (Wise Package Studio only) Contains user-defined meta data after values for the meta data are entered on the Product Details page WiseMobileDevice Contains a list of all mobile device applications, a description of each, and appropriate attributes WiseMobileDeviceDesktopFiles Yes This is added only when you add a Palm application to the Mobile Devices page It describes the files in the file table that are mobile device files. WiseModuleConfiguration Contains the information that configurable merge modules use during the merge process WiseModuleSignature Contains a list of merge modules that are in the installation project file WisePageLists Contains information on the page groups of the page view associated with the installation WisePathReplacement Yes In combination with Wise custom actions, enables conversion of registry path values that contain long file names or trailing backslashes WisePathVariable Contains paths that are defined on the Path Variables page. WisePocketPCFile Contains information about each file for a Pocket PC application WisePocketPCPlatform Contains information about each platform that the user selects on the Support Platform dialog box for a Pocket PC application Windows Installer Editor Reference 505 Wise Tables Wise table Remains in .MSI? Description WisePocketPCRegistry Contains information about each Pocket PC registry key and all of its attributes WisePocketPCShortcut Contains information about each Pocket PC shortcut and all of its attributes WisePrerequisites Contains information on prerequisites that are added to the installation on the Prerequisites page WiseRelease Contains a list of all releases in the installation WiseReleaseExclude Contains a list of features and components that you deselected for a particular release WiseReleaseMedia Contains a list of all media for each release WiseReleaseMediaDest Contains a list of all destination directories for each media within each release WiseReleaseMediaInclude Contains a list of all features and components that are included in a particular media WiseReleaseOverride Contains a list of properties and summary items that you overrode for a specific release on the Release Settings page WiseRuntimeVar Stores information about WiseScript runtimes that are added on the Prerequisites page WiseSequence Contains the remarks used in MSI Script as well as any empty If/End If blocks WiseSourcePath Contains a list of all source paths for all files that are in the installation WiseStreamFiles Contains a list of all source path names for custom actions and graphics that are in the installation WiseTaskList Contains a list of user-defined tasks that are in the installation WiseTextReplacement Yes Contains information concerning the dynamic content of XML files that are added to an installation on the Files or Web Files page when dynamic content is enabled on the Dynamic Content tab of the File Details dialog box. WiseVDAttributes Yes Stores the Web Dialogs settings for the virtual directories on the Web Files page WiseVersionInfo Yes This table is populated when a Windows Installer installation is imported into the Software Manager database It contains version information that speeds future subscriptions and imports of the installation. WiseVirtualDirectory Windows Installer Editor Reference Yes Stores the settings for virtual directories and Web folders that you created on the Web Files page 506 Wise Tables Wise table Remains in .MSI? Description WiseVSDropFile No (Visual Studio integrated editor only) Appears in an installation that is part of a Visual Studio solution Contains a list of files that result from projects that have been excluded from the current build configuration and therefore should not be included in the compiled .MSI WiseVSOutput (Visual Studio integrated editor only) Contains a list of project outputs and their settings WiseVSOutputGroup (Visual Studio integrated editor only) Contains a list of output groups for each solution WiseVSProject (Visual Studio integrated editor only) Contains a list of projects in the solution and their settings WiseWebSiteAttributes Yes Stores the Web Dialogs settings for Web sites that you created on the Web Files page WiseWebSites Yes Stores the settings for Web sites that you created on the Web Files page WiseWildcard Contains an entry for each time you add a wildcard in Installation Expert > Files page and mark the Update installation as files are added or removed from source directory check box WiseWildcardFile Contains a list of files that were originally added with a wildcard, and were later deleted because they no longer exist File information is stored so that if and when a file is readded, crucial information about the file is retained. Windows Installer Editor Reference 507 Appendix C Property Reference Properties are variables that are used by Windows Installer during installation. This section lists Windows Installer properties. This chapter includes the following topics: z Build Properties on page 508 z INI File Properties on page 512 z Run Time Properties on page 515 See also: Properties on page 391 Build Properties Properties that are defined by settings in an installation at build time are listed below. Some of them, such as INSTALLLEVEL, can be changed at run time from the command line or during the Action Sequence. You also can create new properties for your own use. See Creating a New Property on page 393. On the Build Options page, you can configure an installation to create an .EXE that launches an .MSI. Then the installation includes an .INI file that contains settings necessary for the installation to run. Some of the build properties below determine the default value of some of the properties in the .INI file. In that case, the property description includes the name of the corresponding property in the .INI file. Property name Description _WiseDebugMode By default, debug mode is off. Set this property to 1 to debug .DLLs that you added to an installation using a custom action. For this feature to work, the Custom Action Type for the action must be Call DLL with Variable Parameter List and you must have the Microsoft Visual C++ development environment installed. The debugger opens at a breakpoint just before your .DLL code begins, so at first you might see assembly code. If so, single-step ahead to see your .DLL code. _WiseDialogFontDefault Contains the text style used for body text on wizard pages. When you add a control, set its font to this font, otherwise the font specified in DefaultUIFont is used. The font choices for this property are listed in the TextStyle table located on the Tables tab. _WiseDialogSuffix Contains the text that’s appended to the name of the application (ProductName) in the wizard page title bar. Windows Installer Editor Reference 508 Property Reference Property name Description _WiseDialogTitleFontDefault Contains the text style used for the titles on wizard pages. This is not for the text in the title bar itself, but for the text inside the wizard that introduces the page content. The font choices for this property are listed in the TextStyle table located on the Tables tab. Accept Sets the initial value of the radio button on the License dialog. The default value, “No”, causes the I do not accept the license agreement radio button to be marked by default. The Next button on the License dialog has an event attached to it, which causes the Next button to be unavailable until the end user marks I accept the license agreement radio button. ApplicationUsers Sets the initial value of the radio button on the User Information dialog box. The default value, “AllUsers”, causes the Anyone who uses this computer radio button to be marked by default. The Next button on the User Information dialog box has an event attached to it, which causes the Windows Installer property ALLUSERS to be set to true if the end user leaves the Anyone who uses this computer radio button marked. APPS_TEST Provides backward compatibility for the System Search page for installations created in Windows Installer Editor 2.0 or later. DefaultUIFont Contains the text style used for the installation user interface if no other value is set. To match the default dialog box text that already exists, set any new controls you add to _WiseDialogFontDefault. The font choices for this property are listed in the TextStyle table located on the Tables tab. DisableUAP (Windows Installer 4.0 or later only.) Indicates whether User Account Control (UAC, previously known as UAP) is disabled. When User Account Control is disabled, the option to install for all users or for the current user on the installation’s User Information dialog box is hidden. DiskPrompt Contains the default text that prompts the end user to insert the next installation disk. ErrorDialog Contains the name of the dialog box that should be displayed if there are installation errors. IISVERSION If you add Web resources to an installation, this property is set during run time to the version of Microsoft Internet Information Server that is running on the destination computer. If IIS is not installed, this property remains empty during installation. INSTALLDIR This is the main installation directory for the application. By default, INSTALLDIR is set to the first directory you create under the Program Files folder on the Files or Web Files page. On the Destination Folder dialog box during installation, the end user can change this directory. The Windows Installer property PRIMARYFOLDER is set to the value of INSTALLDIR before installation of files begins. INSTALLLEVEL All features that have install levels less than or equal to this number are installed. This value is set by events that are attached to the Next button on the Installation Type dialog. InstallMode Sets the initial value of the radio button on the Installation Type dialog. The default value, “Typical”, causes the Typical radio button to be marked by default. The Next button on the License dialog has an event attached to it, which sets the value of the Windows Installer property INSTALLLEVEL. INSTALLLEVEL determines which features are installed. Windows Installer Editor Reference 509 Property Reference Property name Description MaintenanceMode Sets the initial value of the radio button on the Maintenance Welcome dialog. The default value, “Modify”, causes the Modify radio button to be marked by default. The Next button on the Maintenance Welcome dialog has events attached to it, which cause different pages to appear based on the radio button that is marked. Manufacturer Set this property to your company name. PIDTemplate Determines what characters are valid for the Product ID field on the User Information dialog. For information on the types of text available, see MaskedEdit Control in the Windows Installer SDK Help. PRIMARYFOLDER Contains the installation directory. Always leave this property set to INSTALLDIR. ProductCode ProductCode is a GUID (global unique identifier) generated by Windows Installer, that uniquely identifies this product. No product codes are alike. You can generate a new product code on the Product Details page. Do not enter new product codes, because they must be created according to a specific algorithm. If an installation creates an .EXE that launches an .MSI, this property sets the default value for the ProductCode property in the .INI file that’s generated. See INI File Properties on page 512. ProductID Contains the full product ID after the end user’s entry has been validated. ProductLanguage Indicates the language for this product. See Language IDs on page 285. ProductName Contains the name of the product, which is set on the Product Details page. ProductVersion Contains the product version number, which is set on the Product Details page. If an installation creates an .EXE that launches an .MSI, this property sets the default value for the ProductVersion property in the INI file that’s generated. See INI File Properties on page 512. ReinstallFileOlderVersion Indicates the action to take when an older version of a file being installed already exists. The default value of “o” means overwrite. This sets an option in the ReinstallMode dialog box. ReinstallFileVersion Indicates the action to take when the same version of a file being installed already exists. The default value of “o” means overwrite. This sets an option on the ReinstallMode dialog box. ReinstallRepair Indicates the action to take when reinstalling or repairing a file. The default value of “r” means repair. This sets an option on the ReinstallMode dialog box. SecureCustomProperties Contains a semicolon-delimited list of properties that are restricted public properties. UpgradeCode Contains the product code for a related group of products, one of which might be an upgrade for another. WiseCRLF Contains a carriage return/line feed. Use in editable text boxes to insert lines, or in property definitions. Windows Installer Editor Reference 510 Property Reference Property name Description WiseInitAdminError Contains the text of the error message that appears if the Windows Installer runtime needs to be installed but the current user does not have administrator privileges, which are necessary to install it. If an installation creates an .EXE that launches an .MSI, this property sets the default value for the AdminError property in the .INI file that’s generated. See INI File Properties on page 512. WiseInitCmdLine Contains the default command line that is passed to MSIEXEC, which is the Windows Installer executable that runs the .MSI. The command-line statement should end with the /I command-line switch. This property is absent unless you create it. If an installation creates an .EXE that launches an .MSI, this property sets the default value for the CmdLine property in the .INI file that’s generated. See INI File Properties on page 512. WiseInitExistError Contains the error that is displayed if a previous version of the installation is already installed on the destination computer. If an installation creates an .EXE that launches an .MSI, this property sets the default value for the ExistError property in the .INI file that’s generated. See INI File Properties on page 512. WiseInitLangDefault Contains the default language for the installation, which initially is English. It can also contain the language ID, separated from the language name by a comma. (Example: English, 1033). If the language of the destination computer matches this ID, the installation runs without applying any language transforms. If an installation creates an .EXE that launches an .MSI, this property sets the default value for the WiseInitLangDefault property in the .INI file that’s generated. See INI File Properties on page 512. WiseInitPrefix Contains the text that’s displayed before the “Wise Installation” text in the installation’s initialization window. The initialization window is the small window that appears before the installation wizard dialog boxes appear. If an installation creates an .EXE that launches an .MSI, this property sets the default value for the WiseInitPrefix property in the .INI file that’s generated. See INI File Properties on page 512. WiseInitProductName Contains the text displayed in the title bar of the installation’s initialization window. The initialization window is the small window that appears before the installation wizard dialog boxes appear. This value overrides the value stored in the ProductName property for the initialization window, to provide a shorter name that fits in the window. This property is absent unless you create it. If an installation creates an .EXE that launches an .MSI, this property sets the default value for the ProductName property in the .INI file that’s generated. See INI File Properties on page 512. Windows Installer Editor Reference 511 Property Reference Property name Description WiseInitProgressText Enter the text that should display while the hourglass is being displayed during installation. WiseInitSpaceError Contains the error text that is displayed if the destination computer does not have enough free disk space to copy the .MSI database to its local disk drive. If an installation creates an .EXE that launches an .MSI, this property sets the default value for the SpaceError property in the .INI file that’s generated. See INI File Properties on page 512. WiseInitSuffix Contains the text that’s displayed after the “Wise Installation” text in the installation’s initialization window. The initialization window is the small window that appears before the installation wizard dialog boxes appear. If an installation creates an .EXE that launches an .MSI, this property sets the default value for the WiseInitSuffix property in the .INI file that’s generated. See INI File Properties on page 512. WiseMaskedProperties Contains Windows Installer properties that can be set by the end user during installation, and whose value will be masked. WISEWEBSITES properties Warning Do not edit any properties whose name begins with WISEWEBSITES. They are set when you add Web resources to an installation and generate Web dialog boxes. Changing these properties can result in unexpected behavior. Also, when the Web dialog boxes are regenerated, any changes you make to these properties will be lost. See also: Run Time Properties on page 515 INI File Properties on page 512 Properties on page 391 INI File Properties On the Build Options page, if you configure a release to compile to an .EXE that launches an .MSI, then three files are generated during compile: an .EXE, an .MSI, and an .INI. The values of certain build settings are stored in the .INI file, which must be distributed along with the .EXE that launches the .MSI. You can change these settings, thereby determining how the .MSI database is run. The list below shows the properties that are stored in the [WiseInstaller] section of the .INI file. Some of the properties in the .INI file get their default values from the build properties. See Build Properties on page 508. See individual descriptions below to determine which build property the .INI property takes its default from, if any. Windows Installer Editor Reference 512 Property Reference Property name Description AdminError Contains the text of the error message that appears if the Windows Installer runtime needs to be installed but the current user does not have administrator privileges, which are necessary to install it. Defaults to the value of the build property named WiseInitAdminError. See Build Properties on page 508. CharFont Contains the font that is used in the installation’s initialization window. The initialization window is the small window that appears before the installation wizard dialog boxes appear. This also affects any other initial dialog boxes that appear, such as the language selection and password dialog boxes. CharSet Contains the character set that is used in the installation’s initialization window. Different languages have different character sets. The initialization window is the small window that appears before the installation wizard dialog boxes appear. This also affects any other initial dialog boxes that appear, such as the language selection and password dialog boxes. CharSize Contains the font size that is used in the installation’s initialization window. The initialization window is the small window that appears before the installation wizard dialog boxes appear. This also affects any other initial dialog boxes that appear, such as the language selection and password dialog boxes. CmdLine Contains the default command line that will be passed to MSIEXEC, which is the Windows Installer executable that runs the .MSI. The command-line statement should end with the /I command-line switch. This defaults to the value of the build property named WiseInitCmdLine. See Build Properties on page 508. DelayReboot If this is set to 1, a restart caused by pre-installation of the Windows Installer runtime is delayed to the end of the installation. It is set to 1 if you mark the Delay Windows Installer runtime reboot until after product installation check box on the Prerequisites page. ExistError Contains the error that is displayed if a previous version of the installation is already installed on the destination computer. This defaults to the value of the build property WiseInitExistError. See Build Properties on page 508. InstMSI CmdLine Contains the default command line that is passed to InstMsi.exe, which is the executable that installs Windows Installer. The default command-line switches are /q /r:i. Languagex Contains the language name and ID from the Language Details dialog box. The .INI file contains one Language line for each language in the release, where x is incremented for each language: Language1, Language2, and so on. LanguageFilex Contains the name of the installation .MSI. The .INI file contains one LanguageFile line for each language in the release, where x is incremented for each language: LanguageFile1, LanguageFile2, and so on. This property supports full URL addresses, so if you distribute this installation through the Web, you can specify the address where the file resides. Windows Installer Editor Reference 513 Property Reference Property name Description ProductCode ProductCode is a GUID (global unique identifier) generated by Windows Installer, that uniquely identifies this product. No product codes are alike. You can generate a new product code on the Product Details page. Do not enter new product codes, because they must be created according to a specific algorithm. This is the same as the build property ProductCode. ProductFile Contains the relative path to the .MSI that is being installed. You do not need to change this unless you move the .MSI from its default location. ProductName Text that displays in the title bar of the installation’s initialization window. The initialization window is the small window that appears before the installation wizard dialog boxes appear. This defaults to the value in the build property WiseInitProductName. See Build Properties on page 508. ProductVersion Contains the product version number, which you set on the Product Details page. This defaults to the value of the build property named ProductVersion. See Build Properties on page 508. Remove Previous If this is set to 1, the end user is prompted to remove any previously installed versions of the same application. It is set to 1 if you mark the Prompt to remove previous version before installing check box on the Build Options page. The message stored in the WiseInitExistError property displays. RuntimeNT Contains the relative path of the file that installs Windows Installer for Windows 2000/XP/2003. Do not change this property unless you change the location of this file. RuntimeVersion If an installation includes the Windows Installer runtime, this is the version of the included Windows Installer. You set an installation to include the Windows Installer runtime on the Prerequisites page. SpaceError Contains the error text that is displayed if the destination computer does not have enough free disk space to copy the .MSI database to its local disk drive. This defaults to the value of the build property named WiseInitSpaceError. See Build Properties on page 508. TransformMSI The TransformMSI .INI value is used if the file referenced in the ProductFile property is an .MST. In that case, the TransformMSI property contains the relative path of the base .MSI for the .MST. WiseInitLangDefault Contains the default installation language. This defaults to the value of the build property named WiseInitLangDefault. See Build Properties on page 508. WiseInitLangPrompt Text that displays on the dialog box that prompts the end user for a language during installation, which happens when you create a multiple-language release. Defaults to the value of the WiseInitLangPrompt property in the Property table. WiseInitPrefix Text that displays before the “Wise Installation” text in the installation’s initialization window. The initialization window is the small window that appears before the installation wizard dialog boxes appear. This defaults to the value in the build property WiseInitPrefix. See Build Properties on page 508. WiseInitProgressText Windows Installer Editor Reference Enter the text that displays with the hourglass during installation. 514 Property Reference Property name Description WiseInitSuffix Text that displays after the “Wise Installation” text in the installations’s initialization window. The initialization window is the small window that appears before the installation wizard dialog boxes appear. This defaults to the value in the build property WiseInitSuffix. See Build Properties on page 508. See also: Build Properties on page 508 Run Time Properties on page 515 Properties on page 391 Run Time Properties The properties listed in Build Properties on page 508 represent properties that are initialized by the installation. All build properties are also run time properties. Windows Installer sets additional properties at run time that contain useful information you can use in an installation. For definitions of all the properties Windows Installer sets at run time, see Property Reference in the Windows Installer SDK Help. In Web Installations When you add Web resources in Installation Expert > Web Files page, certain properties are set by a custom action. The following properties are provided so that you can grant the ASPNet account permission to directories. See Setting Permissions for Files and Directories on page 125. Property name Description ASPNET_USER When the .NET Framework is installed, it creates a user account with limited privileges to run ASP .NET applications. This property is populated with the ASP account of either the latest version of .NET, or the version of .NET checked for on the System Requirements page. ASPNET1.0_USER This property is populated with the ASP account that was created by the 1.0 version of .NET. ASPNET1.1_USER This property is populated with the ASP account that was created by the 1.1 version of .NET. The following properties are provided so that you can perform operations based on how and where the Web site or virtual directory is installed. (Example: Use these properties to create shortcuts to a Web site or virtual directory.) In the following property names, and are populated from the PropertyRoot column of the WiseVirtualDirectory table for the given Web site or virtual directory. Windows Installer Editor Reference 515 Property Reference Property name Description _HOMEDIR Contains the physical home directory of the virtual directory. _BEGINURL Contains the beginning portion of the URL of the virtual directory. _URL Contains the URL of the virtual directory. _BEGINURL Contains the beginning portion of the URL of the web site. Example: To create a shortcut to a specific page in the Web site, use: [_BEGINURL]file_name.html _HOMEDIR Contains the physical home directory of the web site or virtual directory. _INSTTYPE Contains the installation type of the web site or virtual directory (NEW, EXIST, or VIRDIR). _URL Contains the URL of the web site or virtual directory. From the SQL Connection dialog box When you add the SQL Connection dialog box to an installation, the following property is set by a custom action. This property is provided so that you can use it for the connection string in Installation Expert > SQL Server Scripts page. See Setting SQL Connection Strings on page 256 and Adding the SQL Connection Dialog to an Installation on page 423. Property name Description WISE_SQL_CONN_STR This property is populated with the connection string that is created when the end user completes the SQL Connection dialog box. See also: Build Properties on page 508 INI File Properties on page 512 Properties on page 391 Windows Installer Editor Reference 516 Index Symbols .NET about 494 ASP user properties 515 assembly options 34 file attributes 127 installation, creating 239, 240 installation, requirements 497 in installation sequence 440 standard 441 stored in Binary table 381 types 441 using conditions 384 Windows Installer 441 Actions list 437 activate prompts 43 assembly adding to installation 115 attributes 128, 241 defined 495 dependency exclusions 117 private 116, 495 scanning 116 scanning options 35 scanning problems 36, 117 sharing 116, 495 side-by-side sharing 116, 495 .NET Compact Framework 218 Add button, unavailable 23 .NET Framework about 493 creating installations with 239 downloading from Web or CD 29 end-user license agreement 197 EULA 197 importing security settings 258 pre-installing 195, 205, 240, 241 version required 166 Add/Remove Programs page 89 administrative image 225 attributes (assembly) adding to installation 128, 241 obtaining 241 .NET Framework Security page 258 Administrative Install page 225 Authenticode 237 .NET Runtime URL 205 administrative installation about 438 dialog boxes 437 automatic conflict resolution 135 .NET Update URL 205 _Property table 435 _WiseDebugMode 508 _WiseDialogFontDefault 508 _WiseDialogSuffix 508 _WiseDialogTitleFontDefault 509 Numerics 32-bit installation about 61 guidelines 65 386 file 156 64-bit component 372 64-bit installation about 61 developing on 32-bit computer 61 differences from 32-bit 62 guidelines 65 AddFile event macro 429 Add-on folder, Palm about 219 installing to 221 Admin Dialogs 396 AdminError 513 Administrator Options page 222 advertisement about 491 auto-adding information 36 configuring shortcut for 152 extension, adding 366 features 492 how it works 491 options 36 rescanning advertising info 37 shortcuts 223 Advertisement Installation mode about 438 dialog boxes 437 All Custom Actions mode 438 Altiris Support Helpdesk 15 A application name 84 path 136 watching 347 Accept property 384, 509 Application Manager 217 action adding to sequence 442 Also see custom action built-in 441 condition 451 copy and paste 442 deleting 441 dialog box 441 in component rule 49, 54 in debugger 432 application type options 35 specifying 85 9x Download URL 205 Windows Installer Editor Reference ApplicationUsers 509 ApplicationWatch 347 AppPath 136 APPS_TEST 509 ASPNET_USER 515 assembly dependencies adding 351 obtaining 241 asynchronous, defined 488 automatic updating 46 automation about 427 of build process 237 of compile 237 B background build 237 backward compatibility dialog boxes 398 themes 400 billboard about 418 adding 419 control 418 creating 419 where to use 419 binary resource adding 103 error 104 exporting 102 linking to file 103 properties, changing 102 refreshing 103, 103 saving 102 source file, editing 102 updating 103 Binary table auto-updating 381 editing 381 missing file 104 storing .DLL 459, 461 storing .EXE 471 517 storing .MSI 474 storing scripts 464, 466 storing WiseScript 479 Cancel button, hiding in installation 230 commit only 487 CAPICOM 237 common language runtime 494 Also see .NET Framework bitfield, for substitution 331 CER file 237 bitmap adding to dialog box 414 dialog box control 407 setting on dialog box 412 CharFont 513 CharSet 513 CharSize 513 Common Files folder 491 comparison of Windows Installer files 74 to source control 311 Build Options page 190 cluster size 209 build properties 508 CmdLine 513 compile automating 237 changes not saved 81 changing source directory 318 error in Task List 24 file path errors 78, 316 how to 77 incrementing version 86 local 78 log file 236 quick 34, 78 release 182, 184 remote 78 silent 236 with multiple processors 38 build settings .INI 512 code group, importing for .NET 259 Complete feature 91 button dialog box control 407 resizing for language 280 code page 271, 274 Complete installation type 179 code signing See digital signature C colors in sequence 441 component 64-bit 372 adding 371 assigning to feature 364, 373 checking if installed 390, 390 condition not working 386 conditions, adding 385, 385 creating 48, 492 defined 492 editing 371 fixing conflict 137 including in media 211 isolating 374 key path 374 moving 365 moving items to 373 moving to merge module 327 naming 50 publishing 375 removing from feature 365 renaming 371 searching for 172 selecting for release 187 blank line, inserting 478 breakpoint, debugger clearing 434 setting 434 check box dialog box control 407 setting items 414 check in files 308 build Also see compile automating 237 sharing settings 188 check out files 309 Build column 184 Citrix compatibility 183 build error See compile Check Repository Files 113 check tables for errors 24, 380 checksum, validating 125 ClearDisableUAP 498 column, table 377 C# importing 350 project types 349 tips for import 349 CAB file, creating 208 CAB file, mobile device about 216 adding to installation 217 CabWiz about 217 Call Custom DLL from destination 457 from installation 458 from installed file 459 tips 453 Call DLL from installation 461 from installed file 462 tips 453 Call JScript from embedded code 463 from installation 463 from installed file 464 from property 465 tips 452 Call VBScript from embedded code 466 from installation 466 from installed file 467 from property 468 tips 452 Windows Installer Editor Reference COM interoperability (interop) about 494 registering .NET assembly 85, 241, 323 COM+ 260 combobox dialog box control 407 Command Line page 227 command verb 155 command-line options, installation about 226 advertising 232 creating 227 general options 227 installation log 175, 230 logging 175, 230 patch, applying 234 patch, removing 234 public property, changing 233 repair 232 running 81, 227 testing 79 transform, applying 234 UI options 229 command-line options, WfWI.exe about 226 compiling with 319 create log file 236 example 236, 319 list of 235 command-line, creating 227 comment out line 443 component error, add to Task List 24 Component Object Model 260 component rules about 49 action 49, 54 adding 53 aligning GUIDs 51 Also see rule set or component condition 49, 54 deleting 53 editing 53 how applied 49 in upgrade 51 518 Microsoft Best Practices 55 modifying 53 One File Per Component 56 predefined 55, 56 selecting 50 sharing 44, 49 ComponentRules.ini 44 Components tab about 368 adding file 111 errors, showing 370 showing, hiding items 368 tree structure 368 compression compiled installation 183 installation files 208 CondFix.msm about 386 when to add 387 condition about 383 adding to dialog box 384 attached to event 385 building 387 checking environment variable 389 checking for component 390, 390 checking for feature 390, 390 checking on reinstall 120, 372 checking property value 388 deleting from Features page 101 evaluating at run time 433, 435 example 386 for component 385, 385 for dialog box item 413 guidelines 385 in component rule 49, 54 not working 386 on Features page 383 organizing 92 setting for action 384, 473 setting for component 371 system requirements 384 tips 451 using environment variable 385 using numbers 385 using properties 383, 385 using string 385 where to use 383 Condition Builder 387 configurable data 329 configurable merge module Also see merge module configuration item 328 creating 328 configuration item 328 adding 328 bitfield 331 configurable 328 constant 328 data types 329 Windows Installer Editor Reference defining 329 key into a table 332 text drop-down 330 custom installation 98, 179 custom installation template See template ConfigureWebUI 498 Custom Property dialog box 425 conflict detection 134 custom tab, in MSI Script 442 conflict resolution about 134 Also see resolving conflicts rules 135 CustomActionData 454 connection string 256, 423 Control Activation 500 controls See dialog box control convert MSI to WSI 352 SMS Installer 347, 348 source paths 315 WiseScript installation 347, 348 Convert button, Dialogs page 398 copy file on destination computer 122 credentials file 38, 237, 238 Current Feature list about 22 Features page 91 number in parentheses 23 Current Release list 23 custom action accessing properties 454 added by Wise 498 adding outside a sequence 439 adding to multiple sequences 439 adding to sequence 442 calling another installation 451 choosing location 451, 484 compile error 104 condition 451 configuring parameters 460 copy and paste 442 description 489 documenting 489 guidelines 449 in deferred mode 454 in merge modules 485 methods for calling .DLL 453 moving 451 name for merge module 485 properties 486 report 489 restrictions on placement 442 run level 448 run on uninstall 451 run once 451 running from dialog box 454 setting condition 473 stored in Binary table 381 tips 449 troubleshooting 455 using formatted text strings 451 Wise 498 D data source, ODBC adding 159 details 160 database configuring during installation 254 connecting to 256 creating during installation 257 running SQL statements 256 database file, Windows Installer 60 Also see MSI file debug DLL 454 VBScript 434 Debugger for Windows Installer about 432 breakpoints 434 evaluating conditions 433, 435 log file 433 properties, setting 434 properties, viewing 433 running 433 starting 432 table, viewing 433 tables, searching 435 temporary table, viewing 435 transform, applying 434 window, rearranging 433 default directory application installation 88 changing 85 projects 45 default language 281 default release language about 282 setting 266, 271, 274 DefaultUIFont 509 deferred execution 487 deferred mode about 440 accessing properties 454 DelayReboot 513 Delete button, unavailable 23 Delete Unreferenced Rows 332 delete virtual layer 81 Dependencies page 323 Custom Actions directory 28, 45 519 dependency adding 116 adding to merge module 323 adding without .NET Framework 241 defined 323 exclusions, about 117 files not found 350 global exclusions 118 scanning for 240 scanning options 35 scanning problems 36, 117 description, custom action 489 desktop installation adding Palm OS files 220 adding Windows Mobile files 217 Desktop, add shortcut 150 destination computer copying file 122 how files are stored 491 moving file 122 removing file 120 removing registry entry 142 detect conflicts 134 development process, streamlining 47 device driver adding to Add/Remove Programs 132 installing 71 options 132 DiagnosticAppSearch 499 DiagnosticCheckDiskSpace 499 DiagnosticCheckDotNet 499 DiagnosticCheckExecuteLocally 499 DiagnosticCheckInUseFiles 499 DiagnosticCheckLaunchCondition 499 DiagnosticCheckPatchExistence 499 DiagnosticFileAssociationConflict 500 DiagnosticLaunchWeb 500 DiagnosticManagedFileCheck 500 DiagnosticMarkBeginRun 500 DiagnosticMarkEndRun 500 DiagnosticOpenDocExtCheck 500 DiagnosticPayloadInstalled 500 DiagnosticSecurityCheckFileRead 500 DiagnosticSecurityCheckFileWrite 500 DiagnosticSecurityCheckRegistryRead 500 DiagnosticSecurityCheckRegistryWrite 500 dialog box about 395 accessing 395 action 441 adding 406 Admin Dialogs 396 backward compatibility 398 Windows Installer Editor Reference bitmap, adding 412 changing for language 280 condition, adding 384, 413 controlling display of 412 creating 406 displaying image 418 editing 402 fonts 410, 415 graphic, adding 414 help, adding 413 Install Dialogs 396 Maintenance Dialogs 396 making modal 405 name 404 position 404 previewing 398 properties 393 properties, editing 404 running action from 454 selecting 398 theme, see theme, dialog box translating 263 turning off all 399, 403 turning on, off 403 Welcome Dialog Wizard 396 WiseUpdate, customizing 293 dialog box control about 407 adding 404 aligning 416 Also see dialog box attributes 411 basic settings 409 centering 417 condition on event 385 condition, adding 384 condition, setting 413 disabling 384, 413 disappearance, preventing 416 editing 409 enabling 384, 413 event, setting 412 graphic, setting 414 help, adding 413 indirect 410 location on dialog box 410, 415 organizing 415 populating 414 properties 409 property, assigning 409 setting as default 413 sizing 417 spacing 417 state, setting 384 tab order, setting 418 text 409 tooltip, adding 413, 415 types 407 dialog control, see dialog box control dialog theme See theme, dialog box Dialogs directory 28, 45 Dialogs page 398 Dialogs tab 402 DIFx 71 DIFxAPP merge module 71 options 132 digital signature adding to installation 237 options 37 Digital Signature page 237 directories, installation resources 27 directory adding contents 114 changing 316 changing to virtual directory 248 creating 367 creating empty 367 default for installation 88 default for projects 45 excluding 192 filtering contents 46 filtering with wildcard 114 merge module 42 name, translating 272, 277 permissions, setting 125 predefined 108 renaming 106 searching for 168 setting with custom action 482 viewing for all features 41, 110, 115 directory combobox control 407 directory listbox control 408 DisableUAP 509 DiskPrompt 509 Display Message 468 distribution Also see Package Distribution preparing for 207 DLL file calling from destination 457 calling from installation 458, 461 calling from installed file 459, 462 debugging 454 preventing conflicts 374 sending parameters to 453, 460, 462, 462 shared DLL count 120, 372 Windows Installer method 453, 461, 462 document, open from installed file 477 documentation, Wise 14 dotNET See .NET dotnetexclude.xml 118 dotnetfx.exe 196 Download File From Internet 469 Download Redistributables 29 520 compiling to 190 editing the WiseScript 200 isolating with .DLL 374 outputting installation as 190 with .MSI 60 driver adding to Add/Remove Programs 132 installing 71 Driver Install Frameworks 71 driver package adding to Add/Remove Programs 132 installing 71 options 132 driver, ODBC adding 159 details 160 duplicate files 124, 125, 367 dyamic content 131 Execute Deferred 437, 440 Execute Immediate 437, 440 execute installation for testing 80 execute program from destination 470 from installation 471 from installed file 472 from path 472 ExistError 513 E edit field control 408 Edit Script button, enabling 200 elevated privileges 147 elevation for UAC about 176 Deferred Execution only 176 with an EXE wrapper 177 without an EXE wrapper 178 End Statement 470 environment variable adding 152 checking the value 389 path variable 314 reading 389 using in condition 385 error compile 24 component 24 in Components tab 370 in Task List 24 save 24 table 24, 380 validation 24 ErrorDialog 509 event dialog box control 412 macro 428 event macro about 429 adding 428 editing 428 exclusion, merge module 324 exclusions 193, 193 directory 192 file extension 192 Exclusions page 324 EXE file calling calling calling calling EXE wrapper 177 from from from from destination 470 installation 471 installed file 472 path 472 Windows Installer Editor Reference export to XML 76 ExpressBuild 38 extension adding 366 Also see first letter of the extension details 154 Extension table excluding extensions 192 F features about 492 adding 94 advertisement options 99 assigning component 364 attributes 98 checking if installed 390, 390 Complete feature 91 conditions, about 100 conditions, adding 383 configuring 95, 96 defaults, setting 179, 339 deleting 91 displaying to end user 98 features tree 91 including in media 211 installation location 98 installation options 95 installation state 482 moving 92 number in parentheses 23 organizing files 92 registry value, adding 140 requiring 100 selecting 22 selecting for release 187 target platform 97 Features page about 90 features tree 91 Features tab about 363 adding feature 94 adding file 110 showing, hiding items 363 tree structure 363 file .NET settings 127 adding from repository 113, 130 adding to installation 110 adding to source control 307 adding with wildcard 114 assembly settings 127 attributes, changing 123 checking in 308 checking out 309 checkout, undoing 310 checksum, validating 125 comparing 74 conditions, adding 383 conflict 137 copying on destination computer 122 details 123 duplicate 125, 367 extension, adding 153, 366 extracting from .MSI 353, 355 general details 124 hidden 124 inside .MSI 208 installation location, setting 120 isolating with application path 136 isolating with component 136 latest version, getting 309 location, changing 316, 317, 318 moving on destination computer 122 moving to resolve conflict 137, 138 multiple files, adding 114 name, changing 123 name, translating 272, 277 outside .MSI 208 path error 316 path, changing during compile 318 permissions, setting 125 preventing overwriting 120 read-only 124 recompressing 86 reinstall options 223 removing from destination computer 120 removing from source control 310 removing when invalid 357 resolving conflict with latest 137, 138 searching for 168 self-registration 125, 126 short file name 190 source directories 355 system file, designating 124 type, setting 154 updating from hard drive 86, 119 521 Win32 settings 127 file association actions 155 adding 153 command verb 155 extension settings 154 importing 154 MIME type 156 File Associations page 153 file extension excluding 192 excluding from Extension table 192 graphic adding to dialog box 414 referencing 101 stored in Binary table 381 updating 101 group box control 408 group, open from repository 73 GUID about 493 for components 51, 371 in universal transform 341 guidelines for creating installation 58 file in repository 113 H file name long 124 short 124 H file 276 file resources, shared 130 hash table 125 help about 14 adding to dialog box 413 Installation Expert 19 using 14 Windows Installer SDK 14 file, CAB (mobile device) about 216 adding 217 file, Palm OS about 219 adding 220 hidden file 124 FILEPATH1 199 history, showing for project 310 Files in Merge Modules 112 Files page about 105 adding directory 114 adding file 110 automatic updating 119 icons 109 viewing directories 41 when to use 107 filter added files 46 directories with wildcards 114 find error in installation database 381 Find table data 380 find text 440 fix component 137 folder See directory font, in dialog box theme 401 forums 15 function, macro showing 431 G GAC See Global Assembly Cache General Information page 89 Getting Started Guide 14 Global Assembly Cache defined 495 directory 108, 116 global dependency exclusions 118 Windows Installer Editor Reference Hide Empty Folders/Items 363, 368 HKEY_USER_SELECTABLE 147 HTTP Server, posting data 477 I icon folder with magnifying glass 115 on Features page 95 on Files page 109 setting on dialog box 411 Task List 24 icon control 408 If Statement 473 IIS details 252 installing to 242 required version, setting 166 restarting 244, 246 user for ASP 515 version 509 virtual directory, creating 246 Web folder, creating 248 Web site, creating 244 IIS dialog boxes adding 249, 251 changing order 402 do not edit 249, 251, 402 regenerating 249, 251, 402 IISVERSION property 509 image adding to dialog box 414 displaying on dialog box 418 immediate execution 487 immediate mode 440 import C# project 350 J# project 350 Visual Basic project 350 INF file, mobile device about 217 INI file build settings 512 creating 147, 148 editing 148 editing tips 148 in WebDeploy 202, 205 properties 512 searching 169 updating 147 INI Files page 147 In-Script Options 440, 486 Install Dialogs 396 install MSI from destination 473 from installation 474 from relative path 475 install/action state 388 installation adding SQL to 256 adding to source control 45, 306, 307 before you start 58 building 77 calling multiple 451, 473, 474, 475 compiling 77 compression 183 creating 69 creating from installed application 347 creation options 72 custom 98, 179 debugging 432 disconnected 77 displaying images during 418 execution of actions 432 installing for user 222 language, setting 362 localizing 263 media 207 multiple instances 343 multiple releases 181 opening a copy 77, 87 opening from repository 73 password, setting 191 pausing 477 previous directory, finding 172 reinstall options 223 restarting 222 rollback 223 running 80 server application 421 silent custom actions 443 source control compare 311, 311 terminating 484 522 testing 79 transform, applying 342 transform, changing with 339 translating 263, 266 turning off dialog boxes 399, 403 uninstall, avoiding 301 uninstalling nested 452 watching 347 Installation Expert about 18 Also see page groups help 19 navigating to 18 page groups 19 page navigation 19 resetting pages 19 undoing changes 19 installation log creating 175, 230 omitting property values 426 installation mode 437 installation sequence about 436 defined 440 types of actions 441 Installation Target 86 Installation Type dialog box 179, 397 Installation Types page 179 installation-on-demand 223, 224 INSTALLDIR 509 Installed property 386, 451 INSTALLLEVEL 97, 509 InstallMode 509 InstallTailor 339 instance identifier 343 instance transform about 343 creating 344 installing 345 product code 344 InstMSI CmdLine 513 InstMsi.exe 196 InstMsi3.exe 196, 205 InstMsiW.exe 196, 196 integer in condition 385 interface 17 Internet Explorer version 165 Internet Information Server See IIS Internet, downloading file 469 Internet-based installation 201 interoperable code 494 Also see COM interoperability IPF file converting to Windows Installer 348 isolated component 136 Windows Installer Editor Reference isolation using application path 136 using component 136, 374 with Win32 assembly 128 launch condition about 361 creating 166 editing 167 Item Field, in .INI 170 Launch Web Page 476 launch Windows Installer Editor 16 J J# importing 350 project types 349 tips for import 349 JScript calling from embedded code 463 calling from installation 463 calling from installed file 464 calling from property 465 guidelines for calling 452 K key fields 377 key path about 374 conflict 137 for components 372 setting 374 Key Table 333 Knowledgebase 15 layer See virtual layer Layout menu 402 License dialog box, importing text 401 License Management Portal 15 line control 408 line, inserting blank 478 listbox control 408 populating 414 Listbox Compatibility Mode 42 listview control 408 localization See language or translation location for custom action 451, 484 for merge module actions 485 Location tab 439, 439 lock directory 125 file 125 registry 146 L language adding 269 Also see translation default for release 282 default, changing 281 defining 271 disabling in installation 268 exporting selected strings 276 multiple-language release 184 pre-translated 284 removing from installation 268 restoring to installation 269 selecting at run time 184 selecting for display 281 setting for installation 362 sharing between releases 267 strings, See text strings transform, creating 266 language ID list 285 setting 271, 274 Language menu, using 281 Language property 513 LanguageFile 513 Languages directory 28, 45 Languages page 263 latest file version, getting 309 latest file, selecting to resolve conflict 137, 138 log file, command line 236 log, installation See installation log logging option, in command line 175, 230 Logon Information dialog box adding 421 guidelines 422 M macro adding for event 428 creating 428 editing 428 event 429 running 429 Macro Editor functions, viewing 431 members 430 objects, viewing 431 showing all macros 431 syntax, checking 431 using 430 macro file renaming 428 samples 427 Macros.wbs 427 Maintenance Dialogs 396 maintenance mode 194 523 MaintenanceMode 510 Merge Modules page 334 managed code 494 message, display to end user 468 manifest creating for Win32 128 defined 495 file 128 meta data adding to Software Manager database 86 defining fields 83 editing 83, 87 entering 83 rearranging 83 manual, reference 14 manufacturer property 510 setting name 84 masked edit control 408 MDAC merge module 423 media creating 208 deleting 208 destination 210 example 213 sharing settings 212 size 209 metadata See meta data Microsoft .NET See .NET Microsoft Internet Information Server See IIS Microsoft SMS converting to Windows Installer 348 installation, creating 238 Media page 207 Microsoft SMS page 238 merge module 32-bit 65 64-bit 65 about 320 action location, choosing 485 add to feature 336 adding 112, 335 adding features 321 CondFix.msm 386 configurable 321 configuring 336 creating as new installation 325 creating from components 326 custom action 33 dependency, adding 323 directory for downloads 336 directory, default 28, 42 downloading from Web or CD 29 exclusion, adding 324 exporting components 327 extracting from .MSI 353, 353 from Software Manager database 43 language, setting 322 naming 322 naming custom action 485 options 42 predefined 29 project file 59 removing 336 running 81 settings 337 showing files and registry entries 42 source directory 353 substitution 328 suppressing errors 34 template 47 testing 80 version, setting 322 Microsoft SQL Server See SQL Server Windows Installer Editor Reference Microsoft Transaction Server 260 Microsoft Visual SourceSafe 307 Microsoft Windows Mobile See Windows Mobile MIF file 238, 238 MIME type, associate with extension 156 minimum installer version 362 minimum system requirements See system requirements mixed installation 35, 85 mobile device installation about 216, 219 Also see Palm OS installation Also see Windows Mobile installation process for adding 216 Mobile Device Package Editor about 216 adding to source control 306 compression 183 contains files 208 converting to .WSI 352 creating 69 defined 59 installing into an SVS layer 191, 192 ways to create 61 working with 60 MSI installed into an SVS layer about 192 maintenance mode 194 modifying 194 removing 194 repairing 194 resetting 194 MSI Script about 436 custom tab 442 finding text 440 shaded areas 442 standard tab 442 window 437 MSI to WSI Conversion about 352 running 352 msiexec.exe 491 MsiFileHash table 125 MSM file Also see merge module defined 59 MSP file Also see patch defined 59 MST file Also see transform defined 59 for languages 266 MTS/COM+ page 260 multifile assembly 115, 495 multiple-language release 184 MYPASSWORD 421 Mobile Devices page about 215 adding Palm OS files 220 adding Windows Mobile files 217 N Module Details page 322 NalpLaunchCA 500 Module tab 321 NalpRemoveLicense 501 ModuleDependency table 324 NalpRemoveLicenseSetProp 501 ModuleExclusion table 325 name of product 84 Modules icon 365 navigate between views 18 Move Components to Merge Module 327 nested installation on destination computer 473 relative to base 475 substorage 474 tips for running 451 uninstalling 452 move file on destination computer 122 move file to resolve conflict 137, 138 MSI Download URL 205 MSI file about 60 MYUSERNAME 421 524 NET See .NET New button, unavailable 23 New event macro 429 new features Refer to Release Notes Package Validation about 356 Also see validation page See Installation Expert page count 362 New Installation File 69 page groups 19 New Language wizard 270 page views about 20 creating 21 customizing 21 displaying 21 predefined 20 selecting 19 sharing 21 template-specific 20 normal installation mode 438 no-touch deployment 258 NT download URL 205 O object list 431 ODBC page 159 ODBC SQL Server driver 423 ODBC, adding 159 ODBC.INI, update 147 Palm add-on folder about 219 installing to 221 missing 357 relative paths 317 UNC paths 318 path edit control 408 path variable environment 314 registry 314 turning off 313 user defined 313 Path Variables page 312 path, application 136 Pause Installation 477 PCP file Also see patch defined 59 PDB file 219 PDF (Package Definition File) 238 per-machine installation 222 Open event macro 429 Palm OS about 219 file, adding to installation 220 wizard 220 permissions directory 125 file 125 registry 146 operation copy file 122 move file 122 remove file 120 Palm OS installation about 219 Also see mobile device installation uninstalling 220 Personal Information Exchange file 237 options .NET assemblies 34 about 32 advertising 36 digital signature 37 general 33 Installation Expert 41 merge modules 42 prompts 43 repository 44 resource sharing 44 software virtualization 34 source control 45 Palm user folder about 220 installing to 221 PIDTemplate 510 osql.exe 423 patch about 302 Also see Patch Creation applying to installation 234 creating 77 description 300 file 59, 59 preparing for 302 project file 59 removing from installation 234 when to use 300 Open Document From Installed File 477 overwriting, preventing 120 P package name 84 opening from repository 73 overwriting 77, 87 path 85 package code 362 changing 85 Package Contents by Feature report 28 Package Contents Summary report 28 Package Definition File (PDF) 238 Package Distribution about 287 Also see the Wise Package Studio help Windows Installer Editor Reference Palm User Information dialog box 220, 397 parameters sending to .DLL 453, 462, 462 parent feature 97 parsing 444 password for installing 191 obtaining 421 Patch Creation about 302 per-user installation 222 PFX file 237 platform (32-bit or 64-bit) See target platform Pocket PC See Windows Mobile installation PopulateVirDirs 501 Post Data to HTTP Server 477 PQA file 219 PRC file 219 preferences See options prerequisites .NET Framework 195 adding 195 command line 198 file, adding file 197 launch conditions 198 requiring a reboot 198, 200 runtimes 199 Windows Installer 195 Prerequisites page about 195 enabling 195 PRIMARYFOLDER 510 Patch Wizard See Patch Creation private assembly 116, 495 path Also see source path broken 315, 357 changing directories 316 invalid 315, 357 private key 38, 238 private directory 136 private key file 237 privileges elevated 147 setting for custom actions 440 525 setting in debugger 434 using in condition 383, 385 value, checking 388 viewing in debugger 433 product name 84 type 84 version, See version product code in instance transform 344 setting 85 upgrading 301 properties for dialog box event 412 help 413 Product Details page 83 Property table 435 Product tab 361 ProductFile 514 public property changing with command line 233 setting in debugger 434 ProductID 510 Public/private key pair 237 ProductLanguage 510 published component, adding 375 ProductName 510, 514 published event 412 ProductVersion 510, 514 PVK file 237 profile installing for 222 Q ProductCode 510, 514 Program Files (x86) 108 progress bar control 408 progress text translation 512, 514 project file connecting to existing 306 creating 69 merge module 59 multiple platforms 66 patch 59 Windows Installer 59 working with 60 Properties icon 361 QueryDisplayValidation event macro 429 QueryFixValidation event macro 430 quick compile 34, 78 Registry page 138 registry path variable 314 registry resources, shared 147 reinstall options 223 rechecking conditions 120 specify source 224 when to use 300 ReinstallFileOlderVersion 510 ReinstallFileVersion 510 ReinstallRepair 510 relative paths, convert to 317 red component icon 370 release about 181 compiling 182, 184 components, selecting 187 creating 182 customizing 185 example 189 features, selecting 187 multiple languages 184 selecting 23 sharing language settings 267 sharing settings 188 subdirectory 183 target platform 184 WSI file only 181 redistributables, download 29 release notes 14 reference action 486 Release Settings page components, selecting 187 customizing release 186 customizing summary 187 features, selecting 187 sharing settings 188 working with 185 R radio button control 408 populating 414 readme See release notes Project Summary page 83 Readme dialog box, importing text 401 prompt options 43 read-only file 124 properties about 391 accessing from custom action 454 adding new 186 as Boolean value 385 as formatted text 393 build 508 common uses 392 creating 394 custom action 486 defined 391 definitions 508 for dialog box control 409 how they are set 391 INI file 512 initializing 391 masking user entry 426 overriding value 186 precedence 392 prompting user for value 425 reference 508 restricted public 394 run time 392, 515 set by user 392, 392 set by Windows Installer 392 set with custom action 483 setting for admin install 225 REBOOT property 393 Windows Installer Editor Reference permission, adding 146 reinstall options 223 removing entry from destination computer 142 removing multiple keys 143 searching 171 value, adding 141 viewing all keys 41 viewing for all features 140, 142 WOW6432Node 64 reboot, setting options for 222 reference manual 14 referencing graphics 101 Refresh column 103 REG file exporting 143 importing 143 register software 15 registry 32-bit or 64-bit view 140 data type 146 empty key, adding 140 exporting 143 for elevated privileges 147 for multiple users 147 importing 143 key, creating 140 key, editing 144 locking 146 per machine 147 per user 147 Releases page 181 remark action 478 remarks, adding to .MSI 33 remove from destination computer file 120 registry entry 142 remove missing files 357 Remove Previous 514 REMOVE property 386, 386 repair option, in command line 232 repair, failing 222 Replace table data 380 526 reports package contents 28 resource sharing 27 repository ID 85, 87 rescan advertising info 37 reset page 19 resolution (screen) requirement 165 resolution rules, for conflicts 135 resolve conflicts about 134 automatically 135 fixing component 137 individually 136 moving file 137, 138 using latest file 137, 138 with Resolve Wizard 136 with rules 135 Resolve Wizard 136 resource directories 27 exporting 102 resource sharing locations 44 options 44 reports 27 Resources directory 28, 45 Resources page 101 Restart Manager, enable 174 restart, setting options for 222 restricted public properties 394 revision control, Software Manager 305 revision number 362 rollback options 223 script 440 rollback only 487 rule See component rules rule set, component copying 53 creating 52 deleting 53 modifying 53 renaming 53 selecting 50 where stored 49 Run button, popup 81 Run event macro 430 run installation changes not saved 81 how to 80 in virtual layer 80 with command line 81 run time properties 392, 515 Windows Installer Editor Reference Run WiseScript example 444, 445, 446 from destination 479 from installation 479 from installed file 481 runtime downloading from Web or CD 29 evaluating conditions 433 runtime prerequisite, add 199 RuntimeNT 514 runtimes 199 RuntimeVersion 514 S save as XML 76 save error 24 Save event macro 430 scan excluding dependencies 117 for dependencies 116, 240 problems 36, 117 SCCS See source control scheduling options 488 schema.msi 341 restricted areas 442 searching 440 types of actions 441 server logon information 421 SQL, configuring 254 server application 421 service adding 156 configuring 157 deleting from destination computer 158 starting 158 stopping 158 Services page 156, 156 Set Directory 482 Set Feature State 482 Set Property 483 SetARPINSTALLLOCATION 501 SetPatchMode 501 SetPatchReinstallMode 501 Setup Editor about 359 navigating to 18 tabs 360 screen colors requirement 165 resolution requirement 165 Setup.dll, mobile device 216 ScreenX property 384 SetWizardProperty1 501 ScreenY property 384 share point directory changing default 44 connecting to 44 subdirectories 27 scrollable text control 408 search depth 168 search for text 440 Search Locations page 224 search table data 380 SecureCustomProperties 510 security achieving with WiseScript 445 for file or folder 125 importing .NET Framework settings 258 Select Feature dialog box 397 select package from repository 73 selection tree control 408 self-registration 125 adding automatically 37 how captured 133 setting for files 126 self-repair, specify source 224 sequence, installation about 436 adding action 442 choosing for action 484 colors of actions 441 commenting out line 443 how they are run 440 inserting blank line 478 SetupCapture event macro 430 SetWizardProperty 501 shared .DLL counter not set 137 shared assembly 116 Shared Files report 27 Shared Registry report 27 shared resources file 130 registry 147 shortcut adding to installation 150 advertised 150, 223 editing 151 reinstall options 223 shortcut, mobile device 218 Shortcuts page 149 side-by-side sharing 116, 495 signcode.exe 237 signtool.exe 237 silent compile 236 silent installation calling WiseScript 443 SLN file 349 Smartphone See Windows Mobile installation 527 replacing text in 258 SMS Also see Microsoft SMS Software Manager 347 software registration 15 software virtualization options 34 source control about 305 adding project 306, 307 checking files in 308 checking files out 309 checkout, undoing 310 comparing to latest 311 connect to existing 306 differences, showing 311 disabling 45 enabling 45 getting latest version 309 history, showing 310 of XML files 306 removing files 310 System.ini, update 147 standard tab, in MSI Script 442 T standard user installation about 70 creating 70 Start menu, add shortcut 150 start Windows Installer Editor 16 status MIF file 238 status, package 87 string Also see text strings using in condition 385 strong name 116 subscribed event 412 source directory See source path substitution value 328 source file location, changing 316 relative paths 317 UNC paths 318 summary items about 362 overriding 187 setting value 362 source path about 315 broken 315, 357 changing 316 changing during compile 318 converting 315 file 355 invalid 315, 357 merge module 353 missing 357 relative 317 specifying 224 UNC-based 318 registry 171 standard action Also see custom action color 441 deleting 441 restrictions on placement 442 Substitutions page 328 support Altiris Support Helpdesk 15 forums 15 Knowledgebase 15 user groups 15 Support Information Page 90 suppressed prompts, activate 43 Systems Management Server See Microsoft SMS SysWOW64 108 tab order for controls 414 on dialog boxes 418 table added by Wise 504 adding row 379 creating 378 deleting 380 deleting row 379 editing binary data 381 editing table data 379 field definition 378 finding errors 380 searching 380 searching in debugger 435 showing/hiding 377 temporary 435 viewing in debugger 433 table error adding to Task List 24, 380 finding 380 finding from Task List 26 Tables tab about 376 column information 377 comparing installations 311 viewing 377 source tree relative to base 475 SVS layer excluding user data files 193 installing MSI 191 maintenance mode 194 removing 194 resetting 194 source type 362 synchronous, defined 488 SpaceError 514 syntax, check macro for 431 target platform about 61 default 17 feature 97 release 184 specifying 62 SPC file 237 SYS file 156 task SQL Client Tools 423 system context 440, 487 SQL Connection dialog box about 397 adding 423 adding multiples 424 guidelines 423 modifying 424 using 422 system directory 108 SQL connection string 423 System Requirements page 164 SQL Server configuring 254 connecting to 256 setting required version 165 system requirements, Wise product Refer to Getting Started Guide SQL Server Scripts page 254 SQL statements adding to installation 256 Windows Installer Editor Reference system file, designate file as 124 system requirements about 164 adding conditions for 384 setting in Installation Expert 164 setting with launch condition 166 System Search page .INI file 169 about 167 file or directory 168 installed component 172 target computer See destination computer adding 24 component 24, 380 save, compile 24 table 24, 380 user-defined 26 validation 24 Task List about 24 adding tasks 24 component error 24 filtering 25 finding table errors 26 icons 24 resolving issues 24 save, compile error 24 table error 24, 380 user-defined task 26 528 images 400 no graphics 400 none 400 predefined 399 validation issue 24 technical support Altiris Support Helpdesk 15 forums 15 Knowledgebase 15 user groups 15 template about 47 creating 47 import Visual Basic 350 import Visual C# 350 import Visual J# 350 language 281 location 47 page view 20 page view, associating 20, 48 page view, customizing 21, 48 server application 421 Template Summary property setting 62 viewing 62 Templates directory 28, 45, 47 temporary table 435 Terminal Services compatibility 183 Terminate Installation 484 test installation 79 merge module 80 transform 80 Test button about 79 avoiding popup 79 Test event macro 430 text box dialog box control 408 resizing for language 280 text strings Also see language exporting all 271 exporting selected strings 276 importing all 272, 273 importing selected strings 277 pre-translated 284 tracking changes 283 translating changed 275 translating in Installation Expert 279 translating in Language Strings dialog box 278 translating in SetupEditor 279 translating without exporting 278 Text Translated 264 theme, dialog box adding 400 backward compatibility 400 changing 399 changing per release 183 editing 400 fonts 401 Windows Installer Editor Reference Themes directory 28, 45, 401 running action during 451 setting options 89 Windows Mobile application 217 WiseScript 446 toolbar for dialog boxes 402 Universal Access Protection See User Account Control (UAC) tools overview 346 starting 346 universal transform added GUIDs 341 creating 341 tooltip for dialog box 413, 415 unmanaged code 494 transform about 338 applying in Debugger 434 applying to installation 234, 342 applying, example 342 based on existing .MSI 339 creating for language 266 creating from installation 339 example 338 excluding files 339 file 59 generic 341 including files 339 meta data, changing 83 multiple instances 343 options for creating 338 options, setting 340 running 81 suppressing errors 340 testing 80 universal 341 update based on wildcards 46 TransformMSI 514 Upgrades page 302 translation Also see language compiling to .MSI 265 compiling to language transform 266 of progress text 512, 514 of user interface 263 strings, See text strings UpgradeSync 302 translator, ODBC adding 159 details 161 tutorial Refer to Getting Started Guide typical installation 179 upgrade about 302 adding to installation 303 aligning component GUIDs 51 archiving previous 300 avoiding uninstall 301 configuring 303 description 300 errors, avoiding 302 further reading 299 general steps 299 guidelines 303 patch or upgrade 300 preparing for 302 product code, changing 301 product version, changing 301 when to patch 300 when to reinstall 300 UpgradeCode 303, 510 User Account Control (UAC) about 176 disabling 70, 174 enabling 174 preventing in WiseScript custom action 448 user context 440 user data files excluding 193 user defined path variable 313 user groups 15 User Information dialog box 397 User Interface 437, 440 U user name, obtain 421 UAC See User Account Control (UAC) UNC paths 318 undo check out 310 Installation Expert page 19 uninstall avoiding 301 failing 222 leaving components installed 120 Palm OS application 220 user, install for 222 user-defined task 26 UserSID 454 V validation errors in tables 380 issue in Task List 24 Validation directory 28, 45 value source, for parameter 461 variable parameters 462, 462 529 VBImport event macro 430 volume combobox control 408 VBP file 349 volume cost listbox control 408 VBPROJ file 349 VXD file 156 VBR file 138 VBScript calling from embedded code 466 calling from installation 466 calling from installed file 467 calling from property 468 debugging 434 guidelines for calling 452 vendor redistributables, download 30 version changing 84 incrementing on compile 86 of product 84 upgrading 301 when to update 87 Windows Installer 89 Version9X property 100 VersionNT property 100, 385 ViewLog 501 views 17 Virtual Directories page See Web Files page virtual directory changing to Web site 248 child 246 choosing dialog boxes 249, 250 creating 246 details 252 editing web.config 131 how options are set 247 IIS 7.0 support 247 installation options 249, 250 removing on uninstall 247 top-level 246 virtual layer deleting installation 81 running installation in 80 virtualization options 34 Vista standard user installation about 70 creating 70 Visual Basic editor 430 importing 350 project types 349 tips for import 349 using in macro 428 Visual MSIDiff key to icons 75, 311 using 74 with source control 311, 311 Visual SourceSafe 307 Visual Studio project importing 350 VJSPROJ file 349 Windows Installer Editor Reference W WBS file 427 Web dialog boxes adding 249, 251 changing order 402 do not edit 249, 251, 402 regenerating 249, 251, 402 Web Files page 242 about 105 when to use 107 Web folder creating 248 details 252 Web installation choosing dialog boxes 249, 250 creating virtual directory 246 features that support 243 installing settings from file 253 Web settings XML file 253 Web page open from installation 476 Web server version 509 Web settings XML file 253 Web site changing to virtual directory 245 choosing dialog boxes 249 creating 244 details 252 how options are set 245 IIS 7.0 support 245 installation options 249 installing on workstation 250 installing settings from file 253 web.config 131, 245, 247 Web-based installation 201 WebDeploy about 201 creating installation 204 process overview 203 setting options 204 tips 204 uploading installation 206 using with Autoplay 202 versus non-WebDeploy installation 201 WebDeploy page 204 wildcard adding files with 114 changing 119 filtering directories 114 groups 46 WIN.INI, update 147 Win32 assembly creating 128 isolating 128 Windows 2000 locked-down machines 394 service, adding 156 service, controlling 158 support information 90 Windows application, create installation 69 Windows directory, add file 108 Windows Installer about 490 actions 441 comparing files 74 compatibility with 89 database 59 database files 60 delaying restart 197 developer documentation 14 help 14 how it works 490 Installer directory 491 package, defined 59 pre-installing 195, 205, 491 pre-installing 3.0 196 project, defined 59 properties 222 repairing feature 92 required version 89 setting required version 165 Windows Installer Options page 174 Windows Installer SDK Help 14, 490 Windows Installer service 440 Windows Mobile about 216 Windows Mobile installation about 216 Also see mobile device installation CAB file 216 INF file 217 Setup.dll 216 uninstalling 217 Windows Mobile wizard 217 Windows NT locked-down machines 394 service, adding 156 service, controlling 158 setting required version 165 Windows On Windows 64 64 Windows XP service, adding 156 service, controlling 158 Windows, required version 165 Winnt directory, add item 108 WinSxS 108, 116 Wise Automation 427 Wise custom actions about 498 documenting 498 530 Wise Installation System See WiseScript Editor WiseInitPrefix 511, 514 WiseSequence table 506 WiseInitProductName 511 Wise options See options WiseInitProgressText 512, 514 WiseSetAssemblyFrameworkPropertie s 502 WiseInitSpaceError 512 WiseSetFirewall 502 WiseInitSuffix 512, 515 WiseSingleFileCheck 502 WiseLangString table 505 WiseSourcePath table 506 WiseLanguage table 505 WiseSql1.sql 255 WiseLaunchCondition table 505 WiseSQLCallDLL 502 WiseMaskedProperties 512 WiseStartup 502 Wise Standard.msi 406 WiseMediaOptions table 505 WiseStreamFiles table 506 Wise tables 504 WiseMetaDataCache table 505 WiseTaskList table 506 Wise Task Manager Refer to Wise Package Studio help WiseMobileDevice table 505 WiseTestSqlConn 503 WiseTextReplacement table 506 Wise textreplacementinit 501 WiseMobileDeviceDesktopFiles table 505 Wise textreplacementmodify 501 WiseModuleConfiguration table 505 WISE_SQL_CONN_STR 423, 516 WiseModuleSignature table 505 WiseAdvertising table 504 WiseNextDlg 502 WiseAltStartup 501 WisePageLists table 505 WiseCleanup 501 WisePathReplacement table 505 WiseComCapture.exe 133 WisePathVariable table 505 WiseCommandLine table 504 WisePocketPCFile table 505 WiseComPlusApp table 504 WisePocketPCPlatform table 505 WiseComPlusComponent table 504 WisePocketPCRegistry table 506 WiseCRLF 510 WisePrerequisites table 506 WiseCustomActionDoc table 504 WisePrevDlg 502 WiseDebugMode 508 WiseRegComPlusAddRemove 502 WiseDialogFontDefault 508 WiseRegComPlusInit 502 WiseDialogSuffix 508 WiseRelease table 505, 506 WiseDialogTitleFontDefault 509 WiseReleaseExclude table 506 WiseUpdate about 287 client 287, 295 configuring 290 dialogs, customizing 293 INI file 292 log 292 process 289 running from a shortcut 295 running from application 296 running silently 296 testing 294 tips 296 troubleshooting 297 update file, about 292 updating file 291 uploading, FTP client 294 using 290 using with WebDeploy 296 WiseDlgSequence 504 WiseReleaseMedia table 506 WiseUpdate page 287 WiseDynamicXmlModify 501 WiseReleaseMediaDest table 506 WiseUpdt.exe 295 WiseFeatureCondition table 504 WiseReleaseMediaInclude table 506 WiseUpgradeCheck 503 WiseFileAttributes 504 WiseReleaseOverride table 506 WiseUpgradeCheckEx 503 WiseFileHash table 504 WiseRemoveFirewall 502 WiseVDAttributes table 506 WiseFindSqlClientTools 501 WiseRuntimeVar table 506 WiseVersionInfo table 506 WiseFirewallInfo 501 WiseScript calling 443 calling from destination 479 calling from installation 479 calling from installed file 481 editing from Prerequisites page 200 example 444 failure on Vista 448 manifest for run level 448 parsing path 444 resetting from Prerequisites page 201 security 445 silent installation 443 uninstalling 446 WiseVirtDirCallDll 503 WiseScript Editor 443 word count 362 Wise PocketPCShortcut table 506 Wise Software Repository adding files from 113, 130 connecting to 44 default, changing 44 options 44 WiseFirewallSetup table 505 WiseFixConditions merge module See CondFix.msm WiseGetASPNETUser 501 WiseGetDotNetVersion 501 WiseGetIEVersion 502 WiseGetIISFeaturesEnabled 502 WiseGetIISVersion 502 WiseGetSQLServers 502 WiseGetSQLServerVersion 502 WiseIISValidateInput 502 WiseInitAdminError 511 WiseInitCmdLine 511 WiseInitExistError 511 WiseInitLangDefault 511, 514 WiseInitLangPrompt 514 Windows Installer Editor Reference WiseScript Express See WiseScript Editor WiseScript Package Editor 443 WiseVirtualDirectory 506 WiseVSDropFile 507 WiseVSOutput table 507 WiseVSOutputGroup table 507 WiseVSProject table 507 WiseWebSiteAttributes 507 WiseWebSites 507 WiseWildcard table 507 WiseWildcardFile table 507 WiseWriteWebXMLDll 503 wizard See tools wizard dialog boxes 396 WOW64 64 WOW6432Node 64 531 wrapper, EXE 177 WSI file creating 69 defined 59 multiple platforms 66 working with 60 WSM file Also see merge module defined 59 wwwroot 242 X XML format installation about 76 create during save 33, 76 exporting to 76 integrating with source control 306 XML, edit attributes 131 Windows Installer Editor Reference 532