Lesson 2: Creating and Using Satellite Assemblies

Lesson 2: Creating and Using Satellite Assemblies

Satellite assemblies are assembly files (.dll) that contain localized resources for an application. Each satellite assembly file contains the resources for one culture. An application can have many satellite assemblies, depending on how many cultures the application supports.

In this lesson, you ll learn how to prepare a Web application to use satellite assemblies, how to store localized user-interface elements within a satellite assembly, and how to load and display elements from the satellite assembly at run time.

After this lesson, you will be able to

  • Create localized resources and add them to satellite assemblies

  • Enable HTML elements within your application to display localized strings from satellite assemblies

  • Load resources into a ResourceManager object

  • Understand how ASP.NET selects the resources to load based on the CurrentUICulture property

  • Get strings from the ResourceManager object and display them in the user interface

Estimated lesson time: 30 minutes

How Satellite Assemblies Work

Web application projects use satellite assemblies to store the translated strings, graphics, and other culture-dependent aspects of an application s user interface. To create the assemblies themselves, you use the Resource Manager. At run time, the Web application loads the translated strings into the Web form based on the current thread s CurrentUICulture property, as shown in Figure 15-5.

figure 15-5 satellite assemblies at work

Figure 15-5. Satellite assemblies at work

To use satellite assemblies, follow these steps:

  1. Set the id and runat attributes for all of the user-interface elements of your application that require translation. Server controls have these attributes by default, but you will need to add them to HTML elements such as heading, paragraph, and span so that you can load translated strings into those elements.

  2. Create a fallback resource file containing the default strings to display in the user interface if the user s culture is not specified or not recognized. Name the fallback resource file filename.resx for example, strings.resx.

  3. Create resource files containing the translated strings to display for each general language that your Web application supports. Name the translated resource files filename.languagecode.resx for example, strings.es.resx.

  4. Optionally, create resource files containing the translated strings to display for each specific culture that your Web application supports. Name the resource file filename.languagecode-regioncode.resx for example, strings.ex-MX.resx.

  5. Write code to load the resources for the Web form using the ResourceManager class.

  6. Write code to detect the user s culture and set the Thread class s CurrentCulture and CurrentUICulture properties to match. ASP.NET uses the CurrentCulture property to determine formatting for dates, currency, and numbers; ASP.NET uses the CurrentUICulture property to determine which satellite assembly is used when loading translated strings.

  7. Write code to get strings from the resource files and display them in elements on the Web form.

The following sections describe these steps in more detail.

Enabling HTML Elements for Resources

Resources from satellite assemblies are loaded into Web form elements on the server side. Therefore, you need to make sure that all the elements on your Web form have id and runat attributes that make them available from server-side code. By default, ASP.NET server controls have these elements; however, HMTL elements do not.

For example, the following HTML shows a simple Web form with a heading, some text, and some controls:

<HTML> <HEAD> <title>Using Satellite Assemblies</title> </HEAD> <body> <form  method="post" runat="server"> <h1>Sample heading</h1> <p>Some introductory text.</p> <span>Enter a number: </span> <asp:TextBox  Runat="server" /> <br> <span>Amount in local currency: </span> <asp:Label  Runat="server" /> <br> <br> <asp:Button  Text="OK" Runat="server" /> <input type="button" onclick="txtCurrencty.value=''" value="Cancel"> </form> </body> </HTML>

To enable the preceding Web form for using resources, you need to change the HTML elements, as shown in the following code in boldface:

<%@ Page Language="vb" AutoEventWireup="false" Codebehind="Satellite.aspx.vb" Inherits="vbSatelliteSnippet.WebForm1"%> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <HTML> <HEAD> <title>Using Satellite Assemblies</title> </HEAD> <body> <form  method="post" runat="server"> <h1  runat="server">Sample heading</h1> <p  runat="server">Some introductory text.</p> <span  runat="server">Enter a number: </span> <asp:TextBox  Runat="server" /> <br> <span  runat="server">Amount in local currency: </span> <asp:Label  Runat="server" /> <br> <br> <asp:Button  Text="OK" Runat="server" /> <input  runat="server" type="button"  onclick="txtCurrencty.value=''" value="Cancel"> </form> </body> </HTML>

The preceding id and runat attributes cause Visual Studio .NET to handle those elements as server controls. When you switch from HTML view to Design view, Visual Studio .NET adds the following declarations to the Web form s code file:

Visual Basic .NET

Protected WithEvents head1 As System.Web.UI.HtmlControls.HtmlGenericControl Protected WithEvents p1 As System.Web.UI.HtmlControls.HtmlGenericControl Protected WithEvents sp1 As System.Web.UI.HtmlControls.HtmlGenericControl Protected WithEvents sp2 As System.Web.UI.HtmlControls.HtmlGenericControl Protected WithEvents butCancel As System.Web.UI.HtmlControls.HtmlInputButton

Visual C#

protected System.Web.UI.HtmlControls.HtmlGenericControl head1; protected System.Web.UI.HtmlControls.HtmlGenericControl p1; protected System.Web.UI.HtmlControls.HtmlGenericControl sp1; protected System.Web.UI.HtmlControls.HtmlGenericControl sp2; protected System.Web.UI.HtmlControls.HtmlInputButton butCancel;

These declarations allow you to set the value and innerHTML attributes of these HTML elements at run time.

Creating Resource Files

You can create three types of resource files when using satellite assemblies to provide translated strings within a Web application, as described in Table 15-2.

Table 15-2. Resource File Types for Satellite Assemblies

Type

Named

Compiled into

Provides

Fallback

file.resx for example, strings.resx

The executable assembly

User-interface strings when culture is not specified or not recognized by the Web application

Language- specific

file.langcode.resx for example, strings.es.resx

Resource-only assembly stored in a subfolder of the bin folder identified by language code for example, bin\es\

Translated strings for cultures using a particular language

Culture-specific

file.langcode- regioncode.resx for example, strings.es-MX.resx

Resource-only assembly stored in a subfolder of the bin folder identified by the language and region code for example, bin\es-MX\

Translated strings for cultures using a specific dialect of a language

The culture codes used to identify language and culture-specific resource files are listed in the CultureInfo Class online Help topic. Those codes are also used in the Name property of the CultureInfo class and the Request object s UserLanguages array.

To add resource files to a Web application project in Visual Studio .NET, follow these steps:

  1. From the Project menu, choose Add New Item, and then select Assembly Resource File from the Templates list.

  2. Type the name of the resource file you want to create, and then click Open. Visual Studio .NET creates a new resource file and adds it to the project, as shown in Figure 15-6.

    figure 15-6 a new resource file

    Figure 15-6. A new resource file

To enter translated strings for the Web form s user interface into a resource file, follow these steps:

  1. Type an identifier for the Web form element in the Name field of the resource file. The identifier must be unique within the scope of the application, so a convention such as formname.elementname works well for example, webform1.butOK.

  2. Type the translated string for that element in the Value field of the resource file.

Figure 15-7 shows translated strings entered for the server control and HTML elements created in the preceding section.

figure 15-7 translated strings in a resource file

Figure 15-7. Translated strings in a resource file

TIP
The Name field within a resource file is case sensitive by default. To avoid errors locating resources at run time, use a consistent capitalization scheme when naming resource elements.

Loading Resource Files

The .NET Framework provides resource management as part of the System.Resources namespace. To use classes from that namespace without fully qualifying their names, include an Imports/using statement at the beginning of your Web form, as shown here:

Visual Basic .NET

Imports System.Resources

Visual C#

using System.Resources;

To load resources into a Web form, create an instance of the ResourceManager class. For example, the following line loads the resource file for the Web application:

Visual Basic .NET

' Load resources. Protected gStrings As New ResourceManager("MCSDWebAppsVB.strings", _ GetType(Satellite).Assembly)

Visual C#

// Load resources. protected ResourceManager gStrings = new ResourceManager("MCSDWebAppsCS.strings", typeof(Satellite).Assembly);

The preceding example loads the resources stored in the Strings assembly file associated with the Satellite Web form s parent assembly and stores the returned object in the gStrings variable. The arguments for the ResourceManager class s constructor are described in Table 15-3.

Table 15-3. ResourceManager Arguments

Argument

Description

baseName

The namespace of the resource within the project. For Visual Basic .NET projects, this is projectname.resourcebasename. For Visual C# projects, this is rootnamespace.resourcebasename. The resourcebasename part omits culture codes, so MyProj.strings includes Strings.resx, Strings.en.resx, Strings.es.rex, and so on.

assembly

The object representing the current executable assembly. Use the Type class s Assembly property to get the value to pass to this argument for example, GetType( Webform1 ).Assembly.

Getting and Setting User-Interface Culture

As shown in Lesson 1, you get the user s culture from the Request object s UserLanguages array, and you set the current thread s culture using the Thread class s CurrentCulture property. When working with satellite assemblies, you need to add one more step: setting the CurrentUICulture property. This property specifies which satellite assembly is used when loading strings from the ResourceManager object.

To set the current user-interface culture for a thread, set the Thread object s CurrentUICulture property. For example, the following code gets the user s preferred language and then sets both the culture and user-interface culture for the current thread:

Visual Basic .NET

Private Sub Page_Load(ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles MyBase.Load If Not IsPostBack Then ' Get the user's perferred language. Dim sLang As String = Request.UserLanguages(0) ' Set the thread's culture for formatting, comparisons, etc. Thread.CurrentThread.CurrentCulture = _ CultureInfo.CreateSpecificCulture(slang) ' Set the thread's UICulture to load resources ' from satellite assembly. Thread.CurrentThread.CurrentUICulture = New CultureInfo(slang) End If End Sub

Visual C#

private void Page_Load(object sender, System.EventArgs e) { if (!IsPostBack) { // Get the user's perferred language. string sLang = Request.UserLanguages[0]; // Set the thread's culture for formatting, comparisons, etc. Thread.CurrentThread.CurrentCulture = CultureInfo.CreateSpecificCulture(sLang); // Set the thread's UICulture to load resources // from satellite assembly. Thread.CurrentThread.CurrentUICulture = new CultureInfo(sLang); } }

In the preceding code, the CurrentCulture and CurrentUICulture properties are set differently. CurrentCulture uses the CreateSpecificCulture method to ensure that the returned object is not a neutral culture. Neutral cultures represent general languages rather than a specific language and region. The CurrentCulture property can t be set to a neutral culture because it uses region information to format currencies, among other things.

When you have set the thread s CurrentUICulture, ASP.NET automatically selects the resources that match, in the following order:

  1. If a satellite assembly is found with an exactly matching culture, the resources from that assembly are used.

  2. If a satellite assembly is found with a neutral culture that matches the Current UICulture, resources from that assembly are used.

  3. If a match is not found for the CurrentUICulture, the fallback resources stored in the executable assembly are used.

Displaying Resource Strings

After you have completed all of the preceding tasks, displaying strings from a resource file on the Web form is straightforward.

To display strings from the resource file on a Web form, use the ResourceManager object s GetString method to retrieve strings and assign them to the Text, value, or innerHTML properties of the Web form s elements.

The following code brings the preceding steps together to load a resource file, get the user s culture, set the current thread s culture, and display strings from the resource file in the Web form server control and HTML elements:

Visual Basic .NET

Imports System.Resources Imports System.Globalization Imports System.Threading ' Load resources. Protected gStrings As New ResourceManager("MCSDWebAppsVB.strings", _ GetType(Satellite).Assembly) Private Sub Page_Load(ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles MyBase.Load If Not IsPostBack Then ' Get the user's preferred language. Dim sLang As String = Request.UserLanguages(0) ' Set the thread's culture for formatting, comparisons, etc. Thread.CurrentThread.CurrentCulture = _ CultureInfo.CreateSpecificCulture(sLang) ' Set the thread's UICulture to load resources from ' satellite assembly. Thread.CurrentThread.CurrentUICulture = New CultureInfo(sLang) ' Get strings from resource file. head1.InnerHtml = gStrings.GetString("satellite.head1") p1.InnerHtml = gStrings.GetString("satellite.p1") sp1.InnerHtml = gStrings.GetString("satellite.sp1") sp2.InnerHtml = gStrings.GetString("satellite.sp2") butOK.Text = gStrings.GetString("satellite.butOK") butCancel.Value = gStrings.GetString("satellite.butCancel") End If End Sub

Visual C#

using System.Globalization; using System.Threading; using System.Resources; // Load resources. protected ResourceManager gStrings = new ResourceManager "MCSDWebAppsCS.strings", typeof(Satellite).Assembly); private void Page_Load(object sender, System.EventArgs e) { if (!IsPostBack) { // Get the user's perferred language. string sLang = Request.UserLanguages[0]; // Set the thread's culture for formatting, comparisons, etc. Thread.CurrentThread.CurrentCulture = CultureInfo.CreateSpecificCulture(sLang); // Set the thread's UICulture to load resources // from satellite assembly. Thread.CurrentThread.CurrentUICulture = new CultureInfo(sLang); // Get strings from resource file. head1.InnerHtml = gStrings.GetString("satellite.head1"); p1.InnerHtml = gStrings.GetString("satellite.p1"); sp1.InnerHtml = gStrings.GetString("satellite.sp1"); sp2.InnerHtml = gStrings.GetString("satellite.sp2"); butOK.Text = gStrings.GetString("satellite.butOK"); butCancel.Value = gStrings.GetString("satellite.butCancel"); } }

At run time, the preceding code displays the translated strings from the resource files based on the user s preferred language, as shown in Figure 15-8.

figure 15-8 displaying strings from a resource file

Figure 15-8. Displaying strings from a resource file



MCAD(s)MCSD Self-Paced Training Kit(c) Developing Web Applications With Microsoft Visual Basic. Net and Microsoft V[.  .. ]0-315
MCAD(s)MCSD Self-Paced Training Kit(c) Developing Web Applications With Microsoft Visual Basic. Net and Microsoft V[. .. ]0-315
ISBN: N/A
EAN: N/A
Year: 2003
Pages: 118

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net