Installation Cleanup Utility Reference
Introduction (You can also refer to the control flow attached)
The Installation Cleanup Utility (cleanup.exe) is a data-driven tool that associates a set of actions with a set of products and performs the actions for a specific product when the user chooses a product. It is intended to perform actions that will manually uninstall a product that is in a broken state on a user’s machine, but since it is data-driven it can be made to do many different things if desired.
Logging
The tool generates three log files in the temporary folder on the computer that it is run on:
· %temp%\Cleanup_main.log – this log lists all standard event log messages, warnings and errors; if the file already exists, the tool will append a session delimiter and add to the existing file
· %temp%\Cleanup_errors.log – this log lists only warnings and errors; if the file already exists, the tool will append a session delimiter and add to the existing file
· %temp%\Cleanup_actions.log – this log lists each directory, file, registry key/value, and MSI product code that the tool finds and removes and any services that it stops; this log is intended to make it easier to investigate root causes of setup problems by consolidating all data that is removed into a single location so that we can parse it later; if the file already exists, the tool will append a session delimiter and add to the existing file
Supported Platforms
The tool is designed to work on all versions of Windows starting with Windows 95. This includes Windows 95, Windows 98, Windows ME, Windows NT 4.0, Windows 2000, Windows XP, Windows Server 2003, Windows Vista, Windows Server 2008 and beyond. It is a Unicode application and includes the unicows.dll wrapper so that it will work on ANSI operating systems such as Windows 95, 98 and ME.
It is written to have no dependencies outside of the files that are packaged with it. This means that there is no installation program for the tool and there is not a dependency on components that are not included with the supported operating systems themselves.
Command Line Switches
The Installation Cleanup Utility supports the following command line parameters:
· /p [Product Name] – this switch allows the user to specify a product name and silently perform the cleanup activities associated with it; no UI will be displayed to the user; the product specified by [Product Name] must exactly match one of the products listed in cleanup.ini
· /u – this switch will cause the cleanup tool to run in unattended mode instead of silent mode; this means that a progress page will be displayed, but no other UI will appear and no user interaction is required; the user must also provide the /p switch in order to run in unattended mode
· /? – this switch displays a dialog box that tells the user what command line switches are available for the tool
The following example demonstrates how to run the Installation Cleanup Utility in silent mode:
cleanup_tool.exe /q:a /c:"cleanup.exe /p <name of product to remove>"
The following example demonstrates how to run the Installation Cleanup Utility in unattended mode:
cleanup_tool.exe /q:a /c:"cleanup.exe /p <name of product to remove> /u"
Exit Codes
The Installation Cleanup Utility can return the following exit codes:
- 0 - cleanup completed successfully for the specified product
- 3010 - cleanup completed successfully for the specified product and a reboot is required to complete the cleanup process
- 1 - cleanup tool requires administrative privileges on the machine
- 2 - the required file cleanup.ini was not found in the same path as cleanup.exe
- 3 - a product name was passed in that cannot be removed because it is a part of the OS on the system that the cleanup tool is running on
- 4 - a product name was passed in that does not exist in cleanup.ini
- 100 - cleanup was able to start but failed during the cleanup process
- 1602 - cleanup was cancelled
INI File Format Rules
The file cleanup.ini controls what products the user can choose to manually remove, and also tells cleanup.exe what actions to perform for each product. Lines that begin with an apostrophe are treated as comments and ignored by cleanup.exe. The following rules describe each of the sections in cleanup.ini.
[Products] section
· Mandatory section
· ProductCount value is an integer number of products
· Product1, Product2, …., ProductN are names of products that the user can select to remove; these names are displayed in the dropdown UI that the user sees
· Each product name should have its own section with actions to perform
· Products can be conditioned to allow cleanup only on certain operating systems. Adding a name/value pair to an action section with the format Product#_OS and containing one or more valid operating system conditions (see below for the syntax for the conditions) will cause the tool to only include the specified product in the selectable list of products in the UI on the specified operating systems and dynamically skip it otherwise
· Supports the following additional optional values:
o DefaultIndex – specifying this value will cause the product name at the chosen index in the drop-down list box to be selected by default in the UI; omitting this value will cause the product name at index 0 to be selected by default in the UI
Note – the Product values are numbered starting with 1 in the INI file, but the index into the drop-down list box starts at 0 and is based on alphabetical ordering of the product names; the DefaultIndex value needs to be set with these criteria in mind in order to cause the desired product name to be selected by default; if you plan to use DefaultIndex, it is easiest to specify each of the Product values in alphabetical order so you can more easily tell which product will end up at which index in the UI
o LogNetfxInstallState – specifying this value and setting it equal to 1 will cause the Installation Cleanup Utility to detect whether or not each shipped version of the .NET Framework is on the user’s system and report the install state in the log file; omitting this value or setting it to a value other than 1 will cause this detection and logging to be skipped
o WindowTitle – this will set the title of the main UI window for the Installation Cleanup Utility; omitting this value will set the window title to the default value “Installation Cleanup Utility”
[Product Name] section
· There should be one section per product listed in the [Products] section; the name should match exactly with the names in the [Products] section
· ActionCount is an integer number of actions to perform for the product
· Action1, Action2, …., ActionN are actions that will be performed for the product
· Actions are performed in sequential order
· Each action should have its own section with items to perform the action on
· Actions can be conditioned to run only on certain operating systems. Adding a name/value pair to an action section with the format Action#_OS and containing one or more valid operating system conditions (see below for the syntax for the conditions) will cause the tool to only run the specified action on the specified operating systems and dynamically skip it otherwise
· Optional value RepairWindowsInstaller can be included for any of the products; setting the value to 1 will cause cleanup.exe to run msiexec /unregister and then msiexec /regserver before performing any of the actions; this step will not be run on Win9x OSs because msiexec is not a service on Win9x; this step will not be run if Windows Installer is detected as not installed; if this value is not equal to 1 or is omitted, the unregister/reregister will not be performed
· Optional value AllowCancel can be included for any of the products; setting the value to 1 will cause cleanup.exe to enable the cancel button during cleanup and allow the user to abort cleaning up this product without letting the process run to completion; this can be dangerous to a user’s machine, so it should be used with caution; if this value is not equal to 1 or is omitted, cleanup.exe will gray out the cancel button while cleanup is in process
· Optional value CreateSystemRestorePoint can be included for any of the products; setting the value to 1 will cause cleanup.exe to create a new system restore point before performing any cleanup actions so that users can revert their machine to the state prior to cleaning up; the system restore point will be created only on operating systems that support them (Windows ME, Windows XP and later) and only on operating systems where system restore is enabled; if this value is not equal to 1 or is omitted, the cleanup tool will not attempt to create a system restore point
[Action] section
· Action sections must begin with specific prefixes that are known and understood by cleanup.exe:
1. “Directories – “ – this section lists directories that should be recursively deleted by cleanup.exe; in use files will be marked to be deleted after the next reboot; folder names can be tokenized using INF-style syntax (see below for tokens that are understood by cleanup.exe)
2. “Files – “ – this section lists files that should be deleted by cleanup.exe; in use files will be marked to be deleted after the next reboot; the full path to the file should be provided; folder names can be tokenized using INF-style syntax (see below for tokens that are understood by cleanup.exe)
3. “Registry – “ – this section lists registry keys and/or values that should be deleted by cleanup.exe; registry roots should use their 4 letter abbreviations (HKCR, HKCU, HKLM, etc), then be followed by a comma, then the name of the registry key to be deleted, then optionally a comma and the name of the value to be deleted; if no value is specified then cleanup.exe will recursively delete all subkeys and values under the key that is provided
4. “Product Codes – “ – this section lists Windows Installer product codes that should be removed as part of the cleanup; for each product code, cleanup.exe will query whether or not the product is installed using MSI API calls; if so, it will remove it using msiexec /x; then, regardless of whether or not it is installed, it will use msizap.exe to remove Windows Installer registry information for the product code; the timeout value for running msiexec /x for each product codes can be customized by adding an = sign and a numerical value in milliseconds; setting the value to -1 will cause the timeout to be infinite; the default timeout value if none is specified is 15 minutes for each product code
5. “No Msizap Product Codes – “ – this section lists Windows Installer product codes that should be removed using msiexec /x as part of the cleanup but that we should not run msizap to remove; for each product code, cleanup.exe will query whether or not the product is installed using MSI API calls; if so, it will remove it using msiexec /x; the timeout value for running msiexec /x for each product codes can be customized by adding an = sign and a numerical value in milliseconds; setting the value to -1 will cause the timeout to be infinite; the default timeout value if none is specified is 15 minutes for each product code
6. “Stop Services – “ – this section lists services that should be stopped on the machine; these could be services that hold files in use that need to be deleted or services that are installed as part of a product setup that we want to stop
7. “Custom Action – “ – this section lists custom action processes that should be run on the machine; parameters for the custom actions are described in the [Custom Action] section below
· Actions sections can be shared across multiple products by including the name of the action section in the list for any applicable products
· Valid directory/file tokens are the following:
1. %10% - Windows directory; example – c:\windows
2. %11% - system directory; example – c:\windows\system32
3. %16422% - Program Files directory – c:\Program Files
4. %16427% - Common Files directory – c:\Program Files\Common Files
[Custom Action] section
· Each custom action listed in the [Action] sections must have a section that contains the parameters that will be used to run the action
· The [Custom Action] sections use standard INI file format, so each entry in the section must follow the format of <parameter>=<value>
· Supported parameters for the [Custom Action] section include the following:
1. “ExecutablePath“ – this parameter specifies the full path of the custom action executable to run; this value allows tokens such as %10%, %11%, etc; this parameter is mandatory, so if an executable path is not specified the action will be skipped and an error logged by the cleanup tool
2. “CommandLineParameters” – this parameter specifies any command line parameters that will be passed to the executable listed in the ExecutablePath parameter; command line parameters are optional, and if none are provided the executable will be launched with no arguments
3. “FriendlyName” – this specifies the name to display in the cleanup tool progress UI while the action is running; this parameter is optional and if no value is provided, the cleanup tool will default to displaying the executable path
4. “WorkingDirectory” – this parameter provides a working directory path to pass to CreateProcess for this executable; this value allows tokens such as %10%, %11%, etc; this value is optional and will default to NULL if not provided
5. “TimeoutSeconds” – this parameter provides the number of seconds that the cleanup tool should wait after calling CreateProcess before it will timeout and kill the process; this parameter is optional and if it is not provided, the cleanup tool will default to an infinite timeout
6. “WaitOnExit” – this parameter specifies whether or not the cleanup tool should wait for the executable to return before continuing with other cleanup actions; this parameter is optional and if it is not provided, the cleanup tool will default to “false” and not wait for the custom action executable to exit; if the parameter is set to 0 the cleanup tool will not wait, and if it is set to any other value it will wait
7. “Silent” – this parameter specifies whether or not to suppress UI for the custom action executable; this parameter is optional and if it is not provided, the cleanup tool will default to “false” and allow the executable to show UI; if the parameter is set to 0 the cleanup tool will allow the executable to show UI, and if it is set to any other value it will suppress any UI for the executable
Operating system conditions
Both products and actions can be associated with a list of applicable operating systems. This allows products and/or actions to only run on specific operating system types. The following represents a list of the valid operating system types recognized by the tool along with their meanings:
· WIN95 – Windows 95
· WIN98 – Windows 98 (both Gold and Second Edition)
· WINME – Windows Millennium Edition (ME)
· NT4 – Windows NT 4.0 family
· WIN2000 – Windows 2000 family
· WINXP – Windows XP family (including Tablet PC and Media Center)
· WIN64XP – Windows XP 64-bit special edition
· WIN2003 – Windows Server 2003 family
· WIN642003 – Windows Server 2003 64-bit edition
· FUTURENT – Any version of Windows released after Windows Server 2003
· FUTURE64NT – Any 64-bit version of Windows released after Windows Server 2003
Example INI file
The following is an example of the syntax for cleanup.ini:
[Products]
ProductCount=2
Product1=.NET Framework 1.0
Product2=.NET Framework 1.1
Product1_OS= NT4,WIN2000,WINXP,WIN2003,FUTURENT
LogNetfxInstallState=1
WindowTitle=.NET Framework Cleanup Tool
[.NET Framework 1.0]
ActionCount=6
Action1=Product Codes - .NET Framework 1.0
Action2=Directories - .NET Framework Common
Action3=Directories - .NET Framework 1.0
Action4=Files - .NET Framework Common
Action5=Files - .NET Framework 1.0
Action6=Registry - .NET Framework Common
RepairWindowsInstaller=1
[.NET Framework 1.1]
ActionCount=5
Action1=Stop Services - .NET Framework 1.1
Action2=Product Codes - .NET Framework 1.1
Action3=Directories - .NET Framework Common
Action4=Files - .NET Framework Common
Action5=Registry - .NET Framework Common
Action5_OS=WIN2000,WINXP,WIN2003
RepairWindowsInstaller=1
[Stop Services - .NET Framework 1.1]
msiserver
w3svc
[Directories - .NET Framework 1.0]
%10%\Microsoft.NET\Framework\v1.0.3705
[Directories - .NET Framework 1.1]
%10%\Microsoft.NET\Framework\v1.1.4322
[Directories - .NET Framework Common]
%11%\URTTemp
[Files - .NET Framework Common]
%11%\netfxperf.dll
[Files - .NET Framework 1.0]
%10%\aaron2.txt
[Registry - .NET Framework Common]
HKLM,Software\Microsoft\.NETFramework\Policy\Upgrades\v1.0
HKLM,Software\Microsoft\.NETFramework\Policy\Upgrades\v1.1,4322
[Product Codes - .NET Framework 1.0]
' .NET Framework 1.0 ENU product code
{B43357AA-3A6D-4D94-B56E-43C44D09E548}=300000
[Product Codes - .NET Framework 1.1]
' .NET Framework 1.1 product code
{CB2F7EDD-9D1F-43C1-90FC-4F52EAE172A1}
Not yet implemented
The following items are known work items for cleanup.exe that have not yet been done, or notes with questions for beta testers.
· There may be some folder tokens that are needed but are not yet implemented – I need to get a complete list of tokens that will be needed and add support to the tool and then document them here
· The list of actions may need to be enhanced to make it more flexible – are there any other action types that should be offered for use (possibly a custom action section that lets the user specify any command line to run?)
· Any other feature suggestions or bugs reported by beta testers….