System.Resources.ResourceReader classe

Artigo
01/11/2024

Este artigo fornece observações complementares à documentação de referência para essa API.

Importante

Chamar métodos desta classe quando você tiver dados não confiáveis é um risco à segurança. Chame os métodos dessa classe somente quando você tiver dados confiáveis. Para obter mais informações, consulte Validar todas as entradas.

A ResourceReader classe fornece uma implementação padrão da IResourceReader interface. Uma ResourceReader instância representa um arquivo .resources autônomo ou um arquivo .resources incorporado em um assembly. Ele é usado para enumerar os recursos em um arquivo .resources e recuperar seus pares nome/valor. Ele difere da ResourceManager classe, que é usada para recuperar recursos nomeados especificados de um arquivo .resources que é incorporado em um assembly. A ResourceManager classe é usada para recuperar recursos cujos nomes são conhecidos antecipadamente, enquanto a ResourceReader classe é útil para recuperar recursos cujo número ou nomes precisos não são conhecidos em tempo de compilação. Por exemplo, um aplicativo pode usar um arquivo de recursos para armazenar informações de configuração organizadas em seções e itens em uma seção, onde o número de seções ou itens em uma seção não é conhecido com antecedência. Os recursos podem então ser nomeados genericamente (como Section1, Section1Item1, Section1Item2e assim por diante) e recuperados usando um ResourceReader objeto.

Importante

Esse tipo implementa a interface IDisposable. Quando você terminar de usar o tipo, deverá descartá-lo direta ou indiretamente. Para descartar o tipo diretamente, chame o método Dispose dele em um bloco try/catch. Para descartá-lo indiretamente, use um constructo de linguagem como using ( em C#) ou Using (em Visual Basic). Para obter mais informações, consulte a seção "Usando um objeto que implementa IDisposable" na documentação da IDisposable interface.

Instanciar um objeto ResourceReader

Um arquivo .resources é um arquivo binário que foi compilado de um arquivo de texto ou de um arquivo .resx XML pelo Resgen.exe (Resource File Generator). Um ResourceReader objeto pode representar um arquivo .resources autônomo ou um arquivo .resources que foi incorporado em um assembly.

Para instanciar um objeto que lê de um arquivo .resources autônomo, use o construtor de classe com um ResourceReader fluxo de entrada ou uma cadeia de caracteres que contém o ResourceReader nome do arquivo .resources. O exemplo a seguir ilustra ambas as abordagens. O primeiro instancia um objeto que representa um ResourceReader arquivo .resources nomeado Resources1.resources usando seu nome de arquivo. O segundo instancia um objeto que representa um arquivo .resources nomeado Resources2.resources usando um ResourceReader fluxo criado a partir do arquivo.

// Instantiate a standalone .resources file from its filename.
var rr1 = new System.Resources.ResourceReader("Resources1.resources");

// Instantiate a standalone .resources file from a stream.
var fs = new System.IO.FileStream(@".\Resources2.resources",
                                  System.IO.FileMode.Open);
var rr2 = new System.Resources.ResourceReader(fs);

' Instantiate a standalone .resources file from its filename.
Dim rr1 As New System.Resources.ResourceReader("Resources1.resources")

' Instantiate a standalone .resources file from a stream.
Dim fs As New System.IO.FileStream(".\Resources2.resources",
                                   System.IO.FileMode.Open)
Dim rr2 As New System.Resources.ResourceReader(fs)

Para criar um objeto que representa um arquivo .resources incorporado, instancie um ResourceReader Assembly objeto do assembly no qual o arquivo .resources está incorporado. Seu Assembly.GetManifestResourceStream método retorna um Stream objeto que pode ser passado para o ResourceReader(Stream) construtor. O exemplo a seguir instancia um objeto que representa um ResourceReader arquivo .resources incorporado.

System.Reflection.Assembly assem =
             System.Reflection.Assembly.LoadFrom(@".\MyLibrary.dll");
System.IO.Stream fs =
             assem.GetManifestResourceStream("MyCompany.LibraryResources.resources");
var rr = new System.Resources.ResourceReader(fs);

Dim assem As System.Reflection.Assembly = 
             System.Reflection.Assembly.LoadFrom(".\MyLibrary.dll") 
Dim fs As System.IO.Stream = 
             assem.GetManifestResourceStream("MyCompany.LibraryResources.resources")
Dim rr As New System.Resources.ResourceReader(fs)

Enumerar os recursos de um objeto ResourceReader

Para enumerar os recursos em um arquivo .resources, você chama o GetEnumerator método, que retorna um System.Collections.IDictionaryEnumerator objeto. Você chama o método para mover de um recurso para o IDictionaryEnumerator.MoveNext próximo. O método retorna false quando todos os recursos no arquivo .resources foram enumerados.

Observação

Embora a classe implementa a interface e o método, o ResourceReader.GetEnumerator IEnumerable.GetEnumerator método não fornece a ResourceReader IEnumerable IEnumerable.GetEnumerator implementação. Em vez disso, o ResourceReader.GetEnumerator método retorna um objeto de IDictionaryEnumerator interface que fornece acesso ao par nome/valor de cada recurso.

Você pode recuperar os recursos individuais na coleção de duas maneiras:

Você pode iterar cada recurso na System.Collections.IDictionaryEnumerator coleção e usar System.Collections.IDictionaryEnumerator propriedades para recuperar o nome e o valor do recurso. Recomendamos essa técnica quando todos os recursos forem do mesmo tipo ou quando você souber o tipo de dados de cada recurso.
Você pode recuperar o nome de cada recurso ao iterar a System.Collections.IDictionaryEnumerator coleção e chamar o GetResourceData método para recuperar os dados do recurso. Recomendamos essa abordagem quando você não souber o tipo de dados de cada recurso ou se a abordagem anterior lançar exceções.

Recuperar recursos usando IDictionaryEnumerator propriedades

O primeiro método de enumerar os recursos em um arquivo .resources envolve recuperar diretamente o par nome/valor de cada recurso. Depois de chamar o IDictionaryEnumerator.MoveNext método para mover para cada recurso na coleção, você pode recuperar o nome do recurso da IDictionaryEnumerator.Key propriedade e os dados do recurso da IDictionaryEnumerator.Value propriedade.

O exemplo a seguir mostra como recuperar o nome e o valor de cada recurso em um arquivo .resources usando as IDictionaryEnumerator.Key propriedades e IDictionaryEnumerator.Value . Para executar o exemplo, crie o seguinte arquivo de texto chamado ApplicationResources.txt para definir recursos de cadeia de caracteres.

Title="Contact Information"
Label1="First Name:"
Label2="Middle Name:"
Label3="Last Name:"
Label4="SSN:"
Label5="Street Address:"
Label6="City:"
Label7="State:"
Label8="Zip Code:"
Label9="Home Phone:"
Label10="Business Phone:"
Label11="Mobile Phone:"
Label12="Other Phone:"
Label13="Fax:"
Label14="Email Address:"
Label15="Alternate Email Address:"

Em seguida, você pode converter o arquivo de recurso de texto em um arquivo binário chamado ApplicationResources.resources usando o seguinte comando:

resgen ApplicationResources.txt

O exemplo a seguir usa a ResourceReader classe para enumerar cada recurso no arquivo .resources binário autônomo e exibir seu nome de chave e valor correspondente.

using System;
using System.Collections;
using System.Resources;

public class Example1
{
   public static void Run()
   {
      Console.WriteLine("Resources in ApplicationResources.resources:");
      ResourceReader res = new ResourceReader(@".\ApplicationResources.resources");
      IDictionaryEnumerator dict = res.GetEnumerator();
      while (dict.MoveNext())
         Console.WriteLine("   {0}: '{1}' (Type {2})", 
                           dict.Key, dict.Value, dict.Value.GetType().Name);
      res.Close();
   }
}
// The example displays the following output:
//       Resources in ApplicationResources.resources:
//          Label3: '"Last Name:"' (Type String)
//          Label2: '"Middle Name:"' (Type String)
//          Label1: '"First Name:"' (Type String)
//          Label7: '"State:"' (Type String)
//          Label6: '"City:"' (Type String)
//          Label5: '"Street Address:"' (Type String)
//          Label4: '"SSN:"' (Type String)
//          Label9: '"Home Phone:"' (Type String)
//          Label8: '"Zip Code:"' (Type String)
//          Title: '"Contact Information"' (Type String)
//          Label12: '"Other Phone:"' (Type String)
//          Label13: '"Fax:"' (Type String)
//          Label10: '"Business Phone:"' (Type String)
//          Label11: '"Mobile Phone:"' (Type String)
//          Label14: '"Email Address:"' (Type String)
//          Label15: '"Alternate Email Address:"' (Type String)

Imports System.Collections
Imports System.Resources

Module Example2
    Public Sub Main()
        Console.WriteLine("Resources in ApplicationResources.resources:")
        Dim res As New ResourceReader(".\ApplicationResources.resources")
        Dim dict As IDictionaryEnumerator = res.GetEnumerator()
        Do While dict.MoveNext()
            Console.WriteLine("   {0}: '{1}' (Type {2})", dict.Key, dict.Value, dict.Value.GetType().Name)
        Loop
        res.Close()
    End Sub
End Module
' The example displays output like the following:
'       Resources in ApplicationResources.resources:
'          Label3: '"Last Name:"' (Type String)
'          Label2: '"Middle Name:"' (Type String)
'          Label1: '"First Name:"' (Type String)
'          Label7: '"State:"' (Type String)
'          Label6: '"City:"' (Type String)
'          Label5: '"Street Address:"' (Type String)
'          Label4: '"SSN:"' (Type String)
'          Label9: '"Home Phone:"' (Type String)
'          Label8: '"Zip Code:"' (Type String)
'          Title: '"Contact Information"' (Type String)
'          Label12: '"Other Phone:"' (Type String)
'          Label13: '"Fax:"' (Type String)
'          Label10: '"Business Phone:"' (Type String)
'          Label11: '"Mobile Phone:"' (Type String)
'          Label14: '"Email Address:"' (Type String)
'          Label15: '"Alternate Email Address:"' (Type String)

A tentativa de recuperar dados de recurso da IDictionaryEnumerator.Value propriedade pode lançar as seguintes exceções:

A FormatException se os dados não estiverem no formato esperado.
A FileNotFoundException se o assembly que contém o tipo ao qual os dados pertencem não puder ser encontrado.
R TypeLoadException se o tipo ao qual os dados pertencem não puder ser encontrado.

Normalmente, essas exceções são lançadas se o arquivo .resources tiver sido modificado manualmente, se o assembly no qual um tipo é definido não tiver sido incluído em um aplicativo ou tiver sido excluído inadvertidamente ou se o assembly for uma versão mais antiga anterior a um tipo. Se uma dessas exceções for lançada, você poderá recuperar recursos enumerando cada recurso e chamando o método, como mostra a seção a GetResourceData seguir. Essa abordagem fornece algumas informações sobre o tipo de dados que a IDictionaryEnumerator.Value propriedade tentou retornar.

Recuperar recursos por nome com GetResourceData

A segunda abordagem para enumerar recursos em um arquivo .resources também envolve navegar pelos recursos no arquivo chamando o IDictionaryEnumerator.MoveNext método. Para cada recurso, você recupera o nome do recurso da propriedade, que é passado para o GetResourceData(String, String, Byte[]) método para recuperar os dados do IDictionaryEnumerator.Key recurso. Isso é retornado como uma matriz de bytes no resourceData argumento.

Essa abordagem é mais incômoda do que recuperar o nome e o valor do recurso das propriedades e IDictionaryEnumerator.Value , porque retorna os bytes reais que formam o valor do IDictionaryEnumerator.Key recurso. No entanto, se a tentativa de recuperar o recurso lançar uma exceção, o método pode ajudar a identificar a origem da exceção fornecendo informações sobre o GetResourceData tipo de dados do recurso. Para obter mais informações sobre a cadeia de caracteres que indica o tipo de dados do recurso, consulte GetResourceData.

O exemplo a seguir ilustra como usar essa abordagem para recuperar recursos e manipular quaisquer exceções que são lançadas. Ele cria programaticamente um arquivo .resources binário que contém quatro cadeias de caracteres, um booleano, um inteiro e um bitmap. Para executar o exemplo, faça o seguinte:

Compile e execute o código-fonte a seguir, que cria um arquivo .resources chamado ContactResources.resources.

using System.Drawing;
using System.Drawing.Imaging;
using System.IO;
using System.Resources;
using System.Runtime.Versioning;

public class Example5
{
    [SupportedOSPlatform("windows")]
    public static void Run()
    {
        // Bitmap as stream.
        MemoryStream bitmapStream = new MemoryStream();
        Bitmap bmp = new Bitmap(@".\ContactsIcon.jpg");
        bmp.Save(bitmapStream, ImageFormat.Jpeg);

        // Define resources to be written.
        using (ResourceWriter rw = new ResourceWriter(@".\ContactResources.resources"))
        {
            rw.AddResource("Title", "Contact List");
            rw.AddResource("NColumns", 5);
            rw.AddResource("Icon", bitmapStream);
            rw.AddResource("Header1", "Name");
            rw.AddResource("Header2", "City");
            rw.AddResource("Header3", "State");
            rw.AddResource("ClientVersion", true);
            rw.Generate();
        }
    }
}

O arquivo de código-fonte é chamado CreateResources.cs. Você pode compilá-lo em C# usando o seguinte comando:

csc CreateResources.cs /r:library.dll

Compile e execute o código a seguir para enumerar os recursos no arquivo ContactResources.resources.

using System;
using System.Collections;
using System.Drawing;
using System.IO;
using System.Resources;
using System.Runtime.Versioning;

public class Example6
{
    [SupportedOSPlatform("windows")]
    public static void Run()
    {
        ResourceReader rdr = new ResourceReader(@".\ContactResources.resources");
        IDictionaryEnumerator dict = rdr.GetEnumerator();
        while (dict.MoveNext())
        {
            Console.WriteLine("Resource Name: {0}", dict.Key);
            try
            {
                Console.WriteLine("   Value: {0}", dict.Value);
            }
            catch (FileNotFoundException)
            {
                Console.WriteLine("   Exception: A file cannot be found.");
                DisplayResourceInfo(rdr, (string)dict.Key, false);
            }
            catch (FormatException)
            {
                Console.WriteLine("   Exception: Corrupted data.");
                DisplayResourceInfo(rdr, (string)dict.Key, true);
            }
            catch (TypeLoadException)
            {
                Console.WriteLine("   Exception: Cannot load the data type.");
                DisplayResourceInfo(rdr, (string)dict.Key, false);
            }
        }
    }

    [SupportedOSPlatform("windows")]
    private static void DisplayResourceInfo(ResourceReader rr,
                                    string key, bool loaded)
    {
        string dataType = null;
        byte[] data = null;
        rr.GetResourceData(key, out dataType, out data);

        // Display the data type.
        Console.WriteLine("   Data Type: {0}", dataType);
        // Display the bytes that form the available data.      
        Console.Write("   Data: ");
        int lines = 0;
        foreach (var dataItem in data)
        {
            lines++;
            Console.Write("{0:X2} ", dataItem);
            if (lines % 25 == 0)
                Console.Write("\n         ");
        }
        Console.WriteLine();
        // Try to recreate current state of data.
        // Do: Bitmap, DateTimeTZI
        switch (dataType)
        {
            // Handle internally serialized string data (ResourceTypeCode members).
            case "ResourceTypeCode.String":
                BinaryReader reader = new BinaryReader(new MemoryStream(data));
                string binData = reader.ReadString();
                Console.WriteLine("   Recreated Value: {0}", binData);
                break;
            case "ResourceTypeCode.Int32":
                Console.WriteLine("   Recreated Value: {0}",
                                  BitConverter.ToInt32(data, 0));
                break;
            case "ResourceTypeCode.Boolean":
                Console.WriteLine("   Recreated Value: {0}",
                                  BitConverter.ToBoolean(data, 0));
                break;
            // .jpeg image stored as a stream.
            case "ResourceTypeCode.Stream":
                const int OFFSET = 4;
                int size = BitConverter.ToInt32(data, 0);
                Bitmap value1 = new Bitmap(new MemoryStream(data, OFFSET, size));
                Console.WriteLine("   Recreated Value: {0}", value1);
                break;
            default:
                break;
        }
        Console.WriteLine();
    }
}

Depois de modificar o código-fonte (por exemplo, lançando deliberadamente um FormatException no final do bloco), você pode executar o exemplo para ver como as chamadas permitem GetResourceData que você recupere ou recrie algumas informações de try recurso.

System.Resources.ResourceReader classe

Instanciar um objeto ResourceReader

Enumerar os recursos de um objeto ResourceReader

Recuperar recursos usando IDictionaryEnumerator propriedades

Recuperar recursos por nome com GetResourceData

Comentários

Recursos adicionais