Thoughts about setup and deployment issues, WiX, XNA, the .NET Framework and Visual Studio
All postings are provided AS IS
with no warranties, and confer no rights. Additionally, views expressed
herein are my own and not those of my employer, Microsoft.
The official deployment guides for system administrators and application developers have been posted on MSDN, and I wanted to provide links here to help raise visibility for them. Here they are along with some additional information about what is contained in each of them:
Microsoft .NET Framework 3.5 Deployment Guide for Application Developers
You can find the deployment guide for application developers at the following location:
The deployment guide for application developers is targeted at developers creating applications that depend on the .NET Framework 3.5 and that will need to incorporate the .NET Framework 3.5 into their installation process. It contains the following information:
Microsoft .NET Framework 3.5 Administrator Deployment Guide
You can find the administrator deployment guide at the following location:
The administrator deployment guide is targeted at system administrators that manage software installation on corporate networks and who want to plan a deployment of the .NET Framework 3.5 to networks that they manage. It contains the following information:
Links with additional information
I have previously posted a few items on my blog that are not covered (or are touched on but not covered in much detail) in the above deployment guides. Here are links to those posts in case you need additional information about deploying the .NET Framework 3.5 or its prerequisites (such as the .NET Framework 2.0 SP1 and/or 3.0 SP1):
A little while ago, I posted this item on my blog that describes a potential issue when installing the .NET Framework 3.5 on a non-English operating system. Over this past weekend, I noticed a related item on Aaron Ruckman's blog that I wanted to link to here. In his post, Aaron describes some .NET Framework installation scenarios related to language packs.
To summarize his post, there are a few key things to keep in mind when installing the .NET Framework 3.5 along with .NET Framework 3.5 language packs:
1. Using the /lang switch with .NET Framework 3.5 setup
By default, the .NET Framework 3.5 setup will detect the language of the OS that setup is running on and attempt to install a .NET Framework 3.5 language pack to match the OS language if one is available. The .NET Framework 3.5 setup contains a command line switched named /lang. This switch allows you to override the default behavior and force .NET Framework 3.5 setup to install a specific language pack (or no language packs at all) instead of installing a language pack that matches the OS language.
For example, this command line will cause the .NET Framework 3.5 to not install any language packs:
This command line will cause the .NET Framework 3.5 to install the French language pack:
Note that the /lang switch only works during initial installation of the .NET Framework 3.5. If you run .NET Framework 3.5 setup in repair mode and attempt to pass in the /lang switch, the value you provide with /lang will be ignored.
2. Creating an installable .NET Framework 3.5 layout that includes language packs
I previously posted some information about creating an installable layout for the .NET Framework 3.5 in this blog post. If you want to create an installable layout for the .NET Framework 3.5 that includes one or more .NET Framework 3.5 language packs, you can first follow the instructions in that previous blog post to create an installable layout for the .NET Framework 3.5 core package. Then you can download and copy the setup packages for the .NET Framework 3.5 language packs into the .NET Framework 3.5 layout you previously created. There are separate language packs for each processor architecture, and they must be copied to the appropriate sub-folders of the .NET Framework 3.5 layout as follows:
3. Deploying the .NET Framework 3.5 with multiple language packs
The most reliable way to deploy the .NET Framework 3.5 along with one or more .NET Framework 3.5 language packs is to first deploy the .NET Framework 3.5 core package and then individually deploy each of the desired language packs. This method will prevent the .NET Framework 3.5 from installing potentially undesired language packs depending on the language of the user's OS. The steps to do this look like the following:
I heard from a customer who ran into an interesting issue during Visual Studio 2008 setup that I hadn't seen until now. I wanted to post a description of the issue, how we diagnosed it and how to work around the issue in case anyone else runs into a similar issue in the future.
Description of this issue
On this customer's system, the Web Authoring Component prerequisite component failed to install and Visual Studio 2008 setup failed as a result. There are many possible causes for this type of failure, so we need to dig deeper to try to find the exact cause of the failure.
How to diagnose this issue
Visual Studio 2008 setup runs the Web Authoring Component setup package in silent mode, so the next step is to take a look at the log file for the Web Authoring Component to narrow down the issue further. This issue will cause the following information to be written to the log file for the Web Authoring Component (named %temp%\SetupExe(*).log):
Catalyst valid path check failed: The path c:\Program Files\\Microsoft Web Designer Tools is invalid
Catalyst valid path check failed: The path c:\Program Files\\Microsoft Web Designer Tools is invalid
Notice that there is an extra backslash between Program Files and Microsoft Web Designer Tools in this log file. I had the customer check their registry and we found that the path to the Program Files folder was being stored there with a trailing backslash, but Windows typically stores the path to Program Files and other system folders without trailing backslashes.
In this scenario, it is also possible to run Web Authoring Component setup directly from <VS install path>\WCU\WebDesignerCore\WebDesignerCore.exe in order to see a specific error message instead of looking at the log files.
How to work around this issue
To work around this issue, you can change the value that Windows uses for the Program Files directory on your system by doing the following:
One note about this issue - the Web Authoring Component setup package uses the same setup wrapper as the Office 2007 family of products. It appears that other Office 2007 products may have similar installation errors if the ProgramFilesDir value has a trailing backslash like this.
When the .NET Framework 3.0 shipped, 3 packages were made available for download - a 2.8 megabyte web download bootstrapper, an approximately 50 megabyte full install package for x86 processor architectures and an approximately 90 megabyte full install package for x64 processor architectures.
When the .NET Framework 3.5 shipped, 2 packages were made available for download - a 2.7 megabyte web download bootstrapper and an approximately 200 megabyte full install package.
Why is the .NET Framework 3.5 full install package so much larger than the 3.0 full install package, and what exactly does it contain? If I need to redistribute the .NET Framework 3.5 as a part of my installer, do I have any options to reduce the size?
The .NET Framework 3.5 full install package includes all prerequisites and product components that could need to be installed for any processor architecture. Basically, it is the union of the x86, x64 and ia64 packages and prerequisites. The .NET Framework 3.5 includes the following prerequisites in addition to the main .NET Framework 3.5 product payload:
The 200 megabyte full install package was not really designed to be redistributed as is by installers that require the .NET Framework, although it will work fine for that purpose if the installer does not have any sensitivity to the larger package size.
Installers that want to reduce the .NET Framework 3.5 payload size have a couple of options:
There is some more specific .NET Framework 3.5 deployment documentation that will be published soon to provide more details about how to redistribute the .NET Framework 3.5 in various types of scenarios. The prerequisites and install options will be described in much more detail than I am going into in this blog post once it is published. I will update my blog with a link to the .NET Framework 3.5 deployment guide once it is available.
As a side note, I have seen some size comparison charts that show the .NET Framework size growing from 20 megabytes in 1.0 up to 50 megabytes in 3.0 and then 200 megabytes in 3.5. It looks like this type of size chart was based on the size of this full install package for the .NET Framework 3.5. That isn't really an accurate comparison though. The 50 megabyte size for the .NET Framework 3.0 only includes x86 components, so an equivalent size for x86 components for the .NET Framework 3.5 is approximately 57 megabytes. That means that the size of features that are new between the .NET Framework 3.0 and 3.5 is approximately 6 or 7 megabytes. That is still fairly large for something that has to be redistributed by other installers for their applications to use at runtime, but it is not nearly as dramatic as saying that the .NET Framework 3.5 is 200 megabytes in size compared to 50 megabytes for the .NET Framework 3.0.
Description of the issue
Recently, I was contacted by a customer who is running Windows Vista Home Premium, but who was unable to launch Windows Media Center. There was not a shortcut available on the Windows Vista start menu, and when they tried navigating directly to c:\Windows\eHome\ and running ehShell.exe directly, they received an error dialog with the following information:
The dialog looks like this:
In Windows Vista, a Group Policy setting was introduced to allow administrators to configure systems to not allow Windows Media Center to run. This setting was designed to be used in locked down environments such as corporate networks where Windows Media Center is not needed on a day-to-day basis. However, it is possible that this setting could end up getting configured on home systems as well.
How to work around the issue
If you see the above dialog when attempting to launch Windows Vista Media Center, you can use the following steps to disable the Windows Media Center Group Policy settings using the Group Policy Object Editor in Windows Vista:
If you see this dialog on your system, it is important to check both the Computer Configuration (per-machine) and User Configuration (per-user) locations for this setting because if either one of them is enabled, Windows Media Center will not launch and will display the above dialog.
What is happening behind the scenes
Behind the scenes, the Group Policy Object Editor sets the following registry values:
The logic for this setting is backwards from what you might typically expect because the setting indicates whether or not Windows Media Center should be disabled (as opposed to enabled). If the setting is enabled, it means that Windows Media Center will not be allowed to run. The MediaCenter registry value will be set to 1 in that case. If the setting is disabled or not configured, it means that Windows Media Center will be allowed to run. If the setting is disabled, the MediaCenter registry value will be set to 0. If the setting is not configured at all, the MediaCenter registry value will not exist on the system.
Where to find additional information
This Windows Media Center Group Policy setting and others that are supported in Windows Vista are described in more detail in the Windows Vista Group Policy Settings Reference. This spreadsheet is available for download at http://www.microsoft.com/downloads/details.aspx?FamilyID=41dc179b-3328-4350-ade1-c0d9289f09ef.
Yesterday, I posted some information about a Group Policy settingthat can prevent Windows Media Center from launching on a Windows Vista Home Premium or Ultimate system. Since then, I have heard from a couple of people who have been receiving the same error message but who did not have this Group Policy setting enabled on their systems. After some further investigation, I found another possible cause of this type of error that I wanted to describe here as well.
To summarize some information from my previous post, it is possible that launching Windows Vista Media Center will fail and will instead display the following error message:
I looked at the startup code for Windows Media Center, and found that in addition to the Group Policy setting that I previously described, it is also possible for this error dialog to appear if Windows Media Center is marked as disabled in the Set Program Access and Computer Defaults control panel on Windows Vista.
How to work around the issue
You can use the following steps to enable Windows Media Center in the Set Program Access and Computer Defaults control panel if it is currently disabled:
Note - you do not have to select the radio button to the left of the Windows Media Center to make it the default media player if you don't want to, but the Enable check box must be checked or Windows Media Center will refuse to launch on your system.
The Enable access to this program check box for the Windows Media Center Item in the Set Program Access and Computer Defaults control panel will result in the following value being changed in the registry on Windows Vista:
[HKEY_LOCAL_MACHINE\SOFTWARE\Clients\Media\Windows Media Center\InstallInfo]IconsVisible
If the IconsVisible value is set to 0, then Windows Media Center will not run on a Windows Vista system.
<update date="10/7/2011"> Fixed broken link to image embedded in this post. </update>
Since the .NET Framework 3.5 shipped, I've written a few blog posts about some of the setup and deployment issues that can affect this product. Behind the scenes, the installer for the .NET Framework 3.5 has some architectural differences from previous releases of the .NET Framework that I've alluded to in a few of those previous posts, and I wanted to take a little time to describe these differences in a bit more detail.
How the .NET Framework 2.0, 3.0 and 3.5 fit together
The .NET Framework 3.5 is essentially an add-on that introduces new features to the .NET Framework 2.0 and 3.0 products but continues to run on the version of the common language runtime (CLR) that shipped in the .NET Framework 2.0. This is similar to the model introduced in the .NET Framework 3.0, which is essentially an add-on for the .NET Framework 2.0 but did not introduce a new version of the CLR. As a result of this add-on model, the .NET Framework 3.0 setup requires the .NET Framework 2.0 as a prerequisite, and the .NET Framework 3.5 requires both the .NET Framework 2.0 and the .NET Framework 3.0 as prerequisites. This is sometimes called a "nesting doll" model for creating a product.
.NET Framework 3.5 setup includes service packs for both the .NET Framework 2.0 and 3.0. These service packs install as prerequisites because some of the new features introduced in the .NET Framework 3.5 require updates to the originally released versions of both the .NET Framework 2.0 and 3.0.
When the .NET Framework 3.5 project first got started, the service packs for the .NET Framework 2.0 and 3.0 were being built as a series of Windows Installer patches (MSP files). It quickly became clear that the number of files being changed by these service packs was going to lead to the service packs being nearly as large as the original versions of the products. This would mean that any customers needing to redistribute the .NET Framework 3.5 with their products would have to include the original versions of the .NET Framework 2.0 and 3.0 and nearly equal-sized service packs for each of them, which would have caused the overall size to grow even larger than it already has.
As a result, the decision was made to create slipstream releases for both the .NET Framework 2.0 SP1 and 3.0 SP1. These slipstream releases include the original payload plus all of the fixes that are a part of the service packs. They will successfully install on systems that had the original releases of the .NET Framework 2.0 and 3.0 as well as on systems that did not yet have either version installed (whereas, standalone service packs only install if the original version of the product was previously installed).
.NET Framework 2.0 SP1 and 3.0 SP1 slipstream behind-the-scenes details
Typical slipstreams for MSI-based products are produced by building a layout that is identical to the original release, but with updated binary content. However, the slipstream releases of the .NET Framework 2.0 and 3.0 are constructed differently behind the scenes than a typical slipstream release.
The .NET Framework 2.0 SP1 and 3.0 SP1 setup packages consist of the following payload:
The .NET Framework 2.0 SP1 and 3.0 SP1 setup packages include logic to do the following:
Each of the MSPs installed during .NET Framework 2.0 and 3.0 SP1 setup is marked to not allow uninstall, which is why you see a series of updates that do not have Uninstall buttons listed in Add/Remove Programs for each of these products (if you check the Show updates box at the top of the Add/Remove Programs control panel).
Implications of this slipstream design
There are a few interesting results that fall out of this slipstream design that warrant a bit more in-depth discussion:
It is also interesting to note that the Silverlight 1.0 installer uses a similar packaging scheme behind the scenes. It includes an MSI that does not have any files of its own, and an MSP that includes the file payload.
<update date="1/21/2008"> Added links to the instructions for creating administrative install points for the .NET Framework 2.0 SP1 and 3.0 SP1 so they'll be easier to find </update>
I often receive emails and blog comments from customers who are having trouble installing the .NET Framework 3.5. Many of the issues that I have been asked about are documented in various places but are unfortunately hard to find with some web searches. In order to try to improve the ability of search engines to find these documents, I wanted to post links to them here.
The following link is for the official .NET Framework 3.5 readme, which includes known installation issues and workarounds:
In addition to the readme, here is a summary of some other useful items regarding .NET Framework 3.5 setup troubleshooting:
As always, if you run into .NET Framework installation/deployment issues that you are having trouble finding solutions for at any of the above locations, please post a comment on one of my blog posts or contact me and I will attempt to help resolve the issue and then update my blog to hopefully help others in the future as well.
Since Visual Studio 2008 shipped last November, I have been asked a few times via my blog about if/when the Votive Visual Studio add-in that is a part of the WiX toolset will support integrating into VS 2008. It was not very well publicized initially, but the version of Votive included with WiX v3.0 has supported integrating into VS 2008 since the VS 2008 beta 2 timeframe. Specifically, this has been available since the 3.0.3328.0 build of WiX v3.0 on SourceForge. The version of Votive in builds between 3.0.3328.0 and 3.0.3621.0 were built using the beta 2 version of VS 2008 and the August 2007 CTP of the VS 2008 SDK. However, those builds of Votive will work correctly when installed on a system that has the final release of VS 2008 installed as well as systems that have VS 2008 beta 2 installed.
Votive in WiX v3.0 has also recently been updated to build with the final release of VS 2008 and the VS 2008 SDK. Builds starting with the 3.0.3621.0 build on the WiX releases page contain these changes. An announcement was also added to the front page of the WiX SourceForge site about Votive support for VS 2008. That announcement states that builds starting with 3.0.3607.0 contain these Votive build changes, but that build number is slightly incorrect because of some issues related to porting the changes into the source tree available on SourceForge.
One of the nice things about Votive in Visual Studio 2008 is that you no longer have to install ProjectAggregator2.msi prior to installing wix3.msi in order to be able to install and use Votive in the Visual Studio 2008 IDE. You can simply install VS 2008 standard edition or higher, then install wix3.msi and you're ready to launch the VS IDE and create WiX projects using the Votive add-in.
The MSIs for the XNA Game Studio Express 1.0 and 1.0 Refresh releases were created using WiX v2.0. The MSIs for the recently released XNA Game Studio 2.0 product were created with a recent build of WiX v3.0. The decision to move from WiX v2.0 to v3.0 is interesting so I wanted to describe how this decision came about behind the scenes.
XNA Game Studio Express 1.0 and 1.0 Refresh integrate into Visual C# 2005 Express Edition only. As noted in this introductory blog post, XNA Game Studio 2.0 now integrates into Visual Studio 2005 standard edition and higher in addition to Visual C# 2005 Express Edition.
XNA Game Studio 2.0 ships a Visual Studio starter kit for a game named Spacewar. This starter kit takes the form of a .zip file for the Windows version of the game and a .zip file for the Xbox 360 version of the game. Each of these .zip files is approximately 30 megabytes in size, and they must be installed to separate locations in order to integrate correctly into Visual C# 2005 Express Edition and the up-level editions of Visual Studio 2005.
In order to minimize the size of the payload for XNA Game Studio 2.0, we needed to find a solution that would allow us to carry only one source copy of each .zip file, but install each .zip file to multiple locations on the system. In addition, we decided to continue to use embedded cab files inside of each MSI we create to deliver the setup payload.
We could have used the DuplicateFile table, but there are some potential limitations with using this table that are related to conditional installs, repairs and patching, so we decided to not use it in XNA Game Studio 2.0 setup if we could avoid it.
Fortunately, WiX v3.0 introduced a new feature last year known as smart cabbing. This feature allows the WiX build process to embed a single physical copy of each file in the cab files it creates if the file is referenced by multiple File elements. The WiX toolset will apply this feature automatically (and not require any setup authoring changes for the feature to take effect) if you author your setup to include multiple files with the same source location defined for them.
By switching to WiX v3.0 and gaining access to the smart cabbing feature, we were able to eliminate 60 megabytes of payload from the XNA Game Studio 2.0 setup package without adding any new setup authoring. This resulted in an overall packages size of approximately 100 megabytes as opposed to 160 megabytes - a size reduction of 37.5%!
Niall Ginsbourg announced the launch of his new Big Screen Global web site and the release of the Big Screen Photos v2 and Big Screen Weather v2 applications for Windows Vista Media Center.
I have been using the beta versions of a few of the Big Screen applications for a while and they're really nice. I encourage you to check out these links for additional information about the Big Screen product line:
A new Channel9 video has been posted that I wanted to link to here. The video is located at http://channel9.msdn.com/ShowPost.aspx?PostID=374129, and in it, Robert Flaming discusses application compatibility issues that can affect Windows Installer-based setups on Windows Vista and Windows Server 2008.
If you are a setup developer and will be targeting Windows Vista or Windows Server 2008 for your MSI-based setup, I encourage you to check out this video.
One of the key application compatibility challenges that Robert discusses in this video is how to author custom actions that will interact correctly with UAC on Windows Vista and Windows Server 2008. Robert has written a series of blog posts that contain much more detail about how Windows Installer interacts with UAC, and I encourage you to also review these posts if you are creating MSIs that will install on Windows Vista and/or Windows Server 2008.
Over the weekend, I noticed a couple of posts on Bob Arnson's blog that I wanted to link to here. Bob indicated in this post that he was going to start publishing more detailed information about the changes included in each weekly build of WiX.
For those of you familiar with WiX, each build includes a text file named history.txt that includes high-level summaries of each change that gets checked in. The level of detail in history.txt is not very deep, and it varies based on which person checked in each change. In addition, the contents of history.txt has not been available on a web page in the past. I think these factors will make a web-based list of changes fairly useful to developers who use WiX in their setup/build processes.
To kick off this effort, Bob posted a list of changes and fixes available in WiX build 3.0.3711. You can view this initial list of changes at http://www.joyofsetup.com/2008/01/13/highlights-of-wix-v303711/.
I also encourage you to keep an eye on Bob's blog in the future for additional information about changes in WiX.
The XNA team has published a new survey on the Connect site to gather feedback about the XNA Game Studio 2.0 product. The answers to this survey will be used to help guide the team as it makes plans for the future of the XNA Game Studio product line. If you are an experienced XNA Game Studio user or even if you are holding off on trying XNA Game Studio for one reason or another, we encourage you to visit the site and take the survey. You can find the survey at this link:
A couple of important notes about this survey: