How Do I...Use resources?

VB UseResources.exe [Run Sample] | [View Source]

Resources are an application-building feature that allow you to place culture-specific items inside satellite files, rather than directly in your main application. For example, error messages need to be translated into every language that is using the application. A resource is a formalized mechanism for loading these sets of culture-dependent items.

The code needed to load resources from a file is focused on the ResourceManager object. The ResourceManager is created by identifying a particular Assembly to base the ResourceManager on, or a Type within a particular assembly. This ensures that the correct set of resources is going to be used (resources are applied to assemblies, which is why an assembly needs to be identified). If you specify an assembly, you also need to specify the root name of the resources file to retrieve. For more information, see How Do I...Create Resources .

The following sample demonstrates creating a ResourceManager. Because ResourceManagers are expensive to use, you may want to declare only one (unless you have a specific need for more), and declare it at the class level. Further, a static (Shared) version of the ResourceManager can be used by many instances of your class, saving even further on memory resources.

' declare a ResourceManager, using the GetExecutingAssembly method of the Assembly
' class to determine which Assembly the ResourceManager is based on.
' The first parameter is the rootname of the resource file you want to load.
' In this case, our resourcefile's rootname is 'strings'
Public Shared rm As ResourceManager = New ResourceManager("strings", _
			System.Reflection.Assembly.GetExecutingAssembly())

' This declaration is similar to the previous declaration, but also allows
' you to pass the Type of a specific resourceset object. This constructor should be used
' when you want to develop your own ResourceSet, which could control things such as the
' caching policy for images. When you have designed your own resourcset, you should also
' define your own ResourceReader by implementing IResourceReader, and control how your
' ResourceSet is parsed. To use this constructor, the last parameter needs to be the Type
' of the resourceSet you created.
Dim rs As ResourceSet = New ResourceSet("myResources.resources")
static ResourceManager rm = new ResourceManager("myResources", _
			Assembly.GetExecutingAssembly(), GetType(rs))

' you can also declare a ResourceManager, passing it a Type. The ResourceManager
' then determines what Assembly that type is a part of, in order to derive information
' about associated resource files
Shared rm AS ResourceManager = New ResourceManager(GetType(ThisClass))

Once you have created your ResourceManager , the next step is to identify the elements to retrieve. In almost all situations, you will know what your specific resources are, so you will be aware of the names given to them. This demonstration focuses on retrieving string resources; however, you can also retrieve other resource types such as images.

To retrieve string entries from a resources file, use the GetString method of ResourceManager. The resources file in question usually consists of many string values, each having an identifier (name) and value. When you call GetString, pass the name of the entry you want to retrieve; the associated value is returned. You can also pass a CultureInfo object to GetString , which identifies the culture to retrieve (the current UICulture is used unless you specify otherwise). Remember, you will have many resource files that can have entries for the same value (for example, they may all have a 'welcome' entry). Each resource file is associated with a particular culture. When you call GetString, you can specify the culture to attempt to retrieve, and if the ResourceManager can find an appropriate entry in the resource file, it will be returned. If it cannot be found, then the ResourceManager falls back through the parent chain, trying to find an appropriate resource entry (rather than causing an exception to occur). This is demonstrated in the following example.

' These two entries are in a strings.resources file, and are in the default
' language of the software developers (which happens to be US-English, en-US). These are
' the neutral resources
' welcome = Hello and welcome to this application. Click 'Go' to continue...
' goodbye = Thank you for using this application

' This entry is in a strings.en-AU.resources file, identified as the Australian resources file
' welcome = Gidday, ladies and gents. Hit the 'Go button, and hold on to yer seats!

' declare a CultureInfo object, as a US-English resource
Dim ci1 As CultureInfo = New CultureInfo("en-US")

' declare a CultureInfo object, as an Australian-English resource
Dim ci2 AS CultureInfo = New CultureInfo("en-AU")

//get the Welcome and goodbye strings...
rm.GetString( "welcome", ci1 )   ' returns  'Hello and welcome...'
rm.GetString( "welcome", ci2 )   ' returns  'Gidday ladies and...'
rm.GetString( "goodbye", ci1 )   ' returns  'Thank you for using...'
rm.GetString( "goodbye", ci2 )   ' returns  'Thank you for using...'
                      ' the last return is because the specified resource could not
                      ' be found in the specified file, therefore the default is used

Try to use Assembly-aware ResourceManagers whenever possible. This means you should use a ResourceManager by declaring it through one of its constructors, as shown in the first sample. However, there may be situations when you want to place your family of resource files in one directory, rather than having to split them up into the separate subdirectory structure. This method avoids using resources through their associated assemblies, which means that you don't have to associate the resources files with assemblies. Keep in mind that this is not how resources are intended to be used, but is available in certain scenarios.

The following sample uses the CreateFileBasedResourceManager method of the ResourceManager to create your ResourceManager. This method needs the base name of the resources file you will be using (as in one of the previous examples), and the location and name of the resources file you are using. The final parameter is an optional Type of a ResourceSet (which you will not specify, indicating the default should be used, but you could specify your own resource format here). Once created, the ResourceManager can be used as in the previous examples.

' use the assembly-ignorant method to create a resourceManager.
' The file you look at is the Australia strings resources file. Note that all you need to specify
' is the directory you want to look in for the resources. ALL resources can be placed in the
' same directory, as long as each is differentiated by the name of the culture for that resource.
' In this example, you have placed all the resources in a subdirectory of the application,
' called "resDir".
Public Shared rm As ResourceManager = ResourceManager.CreateFileBasedResourceManager( _
		"strings", Server.MapPath("ResDir") & Environment.DirectorySpearatorChar, Nothing)

' Using the ResourceManager just created...
rm.GetString( "welcome")
rm.GetString( "goodbye")

You can also save nonstring resources. To access these resources, create a ResourceManager, and instead of using the GetString method, use GetObject. As with a String, the object in question will have been placed into the resources file as a name-value pair, so you can use GetObject the same way you would use GetString .

' create a ResourceManager...
' note you named the base file differently, to reflect the kind of resources
' you are storing. The file has three pictures in it
Public Shared rm As ResourceManager = new ResourceManager("images", _
			System.Reflection.Assembly.GetExecutingAssembly());

' get the resources out of the resource, specifying different cultures to retrieve
rm.GetObject("flag1", new CultureInfo("ja-JP"))   ' a Japanese flag image
rm.GetObject("car1", new CultureInfo("it-IT"))    ' an Italian car image
rm.GetObject("Sport1", new CultureInfo("ta-IN"))  ' a snapshot of India's national sport

To put this concept into practice, in the final example, you will create a small demonstration WinForms application. This application has string resources, but it also has an image resource to demonstrate that objects can also be made into resources. You will create a short program to write all of the resources into the same resources file, which saves work later. The code for the sample simply loads in the appropriate resources, and makes WinForms objects from them, which are then displayed to the user.

To change the particular resources that you see in this demonstration, you can go to your regional options (Start/Settings/Control Panel, and then select Regional Options) and on the General tab, change your locale to English (NZ), English (US), Japanese (which may require installation of the Japanese character set), or German. If you set it to any other culture, the default is used (in this example, U.S. English). Review the code for this demonstration to see how this setting was used (Thread.CurrentThread.CurrentCulture). The executable you need to run is MultipleResources. This executable actually creates the resources that will be used, and then the automation for the page turns the resources into the satellite assemblies you will find in the culture specific subdirectories.

A good test for this demonstration is to set the culture setting to something other than the four supported settings. Because standard fallback is used, the resources displayed should be the default (neutral) resources, which in this case are the U.S. English resources.

VB MultipleResources.exe [Run Sample] | [View Source]