Алгоритм загрузки сателлитных сборок

Сателлитные сборки используются для хранения локализованных ресурсов, настроенных для конкретного языка и культуры.

Вспомогательные сборки (satellite assemblies) используют другой алгоритм загрузки по сравнению с общими управляемыми сборками.

Когда загружаются сателлитные сборки?

Спутниковые сборки загружаются при загрузке локализованного ресурса.

Базовый API для загрузки локализованных ресурсов — класс System.Resources.ResourceManager. В конечном итоге именно класс ResourceManager будет вызывать метод GetSatelliteAssembly для каждого свойства CultureInfo.Name.

Интерфейсы API более высокого уровня могут быть абстракцией API нижнего уровня.

Алгоритм

Процесс использования резервных ресурсов .NET Core включает следующие шаги.

1. Определите экземпляр activeAssemblyLoadContext. Во всех случаях экземпляром active считается AssemblyLoadContext исполняемой сборки.

2. Экземпляр active загружает сателлитную сборку для запрошенной культуры в следующем порядке приоритета:

   • Проверьте его кэш.

   • Если active является экземпляром AssemblyLoadContext.Default, запустите логику проверки сборки спутника по умолчанию (ресурса).

   • Вызовите функцию AssemblyLoadContext.Load.

   • Если управляемая сборка, соответствующая спутниковой сборке, была загружена из файла, проверьте каталог управляемой сборки на наличие подкаталога, который соответствует запрошенной CultureInfo.Name (например, es-MX).

     Примечание.

     В ОС Linux и macOS в именах подкаталогов учитывается регистр и они должны либо:

     • Точное совпадение с учетом регистра.
     • быть написанными строчными буквами.

   • Инициировать событие AssemblyLoadContext.Resolving.

   • Инициализация события AppDomain.AssemblyResolve.

3. Если сателлитная сборка загружена:

   • Возникает событие AppDomain.AssemblyLoad.
   • Сборка выполняет поиск запрошенного ресурса. Если среда выполнения обнаружит ресурс в сборке, она использует его. Если ресурс не найден, поиск продолжается.

   Примечание.

   Чтобы найти ресурс в спутниковой сборке, среда выполнения осуществляет поиск файла ресурсов по запросу ResourceManager для текущего CultureInfo.Name. В файле ресурсов выполняется поиск имени запрошенного ресурса. Если любое из них не найдено, ресурс считается отсутствующим.

4. Следующие ResourceManager поиски в родительских культурных сборках происходят через множество потенциальных уровней, повторяя каждый раз шаги 2 и 3.

   Каждая культура имеет только одного родителя, который определяется свойством CultureInfo.Parent.

   Поиск родительских культур прекращается, когда свойство Parent культуры принимает значение CultureInfo.InvariantCulture.

   Для InvariantCulture выполняется не возврат к шагам 2 и 3, а сразу переход к шагу 5.

5. Если ресурс по-прежнему не найден, ResourceManager использует ресурс для культуры по умолчанию (резервной).

   Обычно ресурсы для языка региональных параметров по умолчанию включены в основную сборку приложения. Но вы можете указать значение UltimateResourceFallbackLocation.Satellite для свойства NeutralResourcesLanguageAttribute.Location. Это означает, что конечным расположением ресурсов по умолчанию будет вспомогательная, а не основная сборка.

   Примечание.

   Культура по умолчанию является окончательной резервной. Поэтому мы рекомендуем всегда включать полный набор ресурсов в файл ресурсов по умолчанию. Это помогает избежать появления исключений. Полный набор обеспечивает резервный вариант для всех ресурсов и гарантирует, что у пользователя всегда будет доступ хотя бы к одному ресурсу, даже если он не является культурно-специфическим.

6. Итак:

   • Если среда исполнения не находит файл ресурсов для культуры по умолчанию (резервной культуры), возникает исключение MissingManifestResourceException или MissingSatelliteAssemblyException.
   • если файл ресурсов найден, но запрошенного ресурса в нем нет, то запрос возвращает null.