Resources in ASP.NET Applications 

After you have created the satellite assemblies for an ASP.NET application, you must place them in specific locations where the common language runtime is able to locate and use them. The directory structure for satellite assemblies in ASP.NET applications and ASP.NET controls differs from the directory structure for satellite assemblies in a Windows-based application. ASP.NET applications can contain assemblies. However, because ASP.NET pages are converted into assemblies dynamically, the assembly name is not known in advance, and standard satellite assembly configuration does not apply. This section describes how to use resources in ASP.NET pages and ASP.NET controls.

Note
The procedures for creating and compiling the resources to use in an ASP.NET application do not differ from the procedures for creating resources for a Windows-based application. For details on this process, see Creating Resource Files, Packaging and Deploying Resources, and Creating Satellite Assemblies.

Resources in ASP.NET Pages

To use resources in ASP.NET pages, first create a parallel main assembly to store your application's resources. This assembly will contain the default or neutral resources for the application. Next, create a satellite assembly containing localized resources for each culture that your application supports. Install the main assembly into the application's bin directory, and the satellite assemblies in the expected subdirectories. The following illustration shows where satellite assemblies should be located in the directory structure of an ASP.NET application.

Note
When you deploy resources in ASP.NET applications using this model, all the assemblies are shadow-copied into the global assembly cache, eliminating potential locking issues.

The following example, used on an ASP.NET page, creates a ResourceManager to retrieve the appropriate resources.

<%
    Dim a As Assembly = Assembly.Load("myApp")
    Dim rm As ResourceManager = New ResourceManager("myApp", a)
    Response.Write(rm.GetString("string"))
    %>

<%
    Assembly a = Assembly.Load("myApp");
    ResourceManager rm = new ResourceManager("myApp", a);
    Response.Write(rm.GetString("string"));
    %>

You can explicitly specify the culture to use to retrieve resources in an .aspx page, by following the lines of code in the previous example with code that creates a CultureInfo object from a culture that you specify and uses the value of CultureInfo to initialize the CurrentUICulture property. The following example forces the retrieval of German resources every time because it sets the CurrentUICulture property to the German parent culture "de".

Thread.CurrentThread.CurrentUICulture = new CultureInfo("de")

Thread.CurrentThread.CurrentUICulture = new CultureInfo("de");

Note that although you can specify a neutral culture like "de" to create a CultureInfo object that can be used to initialize the CurrentUICulture property, you must specify a specific culture to initialize the CurrentCulture property. The CurrentCulture property expects a specific culture, that is, one that is associated with both a language and a region, such as ("de-AT") for German in Austria. The neutral culture "de" will not work because it is associated only with a language. To create a CultureInfo object in the format that the CurrentCulture property expects, use the CultureInfo.CreateSpecificCulture method. This method creates a CultureInfo object that represents the specific culture associated with a specified neutral culture. The following example uses the CultureInfo.CreateSpecificCulture method to create a CultureInfo object that represents the specific culture associated with neutral culture "de", and uses it to initialize the value of the CurrentCulture property.

Thread.CurrentThread.CurrentCulture = CultureInfo.CreateSpecificCulture("de")

Thread.CurrentThread.CurrentCulture = CultureInfo.CreateSpecificCulture("de");

It is good practice to explicitly set the values for both the CurrentUICulture and CurrentCulture properties in your .aspx page. The following example sets CurrentCulture to "de" and then uses the value of CurrentCulture to initialize the CurrentUICulture property.

Thread.CurrentThread.CurrentCulture = CultureInfo.CreateSpecificCulture("de")

Thread.CurrentThread.CurrentUICulture = Thread.CurrentThread.CurrentCulture

Thread.CurrentThread.CurrentCulture = CultureInfo.CreateSpecificCulture("de");

Thread.CurrentThread.CurrentUICulture = Thread.CurrentThread.CurrentCulture;

The CultureInfo.CreateSpecificCulture method also allows you to use the Web browser's current language to initialize the CurrentCulture property in an .aspx page. In the following example, the Request.UserLanguages property returns the Web browser's current language as a string. The CultureInfo.CreateSpecificCulture method parses this string and returns a CultureInfo object in the format that can be used to initialize the value of the CurrentCulture property.

' Set the CurrentCulture property to the culture associated with the Web
' browser's current language setting.
Thread.CurrentThread.CurrentCulture = CultureInfo.CreateSpecificCulture(Request.UserLanguages[0])

' It is good practice to explicitly set the CurrentUICulture property.
' Initialize the CurrentUICulture property
' with the CurrentCulture property.
Thread.CurrentThread.CurrentUICulture = Thread.CurrentThread.CurrentCulture

// Set the CurrentCulture property to the culture associated with the Web
// browser's current language setting.
Thread.CurrentThread.CurrentCulture = CultureInfo.CreateSpecificCulture(Request.UserLanguages[0]);

// It is good practice to explicitly set the CurrentUICulture property.
// Initialize the CurrentUICulture property
// with the CurrentCulture property.
Thread.CurrentThread.CurrentUICulture = Thread.CurrentThread.CurrentCulture;

For more examples of working with resources in ASP.NET applications, see the How to: Retrieve Resource Values Programmatically tutorial and the Localizing ASP.NET Applications and Working With Resource Files samples in the ASP.NET QuickStart.

Resources in ASP.NET Controls

If your ASP.NET application is developed using ASP.NET controls, you can use the same directory structure as described above. When you create controls, you can write code that uses resources to display different sets of information to the user. Because controls are compiled, they have an assembly. This allows you to embed a set of default resources in that assembly. You can create satellite assemblies for the resources to be used by the control and place them in the directory structure expected for satellite assemblies. For details, see Creating Satellite Assemblies. Place the control and the control's resources in the bin directory of the application root. The following illustration provides an example of the correct directory structure.

ASP.NET application with ASP.NET controls directory

You can place multiple instances of myControl, referred to in the illustration, on myPage.aspx. You can set each version to reference a different resource file entry. The following ASP.NET code example demonstrates this.

<Loc:myControl runat="server" Text="entry1" />
<Loc:myControl runat="server" Text="entry2" />

In this example, the ResourceManager uses the application's CultureInfo.CurrentUICulture property to determine which resources to retrieve.

The following example is for a Button control. The Text variable refers to the property value being retrieved and subsequently set in the control inside the .aspx page. This value is used to determine the name of the entry to retrieve. In this example, it is the same property used to display the result to the user.

Public Class myControl
Inherits Button

    Protected Overrides Sub Render(HtmlTextWriter writer)
        ' rm refers to the ResourceManager.
        Text = rm.GetString(Text)
        MyBase.Render(writer)
    End Sub
End Class

public class mycontrol : Button 
{
    protected override void Render(HtmlTextWriter writer) 
    {
        // rm refers to the ResourceManager.
        Text = rm.GetString(Text);      
        base.Render(writer);
    }
}

See Also

Reference

System.Globalization.CultureInfo Class

Concepts

Resources in Applications
Creating Resource Files
Packaging and Deploying Resources
Creating Satellite Assemblies

Other Resources

Creating ASP.NET Web Applications