Cette documentation est archivée et n’est pas conservée.

Vue d'ensemble des ressources des pages Web ASP.NET

Si vous créez des pages Web qui seront lues par les lecteurs de différentes langues, vous devez offrir aux lecteurs un moyen de consulter la page dans leur propre langue. Une approche possible est de recréer la page dans chaque langue. Toutefois, cette approche peut nécessiter beaucoup de travail, être sujette aux erreurs et être difficile à conserver lorsque vous modifiez la page d'origine.

ASP.NET vous offre un moyen de créer une page qui peut obtenir du contenu et d'autres données basées sur le paramètre de langue par défaut pour le navigateur ou le choix explicite de l'utilisateur d'une langue. Le contenu et d'autres données sont appelées ressources et de telles données peuvent être stockées dans des fichiers de ressources ou dans d'autres sources

Dans la page Web ASP.NET, vous configurez des contrôles pour obtenir leurs valeurs de propriété à partir de ressources. Au moment de l'exécution, les expressions de ressource sont remplacées par des ressources du fichier de ressources approprié.

Fichiers de ressources

Un fichier de ressources est un fichier XML qui contient les chaînes que vous souhaitez traduire dans des langues différentes ou chemins d'accès à des images. Le fichier de ressources contient des paires clé/valeur. Chaque paire est une ressource individuelle. Les noms de clés ne respectent pas la casse. Par exemple, un fichier de ressources peut contenir une ressource avec la clé Button1 et la valeur Submit.

Vous créez un fichier de ressources séparé pour chaque langue (par exemple, anglais et français) ou pour une langue et une culture (par exemple anglais du Royaume-Uni, anglais des États-Unis). Chaque fichier de ressources localisé a les mêmes paires clé/valeur ; la seule différence est qu'un fichier de ressources localisé peut contenir moins de ressources que le fichier de ressources par défaut. La langue de secours gère ensuite le chargement de la ressource neutre ou par défaut.

Les fichiers de ressources dans ASP.NET ont une extension .resx. Au moment de l'exécution, le fichier .resx est compilé dans un assembly qui est quelquefois appelé assembly satellite. Étant donné que les fichiers .resx sont compilés dynamiquement, de la même manière que les pages Web ASP.NET, vous ne devez pas créer les assemblys de ressource. La compilation réduit plusieurs fichiers de ressources de langue semblable dans le même assembly.

Lorsque vous créez des fichiers de ressources, commencez par créer un fichier .resx de base. Pour chaque langue que vous souhaitez prendre en charge, créez un nouveau fichier qui a le même nom de fichier de base, mais avec une langue ou un langage et une culture (nom de culture) qui en fait partie. Pour obtenir la liste des noms de cultures, consultez CultureInfo. Par exemple, vous pouvez créer les éléments suivants :

  • WebResources.resx

    Fichier de ressources de base. Il s'agit du fichier de ressources par défaut ou de secours.

  • WebResources.es.resx

    Un fichier de ressources pour l'Espagnol.

  • WebResources.es-mx.resx

    Un fichier de ressources spécifiquement pour l'Espagnol (Mexique).

  • WebResources.de.resx

    Un fichier de ressources pour l'Allemand.

Au moment de l'exécution, ASP.NET utilise le fichier de ressources qui est correspond le mieux au paramètre de la propriété CurrentUICulture. La culture d'interface utilisateur pour le thread est définie selon la culture d'interface utilisateur de la page. Par exemple, si la culture d'interface utilisateur actuelle est espagnole, ASP.NET utilise la version compilée du fichier WebResources.es.resx. Si rien ne correspond à la culture d'interface utilisateur actuelle, ASP.NET utilise le fichier de ressources de secours ; en commençant par les ressources pour une culture spécifique, puis par une culture neutre et enfin par le fichier de ressources par défaut. Dans cet exemple, le fichier de ressources par défaut est WebResource.resx.

Création de fichiers de ressources pour les sites Web ASP.NET

Dans ASP.NET, vous pouvez créer des fichiers de ressources de portée différente. Vous pouvez créer des fichiers de ressources globales, ce qui signifie que vous pouvez lire le fichier de ressources à partir de toute page ou code qui se trouve dans le site Web. Vous pouvez également créer des fichiers de ressources locales qui stockent des ressources pour une page Web ASP.NET seule (fichier .aspx).

Fichiers de ressources globales

Vous créez un fichier de ressources globales en le plaçant dans le dossier réservé App_GlobalResources à la racine de l'application. Tout fichier .resx qui se trouve dans le dossier App_GlobalResources a une portée globale. En outre, ASP.NET génère un objet fortement typé qui fournit aux développeurs une manière simple d'accéder par programme aux ressources globales.

Fichiers de ressources locales

Un fichier de ressources locales est un fichier qui s'applique à une seule page ASP.NET (une page ASP.NET avec l'extension .aspx, .ascx, .master, etc). Vous placez des fichiers de ressources locales dans des dossiers dont le nom réservé est App_LocalResources. Les dossiers App_LocalResources peuvent exister dans tout dossier dans l'application, contrairement au dossier racine App_GlobalResources. Vous associez un jeu de fichiers de ressources à une page Web spécifique à l'aide du nom du fichier de ressources.

Par exemple, si vous avez une page nommée Default.aspx dans le dossier App_LocalResources, vous pouvez créer les fichiers suivants :

  • Default.aspx.resx

    Le fichier de ressources locales par défaut, qui est le fichier de ressources de secours, si aucune correspondance de langue n'est trouvée.

  • Default.aspx.es.resx

    Le fichier de ressources pour l'Espagnol, sans information de culture.

  • Default.aspx.es-mx.resx

    Le fichier de ressources spécifiquement pour l'Espagnol (Mexique).

  • Default.aspx.fr.resx

    Le fichier de ressources pour le Français, sans information de culture.

Le nom de base du fichier correspond au nom de fichier d'échange, suivi par une langue et un nom de culture et se termine avec l'extension .resx. Pour obtenir la liste des noms de cultures, consultez CultureInfo.

Choix entre les fichiers de ressources globales et locales

Vous pouvez utiliser toute combinaison de fichiers de ressources globales et locales dans l'application Web. En général, vous ajoutez des ressources à un fichier de ressources globales lorsque vous souhaitez partager les ressources entre des pages. Les ressources dans les fichiers de ressources globales sont également fortement typées pour les accès aux fichiers par programme.

Toutefois, les fichiers de ressources globales peuvent devenir volumineux, si y vous stockez toutes les ressources localisées. Les fichiers de ressources globales peuvent également être plus difficiles à gérer, si plusieurs développeurs travaillent sur différentes pages dans un fichier de ressources unique.

Les fichiers de ressources locales simplifient la gestion des ressources pour une page Web ASP.NET seule. Mais vous ne pouvez pas partager les ressources entre les pages. En outre, vous pouvez créer de nombreux fichiers de ressources locales, si vous devez localiser un grand nombre de pages dans de nombreuses langues. Si les sites sont grands avec de nombreux dossiers et langues, l'utilisation de ressources locales peut rapidement développer le nombre d'assemblys dans le domaine d'application.

Lorsque vous apportez une modification à un fichier de ressources par défaut, locales ou globales, ASP.NET recompile les ressources et redémarre l'application ASP.NET ce qui peut affecter la performance globale de votre site. L'ajout de fichiers de ressources satellites ne provoquera pas de recompilation de ressources, mais l'application ASP.NET redémarrera.

RemarqueRemarque

Les ressources liées sont prises en charge uniquement dans les fichiers de ressources globales.

Utilisation de ressources dans des pages Web

Après avoir créé des fichiers de ressources, vous pouvez les utiliser dans des pages Web ASP.NET. En général, vous utilisez des ressources pour remplir les valeurs de propriété de contrôles sur la page. Par exemple, vous pouvez utiliser des ressources pour définir la propriété Text d'un contrôle Button, au lieu de coder en dur la propriété en une chaîne spécifique.

Pour utiliser des ressources pour affecter des valeurs de propriété de contrôle, vous pouvez utiliser la localisation implicite ou explicite, comme suit :

  • La localisation implicite fonctionne avec les ressources locales et vous laisse affecter automatiquement à des propriétés de contrôle des ressources correspondantes.

  • La localisation explicite vous permet d'utiliser une expression de ressource pour affecter à une propriété de contrôle une ressource spécifique dans un fichier de ressources locales ou globales.

Localisation implicite avec des ressources locales

Si vous avez créé des fichiers de ressources locales pour une page spécifique, vous pouvez utiliser la localisation implicite pour remplir les valeurs de propriété pour un contrôle à partir du fichier de ressources. Avec la localisation implicite, ASP.NET lit un fichier de ressources et fait correspondre les ressources et les valeurs de propriété.

Pour utiliser la localisation implicite, vous devez utiliser une convention d'affectation de noms pour les ressources dans le fichier de ressources locales qui utilise le schéma suivant :

Key . Property

Par exemple, si vous créez des ressources pour un contrôle Button nommé Button1, vous pouvez créer les paires clé/valeur suivantes dans le fichier de ressources locales :

Button1.Text
Button1.BackColor
Label1.Text

Vous pouvez utiliser tout nom pour Key, mais Property doit correspondre à une propriété du contrôle que vous localisez.

Dans la page, vous utilisez un attribut meta spécial dans le balisage pour le contrôle pour spécifier la localisation implicite. Vous ne devez pas spécifier explicitement les propriétés localisées. Un contrôle Button qui est configuré pour la localisation implicite peut sembler semblable aux éléments suivants :

<asp:Button ID="Button1" runat="server" Text="DefaultText" 
    meta:resourcekey="Button1" />

La valeur resourcekey correspond à une clé dans le fichier de ressources correspondant. Au moment de l'exécution, ASP.NET fait correspondre les ressources aux propriétés de contrôle à l'aide de l'étiquette de contrôle en tant que resourcekey. Si une valeur de propriété est définie dans le fichier de ressources, ASP.NET substitue la valeur de ressource à la propriété.

Localisation explicite

Vous pouvez également utiliser la localisation explicite, dans laquelle vous utilisez une expression de ressource. Contrairement à localisation implicite, vous devez utiliser une expression de ressource pour chaque propriété que vous souhaitez définir.

Un contrôle Button qui est configuré pour définir la propriété Text à partir d'un fichier de ressources globales peut être semblable aux éléments suivants :

<asp:Button ID="Button1" runat="server" 
    Text="<%$ Resources:WebResources, Button1Caption %>" />

L'expression de ressource prend la forme suivante, où Class est facultatif, à moins que la ressource ne soit globale et où ResourceID est requis :

<%$ Ressources : Class , ResourceID %>

La valeur Class identifie le fichier de ressources à utiliser lorsque vous utilisez des ressources globales. Lorsque les fichiers .resx sont compilés, le nom de fichier de base, sans extension, est explicitement utilisé comme nom de classe de l'assembly résultant. Si vous souhaitez utiliser des ressources d'un fichier de ressources locales (un fichier qui correspond au nom de page actuel), vous ne devez pas inclure de nom de classe, car ASP.NET fait correspondre la classe de page à la classe de ressource.

La valeur ResourceID est l'identificateur de la ressource à lire. Dans l'exemple précédent, la propriété Text pour le bouton est lue à partir du fichier de ressources globales WebResources.resx (ou la version localisée appropriée). Dans ce fichier, ASP.NET utilise la valeur pour la ressource avec l'identificateur Button1Caption et pour la page elle-même. Pour définir des propriétés de page, vous pouvez utiliser des expressions de ressource dans la directive @ Page.

Vous pouvez spécifier une expression de ressource explicite ou implicite pour un contrôle, mais pas les deux. La syntaxe déclarative suivante sur un contrôle Button provoquera une erreur d'analyse :

<asp:Button ID="Button1" 
            runat="server" 
            meta:resourcekey="Button1Resource1"
            Text="<%$ Resources:WebResources, Button1Caption %>" />

Dans cet exemple, un fichier de ressources local implicite (qui correspond au nom de la page actuelle) est spécifié ainsi qu'un fichier de ressources explicite appelé WebResources. Pour éviter une erreur d'analyse pour ce contrôle, supprimez l'une des expressions de ressource.

Localisation de texte statique

Si votre page inclut du texte statique, vous pouvez utiliser la localisation ASP.NET en l'incluant dans un contrôle Localize et utiliser ensuite la localisation explicite pour définir le texte statique. Le contrôle Localize ne restitue pas de balisage ; sa seule fonction est d'agir en tant qu'espace réservé pour du texte localisé. Le contrôle Localize peut être modifié en mode Design et non uniquement dans la grille des propriétés. Au moment de l'exécution, ASP.NET traite le contrôle Localize en tant que contrôle Literal. Par exemple, votre page peut inclure le code suivant :

Note de sécuritéRemarque de sécurité

Cet exemple a une zone de texte qui accepte l'entrée d'utilisateur, ce qui constitue une menace éventuelle pour la sécurité. Par défaut, les pages Web ASP.NET vérifient que les entrées d'utilisateur n'incluent pas de script ou d'éléments HTML. Pour plus d'informations, consultez Vue d'ensemble des attaques de script.

 <h1>
    <asp:Localize runat=server 
      ID="WelcomeMessage" 
      Text="Welcome!" meta:resourcekey="LiteralResource1" />
</h1>
<br />
<br />
<asp:Localize runat="server"
    ID="NameCaption"
    Text="Name: " meta:resourcekey="LiteralResource2" />
<asp:TextBox runat="server" ID="TextBox1" 
    meta:resourcekey="TextBox1Resource1" />

Localisation implicite dans les modèles

Dans les contrôles basés sur des modèles, tels que les contrôles DataList, GridView et Wizard, vous localisez les propriétés de style du modèle en accédant aux propriétés par le biais de l'expression de ressource implicite du contrôle parent. Vous ne pouvez pas utiliser d'expression de ressource implicite sur le modèle lui-même.

Pour localiser les valeurs d'une propriété de modèle, utilisez l'attribut meta avec une clé de ressource pour le contrôle auquel le modèle appartient et utilisez la syntaxe Property.Subproperty ou Property-Subproperty dans le fichier de ressources. Par exemple, la syntaxe déclarative suivante est valide pour un contrôle Wizard :

<asp:Wizard ID="Wizard1" 
            runat="server" 
            meta:resourcekey="Wizard1Resource1">
    <NavigationStyle 
            BorderWidth="<%$ resources:navBorderWidth %>"/>
    <WizardSteps>
        <asp:WizardStep ID="WizardStep1" 
            runat="server" 
            Title="Step 1" 
            meta:resourcekey="WizardStep1Resource1">
        </asp:WizardStep>
    </WizardSteps>
</asp:Wizard>

Les paires clé/valeur suivantes dans le fichier de ressources local pourraient être utilisées pour l'exemple ci-dessus :

Wizard1Resource1.NavigationStyle.BackColor, Red
navborderWidth, 5

Les paires clé/valeur suivantes pourraient également être utilisées :

Wizard1Resource1.NavigationStyle-BackColor, Red
navborderWidth, 5

Notez que vous pouvez utiliser une expression de ressource explicite pour la propriété NavigationStyle du contrôle Wizard dans l'exemple ci-dessus. L'expression de ressource explicite omet le nom Class afin que les ressources d'un fichier de ressources local soient utilisées.

Pour plus d'informations sur les contrôles serveur basés sur des modèles, consultez Modèles de contrôles serveur Web ASP.NET.

Sélection de fichiers de ressources pour différentes langues

Lorsqu'une page est exécutée et lorsque ASP.NET récupère des valeurs du gestionnaire des ressources, ASP.NET sélectionne la version du fichier de ressources qui correspond le plus au paramètre UICulture actuel pour la page ou utilise le fichier de ressources de secours pour obtenir une ressource. Par exemple, si vous exécutez la page Default.aspx et la propriété UICulture actuelle a la valeur es (Espagnol), ASP.NET utilise la version compilée du fichier de ressources locales Default.aspx.es.resx.

ASP.NET peut affecter aux propriétés UICulture et Culture pour la page la langue et les valeurs de culture qui sont passées par le navigateur. Vous pouvez également définir explicitement les propriétés UICulture et Culture, soit de manière déclarative ou dans le code. Vous pouvez également définir les valeurs de manière déclarative dans les fichiers Web.config. Pour plus d'informations, consultez Comment : définir la culture et la culture de l'interface utilisateur pour la globalisation des pages Web ASP.NET.

RemarqueRemarque

Vous ne devez pas compter exclusivement sur les paramètres de navigateur pour définir la langue et les informations de culture, car les utilisateurs peuvent utiliser un navigateur sur un ordinateur autre que le leur. En outre, il est fréquent que les navigateurs ne communiquent que langage et non une culture spécifique. Dans ce cas, le serveur doit déduire une culture spécifique pour la mise en forme des données. Une bonne stratégie est de laisser les utilisateurs sélectionner explicitement une langue.

Utilisation des ressources par programme

Outre la définition de valeurs de la ressource dans le balisage avec les expressions de ressource, vous pouvez récupérer des valeurs de ressource par programme. Vous pouvez effectuer ceci si la valeur de ressource n'est pas connue au moment du design ou si vous souhaitez définir la valeur de ressource selon une condition d'exécution. Pour plus d'informations, consultez Comment : récupérer des valeurs de ressources par programme.

Voir aussi

Afficher: