Win32 MUI Run-Time Diagnostics

Confirm that .mui files are properly placed. See To confirm proper placement of MUI files.

Confirm that .mui files and code binary are matched. See To confirm match of .mui files and code binary.

Confirm that the .mui file in the language folder of the language you wish to display is placed properly and is matched with the code binary.

See To confirm proper placement of .mui files and To confirm match of .mui files and code binary.

MUI resource splitting is a new Windows Vista feature. Earlier versions of Windows were not able to connect the code binary with the .mui file for resource location. As a result, the Windows Vista SDK ships with several APIs that make it possible for you to use Windows Vista-style binaries with pre-Windows Vista OS versions:

    
• LoadMUILibrary
   
• FreeMUILibrary

After installing, be sure and confirm that .mui files are placed properly.

Some of your resources may be considered non-localizable. A localizable Windows Vista resource will be found in the satellite .mui binary. Resources in the Windows Vista code binary are considered non-localizable. In the Windows Vista deployment scenario, the Windows Vista Resource Loader understands this difference and loads from either binary as appropriate. In the down-level scenario, using LoadMUILibrary will lock resource loading into one binary or the other (but not both).

The only workaround for this scenario is to load the resources you know to be resident in the main binary (as you would do for Windows XP) and load the localizable resources using the LoadMUILibrary API.

Alternately, some APIs in Windows Vista (such as GetFileVersionInfo) act upon pieces of a dual split resource. Specific resource types may contain both localizable and non-localizable information. For example, the version resource type can sometimes fit this pattern where much of the resource is obtained from the non-localizable code binary, but localizable parts (such as a string) are obtained from the .mui satellite file.

When using LoadMUILibrary on a down-level OS, a single portable executable (PE) file will be searched. APIs that support mui splitting in Windows Vista will work differently. The only true workaround for this scenario is to formulate your own code that will appropriately load the pieces of the resources you need from each binary.

In the event that resource changes were made to your application between its initial release and a subsequent update, it is possible that you have improperly serviced your application. This scenario occurs most often in applications that do not service all supported languages at the same time.
Based on the current servicing model chosen for Windows Vista, all resource changes were disallowed after Windows Vista RTM by procedure. Now only resource additions are allowed. Depending on the type of resource being used, what might appear to be an addition (e.g., a new resource) is actually a resource change.
This issue is most prevalent with RT_STRING types because of the internal format of how individual strings are stored together in groups (or blocks of 16) as a single resource. Additionally, any major changes of version or filename can break resource loading.
During the build step, the PE file's embedded major version and the OriginalFilename are used by the RC Compiler (and muirct.exe in post-build) to generate a checksum that validates that the main binaries and .mui binaries belong to each other (validation done at runtime). Resource-loading APIs allow resources to be loaded out of satellite .mui files only after this validation step is performed. Click here for more information about OriginalFilename or major version.
The MSDN Version Information reference page describes other functions that help read and manipulate the data contained within the version resource.
Potential workarounds

• Add new localized resources to your application only when at least one language in the merged fallback list and the MUI_MERGE_SYSTEM_FALLBACK and MUI_USER_FALLBACK flag is guaranteed to have been serviced (e.g., replaced with the new one). Click here for more information on the merged fallback list.
• Adjust your chosen servicing model. Always ship every language supported by your component (Windows Vista has ~100 languages) and install every language the user has on their system.
• Always service all the main binaries and all .mui files.

Symbolic links added to the Windows Vista kernel are not fully supported by the Resource Loader in Windows Vista RTM. Click here for mklink.exe.

Therefore, it is possible that some types of symbolic links will not produce proper resource loads. This issue is primarily related to scenarios where .mui files are not located directly at the location of the link.

This issue will be fixed in a future release of Windows.

Symbolic links work-around

• Refrain from resource loading APIs and symbolic links until the release of Windows Vista SP1 or Windows Server 2008.
• Read the Symbolic links documentation to determine conditions where sym links will work with resource loading in Windows Vista RTM.

Traditionally and by convention, resource names and type strings have been capitalized in resource PE binaries.

In Windows Vista, the UpdateResource API has a bug where it will allow mixed case to be assigned to a type (custom type) or name. When attempting to locate this resource, the Resource Loader converts the name of the string to uppercase and then cannot find the resource. This issue has been fixed in Windows 7, where UpdateResource converts all strings to uppercase.

To avoid this issue, format custom resource types and names as uppercase when using UpdateResource.

It is likely that the newly added resource was handed to the UpdateResource API starting with a '#' as the first character of the string, for example "#42". UpdateResource treats this as a string where the FindResource/Ex and Enumeration APIs treat this as a numerical resource type or name. Avoid using the Update APIs with '#' characters.
Click here for more information.

One issue encountered during application compatibility testing for Windows Vista is that resource sections of third-party applications can become misaligned prior to resource loading. Although X86 and AMD64 platforms are lenient when it comes to properly aligning memory (performance is apparently the only penalty), IA64 is more strict about misaligned memory and will not load the resources.

To mitigate this problem, use the UpdateResource-related APIs (for non-split binaries only) or Microsoft-provided compilers (RC Compiler) to assure your resources are properly aligned. Click here for more information.

Pay special attention to the internal structure of any custom resource. They can become misaligned, depending on how they are used.

Click here for more information on alignment.

The version resource (type #16) is unique. Normally, it is required to be present in all Microsoft compiler-built applications. It is added by default to the code binary in the default language (normally English). Because the version resource contains some text that may be displayed to the user, the GetVersionInfo API was modified in Windows Vista to be able to get pieces of the version from both a localized type #16 present in the .mui file and the remaining data from the neutral type #16 in the code binary.

Some component owners may wish to localize portions of the version resource, such as:

• Copyright information
• Servicing information

To enable localization of version information

• Read Example for Using the RC Compiler. This topic touches on how to split resources into both main binaries and .mui files.
• Use the /f flag in MUIRCT. Click here for more information.

Although not strictly related to MUI, the LCID to Language Name mapping is widely used in MUI technology.

To map language names appropriately

• Use the LCIDToLocaleName conversion API.
• Review information about language identifier.

Although not strictly related to MUI, validating LCIDs is important when using MUI technology.

To validate language names or LCIDs appropriately

• For LCIDs use the IsValidLocale API.
• For Language Names use the isValidLocaleName API.
• Review information about language identifier.
• Note: All LCID values corresponding to locales > 0xFFFF are not supported by resource loading APIs.

Sometimes it is important to determine that you have the correct .mui file in the properly named folder. At runtime, the Resource Loader confirms that the .mui file is properly placed. If the file validation fails, the Resource Loader ignores the misplaced file.

To confirm proper localization

• Use muirct.exe and point it at the .mui file of interest. See To view MUI resource configuration settings for more information.
• Confirm that the Language field has the appropriate language name.
• Use the resource editor in Visual Studio (or comparable third-party application) to compare the contents of the resource section.

Sometimes it is useful to confirm how resources are split between .mui and code binary PE files.

To confirm how resources are split between .mui and code binary PE files

1. Copy the .mui file to its own folder.
   Example   c:\folder\mui_file\<PE filename>.mui
2. Copy the PE file to its own folder.
   Example   c:\ folder\pe_file\<PE filename>
3. Change the .mui file extension from .dll.mui to .mui.dll.
4. Open both files in the Visual Studio (or similar) resource editor.
5. Review the data in both files.

Resource Loader functionality in Vista has a limitation that .mui file paths cannot exceed the MAX_PATH variable (260 characters). This limit was changed in Windows 7 to be MAX_PATH + LOCALE_NAME_MAX_LENGTH + 5 (350 characters including the null terminator). For Vista, it is possible that a component can get into a situation where the main / code binary is able to load properly (with LoadLibrary/Ex), yet fail to load resources out of a satellite binary. This can occur because the code binary is located within a path/file name configuration that is too long. For Windows 7 when applications use LoadLibrary/Ex this behavior is not possible.

Although this string size varies based on the language name length being supported, a code binary file path length of 240 or more characters may encounter this situation in Windows Vista.

If you are properly adjusting your resources (see previous question), there are three primary possibilities:

• You have a .local mui and/or PE file is in the directory where the application resides. This is a common Windows debugging feature that allows placement and first-chance loading of files named with the .local extension. If this situation applies to you, you will find a .local named .mui file in the directory where the application resides.
• Your binary is being managed by Side By Side (unlikely). Click here for more information.
• Various common Windows components are being added to the CMF (a system-wide MUI caching technology). As such, it is possible that the .mui file where resources are being loaded from is coming from the CMF rather than the actual .mui file that resides on disk (exceedingly unlikely). This is an OS feature and should be transparent to non-Windows components.

To determine if your resource is loading out of the CMF

• Determine the file path associated with the loaded resource. Do this by using the handle retrieved from LoadResource and passing it to GetMappedFileName.
• If the file name contains %windir\rescache\*.cmf., your resource came from the CMF.
• If GetMappedFileName fails and LoadResource is successful, it is also possible that the resource came from the CMF.
• In either of these cases, please discuss the issue with your Microsoft contact.

When using impersonation, mixed UI language can occur for several reasons.

In most cases, the primary reason relates to the fallback language list not being set properly. The most common fix is to have the impersonated thread use the SetThreadUILanguage or SetThreadPreferredUILanguages APIs (or) prior to any resource loading.

A second reason may be that the system on which the impersonated thread is running lacks the appropriate language resources - .mui files are missing or were never installed. To fix this issue, install the appropriate .mui files.

As a note, many services and server-type applications hit this scenario and have only a subset of  all languages they will see when a client connects with its thread language settings. The norm is that a block of resource languages is known to be installed. When the thread language(s) are set, one of the languages known to be installed is always set. This way, the application’s preferences are kept (rather than OS preferences).

If the assemblies are properly installed and being used correctly, the following may be happening:
On XP, the resource loader will load the version of the resource matching the active language on program launch.
On Vista, Common Controls version 6 may or may not load the correct resources. For other side-by-side assemblies, the wrong resources will be loaded if the thread's language is different from the process language. Changing the thread's language before loading a side-by-side assembly's resources is not a supported scenario.
On Windows 7, it is safe to change the thread's language before loading resources.
If these guidelines are followed and the program is unable to load resources, please ensure that at least one corresponding resource assembly for a language in the language fallback list is installed.

Click here for additional information on language fallback.
Click here for more information on assembly manifest creation.
Click here or here for more information on SxS assembly installation.

In some cases, applications must identify the language that the Resource Loader API found during resource discovery.

To verify language resources loaded by the Resource Loader

1. Confirm that your version resource is being split and localized.
2. Confirm that your split version resource has a localized field that will contain the language the .mui file was localized into.
3. Use the GetFileVersionInfo API to obtain the file version.
4. Use the VerQueryValue API to obtain the appropriate language-specific information about the binary being located.

To determine which language resources are loaded by Resource Loader (alternate procedure)

1. Add a dummy custom resource to the appropriate component or find a resource in the component that you are sure is in all .mui files.
2. Call FindResource or FindResourceEx on the component, seeking the dummy resource.
3. Use the GetModuleFileName function passing it the returned handle from FindResource/Ex to determine the file path of the .mui file.
4. Parse the last folder name out of the file path. The last folder name represents the language found by the Resource Loader.

In general, MUI technology does not currently support custom locales in Windows Vista and Windows 7. Custom locale support is being evaluated for a future Windows release. For now, refrain from using custom locales in MUI language management APIs and Win32 resource loading.

The most common cause of ?? characters in the command shell (cmd.exe) is due to the application attempting to display characters that cmd.exe is not configured to display or is unable to display.

To configure your application to display correctly in the current console at run-time, use the SetThreadPreferredUILanguages API with the MUI_CONSOLE_FILTER specified.

Click here for more information on console filtering (see the Remarks section).

Similar functionality is available in SetThreadUILanguage API for Windows XP.

Change the machine language. See To adjust machine-preferred UI language (UPL).

Occasionally the MUI team is asked how the various versions of MUI support differ across Microsoft OS offerings. The table below highlights the primary differences and features provided in the past three Windows MUI offerings.

This situation is addressed in RegLoadMUIString (new to Windows Vista API) and SHLoadIndirectString. Use one of these APIs to properly load UI strings from the registry

This situation is most commonly encountered due to a string caching mechanism within the Windows Shell which has not been informed of resource changes. See To refresh the Shell string cache - Windows Vista and Windows Server 2008 and To refresh the Shell string cache - Windows 7.

If you use the muirct.exe in your build process to do MUI splitting, click here for information on the UltimateFallbackLanguage attribute.

If you use the RC compiler in your build process to do MUI splitting, click here for information on the  UltimateFallbackLanguage attribute.

You can use Muirct -d as the first option for debugging. You can also use debugger extensions from the SDK for Vista and Windows 7. Install debugging tools for Windows 32-bit version, and then search for !mui in windbg's help or click here.

Windows 7 added SetProcessPreferredUILanguages, use this API instead. See To adjust process languages.

All MUI APIs were adjusted in Windows 7 to properly handle multiple parent chains.

• The language fallback list includes all parents associated with any given language.
• The resource loading APIs also follows this list by default or when LOCALE_NEUTRAL is passed to APIs that accept a locale.
• The resource loading functions preserve legacy resource probing in main binary by looking for the Vista-style neutral after the new parent chain list.

Windows support for various special locales (LOCALE_USER_DEFAULT, LOCALE_SYSTEM_DEFAULT) generally extends to MUI resource location, enumeration and updating. It is not supported in language management APIs. This support is provided primarily for backward compatibility. The practice is discouraged for new MUI development as use of explicit locales and LOCALE_NEUTRAL (0) are preferred. Marking resources using these default LANGIDs is also discouraged and not supported by many MUI API.

Under various conditions it is possible to construct Win32 PE files in which the Enumeration APIs are able to discover a resource that resource locator APIs are unable to find (or vice-versa). To avoid these issues the following guidance is offered:

• Use the latest MUI build tools to generate resource containing Win32 PE files.
  Click here for more information on the Resource Compiler.
  Click here for more information on muirct.exe.
  Click here for access to the latest Windows SDK.
• When creating or adding resources in .rc files or via UpdateResource always use valid locales.
  Click here for more information on locale validation.
• Ensure all MUI files remain mono-lingual.
  Click here for more information on viewing resource data.
• When possible, access resources by having Windows use the internally maintained fallback list.
  Click here for more information on language settings.
• When servicing, always update the main binary (exe, dll, sys, etc.) and all associated .mui files.
• Do not attempt to Enumerate resources in SxS stored binaries.
• Test your application and binaries on all platforms prior to release.