Blog
MSI File Versioning Rules
Why is File Versioning required?
At the core of any installer is the actual installation of files. Determining whether to install a file is a complex process. At the highest level, this determination depends on whether the component to which a file belongs is marked for installation. Once determined that a file should be copied, the process is complicated if another file with the same name exists in the target folder. In such situations, File Versioning assumes importance.
How does File Versioning work?
The installer uses some rules when trying to install a file to a location that already contains a file with the same name. The Windows Installer uses the following rules, all other things being equal, to determine whether to install.
- Highest Version Wins—all other things being equal, the file with the highest version wins, even if the file on the computer has the highest version.
- Versioned Files Win—a versioned file gets installed over a non versioned file.
- Favor Product Language—if the file being installed has a different language than the file on the computer, favor the file with the language that matches the product being installed. Language-neutral files are treated as just another language so the product being installed is favored again.
- Mismatched Multiple Languages—after factoring out any common languages between the file being installed and the file on the computer, any remaining languages are favored according to what is needed by the product being installed.
- Preserve Superset Languages—preserve the file that supports multiple languages regardless of whether it is already on the computer or is being installed.
- Non versioned Files are User Data—if the Modified date is later than the Create date for the file on the computer do not install the file because user customizations would be deleted. If the Modified and Create dates are the same, install the file. If the Create date is later than the Modified date, the file is considered unmodified, install the file. The installation of a Companion File depends not on its own file versioning information, but on the versioning of its companion parent. In the case of Companion Files, the installation is skipped only if the parent file has a higher version.
- Non versioned Files Using Companion Files-A non versioned file that is associated with a versioned file using the companion mechanism abides by the rules for the versioned file. The only exception is if the versioned file on the computer and the versioned file being installed have the same version and language but the companion file is missing on the computer. In this case the companion file being installed is used even though the versioned file on the computer is used. Additionally, a non versioned file using a companion file is installed if the REINSTALLMODE property includes the overwrite older versions options (“o” or “e”) and the companion file’s version is equal to a file already on the machine.
Different scenarios involved in File Versioning
Replacing Existing Files
Because unnecessary file copying slows an installation, the Windows Installer determines whether the component’s key file is already installed before attempting to install the files of any component. If the installer finds a file with the same name as the component’s key file installed in the target location, it compares the version, date, and language of the two key files and uses file versioning rules to determine whether to install the component provided by the package. If the installer determines it needs to replace the component base upon the key file, then it uses the file versioning rules on each installed file to determine whether to replace the file. The default file versioning rules can be overridden or modified by using the REINSTALLMODE property. The installer uses the file versioning rules specified by the REINSTALLMODE property when installing, reinstalling, or repairing a file. The following example shows how the installer applies the default File Versioning Rules. The default value of the REINSTALLMODE property is “omus“.
An example of File Versioning
The following tables will be helpful in understanding how file versioning works
Table illustrating the key files installed on the system before the component is reinstalled
| File | Version | Create date | Modified date | Language |
| FileA | 1.0.0000 | 1/1/99 | 1/1/99 | ENG |
| FileB | 2.0.0000 | 1/1/99 | 1/1/99 | ENG |
| FileC | 1.0.0000 | 1/1/99 | 1/1/99 | ENG |
| FileD | 1.0.0000 | 1/1/99 | 1/2/99 | ENG |
| FileE | none | 1/1/99 | 1/1/99 | none |
| FileF (modified > create) | none | 1/1/99 | 1/2/99 | none |
| FileG | 1.0.0000 | 1/1/99 | 1/1/99 | ENG |
| FileH | 1.0.0000 | 1/1/99 | 1/1/99 | ENG,FRN,SPN |
| FileI | 1.0.0000 | 1/1/99 | 1/1/99 | ENG,FRN |
| FileJ | 1.0.0000 | 1/1/99 | 1/1/99 | ENG,GER,ITN |
Table illustrating the component key files included in the installer package
| File | Version | Create date | Modified date | Language |
| FileA(marked same) | 1.0.0000 | 1/1/99 | 1/1/99 | ENG |
| FileB(earlier version) | 1.0.0000 | 1/1/99 | 1/1/99 | ENG |
| FileC (later version) | 2.0.0000 | 1/1/99 | 1/1/99 | ENG |
| FileD(later version) | 2.0.0000 | 12/31/98 | 1/10/99 | FRN |
| FileE (marked same) | none | 1/1/99 | 1/1/99 | none |
| FileF(new file) | none | 1/3/99 | 1/3/99 | none |
| FileG(new language) | 1.0.0000 | 1/1/99 | 1/1/99 | FRN |
| FileH(new language) | 1.0.0000 | 1/1/99 | 1/1/99 | ITN,ENG,GER |
| FileI(more languages) | 1.0.0000 | 1/1/99 | 1/1/99 | ENG,FRN,SPN |
| FileJ(fewer languages) | 1.0.0000 | 1/1/99 | 1/1/99 | GER |
Table illustrating component key files that stay on the system after the component is reinstalled
| File | Version | Create date | Modified date | Language |
| FileA (original) | 1.0.0000 | 1/1/99 | 1/1/99 | ENG |
| FileB (original) | 2.0.0000 | 1/1/99 | 1/1/99 | ENG |
| FileC (replacement) | 2.0.0000 | 1/1/99 | 1/1/99 | ENG |
| FileD (replacement) | 2.0.0000 | 12/31/98 | 1/10/99 | FRN |
| FileE (replacement) | none | 1/1/99 | 1/1/99 | none |
| FileF (original) | none | 1/1/99 | 1/2/99 | none |
| FileG (replacement) | 1.0.0000 | 1/1/99 | 1/1/99 | FRN |
| FileH (replacement) | 1.0.0000 | 1/1/99 | 1/1/99 | ITN,ENG,GER |
| FileI (replacement) | 1.0.0000 | 1/1/99 | 1/1/99 | ENG,FRN,SPN |
| FileJ (original) | 1.0.0000 | 1/1/99 | 1/1/99 | ENG,GER,ITN |
Default File Versioning
The flow diagrams in the following sections illustrate the default file versioning rules used when the key file of a component being installed has the same name as a file already installed in the target location.
Both Files have a Version- If the key file of a component being installed (copy-A) has the same name as a file already installed in the target location (copy-B), the installer compares the version number, date, and language of the two files. If both files have a version number, the installer uses the logic illustrated by the following flow diagram to determine whether to replace all of the installed files belonging to the component. Because the installer only installs entire components, if the installed key file is replaced then all of the component’s files are replaced. Note that this diagram illustrates the default File Versioning Rules, which can be overridden by setting the REINSTALLMODE property. The default value of the REINSTALLMODE property is “omus”.
Default File Versioning when both files have a Version
The previous diagram can also be used with files with no language specified. If copy-A has a specified language and copy-B has no specified language, copy-B is replaced with copy-A. If copy-A and copy-B both have no language specified, then copy-B is not replaced.
Neither File has a version-If the key file of a component being installed (copy-A) has the same name as a file already installed in the target location (copy-B), the installer compares the version number, date, and language of the two files. If neither file has a version number, the installer uses the logic illustrated by the following flow diagram to determine whether to replace all of the installed files belonging to the component. Because the installer only installs entire components, if the installed key file is replaced, then all of the component’s files are replaced. Note that this diagram illustrates the default File Versioning Rules, which can be overridden by setting the REINSTALLMODE property. The default value of the REINSTALLMODE property is “omus”.
Default File Versioning when neither File has a version
Neither File has a Version with File Hash Check-File hashing is available with Windows Installer version 2.0 and later. The MsiFileHash table can only be used with unversioned files. If the key file of a component being installed (copy-A) has the same name as a file already installed in the target location (copy-B), the installer compares the version number, date, and language of the two files. If neither file has a version number, the installer uses the logic illustrated by the following flow diagram to determine whether to replace all of the installed files belonging to the component. Because the installer only installs entire components, if the installed key file is replaced then, all of the component’s files are replaced. Note that this diagram illustrates the default File Versioning Rules, which can be overridden by setting the REINSTALLMODE property. The default value of the REINSTALLMODE property is “omus”.
Default File Versioning when neither file has a version with File Hash Check
One File has a Version- If the key file of a component being installed (copy-A) has the same name as a file already installed in the target location (copy-B), the installer compares the version number, date, and language of the two files. If only one of the files has a version number, the installer uses the logic illustrated by the following flow diagram to determine whether to replace all of the installed files belonging to the component. Because the installer only installs entire components, if the installed key file is replaced, then all of the component’s files are replaced. Note that this diagram illustrates the default File Versioning Rules, which can be overridden by setting the REINSTALLMODE property. The default value of the REINSTALLMODE property is “omus”.
Default File Versioning when one file has a version