System.Resources.ResourceReader 類別

發行項
03/23/2025

本文提供此 API 參考文件的補充備註。

這很重要

從這個類別使用不受信任的數據呼叫方法構成安全性風險。僅使用信任的數據，從這個類別呼叫方法。如需詳細資訊，請參閱驗證所有輸入。

ResourceReader 類別提供 IResourceReader 介面的標準實作。 ResourceReader 實例代表獨立 .resources 檔案或內嵌在元件中的 .resources 檔案。它用來列舉 .resources 檔案中的資源，並擷取其名稱/值組。它與 ResourceManager 類別不同，用來從內嵌在元件中的 .resources 檔案擷取指定的具名資源。 ResourceManager 類別可用來擷取事先知道其名稱的資源，而 ResourceReader 類別可用於擷取在編譯時期未知數目或精確名稱的資源。例如，應用程式可能會使用資源檔來儲存組態資訊，該資訊會組織成區段中的區段和專案，其中區段中的區段或項目數目事先未知。然後，資源可以泛型命名（例如 Section1、Section1Item1、Section1Item2等等），並使用 ResourceReader 物件來擷取。

這很重要

此類型會實作 IDisposable 介面。當您完成使用這個物品後，應直接或間接地處理它。若要直接處置類型，請在 try/catch 區塊中呼叫其 Dispose 方法。若要間接處置它，請使用語言建構，例如 using （C#）或 Using （在 Visual Basic 中）。如需詳細資訊，請參閱介面檔中的<使用實作 IDisposable 的物件>一節。

實例化 ResourceReader 物件

.resources 檔案是從文本檔或 XML .resx 檔案編譯的二進位檔，Resgen.exe （資源檔案產生器）。 ResourceReader 物件可以代表獨立 .resources 檔案或已內嵌在元件中的 .resources 檔案。

若要具現化從獨立 .resources 檔案讀取的 ResourceReader 物件，請使用 ResourceReader 類別建構函式搭配輸入數據流或包含 .resources 檔名的字串。下列範例說明這兩種方法。第一個將 ResourceReader 物件實例化，這個物件是透過其檔名來表示名為 Resources1.resources 的 .resources 檔案。第二個會使用從檔案建立的數據流，具現化 ResourceReader 物件，代表名為 Resources2.resources 的 .resources 檔案。

// 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)

若要建立代表內嵌 .resources 檔案的 ResourceReader 物件，請從內嵌 .resources 檔案的元件具現化 Assembly 物件。其 Assembly.GetManifestResourceStream 方法會傳回可傳遞至 ResourceReader(Stream) 建構函式的 Stream 物件。下列範例會具現化代表內嵌 .resources 檔案的 ResourceReader 物件。

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)

列舉 ResourceReader 對象的資源

若要列舉 .resources 檔案中的資源，您可以呼叫傳回 System.Collections.IDictionaryEnumerator 物件的 GetEnumerator 方法。您可以呼叫 IDictionaryEnumerator.MoveNext 方法，將資源從一個資源移至下一個資源。方法會在列舉 .resources 檔案中的所有資源時，傳回 false。

備註

雖然 ResourceReader 類別會實作 IEnumerable 介面和 IEnumerable.GetEnumerator 方法，但 ResourceReader.GetEnumerator 方法不會提供 IEnumerable.GetEnumerator 實作。相反地，ResourceReader.GetEnumerator 方法會傳回 IDictionaryEnumerator 介面物件，以提供每個資源的名稱/值組存取權。

您可以透過兩種方式擷取集合中的個別資源：

您可以逐一查看 System.Collections.IDictionaryEnumerator 集合中的每個資源，並使用 System.Collections.IDictionaryEnumerator 屬性來擷取資源名稱和值。當所有資源都屬於相同類型，或您知道每個資源的數據類型時，建議您使用這項技術。
當您遍歷 System.Collections.IDictionaryEnumerator 集合並呼叫 GetResourceData 方法來擷取資源的資料時，您可以取得每個資源的名稱。當您不知道每個資源的數據類型，或先前的方法是否擲回例外狀況時，建議您使用此方法。

使用 IDictionaryEnumerator 屬性擷取資源

列舉 .resources 檔案中資源的第一個方法牽涉到直接擷取每個資源的名稱/值組。呼叫 IDictionaryEnumerator.MoveNext 方法以移至集合中的每個資源之後，您可以從 IDictionaryEnumerator.Key 屬性擷取資源名稱，並從 IDictionaryEnumerator.Value 屬性擷取資源數據。

下列範例示範如何使用 IDictionaryEnumerator.Key 和 IDictionaryEnumerator.Value 屬性，擷取 .resources 檔案中每個資源的名稱和值。若要執行此範例，請建立名為 ApplicationResources.txt 的下列文本檔，以定義字串資源。

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:"

接著，您可以使用下列命令，將文字資源文件轉換成名為 ApplicationResources.resources 的二進位檔：

resgen ApplicationResources.txt

下列範例接著會使用 ResourceReader 類別來列舉獨立二進位 .resources 檔案中的每個資源，並顯示其索引鍵名稱和對應的值。

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($"   {dict.Key}: '{dict.Value}' (Type {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)

嘗試從 IDictionaryEnumerator.Value 屬性擷取資源數據，可能會擲回下列例外狀況：

如果數據不是預期的格式，則為 FormatException。
如果找不到包含數據所屬類型的元件，則為 FileNotFoundException。
如果無法找到數據所屬的類型，則為 TypeLoadException。

一般來說，這些例外狀況會在以下情況下發生：如果 .resources 檔案已被手動修改，如果定義型別的元件不是應用程式的一部分或已被不小心刪除，或該元件是先於型別的舊版。如果引發其中一個例外狀況，您可以列舉每個資源並呼叫 GetResourceData 方法來擷取資源，如以下章節所示。此方法提供您 IDictionaryEnumerator.Value 屬性嘗試傳回之數據類型的一些相關信息。

使用 GetResourceData 依名稱擷取資源

列舉 .resources 檔案中資源的第二種方法也牽涉到藉由呼叫 IDictionaryEnumerator.MoveNext 方法瀏覽檔案中的資源。針對每個資源，您會從 IDictionaryEnumerator.Key 屬性擷取資源的名稱，然後傳遞至 GetResourceData(String, String, Byte[]) 方法來擷取資源的數據。這會以 resourceData 引數中的位元組陣列回傳。

這種方法比從 IDictionaryEnumerator.Key 和 IDictionaryEnumerator.Value 屬性擷取資源名稱和值更尷尬，因為它會傳回形成資源值的實際位元組。不過，如果嘗試擷取資源擲回例外狀況，GetResourceData 方法可藉由提供資源數據類型的相關信息來協助識別例外狀況的來源。如需指出資源資料類型之字串的詳細資訊，請參閱 GetResourceData。

下列範例說明如何使用此方法來擷取資源，以及處理拋出的任何例外狀況。它會以程序設計方式建立二進位 .resources 檔案，其中包含四個字串、一個布爾值、一個整數和一個位圖。若要執行此範例，請執行下列動作：

編譯並執行下列原始程式碼，這會建立名為 ContactResources.resources 的 .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();
        }
    }
}

原始碼檔案名為 CreateResources.cs。您可以使用下列命令，在 C# 中編譯它：

csc CreateResources.cs /r:library.dll

編譯並執行下列程序代碼，以列舉 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: {dict.Key}");
            try
            {
                Console.WriteLine($"   Value: {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: {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: {binData}");
                break;
            case "ResourceTypeCode.Int32":
                Console.WriteLine($"   Recreated Value: {BitConverter.ToInt32(data, 0)}");
                break;
            case "ResourceTypeCode.Boolean":
                Console.WriteLine($"   Recreated Value: {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: {value1}");
                break;
            default:
                break;
        }
        Console.WriteLine();
    }
}

修改原始程式碼之後（例如，藉由在 try 區塊結尾刻意擲回 FormatException），您可以執行此範例來查看呼叫 GetResourceData 如何讓您擷取或重新建立某些資源資訊。

共用方式為

System.Resources.ResourceReader 類別

實例化 ResourceReader 物件

列舉 ResourceReader 對象的資源

使用 IDictionaryEnumerator 屬性擷取資源

使用 GetResourceData 依名稱擷取資源

其他資源