Winres.exe (Windows Forms Resource Editor)
The Windows Forms Resource Editor, Winres.exe, is a visual layout tool that helps localization experts localize Windows Forms user interface (UI) resources used by forms. The .resx or .resources files that are used as input to Winres.exe can be created using a visual design environment such as Microsoft Visual Studio. For information on deploying resources in .NET Framework applications, see Resources in Applications.
winres resourceFile
winres /?
Remarks
Argument |
Description |
|---|---|
resourceFile |
The resource file to localize. This file must be a Windows Forms form .resx or .resources file generated by the Visual Studio designer. Winres.exe cannot open generic .resx or .resources files. |
Option |
Description |
|---|---|
/? |
Displays command syntax and options for the tool. |
The state of UI elements from a form in a Windows Forms project are typically stored in resource files, which are either XML-based files with the extension .resx or the corresponding compiled, binary versions with the extension .resources. Winres.exe is a tool that enables limited editing of either type of file outside of the Visual Studio design environment. Specifically, it allows the following types of editing operations:
A neutral or specific culture resource file can be edited to change the UI properties of the form or its controls, such as their text, size, or position.
Neutral or specific culture resource files can be generated from the default resource file.
A culture resource file can be saved as another culture resource file. For example, an English (U.S.) resource file could be saved as a Polish resource file. Typically the new file would subsequently be edited to be compatible with the new culture.
For more information, see Hierarchical Organization of Resources for Localization and Hierarchical Organization of Resources for Localization and Hierarchical Organization of Resources for Localization.
Winres.exe cannot convert a .resx file into its corresponding .resources file; use the Resgen.exe tool instead. For more information about Resgen.exe, see Resgen.exe (Resource File Generator).
Winres.exe is a graphical application that recreates a design-time version of a Windows Forms form from just the resource file, without having access to the source code. Winres.exe hosts Visual Studio's Windows Forms Form Designer and Properties window. These features enable visual editing of a .resources or .resx file containing a Windows Forms form. Typically localizers use Winres.exe to edit control labels and adjust the location and size of controls to accommodate the labels for the target culture.
If Winres.exe cannot resolve the type of a control, it creates a placeholder control in the localized .resx or .resources file. The placeholder control appears on the Windows Forms form as a hatched window. The size and position of the hatched window matches that of the actual control. All the available localizable properties for the placeholder control appear in the Properties window. Any changes that you make to the placeholder control are saved for the actual control.
Winres.exe versus Visual Studio
In general, before you begin to localize an application's Windows Forms forms, you should decide whether you want to use Visual Studio or Winres.exe as the localization tool. Version compatibility, as described later, may prevent you from switching from one tool to the other.
The advantage of Visual Studio is that you can use it to both develop and localize an application. To localize a form, after development is complete, set the form's LocalizableAttribute (the Localizable property in the Properties Editor) to true and change its Language property to the desired target culture. Then, edit strings and adjust the location and size of controls to accommodate the strings for the target culture. When you save the localized .resx file, Visual Studio writes only the localizable properties (properties that changed in the target culture) to the file. Visual Studio automatically creates a satellite assembly for the localized .resx file in the correct directory location. For more information, see Walkthrough: Localizing Windows Forms and Walkthrough: Localizing Windows Forms and Walkthrough: Localizing Windows Forms and Walkthrough: Localizing Windows Forms.
Although Visual Studio provides an integrated development and localization environment, Winres.exe is the recommended tool to use if localization will be done by third-party localizers. Because Winres.exe is a localization tool only, it allows for a cleaner separation of an application's code from the forms to be localized, which is more practical for managing large projects.
Using Winres.exe
To localize using Winres.exe, you must first develop an application using a visual designer like the Forms Designer in Visual Studio. When development is complete, set the form's LocalizableAttribute (the Localizable property in the Properties Editor) to true, and then hand off the .resx file for the default culture to a third-party localizer. This .resx file contains extra information that Winres.exe uses to recreate a design-time version of the original form.
.gif "Caution note") Caution |
|---|
Winres.exe cannot be used to edit the default resource file. Winres.exe interprets all changed properties as localized properties and saves them to the target culture resource file. |
The final versions of the culture resource files can finally be used to create localized versions of the application. For more information, see Resources in Applications.
Version 2.0 of Winres.exe has the following features and capabilities:
Winres can operate in Single File Mode (SFM) or Visual Studio File Mode (VSFM). SFM is the legacy mode where complete information about the form and its contents is stored to the resource file. VSFM only stores only the cultural changes in the resource file.
An error-reporting window, docked to the bottom-left of the main window, has been added to the interface.
Hotkeys can be checked for duplicates: from the Format menu, click the Check HotKeys command.
Version Compatibility
Because the format of resource files changed between Visual Studio .NET 2002 and Visual Studio 2005, Winres.exe was likewise changed to be compatible. Therefore, as a general rule, you should use the version of Winres.exe that was released with the .NET Framework you are using to create the application. The following table lists the compatible versions.
Visual Studio |
.NET Framework |
Winres.exe |
|---|---|---|
Visual Studio .NET 2002 |
1.0 |
1.0 |
Visual Studio .NET 2003 |
1.1 |
1.1 |
Visual Studio 2005 |
2.0 |
2.0 |
Visual Studio 2008 |
3.0 and 3.5 |
3.0 and 3.5 |
Visual Studio 2010 |
4.0 |
4.0 |
If you attempt to open an older resource file with version 2.0 of Winres.exe, you will be prompted to upgrade the format of the file to be compatible with version 2.0 of the .NET Framework.
In versions of the .NET Framework prior to version 2.0, Winres.exe and the Forms Designer of Visual Studio created incompatible culture-neutral and culture-specific resource files. Therefore, once the localization process began, you had to continue using only the same tool. However, with version 2.0 of Winres.exe, the Visual Studio File Mode (VSFM) was added. As the name implies, a resource file saved in this compatibility mode can be edited with either tool.
Note
Although VSFM has the advantage of being compatible with Visual Studio, since it stores only changed values in the resource file, Winres.exe requires that the parents of the current resource file be located in the same directory. For example, editing TestApp.de-DE.resources, a German in Germany resource file, requires the presence of the default resource file, TestApp.resx, and possibly the culture-neutral resource file, TestApp.de.resources.
Examples
To localize a .resx or .resources file associated with a form
Type winres at the command prompt to run Winres.exe.
To open the default resources for a form to localize, click the Open command on the File menu and navigate to the file to open it.
-or-
Specify the file to open at the command line when you start Winres.exe.
The following command starts Winres.exe and loads the form associated with TestApp.resx in the Form Designer.
winres TestApp.resxThe following command starts Winres.exe and loads the form associated with TestApp.resources in the Form Designer.
winres TestApp.resourcesNote
If the form whose resources you are editing is an inherited form, both the assembly contained the inherited form and the assembly containing the inheriting (derived) form must either be registered in the Global Assembly Cache (GAC), or must reside in the same directory as WinRes.exe. For more information about installing .NET Framework components into the GAC, see Global Assembly Cache.
Select controls on the form and change their Text and other properties to reflect the localized culture and its language. Move or resize controls as necessary to accommodate the localized text.
To save the localized version of the .resx or .resources file, click the Save icon or the same command on the File menu. The tool displays the Select Culture window.
Select the appropriate culture and file mode then click OK. The tool saves the file, using the naming convention that the run time expects for localized resource files. For example, if you localize TestApp.resources for German in Germany, the tool saves the file as TestApp.de-DE.resources. If you localize TestApp.resx for German in Germany, the tool saves the file as TestApp.de-DE.resx. For more information about resource naming conventions, see Packaging and Deploying Resources. For a list of the predefined culture names used by the run time, see the CultureInfo Class.