How to: Use Resources to Set Property Values in Web Server Controls

Article
10/15/2014

In an ASP.NET page, you can use the following methods to retrieve values from resource files that are compiled by ASP.NET and managed by the .NET Framework resource manager:

Implicit localization, wherein ASP.NET fills property values from the resource manager based on matching the resource key to the properties of the control.
Explicit localization, by creating an expression that retrieves a specific resource from the .NET Framework resource manager.
Programmatically, by retrieving resource values in code.

For detailed information, see How to: Retrieve Resource Values Programmatically.

To use implicit localization

Make sure that you have local resource files (.resx files) that meet the following criteria:
- They are in an App_LocalResources folder.
- The base name matches the page name.
  
  For example, if you are working with the page named Default.aspx, the resource files are named Default.aspx.resx (for the default resources), Default.aspx.es.resx, Default.aspx.es-mx.resx, and so on.
- The resources in the file use the naming convention resourcekey."property".
  
  For example, key name Button1."Text".
In the control markup, add an implicit localization attribute.

For example:
```
<asp:Button ID="Button1" runat="server" Text="DefaultText" 
    meta:resourcekey="Button1" />
```
All resource files are compiled and the .NET Framework resource manager is used by ASP.NET at run time to retrieve the culture-appropriate resource for each resource in the default resource file. For each resource, ASP.NET looks for a corresponding resourcekey."property" combination (in the preceding example, resourcekey="Button1") in the page, and then substitutes the resource for the retrieved value.

To use explicit localization

In the markup for a control, use a resource expression to set the value for each property that you want to replace with a resource. The syntax is as follows:
```
<%$ Resources:Class, ResourceKey %>
```
Use these values:
- Class is the resource file class, which is based on the .resx file name.
  
  A resource file named WebResources.resx uses the class name WebResources. All culture variant resource files use the same class name as the culture neutral resource file. If you want to obtain a resource from the local resource file that is associated with a page, Class is optional.
- ResourceKey is the name of a resource in the specified class.
For example, a Button control that is configured to set the Text property from a global resource file might look similar to the following code example:
```
<asp:Button ID="Button1" runat="server" 
    Text="<%$ Resources:WebResources, Button1Caption %>" />
```

Example

The following code examples show implicit and explicit localization. The first code example shows how to use implicit localization, in which each control is marked with the meta attribute. At run time, ASP.NET matches resources to control properties. The second code example shows a page that uses resource expressions (explicit localization) to set the values of the Text property of various controls and of the ImageUrl property of an Image control.

In the first example, change <default> in the first line to a valid culture name. For a list of culture names, see the "Culture Names and Identifiers" table in CultureInfo.

Security Note
This example has a text box that accepts user input, which is a potential security threat. By default, ASP.NET Web pages validate that user input does not include script or HTML elements. For more information, see Script Exploits Overview.

<%@ Page Language="VB" Culture="auto:<default>" 
    meta:resourcekey="PageResource1" UICulture="auto" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML
  1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
  <title>Implicit Localization Sample</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>
    <h1>
       <asp:Localize runat=server 
          ID="WelcomeMessage" 
          Text="Welcome!" meta:resourcekey="Literal1" />
    </h1>
    <p>
    <asp:Image runat="server" ID="Logo" ImageUrl="" 
      meta:resourcekey="Logo" />
    </p>
    <br />
    <br />
    <asp:Localize runat="server"
       ID="NameCaption"
       Text="Name: " meta:resourcekey="Literal2" />
    <asp:TextBox runat="server" ID="TextBox1" 
      meta:resourcekey="TextBox1" />
    <br />
    <br />
    <asp:Button ID="Button1" runat="server" Text="Submit" 
      meta:resourcekey="Button1"/><br />
    </div>
    </form>
</body>
</html>

<%@ Page Language="C#" Culture"auto:<default>" 
    meta:resourcekey="PageResource1" UICulture="auto" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 
  1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
  <title>Implicit Localization Sample</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>
    <h1>
       <asp:Localize runat=server 
          ID="WelcomeMessage" 
          Text="Welcome!" meta:resourcekey="Literal1" />
    </h1>
    <p>
    <asp:Image runat="server" ID="Logo" ImageUrl="" 
      meta:resourcekey="Logo" />
    </p>
    <br />
    <br />
    <asp:Localize runat="server"
       ID="NameCaption"
       Text="Name: " meta:resourcekey="Literal2" />
    <asp:TextBox runat="server" ID="TextBox1" 
      meta:resourcekey="TextBox1" />
    <br />
    <br />
    <asp:Button ID="Button1" runat="server" Text="Submit" 
      meta:resourcekey="Button1"/><br />
    </div>
    </form>
</body>
</html>

<%@Page Language="VB"
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 
  1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
  <title>Explicit Localization Sample</title>
</head>
<body>
  <form id="form1" runat="server">
  <div>
    <h1>
    <asp:localize runat="server" 
      Text="<%$ Resources:WebResources, WelcomeMessage %>" />
    </h1>
    <asp:Image runat="server" id="Logo" 
      ImageUrl="<%$ Resources:WebResources, LogoUrl %>" />
    <p>
      <asp:Localize runat="server" 
         Text="<%$ Resources:WebResources, EnterNameCaption %>" />
       <asp:TextBox ID="TextBox1" runat="server"></asp:TextBox>
       <br />
       <br />
       <asp:Button ID="Button1" runat="server" 
          Text="<%$ Resources:WebResources, SubmitButtonCaption %>" />
    </p>
  </div>
  </form>
</body>
</html>

<%@ Page Language="C#" UICulture="auto" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 
  1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
  <title>Explicit Localization Sample</title>
</head>
<body>
  <form id="form1" runat="server">
  <div>
    <h1>
    <asp:localize runat="server" 
      Text="<%$ Resources:WebResources, WelcomeMessage %>" />
    </h1>
    <asp:Image runat="server" id="Logo" 
      ImageUrl="<%$ Resources:WebResources, LogoUrl %>" />
    <p>
      <asp:Localize runat="server" 
         Text="<%$ Resources:WebResources, EnterNameCaption %>" />
       <asp:TextBox ID="TextBox1" runat="server"></asp:TextBox>
       <br />
       <br />
       <asp:Button ID="Button1" runat="server" 
          Text="<%$ Resources:WebResources, SubmitButtonCaption %>" />
    </p>
  </div>
  </form>
</body>
</html>

In the @ Page directive, the UICulture attribute is set to auto to specify that the page should set the current UI culture to the information that is passed by the browser.

In Web pages, resources, such as graphics, are included by using a URL to reference an external file. Typically, you localize graphics and other resources by creating different versions of the graphics. You can then set the URL of a control using a resource expression that specifies a string resource to the appropriate path.

How to: Use Resources to Set Property Values in Web Server Controls

To use implicit localization

To use explicit localization

Example

See Also

Concepts

Additional resources