ASP.NET Web Page Resources Overview

ASP.NET Web Page Resources Overview


ASP.NET provides a way for you to create a page that can obtain content and other data based on the preferred language setting for the browser or the user's explicit choice of language. Content and other data is referred to as resources and such data can be stored in resource files or other sources


Resource Files



Resource files in ASP.NET have an .resx extension. At run time, the .resx file is compiled into an assembly, which is sometimes referred to as a satellite assembly. Because the .resx files are compiled dynamically, in the same manner as ASP.NET Web pages, you do not have to create the resource assemblies. The compilation condenses several similar-language resource files into the same assembly.

When you create resource files, start by creating a base .resx file. For each language that you want to support, create a new file that has the same basic file name, but with a language or language and culture (culture name) as part of it. For a list of culture names, see CultureInfo. For example, you might create the following files:

  • WebResources.resx

    The base resource file. This is the default, or fallback, resource file.


    A resource file for Spanish.


    A resource file for Spanish (Mexico), specifically.


    A resource file for German.

At run time, ASP.NET uses the resource file that is the best match for the setting of the CurrentUICulture property. The UI culture for the thread is set according to the UI culture of the page. For example, if the current UI culture is Spanish, ASP.NET uses the compiled version of the file. If there is no match for the current UI culture, ASP.NET uses resource fallback; starting with resources for a specific culture, then a neutral culture, and then the default resource file. In this example, the default resource file is WebResource.resx.

Creating Resource Files for ASP.NET Web Sites


Global Resource Files

You create a global resource file by putting it in the reserved folder App_GlobalResources at the root of the application. Any .resx file that is in the App_GlobalResources folder has global scope. Additionally, ASP.NET generates a strongly typed object, which gives developers a simple way to programmatically access global resources.

Local Resource Files

A local resources file is one that applies to only one ASP.NET page (an ASP.NET page with the extension of .aspx, .ascx, .master, and so on). You put local resource files in folders that have the reserved name App_LocalResources. App_LocalResources folders can exist in any folder in the application, unlike the root App_GlobalResources folder. You associate a set of resources files to a specific Web page using the name of the resource file.


  • Default.aspx.resx

    The default local resource file, which is the fallback resource file, if no language match is found.


    The resource file for Spanish, without culture information.


    The resource file for Spanish (Mexico), specifically.


    The resource file for French, without culture information.


Choosing Between Global and Local Resource Files



Local resource files make it easier to manage resources for a single ASP.NET Web page. But you cannot share resources between pages. Additionally, you might create lots of local resource files, if you have many pages that must be localized into many languages. If sites are large with many folders and languages, using local resources can quickly expand the number of assemblies in the application domain.

When you make a change to a default resource file, either local or global, ASP.NET recompiles the resources and restarts the ASP.NET application, which can affect the overall performance of your site. Adding satellite resource files will not cause a recompilation of resources, but the ASP.NET application will restart.


Linked resources are supported only in global resource files.

Working with Resources in Web Pages





Implicit Localization with Local Resources






You can use any name for Key, but Property must match a property of the control that you are localizing.


    meta:resourcekey="Button1" />


Explicit Localization


A Button control that is configured to set the Text property from a global resource file might look similar to the following:

<asp:Button ID="Button1" runat="server" 


<%$ Resources:Class, ResourceID %>


The ResourceID value is the identifier of the resource to read. In the preceding example, the Text property for the button is read from the global resource file WebResources.resx (or the appropriate localized version). In that file, ASP.NET uses the value for the resource with the identifier Button1Caption and for the page itself. To set page properties, you can use resource expressions in the @ Page directive.

You can specify an explicit resource expression or an implicit resource expression for a control, but not both. The following declarative syntax on a Button control will result in a parser error:

<asp:Button ID="Button1" 

In this example, an implicit local resource file (one that matches the current page name) is specified as well as an explicit resource file called WebResources. To prevent a parser error for this control, remove one of the resource expressions.

Localizing Static Text


Security noteSecurity Note


    <asp:Localize runat=server 
<br />
<br />
<asp:Localize runat="server"
<asp:TextBox runat="server" ID="TextBox1" 
    meta:resourcekey="TextBox1Resource1" />

Implicit Localization in Templates

In templated controls, such as the DataList, GridView, and Wizard controls, you localize template style properties by accessing the properties through the parent control's implicit resource expression. You can not use an implicit resource expression on the template itself.

To localize values for a template property, use the meta attribute with a resource key for the control that the template belongs to, and use either the Property.Subproperty syntax or the Property-Subproperty syntax in the resource file. For example, the following declarative syntax is valid for a Wizard control:

<asp:Wizard ID="Wizard1" 
            BorderWidth="<%$ resources:navBorderWidth %>"/>
        <asp:WizardStep ID="WizardStep1" 
            Title="Step 1" 

The following key/value pairs in the local resource file could be used for the above example:

Wizard1Resource1.NavigationStyle.BackColor, Red
navborderWidth, 5

Or the following key/value pairs could be used:

Wizard1Resource1.NavigationStyle-BackColor, Red
navborderWidth, 5

Note that you can use an explicit resource expression for the NavigationStyle property of the Wizard control in the above example. The explicit resource expression omits the Class name so that resources from a local resource file are used.

For more information on templated server controls, see ASP.NET Web Server Controls Templates.

Selecting Resource Files for Different Languages

When a page is being run and ASP.NET is retrieving values from the resource manager, ASP.NET selects the version of the resource file that most closely matches the current UICulture setting for the page or uses resource fallback to obtain a resource. For example, if you are running the Default.aspx page and the current UICulture property is set to es (Spanish), ASP.NET uses the compiled version of the local resource file



You should not rely exclusively on browser settings to set language and culture information, because users can be using a browser on a computer other than their own. Also, browsers frequently communicate only language, not a specific culture. In this case, the server has to deduce a specific culture for data formatting. A good strategy is to let users select a language explicitly.

Working with Resources Programmatically

Besides setting resource values in markup with resource expressions, you can retrieve resource values programmatically. You might do this, if the resource value is not known at design time or if you want to set the resource value based on a run-time condition. For detailed information, see How to: Retrieve Resource Values Programmatically.

See Also

© 2016 Microsoft