ResourceManager 類別

定義

表示在執行階段提供特定文化特性資源存取權限的資源管理員。

public ref class ResourceManager
public class ResourceManager
[System.Serializable]
public class ResourceManager
[System.Serializable]
[System.Runtime.InteropServices.ComVisible(true)]
public class ResourceManager
type ResourceManager = class
[<System.Serializable>]
type ResourceManager = class
[<System.Serializable>]
[<System.Runtime.InteropServices.ComVisible(true)>]
type ResourceManager = class
Public Class ResourceManager
繼承
ResourceManager
衍生
屬性

範例

下列範例示範如何使用明確文化特性和隱含目前的 UI 文化特性,從主要元件和附屬元件取得字串資源。 如需詳細資訊,請參閱 建立附屬元件 主題中的一節。

若要執行此範例:

  1. 在應用程式目錄中,建立名為 rmc.txt 的檔案,其中包含下列資源字串:

    day=Friday
    year=2006
    holiday="Cinco de Mayo"
    
  2. 使用 資源檔產生器 ,從rmc.txt輸入檔產生 rmc.resources 資源檔,如下所示:

    resgen rmc.txt
    
  3. 建立應用程式目錄的子目錄,並將其命名為 「es-MX」。 這是您將在後續三個步驟中建立的附屬元件文化特性名稱。

  4. 在包含下列資源字串的 es-MX 目錄中建立名為 rmc.es-MX.txt 的檔案:

    day=Viernes
    year=2006
    holiday="Cinco de Mayo"
    
  5. 使用 資源檔產生器 ,從rmc.es-MX.txt輸入檔產生 rmc.es-MX.resources 資源檔,如下所示:

    resgen rmc.es-MX.txt
    
  6. 假設此範例的檔案名是 rmc.vb 或 rmc.cs。 將下列原始程式碼複製到檔案中。 然後編譯它,並在可執行元件中內嵌主要元件資源檔 rmc.resources。 如果您使用Visual Basic編譯器,語法為:

    vbc rmc.vb /resource:rmc.resources
    

    C# 編譯器的對應語法為:

    csc /resource:rmc.resources rmc.cs
    
  7. 使用 元件連結器 來建立附屬元件。 如果應用程式的基底名稱是 rmc,則必須rmc.resources.dll附屬元件名稱。 附屬元件應該在 es-MX 目錄中建立。 如果 es-MX 是目前的目錄,請使用此命令:

    al /embed:rmc.es-MX.resources /c:es-MX /out:rmc.resources.dll
    
  8. 運行rmc.exe以獲取並顯示嵌入的資源字符串。

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

class Example
{
    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 Example
    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(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.
        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.

備註

重要

使用不信任的資料呼叫此類別的方法,會造成安全性上的風險。 呼叫此類別的方法時,請一律使用信任的資料。 如需詳細資訊,請參閱 驗證所有輸入

類別 ResourceManager 會從內嵌在元件或獨立 .resources 檔案中的二進位 .resources 檔案擷取資源。 如果應用程式已當地語系化,且當地語系化的資源已部署在 附屬元件中,則會查閱特定文化特性的資源、在當地語系化資源不存在時提供資源後援,並支援資源序列化。

如需在傳統型應用程式和 Windows 8.x 應用程式中建立和管理資源的詳細資訊,請參閱下列各節:

傳統型應用程式

針對傳統型應用程式,類別 ResourceManager 會從二進位資源 (.resources 擷取資源) 檔案。 一般而言,語言編譯器或 元件連結器 (AL.exe) 將這些資源檔內嵌在元件中。 您也可以呼叫 方法, CreateFileBasedResourceManager 使用 ResourceManager 物件直接從未內嵌在元件中的 .resources 檔案擷取資源。

警告

在 ASP.NET 應用程式中使用獨立 .resources 檔案會中斷 XCOPY 部署,因為資源會維持鎖定狀態,直到 方法明確釋放 ReleaseAllResources 為止。 如果您想要使用 ASP.NET 應用程式部署資源,您應該將 .resources 檔案編譯成附屬元件。

在資源型應用程式中,一個 .resources 檔案包含預設文化特性的資源,如果找不到特定文化特性的資源,則會使用其資源。 例如,如果應用程式的預設文化特性是英文 (en) ,則每當找不到特定文化特性的當地語系化資源時,就會使用英文語言資源,例如英文 (美國) (en-US) 或法文 (法國) (fr-FR) 。 一般而言,預設文化特性的資源會內嵌在主要應用程式元件中,而其他當地語系化文化特性的資源則內嵌在附屬元件中。 附屬元件只包含資源。 它們有相同的根檔案名稱,以及主要組件的延伸模組 .resources.dll。 對於元件未在全域組件快取中註冊的應用程式,附屬元件會儲存在名稱對應至元件文化特性的應用程式子目錄中。

建立資源

當您開發以資源為基礎的應用程式時,會將資源資訊儲存在具有 .resx 副檔名) .txt或 .restext 副檔名) 或 XML (檔案 (文字檔中。 然後使用 資源檔產生器 (Resgen.exe 編譯 文字或 XML 檔案,) 來建立二進位 .resources 檔案。 接著,您可以使用 C# 和 Visual Basic 編譯器之類的 /resources 編譯器選項,將產生的 .resources 檔案內嵌在可執行檔或程式庫中,或者您可以使用元件連結器 (AI.exe) 將它內嵌在附屬元件中。 如果您在Visual Studio專案中包含 .resx 檔案,Visual Studio會在建置過程中自動處理預設和當地語系化資源的編譯和內嵌。

在理想情況下,您應該為應用程式支援的每個語言建立資源,或至少為每個語言有意義的子集建立資源。 二進位 .resources 檔案名遵循命名慣例 basenamecultureName.resources,其中 basename 是應用程式的名稱或類別的名稱,視您想要的詳細資料層級而定。 屬性 CultureInfo.Name 是用來判斷 cultureName。 應用程式預設文化特性的資源應該命名為 basename.resources

例如,假設元件在具有基底名稱 MyResources 的資源檔中有數個資源。 這些資源檔的名稱應為日本 (日文) 文化特性、德文文化特性的 MyResources.de.resources、簡體中文文化特性的 MyResources.zh-CHS.resources 等名稱,以及法文 (比利時) 文化特性的 MyResources.fr-BE.resources。 預設資源檔應命名為 MyResources.resources。 特定文化特性的資源檔通常會封裝在每個文化特性的附屬元件中。 預設資源檔應該內嵌在應用程式的主要元件中。

請注意, 元件連結器 允許將資源標示為私人,但您應該一律將它們標示為公用,以便其他元件存取它們。 (因為附屬元件不包含任何程式碼,所以透過任何機制,您的應用程式無法使用標示為私人的資源。)

如需建立、封裝和部署資源的詳細資訊,請參閱 建立資源檔建立附屬元件封裝和部署資源一文。

具現化 ResourceManager 物件

您可以呼叫其中一個 ResourceManager 類別建構函式多載,以具現化物件,從內嵌的 .resources 檔案擷取資源。 這會緊密結合 ResourceManager 物件與特定 .resources 檔案,以及附屬元件中任何相關聯的當地語系化 .resources 檔案。

兩個最常呼叫的建構函式包括:

  • ResourceManager(String, Assembly) 根據您提供的兩項資訊來查閱資源:.resources 檔案的基底名稱,以及預設 .resources 檔案所在的元件。 基底名稱包含 .resources 檔案的命名空間和根名稱,不含其文化特性或副檔名。 請注意,從命令列編譯的 .resources 檔案通常不包含命名空間名稱,而在 Visual Studio 環境中建立的 .resources 檔案則不會包含命名空間名稱。 例如,如果資源檔名為 MyCompany.StringResources.resources,而且 ResourceManager 建構函式是從名為 Example.Main 的靜態方法呼叫,則下列程式碼會具現化 ResourceManager 可從 .resources 檔案擷取資源的 物件:

    ResourceManager rm = new ResourceManager("MyCompany.StringResources",
                                             typeof(Example).Assembly);
    
    Dim rm As New ResourceManager("MyCompany.StringResources",
                                  GetType(Example).Assembly)
    
  • ResourceManager(Type) 根據類型物件的資訊,查閱附屬元件中的資源。 類型的完整名稱會對應至 .resources 檔案的基底名稱,而沒有副檔名。 在使用 Visual Studio 資源設計工具所建立的桌面應用程式中,Visual Studio建立包裝函式類別,其完整名稱與 .resources 檔案的根名稱相同。 例如,如果資源檔名為 MyCompany.StringResources.resources,而且有名為 MyCompany.StringResources 的包裝函式類別,下列程式碼會具現化 ResourceManager 可從 .resources 檔案擷取資源的 物件:

    ResourceManager rm = new ResourceManager(typeof(MyCompany.StringResources));
    
    Dim rm As New ResourceManager(GetType(MyCompany.StringResources))
    

如果找不到適當的資源,建構函式呼叫會建立有效的 ResourceManager 物件。 不過,嘗試擷取資源會擲回例外狀況 MissingManifestResourceException 。 如需處理例外狀況的相關資訊,請參閱本文稍後 的處理 MissingManifestResourceException 和 MissingSatelliteAssembly 例外狀況 一節。

下列範例示範如何具現化 ResourceManager 物件。 它包含名為 ShowTime.exe 之可執行檔的原始程式碼。 它也包含下列名為 Strings.txt 的文字檔,其中包含單一字串資源: TimeHeader

TimeHeader=The current time is

您可以使用批次檔來產生資源檔,並將其內嵌至可執行檔。 以下是使用 C# 編譯器產生可執行檔的批次檔:

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

針對Visual Basic編譯器,您可以使用下列批次檔:

resgen strings.txt
vbc ShowTime.vb /resource:strings.resources
using System;
using System.Resources;

public class Example
{
   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 Example
   Public Sub Main()
      Dim rm As New ResourceManager("Strings", GetType(Example).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

ResourceManager 和 Culture-Specific Resources

當地語系化的應用程式需要部署資源,如 封裝和部署資源一文所述。 如果元件已正確設定,資源管理員會根據目前線程的 Thread.CurrentUICulture 屬性來決定要擷取的資源。 (該屬性也會傳回目前線程的 UI 文化特性。) 例如,如果應用程式是以主要元件中的預設英文語言資源編譯,以及兩個附屬元件中的法文和俄文語言資源,而且 Thread.CurrentUICulture 屬性設定為 fr-FR,資源管理員就會擷取法文資源。

您可以明確或隱含地設定 CurrentUICulture 屬性。 您設定的方式會決定物件如何 ResourceManager 根據文化特性擷取資源:

  • 如果您明確將 Thread.CurrentUICulture 屬性設定為特定文化特性,則不論使用者的瀏覽器或作業系統語言為何,資源管理員一律會擷取該文化特性的資源。 請考慮使用預設英文資源編譯的應用程式,以及三個附屬元件,其中包含英文 (美國) 、法文 (法國) ,以及俄文 (俄羅斯) 。 CurrentUICulture如果屬性設定為 fr-FR, ResourceManager 物件一律會擷取法文 (法國) 資源,即使使用者的作業系統語言不是法文也一樣。 在明確設定 屬性之前,請確定這是所需的行為。

    在 ASP.NET 應用程式中,您必須明確設定 Thread.CurrentUICulture 屬性,因為伺服器上的設定不太可能符合傳入的用戶端要求。 ASP.NET 應用程式可以將 屬性明確設定 Thread.CurrentUICulture 為使用者的瀏覽器接受語言。

    明確設定 Thread.CurrentUICulture 屬性會定義該執行緒目前的 UI 文化特性。 它不會影響應用程式中任何其他執行緒的目前 UI 文化特性。

  • 您可以將代表該文化特性的物件指派 CultureInfo 給靜態 CultureInfo.DefaultThreadCurrentUICulture 屬性,以設定應用程式域中所有線程的 UI 文化特性。

  • 如果您未明確設定目前的 UI 文化特性,而且未定義目前應用程式域的預設文化特性,屬性 CultureInfo.CurrentUICulture 會由 Windows GetUserDefaultUILanguage 函式隱含設定。 此函式是由多語系消費者介面 (MUI) 提供,可讓使用者設定預設語言。 如果使用者未設定 UI 語言,則會預設為系統安裝的語言,這是作業系統資源的語言。

下列簡單的 「Hello world」 範例會明確設定目前的 UI 文化特性。 其中包含三種文化特性的資源:英文 (美國) 或 en-US、法文 (法國) 或 fr-FR,以及俄文 (俄羅斯) 或 ru-RU。 en-US 資源包含在名為 Greetings.txt 的文字檔中:

HelloString=Hello world!

fr-FR 資源包含在名為 Greetings.fr-FR.txt 的文字檔中:

HelloString=Salut tout le monde!

ru-RU 資源包含在名為 Greetings.ru-RU.txt 的文字檔中:

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

以下是適用于 Visual Basic 版本的範例 (Example.vb 的原始程式碼,或 C# 版本的 Example.cs) :

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.
'       Всем привет!

若要編譯此範例,請建立包含下列命令的批次 (.bat) 檔案,並從命令提示字元執行。 如果您使用 C#,請指定 csc 而不是 vbcExample.cs ,而不是 Example.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

擷取資源

您可以呼叫 GetObject(String)GetString(String) 方法來存取特定資源。 您也可以呼叫 GetStream(String) 方法來擷取非字串資源作為位元組陣列。 根據預設,在具有當地語系化資源的應用程式中,這些方法會傳回由發出呼叫之執行緒目前 UI 文化特性所決定文化特性的資源。 如需如何定義執行緒目前 UI 文化特性的詳細資訊,請參閱上一節 ResourceManager 和 Culture-Specific Resources。 如果資源管理員找不到目前線程 UI 文化特性的資源,它會使用後援進程來擷取指定的資源。 如果資源管理員找不到任何當地語系化的資源,它會使用預設文化特性的資源。 如需資源後援規則的詳細資訊,請參閱 封裝和部署資源一文中的一節。

注意

如果找不到類別建構函式中指定的 ResourceManager .resources 檔案,則嘗試擷取資源會 MissingManifestResourceException 擲回 或 MissingSatelliteAssemblyException 例外狀況。 如需處理例外狀況的相關資訊,請參閱本主題稍後 的處理 MissingManifestResourceException 和 MissingSatelliteAssemblyException 例外狀況 一節。

下列範例會 GetString 使用 方法來擷取特定文化特性的資源。 其中包含從英文 (en) 、法文 (法國) (fr-FR) ,以及俄文 (俄羅斯) (ru-RU) 文化特性的.txt檔案所編譯的資源。 此範例會將目前的文化特性和目前 UI 文化特性變更為英文 (美國) 、法文 (法國) 、俄文 (俄羅斯) ,以及瑞典文 (瑞典) 。 然後它會呼叫 GetString 方法來擷取當地語系化字串,其會顯示于當天和月份。 請注意,輸出會顯示適當的當地語系化字串,但目前的 UI 文化特性是瑞典文 (瑞典) 。 因為無法使用瑞典文語言資源,所以應用程式會改用預設文化特性的資源,也就是英文。

此範例需要下表所列的文字型資源檔。 每個都有名為 DateStart 的單一字串資源。

文化特性 檔案名稱 資源名稱 資源值
en-US DateStrings.txt DateStart 今天是
fr-FR DateStrings.fr-FR.txt DateStart Aujourd'hui, c'est le
ru-RU DateStrings.ru-RU.txt DateStart Сегодня

以下是 (Visual Basic 版的 ShowDate.vb 範例原始程式碼,或) C# 版本的 ShowDate.cs 範例。

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

[assembly:NeutralResourcesLanguage("en")]

public class Example
{
   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 Example
   Public Sub Main()
      Dim cultureNames() As String = { "en-US", "fr-FR", "ru-RU", "sv-SE" }
      Dim rm As New ResourceManager("DateStrings",
                                    GetType(Example).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.

若要編譯此範例,請建立包含下列命令的批次檔,並從命令提示字元執行。 如果您使用 C#,請指定 csc 而不是 vbcshowdate.cs 而不是 showdate.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

有兩種方式可擷取目前 UI 文化特性以外的特定文化特性資源:

  • 您可以呼叫 GetString(String, CultureInfo)GetObject(String, CultureInfo)GetStream(String, CultureInfo) 方法來擷取特定文化特性的資源。 如果找不到當地語系化的資源,資源管理員會使用資源後援程式來找出適當的資源。

  • 您可以呼叫 GetResourceSet 方法,以取得 ResourceSet 代表特定文化特性之資源的 物件。 在方法呼叫中,您可以判斷如果資源管理員無法找到當地語系化的資源,還是只回復到預設文化特性的資源,資源管理員會探查父文化特性。 然後 ResourceSet ,您可以使用 方法來存取 (依名稱) 當地語系化的資源,或列舉集合中的資源。

處理 MissingManifestResourceException 和 MissingSatelliteAssemblyException 例外狀況

如果您嘗試擷取特定資源,但資源管理員找不到該資源,而且未定義預設文化特性,或無法找到預設文化特性的資源,則資源管理員 MissingManifestResourceException 會在預期在主要元件 MissingSatelliteAssemblyException 中找到資源時擲回例外狀況,如果預期在附屬元件中尋找資源,則會擲回例外狀況。 請注意,當您呼叫 或 GetObject 之類的 GetString 資源擷取方法時,不會在具現化 ResourceManager 物件時擲回例外狀況。

例外狀況通常會在下列情況下擲回:

  • 適當的資源檔或附屬元件不存在。 如果資源管理員預期應用程式的預設資源會內嵌在主要應用程式元件中,則它們不存在。 NeutralResourcesLanguageAttribute如果屬性指出應用程式的預設資源位於附屬元件中,則找不到該元件。 當您編譯應用程式時,請確定資源會內嵌在主要元件中,或產生必要的附屬元件,並適當地命名。 其名稱格式應為 appName .resources.dll,而且應該位於名為之後它所包含之資源的文化特性的目錄。

  • 您的應用程式未定義預設或中性文化特性。 將 NeutralResourcesLanguageAttribute 屬性新增至原始程式碼檔或專案資訊檔, (Visual Basic app 的 AssemblyInfo.vb 或 C# 應用程式) 檔案的 AssemblyInfo.cs。

  • baseName 構函式中的 ResourceManager(String, Assembly) 參數未指定 .resources 檔案的名稱。 名稱應包含資源檔的完整命名空間,但不應包含其副檔名。 一般而言,在 Visual Studio 中建立的資源檔包含命名空間名稱,但在命令提示字元中建立和編譯的資源檔則不會。 您可以編譯和執行下列公用程式來判斷內嵌 .resources 檔案的名稱。 這是主控台應用程式,可接受主要元件或附屬元件的名稱做為命令列參數。 它會顯示應提供為 參數的 baseName 字串,讓資源管理員能夠正確識別資源。

    using System;
    using System.IO;
    using System.Reflection;
    using System.Resources;
    
    public class Example
    {
       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
    

如果您要明確變更應用程式的目前文化特性,您也應該記得資源管理員會根據 屬性的值 CultureInfo.CurrentUICulture 擷取資源集,而不是 CultureInfo.CurrentCulture 屬性。 一般而言,如果您變更一個值,您也應該變更另一個值。

資源版本控制

因為包含應用程式預設資源的主要元件與應用程式的附屬元件不同,所以您可以釋放新版的主要元件,而不需要重新部署附屬元件。 您可以使用 SatelliteContractVersionAttribute 屬性來使用現有的附屬元件,並指示資源管理員不要以新版的主要元件重新部署它們。

如需附屬元件版本控制支援的詳細資訊,請參閱 擷取資源一文。

<satelliteassemblies> 組態檔節點

注意

本節專屬於.NET Framework應用程式。

針對從網站部署和執行的可執行檔, (HREF .exe檔案) , ResourceManager 物件可能會透過 Web 探查附屬元件,這會損害您應用程式的效能。 若要消除效能問題,您可以將此探查限制為已使用應用程式部署的附屬元件。 若要這樣做,您可以在應用程式的組態檔中建立 <satelliteassemblies> 節點,以指定您已為應用程式部署一組特定的文化特性,而且 ResourceManager 物件不應該嘗試探查該節點中未列出的任何文化特性。

注意

建立節點的慣用替代方案 <satelliteassemblies> 是使用ClickOnce部署資訊清單功能。

在應用程式的組態檔中,建立類似下列的區段:

<?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>

編輯此組態資訊,如下所示:

  • 針對您部署的每個主要元件指定一或多個 <assembly> 節點,其中每個節點會指定完整元件名稱。 指定主要元件的名稱以取代 MainAssemblyName,並指定 Version 對應至主要元件的 、 PublicKeyTokenCulture 屬性值。

    Version針對 屬性,指定元件的版本號碼。 例如,第一個版本的元件可能是版本號碼 1.0.0.0。

    PublicKeyToken針對 屬性,如果您尚未使用強式名稱簽署元件,請指定 關鍵字 null ,或者如果您已簽署元件,請指定公開金鑰權杖。

    Culture針對 屬性,指定 關鍵字 neutral 以指定主要元件,並讓 ResourceManager 類別只探查節點中列出的 <culture> 文化特性。

    如需完整元件名稱的詳細資訊,請參閱 元件名稱一文。 如需強式名稱元件的詳細資訊,請參閱 建立和使用強式名稱元件一文。

  • 使用特定文化特性名稱指定一或多個 <culture> 節點,例如 「fr-FR」 或中性文化特性名稱,例如 「fr」。

如果節點下 <satelliteassemblies> 未列出的任何元件需要資源,類別 ResourceManager 會使用標準探查規則探查文化特性。

Windows 8.x Apps

重要

雖然 Windows 8.x 應用程式中支援 類別 ResourceManager ,但我們不建議使用它。 只有在您開發可搭配 Windows 8.x 應用程式使用的可攜式類別庫專案時,才使用此類別。 若要從 Windows 8.x 應用程式擷取資源,請使用Windows。ApplicationModel.Resources.ResourceLoader類別。

針對 Windows 8.x 應用程式,類別會 ResourceManager 從套件資源索引擷取資源, (PRI) 檔案。 單一 PRI 檔案 (應用程式套件 PRI 檔案) 包含預設文化特性和任何當地語系化文化特性的資源。 您可以使用 MakePRI 公用程式,從 XML 資源 (.resw) 格式的一或多個資源檔建立 PRI 檔案。 對於包含在Visual Studio專案中的資源,Visual Studio會自動處理建立和封裝 PRI 檔案的程式。 然後,您可以使用 .NET Framework ResourceManager 類別來存取應用程式的 或程式庫資源。

您可以使用與傳統型應用程式相同的方式,為 Windows 8.x 應用程式具現化 ResourceManager 物件。

然後,您可以傳遞要擷取至 GetString(String) 方法的資源名稱,以存取特定文化特性的資源。 根據預設,此方法會傳回由發出呼叫之執行緒目前 UI 文化特性所決定之文化特性的資源。 您也可以傳遞資源的名稱,以及 CultureInfo 代表資源要擷取至 GetString(String, CultureInfo) 方法之文化特性之文化特性的物件,以擷取特定文化特性的資源。 如果找不到目前 UI 文化特性或指定文化特性的資源,資源管理員會使用 UI 語言後援清單來找出適當的資源。

建構函式

ResourceManager()

使用預設值,初始化 ResourceManager 類別的新執行個體。

ResourceManager(String, Assembly)

初始化 ResourceManager 類別的新執行個體,這個執行個體會在所指的組件中查閱具有指定根名稱之檔案中的資源。

ResourceManager(String, Assembly, Type)

初始化 ResourceManager 類別的新執行個體,這個執行個體使用指定的 ResourceSet 類別查閱所指組件中具有指定根名稱的檔案所包含的資源。

ResourceManager(Type)

根據指定之型別物件的資訊,初始化可查閱附屬組件中資源之 ResourceManager 類別的新執行個體。

欄位

BaseNameField

指定 ResourceManager 搜尋資源的資源檔之根目錄名稱。

HeaderVersionNumber

指定目前 ResourceManager 的實作能夠解譯和產生的資源檔標頭版本。

MagicNumber

保留用來識別資源檔的編號。

MainAssembly

指定包含資源的主要組件。

ResourceSets
已過時。

包含 Hashtable,其傳回從文化特性到 ResourceSet 物件的對應。

屬性

BaseName

取得 ResourceManager 搜尋資源的資源檔之根目錄名稱。

FallbackLocation

取得或設定要擷取預設後援資源的位置。

IgnoreCase

取得或設定值,指出資源管理員是否允許在 GetString(String)GetObject(String) 方法中進行不區分大小寫的資源查詢。

ResourceSetType

取得資源管理員用來建構 ResourceSet 物件之資源集物件的型別。

方法

CreateFileBasedResourceManager(String, String, Type)

傳回 ResourceManager 物件,該物件會搜尋特定目錄而不是資源的組件資訊清單。

Equals(Object)

判斷指定的物件是否等於目前的物件。

(繼承來源 Object)
GetHashCode()

做為預設雜湊函式。

(繼承來源 Object)
GetNeutralResourcesLanguage(Assembly)

藉由擷取指定之組件上的 NeutralResourcesLanguageAttribute 屬性的值,傳回主要組件的預設資源的文化特性資訊。

GetObject(String)

傳回指定的非字串資源的值。

GetObject(String, CultureInfo)

取得針對指定的文化特性當地語系化之所指定非字串資源的值。

GetResourceFileName(CultureInfo)

為所指 CultureInfo 物件產生資源檔的名稱。

GetResourceSet(CultureInfo, Boolean, Boolean)

擷取特定文化特性設定的資源。

GetSatelliteContractVersion(Assembly)

傳回所指組件中 SatelliteContractVersionAttribute 屬性所指定的版本。

GetStream(String)

從指定的資源傳回 Unmanaged 記憶體資料流物件。

GetStream(String, CultureInfo)

使用指定的文化特性,從指定的資源傳回 Unmanged 記憶體資料流物件。

GetString(String)

傳回指定的字串資源的值。

GetString(String, CultureInfo)

傳回為指定文化特性當地語系化之字串資源的值。

GetType()

取得目前執行個體的 Type

(繼承來源 Object)
InternalGetResourceSet(CultureInfo, Boolean, Boolean)

提供用來尋找資源集的實作。

MemberwiseClone()

建立目前 Object 的淺層複製。

(繼承來源 Object)
ReleaseAllResources()

指示資源管理員要呼叫所有 ResourceSet 物件上的 Close() 方法並釋放所有資源。

ToString()

傳回代表目前物件的字串。

(繼承來源 Object)

適用於

執行緒安全性

此型別具備執行緒安全。

另請參閱