Chapter 7: Application Migration

Summary of Migration Requirements

Rationale

Millions of users today are running Windows 95, Windows 98, or Windows NT Workstation 4. Looking ahead, Windows 2000 Professional will increasingly become the predominant operating system of choice. Many of those Windows 95/98 and Windows NT 4 machines will be upgraded to Windows 2000 Professional. The goal of this requirement is that when users upgrade their operating system, previously installed applications will continue to function as before, with all preferences and privileges working after the upgrade.

Customer Benefits

• Applications work properly after customers upgrade to new operating systems, with no loss of functionality
  
  
• Customers experience reduced Total Cost of Ownership (TCO)
  
  
• End-users' experience with their applications and the operating system is the same or better after the upgrade

Requirements

7.1  Application must continue to function after upgrade to Windows 2000 Professional without reinstall

References

• Microsoft Platform SDK: Migration Extension Interface at: http://msdn.microsoft.com/library/psdk/win9xmig/migport_6l2d.htm

How to Comply with Migration Requirements

7.1  Application must continue to function after upgrade to Windows 2000 Professional without reinstall

To be certified on Windows 95, Windows 98, or Windows NT Workstation 4, applications must remain fully functional after an operating system upgrade to Windows 2000 Professional.

In the ideal case, applications will use a single set of binaries and not require different configurations on different operating systems. This is the best way to ensure a smooth upgrade of your application.

In the event that your application utilizes features specific to a particular operating system, Microsoft suggests the following alternatives for you to ensure smooth application migration. While the method you choose is up to you, it is a requirement that the application successfully migrate:

• When installing your application on one 32-bit Microsoft Windows operating system, the installer should install all the additional binaries that would be required to make the program operate on the other operating systems. Ideally, your application should isolate platform-specific behavior into dynamically loaded modules. The application should determine at runtime which components to use. For example, if the application requires a different DLL on Windows 2000 than on Windows 98, the application should install both and pick the one to actually load and use at application startup time. Use GetVersionEx to determine the version at runtime.

  If the application has platform-specific behavior, it should be written to detect an operating system change (e.g., the user upgrades the operating system after the app is installed). If the operating system changes, the application should be able to function properly on the new operating system. For example, if the application uses a .VXD on Windows 98, and uses a service on Windows 2000, the application should automatically install the service after Windows 98 is upgraded to Windows 2000 Professional. In addition, your uninstall process should dynamically check the OS version so that if the user has upgraded the OS since the initial install of the app, the correct uninstall routine will be called.

• For Windows 9x applications that implement Windows 9x-specific behavior, you can write a migration DLL to ensure that your application will work correctly after an end user upgrades to Windows 2000 from Windows 95 or Windows 98. For example, if the application uses a .VXD on Windows 9x, a migration DLL could be used to implement the equivalent functionality on Windows 2000 as a service. Windows 2000 Setup calls migration DLLs to perform any necessary migration of the application so it will continue to function for Win2000.

  Note   Migration DLLs can only be applied during the upgrade process from a Windows 9x system. Once the upgrade is complete, the DLL can no longer be applied. It is imperative that vendors make their migration DLLs broadly available for customers in a timely fashion. For more information about writing Migration DLLs, see the Migration Extension Interface in the Microsoft Platform SDK.

  Place your Migrate.dll file, along with your company's digital certificate and other associated files, on your distribution media, on the Web site from which the user installed the application, or on the user's hard disk. If the files are installed on the hard disk, you must write the following to the Windows 95 or Windows 98 registry:

  HKLM\Software\Microsoft\Windows\CurrentVersion\Setup\Migration DLLs
     Value name: <ProductID string >
     Value: <path to MIGRATE.DLL>
  

  Note   The ProductID must match the string returned by the QueryVersion function described in the Platform SDK. Following this process makes the migration process "seamless" and silent for the user.

  You might want to consider using the Migration DLL AppWizard. The Migration DLL AppWizard is a tool that creates a skeleton migration DLL with localization support. Full implementation details are available at: http://msdn.microsoft.com/library/psdk/win9xmig/migport_6l2d.htm.

  Note   Microsoft does not provide technical support for the Migration DLL AppWizard.

How to Pretest Applications for Migration Requirements

The following procedures outline the minimal process you should undertake during your test. Note that you should repeat the tests for multiple user account scenarios, that is, default, roaming, workgroup, and domain users. The scenarios should also cover combinations of these user accounts.

To test the migration of your application

1. Install Windows 95, Windows 98, or Windows NT Workstation 4 on a computer.
   
   
2. Install the target application on the computer.
   
   
3. Exercise the functionality of the application so that user-specific settings, .INI files, registry entries, MRU lists, etc are populated as they would be on a normal user's machine.
   
   
4. Start Windows 2000 Setup and select the Upgrade option on the Welcome page.
   
   
5. If you are using a migration DLL, insert the media containing the migration DLL when prompted. See the additional information below about using migration DLLs.
   
   
6. Complete Windows 2000 Setup.
   
   
7. Launch the migrated application on Windows 2000.
   
   
8. Run test suites to determine if the application is fully functional.
   
   
9. Repeat this process, starting out with other operating systems as appropriate.

Using Migration DLLs

Migrations DLLs must be tested for compliance as specified in the Microsoft Platform SDK. In particular, note:

• Be sure to test your migration DLL in the scenario in which your application is NOT installed on the system
  
  
• No changes may be made on the Window 95/98 side of setup, except to the working directory and answer file
  
  
• All changes must be reported to setup using Migrate.inf
  
  
• It is recommended that no user interface (UI) be present
  
  
• No UI is allowed in unattended mode
  
  
• The Migration DLL must provide complete VENDORINFO structure, which gives company name, URL, support phone and support instructions
  
  
• The Migration DLL must understand localization issues and either run on all localized OSes, or provide a code page list of the code pages it supports
  
  
• Additional disk space usage in GUI mode setup is given to setup on Win9x via Migrate.inf
  
  
• If an incompatibility message is added to the upgrade report, the DLL must write the text in the proper language
  
  
• The Migration DLL must be restartable (the machine can crash during setup, and the Migration DLL still does its job)

For more information, see the Migration Extension Interface in the Platform SDK.