Mitigating Issues by Using Compatibility Fixes

Application compatibility is an important consideration when planning a migration to a new version of the Windows® operating system. While a significant percentage of your applications will work on computers that are running the new operating system, some applications will require compatibility fixes to function properly in the new environment. You can use the Windows Application Compatibility Infrastructure to apply one or more compatibility fixes (previously known as “shims”) to a specific application.

Compatibility fixes work by injecting new code between the running application and the Windows operating system. Because the code exists inside a “fix” that runs before the application calls to the Windows operating system, the code is unable to do anything that your application would be unable to do. Consequently, you can apply fixes to existing applications without modifying the source code, and still having the same level of safety and security provided by the new operating system.

The most challenging aspect of working with compatibility fixes is simply learning which fixes are available and how to configure them. In this walkthrough, we use the StockViewer demo application to mimic several issues that could cause your application to fail on a computer running the Windows 7 operating system. We then use the Standard User Analyzer and the Compatibility Administrator to fix the issues and to deploy the fixes to your environment.

Testing and Mitigating User Account Control-Related Issues with the Standard User Analyzer and the Compatibility Administrator

The Standard User Analyzer (SUA) tests your applications to detect potential compatibility issues related to User Account Control (UAC). SUA then recommends the appropriate mitigations to fix the issues. UAC, formerly known as Limited User Account (LUA), requires that all users (including members of the Administrator group) run as Standard Users until the application is deliberately elevated by using the security prompt dialog box. However, applications that require access and privileges for locations that are not available to a Standard User cannot run properly with the Standard User role.

In this section, we run the SUA tool on an application with known UAC issues and then apply the recommended mitigations.

Collecting the UAC-related issues

First, use the SUA tool to test an application and to locate the UAC-related issues.

To collect the UAC-related issues by using SUA

1. Click Start, point to All Programs, point to Microsoft Application Compatibility Toolkit 5.6, point to Developer and Tester Tools, and then click Standard User Analyzer.

   The SUA tool starts.

2. In the Target Application field, browse to the \Program Files\Microsoft Application Compatibility Toolkit\Compatibility Administrator (32-bit)\Demo Application\StockViewer directory, and then double-click StockViewer.exe.

3. Clear the Elevate check box, and then click Launch.

   The StockViewer tool attempts to start and the Permission denied dialog box appears.

4. Click OK.

   The StockViewer application starts, despite the warning.

5. Click the Trends button, located on the toolbar.

   An error message appears, stating that the application cannot create the object.

6. Click OK to close the error message.

7. On the Tools menu, click Options.

   An error message appears, stating that there was an unhandled exception in the application.

8. Click Continue to close the error message and to continue testing the application.

9. On the Help menu, click Check for Updates.

   Another error message appears, stating that there was an unhandled exception in the application.

10. Click Continue to close the error message and to continue testing the application.

11. Close the StockViewer application.

    SUA automatically collects and shows the data that was found during the application runtime.

Reviewing the SUA Tool Results

After collecting UAC-related issues from the StockViewer tool, review the information in the SUA tool.

To review the SUA tool results

1. In the SUA tool, click the Registry tab to review the registry issues.

2. Click the Token tab to review the issue that occurred when checking the token.

3. Click the Name Space tab to review the issues that occurred with the global name space.

4. Click the Other Objects tab to review the UAC-related mapping issue that occurred.

5. Click the Process tab to review the issues that occurred while launching a process.

Applying the Recommended Mitigations

After reviewing the UAC-related information from the various tabs of the SUA tool, you can review and apply the recommended mitigations.

To review and apply the recommended mitigations

1. On the Mitigation menu of the SUA tool, click Apply Mitigations.

   The Mitigate AppCompat Issues dialog box appears.

2. Review the recommended compatibility fixes. For more detailed information about each compatibility fix, see Windows Vista and Windows 7 Operating Systems or the Windows XP and Earlier topics.

3. Click Apply.

   The SUA tool generates a custom compatibility fix database and automatically applies it to your local computer, so that you can test the fixes to see if they worked.

Testing the Mitigations

After the SUA tool applies the custom compatibility fix database to your computer, you must test the StockViewer application to see if all of your issues are fixed.

To test the recommended mitigations

1. Browse to the**\Program Files\Microsoft Application Compatibility Toolkit\Compatibility Administrator (32-bit)\Demo Application\StockViewer**, and double-click StockViewer.exe.

   The StockViewer application starts without causing the Permission denied dialog box to appear.

2. Click the Trends button, located on the toolbar.

   The Trends screen appears.

3. On the Tools menu, click Options.

   The Options page appears.

4. On the Help menu, click Check for Updates.

   The StockViewer tool successfully checks for updates.

Creating a Custom Compatibility Fix Database for Deployment

Now that you know the recommended compatibility fixes work, you can create your own custom compatibility fix database to deploy across your organization.

To create a custom compatibility database

1. Click Start, point to All Programs, point to Microsoft Application Compatibility Toolkit 5.6, point to Developer and Tester Tools, and then click Compatibility Administrator.

   The Compatibility Administrator appears.

2. Select the New Database (1) [Untitled_1] custom database.

3. On the toolbar, click the Fix button.

   The Create New Application Fix wizard appears, showing the Program information page.

4. In the Name of the program to be fixed field, type StockViewer.

5. In the Name of the vendor for this program field, type Contoso.

6. In the Program file location field, type C:\Program Files\Microsoft Application Compatibility Toolkit\Compatibility Administrator (32-bit)\Demo Application\StockViewer\StockViewer.exe, and then click Next.

   The Create new Application Fix wizard shows the available Compatibility Modes.

7. Leave the fields blank, and then click Next.

   The Create new Application Fix wizard shows the available Compatibility Fixes.

8. Check the boxes for the ForceAdminAccess, LocalMappedObject, VirtualizeHKCRLite, and ElevateCreateProcess compatibility fixes, and then click Next.

   The Create new Application Fix wizard shows the available matching information.

9. Accept the default matching information, and then click Finish.

   The custom database is created in the Custom Databases node.

10. Select the new custom database, and then click the Save button, located on the toolbar.

11. In the File Name field, type Contoso, and then save the file, contoso.sdb, to your desktop.

Removing the SUA Mitigations Database

Before you deploy the custom compatibility fix database, remove the original database created by the SUA tool and then install and test the Contoso.sdb database again to ensure that the compatibility fixes were successfully applied to your local computer.

To remove the SUA Mitigations database

• In the Compatibility Administrator, expand the Installed Databases node, right-click the SUA Mitigations database (the only installed database that includes the StockViewer application), and then click Uninstall.

  The SUA Mitigations database is uninstalled from your local computer.

To install the custom database

1. In the Custom Databases node, right-click the Contoso.sdb database, and then click Install.

2. Verify that the Contoso database appears in the Installed Databases node.

3. Repeat the steps listed in the Testing the Mitigations section of this topic to ensure that the fixes have been successfully applied to the computer.

Deploying the Contoso.sdb Database to Your Environment

Finally, you can deploy the Contoso.sdb database into your environment so that the StockViewer application functions properly on all of your computers. For the purpose of this exercise, we simulate placing the Contoso.sdb database on a network share, and then we create a script to enable a management tool, such as Microsoft® System Center Configuration Manager, to install the database for later deployment to your environment.

To create the network share location

1. Create a new folder on your desktop, named SDBShare.

2. Right-click the SDBShare folder, and then click Properties.

   The Properties dialog box appears.

3. Click the Sharing tab, and then click Advanced Sharing.

4. Select the Share this folder check box, accept the default values, and then click OK.

5. Close the Properties dialog box.

6. Drag the Contoso.sdb database file, previously created and stored on your desktop, into the SDBShare folder.

   The compatibility fix database is now available for installation by remote computers.

To create the deployment script

1. To retrieve your computer name, open a Command Prompt window and type net config workstation.

2. Click Start, point to All Programs, click Accessories, and then click Notepad.

   The Notepad tool appears.

3. Type sdbinst “\\<your_computer_name>\SDBShare\Contoso.sdb” –q, and then save the file to your desktop as SDBInstScript.cmd.

4. Click Start, point to All Programs, click Accessories, right-click Command Prompt, and then click Run as Administrator.

   A Command Prompt window appears with Administrator permissions.

5. Type C:\users\<your_profile_name>\desktop\sdbinstscript.cmd, and then press ENTER.

   The Contoso.sdb database file is installed to the local computer. Run this script on each computer in your environment to ensure that the applications run properly.

See Also

Concepts

Phase 3: Testing and Mitigating Your Compatibility Issues
Known Compatibility Fixes, Compatibility Modes, and AppHelp Messages
Using the Sdbinst.exe Command-Line Tool
Compatibility Administrator Tool
Standard User Analyzer
Application Compatibility Toolkit Technical Reference