FinRad Code Generators for Visual Studio

The FinRad code generators for Visual Studio are intended to supplement the Microsoft-provided strongly typed resource generator by providing the following additional functionality for string resources:

1. Localization of exception messages using cultures other than the user's preferred UI and formatting cultures, and
2. Retrieval of messages with placeholder via formatting methods whose signatures will change as safely as possible across resource string edits.

Installation

Download and install FinRad.CodeGenerators.Setup.msi. (Installation should be performed under a local administrator account.)

Adding a resource file

1. Launch Visual Studio 2008.
2. Open a C# or Visual Basic project.
3. Add a new string or exception message resource to the project, assigning your preferred name to the new file. (Please note that you may also change the custom tool association for an existing resource file to either "FinRad.StringResourceCodeGenerator" or "FinRad.ExceptionMessageResourceCodeGenerator" in order to use one of these code generators).
4. 
5. 
6. Add string resources to your resource file. Named placeholders with or without formatting are permitted.
7. 
8. Save your resource file. Two associated files should be created by the code generator: the generated C# or VB code file and an XML file containing a list of resources and placeholders. These two files should be visible in Solution Explorer if your project is set to save all files.
9. 
10. If your project is under source control, add all three files (.resx, .cs/.vb, and .xml) to your source control repository.

Consuming strongly typed resource strings

The C# or VB file generated by the tool contains one static, internally visible resource-fetching member per resource. If the resource string contained no placeholders, this will be a read-only property with a name in the form "<ResourceName>Message". If the resource string does contain placeholders, the member will be a method with a name in the form "Format<ResourceName>Message". The following example demonstrates use of the resource-fetching members for the resource file shown in the above screenshot:

Modifying strongly typed resource strings

Most modifications to a resource string will probably not result in any changes to the corresponding resource-fetching member. Such modifications include:

1. Changing any "static" portion of the string (i.e.: any part outside of a placeholder).
2. Adding, removing, or modifying the format specifier used for any given placeholder instance. (e.g.: "Today's date is {date}." -> "Today's date is {date:yyyy-MM-dd}.")
3. Changing the sequence of placeholders. (e.g.: "{childName} is {parentName}'s child." -> "{parentName} is {childName}'s parent.")
4. Changing the number of instances of any given placeholder without changing the overall set of placeholder names.

Adding a new placeholder or changing a placeholder name will result in a breaking change in the resource-fetching member since a new argument will be added to the resource-fetching member.

1. Changing "The value {value} is too low." to "The value {value} is too low. Please provide a value lower than {maxValue}." will change the resource-fetching method signature from internal string FormatValueTooLow(object value) to internal string FormatValueTooLow(object value, object maxValue). In this case, you would presumably want to modify any callers to add the new parameter.
2. The tool has no way to know whether a change to an existing placeholder name represents a correction or a truly new placeholder, so it assumes the latter in order to break calling code. For example, if you change "The value {value} is too low. Please provide a value lower than {maxValue}." to "The value {value} is too low. Please provide a value lower than {maximumValue}.", you will end up with the following method signature: internal string FormatValueTooLow(object value, object maxValue, object maximumValue). If your intent was to change the name of an existing placeholder, you can correct the problem by editing the member arguments XML file to remove the replaced placeholder.

If you remove a placeholder, the tool will conserve it in the method signature until you manually remove it from the member arguments XML file. This means that existing callers won't automatically be broken by a simple removal, although they will be providing placeholder substitution data that will be discarded at runtime unless/until you change the member arguments XML file.

Changing the tool code

If you would like to modify the tool for your own internal use, the source code is available for download. You will need to generate your own strong naming key for signing the assembly if you want to compile a modified version since the FinRad key is not included in the source tree. It is expected that the most common modification would be drawing the default resource and formatting cultures for the exception message code generator from a custom property defined by your own internal application framework.