Partager via

Classe System.Resources.ResourceManager

  • Article

Cet article vous offre des remarques complémentaires à la documentation de référence pour cette API.

Important

L’appel de méthodes de cette classe avec des données non approuvées est un risque de sécurité. Appelez les méthodes de cette classe avec des données approuvées uniquement. Pour plus d’informations, consultez Valider toutes les entrées.

La ResourceManager classe récupère des ressources à partir d’un fichier .resources binaire incorporé dans un assembly ou à partir d’un fichier .resources autonome. Si une application a été localisée et localisée des ressources ont été déployées dans des assemblys satellites, elle recherche des ressources propres à la culture, fournit une secours des ressources lorsqu’une ressource localisée n’existe pas et prend en charge la sérialisation des ressources.

Applications de bureau

Pour les applications de bureau, la ResourceManager classe récupère des ressources à partir de fichiers de ressources binaires (.resources). En règle générale, un compilateur de langage ou l’Assembly Linker (AL.exe) incorpore ces fichiers de ressources dans un assembly. Vous pouvez également utiliser un ResourceManager objet pour récupérer des ressources directement à partir d’un fichier .resources qui n’est pas incorporé dans un assembly, en appelant la CreateFileBasedResourceManager méthode.

Attention

L’utilisation de fichiers .resources autonomes dans une application ASP.NET interrompt le déploiement XCOPY, car les ressources restent verrouillées jusqu’à ce qu’elles soient explicitement libérées par la ReleaseAllResources méthode. Si vous souhaitez déployer des ressources avec vos applications ASP.NET, vous devez compiler vos fichiers .resources dans des assemblys satellites.

Dans une application basée sur des ressources, un fichier .resources contient les ressources de la culture par défaut dont les ressources sont utilisées si aucune ressource spécifique à la culture n’est disponible. Par exemple, si la culture par défaut d’une application est l’anglais (en), les ressources de langue anglaise sont utilisées chaque fois que des ressources localisées ne sont pas disponibles pour une culture spécifique, telle que l’anglais (États-Unis) (en-US) ou Français (France) (fr-FR). En règle générale, les ressources de la culture par défaut sont incorporées dans l’assembly d’application principal, et les ressources pour d’autres cultures localisées sont incorporées dans des assemblys satellites. Les assemblys satellites contiennent uniquement des ressources. Ils ont le même nom de fichier racine que l’assembly principal et une extension de .resources.dll. Pour les applications dont les assemblys ne sont pas inscrits dans le Global Assembly Cache, les assemblys satellites sont stockés dans un sous-répertoire d’application dont le nom correspond à la culture de l’assembly.

Créer des ressources

Lorsque vous développez une application basée sur des ressources, vous stockez des informations de ressource dans des fichiers texte (fichiers qui ont une extension .txt ou .restext) ou XML (fichiers qui ont une extension .resx). Vous compilez ensuite les fichiers texte ou XML avec le générateur de fichiers de ressources (Resgen.exe) pour créer un fichier .resources binaire. Vous pouvez ensuite incorporer le fichier .resources résultant dans un exécutable ou une bibliothèque à l’aide d’une option de compilateur telle que /resources pour les compilateurs C# et Visual Basic, ou vous pouvez l’incorporer dans un assembly satellite à l’aide de l’Assembly Linker (AI.exe). Si vous incluez un fichier .resx dans votre projet Visual Studio, Visual Studio gère automatiquement la compilation et l’incorporation de ressources par défaut et localisées dans le cadre du processus de génération.

Dans l’idéal, vous devez créer des ressources pour chaque langue prise en charge par votre application, ou au moins pour un sous-ensemble significatif de chaque langue. Les noms de fichiers .resources binaires suivent le nom de base de convention d’affectation de noms.cultureName.resources, où basename est le nom de l’application ou le nom d’une classe, en fonction du niveau de détail souhaité. La CultureInfo.Name propriété est utilisée pour déterminer cultureName. Une ressource pour la culture par défaut de l’application doit être nommée basename.resources.

Par exemple, supposons qu’un assembly possède plusieurs ressources dans un fichier de ressources qui a le nom de base MyResources. Ces fichiers de ressources doivent avoir des noms tels que MyResources.ja-JP.resources pour la culture japonaise (japonaise), MyResources.de.resources pour la culture allemande, MyResources.zh-CHS.resources pour la culture chinoise simplifiée et MyResources.fr-BE.resources pour la culture Français (Belgique). Le fichier de ressources par défaut doit être nommé MyResources.resources. Les fichiers de ressources spécifiques à la culture sont généralement empaquetés dans les assemblys satellites pour chaque culture. Le fichier de ressources par défaut doit être incorporé dans l’assembly principal de l’application.

Notez que Assembly Linker permet aux ressources d’être marquées comme privées, mais vous devez toujours les marquer comme publiques afin qu’elles soient accessibles par d’autres assemblys. (Étant donné qu’un assembly satellite ne contient aucun code, les ressources marquées comme privées ne sont pas disponibles pour votre application via n’importe quel mécanisme.)

Pour plus d’informations sur la création, l’empaquetage et le déploiement de ressources, consultez les articles Création de fichiers de ressources, Création d’assemblys satellites et empaquetage et déploiement de ressources.

Instancier un objet ResourceManager

Vous instanciez un ResourceManager objet qui récupère des ressources à partir d’un fichier .resources incorporé en appelant l’une de ses surcharges de constructeur de classe. Cela couple étroitement un ResourceManager objet avec un fichier .resources particulier et avec tous les fichiers .resources localisés associés dans les assemblys satellites.

Les deux constructeurs les plus couramment appelés sont les suivants :

  • ResourceManager(String, Assembly) recherche des ressources en fonction de deux informations que vous fournissez : le nom de base du fichier .resources et l’assembly dans lequel réside le fichier .resources par défaut. Le nom de base inclut l’espace de noms et le nom racine du fichier .resources, sans sa culture ou son extension. Notez que les fichiers .resources compilés à partir de la ligne de commande n’incluent généralement pas de nom d’espace de noms, tandis que les fichiers .resources créés dans l’environnement Visual Studio le font. Par exemple, si un fichier de ressources est nommé MyCompany.StringResources.resources et que le ResourceManager constructeur est appelé à partir d’une méthode statique nommée Example.Main, le code suivant instancie un ResourceManager objet qui peut récupérer des ressources à partir du fichier .resources :

    ResourceManager rm = new ResourceManager("MyCompany.StringResources",
                                         typeof(Example).Assembly);

    Dim rm As New ResourceManager("MyCompany.StringResources",
                            GetType(Example2).Assembly)

  • ResourceManager(Type) recherche des ressources dans les assemblys satellites en fonction des informations d’un objet de type. Le nom complet du type correspond au nom de base du fichier .resources sans son extension de nom de fichier. Dans les applications de bureau créées à l’aide du Concepteur de ressources Visual Studio, Visual Studio crée une classe wrapper dont le nom complet est identique au nom racine du fichier .resources. Par exemple, si un fichier de ressources est nommé MyCompany.StringResources.resources et qu’il existe une classe wrapper nommée MyCompany.StringResources, le code suivant instancie un ResourceManager objet qui peut récupérer des ressources à partir du fichier .resources :

    ResourceManager rm = new ResourceManager(typeof(MyCompany.StringResources));

    Dim rm As New ResourceManager(GetType(MyCompany.StringResources))

Si les ressources appropriées sont introuvables, l’appel du constructeur crée un objet valide ResourceManager . Toutefois, la tentative de récupération d’une ressource lève une MissingManifestResourceException exception. Pour plus d’informations sur la gestion de l’exception, consultez la section Handle MissingManifestResourceException et MissingSatelliteAssemblyException Exceptions plus loin dans cet article.

L’exemple suivant montre comment instancier un ResourceManager objet. Il contient le code source d’un exécutable nommé ShowTime.exe. Il inclut également le fichier texte suivant nommé Strings.txt qui contient une ressource de chaîne unique : TimeHeader

TimeHeader=The current time is

Vous pouvez utiliser un fichier de commandes pour générer le fichier de ressources et l’incorporer dans l’exécutable. Voici le fichier de commandes pour générer un exécutable à l’aide du compilateur C# :

resgen strings.txt
csc ShowTime.cs /resource:strings.resources

Pour le compilateur Visual Basic, vous pouvez utiliser le fichier batch suivant :

resgen strings.txt
vbc ShowTime.vb /resource:strings.resources

using System;
using System.Resources;

public class ShowTimeEx
{
    public static void Main()
    {
        ResourceManager rm = new ResourceManager("Strings",
                                 typeof(Example).Assembly);
        string timeString = rm.GetString("TimeHeader");
        Console.WriteLine("{0} {1:T}", timeString, DateTime.Now);
    }
}
// The example displays output like the following:
//        The current time is 2:03:14 PM

Imports System.Resources

Module Example6
    Public Sub Main()
        Dim rm As New ResourceManager("Strings", GetType(Example6).Assembly)
        Dim timeString As String = rm.GetString("TimeHeader")
        Console.WriteLine("{0} {1:T}", timeString, Date.Now)
    End Sub
End Module
' The example displays output similar to the following:
'       The current time is 2:03:14 PM

Ressources ResourceManager et propres à la culture

Une application localisée nécessite le déploiement de ressources, comme indiqué dans l’article Empaquetage et déploiement de ressources. Si les assemblys sont correctement configurés, le gestionnaire de ressources détermine les ressources à récupérer en fonction de la propriété du Thread.CurrentUICulture thread actuel. (Cette propriété retourne également la culture de l’interface utilisateur du thread actuel.) Par exemple, si une application est compilée avec des ressources de langue anglaise par défaut dans l’assembly principal et avec des ressources de langue Français et russe dans deux assemblys satellites, et que la Thread.CurrentUICulture propriété est définie sur fr-FR, le gestionnaire de ressources récupère les ressources Français.

Vous pouvez définir la CurrentUICulture propriété explicitement ou implicitement. La façon dont vous la définissez détermine comment l’objet ResourceManager récupère les ressources en fonction de la culture :

  • Si vous définissez explicitement la Thread.CurrentUICulture propriété sur une culture spécifique, le gestionnaire de ressources récupère toujours les ressources de cette culture, quel que soit le navigateur ou le langage du système d’exploitation de l’utilisateur. Considérez une application compilée avec les ressources de langue anglaise par défaut et trois assemblys satellites qui contiennent des ressources pour l’anglais (États-Unis), Français (France) et russe (Russie). Si la CurrentUICulture propriété est définie sur fr-FR, l’objet ResourceManager récupère toujours les ressources Français (France), même si la langue du système d’exploitation de l’utilisateur n’est pas Français. Assurez-vous qu’il s’agit du comportement souhaité avant de définir explicitement la propriété.

    Dans ASP.NET applications, vous devez définir la Thread.CurrentUICulture propriété explicitement, car il est peu probable que le paramètre sur le serveur corresponde aux demandes clientes entrantes. Une application ASP.NET peut définir la Thread.CurrentUICulture propriété explicitement sur la langue d’acceptation du navigateur de l’utilisateur.

    Définir explicitement la propriété définit la culture actuelle de l’interface Thread.CurrentUICulture utilisateur pour ce thread. Elle n’affecte pas la culture actuelle de l’interface utilisateur des autres threads d’une application.

  • Vous pouvez définir la culture de l’interface utilisateur de tous les threads d’un domaine d’application en affectant un CultureInfo objet qui représente cette culture à la propriété statique CultureInfo.DefaultThreadCurrentUICulture .

  • Si vous ne définissez pas explicitement la culture actuelle de l’interface utilisateur et que vous ne définissez pas de culture par défaut pour le domaine d’application actuel, la CultureInfo.CurrentUICulture propriété est définie implicitement par la fonction Windows GetUserDefaultUILanguage . Cette fonction est fournie par l’interface utilisateur multilingue (MUI), qui permet à l’utilisateur de définir la langue par défaut. Si la langue de l’interface utilisateur n’est pas définie par l’utilisateur, elle est définie par défaut sur la langue installée par le système, qui est la langue des ressources du système d’exploitation.

L’exemple « Hello world » suivant montre comment définir explicitement la culture actuelle de l’interface utilisateur. Il contient des ressources pour trois cultures : anglais (États-Unis) ou en-US, Français (France) ou fr-FR, et russe (Russie) ou ru-RU. Les ressources en-US sont contenues dans un fichier texte nommé Greetings.txt :

HelloString=Hello world!

Les ressources fr-FR sont contenues dans un fichier texte nommé Greetings.fr-FR.txt :

HelloString=Salut tout le monde!

Les ressources ru-RU sont contenues dans un fichier texte nommé Greetings.ru-RU.txt :

HelloString=Всем привет!

Voici le code source de l’exemple (Example.vb pour la version Visual Basic ou Example.cs pour la version C#) :

using System;
using System.Globalization;
using System.Resources;
using System.Threading;

public class Example
{
    public static void Main()
    {
        // Create array of supported cultures
        string[] cultures = { "en-CA", "en-US", "fr-FR", "ru-RU" };
        Random rnd = new Random();
        int cultureNdx = rnd.Next(0, cultures.Length);
        CultureInfo originalCulture = Thread.CurrentThread.CurrentCulture;
        ResourceManager rm = new ResourceManager("Greetings", typeof(Example).Assembly);
        try
        {
            CultureInfo newCulture = new CultureInfo(cultures[cultureNdx]);
            Thread.CurrentThread.CurrentCulture = newCulture;
            Thread.CurrentThread.CurrentUICulture = newCulture;
            string greeting = String.Format("The current culture is {0}.\n{1}",
                                            Thread.CurrentThread.CurrentUICulture.Name,
                                            rm.GetString("HelloString"));
            Console.WriteLine(greeting);
        }
        catch (CultureNotFoundException e)
        {
            Console.WriteLine("Unable to instantiate culture {0}", e.InvalidCultureName);
        }
        finally
        {
            Thread.CurrentThread.CurrentCulture = originalCulture;
            Thread.CurrentThread.CurrentUICulture = originalCulture;
        }
    }
}
// The example displays output like the following:
//       The current culture is ru-RU.
//       Всем привет!

Imports System.Globalization
Imports System.Resources
Imports System.Threading

Module Example
   Sub Main()
      ' Create array of supported cultures
      Dim cultures() As String = {"en-CA", "en-US", "fr-FR", "ru-RU" }
      Dim rnd As New Random()
      Dim cultureNdx As Integer = rnd.Next(0, cultures.Length)
      Dim originalCulture As CultureInfo = Thread.CurrentThread.CurrentCulture
      Dim rm As New ResourceManager("Greetings", GetType(Example).Assembly)
      Try
         Dim newCulture As New CultureInfo(cultures(cultureNdx))
         Thread.CurrentThread.CurrentCulture = newCulture
         Thread.CurrentThread.CurrentUICulture = newCulture
         Dim greeting As String = String.Format("The current culture is {0}.{1}{2}",
                                                Thread.CurrentThread.CurrentUICulture.Name,
                                                vbCrLf, rm.GetString("HelloString"))

         Console.WriteLine(greeting)
      Catch e As CultureNotFoundException
         Console.WriteLine("Unable to instantiate culture {0}", e.InvalidCultureName)
      Finally
         Thread.CurrentThread.CurrentCulture = originalCulture
         Thread.CurrentThread.CurrentUICulture = originalCulture
      End Try
   End Sub
End Module
' The example displays output like the following:
'       The current culture is ru-RU.
'       Всем привет!

Pour compiler cet exemple, créez un fichier de lots (.bat) qui contient les commandes suivantes et exécutez-le à partir de l’invite de commandes. Si vous utilisez C#, spécifiez csc plutôt vbc que .Example.csExample.vb

resgen Greetings.txt
vbc Example.vb /resource:Greetings.resources

resgen Greetings.fr-FR.txt
Md fr-FR
al /embed:Greetings.fr-FR.resources /culture:fr-FR /out:fr-FR\Example.resources.dll

resgen Greetings.ru-RU.txt
Md ru-RU
al /embed:Greetings.ru-RU.resources /culture:ru-RU /out:ru-RU\Example.resources.dll

Récupérer des ressources

Vous appelez les méthodes et GetString(String) les GetObject(String) méthodes pour accéder à une ressource spécifique. Vous pouvez également appeler la GetStream(String) méthode pour récupérer des ressources non-chaînes en tant que tableau d’octets. Par défaut, dans une application qui a des ressources localisées, ces méthodes retournent la ressource pour la culture déterminée par la culture actuelle de l’interface utilisateur du thread qui a effectué l’appel. Pour plus d’informations sur la façon dont la culture actuelle d’un thread est définie, consultez la section précédente, ResourceManager et les ressources spécifiques à la culture de culture. Si le gestionnaire de ressources ne trouve pas la ressource pour la culture de l’interface utilisateur du thread actuel, il utilise un processus de secours pour récupérer la ressource spécifiée. Si le gestionnaire de ressources ne trouve pas de ressources localisées, il utilise les ressources de la culture par défaut. Pour plus d’informations sur les règles de secours des ressources, consultez la section « Processus de secours des ressources » de l’article Empaquetage et déploiement de ressources.

Remarque

Si le fichier .resources spécifié dans le ResourceManager constructeur de classe est introuvable, la tentative de récupération d’une ressource lève une exception ou MissingSatelliteAssemblyException une MissingManifestResourceException exception. Pour plus d’informations sur la gestion de l’exception, consultez la section Handle MissingManifestResourceException et MissingSatelliteAssemblyException Exceptions plus loin dans cet article.

L’exemple suivant utilise la méthode pour récupérer des ressources spécifiques à la GetString culture. Il se compose de ressources compilées à partir de .txt fichiers pour les cultures anglaises (en), Français (France) (fr-FR) et russe (Russie) (ru-RU). L’exemple modifie la culture actuelle et la culture actuelle de l’interface utilisateur en anglais (États-Unis), Français (France), Russe (Russie) et Suédois (Suède). Il appelle ensuite la GetString méthode pour récupérer la chaîne localisée, qu’elle affiche avec le jour et le mois actuels. Notez que la sortie affiche la chaîne localisée appropriée, sauf lorsque la culture actuelle de l’interface utilisateur est suédoise (Suède). Étant donné que les ressources de langue suédoise ne sont pas disponibles, l’application utilise plutôt les ressources de la culture par défaut, qui est l’anglais.

L’exemple nécessite les fichiers de ressources textuels répertoriés dans le tableau suivant. Chacun a une ressource de chaîne unique nommée DateStart.

culture Nom de fichier Nom de la ressource Valeur de la ressource
fr-FR DateStrings.txt DateStart Aujourd’hui est
fr-FR DateStrings.fr-FR.txt DateStart Aujourd’hui, c’est le
ru-RU DateStrings.ru-RU.txt DateStart Сегодня

Voici le code source de l’exemple (ShowDate.vb pour la version Visual Basic ou ShowDate.cs pour la version C# du code).

using System;
using System.Globalization;
using System.Resources;
using System.Threading;

[assembly: NeutralResourcesLanguage("en")]

public class ShowDateEx
{
    public static void Main()
    {
        string[] cultureNames = { "en-US", "fr-FR", "ru-RU", "sv-SE" };
        ResourceManager rm = new ResourceManager("DateStrings",
                                                 typeof(Example).Assembly);

        foreach (var cultureName in cultureNames)
        {
            CultureInfo culture = CultureInfo.CreateSpecificCulture(cultureName);
            Thread.CurrentThread.CurrentCulture = culture;
            Thread.CurrentThread.CurrentUICulture = culture;

            Console.WriteLine("Current UI Culture: {0}",
                              CultureInfo.CurrentUICulture.Name);
            string dateString = rm.GetString("DateStart");
            Console.WriteLine("{0} {1:M}.\n", dateString, DateTime.Now);
        }
    }
}
// The example displays output similar to the following:
//       Current UI Culture: en-US
//       Today is February 03.
//       
//       Current UI Culture: fr-FR
//       Aujourd'hui, c'est le 3 février
//       
//       Current UI Culture: ru-RU
//       Сегодня февраля 03.
//       
//       Current UI Culture: sv-SE
//       Today is den 3 februari.

Imports System.Globalization
Imports System.Resources
Imports System.Threading

<Assembly:NeutralResourcesLanguage("en")>

Module Example5
    Public Sub Main()
        Dim cultureNames() As String = {"en-US", "fr-FR", "ru-RU", "sv-SE"}
        Dim rm As New ResourceManager("DateStrings",
                                    GetType(Example5).Assembly)

        For Each cultureName In cultureNames
            Dim culture As CultureInfo = CultureInfo.CreateSpecificCulture(cultureName)
            Thread.CurrentThread.CurrentCulture = culture
            Thread.CurrentThread.CurrentUICulture = culture

            Console.WriteLine("Current UI Culture: {0}",
                           CultureInfo.CurrentUICulture.Name)
            Dim dateString As String = rm.GetString("DateStart")
            Console.WriteLine("{0} {1:M}.", dateString, Date.Now)
            Console.WriteLine()
        Next
    End Sub
End Module
' The example displays output similar to the following:
'       Current UI Culture: en-US
'       Today is February 03.
'       
'       Current UI Culture: fr-FR
'       Aujourd'hui, c'est le 3 février
'       
'       Current UI Culture: ru-RU
'       Сегодня февраля 03.
'       
'       Current UI Culture: sv-SE
'       Today is den 3 februari.

Pour compiler cet exemple, créez un fichier de commandes qui contient les commandes suivantes et exécutez-le à partir de l’invite de commandes. Si vous utilisez C#, spécifiez csc plutôt vbc que .showdate.csshowdate.vb

resgen DateStrings.txt
vbc showdate.vb /resource:DateStrings.resources

md fr-FR
resgen DateStrings.fr-FR.txt
al /out:fr-FR\Showdate.resources.dll /culture:fr-FR /embed:DateStrings.fr-FR.resources

md ru-RU
resgen DateStrings.ru-RU.txt
al /out:ru-RU\Showdate.resources.dll /culture:ru-RU /embed:DateStrings.ru-RU.resources

Il existe deux façons de récupérer les ressources d’une culture spécifique autre que la culture actuelle de l’interface utilisateur :

  • Vous pouvez appeler le GetString(String, CultureInfo), GetObject(String, CultureInfo)ou GetStream(String, CultureInfo) la méthode pour récupérer une ressource pour une culture spécifique. Si une ressource localisée est introuvable, le gestionnaire de ressources utilise le processus de secours de ressource pour localiser une ressource appropriée.
  • Vous pouvez appeler la GetResourceSet méthode pour obtenir un ResourceSet objet qui représente les ressources d’une culture particulière. Dans l’appel de méthode, vous pouvez déterminer si le gestionnaire de ressources sonde les cultures parentes s’il n’est pas en mesure de trouver des ressources localisées ou s’il revient simplement aux ressources de la culture par défaut. Vous pouvez ensuite utiliser les ResourceSet méthodes pour accéder aux ressources (localisées pour cette culture) par nom ou pour énumérer les ressources dans l’ensemble.

Gérer les exceptions MissingManifestResourceException et MissingSatelliteAssemblyException

Si vous essayez de récupérer une ressource spécifique, mais que le gestionnaire de ressources ne trouve pas cette ressource et qu’aucune culture par défaut n’a été définie ou que les ressources de la culture par défaut ne peuvent pas être localisées, le gestionnaire de ressources lève une MissingManifestResourceException exception si elle s’attend à trouver les ressources dans l’assembly principal ou si MissingSatelliteAssemblyException elle s’attend à trouver les ressources dans un assembly satellite. Notez que l’exception est levée lorsque vous appelez une méthode de récupération de ressources telle que GetString ou GetObject, et non lorsque vous instanciez un ResourceManager objet.

L’exception est généralement levée dans les conditions suivantes :

  • Le fichier de ressources ou l’assembly satellite approprié n’existe pas. Si le gestionnaire de ressources s’attend à ce que les ressources par défaut de l’application soient incorporées dans l’assembly d’application principal, elles sont absentes. Si l’attribut NeutralResourcesLanguageAttribute indique que les ressources par défaut de l’application résident dans un assembly satellite, cet assembly est introuvable. Lorsque vous compilez votre application, assurez-vous que les ressources sont incorporées dans l’assembly principal ou que l’assembly satellite nécessaire est généré et est nommé de manière appropriée. Son nom doit prendre la forme appName.resources.dll et il doit se trouver dans un répertoire nommé après la culture dont il contient les ressources.

  • Votre application n’a pas de culture par défaut ou neutre définie. Ajoutez l’attribut NeutralResourcesLanguageAttribute à un fichier de code source ou au fichier d’informations de projet (AssemblyInfo.vb pour une application Visual Basic ou AssemblyInfo.cs pour un fichier d’application C#).

  • Le baseName paramètre du ResourceManager(String, Assembly) constructeur ne spécifie pas le nom d’un fichier .resources. Le nom doit inclure l’espace de noms complet du fichier de ressources, mais pas son extension de nom de fichier. En règle générale, les fichiers de ressources créés dans Visual Studio incluent des noms d’espaces de noms, mais les fichiers de ressources créés et compilés à l’invite de commandes ne le sont pas. Vous pouvez déterminer les noms des fichiers .resources incorporés en compilant et en exécutant l’utilitaire suivant. Il s’agit d’une application console qui accepte le nom d’un assembly principal ou d’un assembly satellite en tant que paramètre de ligne de commande. Il affiche les chaînes qui doivent être fournies en tant que baseName paramètre afin que le gestionnaire de ressources puisse identifier correctement la ressource.

    using System;
using System.IO;
using System.Reflection;

public class Example0
{
   public static void Main()
   {
      if (Environment.GetCommandLineArgs().Length == 1) { 
         Console.WriteLine("No filename.");
         return;
      }
      
      string filename = Environment.GetCommandLineArgs()[1].Trim();
      // Check whether the file exists.
      if (! File.Exists(filename)) {
         Console.WriteLine("{0} does not exist.", filename);
         return;
      }   
      
      // Try to load the assembly.
      Assembly assem = Assembly.LoadFrom(filename);
      Console.WriteLine("File: {0}", filename);
         
      // Enumerate the resource files.
      string[] resNames = assem.GetManifestResourceNames();
      if (resNames.Length == 0)
         Console.WriteLine("   No resources found.");

      foreach (var resName in resNames)
         Console.WriteLine("   Resource: {0}", resName.Replace(".resources", ""));

      Console.WriteLine();
   }
}

    Imports System.IO
Imports System.Reflection
Imports System.Resources

Module Example
   Public Sub Main()
      If Environment.GetCommandLineArgs.Length = 1 Then 
         Console.WriteLine("No filename.")
         Exit Sub
      End If
      Dim filename As String = Environment.GetCommandLineArgs(1).Trim()
      ' Check whether the file exists.
      If Not File.Exists(filename) Then
         Console.WriteLine("{0} does not exist.", filename)
         Exit Sub
      End If   
      
      ' Try to load the assembly.
      Dim assem As Assembly = Assembly.LoadFrom(filename)
      Console.WriteLine("File: {0}", filename)
         
      ' Enumerate the resource files.
      Dim resNames() As String = assem.GetManifestResourceNames()
      If resNames.Length = 0 Then
         Console.WriteLine("   No resources found.")
      End If
      For Each resName In resNames
         Console.WriteLine("   Resource: {0}", resName.Replace(".resources", ""))
      Next
      Console.WriteLine()
   End Sub
End Module

Si vous modifiez explicitement la culture actuelle de votre application, n’oubliez pas que resource Manager récupère un jeu de ressources en fonction de la valeur de la CultureInfo.CurrentUICulture propriété, et non de la CultureInfo.CurrentCulture propriété. En règle générale, si vous modifiez une valeur, vous devez également modifier l’autre.

Contrôle de version de ressources

Étant donné que l’assembly principal qui contient les ressources par défaut d’une application est distinct des assemblys satellites de l’application, vous pouvez publier une nouvelle version de votre assembly principal sans redéployer les assemblys satellites. Vous utilisez l’attribut SatelliteContractVersionAttribute pour utiliser des assemblys satellites existants et demandez au gestionnaire de ressources de ne pas les redéployer avec une nouvelle version de votre assembly principal,

Pour plus d’informations sur la prise en charge du contrôle de version pour les assemblys satellites, consultez l’article Récupération des ressources.

<nœud de fichier de configuration satelliteassemblies>

Remarque

Cette section est spécifique aux applications .NET Framework.

Pour les exécutables déployés et exécutés à partir d’un site web (fichiers HREF .exe), l’objet ResourceManager peut rechercher des assemblys satellites sur le web, ce qui peut nuire aux performances de votre application. Pour éliminer le problème de performances, vous pouvez limiter cette détection aux assemblys satellites que vous avez déployés avec votre application. Pour ce faire, vous créez un <satelliteassemblies> nœud dans le fichier de configuration de votre application pour spécifier que vous avez déployé un ensemble spécifique de cultures pour votre application, et que l’objet ResourceManager ne doit pas essayer de rechercher une culture qui n’est pas répertoriée dans ce nœud.

Remarque

L’alternative préférée à la création d’un <satelliteassemblies> nœud consiste à utiliser la fonctionnalité manifeste de déploiement ClickOnce.

Dans le fichier de configuration de votre application, créez une section similaire à ce qui suit :

<?xml version ="1.0"?>
<configuration>
  <satelliteassemblies>
    <assembly name="MainAssemblyName, Version=versionNumber, Culture=neutral, PublicKeyToken=null|yourPublicKeyToken">
      <culture>cultureName1</culture>
      <culture>cultureName2</culture>
      <culture>cultureName3</culture>
    </assembly>
  </satelliteassemblies>
</configuration>

Modifiez ces informations de configuration comme suit :

  • Spécifiez un ou plusieurs <assembly> nœuds pour chaque assembly principal que vous déployez, où chaque nœud spécifie un nom d’assembly complet. Spécifiez le nom de votre assembly principal à la place de MainAssemblyName, puis spécifiez les valeurs d’attribut et Culture les VersionPublicKeyTokenvaleurs d’attribut qui correspondent à votre assembly principal.

    Pour l’attribut Version , spécifiez le numéro de version de votre assembly. Par exemple, la première version de votre assembly peut être le numéro de version 1.0.0.0.

    Pour l’attributPublicKeyToken, spécifiez le mot clé null si vous n’avez pas signé votre assembly avec un nom fort, ou spécifiez votre jeton de clé publique si vous avez signé votre assembly.

    Pour l’attributCulture, spécifiez l’mot clé neutral pour désigner l’assembly principal et provoquer la sonde de la ResourceManager classe uniquement pour les cultures répertoriées dans les <culture> nœuds.

    Pour plus d’informations sur les noms d’assemblys complets, consultez l’article Noms des assemblys. Pour plus d’informations sur les assemblys avec nom fort, consultez l’article Créer et utiliser des assemblys avec nom fort.

  • Spécifiez un ou plusieurs <culture> nœuds avec un nom de culture spécifique, tel que « fr-FR » ou un nom de culture neutre, tel que « fr ».

Si des ressources sont nécessaires pour un assembly non répertorié sous le <satelliteassemblies> nœud, les ResourceManager sondes de classe pour les cultures à l’aide de règles de détection standard.

Applications Windows 8.x

Important

Bien que la ResourceManager classe soit prise en charge dans les applications Windows 8.x, nous ne recommandons pas son utilisation. Utilisez cette classe uniquement lorsque vous développez des projets de bibliothèque de classes portables qui peuvent être utilisés avec des applications Windows 8.x. Pour récupérer des ressources à partir d’applications Windows 8.x, utilisez plutôt la classe Windows.ApplicationModel.Resources.ResourceLoader .

Pour les applications Windows 8.x, la ResourceManager classe récupère des ressources à partir de fichiers d’index de ressources de package (PRI). Un seul fichier PRI (fichier PRI du package d’application) contient les ressources pour la culture par défaut et toutes les cultures localisées. Vous utilisez l’utilitaire MakePRI pour créer un fichier PRI à partir d’un ou plusieurs fichiers de ressources au format de ressource XML (.resw). Pour les ressources incluses dans un projet Visual Studio, Visual Studio gère automatiquement le processus de création et d’empaquetage du fichier PRI. Vous pouvez ensuite utiliser la classe .NET ResourceManager pour accéder aux ressources de l’application ou de la bibliothèque.

Vous pouvez instancier un ResourceManager objet pour une application Windows 8.x de la même façon que pour une application de bureau.

Vous pouvez ensuite accéder aux ressources d’une culture particulière en transmettant le nom de la ressource à récupérer à la GetString(String) méthode. Par défaut, cette méthode retourne la ressource pour la culture déterminée par la culture actuelle de l’interface utilisateur du thread qui a effectué l’appel. Vous pouvez également récupérer les ressources d’une culture spécifique en passant le nom de la ressource et un CultureInfo objet qui représente la culture dont la ressource doit être récupérée dans la GetString(String, CultureInfo) méthode. Si la ressource pour la culture actuelle de l’interface utilisateur ou la culture spécifiée est introuvable, le gestionnaire de ressources utilise une liste de secours de langue d’interface utilisateur pour localiser une ressource appropriée.

Exemples

L’exemple suivant montre comment utiliser une culture explicite et la culture d’interface utilisateur actuelle implicite pour obtenir des ressources de chaîne à partir d’un assembly principal et d’un assembly satellite. Pour plus d’informations, consultez la section « Emplacements de répertoire pour les assemblys satellites non installés dans le Global Assembly Cache » de la rubrique Création d’assemblys satellites .

Pour exécuter cet exemple :

  1. Dans le répertoire de l’application, créez un fichier nommé rmc.txt qui contient les chaînes de ressources suivantes :

    day=Friday
year=2006
holiday="Cinco de Mayo"

  2. Utilisez le générateur de fichiers de ressources pour générer le fichier de ressources rmc.resources à partir du fichier d’entrée rmc.txt comme suit :

    resgen rmc.txt

  3. Créez un sous-répertoire du répertoire de l’application et nommez-le « es-MX ». Il s’agit du nom de culture de l’assembly satellite que vous allez créer dans les trois étapes suivantes.

  4. Créez un fichier nommé rmc.es-MX.txt dans le répertoire es-MX qui contient les chaînes de ressources suivantes :

    day=Viernes
year=2006
holiday="Cinco de Mayo"

  5. Utilisez le générateur de fichiers de ressources pour générer le fichier de ressources rmc.es-MX.resources à partir du fichier d’entrée rmc.es-MX.txt comme suit :

    resgen rmc.es-MX.txt

  6. Supposons que le nom de fichier de cet exemple est rmc.vb ou rmc.cs. Copiez le code source suivant dans un fichier. Ensuite, compilez-le et incorporez le fichier de ressources d’assembly principal, rmc.resources, dans l’assembly exécutable. Si vous utilisez le compilateur Visual Basic, la syntaxe est la suivante :

    vbc rmc.vb /resource:rmc.resources

    La syntaxe correspondante pour le compilateur C# est la suivante :

    csc /resource:rmc.resources rmc.cs

  7. Utilisez Assembly Linker pour créer un assembly satellite. Si le nom de base de l’application est rmc, le nom de l’assembly satellite doit être rmc.resources.dll. L’assembly satellite doit être créé dans le répertoire es-MX. Si es-MX est le répertoire actif, utilisez cette commande :

    al /embed:rmc.es-MX.resources /c:es-MX /out:rmc.resources.dll

  8. Exécutez rmc.exe pour obtenir et afficher les chaînes de ressources incorporées.

    using System;
using System.Globalization;
using System.Resources;

class Example2
{
    public static void Main()
    {
        string day;
        string year;
        string holiday;
        string celebrate = "{0} will occur on {1} in {2}.\n";

        // Create a resource manager.
        ResourceManager rm = new ResourceManager("rmc",
                                 typeof(Example).Assembly);

        Console.WriteLine("Obtain resources using the current UI culture.");

        // Get the resource strings for the day, year, and holiday
        // using the current UI culture.
        day = rm.GetString("day");
        year = rm.GetString("year");
        holiday = rm.GetString("holiday");
        Console.WriteLine(celebrate, holiday, day, year);

        // Obtain the es-MX culture.
        CultureInfo ci = new CultureInfo("es-MX");

        Console.WriteLine("Obtain resources using the es-MX culture.");

        // Get the resource strings for the day, year, and holiday
        // using the specified culture.
        day = rm.GetString("day", ci);
        year = rm.GetString("year", ci);
        holiday = rm.GetString("holiday", ci);
        // ---------------------------------------------------------------
        // Alternatively, comment the preceding 3 code statements and
        // uncomment the following 4 code statements:
        // ----------------------------------------------------------------
        // Set the current UI culture to "es-MX" (Spanish-Mexico).
        //    Thread.CurrentThread.CurrentUICulture = ci;

        // Get the resource strings for the day, year, and holiday
        // using the current UI culture. Use those strings to
        // display a message.
        //    day  = rm.GetString("day");
        //    year = rm.GetString("year");
        //    holiday = rm.GetString("holiday");
        // ---------------------------------------------------------------

        // Regardless of the alternative that you choose, display a message
        // using the retrieved resource strings.
        Console.WriteLine(celebrate, holiday, day, year);
    }
}
/*
This example displays the following output:

   Obtain resources using the current UI culture.
   "5th of May" will occur on Friday in 2006.

   Obtain resources using the es-MX culture.
   "Cinco de Mayo" will occur on Viernes in 2006.
*/

    Imports System.Resources
Imports System.Reflection
Imports System.Threading
Imports System.Globalization

Class Example4
    Public Shared Sub Main()
        Dim day As String
        Dim year As String
        Dim holiday As String
        Dim celebrate As String = "{0} will occur on {1} in {2}." & vbCrLf

        ' Create a resource manager. 
        Dim rm As New ResourceManager("rmc", GetType(Example4).Assembly)

        Console.WriteLine("Obtain resources using the current UI culture.")

        ' Get the resource strings for the day, year, and holiday 
        ' using the current UI culture. 
        day = rm.GetString("day")
        year = rm.GetString("year")
        holiday = rm.GetString("holiday")
        Console.WriteLine(celebrate, holiday, day, year)

        ' Obtain the es-MX culture.
        Dim ci As New CultureInfo("es-MX")

        Console.WriteLine("Obtain resources using the es-MX culture.")

        ' Get the resource strings for the day, year, and holiday 
        ' using the es-MX culture.  
        day = rm.GetString("day", ci)
        year = rm.GetString("year", ci)
        holiday = rm.GetString("holiday", ci)

        ' ---------------------------------------------------------------
        ' Alternatively, comment the preceding 3 code statements and 
        ' uncomment the following 4 code statements:
        ' ----------------------------------------------------------------
        ' Set the current UI culture to "es-MX" (Spanish-Mexico).
        '    Thread.CurrentThread.CurrentUICulture = ci
        ' Get the resource strings for the day, year, and holiday 
        ' using the current UI culture. 
        '    day  = rm.GetString("day")
        '    year = rm.GetString("year")
        '    holiday = rm.GetString("holiday")
        ' ---------------------------------------------------------------

        ' Regardless of the alternative that you choose, display a message 
        ' using the retrieved resource strings.
        Console.WriteLine(celebrate, holiday, day, year)
    End Sub
End Class
' This example displays the following output:
'Obtain resources using the current UI culture.
'"5th of May" will occur on Friday in 2006.
'
'Obtain resources using the es-MX culture.
'"Cinco de Mayo" will occur on Viernes in 2006.