Aaron Stebner's WebLog

Links to 3 new community spotlight features on the XNA Creators Club Web site

Three new community spotlight features were posted today on the XNA Creators Club Web site, and I want to link to them here and encourage you to take a look.  Here is a bit more information about each of them:

• Making Schizoid with XNA Game Studio - This post is an interview with 2 members of the team that created Schizoid, the first game created with XNA Game Studio to be made available on Xbox LIVE Arcade.
• Interview with Albert Ho (GPM on the XNA community team) - In this post, Albert talks about some of the announcements made at Gamefest this past week regarding Xbox LIVE Community Games.
• Mother Gaia Studio - This post is an interview with some members of the team that won first place in the Imagine Cup 2008 contest with their game City Rain.

You can find a full collection of XNA Creators Club community spotlight features on this page.

Some notes about OS installation conditions in Media Center application setup files

Recently, I noticed this post on the Big Screen Blog where Niall Ginsbourg talks about some changes he made to the installers for his Big Screen applications for Windows Vista Media Center.  He didn't go into much detail about what he changed, so I want to explain the OS version detection that happens in the WiX v3.0-based installer files included with the Windows Media Center application project templates that ship in the Windows Media Center SDK v5.3 and that I have previously posted on my blog (for example, here and here).  I will also outline the types of changes you may want to make in the OS version conditions in your Windows Media Center application installers depending on what scenarios you plan to support in the future.

For the WiX syntax quoted in this blog post, I will refer to the WiX v3.0 setup files that are created by the Visual Studio project templates that ship in the Windows Media Center SDK.  You can find these setup files in the Setup sub-folder after creating an instance of one of the Windows Media Center project templates after installing Visual Studio and the Windows Media Center SDK v5.3.

Description of the OS install block  in existing Media Center application setup samples

The WiX source file in the Windows Media Center project templates (named Setup.wxs) includes a custom action to block installation if the user attempts to run the MSI on an unsupported OS.  The custom action is defined by the following WiX element:

<CustomAction Id="CA_ErrWrongWindowsVersion" Error="!(loc.LaunchCondition_WrongOSVersion)" />

Later on in Setup.wxs, the conditions are defined that control when this custom action will be run.  The following WiX element is included in both the InstallExecuteSequence table and the InstallUiSequence table in order to make sure that the custom action will run if the MSI is installed in full UI mode or in silent mode:

<Custom Action="CA_ErrWrongWindowsVersion" Before="CostInitialize"><![CDATA[(NOT VersionNT = 600 OR NOT MCEINSTALLVERSION = "5.0" OR NOT REGISTERMCEAPP) AND NOT Installed]]></Custom>

There are 4 specific conditions that are checked for this custom action:

1. NOT VersionNT = 600 - This checks the built-in Windows Installer property named VersionNT to make sure it is equal to 600, and will cause setup to block if it is not.  This is primarily designed to prevent the MSI from installing on older versions of Windows such as Windows XP Media Center Edition (which will have VersionNT = 501), but will also end up preventing installation on future versions of Windows that have the VersionNT value set to something higher than 600 as well.
2. NOT MCEINSTALLVERSION = "5.0" - This queries the Ident registry value located at HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Media Center and will cause setup to block if the value does not exist or is not equal to 5.0.  This is primarily designed to prevent the MSI from installing on versions of Windows that do not include Windows Media Center features or from installing on systems that have older versions of Media Center (see the chart of Ident values here for more information).  However, it will also end up preventing installation on systems if they have future versions of Windows Media Center that have the Ident value set to something higher than 5.0 as well.
3. NOT REGISTERMCEAPP - this condition checks to make sure that the file %windir%\eHome\RegisterMceApp.exe exists on the system and has a version number at least 6.0.0.0.  This will make sure that at least the Windows Vista version of RegisterMceApp.exe is on the system because it is needed during setup to register the application for use in Windows Media Center.
4. NOT Installed - this condition is a standard Windows Installer condition that is typically added to blocking custom actions such as this one.  It detects whether or not the current product is already installed, and is intended to prevent the user from being blocked when trying to uninstall the product.

Of the conditions listed above, the VersionNT condition (item 1) and the MCEINSTALLVERSION condition (item 2) are not future-proof.  In other words, they will end up causing setup to block on future versions of Windows and Windows Media Center if they end up being configured to use higher values for the VersionNT property and/or the Ident registry value.

When we shipped these example installers in the Media Center SDK, we made a conscious decision to bind the installers to a specific, known version of Windows and Windows Media Center.  This is because the known version is the only one that can currently be tested and assured of working correctly with Media Center application code developed using the SDK.

Making the install conditions less restrictive

In your scenario (and in the scenario Niall described in his blog post), you may find these conditions too restrictive and may want to update your Media Center application installer so that you do not necessarily have to release new versions of your installers if new versions of Windows and/or Windows Media Center ship with higher values for the VersionNT property and/or the Ident registry value in the future.

If you would like to loosen the restrictions in your installer, I suggest changing the custom action condition to the following:

<Custom Action="CA_ErrWrongWindowsVersion" Before="CostInitialize"><![CDATA[(NOT VersionNT >= 600 OR NOT MCEINSTALLVERSION OR NOT REGISTERMCEAPP) AND NOT Installed]]></Custom>

This condition contains the following changes when compared to the original Setup.wxs file that is created by the project templates in the Windows Media Center SDK:

• NOT VersionNT >= 600 - This condition will cause the MSI to only block on any version of Windows prior to Vista.  It will no longer block on any potential future versions of Windows with a VersionNT value greater than 600.
• NOT MCEINSTALLVERSION - This condition will cause the MSI to only block if the Ident registry value does not exist, but will not check the exact Ident version value.  It will no longer block on any potential future version of Windows Media Center with an Ident value not equal to 5.0.  It could also theoretically run on an older version of Windows Media Center, but you should be protected by the VersionNT check in that case to avoid the MSI running on Windows XP Media Center Edition for example.  I chose not to put a greater than or equal check here because the Ident value is a REG_SZ data type in the registry, and greater than or equal checks on strings tend to not always be accurate (for example "10.0" is less than "2.0" when doing string comparisons).

Note that you must make sure to change this condition in both the InstallExecuteSequence table and the InstallUiSequence table in your WXS file or else you will see different install blocking behavior in full UI mode versus silent mode.

A real-world example - PowerPlaylist

You can take a look at the WiX source code for the PowerPlaylist application on Codeplex for an example of less restrictive installation conditions.  The installer for PowerPlaylist was initially created from a Windows Media Center project template in the SDK, and it was later modified to contain less restrictive OS installation conditions.  PowerPlaylist is used within the Media Center team at Microsoft as an application compatibility test case, so it had to be modified to allow installation on any possible version of Windows Media Center starting with Windows Vista.  There are trade-offs related to application compatibilty that you have to make if you decide to make the OS installation conditions in your Media Center application installer less restrictive though - see the note at the end of this blog post for more details.

Note that unlike the recommendation above, the installer for PowerPlaylist does not check for the Ident registry value at all (you will not see any reference to the MCEINSTALLVERSION property in that installer).  This option will also work, but I recommend checking that the Ident value exists is an extra safeguard to make sure that the system really does contain Windows Media Center.  A system should not be able to contain Windows Media Center functionality without the Ident registry value also being present.

A word of caution about less restrictive installation conditions

If you decide to update the installer for your Media Center application to include less restrictive OS install conditions, please note that this will allow your application to install on any possible future version of Windows and/or Windows Media Center.  Since these future versions do not yet exist, it is impossible to know whether or not your application will continue to be compatible with them.  Microsoft generally makes a best effort to maintain application compatibility as it releases new versions of Windows, but compatibility cannot be guaranteed.  It is strongly advised that you perform compatibility testing for your application as new versions of Windows are released in order to be sure that things still work as expected within your application.  By loosening OS install conditions, you are essentially putting some of the compatibility testing burden onto users of your application, which can be frustrating for them.

I realize that most Media Center application developers are not WiX or Windows Installer experts, so the above information might be confusing.  Please don't hesitate to leave a comment on this blog post or contact me if you have more detailed questions about the scenarios described here or would like an opinion about installation behavior that you are considering for your application.

 

Link to MSDN topic with descriptions of all Win32 error codes

I recently discovered a useful topic that was published on MSDN as a part of the Open Specifications initiative that I want to link to here in order to hopefully help make it easier to find.

The topic, located at http://msdn.microsoft.com/library/cc231199.aspx, provides a full table of Win32 error code values, their associated message identifiers and descriptions of what the errors mean.

This table of Win32 error codes can be useful in many types of development and troubleshooting scenarios.  For example, I often use it in conjunction with the err.exe tool that I described in more detail in this previous blog post to help narrow down root causes when troubleshooting installation issues.

More details about Xbox LIVE Community Games

Additional information was announced this morning at Gamefest about Xbox LIVE Community Games.  This information expands on the original announcement back in February at GDC by providing more details about how developers will be able to make money by selling their Xbox 360 games created with XNA Game Studio on Xbox LIVE Marketplace.

Here are some links with additional information:

• Today's announcement is summarized in this post on the XNA team blog.
• You can see more detailed information about the new announcements in the Introducing Xbox LIVE Community Games article and FAQ on the Creators Club Web site.
• For additional information about how the game submission, peer review and publishing process works, check out this quick start guide.

Xbox LIVE Community Games will be available in the holiday 2008 timeframe, but as a developer you can get started now by doing the following:

1. Download and install XNA Game Studio
2. Join the XNA Creators Club so that you can develop and submit your Xbox 360 game.  You will need a premium membership (as described here).
3. Prepare to submit your game when Xbox LIVE Community Games is available

Scenarios where .NET Framework 3.5 setup tries to connect to the Internet and how to avoid them

The setup program for the .NET Framework 3.5 and the Visual Studio 2008 Express Editions contains logic that will cause it to attempt to connect to the Internet to download files in some scenarios.  I've heard from several folks who have asked me why this happens and how to prevent it in case they need to install in a fully offline scenario where the system has no Internet connectivity.  This post will describe the cases I know of where .NET Framework 3.5 and VS 2008 Express Edition setup will attempt to download files from the Internet and how they can be avoided if necessary.

Case 1 - Missing setup packages

.NET Framework 3.5 and Visual Studio 2008 Express Edition setup both have logic to search in relative paths next to setup.exe for packages that need to be installed during the setup process.  If any of the packages are not found in those relative paths, setup will use URL values constructed from information in the setup data file named baseline.dat to attempt to download the packages from the Internet instead.  If setup cannot connect to the Internet or the download fails for any reason, then setup will fail and report an error.

In order to avoid requiring Internet access in this scenario, you need to make sure to construct an install point for the .NET Framework 3.5 or the Visual Studio 2008 Express Editions that include all packages that could need to be installed in your environments.  You can find more information about how to do this in the following blog posts:

• Creating an installable layout for the .NET Framework 3.5
• Creating an installable layout for Visual Studio 2008 Express Editions

If you are interested, you can find more information about how this automatic download functionality works in .NET Framework 3.5 setup here and here.  The VS 2008 Express Edition setup packages use the same setup.exe code as the .NET Framework 3.5 setup, so the behind-the-scenes logic is similar for those packages.

Case 2 - Installing the .NET Framework 3.5 on a non-English OS

The .NET Framework 3.5 setup contains logic to check the language of the OS that it is being installed on and attempt to install a language pack that matches the OS language if one is available.  However, the "full install" setup package for the .NET Framework 3.5 does not include any language packs, so setup will attempt to connect to the Internet when this package is run on many non-English language OS's.

In order to avoid requiring Internet access in this scenario, you can use one of the following techniques:

• Download the .NET Framework 3.5 language packs that could be needed in your environments and copy them into your installable .NET Framework 3.5 layout.  You can find download locations for the .NET Framework 3.5 language packs in this blog post and instructions regarding where to copy them in your .NET Framework 3.5 installable layout in item 2 in this blog post.
• Run .NET Framework 3.5 setup with the /lang switch and pass in the value ENU to prevent it from attempting to install any language packs.  This is described in item 1 in this blog post.

Note - .NET Framework 3.5 setup is configured to report warnings as opposed to failures if it is unable to download or install language packs.  That means that the above steps are not required in order to allow setup to succeed in offline scenarios, but these steps are required if you want to avoid any attempts to connect to the Internet during .NET Framework 3.5 setup on non-English operating systems.

Case 3 - Checking for a new version of setup

The setup programs for the .NET Framework 3.5 and the Visual Studio 2008 Express Editions contain logic to cause them to connect to the Internet to search for an updated version of the setup program.  This will only happen if setup is run with the /web command line switch.  The .NET Framework 3.5 setup program (dotnetfx35setup.exe) and the web download bootstrapper packages for the Visual Studio 2008 Express Editions (vbsetup.exe, vcsetup.exe, vcssetup.exe and vnssetup.exe) are self-extracting packages that are configured to unpack and then run the setup.exe contained within the package with the /web switch.

In order to avoid having .NET Framework 3.5 setup connect to the Internet to search for an updated version of itself, you must do the following:

1. Create an installable layout using the steps in this blog post
2. Go to the folder that you extracted the .NET Framework 3.5 setup files to, find the file named dotnetfx35setup.exe and run dotnetfx35setup.exe /x to unpack it
3. When prompted, choose to unpack it to the same folder it is currently located in
4. Instead of using the file dotnetfx35setup.exe to start installing the .NET Framework 3.5, use the file setup.exe in the unpacked location.  This will cause setup to run without the /web switch and skip the step of connecting to the Internet to search for a new copy of setup.  The setup.exe file takes the same command line parameters as dotnetfx35setup.exe (such as the /q and /norestart switches for silent installation).

For the Visual Studio 2008 Express Editions, only the web download bootstrapper packages available from this download page are configured to use the /web switch.  If you use the instructions for creating an installable layout in this blog post, you will end up unpacking the package that has the /web switch built into it, and running from the layout you create will not end up searching for a new instance of itself during setup.

Note - .NET Framework 3.5 and VS 2008 Express Edition setups are configured to not fail if they are unable to connect to the Internet to check for a new instance of setup.  That means that the above steps are not required in order to allow setup to succeed in offline scenarios, but these steps are required if you want to avoid any attempts to connect to the Internet during .NET Framework 3.5 setup.

How .NET Framework 3.5 setup checks for its prerequisites behind the scenes

The .NET Framework 3.5 setup package is a chainer that installs multiple packages behind the scenes.  Before installing anything, it performs an inventory of the state of the system being installed on and decides which packages need to be installed on the system during setup based on what it finds on the system.

The .NET Framework 3.5 Administrator Deployment Guide lists the prerequisite packages that setup installs on each supported OS and describes the command lines that can be used to install them silently, but it does not describe how to determine whether or not a system already has any of the prerequisites installed in order to optimize the deployment process.

The following is a list of all prerequisites for .NET Framework 3.5 setup and the exact logic that .NET Framework 3.5 setup uses behind the scenes to determine whether or not each of them is installed on a user's system, and whether or not setup will block installation if they are not present or will automatically install them for the user.

Note that all of the OS install state, file version and registry version information listed below comes from the file baseline.dat that is included in the .NET Framework 3.5 self-extracting setup package.

Windows XP SP2

On Windows XP systems, .NET Framework 3.5 setup checks the following registry value to determine the OS service pack state:

[HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Windows]
CSDVersion >= 512

Setup will block if the necessary service pack is not found, and the user must manually update their system before setup can proceed.

Windows Server 2003 SP1

On Windows Server 2003 systems, .NET Framework 3.5 setup checks the following registry value to determine the OS service pack state:

[HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Windows]
CSDVersion >= 256

Setup will block if the necessary service pack is not found, and the user must manually update their system before setup can proceed.

Windows Installer 3.1

.NET Framework setup only checks for this prerequisite on Windows XP because the necessary Windows Installer version is a part of the OS on other supported platforms.  To determine installation state, it checks the version of the following file:

%windir%\system32\msi.dll >= 3.1.4000.2435

Setup will block if the necessary version is not found, and the user must manually update their system before setup can proceed.

Software rasterizer for the DirectX 9.0 SDK (RGB Rasterizer)

.NET Framework 3.5 setup only attempts to install this component on Windows XP and Windows Server 2003.  To determine installation state, it checks the version of the following file:

%windir%\system32\rgb9rast_2.dll >= 9.15.735.0

Setup will install this package if the necessary version is not found on the system.

MSXML 6.0

.NET Framework 3.5 setup only attempts to install this component on Windows XP and Windows Server 2003.  To determine installation state, it checks the version of the following file:

%windir%\system32\msxml6.dll >= 6.0.3888.0

Setup will install this package if the necessary version is not found on the system.

Windows Imaging Component

.NET Framework 3.5 setup only attempts to install this component on Windows XP and Windows Server 2003.  To determine installation state, it checks the version of the following file:

%windir%\system32\windowscodecs.dll >= 6.0.5840.16388

Setup will install this package if the necessary version is not found on the system.

.NET Framework 2.0 SP1 (Windows XP and Windows Server 2003)

On Windows XP and Windows Server 2003, .NET Framework 3.5 setup checks for the existence of the MSI-based version of the .NET Framework 2.0 SP1.  To determine installation state, it checks the following registry value:

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\NET Framework Setup\NDP\v2.0.50727]
Version >= 2.1.21022

Setup will install this package if the necessary version is not found on the system.

.NET Framework 2.0 SP1 (Windows Vista and Windows Server 2008)

On Windows Vista and Windows Server 2008, .NET Framework 3.5 setup checks for the existence of the .NET Framework 2.0 SP1 OS update package because the .NET Framework 2.0 is an OS component on these OS's.  To determine installation state, it checks the version of the following file:

%windir%\Microsoft.NET\Framework\v2.0.50727\mscorwks.dll >= 2.0.50727.1433

Setup will install this package if the necessary version is not found on the system.

XML Paper Specification Shared Components (XPS)

.NET Framework 3.5 setup only attempts to install this component on Windows XP and Windows Server 2003.  To determine installation state, it checks the version of the following file:

%windir%\system32\prntvpt.dll >= 6.0.6000.16438

Setup will install this package if the necessary version is not found on the system.

.NET Framework 3.0 OS component (Windows Vista and Windows Server 2008)

On Windows Vista and Windows Server 2008, .NET Framework 3.5 setup checks for the existence of the .NET Framework 3.0 component that ships as a part of the OS.  To determine installation state, it checks the following registry value:

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\NET Framework Setup\NDP\v3.0\Setup]
InstallSuccess = 1

If the .NET Framework 3.0 SP1 OS component is not found on the system, setup will use a technique like the one described in this blog post to cause the OS to install the component.

.NET Framework 3.0 SP1 (Windows XP and Windows Server 2003)

On Windows XP and Windows Server 2003, .NET Framework 3.5 setup checks for the existence of the MSI-based version of the .NET Framework 3.0 SP1.  To determine installation state, it checks the following registry value:

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\NET Framework Setup\NDP\v3.0]
Version >= 3.1.21022

Setup will install this package if the necessary version is not found on the system.

.NET Framework 3.0 SP1 (Windows Vista and Windows Server 2008)

On Windows Vista and Windows Server 2008, .NET Framework 3.5 setup checks for the existence of the .NET Framework 3.0 SP1 OS update package because the .NET Framework 3.0 is an OS component on these OS's.  To determine installation state, it checks the following registry value:

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\NET Framework Setup\NDP\v3.0\Setup]
Version >= 3.0.04506.648

Setup will install this package if the necessary version is not found on the system.

.NET Framework 3.5

On all supported operating systems, .NET Framework 3.5 setup checks for the existence of the main .NET Framework 3.5 MSI package.  To determine installation state, it checks the following registry value:

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\NET Framework Setup\NDP\v3.5]
Version >= 3.5.21022.08

Setup will install this package if the necessary version is not found on the system.

Additional information

The .NET Framework 2.0 SP1 and .NET Framework 3.0 SP1 also ship as standalone installation packages that can be installed independently from the .NET Framework 3.5.  Each of these packages includes a subset of the above prerequisites and uses the same logic described above to determine whether or not each prerequisite is already installed.  The following is a list of which of the above prerequisites are required for the .NET Framework 2.0 SP1 and 3.0 SP1:

Prerequisites for the .NET Framework 2.0 SP1:

• Windows XP SP2
• Windows Server 2003 SP1
• Windows Installer 3.1

Prerequisites for the .NET Framework 3.0 SP1:

• Windows XP SP2
• Windows Server 2003 SP1
• Windows Installer 3.1
• Software rasterizer for the DirectX 9.0 SDK (RGB Rasterizer)
• MSXML 6.0
• Windows Imaging Component
• .NET Framework 2.0 SP1 (Windows XP and Windows Server 2003)
• .NET Framework 2.0 SP1 (Windows Vista and Windows Server 2008)
• XML Paper Specification Shared Components (XPS)
• .NET Framework 3.0 OS component (Windows Vista and Windows Server 2008)

Here are links to some additional useful information related to .NET Framework 3.5 deployment:

• .NET Framework 3.5 setup log files
• Information about .NET Framework 3.5 deployment guides

Version information that can help diagnose errors when opening XNA Game Studio projects in Visual Studio

I recently noticed a blog article from the Zman that I wanted to link to here to hopefully make it easier to find.  The post, located at http://www.thezbuffer.com/articles/541.aspx, provides some behind-the-scenes details about the contents of XNA Game Studio and XNA Game Studio Express .csproj files.  The project GUIDs and XNA Framework version information listed in this post can help you determine exactly what version of XNA Game Studio or XNA Game Studio Express a specific .csproj file was created with.

If you run into an error message stating "The project type is not supported by this installation" when attempting to open an XNA Game Studio project in Visual Studio 2005 or 2008 and are trying to figure out how to fix it, the information in this article can be very helpful.  Typically, this error occurs when trying to open XNA Game Studio projects for one of the following reasons:

• Trying to double-click an XNA Game Studio project (.csproj) file on a system that does not have the matching version of XNA Game Studio or XNA Game Studio Express installed.
• Trying to open a project from within a version of Visual Studio that is not supported by the version of XNA Game Studio that the project was created in (for example - opening an XNA Game Studio 2.0 project in Visual Studio 2008).
• Trying to open a XNA Game Studio Express 1.0 or 1.0 Refresh project on a system that has an up-level edition of Visual Studio 2005 installed but does not have Visual C# 2005 Express Edition installed - this will cause the solution to open in the up-level edition of Visual Studio 2005, but XNA Game Studio did not support up-level editions of VS until XNA Game Studio 2.0.  Projects for the 1.0 or 1.0 Refresh versions must be opened on a system that has Visual C# 2005 Express Edition and XNA Game Studio 1.0 or 1.0 Refresh installed.

If you run into an error while trying to open an XNA Game Studio or XNA Game Studio Express project on your system, I encourage you to check out this article and use the information listed there to determine the XNA Game Studio version of the project that you're trying to open by looking at your .csproj file in Notepad, then verify that the necessary versions of both Visual Studio and XNA Game Studio are installed on your system.

For reference, here is a list of supported Visual Studio platforms per version of XNA Game Studio:

• XNA Game Studio Express 1.0 - Visual C# 2005 Express
• XNA Game Studio Express 1.0 Refresh - Visual C# 2005 Express with SP1
• XNA Game Studio 2.0 - Visual C# 2005 Express with SP1 and Visual Studio 2005 Standard Edition or higher with SP1
• XNA Game Studio 3.0 CTP - Visual C# 2008 Express and Visual Studio 2008 Standard Edition or higher

Mailbag: How can I detect the presence of the .NET Framework 2.0 or later in my MSI-based installer?

Question:

I am creating an application that is built on the .NET Framework 2.0, and I am attempting to create an MSI-based installer for it.  I have seen documentation and sample code describing how to detect the presence of individual versions of the .NET Framework.  My application does not require a specific version of the .NET Framework, but has a minimum version of 2.0, so I would like to detect the presence of the .NET Framework 2.0 or later in order to try to avoid needing to update my installation logic each time the .NET Framework ships a new version.  How can I do this?

Answer:

There is not an officially supported way of checking for the presence of a range of .NET Framework versions.  There are supported ways of checking for each version that has been released, but this logic can only be used to determine whether or not that exact version is installed.  This logic cannot necessarily be used to infer anything about other versions of the .NET Framework.  In particular, it is not possible to know ahead of time what types of detection logic will be needed for versions of the .NET Framework that have not yet been released.

As a result, it is most reliable to have your application's installer check for specific versions of the .NET Framework that you have tested your application against and that you know your application is compatible with.  Then, you can update your installer logic if you need to support additional versions of the .NET Framework as they are released in the future.

Admittedly, it is not ideal to have to update your installer as new versions of the .NET Framework are released, but it is the only way to be sure that your detection logic will return the correct result for .NET Framework install state checks in the future.  As a side benefit, the process of updating your installer will also help ensure that you perform the necessary compatibility testing to ensure that your application continues to work as expected when installed on a system that only has some future version of the .NET Framework that was not available to test against when your application originally shipped.

For reference, here are a few ways that I have seen various setups use in order to attempt to implement a "greater than or equal" check for versions of the .NET Framework along with reasons why they are not reliable:

• Check for the presence of the .NET Framework 2.0 using the documented detection registry value in order to detect the .NET Framework 2.0 or higher.  This check happens to work for the .NET Framework 3.0 and 3.5 because 3.0 and 3.5 are not truly new versions of the .NET Framework (meaning - they do not update the underlying CLR), and 3.0 and 3.5 both require 2.0 to be installed before they allow the user to install.  However, this logic is not necessarily going to be true in future versions of the .NET Framework and there will likely eventually be a new version of the CLR that will cause this type of check to return incorrect results on a system that does not also have the .NET Framework 2.0 installed.
• Check the value of the Windows Installer MsiNetAssemblySupport property.  This property is set to the version number of fusion.dll for the latest version of the CLR that is installed on the system.  This property does not get updated to a version greater than 2.0 when installing the .NET Framework 3.0 or 3.5 because both 3.0 and 3.5 use the 2.0 version of the CLR.  As a result, this property cannot currently be used to distinguish any versions of the .NET Framework greater than 2.0.  In addition, using this property may also not return the correct installation state needed for your application if the .NET Framework client profile is installed on the system but a full version of the .NET Framework is not installed.  For example, if your application requires a part of the .NET Framework not included in the client profile, but you use the MsiNetAssemblySupport property to detect the .NET Framework, it may return true when in reality the full version of the .NET Framework needed by your application is not present on the system.
• Check the version number of %windir%\system32\mscoree.dll.  This file is shared by all versions of the CLR and will have a file version equal to the highest installed version of the CLR on the system.  This file will still have a 2.0 version after installing the .NET Framework 3.0 or 3.5 because both 3.0 and 3.5 use the 2.0 version of the CLR.  As a result, this file cannot currently be used to distinguish any versions of the .NET Framework greater than 2.0.  In addition, using this file may also not return the correct installation state needed for your application if the .NET Framework client profile is installed on the system but a full version of the .NET Framework is not installed.  For example, if your application requires a part of the .NET Framework not included in the client profile, but you use the file version of mscoree.dll to detect the .NET Framework, it may return true when in reality the full version of the .NET Framework needed by your application is not present on the system.

A note for WiX users

If you are using WiX v3.0 to create MSI-based installers, there are some built-in properties in the WixNetFxExtension that can be included in your setup authoring to detect the presence of all currently released versions of the .NET Framework.  You can find a how-to help topic describing how to check for versions of the .NET Framework in an MSI-based setup using WiX v3.0 in builds 3.0.4220.0 or higher of WiX v3.0.  You can download WiX builds at http://wix.sourceforge.net/releases.  In the table of contents in WiX.chm (which is located in wix3-binaries.zip for each build of WiX), the topic is located under WiX Help | How To Guides | Redistributables and Install Checks | How To: Check for .NET Framework Versions.

.NET Framework 2.0 SP1 and 3.0 SP1 repair options on Windows Vista and Windows Server 2008

In my previous blog post, I described silent repair and uninstall command line switches that can be used for the .NET Framework 3.5.  In that post, I also noted that because the .NET Framework 3.5 includes the .NET Framework 2.0 SP1 and 3.0 SP1 as prerequisites, the repair process would chain in the repair for the .NET Framework 2.0 SP1 and 3.0 SP1 as well.

As a few people have already noticed, that statement is only true when running .NET Framework 3.5 repair on operating systems prior to Windows Vista.  Specifically, the supported pre-Vista OS's for the .NET Framework 3.5 are Windows XP (with SP2 or later) and Windows Server 2003.  On pre-Vista OS's, the .NET Framework 2.0 SP1 and 3.0 SP1 are installed using MSI-based packages.

On Windows Vista and Windows Server 2008, the .NET Framework 2.0 and 3.0 are OS components, so any updates to the .NET Framework 2.0 and 3.0 must be installed via OS updating technologies instead of by MSI-based packages.  Unfortunately, the OS updating logic does not allow the packages to be re-run to perform a repair.  Instead you have to uninstall and then reinstall the packages.  Because of this OS update behavior, running a repair of the .NET Framework 3.5 on Windows Vista will skip attempting to repair the .NET Framework 2.0 SP1 and 3.0 SP1 in order to avoid scenarios that we know will report failures.

How to uninstall and re-install 2.0 SP1 and 3.0 SP1 on Windows Vista

There is not an easy way to repair the .NET Framework 2.0 SP1 or 3.0 SP1 on Windows Vista.  If you are running Windows Vista without Vista SP1, you can uninstall the .NET Framework 2.0 SP1 and 3.0 SP1 using the following steps, and then perform a repair of the .NET Framework 3.5 to re-install them:

1. Go to the Programs and Features control panel
2. Click on the link at the top left labeled View installed updates
3. To remove the .NET Framework 3.0 SP1, find the item named Update for Microsoft Windows (KB929300), right-click on it and choose Uninstall
4. To remove the .NET Framework 2.0 SP1, find the item named Update for Microsoft Windows (KB110806), right-click on it and choose Uninstall
5. Repair the .NET Framework using the steps in this blog post to restore the .NET Framework 2.0 SP1 and 3.0 SP1

Important note about Windows Vista SP1 and Windows Server 2008

The .NET Framework 2.0 SP1 and 3.0 SP1 packages are integrated into Windows Vista SP1 and Windows Server 2008, so they are not available separately in the Programs and Features control panel like they are for Windows Vista without SP1.

This means that you must use one of the following options to attempt to repair the .NET Framework 2.0 SP1 and 3.0 SP1 on Windows Vista SP1 and Windows Server 2008:

1. If you installed the standalone Windows Vista SP1 update package (as opposed to purchasing a computer with Windows Vista with SP1 pre-installed), you can attempt to repair or re-install Windows Vista SP1 to repair all components of SP1, including the .NET Framework 2.0 SP1 and 3.0 SP1
2. If you have a computer that came pre-installed with Windows Vista SP1 or a computer with Windows Server 2008, there is not a separate update package that can be repaired.  You can use steps like the ones in this knowledge base article (KB929833) to repair the files that are a part of the OS (including the .NET Framework 2.0 SP1 and 3.0 SP1 payload).  The only way to perform a full repair of all components of the .NET Framework 2.0 SP1 and 3.0 SP1 (registry keys, services, etc and not just the files) is to repair or re-install Windows Vista or Windows Server 2008 themselves.

Mailbag: How to perform a silent repair and uninstall of the .NET Framework 3.5

Question:

A while back, you posted a set of instructions that can be used to perform silent or unattended repairs and uninstalls for the .NET Framework 2.0 SP1 and the .NET Framework 3.0 SP1.  I would like to automate the repair and uninstall for the .NET Framework 3.5 as well.  How can I do that?

Answer:

The .NET Framework 3.5 installs a copy of its setup files to the folder %windir%\Microsoft.NET\Framework\v3.5\Microsoft .NET Framework 3.5, and this location is the one that is launched when you go to Add/Remove Programs and choose to repair or uninstall the .NET Framework 3.5.  The setup.exe in this location can also be called directly in order to automate the repair or uninstall of the .NET Framework 3.5.

The following command lines can be used to repair and uninstall the .NET Framework 3.5.  The silent option will perform the repair/uninstall with no UI displayed to the user.  The unattended option will perform the repair/uninstall with only a progress dialog, but with no user interaction required.

.NET Framework 3.5 - silent repair

"%windir%\Microsoft.NET\Framework\v3.5\Microsoft .NET Framework 3.5\setup.exe" /q /norestart

.NET Framework 3.5 - unattended repair

"%windir%\Microsoft.NET\Framework\v3.5\Microsoft .NET Framework 3.5\setup.exe" /qb /norestart

.NET Framework 3.5 - silent uninstall

"%windir%\Microsoft.NET\Framework\v3.5\Microsoft .NET Framework 3.5\setup.exe" /q /uninstall /norestart

.NET Framework 3.5 - unattended uninstall

"%windir%\Microsoft.NET\Framework\v3.5\Microsoft .NET Framework 3.5\setup.exe" /qb /uninstall /norestart

Note:  There are a few things to keep in mind about the above instructions:

• When calling .NET Framework 3.5 setup in silent or unattended mode, you should check the return code from the setup.exe process in order to determine success or failure.  Return code 0 means that the setup was successful, return code 3010 means that the setup was successful but a reboot is required to complete the setup and any other return code means that there was an error.
• Log files will be created for the .NET Framework 3.5 repair and uninstall just like for the initial install.  You can find a list of .NET Framework 3.5 log files in this blog post.
• The .NET Framework 3.5 repair process will chain the repair processes for the .NET Framework 2.0 SP1 and the .NET Framework 3.0 SP1, so there is no need to use separate steps to repair those products if you are going to repair the .NET Framework 3.5.
• The .NET Framework 3.5 uninstall process will only uninstall the .NET Framework 3.5 MSI.  It will not uninstall the .NET Framework 2.0 SP1 or the .NET Framework 3.0 SP1 products because there may be other applications on the system that rely on those versions of the .NET Framework.  If you want to uninstall the .NET Framework 2.0 SP1 and 3.0 SP1, you must uninstall in the following order:  .NET Framework 3.5, then .NET Framework 3.0 SP1 then .NET Framework 2.0 SP1.

Strange .NET Framework 2.0 SP1, 3.0 SP1 and 3.5 installation error caused by orphaned registry value

Recently, I heard from a customer who could not get the .NET Framework 2.0 SP1 to install correctly on their system, and I wanted to explain the issue and how we were eventually able to resolve it in case anyone else runs into a similar issue in the future.

Description of the issue

The customer was able to successfully install the .NET Framework 1.1 and the original version of the .NET Framework 2.0.  However, when they launched the .NET Framework 2.0 SP1 installer, it allowed them to accept the license agreement, and then briefly showed the progress page before transitioning to a blank error page that looks like the following:

This error dialog is obviously not very helpful, and to complicate matters, there are not any errors reported in the .NET Framework 2.0 SP1 log files that are created in this scenario.  I had the customer use these steps to gather a list of installed products, and it did not list the .NET Framework 2.0 SP1, and the information in the application event log seemed to indicate that setup had not even attempted to install the 2.0 SP1 MSI.

Root cause of this issue for the .NET Framework 2.0 SP1

Eventually I discovered that there was an orphaned registry value on the system that was causing .NET Framework 2.0 SP1 setup to get confused and think that the product was already installed, even though the MSI was not actually installed on the system.  Once I discovered this issue, I was able to reproduce it on my test machine.  This is the exact registry value that causes this issue during .NET Framework 2.0 SP1 setup:

On x86 systems:

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\NET Framework Setup\NDP\v2.0.50727]
Version

On x64 and ia64 systems:

[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\NET Framework Setup\NDP\v2.0.50727]
Version

How to resolve this issue for the .NET Framework 2.0 SP1

Here are the steps that can be used to resolve this issue if you encounter it during .NET Framework 2.0 SP1 setup:

1. Click on the Start menu, choose Run, type cmd and click OK
2. Run this command:  reg delete "HKLM\SOFTWARE\Microsoft\NET Framework Setup\NDP\v2.0.50727" /v Version /f
3. Run this command:  reg delete "HKLM\SOFTWARE\Wow6432Node\Microsoft\NET Framework Setup\NDP\v2.0.50727" /v Version /f
4. Try again to download and install the .NET Framework 2.0 SP1 from here for x86, from here for x64 or from here for ia64

Root cause of this issue for the .NET Framework 3.0 SP1

While investigating this issue, I found that a similar issue can affect the installer for the .NET Framework 3.0 SP1.  A similar dialog to the one shown above will appear when attempting to run .NET Framework 3.0 SP1 setup, and like in the case of the .NET Framework 2.0 SP1, no errors are reported in the .NET Framework 3.0 SP1 setup log files.  This is the exact registry value that causes this issue during .NET Framework 3.0 SP1 setup:

On x86 systems:

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\NET Framework Setup\NDP\v3.0]
Version

On x64 and ia64 systems:

[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\NET Framework Setup\NDP\v3.0]
Version

How to resolve this issue for the .NET Framework 3.0 SP1

Here are the steps that can be used to resolve this issue if you encounter it during .NET Framework 3.0 SP1 setup:

1. Click on the Start menu, choose Run, type cmd and click OK
2. Run this command:  reg delete "HKLM\SOFTWARE\Microsoft\NET Framework Setup\NDP\v3.0" /v Version /f
3. Run this command:  reg delete "HKLM\SOFTWARE\Wow6432Node\Microsoft\NET Framework Setup\NDP\v3.0" /v Version /f
4. Try again to download and install the .NET Framework 3.0 SP1 from this location

Root cause of this issue for the .NET Framework 3.5

The above issue can also affect the installer for the .NET Framework 3.5 because it uses the same setup engine as the .NET Framework 2.0 SP1 and 3.0 SP1.  A similar dialog to the one shown above will appear when attempting to run .NET Framework 3.5 setup, and like in the cases above, no errors are reported in the .NET Framework 3.5 setup log files.  This is the exact registry value that causes this issue during .NET Framework 3.5 setup:

On x86 systems:

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\NET Framework Setup\NDP\v3.5]
Version

On x64 and ia64 systems:

[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\NET Framework Setup\NDP\v3.5]
Version

How to resolve this issue for the .NET Framework 3.5

Here are the steps that can be used to resolve this issue if you encounter it during .NET Framework 3.5 setup:

1. Click on the Start menu, choose Run, type cmd and click OK
2. Run this command:  reg delete "HKLM\SOFTWARE\Microsoft\NET Framework Setup\NDP\v3.5" /v Version /f
3. Run this command:  reg delete "HKLM\SOFTWARE\Wow6432Node\Microsoft\NET Framework Setup\NDP\v3.5" /v Version /f
4. Try again to download and install the .NET Framework 3.5 from this location

Another note about .NET Framework 3.5 setup

The above issues affects the standalone setup packages for the .NET Framework 2.0 SP1, the .NET Framework 3.0 SP1 and the .NET Framework 3.5.  However, since the 2.0 SP1 and 3.0 SP1 packages are also installed as prerequisites by .NET Framework 3.5 setup, that means this issue can also cause a different type of failure during .NET Framework 3.5 setup than the one described above.

The orphaned registry value issue is specific to the MSI-based versions of the .NET Framework 2.0 SP1 and 3.0 SP1, so it is only possible to see the problem below during .NET Framework 3.5 setup on Windows XP and Windows Server 2003 since those are the only OS's that you can install the MSI-based versions of the .NET Framework 2.0 SP1 and 3.0 SP1 on (as described here).

If the orphaned registry key is from .NET Framework 2.0 SP1 or 3.0 SP1 setup (as opposed to from 3.5 setup), then the behavior of .NET Framework 3.5 setup is a bit different than the behavior for the standalone .NET Framework 2.0 SP1 and 3.0 SP1 setups described above.  During .NET Framework 3.5 setup, an orphaned .NET Framework 2.0 SP1 or 3.0 SP1 registry value will cause an error dialog like the following will appear:

This is a generic error page that appears for all .NET Framework 3.5 installation failures.  In this orphaned registry value scenario, the error log that appears when clicking the link in this dialog displays misleading information about the cause of the failure.  If the system has the .NET Framework 2.0 SP1 registry value orphaned, the .NET Framework 3.5 setup error log will indicate that the .NET Framework 3.0 SP1 is failing.  If the system has the .NET Framework 3.0 SP1 registry value orphaned, the .NET Framework 3.5 setup error log will indicate that the .NET Framework 3.5 is failing like in the following log snippet:

[06/19/08,11:11:11] Microsoft .NET Framework 3.5 'package': [2] Error: Installation failed for component Microsoft .NET Framework 3.5 'package'. MSI returned error code 1603
[06/19/08,11:11:30] WapUI: [2] DepCheck indicates Microsoft .NET Framework 3.5 'package' is not installed.

However, if you look in the main install log file for .NET Framework 3.5 setup (%temp%\dd_dotnetfx35install.txt), you will not see any attempt to install the .NET Framework 2.0 SP1 or 3.0 SP1.  If your system has one of the 2.0 SP1 or 3.0 SP1 registry values present but does not have the corresponding MSI installed, then the same workarounds described above can help resolve this .NET Framework 3.5 installation issue as well.

Final note

There are many possible causes for .NET Framework 2.0 SP1, .NET Framework 3.0 SP1 and .NET Framework 3.5 setup failures.  The scenario in this blog post only describes one possibility.  If you are encountering a .NET Framework installation failure but have different symptoms or different information in your log files, you are likely running into a different problem.  In those cases, I suggest consulting the .NET Framework setup troubleshooting guide for links to other possible installation issues and workarounds, links to log file locations, links to readme files, etc.

Feature in Wix v3.0 to make it easier to test rollback custom actions

When authoring deferred custom actions (which are custom actions that change the system state) in an MSI, it is necessary to also provide an equivalent set of rollback custom actions to undo the system state change in case the MSI fails and rolls back.  The rollback behavior typically needs to behave differently depending on if the MSI is currently being installed, repaired or uninstalled.  This means that the following scenarios need to be accounted for when coding and testing a set of deferred custom actions to make sure that they are working as expected during both success and failure cases:

• Successful install
• Failed install
• Successful repair
• Failed repair
• Successful uninstall
• Failed uninstall

The scenario in this blog post provides an example of what can happen when rollback custom actions do not behave the way they should.

The failure cases are often difficult to simulate by unit testing the custom action code directly because deferred custom action code typically depends on state information provided to it by Windows Installer during an active installation session.  As a result, this type of testing usually requires fault injection in order to cause the rollback custom actions to be executed at the proper times during real installation scenarios.

Bob Arnson recently posted an item about a useful feature that he recently added to WiX v3.0 to help test rollback custom actions in an MSI.  This feature is a simple deferred custom action named WixFailWhenDeferred that will always fail when it is executed during the installation, repair or uninstallation of an MSI.  Adding the WixFailWhenDeferred custom action to your MSI allows you to easily inject a failure into your MSI in order to test your rollback custom actions.

There are 3 steps you need to take to use this technique to test the rollback custom actions in your MSI:

1.  Add a reference to the WixFailWhenDeferred custom action

To add a reference to this custom action, include the following in your WiX v3.0 setup authoring:

<CustomActionRef Id="WixFailWhenDeferred"/>

This will cause WiX to add the WixFailWhenDeferred custom action to your MSI, schedule it immediately before the InstallFinalize action and condition it to only run if the property WIXFAILWHENDEFERRED=1.

2.  Add a reference to the WixUtilExtension to your WiX project

When running WiX tools directly, this means adding a parameter to the light.exe command line like the following:

light.exe myproject.wixobj -ext WixUtilExtension.dll

When using Votive and Visual Studio for your WiX project, you can add a reference to WixUtilExtension by using the following steps:

• Right-click on the References node of the WiX project in the Solution Explorer and choose Add Reference...
• In the Add Reference dialog, click on the Browse tab.
• Locate WixUtilExtension.dll and click the Add button, then click OK to dismiss the dialog.

3.  Set the WIXFAILWHENDEFERRED property to 1 when installing the MSI to trigger rollback

The WixFailWhenDeferred custom action is conditioned to run only when the Windows Installer public property WIXFAILWHENDEFERRED=1.  After building an MSI that includes a reference to the WixFailWhenDeferred custom action, the following set of command lines can be used to simulate a set of standard install and rollback testing scenarios:

• Standard install:  msiexec.exe /i MyProduct.msi /qb /l*vx %temp%\MyProductInstall.log
• Install rollback:  msiexec.exe /i MyProduct.msi /qb /l*vx %temp%\MyProductInstallFailure.log WIXFAILWHENDEFERRED=1
• Standard repair:  msiexec.exe /fvecmus MyProduct.msi /qb /l*vx %temp%\MyProductRepair.log
• Repair rollback:  msiexec.exe /fvecmus MyProduct.msi /qb /l*vx %temp%\MyProductRepairFailure.log WIXFAILWHENDEFERRED=1
• Standard uninstall:  msiexec.exe /x MyProduct.msi /qb /l*vx %temp%\MyProductUninstall.log
• Uninstall rollback:  msiexec.exe /x MyProduct.msi /qb /l*vx %temp%\MyProductUninstallFailure.log WIXFAILWHENDEFERRED=1

Mailbag: How to install the Visual Studio 2008 SDK in silent mode

Question:

I am attempting to automate the installation of the Visual Studio 2008 SDK, but have not been able to figure out how to do so.  Running vssdk_sfx.exe /? just displays the normal setup UI and not a usage dialog, and I haven't been able to find any deployment documentation for this product.  How can I perform a silent install of the VS 2008 SDK?

Answer:

The Visual Studio 2008 SDK can be installed in silent mode by using the following steps:

1. Download the vssdk_sfx.exe installer from http://www.microsoft.com/downloads/details.aspx?familyid=30402623-93ca-479a-867c-04dc45164f5b and save it to your local hard drive
2. Extract the contents of the VS SDK setup by running the following:  vssdk_sfx.exe /x:%temp%\vssdk2008_setup /q
3. Run the VS SDK MSI in silent mode from within the extracted folder by running the following:  msiexec /i %temp%\vssdk2008_setup\vssdk.msi /qn /l*v %temp%\vssdk2008setup.txt
4. (optionally) Delete the copy of VS SDK setup that you extracted in step 2 by running the following:  rd /s /q %temp%\vssdk2008_setup

A couple of notes to keep in mind when doing this:

• When running VS SDK setup in full UI mode, there is a check-box that allows you to choose not to install the documentation.  The command line in step 3 above will install the default set of features for the VS 2008 SDK, which will include the documentation.  If you need to install a non-default set of features, you will need to figure out the feature names from the MSI and then add the ADDLOCAL property to the end of the command line in step 3.  The easiest way I've seen to do this is to enable Windows Installer verbose logging using these steps, then install in full UI mode with the documentation item unchecked.  After the installation completes, you can look at the verbose log file created by the VS SDK installer in the %temp% directory and copy the exact value passed in for the ADDLOCAL property from that log file.
• The command line in step 3 above will perform a fully silent install of the VS 2008 SDK.  If you want to perform an unattended install instead (meaning, there will be a small progress dialog during installation but no user interaction will be required), then you can change the /qn switch to /qb in the command line in step 3.  Note that if you do that, the progress dialog will be blank during installation because the VS SDK MSI does not include the necessary strings in the ActionText and Error tables.  In my experiments, I found that an unattended installation appears to be hung for a long time towards the end of installation while it is merging the SDK help documentation and completing the installation because the progress bar does not move and the progress dialog has no text.  I was able to see the installer continue to make progress by looking at the processes in Task Manager and by looking at the verbose log file at %temp%\vssdk2008setup.txt.

<update date="6/20/2008"> The VS SDK installer does not enable Windows Installer verbose logging by default.  Added a link to information about how to enable verbose logging if needed. </update>

 

Notes about a couple of possible issues while using the SubInAcl tool

A while back, I posted some instructions for using a tool from the Windows Resource Kit named SubInAcl that can be used to update file, folder and registry permissions.  This tool can help fix some types of access denied errors that can be encountered while trying to install products, hotfixes and service packs on Windows.

Since that original post, I have heard from some people who have run into various types of problems while attempting to install and use the SubInAcl tool.  I wanted to post more details about a few of these scenarios in case other folks run into similar issues in the future.

Issue 1 - Running SubInAcl reports an error on some non-English operating systems

On some non-English operating systems, customers have reported seeing errors like the following when trying to use the command lines listed in my previous blog post:

LookupAccountName : HKEY_CURRENT_USER:administrators 1337 The security ID structure is invalid.

The reason for this error is that on some non-English operating systems, the name of the Administrators group is translated into the OS language.  If you are running SubInAcl on a non-English OS where the name of the Administrators group is translated, you will need to update each of the command lines for SubInAcl to specify the translated name of the Administrators group.

Issue 2 - SubInAcl.msi fails to install

I have heard from a few people who were not able to get the SubInAcl.msi installer to work correctly on their systems, which prevented them from being able to use the tool.  If you run into an error while installing SubInAcl.msi to install this tool, you can get a copy of the tool that does not require a full installation from an alternate location by using the following steps:

1. Download SubInAcl.zip and save it to your local computer
2. Extract the contents of the zip file to a local folder on your system
3. Use the steps in the previous blog post to run SubInAcl from the extracted location

Note - you should first attempt to install and run SubInAcl.msi before downloading and extracting this zip file.  This zip file is only intended for cases where for some reason, SubInAcl.msi will not install correctly - which unfortunately can sometimes happen because of one of the same issues that SubInAcl is designed to fix.

Issue 3 - How to get SubInAcl to create a log file

SubInAcl is a console application, which means that the output that it prints will be displayed in the console window by default.  For the command lines listed in my previous blog post, SubInAcl prints a lot of information, and if any errors occur, it will quickly scroll off the screen and you won't be able to see the details of the errors.

For a console application like SubInAcl, running it from a cmd prompt and putting a greater than sign and then the name of a file at the end of the command line (such as > %temp%\subinacl_output.txt) will cause the output to be redirected to a file.  I recently updated the command lines in that post and in the example script I posted on my file server to use this syntax to redirect the output to a file instead of printing it to the console.

Note - creating a log file as described above will not work if you run SubInAcl from the Windows start menu.  It has to be run from a cmd prompt in order to allow the log file to be created.

Information about the err.exe tool I use to look up error codes when debugging setup issues

When I am attempting to investigate a setup-related failure, I typically end up looking at verbose log files.  These log files can contain information about a wide variety of failures, and the failures will typically include some detailed error information (such as the information reported by the GetLastError and FormatMessage APIs or something equivalent to them).  In the case of verbose Windows Installer log files, I find the error information in most cases by searching for the text "return value 3" as described in this blog post.

Once I find the error information, I can often recognize the error codes from my past experience.  However, there are also a lot of cases where I run into error codes that I do not recognize from past experience.  When that happens, I use a tool that helps me translate error codes (normally HRESULT values from function calls) into more readable information.  Doing this can help me better understand what the error means, which in turn can help give ideas for what might be causing the error and what types of fixes might help eliminate the error.

Recently, I discovered that the tool that I've been using to do error code translation is available on the Microsoft Download Center so that anyone can get a copy and use it themselves.  You can find the tool, called Err.exe, at http://www.microsoft.com/downloads/details.aspx?familyid=be596899-7bb8-4208-b7fc-09e02a13696c.  This site describes the tool as an Exchange Server Error Code Look-up, but this tool actually aggregates information from 172 sources (header files, etc) from Windows and various other products around Microsoft and is not only useful for Exchange Server issues.

For example, it includes information from corerror.h (a header file that ships with the .NET Framework SDK and Windows SDK) so it can report error information for some types of .NET Framework errors.  Here are a couple of specific examples of the output produced by err.exe:

For error code 0x8002802F (described in more detail here):

Err.exe 0x8002802F
# for hex 0x8002802f / decimal -2147319761 :
  TYPE_E_DLLFUNCTIONNOTFOUND                                    winerror.h
# Function not defined in specified DLL.
# 1 matches found for "0x8002802F"

For error code 0x80070005 (described in more detail here):

Err.exe 0x80070005
# for hex 0x80070005 / decimal -2147024891 :
  COR_E_UNAUTHORIZEDACCESS                                      corerror.h
# MessageText:
# Access is denied.
  DIERR_OTHERAPPHASPRIO                                         dinput.h
  DIERR_READONLY                                                dinput.h
  DIERR_HANDLEEXISTS                                            dinput.h
  DSERR_ACCESSDENIED                                            dsound.h
  ecAccessDenied                                                ec.h
  ecPropSecurityViolation                                       ec.h
  MAPI_E_NO_ACCESS