Упаковка и развертывание ресурсов в приложениях .NETPackaging and Deploying Resources in .NET Apps

Приложения зависят от диспетчера ресурсов платформы .NET Framework, представленного классом ResourceManager, для извлечения локализованных ресурсов.Applications rely on the .NET Framework Resource Manager, represented by the ResourceManager class, to retrieve localized resources. Диспетчер ресурсов предполагает, что модель "звезда" используется для упаковки и развертывания ресурсов.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

В процессе упаковки ресурсов приложения им необходимо присваивать имена в соответствии с соглашениями об именовании, которые применяются в среде CLR.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.

Примечание

Существует несколько исключений для имен с двумя буквами, например zh-Hans для китайского языка (упрощенное письмо).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 определить, должна ли вспомогательная сборка быть установлена по требованию.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-GB и en-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, чтобы определить, следует ли устанавливать родительскую вспомогательную сборку по требованию.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. Но можно задать значение Satellite для свойства Location атрибута NeutralResourcesLanguageAttribute, чтобы указать, что конечное расположение резервных ресурсов является вспомогательной сборкой, а не основной сборкой.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. В конечном итоге, если среда выполнения не находит ресурса для стандартного (резервного) языка и региональных параметров, порождается исключение MissingManifestResourceException или MissingSatelliteAssemblyException, указывающее на то, что ресурс не может быть найден.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 FrameworkOptimizing 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 не имеет значение true.That 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 для установки вспомогательных сборок по требованию.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 (например, es или es-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. См. раздел AssemblyLoadContext.See 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.

    Примечание

    Чтобы найти ресурс во вспомогательной сборке, среда выполнения выполняет поиск файла ресурсов по запросу ResourceManager для текущего CultureInfo.Name.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-GB и en-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. Но можно задать значение Satellite для свойства Location, чтобы указать, что конечное расположение резервных ресурсов является вспомогательной, а не основной сборкой.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. В конечном итоге, если среда выполнения не находит файл ресурсов для стандартного (резервного) языка и региональных параметров, порождается исключение MissingManifestResourceException или MissingSatelliteAssemblyException, указывающее на то, что ресурс не может быть найден.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. Если файл ресурсов найден, но запрошенный ресурс отсутствует, то запрос возвращает null.If 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, определяющее, должен ли диспетчер ресурсов извлечь резервные ресурсы из основной сборки или из вспомогательной сборки.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=Добрый день

Эти файлы компилируются в файлы с расширением RESOURCES путем запуска генератора файловых ресурсов (Resgen.exe) из командной строки.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

RESOURCES-файлы внедряются в библиотеки DLL путем запуска из командной строки компоновщика сборок (Al.exe) для ресурса французского языка следующим образом: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. Он создает диспетчер ресурсов, получает значение ресурса 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