在 .NET 應用程式中封裝和部署資源Packaging and Deploying Resources in .NET Apps

應用程式會依賴 ResourceManager 類別所代表的 .NET Framework Resource Manager,來擷取當地語系化的資源。Applications rely on the .NET Framework Resource Manager, represented by the ResourceManager class, to retrieve localized resources. Resource Manager 假設使用中樞和支點模型來封裝和部署資源。The Resource Manager assumes that a hub and spoke model is used to package and deploy resources. 中樞是主要組件,其中包含未當地語系化的可執行程式碼以及稱為中性或預設文化特性之單一文化特性的資源。The hub is the main assembly that contains the nonlocalizable executable code and the resources for a single culture, called the neutral or default culture. 預設文化特性是應用程式的後援文化特性;如果找不到當地語系化的資源,則它是使用其資源的文化特性。The default culture is the fallback culture for the application; it is the culture whose resources are used if localized resources cannot be found. 每個支點都會連線至附屬組件,其中包含單一文化特性但未包含任何程式碼的資源。Each spoke connects to a satellite assembly that contains the resources for a single culture, but does not contain any code.

這個模型有數個優點:There are several advantages to this model:

  • 在您部署應用程式之後,可以透過累加方式新增新文化特性的資源。You can incrementally add resources for new cultures after you have deployed an application. 因為文化特性特定資源的後續開發可能需要很長一段時間,所以這可讓您先發行主要應用程式,並於日後提供文化特性特定資源。Because subsequent development of culture-specific resources can require a significant amount of time, this allows you to release your main application first, and deliver culture-specific resources at a later date.
  • 您可以更新並變更應用程式的附屬組件,而不需要重新編譯應用程式。You can update and change an application's satellite assemblies without recompiling the application.
  • 應用程式只需要載入包含特定文化特性所需之資源的附屬組件。An application needs to load only those satellite assemblies that contain the resources needed for a particular culture. 這可以大幅降低系統資源的使用。This can significantly reduce the use of system resources.

不過,這個模型也有缺點:However, there are also disadvantages to this model:

  • 您必須管理多組資源。You must manage multiple sets of resources.
  • 因為您必須測試數個組態,所以測試應用程式的初始成本會增加。The initial cost of testing an application increases, because you must test several configurations. 請注意,長期而言,測試一個具有數個附屬的核心應用程式,與測試並維護數個平行國際版本相較之下,較為簡單且費用較少。Note that in the long term it will be easier and less expensive to test one core application with several satellites, than to test and maintain several parallel international versions.

資源命名慣例Resource naming conventions

當您封裝應用程式的資源時,必須使用 Common Language Runtime 所預期的資源命名慣例來命名它們。When you package your application's resources, you must name them using the resource naming conventions that the common language runtime expects. 執行階段會依文化特性名稱識別資源。The runtime identifies a resource by its culture name. 每個文化特性都會獲指定唯一名稱,此名稱通常是下列項目的組合:與語言建立關聯的兩個字母小寫文化特性名稱以及與國家或地區建立關聯的兩個字母大寫子文化特性名稱 (必要時)。Each culture is given a unique name, which is usually a combination of a two-letter, lowercase culture name associated with a language and, if required, a two-letter, uppercase subculture name associated with a country or region. 子文化特性名稱遵循文化特性名稱,以破折號 (-) 分隔。The subculture name follows the culture name, separated by a dash (-). 範例包括 ja-JP (代表在日本日文)、en-US (美式英文)、de-DE (德國德文),或 de-AT (奧地利德文)。Examples include ja-JP for Japanese as spoken in Japan, en-US for English as spoken in the United States, de-DE for German as spoken in Germany, or de-AT for German as spoken in Austria. 請參閱 Windows 支援的語言/地區名稱清單中的 [語言標記] 資料行。See the Language tag column in the list of language/region names supported by Windows. 文化名稱遵循 BCP 47 定義的標準。Culture names follow the standard defined by BCP 47.

注意

這兩個字母的文化特性名稱有一些例外,例如中文(簡體) @no__t 0。There are some exceptions for the two-letter culture names, such as zh-Hans for Chinese (Simplified).

注意

如需建立資源檔的資訊,請參閱建立資源檔建立附屬組件For information about creating resource files, see Creating Resource Files and Creating Satellite Assemblies.

資源後援處理序The Resource Fallback Process

封裝和部署資源的中樞和支點模型會使用後援程序來找出適當的資源。The hub and spoke model for packaging and deploying resources uses a fallback process to locate appropriate resources. 如果應用程式要求的當地語系化資源無法使用,通用語言執行平台 (CLR) 就會在文化特性的階層架構中搜尋最接近使用者應用程式所要求的適當後援資源,而擲回例外狀況只會做為最後手段。If an application requests a localized resource that is unavailable, the common language runtime searches the hierarchy of cultures for an appropriate fallback resource that most closely matches the user's application's request, and throws an exception only as a last resort. 在階層的每個層級,如果找到適當的資源,則執行階段會使用它。At each level of the hierarchy, if an appropriate resource is found, the runtime uses it. 如果找不到資源,則會繼續搜尋下一個層級。If the resource is not found, the search continues at the next level.

若要改善查閱效能,請將 NeutralResourcesLanguageAttribute 屬性套用至主要組件,並將使用主要組件之中性語言的名稱傳遞給它。To improve lookup performance, apply the NeutralResourcesLanguageAttribute attribute to your main assembly, and pass it the name of the neutral language that will work with your main assembly.

.NET Framework 資源後援處理序.NET Framework resource fallback process

.NET Framework 資源後援處理序包含下列步驟:The .NET Framework resource fallback process involves the following steps:

提示

您可以使用 <relativeBindForResources> 組態項目最佳化資源後援處理序,以及執行階段探查資源組件的處理序。You may be able to use the <relativeBindForResources> configuration element to optimize the resource fallback process and the process by which the runtime probes for resource assemblies. 如需詳細資訊,請參閱最佳化資源後援處理序一節。For more information, see the Optimizing the Resource Fallback Process section.

  1. 執行階段會先檢查全域組件快取是否有符合應用程式之所要求文化特性的組件。The runtime first checks the global assembly cache for an assembly that matches the requested culture for your application.

    全域組件快取可以儲存多個應用程式所共用的資源組件。The global assembly cache can store resource assemblies that are shared by many applications. 這可讓您不需要在所建立之每個應用程式的目錄結構中包括特定資源集。This frees you from having to include specific sets of resources in the directory structure of every application you create. 如果執行階段找到組件的參考,則會搜尋所要求資源的組件。If the runtime finds a reference to the assembly, it searches the assembly for the requested resource. 如果在組件中找到項目,則會使用所要求的資源。If it finds the entry in the assembly, it uses the requested resource. 如果找不到項目,會繼續搜尋。If it doesn't find the entry, it continues the search.

  2. 執行階段接下來會檢查目前執行中組件的目錄中是否有符合所要求文化特性的子目錄。The runtime next checks the directory of the currently executing assembly for a subdirectory that matches the requested culture. 如果它找到子目錄,則會搜尋該子目錄中是否有所要求文化特性的有效附屬組件。If it finds the subdirectory, it searches that subdirectory for a valid satellite assembly for the requested culture. 執行階段接著會搜尋所要求資源的附屬組件。The runtime then searches the satellite assembly for the requested resource. 如果在組件中找到資源,則會使用它。If it finds the resource in the assembly, it uses it. 如果找不到資源,會繼續搜尋。If it doesn't find the resource, it continues the search.

  3. 執行階段接下來會查詢 Windows Installer,以判斷是否依需求安裝附屬組件。The runtime next queries the Windows Installer to determine whether the satellite assembly is to be installed on demand. 如果是這樣,它會處理安裝、載入組件,並搜尋它或所要求的資源。If so, it handles the installation, loads the assembly, and searches it or the requested resource. 如果在組件中找到資源,則會使用它。If it finds the resource in the assembly, it uses it. 如果找不到資源,會繼續搜尋。If it doesn't find the resource, it continues the search.

  4. 執行階段會引發 AppDomain.AssemblyResolve 事件,指出找不到附屬組件。The runtime raises the AppDomain.AssemblyResolve event to indicate that it is unable to find the satellite assembly. 如果您選擇處理事件,則事件處理常式會傳回其資源用於查閱之附屬組件的參考。If you choose to handle the event, your event handler can return a reference to the satellite assembly whose resources will be used for the lookup. 否則,事件處理常式會傳回 null 並繼續搜尋。Otherwise, the event handler returns null and the search continues.

  5. 執行階段接下來會重新搜尋全域組件快取,這一次則會搜尋所要求文化特性的父組件。The runtime next searches the global assembly cache again, this time for the parent assembly of the requested culture. 如果父組件位於全域組件快取中,則執行階段會搜尋所要求資源的組件。If the parent assembly exists in the global assembly cache, the runtime searches the assembly for the requested resource.

    父文化特性會定義為適當的後援文化特性。The parent culture is defined as the appropriate fallback culture. 請將父項視為後援候選項目,因為最好提供任何資源以擲回例外狀況。Consider parents as fallback candidates, because providing any resource is preferable to throwing an exception. 此程序也可讓您重複使用資源。This process also allows you to reuse resources. 只有在子文化特性不需要當地語系化所要求的資源時,才應該包括父層級的特定資源。You should include a particular resource at the parent level only if the child culture doesn't need to localize the requested resource. 例如,如果您提供適用於 en (中性英文)、en-GB (英式英文) 和 en-US (美式英文) 的附屬組件,en 附屬組件就會包含一般術語,而 en-GBen-US 附屬組件可以僅針對那些不同的詞彙提供覆寫。For example, if you supply satellite assemblies for en (neutral English), en-GB (English as spoken in the United Kingdom), and en-US (English as spoken in the United States), the en satellite would contain the common terminology, and the en-GB and en-US satellites could provide overrides for only those terms that differ.

  6. 執行階段接著會檢查目前執行中組件的目錄,以查看它是否包含上層目錄。The runtime next checks the directory of the currently executing assembly to see if it contains a parent directory. 如果已有上層目錄,則執行階段會搜尋目錄中是否有父文化特性的有效附屬組件。If a parent directory exists, the runtime searches the directory for a valid satellite assembly for the parent culture. 如果找到組件,則執行階段會搜尋所要求資源的組件。If it finds the assembly, the runtime searches the assembly for the requested resource. 如果找到資源,則會使用它。If it finds the resource, it uses it. 如果找不到資源,會繼續搜尋。If it doesn't find the resource, it continues the search.

  7. 執行階段接下來會查詢 Windows Installer,以判斷是否依需求安裝父附屬組件。The runtime next queries the Windows Installer to determine whether the parent satellite assembly is to be installed on demand. 如果是這樣,它會處理安裝、載入組件,並搜尋它或所要求的資源。If so, it handles the installation, loads the assembly, and searches it or the requested resource. 如果在組件中找到資源,則會使用它。If it finds the resource in the assembly, it uses it. 如果找不到資源,會繼續搜尋。If it doesn't find the resource, it continues the search.

  8. 執行階段會引發 AppDomain.AssemblyResolve 事件,指出找不到適當的後援資源。The runtime raises the AppDomain.AssemblyResolve event to indicate that it is unable to find an appropriate fallback resource. 如果您選擇處理事件,則事件處理常式會傳回其資源用於查閱之附屬組件的參考。If you choose to handle the event, your event handler can return a reference to the satellite assembly whose resources will be used for the lookup. 否則,事件處理常式會傳回 null 並繼續搜尋。Otherwise, the event handler returns null and the search continues.

  9. 執行階段接下來會如先前三個步驟所述搜尋父組件的多個可能層級。The runtime next searches parent assemblies, as in the previous three steps, through many potential levels. 每個文化特性都只有 CultureInfo.Parent 屬性所定義的一個父代,但是父代可能有其本身的父代。Each culture has only one parent, which is defined by the CultureInfo.Parent property, but a parent might have its own parent. 文化特性的 Parent 屬性傳回 CultureInfo.InvariantCulture 時,會停止搜尋父文化特性;針對資源後援,不會將不區分文化特性視為父文化特性或可有資源的文化特性。The search for parent cultures stops when a culture's Parent property returns CultureInfo.InvariantCulture; for resource fallback, the invariant culture is not considered a parent culture or a culture that can have resources.

  10. 如果已搜尋原先指定的文化特性和所有父項,但仍然找不到資源,則會使用預設 (後援) 文化特性的資源。If the culture that was originally specified and all parents have been searched and the resource is still not found, the resource for the default (fallback) culture is used. 通常,主要應用程式組件中會包含預設文化特性的資源。Typically, the resources for the default culture are included in the main application assembly. 不過,您可以指定 NeutralResourcesLanguageAttribute 屬性 (attribute) 之 Location 屬性 (property) 的 Satellite 值,指出資源的最終後援位置是附屬組件,而不是主要組件。However, you can specify a value of Satellite for the Location property of the NeutralResourcesLanguageAttribute attribute to indicate that the ultimate fallback location for resources is a satellite assembly, rather than the main assembly.

    注意

    預設資源是可使用主要組件進行編譯的唯一資源。The default resource is the only resource that can be compiled with the main assembly. 除非您使用 NeutralResourcesLanguageAttribute 屬性指定附屬組件,否則它是最終後援 (最終父項)。Unless you specify a satellite assembly by using the NeutralResourcesLanguageAttribute attribute, it is the ultimate fallback (final parent). 因此,建議您一律在主要組件中包括預設一組資源。Therefore, we recommend that you always include a default set of resources in your main assembly. 這樣有助於防止擲回例外狀況。This helps prevent exceptions from being thrown. 透過包括預設資源檔,您就能為所有資源提供後援,並確保使用者一律至少有一個資源,即使該資源不是文化特性特有的也一樣。By including a default resource, file you provide a fallback for all resources and ensure that at least one resource is always present for the user, even if it is not culturally specific.

  11. 最後,如果執行階段找不到預設 (後援) 文化特性的資源,則會擲回 MissingManifestResourceExceptionMissingSatelliteAssemblyException 例外狀況,指出找不到資源。Finally, if the runtime doesn't find a resource for a default (fallback) culture, a MissingManifestResourceException or MissingSatelliteAssemblyException exception is thrown to indicate that the resource could not be found.

例如,假設應用程式要求已針對西班牙文 (墨西哥) (es-MX 文化特性) 進行當地語系化的資源。For example, suppose the application requests a resource localized for Spanish (Mexico) (the es-MX culture). 執行階段會先在全域組件快取中搜尋符合 es-MX 的組件,但找不到。The runtime first searches the global assembly cache for the assembly that matches es-MX, but doesn't find it. 執行階段接著會在目前執行中組件的目錄內搜尋 es-MX 目錄。The runtime then searches the directory of the currently executing assembly for an es-MX directory. 如果失敗,執行階段就會在全域組件快取中重新搜尋可反映適當後援文化特性的父組件,在此案例中為 es (西班牙文)。Failing that, the runtime searches the global assembly cache again for a parent assembly that reflects the appropriate fallback culture — in this case, es (Spanish). 如果找不到父組件,執行階段就會搜尋 es-MX 文化特性之父組件的所有可能層級,直到找到對應的資源為止。If the parent assembly is not found, the runtime searches all potential levels of parent assemblies for the es-MX culture until it finds a corresponding resource. 如果找不到資源,執行階段會使用預設文化特性的資源。If a resource isn't found, the runtime uses the resource for the default culture.

將 .NET Framework 資源後援處理序最佳化Optimizing the .NET Framework Resource Fallback Process

在下列情況中,您可以最佳化執行階段用來搜尋附屬組件中資源的程序。Under the following conditions, you can optimize the process by which the runtime searches for resources in satellite assemblies

  • 附屬組件會部署在與程式碼組件相同的位置中。Satellite assemblies are deployed in the same location as the code assembly. 如果程式碼組件安裝在全域組件快取中,則也會將附屬組件安裝在全域組件快取中。If the code assembly is installed in the Global Assembly Cache, satellite assemblies are also installed in the global assembly cache. 如果程式碼組件安裝在目錄中,則附屬組件會安裝在該目錄的文化特性特定資料夾中。If the code assembly is installed in a directory, satellite assemblies are installed in culture-specific folders of that directory.

  • 不會隨選安裝附屬組件。Satellite assemblies are not installed on demand.

  • 應用程式碼不會處理 AppDomain.AssemblyResolve 事件。Application code does not handle the AppDomain.AssemblyResolve event.

如下列範例所示,您將藉由在應用程式組態檔中加入 <relativeBindForResources> 項目並且將其 enabled 屬性設定為 true 的方式,最佳化附屬組件的探查工作。You optimize the probe for satellite assemblies by including the <relativeBindForResources> element and setting its enabled attribute to true in the application configuration file, as shown in the following example.

<configuration>
   <runtime>
      <relativeBindForResources enabled="true" />
   </runtime>
</configuration>

附屬組件的最佳化探查是選擇性功能。The optimized probe for satellite assemblies is an opt-in feature. 也就是說,執行階段會遵循資源後援處理序中說明的步驟,除非應用程式組態檔中已有 <relativeBindForResources> 項目,而且其 enabled 屬性已設定為 trueThat is, the runtime follows the steps documented in The Resource Fallback Process unless the <relativeBindForResources> element is present in the application's configuration file and its enabled attribute is set to true. 如果是這種情況,附屬組件的探查程序修改如下:If this is the case, the process of probing for a satellite assembly is modified as follows:

  • 執行階段使用父程式碼組件的位置來探查附屬組件。The runtime uses the location of the parent code assembly to probe for the satellite assembly. 如果父組件安裝在全域組件快取中,則執行階段會在快取中探查,而不是在應用程式目錄中探查。If the parent assembly is installed in the global assembly cache, the runtime probes in the cache but not in the application's directory. 如果父組件安裝在應用程式目錄中,則執行階段會在應用程式目錄中探查,而不是在全域組件快取中探查。If the parent assembly is installed in an application directory, the runtime probes in the application directory but not in the global assembly cache.

  • 執行階段不會查詢 Windows Installer 是否有附屬組件的隨選安裝。The runtime doesn't query the Windows Installer for on-demand installation of satellite assemblies.

  • 如果探查特定資源組件失敗,則執行階段不會引發 AppDomain.AssemblyResolve 事件。If the probe for a particular resource assembly fails, the runtime does not raise the AppDomain.AssemblyResolve event.

.NET Core 資源後援處理序.NET Core resource fallback process

.NET Core 資源後援處理序包含下列步驟:The .NET Core resource fallback process involves the following steps:

  1. 執行階段會嘗試載入所要求文化特性的附屬組件。The runtime attempts to load a satellite assembly for the requested culture.

    • 檢查目前執行中組件的目錄中是否有符合所要求文化特性的子目錄。Checks the directory of the currently executing assembly for a subdirectory that matches the requested culture. 如果它找到子目錄,則會在該子目錄內搜尋所要求文化特性的有效附屬組件並載入它。If it finds the subdirectory, it searches that subdirectory for a valid satellite assembly for the requested culture and loads it.

      注意

      在具備區分大小寫之檔案系統的作業系統 (也就是 Linux 和 macOS) 上,文化特性名稱子目錄搜尋會區分大小寫。On operating systems with case-sensitive file systems (that is, Linux and macOS), the culture name subdirectory search is case-sensitive. 子目錄名稱必須完全符合 CultureInfo.Name 的大小寫 (例如 eses-MX)。The subdirectory name must exactly match the case of the CultureInfo.Name (for example, es or es-MX).

      注意

      如果程式設計師已從 AssemblyLoadContext 衍生了自訂組件載入內容,則情況很複雜。If the programmer has derived a custom assembly load context from AssemblyLoadContext, the situation is complicated. 如果已將執行中組件載入到自訂內容,執行階段就會將附屬組件載入到自訂內容。If the executing assembly was loaded into the custom context, the runtime loads the satellite assembly into the custom context. 詳細資料不在本文的範圍內。The details are out of scope for this document. 請參閱 AssemblyLoadContextSee AssemblyLoadContext.

    • 如果找不到附屬組件,AssemblyLoadContext 就會引發 AssemblyLoadContext.Resolving 事件,指出找不到附屬組件。If a satellite assemble has not been found, the AssemblyLoadContext raises the AssemblyLoadContext.Resolving event to indicate that it is unable to find the satellite assembly. 如果您選擇處理事件,則您的事件處理常式可以載入並傳回附屬組件的參考。If you choose to handle the event, your event handler can load and return a reference to the satellite assembly.

    • 如果仍然找不到附屬組件,AssemblyLoadContext 就會導致 AppDomain 觸發 AppDomain.AssemblyResolve 事件,指出它找不到附屬組件。If a satellite assembly still has not been found, the AssemblyLoadContext causes the AppDomain to trigger an AppDomain.AssemblyResolve event to indicate that it is unable to find the satellite assembly. 如果您選擇處理事件,則您的事件處理常式可以載入並傳回附屬組件的參考。If you choose to handle the event, your event handler can load and return a reference to the satellite assembly.

  2. 如果找到了附屬組件,執行階段就會在其中搜尋所要求的資源。If a satellite assembly is found, the runtime searches it for the requested resource. 如果在組件中找到資源,則會使用它。If it finds the resource in the assembly, it uses it. 如果找不到資源,會繼續搜尋。If it doesn't find the resource, it continues the search.

    注意

    為了在附屬組件內尋找資源,執行階段會搜尋目前 CultureInfo.NameResourceManager 所要求的資源檔。To find a resource within the satellite assembly, the runtime searches for the resource file requested by the ResourceManager for the current CultureInfo.Name. 它會在資源檔內搜尋所要求的資源名稱。Within the resource file it searches for the requested resource name. 如果找不到任一個,就會將資源視為找不到。If either is not found, the resource is treated as not found.

  3. 執行階段接下來會透過許多可能的層級搜尋父文化特性組件,每次均會重複執行步驟 1 和 2。The runtime next searches the parent culture assemblies through many potential levels, each time repeating steps 1 & 2.

    父文化特性會定義為適當的後援文化特性。The parent culture is defined as an appropriate fallback culture. 請將父項視為後援候選項目,因為最好提供任何資源以擲回例外狀況。Consider parents as fallback candidates, because providing any resource is preferable to throwing an exception. 此程序也可讓您重複使用資源。This process also allows you to reuse resources. 只有在子文化特性不需要當地語系化所要求的資源時,才應該包括父層級的特定資源。You should include a particular resource at the parent level only if the child culture doesn't need to localize the requested resource. 例如,如果您提供適用於 en (中性英文)、en-GB (英式英文) 和 en-US (美式英文) 的附屬組件,en 附屬組件就會包含一般術語,而 en-GBen-US 附屬組件僅會針對那些不同的詞彙提供覆寫。For example, if you supply satellite assemblies for en (neutral English), en-GB (English as spoken in the United Kingdom), and en-US (English as spoken in the United States), the en satellite contains the common terminology, and the en-GB and en-US satellites provides overrides for only those terms that differ.

    每個文化特性都只有 CultureInfo.Parent 屬性所定義的一個父代,但是父代可能有其本身的父代。Each culture has only one parent, which is defined by the CultureInfo.Parent property, but a parent might have its own parent. 當文化特性的 Parent 屬性傳回 CultureInfo.InvariantCulture 時,即會停止搜尋父文化特性。The search for parent cultures stops when a culture's Parent property returns CultureInfo.InvariantCulture. 針對資源後援,不會將不因文化特性而異視為父文化特性或可擁有資源的文化特性。For resource fallback, the invariant culture is not considered a parent culture or a culture that can have resources.

  4. 如果已搜尋原先指定的文化特性和所有父項,但仍然找不到資源,則會使用預設 (後援) 文化特性的資源。If the culture that was originally specified and all parents have been searched and the resource is still not found, the resource for the default (fallback) culture is used. 通常,主要應用程式組件中會包含預設文化特性的資源。Typically, the resources for the default culture are included in the main application assembly. 不過,您可以指定 Location 屬性的 Satellite 值,指出資源的最終後援位置是附屬組件,而不是主要組件。However, you can specify a value of Satellite for the Location property to indicate that the ultimate fallback location for resources is a satellite assembly rather than the main assembly.

    注意

    預設資源是可使用主要組件進行編譯的唯一資源。The default resource is the only resource that can be compiled with the main assembly. 除非您使用 NeutralResourcesLanguageAttribute 屬性指定附屬組件,否則它是最終後援 (最終父項)。Unless you specify a satellite assembly by using the NeutralResourcesLanguageAttribute attribute, it is the ultimate fallback (final parent). 因此,建議您一律在主要組件中包括預設一組資源。Therefore, we recommend that you always include a default set of resources in your main assembly. 這樣有助於防止擲回例外狀況。This helps prevent exceptions from being thrown. 透過包括預設資源檔,您就能為所有資源提供後援,並確保使用者一律至少有一個資源,即使該資源不是文化特性特有的也一樣。By including a default resource file, you provide a fallback for all resources and ensure that at least one resource is always present for the user, even if it is not culturally specific.

  5. 最後,如果執行階段找不到預設 (後援) 文化特性的資源檔,即會擲回 MissingManifestResourceExceptionMissingSatelliteAssemblyException 例外狀況,指出找不到資源。Finally, if the runtime doesn't find a resource file for a default (fallback) culture, a MissingManifestResourceException or MissingSatelliteAssemblyException exception is thrown to indicate that the resource could not be found. 如果找到了資源檔,但所要求的資源不存在,要求就會傳回 nullIf the resource file is found but the requested resource is not present the request returns null.

附屬組件的最終後援Ultimate Fallback to Satellite Assembly

您可以選擇性地從主要組件中移除資源,並指定執行階段應該從對應至特定文化特性的附屬組件中載入最終後援資源。You can optionally remove resources from the main assembly and specify that the runtime should load the ultimate fallback resources from a satellite assembly that corresponds to a specific culture. 若要控制後援程序,請使用 NeutralResourcesLanguageAttribute.NeutralResourcesLanguageAttribute(String, UltimateResourceFallbackLocation) 建構函式,並提供 UltimateResourceFallbackLocation 參數的值,而此參數指定 Resource Manager 應該從主要組件還是附屬組件擷取後援資源。To control the fallback process, you use the NeutralResourcesLanguageAttribute.NeutralResourcesLanguageAttribute(String, UltimateResourceFallbackLocation) constructor and supply a value for the UltimateResourceFallbackLocation parameter that specifies whether Resource Manager should extract the fallback resources from the main assembly or from a satellite assembly.

下列 .NET Framework 範例會使用 NeutralResourcesLanguageAttribute 屬性,將應用程式的後援資源儲存在法文 (fr) 語言的附屬組件中。The following .NET Framework example uses the NeutralResourcesLanguageAttribute attribute to store an application's fallback resources in a satellite assembly for the French (fr) language. 此範例有兩個文字型資源檔案定義名為 Greeting 的單一字串資源。The example has two text-based resource files that define a single string resource named Greeting. 首先,resources.fr.txt 包含法文語言資源。The first, resources.fr.txt, contains a French language resource.

Greeting=Bon jour!

其次,resources,ru.txt 包含俄文語言資源。The second, resources,ru.txt, contains a Russian language resource.

Greeting=Добрый день

從命令列執行資源檔產生器 (Resgen.exe),以將這兩個檔案編譯成 .resources 檔案。These two files are compiled to .resources files by running the resource file generator (Resgen.exe) from the command line. 法文語言資源的命令為:For the French language resource, the command is:

resgen.exe resources.fr.txtresgen.exe resources.fr.txt

俄文語言資源的命令為:For the Russian language resource, the command is:

resgen.exe resources.ru.txtresgen.exe resources.ru.txt

從法文語言資源的命令列執行組件連結器 (Al.exe) 以將 .resources 檔案內嵌到動態連結程式庫,如下所示:The .resources files are embedded into dynamic link libraries by running assembly linker (Al.exe) from the command line for the French language resource as follows:

al /t:lib /embed:resources.fr.resources /culture:fr /out:fr\Example1.resources.dllal /t:lib /embed:resources.fr.resources /culture:fr /out:fr\Example1.resources.dll

而俄文語言資源如下所示:and for the Russian language resource as follows:

al /t:lib /embed:resources.ru.resources /culture:ru /out:ru\Example1.resources.dllal /t:lib /embed:resources.ru.resources /culture:ru /out:ru\Example1.resources.dll

應用程式原始程式碼位在名為 Example1.cs 或 Example1.vb 的檔案中。The application source code resides in a file named Example1.cs or Example1.vb. 它會包括 NeutralResourcesLanguageAttribute 屬性,指出預設應用程式資源是在 fr 子目錄中。It includes the NeutralResourcesLanguageAttribute attribute to indicate that the default application resource is in the fr subdirectory. 它會執行個體化 Resource Manager、擷取 Greeting 資源的值,並將它顯示到主控台。It instantiates the Resource Manager, retrieves the value of the Greeting resource, and displays it to the console.

using System;
using System.Reflection;
using System.Resources;

[assembly:NeutralResourcesLanguage("fr", UltimateResourceFallbackLocation.Satellite)]

public class Example
{
   public static void Main()
   {
      ResourceManager rm = new ResourceManager("resources", 
                                               typeof(Example).Assembly);
      string greeting = rm.GetString("Greeting");
      Console.WriteLine(greeting); 
   }
}
Imports System.Reflection
Imports System.Resources

<Assembly:NeutralResourcesLanguage("fr", UltimateResourceFallbackLocation.Satellite)>
Module Example
   Public Sub Main()
      Dim rm As New ResourceManager("resources", GetType(Example).Assembly)
      Dim greeting As String = rm.GetString("Greeting")
      Console.WriteLine(greeting) 
   End Sub
End Module

您接著可以從命令列編譯 C# 原始程式碼,如下所示:You can then compile C# source code from the command line as follows:

csc Example1.cs

Visual Basic 編譯器的命令十分類似:The command for the Visual Basic compiler is very similar:

vbc Example1.vb

因為主要組件中未內嵌任何資源,所以您不需要使用 /resource 切換參數進行編譯。Because there are no resources embedded in the main assembly, you do not have to compile by using the /resource switch.

當您從語言非俄文的系統執行此範例時,會顯示下列輸出:When you run the example from a system whose language is anything other than Russian, it displays the following output:

Bon jour!

建議的封裝替代方式Suggested Packaging Alternative

時間或預算限制可能會讓您無法針對應用程式所支援的每個子文化特性建立一組資源。Time or budget constraints might prevent you from creating a set of resources for every subculture that your application supports. 相反地,您可以建立所有相關子文化特性可使用之父文化特性的單一附屬組件。Instead, you can create a single satellite assembly for a parent culture that all related subcultures can use. 例如,您可以提供要求地區特定英文資源之使用者所擷取的單一英文附屬組件 (en),以及要求地區特定德文資源之使用者的單一德文附屬組件 (de)。For example, you can provide a single English satellite assembly (en) that is retrieved by users who request region-specific English resources, and a single German satellite assembly (de) for users who request region-specific German resources. 例如,德國德文 (de-DE)、奧地利德文 (de-AT) 和瑞士德文 (de-CH) 的要求會改為使用德文附屬組件 (de)。For example, requests for German as spoken in Germany (de-DE), Austria (de-AT), and Switzerland (de-CH) would fall back to the German satellite assembly (de). 預設資源是最終後援,因此應該是大部分應用程式使用者所要求的資源,請小心選擇這些資源。The default resources are the final fallback and therefore should be the resources that will be requested by the majority of your application's users, so choose these resources carefully. 這種方式所部署的資源具有較少的特定文化特性,但可以大幅減少您應用程式的當地語系化成本。This approach deploys resources that are less culturally specific, but can significantly reduce your application's localization costs.

另請參閱See also