Guidelines for Creating Quality Applications

  • Article

Guidelines for Creating Quality Applications

With each release of Windows, Microsoft developers and testers spend countless hours to assure the highest compatibility between existing applications and the current version of Windows. As part of this effort, Microsoft provides tools, technologies, and guidance to developers to ease this transition.

In addition to the general guidelines discussed below, developers will often be faced with specific technical issues when working with different versions of Windows or different Microsoft technologies. For more information about Windows Vista® migration recommendations, see Interoperability & Migration and Application Compatibility.

Always Generate an Application Manifest

An application manifest is an XML file that describes the application (metadata) and identifies the resources used. Application manifests should be included as a Windows resource in the application's .exe file or DLL.

For a .NET Framework 3.0 application, such a manifest is generated by default and accessible both at design-time and runtime.

Developers of Win32 applications typically control the generation of manifests through their development environment. For example, the Windows SDK and Microsoft Visual Studio contain command line and GUI versions of the Manifest Generation and Editing (MAGE) tool. MAGE supports the creation and editing of application and deployment manifests. As a command-line tool, Mage.exe can be run from both batch scripts and other Windows-based applications, including ASP.NET applications. For more information, see "Manifest Generation and Editing Tool" in the Windows SDK.

Manifests enable applications to use only private resources (so-called isolated applications) or safely share resources with other applications using side-by-side assemblies to reduce versioning conflicts. For more information, see "Isolated Applications and Side-by-side Assemblies" in the Windows SDK.

Allow for Intelligent Version Checking

If an application depends upon features of a specific version of a runtime environment, it should perform a runtime query to determine this dependency through one of the following mechanisms:

  • For Win32 code, use the GetVersionEx and VerifyVersionInfo functions.

  • For .NET Framework 3.0 code, the System.OperatingSystem class provides information about the current computer's operating system, and the System.Version class returns information about the Common Language Runtime (CLR).

In using these methods, developers should:

  • Research the minimum operating system version that their application requires.

  • Check that the version of the operating system returned is greater than or equal to this minimum. Do not simply check if the version is equal to the minimum.

Never hard-code dependencies on specific versions of a system DLL, as DLL versions can change with even minor updates.

Support User Account Control

Make use of the User Account Control (UAC) management of privileges, including graceful failure if a feature requires privileges a user cannot access.

Installers should be designed to allow compatible patching. For more information on the guidelines for doing this, see Developer Story Windows Installer.

Applications should conduct all their administrative level setup work during installation, not during the initial run of the application.

Do not rely on file and registry virtualization. Not all Windows Vista systems will be configured to support virtualization, there is a performance penalty and 64-bit processes do not support virtualization.

Make Use of the Microsoft Windows Error Reporting (WER) Services

Windows Vista provides mechanisms for standardized error reporting, data collection and problem analysis for development teams that participate in the Windows Error Reporting (WER) services.

To be notified and quickly respond to top field failures with their applications, developers should:

  • Instrument their applications using Windows Feedback. For more information, see Windows Feedback Services, and also "Windows Feedback" and "Windows Error Reporting" in the Windows SDK.

  • Subscribe to Windows Quality Online Services (WinQual). For more information, see the WinQual (https://winqual.microsoft.com/default.aspx) site.

  • Register to actively participate in the WER service.

Support Internationalization

With the advent of the Internet, access to the world software market has become a primary strategy for most ISVs. To provide maximum advantage, an application should be localized to the culture of its user. Support for globalization and localization can be best performed during the analysis and design phases of an application's life cycle.

One important aspect of localization involves displaying text information using the local character set and syntax. To do so, applications should always use Unicode and DBCS character types and avoid ASCII-based APIs. (However, additional ASCII support may be necessary for backward compatibility.)

For more information about internationalization of software, see one or more of the following Windows SDK topics:

  • For Win32 applications—"International Text Display"

  • For .NET Framework applications—"Encoding and Localization"

  • For Windows Presentation Foundation applications—"Globalization and Localization"

"Developing International Software, Second Edition" by Microsoft Press is an indispensable resource for localization efforts, especially of large software projects.

Use Publicly Available and Supported Interfaces

Microsoft provides programmatic access to and documentation for its public APIs. Developers should exclusively rely on current public APIs. Do not use unpublished internal functions or deprecated or obsolete APIs.

Check MSDN regularly for news and to check the current disposition of each API set used (including deprecated types). Microsoft also provides the following tools to test the compliance of applications with Windows standards:

  • The Application Verifier (AppVerifier) identifies common compatibility issues, such as the use of unsupported APIs, as well as verifying compliance with various Windows requirements. It runs on Windows XP or later and can be obtained from the Microsoft Download Center.

  • FxCop is a GUI application that analyzes managed code assemblies (.dll or .exe) and reports possible problems, such as possible design, localization, performance, and security improvements. The latest version can be downloaded from Microsoft GotDotNet.

For more information on verifying native applications, see "Application Verifier" in the Windows SDK.

Support State Separation

Building state separation into an application involves:

  • Use Known Folders, Search Folders and relative paths to specify the location of an application's components and the path to necessary registry settings. Applications should never contain hard-coded file or registry paths. Search Folders is an extension available under the Windows Vista shell that provides a mechanism for specifying data locations in a system-independent way. For more information, see Search and Organize.

  • Clearly separate user and computer settings, using different registry hives and different locations on disk.

  • Avoid directly modifying the registry to install services; instead, use the Service Control Manager (SCM). For more information on the SCM, see "Service Control Manager" in the Windows SDK.

  • Do not modify critical system areas of the registry or file system, such as the Windows folder or the HKLM settings in the registry, except during installation or when running with properly elevated administrator privileges.

Support the Windows Standard Environment

Applications should not block standard key strokes, in particular ALT+TAB behavior.

The 16-bit subsystem or a 16-bit installation engine are deprecated and should not be used. For more information, see Application Compatibility: Windows Vista 64-Bit.

Avoid race conditions by using the appropriate semaphores and locks to ensure correct behavior. Never rely upon any assumption about the relative timing of operations.

Applications should never replace or distribute system DLLs or install files in the system directory by themselves. Always use a re-distributable Windows Installer file to perform this task. For more information, see Installation and Update Management.

Design for 32-bit and 64-bit Systems

Windows Vista is the first Microsoft client operating system to be concurrently designed in both 32-bit and 64-bit flavors. The following guidelines are offered for 64-bit development:

  • Explicitly choose and document the operating systems on which an application is to run. If an application is to support both 64-bit and 32-bit, it is essential to test explicitly on both.

  • Applications designed for or validated against only one should explicitly check for the correct type of CPU. If the correct CPU type is not found, the application should gracefully fail on the untested CPU.

  • Applications supporting 64-bit computing should eliminate the use of 16-bit installers (as 16-bit applications are not supported). When providing ActiveX Controls for Internet Explorer, applications must also provide 64-bit versions of the controls and any necessary 64-bit kernel mode drivers.

For more information about application development for 64-bit versions of Windows, see "64-bit Windows Programming" in the Windows SDK and Application Compatibility: Windows Vista 64-Bit.

The .NET Framework is also available in a 64-bit version that enables the .NET Framework runtime, tools and applications to run on 64-bit workstations and servers. This version of the framework provides increased performance and scalability by addressing more memory (16 TB vs. 4G), processing more data (64 bits vs. 32 bits) per clock cycle and performing faster numeric calculations. For more information, visit the "64-Bit .NET Framework" page on the .NET Framework Developer Center (https://msdn.microsoft.com/netframework/) site.

Test Fully

Test early and make full use of the Microsoft beta releases, reporting any incompatibilities as soon as you discover them. This can be done by participating in WinQual, the Windows Quality Online Services application, or through MSDN. For more information about WinQual, see the (https://winqual.microsoft.com/) site.

It is particularly important to:

  • Test with the full-page heap enabled, which can be done by using the Global Flags tool (Gflags.exe). For more information, see the reference page on gflags.exe on MSDN.

    Enabling the full-page heap, as opposed to the normal-page heap, reveals heap corruptions with a non-accessible page at the end of an allocation, which causes an access violation whenever common allocation errors occur.

  • Test all TCP/IP-based applications against IPv6 scenarios. For more information about IPv6 scenarios and validation, see Interoperability & Migration.

  • Verify that, if necessary components are missing, an application fails gracefully.

  • Use an application verification tool to catch style and usage errors.