Cool Client Stuff : WinRes

WinRes: Improvements in Whidbey

rprabhu — Fri, 18 Feb 2005 09:41:00 GMT

One of the first posts I made, after starting this blog, was about WinRes, a UI localization tool that ships with the .NET Framework SDK. The reason I wrote that post was that I had been increasing noticing how many people had the same set of issues with WinRes, and were having trouble resolving them, given that there isn't much documentation on MSDN about it. The information in that post gives a general understanding of how WinRes works and helps you debug the most common problems you may run into.

Ofcourse, simply documenting the issues is not enough, so we have attempted to improve the tool in Whidbey (.NET 2.0). Here are some of the improvements we have made:

1) Better error reporting - The single biggest problem users had with WinRes was not the errors, but the fact that it was very difficult to diagnose them. Many a time, WinRes simply failed to load a resource file and displayed an extremely informative message like 'Unknown item' or ' Item not found'. Not surprisingly, the user was left with no clue with what to do next. What's worse is that the typical user of WinRes is a localization/language expert, not a developer who can be expected to debug his/her way through the problem. I am happy to say that the error reporting is much improved in Whidbey. In typical cases, WinRes should be able to give a clear and specific indication of what the problem is, like the particular element in the resx that is invalid or which component it was not able to parent correctly and so on. It still may not be totally obvious how to resolve the problem, but you should atleast have something specific to go on. There will still be cases when WinRes will not be able to clearly pinpoint the problem, but it should, as a last resort, atleast show you what exception occured.

2) Robustness - A related issue with WinRes' loading mechanism was its sensitivity to problems. For example, it used to often fail to load an entire dialog just because it couldn't find one component's assembly or found one property it could not interpret. In Whidbey, WinRes is much more resilient to issues like these. In most cases, it will load the dialog inspite of such errors and report to you what errors occured in a textbox below the designer (much like the tasklist in Visual Studio). For example, if a component's type is not found, it will load the dialog and use a place holder control for that dialog, so that you can continue localizing (although I strongly recommend you ensure all the assemblies that are referenced in the resource file are placed either in the GAC or in the same directory as WinRes.exe, so it can locate and load them).

3) Support for VS localized resx files - One limitation of WinRes in v1.0/1.1 was that it required localized resx files (like Form1.ar.resx) to be self contained, in the sense that they had to have all the localizable properties defined in them. However, if you used Visual Studio for localization, the resx files it produced only contained diffs from the parent culture, which is more efficient and fits into the runtime resource loading behavior. These VS localized resx files could not be opened in WinRes, since it did not support the use of multiple resx files to load the dialog. In Whidbey, WinRes has the ability to do this and if you place the parent culture resx files in the same directory as the file you are trying to open, it should be able to pick them up and load the dialog.

4) Some support for public inherited controls - In v1.0/1.1, WinRes had trouble loading dialogs that had public inherited controls. We have fixed this issue in Whidbey and it should now be possible, in typical cases, to open these dialogs without problems. Note though that there will always be limitations in this area. There are many complex inheritance cases that we will still not be able to support (not only in WinRes, but even in the VS designer). Visual inheritance, though a tempting design choice, is fraught with many problems - but let me save that rather controversial topic for a separate post :-)

These are the major issues - besides these, we have fixed several small (yet irritating) bugs and improved the UI a bit. WinRes also supports the new designer improvements like snap lines for layout, since its designer has been rewritten to use the Whidbey designer hosting API. See also this post for improvements to localization in general in Whidbey.

If you have a chance to try out WinRes in Whidbey builds and find any issues you would like resolved, do let us know through MSDN Product Feedback. Note that some of the improvements mentioned above may not have made it into Beta 1 or the recent CTP builds, but should be available in the Beta 2 release.

In summary, WinRes is a useful, free tool that handles the most common and basic UI localization scenarios. For more advanced cases, users may prefer to use one of the third party localization tools available.

WinRes

rprabhu — Thu, 21 Aug 2003 08:02:00 GMT

WinRes is a .Net SDK tool that localization specialists can use to localize Forms. It hosts designers for the Form and components on it, and also a property grid, using which you can localize a Form and save it to the appropriate culture. The MSDN link above has general information about how to use this tool.

The cool thing about WinRes is that it can visually represent a Form based on just the information contained in a resource file (.resx or .resources). It can bring up a Form at design time and allow you to modify its localizable properties - all without access to the source code. How does it do that? The resource file has information in it about the Type of the components present on a Form. WinRes uses this information to dynamically create those components and their designers. It then initializes the (Localizable) properties on those components using the values serialized (I will probably talk another day about how we do the serialization) into the resource file by Visual Studio. Once the localizer has made the appropriate modifications, it serializes the new set of property values into a culture specific resource file (like Form1.fr.resx for French) that can be built into a satellite assembly. To learn more about Localization in general, here are some useful articles.

The ability to design and localize a Form visually without access to the source code is nice, but there are currently some limitations to what WinRes can do. I have fielded many questions about WinRes from both internal and external customers. I think documenting the limitations of the WinRes and the common issues you might run into maybe of some benefit. This blog is as good a place as any to do this, so here goes.

WinRes TroubleShooting

First of all, having a basic knowledge of the resource file format can be extremely useful when you run into problems. Resource files can be either in XML (.resx) or binary (.resources) format. The .resx format is more human-readable, so if you have a .resources file that you wish to look at, use the ResGen tool to convert it to a .resx. Now, open the .resx file in notepad. You will find the schema definition and some other stuff in the header. That stuff is not so interesting, so I won't describe it here. The rest of the .resx file is made up of "data" nodes. Each data node represents one localizable property in the dialog. Lets look at a couple of data nodes in a simple resx file for a Form that contains a Button:

<data name="button1.Text">
<value>button1</value>
</data>

The first node has the name "button1.Size", so looks like it represents the Size property of a component called button1. The type attribute represents, not surprisingly, the full name of the Type of this property. The value node contains a string representation of value of the Size property, which is in this case: (Width = 75, Height = 23). SImilarly, the second node above represents the Text property on button1. There is no Type information, so by default, this means that the property is of type String.

Okay, but what is button1? This information is conveyed by the following "special" properties, prefixed with the ">>":

<data name=">>button1.Name">
    <value>button1</value>
</data>
<data name=">>button1.Type">
    <value>System.Windows.Forms.Button, System.Windows.Forms, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
</data>
<data name=">>button1.Parent">
    <value>$this</value>
</data>
<data name=">>button1.ZOrder">
    <value>0</value>
</data>

These are special because they convey information about what button1 represents. The Type property tells us that button1 is actually a Windows Forms Button control. Its parent is "$this", which represents the Form being localized. The ZOrder value helps determine the order in which this component is placed on this Parent control relative to its siblings. The Name, ofcourse, is the name assigned to this instance of the Button control by the VS designer. With the above information, you should be able to decipher most of the contents of the .resx file.

Okay, now we are ready to look at some of the possible reasons for getting a 'Red X' (error) in WinRes when you load a Form. Unfortunately, the error messages that WinRes displays are currently often cryptic. So, when an error occurs, you should open the .resx file in notepad and take a look.

The most common problem is due to a current limitation of WinRes that it needs to be able to instantiate all the components on the Form. To instantiate a particular component, WinRes needs to load the assembly that contains it. WinRes needs the assembly to be present either in the Global Assembly Cache (GAC) or the same folder as WinRes.exe (search your file system for this file to locate where WinRes.exe is present - its usually in [dir where VS is installed]\SDK\[version]\Bin. All the framework assemblies should be in the GAC already, so WinRes should be able to instantiate components in them. However, if you have user controls or third party controls on your Form and their assemblies aren't in the GAC, you should either install them in the GAC or copy them to the WinRes folder.
Make sure that controls with a common parent have unique "ZOrder" values. If two or more controls with a common parent have the same ZOrder, WinRes is likely to fail to load the dialog, since it doesn't know in what order to place the controls.
Sometimes, the resx may contain incorrect Type information for one or more of the components in the Form. Make sure that the Type's name and assembly information is correct and complete. If not, WinRes will fail to load the Type.
The "name" attribute represents a property on a component and is always of the form "component.Property" (with the exception of the ">>" prefix on the special properties). Make sure that the names in your resx are in that format. Also, make sure that all the 4 special properties noted above are present for each component. WinRes needs those!
Make sure you are using the version of WinRes compatible with the assemblies you are localizing. For example, if your assemblies are built against v1.1 of the .NET Framework, use the WinRes.exe that came with v1.1 framework SDK. If not, you might run into weird versioning issues.
Another issue you might run into is this: when you have a combobox or listbox with items in it and you bring up the dialog with this control in WinRes, WinRes may not populate the control with those items. Further, if you add items to it through WinRes and save the localized resource, the localized items will not get picked up at runtime. It is, unfortunately, a limitation in WinRes currently that it is not able to handle collections (like the comboBox.ItemsCollection) correctly. The workaround is to not pre-populate the control with items, but do so at runtime with localized strings.

That is all I can think of at this time. I will post more information when I can.