The Windows Vista Developer Story: Application Compatibility Cookbook

July 2006
Revised October 2006

The Windows Vista Developer Story includes content for developers, and other technology experts and managers, interested in an in-depth exploration of some of the new and extended features in Windows Vista. It is released to the Windows Vista Developer Center in the form of Articles, published approximately one every two weeks. Those Articles are only a summary of the Windows Help file, which can be downloaded here.

Note   This topic is pre-release documentation and is subject to change in future releases.

Note   To provide feedback about the articles, please send email to Vistadev@microsoft.com.

Contents

Introduction
Thirty-Minute Compatibility Check
Operating System Versioning
User Account Control
User Account Control - Application Update Guidelines
Windows Resource Protection (WRP)
Internet Explorer Protected Mode
Windows Vista 64-bit
Microsoft Graphical Identification and Authentication (GINA)
Session 0 Isolation
Networking: TCP/IP Stack and the Windows Filtering Platform
Networking: Kernel Mode IP Helper APIs
Networking: IPv6
Networking: Turning Off the Windows Firewall
Compatibility Risks
Help and Support Center
Assistance Platform Client
Default Programs
Program Compatibility Assistant (PCA) in Windows Vista - Customer Ready Documentation
Graphical Device Interface (GDI)
Painting (WM_PAINT) Behavior Differences
Rendering Performance
UIPI (GUI Portion of User Account Control)
High DPI Scaling
PNG Icons
Named Pipe Hardening
SPAP Deprecation (Pstore)
WMI Providers: Default Security Hosting Model
Volume Shadow Copy Service
Standard User Analyzer
Help Engine Support
Junction Points and Backup Applications
Notes for Backup and Recovery
Search the Internet
See Also

Introduction

Microsoft Windows Vista introduces the next generation operating system technology and software development platform that will be used by application developers and enterprises worldwide. As part of enhancing the security and user experience of Windows Vista, many new features have been introduced and existing features have been improved.

While Windows Vista is highly compatible with most of the applications written for Microsoft Windows XP, Microsoft Windows Server 2003, and their service packs, some amount of compatibility breaks are inevitable due to new innovations, security tightening, and increased reliability. Overall, Windows Vista compatibility is high, and Microsoft is continuously striving to achieve the best possible compatibility solutions for existing applications for Windows Vista.

This document is the first step for application developers to become familiar with how to verify the compatibility of their applications. This document also provides an overview of the few known application incompatibility issues in Windows Vista and provides links to detailed white papers and other developer guidance.

There are several new features that will enable developers to troubleshoot and workaround applications that do not function properly under Windows Vista, such as the following:

• Compatibility tab.

  Users can right-click the shortcut or the EXE and apply the Windows XP SP2 compatibility mode to allow the application to work as it did on Windows XP. Additionally, the user can choose Run this program as administrator if the application needs administrator privileges and the user possesses those rights. For more information, see the "User Account Control" section in this document.

Thirty-Minute Compatibility Check

This section provides guidance on how to test and evaluate the compatibility of an application on Windows Vista. There are two primary scenarios to test for compatibility on Windows Vista, as follows.

Working with a Clean Installation of Windows Vista

1. Install Windows Vista on a test machine.
2. Install the application on Windows Vista. If a prompt is displayed requesting permission to install the application, click Permit and continue. If installation succeeds, go to step 6.
3. If the application installation failed and no installation permission prompt was displayed, then right-click the installer EXE and choose Run this program as administrator and re-install the application. If the install succeeds, go to step 6.

   Note   This step is not necessary if an MSI is used to install.

4. If you receive any errors, such as OS version, CLSID registration, or file copy, then right-click the installer EXE file, choose the Compatibility tab, and choose the Windows XP SP2 compatibility mode.
5. Go back to step 2. If you cannot install the application, go to step 9.
6. The application should now be installed.
7. Launch the application. If the application did not launch properly or if errors are displayed, apply the Windows XP SP2 compatibility mode to the application EXE and try again.
8. If the application launches successfully, run through the full suite of tests that would typically be used to test the application on Windows XP. Verify your application functionality and confirm that the application performs properly. If all major functionality tests pass, go to step 10.
9. If the application does not install, launch successfully, crashes, encounters an error, or fails major functionality tests, it may be one of the small set of applications that are impacted by Windows Vista changes. Use the topics in this document to check your application.
10. You have completed the scenario.

Working with an Upgrade from Windows XP Service Pack 2

1. Install Windows XP SP2 on a test machine and then install the application. Verify all the functionality of the application before proceeding.
2. Upgrade the test machine to Windows Vista. Follow the Windows Vista setup and upgrade instructions. Once the upgrade is complete, log on as you would on Windows XP.
3. Launch the application. If the application did not launch properly or if errors are displayed, apply the Windows XP SP2 compatibility mode to the application EXE and try again.
4. If the application launches successfully, run through the full suite of tests that would typically be used to test the application on Windows XP. Verify your application functionality and confirm that the application performs properly. If all major functionality tests pass, go to step 6.
5. If the application does not install, launch successfully, crashes, encounters an error, or fails major functionality tests, it may be one of the small set of applications that are impacted by Windows Vista changes. Use the topics in this document to check your application.
6. You have completed the scenario.

If both scenarios have been completed and the application has performed properly, then the application functions correctly under Windows Vista. For information about obtaining certification for your application, see the Windows Vista Home Page.

Links

• Windows Internet Explorer 7: Beta 2 Preview IT Pro Checklist
• Windows Vista Home Page

Operating System Versioning

Feature Impact

High

Brief Description

The internal version number for Windows Vista is 6. The GetVersion function will now return this version number to applications when queried.

Note   This is the next major version number from Windows XP (version 5.x).

Manifestation

The manifestation of this version change is very application-specific, as follows:

• Any application that specifically checks for the OS version will get a higher version number.
• Application installers may prevent themselves from installing the application and applications may prevent themselves from starting.
• Applications may warn users and continue to function properly.
• Some applications may become unstable or crash.

Mitigation

Most applications will function properly on Windows Vista because the application compatibility in Windows Vista is very high. However, for applications and installers that check for OS version, a Compatibility mode is provided in Windows Vista.

Users can right-click the shortcut or the EXE and apply the Windows XP SP2 compatibility mode from the Compatibility tab. In most cases, this should enable the application to work as it did on Windows XP without a need for any changes to the application.

Remedies

• Generally, applications should not perform OS version checks or, at minimum, always accept version 6 or later for the OS. This behavior should be followed unless there is a very specific legal, business, or system-component need to do this version check.
• Application installers should not use 16-bit installers to ensure 64-bit system compatibility.
• Ensure that any drivers an application uses are user mode drivers as much as possible to maintain multiplatform (32-bit and 64-bit) compatibility.

User Account Control

Feature Impact

High

Brief Description

A fundamental step toward increasing the security of Windows is enabling interactive users to run with a standard user account, which gives them access to only a limited set of permissions and privileges. By default, Windows Vista will run every application as a standard user even if you log on as a member of the administrator's group. Conversely, when users attempt to launch an application that has been marked as requiring administrator permissions, the system will explicitly ask them to confirm their intention to do so. Only applications running with administrator privileges can modify system and global settings and behavior. This feature of Windows Vista is the User Account Control (UAC).

Manifestation

• Custom installers, uninstallers, and updaters may not be detected and elevated to run as administrator.
• Standard user applications that require administrative privileges to perform their tasks may fail or not make this task available to standard users.
• Applications that attempt to perform tasks for which the current user does not have the necessary permissions, may fail. How the failure manifests itself is dependent upon how the application was written.
• Control panel applications that perform administrative tasks and make global changes may not function properly and may fail.
• DLL applications that run using RunDLL32.EXE may not function properly if they perform global operations.
• Standard user applications writing to global locations will be redirected to per-user locations through virtualization.

Remedies

Quick solution for custom installers:

• A user can launch the installer or updater by right-clicking and selecting Run this program as administrator.
• Apply an application compatibility fix to indicate that specific installers require elevation. To do so, right-click the shortcut or the EXE and apply the Windows XP SP2 compatibility mode from the Compatibility tab.

Quick solution for applications that require administrative privileges to perform system modifications or write to privileged areas:

• Corporate users will be able to apply an application compatibility fix to indicate that the legacy application requires administrator permissions or privileges to run correctly.
• Reducing the restrictions of access control lists (ACLs) on certain restricted files may help applications that attempt to write these files.
• Check the virtualized folders or registry keys to see if applications are accessing something that requires administrator privileges. This information can be used to remove the requirements of accessing administrator-protected locations from future versions of the application. For more information about virtualized files, folders, and locations, see the "Links" section.
• Wrap a "Run DLL as an app" DLL call in a separate EXE and include a manifest for this EXE to require elevated privileges.

Compatibility test:

• Any install, uninstall, or update scenario should prompt the user for consent or credentials. Upon receiving user approval, the action should succeed.
• Attempt to reproduce the failing scenario as the built-in-administrator. If this scenario passes, the failure is probably due to a lack of privileges.
• Use the User Account Control predictor tool of the Application Compatibility Toolkit's Compatibility Administrator to identify those areas of an application that are performing administrator operations.

Leverage Windows Vista capability solution:

• Windows Vista based applications need to:
  • Follow the prescribed guidelines found in the Windows Vista LOGO program and user experience (UX) guidelines documentation (see the "Links" section).
  • Use embedded manifests to indicate their specific requestedExecutionLevel (formerly known as RunLevel).
  • Separate all administrative and non-administrative functions into separate EXEs. All functions that need higher privileges should be in a separate executable EXE with manifested execution level or a COM object running with administrative privileges. Launch the administrative tasks only when required. This holds true for all applications.
• For applications that are not specifically administrative in nature, modify code to eliminate need for administrator permissions or privileges.
• For applications that are only used by administrators, mark the application so it will run with administrator permissions or privileges.
• When updating an application, use a separate updater EXE to update the target application.
• Control panel applications must move away from .cpl files to .exe files, and include a manifest for their EXE-based control panel applications that specifies the execution level required.
• DLLs running under RunDLL32.EXE that need elevation should be modified into an executable EXE with its elevation level indicated in its manifest.
• Always open files and registry keys with read-only access when possible. Use read-write access only when needed and revert the permissions back to read-only once the operation is complete.

Links

• Windows Vista security
• Windows Vista UAC main page
• Getting Started with User Account Control
• Developer Best Practices and Guidelines for Applications in a Least Privileged Environment
• Windows Vista User Experience
• File and registry virtualization details
• Slides from the Microsoft Professional Developers Conference (PDC) 2005; search for FUN406
• UACBlog
• UAC-related question on Microsoft Forums
• Aaron Margosis' WebLog; search for "Not running as administrator"

User Account Control - Application Update Guidelines

Feature Impact

Medium

Brief Description

Many existing applications have a tendency to incorporate update functionality in their application. The goal of embedding update functionality is to ensure that the client is running the most up to date binary that the ISV can offer.

It has been found that a number of applications, when they perform their updating functions, require more privileges than that of a Standard user. Often, the per-machine files that were laid down during installation need to be serviced. As per the UAC model for running and installation applications, only the elevated administrator in Admin Approval Mode Admin has sufficient privileges to perform these actions.

The Windows Vista Installer Detection heuristics detect many applications' updaters correctly and elevate the updater process appropriately so that the update completes successfully on elevation. However, a few areas remain where application updates cannot complete successfully. For example:

• Out of Process Updaters not Install Detected—Updaters that do not get detected through install detection heuristics.
• Multi-purposed executables/ In-process updates—Overloaded executables that perform more than one operation. For example, the binary is both the main application and the updating application OR the multi-purposed executable runs as a thread within the application

Manifestation

Application update functionality fails

Remedies

Out of Process updaters not Install Detected

• This is an issue that could occur within any enterprise and could result in that enterprise requiring an application to be run with Administrator privileges. If an application updates itself by using a separate process that is not installer detected then this separate process should be marked as requiring Administrator privileges using App Fix.
• Updaters that do not work as a user will prohibit an enterprise from running with least privilege.
• The updater should be written as a separate process with a desired run level of requires Administrator.
  • This process should only execute when necessary for updating purposes. Checking for whether the program needs updates should be done as the user.

Multi Purpose Executables/In-Process Updates

On Vista, there is no good way to create a multi-purpose executable that performs updates because you can't toggle the state under which an executable is run. Consequently, the executable will always have to run as Administrator. Instead, applications should follow one of the following methods to perform updates.

1. Utilizing Patching technology in MSI (Latest versions of Windows Installer, InsallShield, Wise etc. support this).
   • MSI is a key installer technology because it provides the ability to manage updates for you.
   • Use MSI to create your initial installer and embed a certificate in the MsiPatchCertificate table.
   • Create an update for your application and sign it with the previously specified certificate.
   • MSI will perform the elevation for the application when applying the patch.

   Note   The main advantage of this method over others is that it works with Standard User, and keeps the game secure. It provides a better user experience because the Standard User account doesn't have to ask an Administrator to install the patch or request permanent Administrator privileges to play the game.

2. Using other custom installer mechanisms.
   • This is discouraged for the enterprise environment because this will prohibit user from running as non-Administrators
   • The updater should be written as a separate process with a desired run level of requiresAdministrator.

     Note   This process should only execute when necessary for updating purposes. Checking for whether the program needs updates should be done as the user.

3. Updating while running as a "Standard User" applications.
   • Updating can occur as a Standard User when using ClickOnce technology. Again, this is an install platform that allows the user to deploy applications within it and handles the updating for the app writer.

Links

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/patching_and_upgrades.asp

http://msdn.microsoft.com/msdnmag/issues/04/05/ClickOnce/

Windows Resource Protection (WRP)

Feature Impact

High (may block the application from installing or running)

Brief Description

As an initiative to increase system stability, predictability and reliability, Windows Resource Protection (WRP) protects Windows read-only resources: specifically OS files, folders, and registry keys that are non-configurable by design. See Protected Resource List.

WRP enforces this protection using Windows Security by specifying special security descriptors on the resource. Any process, including those running as administrator or system, do not have rights to make changes to WRP resources; they can read and execute. Full access to WRP resources is restricted to Windows Modules Installer service.

As a result, read-only system state is protected from the inadvertent impact of application installs and administrator modifications, which improves system stability.

Manifestation

Applications (typically this happens during application install and uninstall) will not succeed in replacing or modifying protected OS resources, with the following results:

• Attempts to replace, modify, or delete OS files and/or registry keys that are protected by WRP may fail with an error message indicating that the resource could not be updated. This is because access to these resources is denied.
• Attempts to write new registry keys or values to protected registry keys may fail with an error message that indicates that the change failed because access was denied.
• Attempts to write to protected resources may fail if they rely on the application succeeding in writing to protected registry keys or values.

Because applications are prevented from making changes to WRP resources, and related errors are suppressed, runtime errors may result.

Mitigations

Important   The following mitigation will not be applied if the application has a manifest that specifies a requestedExecutionLevel as required by UAC.

For well-known installers, Access Denied errors resulting from attempts to create, modify, or delete WRP resources will be suppressed, and no changes are applied to the WRP resource.

Remedies

• Do not install or update system state (files and registry) on Windows Vista except when using Microsoft-provided redistributable packages designed for Windows Vista.
• Do not decompose a Microsoft-provided redistributable designed for Windows Vista and install individual files or registry keys. The redistributable must be installed as provided by Microsoft.
• Use SfcIsFileProtected API to detect WRP-protected files. If a file is WRP, then the application installer should not install or modify the file.
• Use SfcIsKeyProtected API to detect WRP-protected keys. If a key is WRP, then the application installer should not install or modify the key.

WRP Protected Keys

It is expected that if an application attempts to create/modify/delete a WRP key then that application will get an "Access Denied" error. When you encounter an "Access Denied" error, verify that the access denied error is a result of a WRP Security Descriptor on the key (or a parent key) and not because the user does not having enough permissions to write to the key.

The decision on how to handle an "Access Denied" error because of WRP will depend on the impact of this failure for the application:

1. If the application is trying to write a key or value that already exists, then the application can ignore the error message.
2. If the key or value does not exist then as the developer you must decide the impact on your application. Is this key required for your application to run successfully on Windows Vista? If not, then you can ignore the error. If this key is required then you will need to redesign your application to write to an alternate key or use some alternate design.

How to recognize if a resource is WRP:

For Registry:

1. Through code, use SfcIsKeyProtected API.
2. Or use Regedit to check permissions on the key.

• Click Start, and then click Run.
• Type Regedit, and then click OK.
• Search for the key. Right-click the registry key. Click Permissions.
  • Keys that are WRP will show Trusted Installer with Full Control. SYSTEM, Administrators, and Users will only have Read permissions.

For files:

1. Through code, use SfcIsFileProtected API.
2. Or use Explorer to check permissions on the file.
   • Open the folder that contains the file whose properties you want to see.
   • Right-click the file whose properties you want to see, and then click Properties.
   • Keys that are WRP will show Trusted Installer with Full Control. SYSTEM, Administrators, and Users will have Read permissions only.

Internet Explorer Protected Mode

Feature Impact

High

Brief Description

In Windows Vista, Microsoft Internet Explorer 7 runs in Protected Mode, which can help protect users from attack by running the Internet Explorer process with greatly restricted privileges. Protected Mode significantly reduces the ability of an attack to write, alter, or destroy data on the user's machine or to install malicious code. It can help protect a user from malicious code installing itself without authorization. This is the default mode for Internet Explorer when Windows Vista is installed.

Manifestation

• Applications that use Internet Explorer 7 will not be able to write directly to disk while in the Internet or Intranet zone.
• Applications may not know how to handle new prompts.

Protected Mode builds on the new integrity mechanism to restrict write access to securable objects like processes, files, and registry keys with higher integrity levels. When run in Protected Mode, Internet Explorer is a low-integrity process; it cannot gain write access to files and registry keys in a user's profile or system locations.

Low-integrity processes can only write to folders, files, and registry keys that have been assigned a low-integrity mandatory label. As a result, Internet Explorer and its extensions run in Protected Mode, which can only write to low-integrity locations, such as the new low-integrity Temporary Internet Files folder, the History folder, the Cookies folder, the Favorites folder, and the Windows Temporary Files folders.

Furthermore, the Protected Mode process will run with a low desktop integrity level when Windows Vista ships, which will prevent it from sending specific window messages to higher integrity processes.

By preventing unauthorized access to sensitive areas of a user's system, Protected Mode limits the amount of damage that can be caused by a compromised Internet Explorer process or malware. An attacker cannot, for example, silently install a keystroke logger to the user's Startup folder. Likewise, a compromised process cannot manipulate applications on the desktop through window messages.

Of course, these defenses also limit legitimate changes to higher integrity locations (IL). As a result, Protected Mode provides a compatibility architecture that reduces the impact on existing extensions, as shown in the following figure.

Figure 1.

A compatibility layer handles the needs of many existing extensions. It intercepts attempts to write to medium integrity resources, such as the My Documents folder in the user profile and the HKEY_CURRENT_USER registry hive. The compatibility layer uses a generic Windows compatibility fix to automatically redirect these operations to the following low-integrity locations:

• %userprofile%\LocalSettings\Temporary Internet Files\Virtualized
• HKEY_CURRENT_USER\Software\Microsoft\InternetExplorer\InternetRegistry

Two higher privilege broker processes allow Internet Explorer and extensions to perform elevated operations given user consent. For example, the user privilege broker (IEUser.exe) process provides a set of functions that let the user save files to areas outside of low-integrity areas. In addition, an administrator privilege broker (IEInstal.exe) process allows Internet Explorer to install ActiveX controls.

Remedies

Quick solution:

• Add the site in question to the trusted sites list.
• Turn off Protected Mode (not recommended).

Compatibility test:

• Apply the quick solution and ensure that the application can perform the dependent functions as in Windows XP SP2.

Leverage Windows Vista capability solution:

• Change the application to handle Protected Mode, including any related prompts that may be displayed.

Links

• Security and Compatibility in Internet Explorer 7
• Understanding and Working in Protected Mode Internet Explorer
• Internet Explorer Developer Center
• Information Index for Internet Explorer 7 Beta 2 Preview

Windows Vista 64-bit

Feature Impact

High

Brief Description

Windows Vista fully supports the 64-bit architecture processors from AMD and Intel. The 64-bit version of Windows Vista can run all 32-bit applications with the help of the WOW64 emulator. However, 16-bit applications, 16-bit installers, and 32-bit kernel mode drivers are not supported by the kernel.

All 64-bit drivers have to be digitally signed for Windows Vista 64-bit editions. Unsigned drivers are not supported and cannot be installed on 64-bit Windows Vista. The digital signature check is done both during installation and driver load time.

Manifestation

• Applications or components that use 16-bit executables, 16-bit installers or 32-bit kernel drivers will either fail to start or will function improperly on a 64-bit edition of Windows Vista. In this case, the following error message is displayed:

  The program or feature "[exepath]\[app16bit].exe" cannot start or run due to incompatibility with 64-bit versions of Windows. Please contact the software vendor to ask if a 64-bit Windows compatible version is available.

• When a 16-bit installer or application is launched, the following error message is displayed:

  The version of this file is not compatible with the version of Windows you're running. Check your computer's system information to see whether you need an x86 (32-bit) or x64 (64-bit) version of the program, and then contact the software publisher.

• Installation of 32-bit kernel drivers will fail on the 64-bit system. If an installer manually adds a driver by editing the registry, the system will not load this driver and this action could cause the system to fail.
• Installation of 64-bit unsigned drivers will fail on the 64-bit system. If an installer manually adds a driver by editing the registry, the system will not load the driver during load time if it is not signed.

Remedies

Leverage Windows Vista capability solution:

• All 16-bit components should be removed from applications and replaced with 32-bit or 64-bit equivalents.
• All 16-bit installers should be converted to 32-bit or 64-bit installers.
• If the application uses kernel mode drivers, then a 64-bit version of the driver needs to be authored. The application should detect the platform of the OS (32-bit or 64-bit) and then install the proper architecture of the driver based on the OS platform.
• Ensure that all 64-bit drivers are digitally signed.

Compatibility test:

• Install and launch the application on a 32-bit and a 64-bit Windows Vista machine. The application should function properly on both architectures.

Links

• Running 32-bit Applications
• Video
• Digital Signatures for Kernel Modules on x64-based Systems Running Windows Vista

Microsoft Graphical Identification and Authentication (GINA)

Feature Impact

High (frequency: low)

Brief Description

Prior to Windows Vista, to log on to a third-party server or with a third-party device, ISVs had to replace the Graphical Identification and Authentication (GINA) dynamic-link library in Windows XP. Such applications also had to replace the existing UI and implement smart card and remote desktop features on Windows XP.

Note   If an application did not function this way in Windows XP, then this information does not apply.

Windows Vista introduces a new authentication model where LogonUI and WinLogon communicate directly with each other. This model provides simplicity, scalability, and flexibility that did not exist with GINA. Unlike the GINA module, ISVs no longer need to replace the UI for the logon screen, thus relieving the ISV of the burden of re-authoring the user interface for the user. An ISV can author a credential provider, which is a module that plugs into the LogonUI, to describe the UI and to gather the credential and pass it on to WinLogon. Credential providers are completely transparent to WinLogon.

Credential providers are also additive, meaning that users can install multiple credential providers and pick the one they want to use. Credential providers can be user selected and/or event driven. Multiple credential providers can coexist on Windows Vista and are not only for third parties. In fact, Windows will ship two credential providers in the box: a user name and password credential provider and a smart card credential provider.

Additionally, credential providers can be reused within CredUI. That is, the same object that describes and collects credential information on LogonUI can be used to gather the very same credentials in CredUI scenarios.

The GINA functionality from Windows XP and Windows Server 2003 has been deprecated and removed from Windows Vista. The GINA modules of applications will not function and will have to be re-authored using the new authentication model for Windows Vista.

Manifestation

• User will not be able to successfully install custom logon applications.
• User will not be able to log on using custom logon applications (using the Windows XP technology) in Windows Vista. These may include:
  • Biometric devices.
  • Custom UI for logon.
  • Virtual private network (VPN) solutions for remote users with custom logon UI.

Remedies

Leverage Windows Vista capability solution:

• The applications or components that use the GINA technology will need to be re-authored to use the new logon authentication model for Windows Vista.

Links

• For all credential provider information and questions, send e-mail to the Shell Credential Provider alias: credprov@microsoft.com

Session 0 Isolation

Feature Impact

High (frequency: low)

Brief Description

In Windows XP, Windows Server 2003, and earlier versions of the Windows operating system, all services run in the same session as the first user who logs on to the console. This session is called Session 0. Running services and user applications together in Session 0 poses a security risk because services run at elevated privilege and therefore are targets for malicious agents who are looking for a means to elevate their own privilege level.

The Microsoft Windows Vista operating system mitigates this security risk by isolating services in Session 0 and making Session 0 non-interactive. In Windows Vista, only system processes and services run in Session 0. The first user logs on to Session 1, and subsequent users log on to subsequent sessions. This means that services never run in the same session as users' applications and are therefore protected from attacks that originate in application code.

Specific examples of affected driver classes include:

• Printer drivers, which are loaded by the spooler service.
• All drivers authored with the User Mode Driver Framework (UMDF), because these drivers are hosted by a process in Session 0.

Application classes affected by this feature:

• Services that create UI.
• A service that tries to use window message functions such as SendMessage and PostMessage to communicate with an application.
• Applications creating globally named objects.

Manifestation

If a service belonging to an application throws a UI, the application is waiting on the service, and the UI is not displayed in the user session.

Remedies

Quick solution:

• If the application's service uses a UI, a built-in mitigation in Windows Vista allows the user to interact with the Session 0 UI in a special desktop. This will make available the UI specific to the application, instead of the entire Session 0 desktop.
• If the application creates globally named objects, then use the Windows XP compatibility mode to ensure that the application will continue to work with the Session 0 services.

Compatibility test:

• Test and verify the application on Windows XP in a Terminal Server mode or a Fast User Switching (FUS) mode. If the application works properly on Windows XP in these scenarios, then it is very likely to work under Windows Vista.
• Verify that the application functions properly after applying the Windows XP compatibility mode, which contains mitigation for some of the Session 0 issues.
• Test the driver in Windows Vista to ensure that it runs properly. If that is not possible, test the driver in Windows XP with FUS enabled and multiple users logged on. If the driver works correctly for second and subsequent logged-on users, it is not likely to be affected by the Session 0 changes in Windows Vista. The only issues that this test does not detect are those related to the absence of the video driver in Session 0 in Windows Vista.

Leverage Windows Vista capability solution:

• Use client or server mechanisms such as remote procedure call (RPC) or named pipes to communicate between services and applications.
• Use the WTSSendMessage function to create a simple message box on the user's desktop. This allows the service to give the user a notification and request a simple response.
• For more complex UI, use the CreateProcessAsUser function to create a process in the user's session.
• Explicitly choose either the Local\ or Global\ namespace for any named objects, such as events or mapped memory, that the service makes available.

Links

• Impact of Session 0 Isolation on Services and Drivers in Windows Vista
• Services
• Synchronization
• Making a Remote Procedure Call
• Client/Server Applications
• CreateProcessAsUser
• Test Your Application with Fast User Switching

Networking: TCP/IP Stack and the Windows Filtering Platform

Feature Impact

High

Brief Description

The Windows Vista networking stack has been completely rewritten. Instead of the dual stack model that exists in Windows XP or Windows Server 2003 (to support IPv4 and IPv6), Windows Vista implements a new architecture whereby there is a single transport and framing layer that support multiple IP layers. There are several new features and protocols enhancements. The new stack is very modular, flexible, and extensible. While all attempts have been made to maintain application compatibility with the existing applications that interface with the stack at various layers, nevertheless, there are changes (that are mostly side-effects of the improvements) that may have potential application compatibility issues and that application developers must carefully evaluate to understand the impact of these changes on their applications.

The Microsoft Windows Filtering Platform (WFP) API allows developers to create code that interacts with the filtering that takes place at several layers in the Windows Vista and Microsoft Windows Server Code Name "Longhorn" operating system networking stack and throughout the operating system. WFP also integrates with and provides support for firewall features, such as authenticated communication and dynamic firewall configuration, based on an application's use of the sockets API.

Note   WFP is not a firewall itself. It is a set of system services and APIs that enable firewalls to be implemented.

The following elements of the TCP/IP stack will not be supported on Windows Vista:

• The firewall-hook driver functions and the filter-hook driver functions have been deprecated.
• The R-series tools, including rexec, rsh, finger, and so on. These tools are available from the Services For Unix components, if needed.
• The Internetwork Packet Exchange (IPX) protocol. IPX has been deprecated and is not used much, if at all. There should be no or minimal application compatibility impact because of this change.

Manifestation

• If an application built for Windows XP was using only public functions for networking, it should not see any break in functionality. It should be tested on Windows Vista to verify its functionality.
• Applications using any of the firewall-hook driver or filter-hook driver functions will not work.
• Applications relying on internal structures and functions calls that were never published by Microsoft will fail.
• Transport Driver Interface (TDI) filter drivers written in Kernel mode may not work properly after an OS upgrade.

  Note   The TDI interface is on a path to deprecation in a future release. However, these drivers will still work on Windows Vista.

Remedies

Leverage Windows Vista capability solution:

• The WFP exposes a rich set of functions and services for the network security developers and provides guidance and documentation on the available feature sets.

  Note   Applications and scripts that rely on Services for Unix and R-series must now install these tools first.

Links

• WFP architecture, details, and SDK (prerelease)
• Interoperability and Migration Center

Networking: Kernel Mode IP Helper APIs

Feature Impact

High

Brief Description

In prior releases of Windows, Winsock clients did not have an API set to access the kernel. This will change in Windows Vista. Also, Windows Vista now supports IPv6 by default. Instead of providing separate APIs for IPv4 and IPv6, a new Helper API set was designed to provide a common functionality across all the new technologies, as follows:

• Kernel mode functions for Windows Sockets in Kernel (WSK) clients.
• IPv6 support.
• Single set of functions for IPv4 and IPv6 addressing.
• Provides a consistent, extensible object model.
• Provides a well-defined security model based on the network service interface.
• Exposes new stack functionality, such as compartments and subinterfaces.

Manifestation

Applications using the older Helper APIs or undocumented kernel function calls will fail to function and may become unstable.

Remedies

• Applications need to support and implement the new kernel mode IP helper APIs.

Links

• None at this time.

Networking: IPv6

Feature Impact

High (frequency: medium)

Brief Description

The TCP/IP stack in Windows Vista has IPv6 enabled by default. IPv6 connectivity is preferred, if available. This has the following implications for applications that hook into the TCP/IP stack:

• IPv6 traffic will be sent by the Windows Vista stack regardless of whether the network supports IPv6 or not. Therefore, for example, router solicitation and neighbor discovery messages will be generated by default.
• IPv6 addresses will be present and on by default. There may be multiple IPv6 addresses associated with link-local, global, temporary, or transition technologies like 6to4, 6over4, ISATAP, or Teredo.

  Note   Teredo will be enabled by default.

• Windows Vista will allow a system to be configured in an IPv6-only mode. In this case, no IPv4 support will be available.

The TCP/IP stack in Windows Vista supports a strong host routing model. This means that packets are routed from a multi-homed machine not only based on the destination address but also based on the source address of a packet. This change is needed because in IPv6, each machine gets multiple IP addresses and, with transition technologies, essentially appears as a multi-homed machine as far as routing is concerned. To ensure proper connectivity happens in these scenarios, the networking stack has to implement a strong host routing model.

Manifestation

Applications using the Windows XP TCP/IP stack and/or unaware of the IPv6 protocol will not function properly and may crash or create an unstable system.

The implication of the strong host routing model for the applications is as follows:

• Connection from a non-loopback address to a loopback address and vice-versa will fail.
• Packets with a source address of 127.0.0.0/8 will not be allowed to be sent by a Windows Vista machine on a network.

Remedies

Applications will need to be re-authored as follows:

• Any application that hooks into the stack must be capable of handling IPv6 traffic. Minimally, it should not crash on receiving IPv6 traffic.
• Any application that relies on there being a single IPv4 address will need to be modified to handle multiple IPv6 addresses. Further, any application that picked the first address may have to more carefully identify the IPv6 address to use. This is because an IPv6 link-local address is not routable and hence, the application may not work. Instead, the application should use functions that allow connection by name and choose the most appropriate address automatically.
• Applications must handle and support IPv6-only scenarios.
• Applications must support and implement the strong host routing model.

Links

• IPv6 Guide for Windows Sockets Applications

Networking: Turning off the Windows Firewall

Feature Impact

High

Brief Description

In order to avoid the situation where a user–installed firewall (which is compatible with Windows XP but is incompatible with Windows Vista) attempts to turn off the Windows Firewall in Windows Vista, Microsoft has deprecated the Windows Firewall XP SP2 INetFwProfile.put_FirewallEnabled(VARIANT_FALSE) function in Windows Vista. When called on Windows Vista, this function will return and error code of E_NOTIMPL, show a message to the user and will log an appropriate event in the Windows event log.

Manifestation

Applications using the Windows XP SP2 INetFwProfile.put_FirewallEnabled(VARIANT_FALSE) function to turn-off the Windows Firewall on Windows Vista will receive an error code.

Remedies

Applications (typically firewalls) replacing the Windows Firewall with their own firewall solution, must carefully consider the following security-related points:

• Windows Vista supports IPv6 and IPv4 out-of-the-box and will automatically have link local IPv6 address; therefore, it is essential that your firewall solution filters BOTH IPv4 & IPv6.
• Windows Vista also supports additional IP protocols (e.g., GRE, L2TP, PGM & ICMPv6); therefore, it is essential that your firewall solution filters arbitrary protocol filtering (IANA Protocol 0-255) & ICMP type and code filtering.
• In Windows Vista there are listening processes in both user mode and kernel mode (i.e., system process, http.sys, smb.sys); therefore, it is essential to filter BOTH User mode and Kernel mode network traffic.

Microsoft further recommends that these applications:

• Do not replace the Windows Firewall unless all of the security-related points specified above are addressed.
• Check the firewall status before your application turns-off or disables Windows Firewall with Advanced Security.
• Do not turn off the firewall service (mpssvc) since this is the service that enforces Windows Service Hardening restrictions.
• Allow their firewall solution to overlap with Windows Firewall with Advanced Security in order to minimize your customers' exposure to security threats.

Applications can disable Windows Firewall with Advanced Security by using the following code example. To protect users, they you should only disable Windows Firewall with Advanced Security after: (1) you have successfully turned on your firewall solution with the recommended settings; and (2) you have notified the user that Windows Firewall with Advanced Security is going to be disabled.

C++

#include <objbase.h>
#include <windows.h>
#include <stdio.h>
#include <comutil.h>
#include <strsafe.h>
#include <netfw.h>

#import "netfw.tlb"

HRESULT 
CoCreateInstanceAsAdmin(
    HWND hwnd, 
    REFCLSID rclsid, 
    REFIID riid, 
    __out void ** ppv
    )
{
    BIND_OPTS3 bo;
    WCHAR  wszCLSID[50];
    WCHAR  wszMonikerName[300];

    StringFromGUID2(rclsid, wszCLSID, sizeof(wszCLSID)/sizeof(wszCLSID[0])); 
    HRESULT hr = StringCchPrintf(wszMonikerName, 
sizeof(wszMonikerName)/sizeof(wszMonikerName[0]), 
L"Elevation:Administrator!new:%s", wszCLSID);
    if (FAILED(hr))
        return hr;
    memset(&bo, 0, sizeof(bo));
    bo.cbStruct = sizeof(bo);
    bo.hwnd = hwnd;
    bo.dwClassContext  = CLSCTX_LOCAL_SERVER;
    return CoGetObject(wszMonikerName, &bo, riid, ppv);
}

int __cdecl main()
{
    HRESULT hr;
    BOOL fComInitialized = FALSE;

    try
    {
        //
        // Initialize the COM library on the current thread
        //
        hr = CoInitialize(NULL); 
        if (FAILED(hr))
        {
            _com_issue_error(hr);
        }
        fComInitialized = TRUE;
        NetFwPublicTypeLib::INetFwPolicy2Ptr sipFwPolicy2;

        hr = CoCreateInstanceAsAdmin(GetDesktopWindow(), 
__uuidof(NetFwPolicy2), IID_PPV_ARGS(&sipFwPolicy2));
        if (FAILED(hr))
        {
            _com_issue_error(hr);
        }
        sipFwPolicy2->FirewallEnabled[NetFwPublicTypeLib::NET_FW_PROFILE2_DOMAIN] = FALSE;
        sipFwPolicy2->FirewallEnabled[NetFwPublicTypeLib::NET_FW_PROFILE2_PRIVATE] = FALSE;
        sipFwPolicy2->FirewallEnabled[NetFwPublicTypeLib::NET_FW_PROFILE2_PUBLIC] = FALSE;
    }
    catch (_com_error& e)
    {
        printf ("Error. HRESULT message is: %s (0x%08lx)\n", e.ErrorMessage(), e.Error());
        if (e.ErrorInfo())
        {
            printf ("Description: %s\n", (char *)e.Description());
        }
    }
    if (fComInitialized)
    {
        CoUninitialize();
    }
    return 0;
}

Visual Basic Script

option explicit
' Profile Type
Const NET_FW_PROFILE2_DOMAIN = 1
Const NET_FW_PROFILE2_PRIVATE = 2
Const NET_FW_PROFILE2_PUBLIC = 4

Dim fwPolicy2
Set fwPolicy2 = CreateObject("HNetCfg.FwPolicy2")
fwPolicy2.FirewallEnabled(NET_FW_PROFILE2_DOMAIN) = FALSE
fwPolicy2.FirewallEnabled(NET_FW_PROFILE2_PRIVATE) = FALSE
fwPolicy2.FirewallEnabled(NET_FW_PROFILE2_PUBLIC) = FALSE

Links

Windows Firewall with Advanced Security Reference

Compatibility Risks

Deprecated Components

The following components from earlier Windows releases will not be present in Windows Vista:

• Kernel mode Printer driver support: All printer drivers will now have to follow the User mode driver framework. All kernel mode printer drivers will be blocked from loading on Windows Vista. For more information, see the User-Mode Driver Framework (UMDF) site.
• Windows Help (WinHelp.exe and WinHlp32.exe) is being deprecated for Windows Vista. Windows Help is not supported in Beta 2 and some of the Windows Help code has been removed for the release. To view Help files with the .HLP file name extension in Windows Vista, you will need to download and install Windows Help from the Microsoft Download Center. This download will not be available for Beta 2 or RC1. For more information, see Help Engine Support.

  Note   HTML Help and .CHM files will continue to be supported for Windows Vista.

• Microsoft FrontPage server extensions. Windows SharePoint Services now provides an enhanced feature set to the developer community.
• Services for Macintosh.
• D3DRM. DirectX will be the only supported graphics package for Windows Vista.
• Web Publishing Wizard.
• NetDDE—For security reasons, Windows Vista does not support NetDDE. (NetDDE is disabled by default on Windows XP SP 2 and Windows Server 2003.) Regular DDE is still supported. NetDDE is a technology that allows applications that use the DDE transport to transparently exchange data over a network. The result is the application fails to exchange data over the network. To workaround, use a different networking technology, such as DCOM or Windows Communication Foundation. For more information about NetDDE, see http://support.microsoft.com/default.aspx?scid=kb;en-us;125703.

Help and Support Center

The Help and Support Center (HelpCtr.exe) was a Help application designed for Windows XP and Windows Server 2003. The Help and Support Center displayed compiled Help files with the .CHM file name extension.

The Help and Support Center is not included in Windows Vista and its features are not supported. Compiled Help files with the .CHM file name extension will only be displayed in the HTML Help application as described above.

Assistance Platform Client

The Assistance Platform client (HelpPane.exe) is a new Help engine designed for Windows Vista. It is not compatible with any previous versions of Windows. The Assistance Platform client is required to display Help files with the .H1S file name extension.

In Windows Vista, the Assistance Platform client can be customized by OEMs, system builders, and enterprise customers under license agreement, but cannot be used by third-party programs. For more information on customizing the Assistance Platform client, see the Windows SDK.

Windows Vista Display Driver Model (VDDM)

Windows Vista Display Driver Model (VDDM) is a completely new display driver model that improves display driver stability in Windows. There are a number of key features in VDDM, including:

• Efficient management of video memory for DX applications and the new Desktop Window Manager (DWM). Multiple 3-D applications will be using the graphics processor unit (GPU) in Windows Vista.
• Driver upgrades without reboot.
• Dynamic detection of GPU hangs and recovery without reboot.
• Hot Plug detection support of monitors.
• Using the hardware features mandated by DX9L.
• Glitch-free video playback.
• An opportunity for a very secure design.

While most of the applications from earlier versions of Windows should not be impacted by VDDM, some risks include:

• DX Games compatibility, resulting in DX run-time or IHV driver or core graphics stack issues.
• Mobile functionality like hotkey, cloneview, brightness and zoom due to stricter ACPI requirements.
• Accessibility, specifically that screen magnification applications designed by Windows XP will not work on Windows Vista.

Links

• E-mail the Graphics Feedback alias: lhgfxfb@microsoft.com

Safe Exception Handling

In earlier Windows versions, the IsBadReadPtr and IsBadWritePtr functions were used to validate parameters. These functions are now banned on Windows Vista. Also, applications that rely on Windows components using these functions to validate parameters will find that Windows no longer uses them. Applications should not rely on Windows to do any parameter validation (a check for null is done and the application fails if it is a bad pointer).

Safe exception handling (SEH) also goes hand-in-hand with the no-execute flag. Exception handlers are checked that they are marked page_execute before the exception is dispatched, and also that the handler is valid code and that it is in the SEH table.

DLLmain Operations

The load order of DLLs during process creation is not guaranteed and should never be depended upon to perform operations. Complex processing in DllMain may cause applications to hang or crash because of new OS component dependencies. For details, see the following pages on MSDN:

• Dllmain
• "Calls to an OLE Object Should Not Be Done from DllMain"
• "PRB: Cannot Create an MFC Thread During DLL Startup"
• "Your application may fail with an 'Access Violation' error message when you use ODBC or DAO in the InitInstance or DllMain functions of a DLL"
• "COM application hangs when you call CoCreateInstance from DllMain"

Outlook Express Renamed

Outlook Express has been changed and moved, and is now called Windows Mail. MAPI applications need to be aware of this change. Most applications that dynamically use the default program for MAPI should not see any compatibility problems.

Shell: Themes and My Documents Location

The Windows Explorer Shell has introduced new visual themes for Windows Vista. An application capable of handling themes in earlier versions of Windows should have no compatibility impact with the new themes.

Also, the My Documents location and structure has changed in Windows Vista to provide a better user experience. The user data is now stored in \users\%username%\ folder structure. Pictures, Music, Documents, Desktop, and Favorites are all new folders directly under this structure. If an application uses the ShGetFolderPath function and uses the folder path dynamically, it will be redirected automatically to the new path and file locations. In general, applications will not see a compatibility impact due to these changes.

Fast User Switching (FUS)

Fast User Switching (FUS) is now available on Windows Vista for all versions, including domain joined computers. Applications and installers need to be aware of FUS and be able to handle multiple logged in user sessions and terminal server scenarios. For more information, see Microsoft Windows XP Fast User Switching: Design Guide for Building Business Applications.

CriticalSection Code Changes

CriticalSection code was changed to increase security and robustness. Applications using critical section locks:

• Should always initialize critical sections.
• Should not read into undocumented objects. Applications that read into the undocumented structures to assess the status of a critical section will most likely break if they are looking for uninitialized and freed critical sections.
• Should prevent starvation. Applications that call Sleep while holding the critical section lock now can cause starvation for other threads that need the lock. Sleep calls should be placed after the LeaveCriticalSection call.

For more information, see the critical section objects topic in MSDN.

User Interface Privilege Isolation (UIPI)

In Windows Vista, User Interface Privilege Isolation (UIPI) is enabled by default. As a result of this security feature, a process in a lower integrity level cannot communicate with a higher integrity level process using Windows Messaging (SendMessage). This means that applications running under standard user level cannot communicate with other applications running with an elevated administrative level. This also means that applications installing keyboard or mouse hooks will now need to change to use manifests and request elevation. For related information, see the "Internet Explorer Protected Mode" section in this document.

Default Programs

Feature Impact

Medium

Brief Description

Default Programs is a new infrastructure to manage per user file and protocol associations designed with contentious applications in mind. Applications need to register in order to use Default Programs functionality. Be aware that Default Programs will get a lot of visibility in Windows Vista and beyond and make certain tasks much easier for applications to code and maintain.

It is difficult in today's software ecosystem to manage your default behaviors in Windows because there are so many competing applications for common tasks. Many people have multiple software programs that do the same things: browse the web, view photos, play music, watch movies, and manage e-mail to name a few. Many people have great difficulty because even if they decide to try an application, it has forever taken over their system and default behaviors like double click.

The problem gets worse as we start adding multiple users onto the same computer. As multiple users start using different applications they will start stomping on each others defaults. The root of this problem is that both protocols and file association are typically only taken or managed on a per machine basis by writing keys in the registry to HKLM (HKEY_Local_Machine). To make the matter more difficult there are multiple places in the registry where applications write to take the defaults.

This often results in some applications writing to one place in the registry and other applications writing to another place. The problem gets worse as these applications want to reclaim being the default for certain behaviors but they can't because they aren't writing to all the places other applications have. The core problem is that there needs to be an easy way to manage applications on the system that have competing interests.

Remedies

Windows first attempt to solve this problem was SPAD (Set Program Access and Defaults). This gave users the ability to allow an application to try to reclaim it's once default behavior. SPAD simply allowed applications to run some registered code to get back to some state. SPAD was a big switch and set defaults for the entire computer. SPAD will still be available in Windows Vista to allow an administrator to configure the machine defaults and hide access, but will not be the primary defaults experience for users.

In Windows Vista, we have provided a new set of functionality for applications to take advantage of. This new set of functionality is called "Default Programs". Default Programs was designed to help users make choices about their default behaviors. A large part of this is that defaults in Windows Vista and beyond will be primarily controlled at the Per User level instead of the Per Machine level. This allows much more flexibility for the multi-user computer environment that we believe is going to become the standard. Part of this is adding new centralized UI for the user, but the other part is giving ISVs the tools they need to help a user express choice. Default Programs gives an application:

• A simplified process for taking defaults.
• Per user file and protocol associations.
• Programmatic way to check for defaults.
• Common Windows UI to reuse.
• Advertising area within Windows.

This functionality was primarily designed for contentious applications. These are applications that want to be the default for file types like mp3 and jpeg, or protocols like http and mailto. Applications that primarily deal in their own protocols and file associations won't typically need to use this new functionality since they don't have to worry about other applications stomping over them. Applications that aren't contentious will behave and install like in XP. However, any application can take advantage of the new "Default Programs" work.

"Default Programs" functionality is built into the operating system as a series of control panels and open APIs. For an application to use the control panels or APIs it needs to register at install time to be part of Default Programs by writing a specific schema. This will allow the application to show up in the Default Programs control panels so a user can restore the application's default file associations and protocols at any given time.

Once an application has registered with Default Programs the application can take advantage of new functionality provided through APIs. Default programs provides APIs to:

• Restore all registered defaults.
• Restore single registered default.
• Query for the owner of a specific default file association/protocol/start menu canonical.
• Launch Defaults UI for a specific app.
• Clear all per-user associations.

The Default Programs work is intended to make it very easy to express user choice post-install and provide applications a simple framework to contend for defaults and claim them.

Why Use Default Programs

High-level points:

• Default Programs helps applications get discovered.
• The underlying architecture that allowed all administrators to write to HKLM is changing for Windows Vista.
• Default Programs allows applications to maintain XP parity process flows while changing very little code.
• Claiming only machine level defaults won't always give the desired results.

There is an obvious consumer gain for contentious applications using the Default Programs framework, but there is also a significant gain for the application to use Default Programs.

Default Programs provides a rich UI experience for registered applications so it can really advertise to the user all the amazing things it can do. In addition, applications that are digitally signed with a URL will be able to display that URL and allow users to easily navigate back to its home website and see what other apps and enhancements the company offers.

Using the new API set also significantly reduces the development cost for new applications. Almost all contentious applications monitor or check to see if they are not the default. Using the new API set this can be done in a single API call instead of crawling the registry like in previous versions of the OS.

Using the new API set also helps applications correctly function in the new world with User Account Control (UAC). UAC is implemented by taking an administrator and making her look like a standard user to the system. This means that an administrator cannot normally write to HKLM in Windows Vista and beyond. This is done so processes cannot act on the administrator's behalf without her knowledge. Installation will typically always be elevated because there is an experience for that, but for applications that want to be able to claim defaults post-install, they need to claim the defaults on the per-user level instead of the per-machine level. Switching to the new API set does this automatically. Applications that try to claim per-machine defaults post-install will fail.

The other strong reason for an application to rev to using Default Programs is to consistently achieve the desired results. File and protocol associations are derived from a hierarchical structure in the registry. Part of this structure dictates that per-user defaults will always be chosen over per-machine defaults. This means that if an application decided to build elevation points in their code to claim defaults by writing to HKLM like in XP, it would not always achieve the desired result. As soon as another similar application is installed and used default programs APIs that take per-user file and protocol associations, the previous application would no longer be the default because per-user defaults have a higher precedence.

Default Programs UI

Default Programs has several pieces of UI. These pictures are not final pictures of what this experience will look like by the time Windows Vista ships, but they are a general walk through in functionality and understanding.

Default Program UI flow:

Figure 2. (Click on the image for a larger picture)

Startmenu:

Figure 3. (Click the image for a larger picture)

Default Programs Control Panel Hub Page:

Figure 4. (Click the image for a larger picture)

Set a Default Program page:

Figure 5. (Click the image for a larger picture)

Only applications that have registered will show up in the list of applications. When an application registers a description value it will show up in the listbox on the right side. A description is required when registering.

Figure 6. (Click the image for a larger picture)

Restore defaults will reclaim all registered defaults for an application. Advanced will allow a user to choose specific defaults for an application.

Note   In order to show a URL in the UI an application must embed a URL in its digitally signed authenticode certificate. Applications that are not signed will not be able to show a URL.

Advanced

Figure 7. (Click the image for a larger picture)

This view shows everything that the application has registered for and what application currently owns the default. There is a Windows public API that allows apps to call this window so applications no longer need to maintain file association UI. We recommend using this UI instead of creating custom UI.

Default Programs Guidelines and Best Practices:

Install

Applications that install onto the operating system should keep installing the way they do in XP. In addition, an application will need to create their schema for default programs. Registering the new schema allows an application to take advantage of all the new functionality. Applications that just install like they did in XP will still function, but applications will need to register in order to take defaults post install. An application should do the following at install:

1. Install necessary binaries (Like XP).
2. Write program IDs to HKLM (Like XP).

   Note   Applications need to create application specific ProgIDs for their associations.

3. Claim machine level file associations (Like XP).
4. Write to new Default programs schema (New for Windows Vista).

Post Install

First Run Experiences:

Applications can choose to have a per-user first run experience. This is recommended. This is where an application should ask questions that refer to per-user choice. Applications should not have a per-machine first run. First run experiences should offer the user 2 main choices:

1. Accept default application settings (this should be the default behavior).
2. Customize settings.

Accept defaults should call the Program Defaults API that claims all registered defaults for an application. This changes the default file association from a per-machine setting to a per-user setting.

Customize settings should bring the user to the file association UI. Applications can programmatically call Windows file association UI for a specific application. This is the recommended approach.

Defaults UI:

Applications that choose to show Defaults UI should use the new Default Programs APIs to open an app centric version of file associations.

Example for Litware Media player:

Figure 8.

In this view, a user will see all the defaults a specific application has registered. A user will be able to see what an application owns, the current defaults, and change the default to the new application. On save, all updates will be committed and the window will be closed. On cancel, the window will be closed. This UI is provided so applications do not need to spend development resources for maintaining File association UI or worry about setting associations correctly.

Checking if an Application Is the Default:

Many applications like web browsers or e-mail clients have file and protocol associations that aren't commonly known to the user. Examples of these are things like HTTP:\ and Mailto:\. These applications typically do a check to see if they are the default when the application is invoked. Applications should check and see if they are the default through the new Default Programs API set. If the application is not the default, the application should present the user with UI that asks the user to:

1. Keep everything the way it is.
2. Make this application the default.

Applications should also include a checkbox that is defaulted to checked that says the equivalent of "Tell me when <application> is not the default anymore". Applications should NOT automatically claim defaults without asking the user. Applications should implement #1 by calling the Default Programs APIs to reclaim all of the application's registered defaults.

An example using Internet Explorer is:

Figure 9. (Click the image for a larger picture)

Registering with Default Programs

Default Programs functions by having each application explicitly register for what file associations and protocols they want to be considered for the default. This is done by registering the following schema in HKLM. Note that ApplicationDescription can be a string literal or a string resource reference. The latter allows MUI'ization.

HKLM\%APPLICATIONCAPABILITYPATH%
   ApplicationDescription = REG_EXPAND_SZ "@path\to\dll.dll,-resourceId"
   ApplicationName = REG_EXPAND "@path\to\dll.dll,-resourceId"
   \FileAssociations
   .file-extension = REG_SZ "file-extension-progid"
   \UrlAssociations
   url-scheme = REG_SZ "url-scheme-progid"
   \MIMEAssociations
      MIME = REG_SZ "mime-progrid"
   \Startmenu  REG_SZ            
   StartmenuInternet ="%app Name%"
          Mail ="%App Name%" 

Note   These are pointers to apps that have registered for canonicals in HKLM\software\clients. The value should be the name of the key under HKLM\software\clients\StartmenuInternet or HKLM\software\clients\Mail.

HKLM\Software\RegisteredApplications
   unique-app-name = REG_SZ "%APPLICATIONCAPABILITYPATH%"

Note   ApplicationDescription is required. However, ApplicationName is an optional entry that allows different type applications to point to the same .exe and show up as different names.

Note   In order to show a URL in the UI, an application must embed a URL in its digitally signed certificate. Applications that are not signed will not be able to show a URL.

An example using Contoso Web Browser:

Note   This should be a DLL to allow for localization.

HKLM\software\Contoso\WebBrowser\Capabilities
   Description =" The award-winning Web browser is better than ever. 
   Search the internet in second and find anything you want. Use 
   integrated tabs and new phishing detectors to enhance your internet experience."
\FileAssociations
  .htm = ContosoHTML
  .html = ContosoHTML
  .shtml = ContosoHTML
  .xht = ContosoHTML
  .xhtml = ContosoHTML
\UrlAssociations
  http = Contoso.Url.Http
  https = Contoso.Url.Https
  ftp = Contoso.Url.ftp
\Startmenu
  StartmenuInternet = "Contoso.exe"

HKLM\software\RegisteredApplications
  Contoso.WebBrowser.1.06 = software\Contoso\WebBrowser\Capabilities

ProgIds

Applications need to provide Applications specific ProgIds. This should have all the information that is typically written into the default key. Applications can do a one-to-one mapping of progid to protocol/extension or do one-to-many. It is completely arbitrary and both methods work equally. In the example above, ContosoHTML points to a single progid that has the shellexecute information for htm, html, shtml, xht, and xhtml. For the protocols, a specific progid is defined per protocol. This allows the execution string to be different per protocol.

When defining a ProgID for a MIME, the prog-id must contain the CLSID subkey with the class id for the corresponding application. This is used to do a lookup against the class id in the MIME database stored in HKLM.

Definitions of values

Capabilities—The registry subkey that all Default Programs information lives under for a specific application. The capabilities subkey is always under the applications registry keys.

Description—Default Programs is designed to allow users to make informed choices. We allow every application to register a description string so each application has a way to advertise its capabilities to the user. This value is a property under \capabilities.

Note   This is a required field. An application must provide an entry here to show up in the UI. Be sure to localize your strings.

ApplicationName—Specifies the name that will show up in the Default Programs UI. If this field is not filled out then default programs will use the name of the .exe associated to the first registered progid for the application. Application name should always match the RegisteredApplications name.

FileAssocations—The file associations subkey is where all the specific file associations the application wants to claim are put. Each file association is stored as a property of the FileAssocations Subkey. Each extension should point to an application specific progid and not a generic progid.

UrlAssocaitions—The URL associations subkey is where all the specific URL associations the application wants to claim are put. Each URL association is stored as a property of the UrlAssocations Subkey. Each protocol should point to an application specific progid and not a generic progid.

MIMEAssocaitions—The MIME associations subkey is where all the specific MIME associations the application wants to claim are put. Each mime association is stored as a property of the MIMEAssocations Subkey. The name should be the exact name of the MIME name stored in the MIME database and the value should be an application specific progid that has the corresponding CLSID in it.

Startmenu—The startmenu subkey is for internet and e-mail slots that are on the start menu. Applications that also register to be a contender for those spots can link that functionality into their Default programs entry. Providing a link to the start menu registration allows an application to show that it also wants the corresponding e-mail or internet link when displayed in default programs. If this information is provided and the user restores the default to this program then it will also take over the startmenu spot. The registration should just be the name of the registered key under HKLM\software\clients\StartMenuInternet or HKLM\software\clients\Mail. In the case of a mail client this also sets the default MAPI client.

Note   There is a separate start menu registration. For more information, see http://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/platform/shell/programmersguide/shell_adv/registeringapps.asp

HKLM\software\RegisteredApplications—RegisteredApplications is required so the OS can know where all of the information about each application is stored. This should be the name of the application.

Using Default Programs APIs

Once an application is registered, there are a number of APIs an application can take advantage of to allow for a better user experience. This interface should be in the June CTP. There is a slightly different interface in the Beta2 release that was changed due to customer feedback.

typedef [v1_enum] enum tagASSOCIATIONLEVEL
{
   AL_MACHINE,
   AL_EFFECTIVE,
   AL_USER
} ASSOCIATIONLEVEL;

typedef [v1_enum] enum tagASSOCIATIONTYPE
{
   AT_FILEEXTENSION,
   AT_URLPROTOCOL,
   AT_STARTMENUCLIENT,
   AT_MIMETYPE
} ASSOCIATIONTYPE;

[
   object,
   uuid(4e530b0a-e611-4c77-a3ac-9031d022281b),
   pointer_default(unique),
   helpstring("Application File Extension and URL Protocol Registration")
]

interface IApplicationAssociationRegistration : IUnknown
{
   HRESULT QueryCurrentDefault(
      [in, string] LPCWSTR pszQuery,
      [in] ASSOCIATIONTYPE atQueryType,
      [in] ASSOCIATIONLEVEL alQueryLevel,
      [out, string] LPWSTR* ppszAssociation);

   HRESULT QueryAppIsDefault(
      [in, string] LPCWSTR pszQuery,
      [in] ASSOCIATIONTYPE atQueryType,
      [in] ASSOCIATIONLEVEL alQueryLevel,
      [in, string] LPCWSTR pszAppRegistryName,
      [out] BOOL* pfDefault);

   HRESULT QueryAppIsDefaultAll(
      [in] ASSOCIATIONLEVEL alQueryLevel,
      [in, string] LPCWSTR pszAppRegistryName,
      [out] BOOL* pfDefault);

   HRESULT SetAppAsDefault(
      [in, string] LPCWSTR pszAppRegistryName,
      [in, string] LPCWSTR pszSet,
      [in] ASSOCIATIONTYPE atSetType);

   HRESULT SetAppAsDefaultAll(
      [in, string] LPCWSTR pszAppRegistryName);

   HRESULT ClearUserAssociations();
}
   
interface IApplicationAssociationRegistrationUI : IUnknown
{
   HRESULT LaunchAdvancedAssociationUI([in, string] LPCWSTR pszAppRegName);
}

AssociationLevel

AL_MACHINE—returns the machine default for an extension.

AL_EFFECTIVE—returns the effective default for the current user.

Note   This is what most applications should use.

AL_USER—returns the per user default. If no per user default, it returns failure code 0x80070483.

AssociationType

AT_FILEEXTENSION—use to query for a file extension like .htm or .mp3

AT_URLPROTOCOL—use to query for a protocol like http:// or mailto:

AT_STARTMENUCLIENT—use to query for the owner of the startmenu client for the mail or internet link.

AT_MIMETYPE—use to query for the MIME type like audio/mp3.

QueryCurrentDefault

Pass in the string of the extension (.mp3, HTTP, etc), type of extension it is, association level and it will return the ProgID for the current default. Typically, applications should use the AL_EFFECTIVE association level since that will determine the effective default for the user. The caller must CoTaskMemFree the returned progid string.

QueryAppIsDefault

Pass in the string of the extension (.mp3, HTTP, etc), type of extension it is, association level, and the registered application name and it will return a BOOL based on whether the application owns the default. Typically, applications should use the AL_EFFECTIVE association level since that will determine the effective default for the user.

QueryAppIsDefaultAll

Pass in the association level, and the registered application name, and it will return a BOOL based on whether the application owns all its registered defaults. Typically, applications should use the AL_EFFECTIVE association level since that will determine the effective default for the user.

SetAppAsDefault

Pass in the name of the registered app, the extension (.mp3, HTTP, etc), and the type of extension it is. The default will be set to the registered app.

SetAppAsDefaultAll

Pass in the name of the registered app and it will set all the defaults registered to the application.

ClearUserAssociations

Deletes all per-user associations for the current user, returning that user to whatever per-machine defaults exist. There does not currently exist a defined partner or 3rd party scenario where we would expect anyone to call this. But if they wanted to, they should be able to.

LaunchAdvancedAssociationUI

The specified app registration name must match one of the values registered under HKLM\Software\RegisteredApplications. This launches the Set Program Associations page for the specified app. This is intended for use by applications who want to provide a UX direct link to their advanced associations' configuration.

Note   This API set is only available for Windows Vista and beyond. Applications supporting downlevel OSs (Windows XP, Windows 2000, and Windows 98) should use their pre-existing defaults code on those OSs by using a SKU check to differentiate between pre-Windows Vista and post-Windows Vista OSs.

Code Examples

Using the registration for the Contoso Web browser, following is how it would implement using the API set.

Querying if Contoso Web Browser owns all of its defaults:

HRESULT CheckContosoHasAllDefaults(__out BOOL* pfHasAllDefaults)
{
    IApplicationAssociationRegistration* pAAR;

    HRESULT hr = CoCreateInstance(CLSID_ApplicationAssociationRegistration,
                                  NULL,
                                  CLSCTX_INPROC,
                                  __uuidof(IApplicationAssociationRegistration),
                                 (void**)&pAAR);
    if (SUCCEEDED(hr))
    {
        hr = pAAR->QueryAppIsDefaultAll(AL_EFFECTIVE,
                                        L"Contoso.WebBrowser.1.06",
                                        pfHasAllDefaults);

        pAAR->Release();
    }

    return hr;
}

Querying if Contoso Web Browser owns the default for .htm:

HRESULT CheckContosoHasDotHTM(__out BOOL* pfHasDotHTM)
{
    IApplicationAssociationRegistration* pAAR;

    HRESULT hr = CoCreateInstance(CLSID_ApplicationAssociationRegistration,
                                  NULL,
                                  CLSCTX_INPROC,
                                  __uuidof(IApplicationAssociationRegistration),
                                  (void**)&pAAR);
    if (SUCCEEDED(hr))
    {
        hr = pAAR->QueryAppIsDefault(L".htm",
                                     AT_FILEEXTENSION,
                                     AL_EFFECTIVE,
                                     L"Contoso.WebBrowser.1.06",
                                     pfHasDotHTM);
        pAAR->Release();
    }
    return hr;
}

Setting Contoso Web Browser as the default for .HTM:

HRESULT SetContosoAsDefaultForDotHTM()
{
    IApplicationAssociationRegistration* pAAR;

    HRESULT hr = CoCreateInstance(CLSID_ApplicationAssociationRegistration,
                                  NULL,
                                  CLSCTX_INPROC,
                                  __uuidof(IApplicationAssociationRegistration),
                                  (void**)&pAAR);
    if (SUCCEEDED(hr))
    {
        hr = pAAR->SetAppAsDefault(L"Contoso.WebBrowser.1.06",
                                   L".htm",
                                   AT_FILEEXTENSION);

        pAAR->Release();
    }

    return hr;
}

File Association Documentation

For more information about Creating a File Association, see http://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/platform/shell/programmersguide/shell_basics/shell_basics_extending/fileassociations/fileassoc.asp

For more information about Registering Programs with Client Types, see http://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/platform/shell/programmersguide/shell_adv/registeringapps.asp

For more information about Verbs and File Associations, see http://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/platform/shell/programmersguide/shell_basics/shell_basics_extending/fileassociations/fa_verbs.asp

For more information about File Types, see http://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/platform/shell/programmersguide/shell_basics/shell_basics_extending/fileassociations/fa_file_types.asp

Program Compatibility Assistant (PCA) in Windows Vista

Introduction to PCA

The Program Compatibility Wizard in Help and Support and the Compatibility tab in file properties are useful tools for users to fix program compatibility issues in Windows XP. The major limitation with these tools is the discoverability and the fact that the user needs to know when to use these tools. The Program Compatibility Assistant (PCA) is a new feature in Windows Vista that can make older programs that have compatibility problems work better, in an automated manner. PCA monitors programs for known issues. If an issue is detected, it notifies the user of the problem and offers to apply solutions that will be effective before the user runs the program the next time.

Note   PCA is a client-only feature and is not available on the Server.

The following sections describe the scenarios in which the user is expected to encounter PCA, details on the user experience, the solutions applied in each of those scenarios and how to manage the settings made by PCA at a later time. The last section talks about how to exclude programs from PCA.

PCA Scenarios

Detecting Failures in Setup Programs

One of the main scenarios for PCA is to detect setup programs failing to install on Windows Vista and to provide the solution of applying the Windows XP compatibility mode.

The most common setup failure is due to installers hard coding the check for the Windows OS version that they can run on. These installers will typical fail with an error message saying that the current version of Windows is not supported and terminate.

Below is an example of such error message, illustrated by a test program.

Figure 10.

To give more details on this, programs commonly use GetVersion or the GetVersionEx APIs to get information on the Windows OS version that they are running on. In Windows Vista these APIs will return 6 as the major version. If the program is hard coded to look for the XP version, which is major version 5, then it will fail in Windows Vista. The XPVersionLie fix included in the Windows XP compatibility mode will provide the XP version of the OS to the program, when it calls GetVersion or GetVersionEx APIs.

PCA targets to detect this scenario and will display a user interface similar to the one below after the installer is terminated. This scenario also covers uninstallers and a similar dialog will show be shown.

Figure 11.

When the user selects the option to Reinstall using recommended settings, the WINXPS2 compatibility mode will be applied to the installer program and the installer will be automatically restarted.

More details on what happens under the covers are explained through the Question / Answer below:

1. What is the detection logic and how does PCA know that the setup failed due to version problems?

   PCA does not specifically look for the setup's failing due to version problems. The logic used by PCA is to detect if a setup did not complete successfully. It monitors a program detected as setup by Windows Vista and checks if the program registers an entry in Add or Remove Programs (ARP). If no entries are created in ARP then PCA concludes that the installer did not complete successfully. It will then wait for the install program to terminate before displaying the UI. If it is an uninstaller then the detection looks for whether an entry is deleted from ARP.

2. How does PCA get information about the setup programs?

   PCA relies on the User Access Control (UAC) feature in Windows Vista to know if a program is setup. UAC includes detection for setup programs and will make sure the detected setup programs will be run as administrator. This includes getting administrative credentials or confirmation from the user before launching the program.

3. What does each option in the PCA dialog for setups do?
   1. Reinstall using recommended settings

      This will apply the Windows XP compatibility mode and restart the program. Refer to the section below on managing PCA settings to get more details on how the compatibility mode is applied.

   2. The program installed correctly

      It is possible that in some cases, PCA might come up for a setup program that completed correctly but did not create an entry in ARP. In those cases, users can use this option to suppress the PCA dialog the next time.

   3. Cancel

      PCA will do nothing.

All these options will result in the PCA dialog to disappear. PCA will not show up again for the same setup program except when the user selected the 'cancel' option on the previous PCA dialog.

Detecting program failures under UAC

The second main scenario category for PCA is to detect program failures while running under User Access Control (UAC). PCA detects 3 different types of program failures under UAC, which are described below.

Detecting program failures while trying to launch installers

PCA detects this particular scenario of a program not running as administrator and is experiencing a failure while launching a child exe, because the child program is required to run as administrator. This will typically be the case for programs trying to launch an updater.exe. This is because Windows Vista returns a new error code to programs trying to launch an executable which is detected to run as administrator. If the same updater.exe is run from explorer it will run as administrator since explorer knows how to handle this error code and launch the UAC consent UI asking for administrator credentials or approval and finally run the program as administrator.

Below is an example of a PCA dialog that will show up in this scenario, illustrated by a test program.

Figure 12.

Here the test program was trying to launch an up