Создание вспомогательных сборок для приложений для настольных системCreating Satellite Assemblies for Desktop Apps

Файлы ресурсов играют важную роль в локализованных приложениях.Resource files play a central role in localized applications. Они позволяют приложению использовать для отображения строк, изображений и других данных текущие региональные настройки пользователя, а также предоставлять альтернативные данных при отсутствии необходимых ресурсов для языка и региональных параметров этого пользователя.They enable an application to display strings, images, and other data in the user's own language and culture, and to provide alternate data if resources for the user's own language or culture are unavailable. Для установления местонахождения локализованных ресурсов и их получения в платформе .NET Framework используется модель "звезда".The .NET Framework uses a hub-and-spoke model to locate and retrieve localized resources. Центром в этой модели является основная сборка, которая содержит не локализуемый исполняемый код и ресурсы для единственного языка и региональных параметров, называемых нейтральными языком и региональными параметрами, или региональными настройками по умолчанию.The hub is the main assembly that contains the non-localizable executable code and the resources for a single culture, which is called the neutral or default culture. Язык и региональные параметры по умолчанию являются резервными параметрами; они используются, когда не доступны локализованные ресурсы.The default culture is the fallback culture for the application; it is used when no localized resources are available. Атрибут NeutralResourcesLanguageAttribute используется для указания языка и региональных параметров по умолчанию для приложения.You use the NeutralResourcesLanguageAttribute attribute to designate the culture of the application's default culture. Каждый луч звезды ведет к вспомогательной сборке, которая содержит ресурсы для одного локализованного языка и региональных параметров, но не содержит кода.Each spoke connects to a satellite assembly that contains the resources for a single localized culture but does not contain any code. Так как вспомогательные сборки не являются частью главной сборки, ресурсы, относящиеся к конкретному языку и региональным параметрам, можно легко заменять или обновлять, не заменяя главную сборку приложения.Because the satellite assemblies are not part of the main assembly, you can easily update or replace resources that correspond to a specific culture without replacing the main assembly for the application.

Примечание

Ресурсы языка и региональных параметров по умолчанию приложения также могут храниться и во вспомогательной сборке.The resources of an application's default culture can also be stored in a satellite assembly. Для этого нужно назначить атрибуту NeutralResourcesLanguageAttribute значение UltimateResourceFallbackLocation.Satellite.To do this, you assign the NeutralResourcesLanguageAttribute attribute a value of UltimateResourceFallbackLocation.Satellite.

Имя и расположение вспомогательной сборкиSatellite Assembly Name and Location

Для реализации модели "звезда" необходимо разместить ресурсы в определенных местах так, чтобы их можно было легко найти и использовать.The hub-and-spoke model requires that you place resources in specific locations so that they can be easily located and used. Если ресурсы именованы неверно или компилируются с ошибками, или неверно расположены, то среда CLR не сможет их найти и будет вместо них использовать ресурсы языка и региональных параметров по умолчанию.If you do not compile and name resources as expected, or if you do not place them in the correct locations, the common language runtime will not be able to locate them and will use the resources of the default culture instead. Диспетчер ресурсов .NET Framework, представленный объектом ResourceManager, используется для автоматического доступа к локализованным ресурсам.The .NET Framework Resource Manager, represented by a ResourceManager object, is used to automatically access localized resources. Для диспетчера ресурсов необходимо выполнить следующие условия.The Resource Manager requires the following:

  • Одна вспомогательная сборка должна включать все ресурсы для определенных языка и региональных параметров.A single satellite assembly must include all the resources for a particular culture. Иначе говоря, необходимо скомпилировать несколько TXT- или RESX-файлов в двоичный RESOURCES-файл.In other words, you should compile multiple .txt or .resx files into a single binary .resources file.

  • Для каждого локализованного языка и региональных параметров, где содержатся ресурсы для языка и региональных параметров, должен быть выделен отдельный вложенный каталог.There must be a separate subdirectory in the application directory for each localized culture that stores that culture's resources. Имя вложенного каталога должно совпадать с именем языка и региональных параметров.The subdirectory name must be the same as the culture name. Кроме того, можно хранить вспомогательные сборки в глобальном кэше сборок.Alternately, you can store your satellite assemblies in the global assembly cache. В этом случае компонент данных языка и региональных параметров строгого имени сборки должен указывать на свой язык и региональные параметры.In this case, the culture information component of the assembly's strong name must indicate its culture. (См.раздел Установка вспомогательных сборок в глобальном кэше сборок далее в этой статье.)(See the Installing Satellite Assemblies in the Global Assembly Cache section later in this topic.)

    Примечание

    Если приложение содержит ресурсы для дочерних языков и региональных параметров, поместите каждый дочерний язык и региональные параметры в отдельный вложенный подкаталог в каталоге приложения.If your application includes resources for subcultures, place each subculture in a separate subdirectory under the application directory. Не следует размещать дочерние языки и региональных параметры во вложенных каталогах каталога основного языка и региональных параметров.Do not place subcultures in subdirectories under their main culture's directory.

  • Вспомогательная сборка должна иметь то же имя, что и приложение, а также должна использовать расширение имени файла ".resources.dll".The satellite assembly must have the same name as the application, and must use the file name extension ".resources.dll". Например, если приложение называется Example.exe, то именем каждой вспомогательной сборки должно быть Example.resources.dll.For example, if an application is named Example.exe, the name of each satellite assembly should be Example.resources.dll. Обратите внимание, что имя вспомогательной сборки не указывает на язык и региональные параметры ее файла ресурсов.Note that the satellite assembly name does not indicate the culture of its resource files. Но вспомогательная сборка отображается в каталоге, который указывает на определенные язык и региональные параметры.However, the satellite assembly appears in a directory that does specify the culture.

  • Сведения о языке и региональных параметрах вспомогательной сборки должны быть включены в метаданных сборки.Information about the culture of the satellite assembly must be included in the assembly's metadata. Чтобы сохранить имя языка и региональных параметров в метаданных вспомогательной сборки, необходимо задать параметр /culture при использовании компоновщика сборок для внедрения ресурсов во вспомогательную сборку.To store the culture name in the satellite assembly's metadata, you specify the /culture option when you use Assembly Linker to embed resources in the satellite assembly.

На следующем рисунке показан пример структуры каталогов и приведены требования к размещению файлов для приложений, которые не устанавливаются в глобальный кэш сборок.The following illustration shows a sample directory structure and location requirements for applications that you are not installing in the global assembly cache. Элементы с расширениями имен .txt и .resources не будут включаться в окончательный пакет приложения.The items with .txt and .resources extensions will not ship with the final application. Они представляют собой промежуточные файлы ресурсов, используемые для создания итоговых вспомогательных сборок ресурсов.These are the intermediate resource files used to create the final satellite resource assemblies. В этом примере можно было бы заменить RESX- файлы на TXT-файлы.In this example, you could substitute .resx files for the .txt files. Дополнительные сведения см. в статье Упаковка и развертывание ресурсов.For more information, see Packaging and Deploying Resources.

На следующем изображении показан каталог вспомогательных сборок:The following image shows the satellite assembly directory:

Каталог вспомогательных сборок с подкаталогами для языков и региональных параметров.

компиляция вспомогательных сборокCompiling Satellite Assemblies

Используйте генератор файлов ресурсов (Resgen.exe) для компиляции текстовых файлов или файлов XML (RESX), содержащих ресурсы, в двоичные RESOURCES-файлы.You use Resource File Generator (Resgen.exe) to compile text files or XML (.resx) files that contain resources to binary .resources files. Для компиляции RESOURCES-файлов во вспомогательные сборки используется компоновщик сборок (Al.exe).You then use Assembly Linker (Al.exe) to compile .resources files into satellite assemblies. Программа Al.exe создает сборку из указанных RESOURCES-файлов.Al.exe creates an assembly from the .resources files that you specify. Вспомогательные сборки могут содержать только ресурсы; они не могут содержать исполняемый код.Satellite assemblies can contain only resources; they cannot contain any executable code.

Для создания вспомогательной сборки со строгим именем для приложения Example из файла ресурсов региональных настроек Германии strings.de.resources служит следующая команда Al.exe.The following Al.exe command creates a satellite assembly for the application Example from the German resources file strings.de.resources.

al -target:lib -embed:strings.de.resources -culture:de -out:Example.resources.dll  

Для создания вспомогательной сборки для приложения Example из файла strings.de.resources служит следующая команда Al.exe.The following Al.exe command also creates a satellite assembly for the application Example from the file strings.de.resources. Параметр /template служит для наследования вспомогательной сборкой всех метаданных сборки, за исключением сведений о языке и региональных параметров ее родительской сборки (Example.dll).The /template option causes the satellite assembly to inherit all assembly metadata except for its culture information from the parent assembly (Example.dll).

al -target:lib -embed:strings.de.resources -culture:de -out:Example.resources.dll -template:Example.dll  

В приведенной ниже таблице более подробно описываются параметры Al.exe, используемые в этих командах.The following table describes the Al.exe options used in these commands in more detail.

ПараметрOption ОписаниеDescription
-target: lib-target: lib Указывает, что вспомогательная сборка компилируется в файл библиотеки (DLL).Specifies that your satellite assembly is compiled to a library (.dll) file. Так как вспомогательная сборка не содержит исполняемого кода и не является основной сборкой приложения, ее необходимо хранить в виде библиотеки DLL.Because a satellite assembly does not contain executable code and is not an application's main assembly, you must save satellite assemblies as DLLs.
-embed: strings.de.resources-embed: strings.de.resources Указывает для программы Al.exe имя файла ресурсов, включенного при компиляции сборки.Specifies the name of the resource file to embed when Al.exe compiles the assembly. Во вспомогательной сборке можно включить несколько файлов ресурсов, но если следовать модели "звезда", то необходимо компилировать отдельную вспомогательную сборку для каждого языка и региональных параметров.You can embed multiple .resources files in a satellite assembly, but if you are following the hub-and-spoke model, you must compile one satellite assembly for each culture. Впрочем, можно создавать и отдельные RESOURCES-файлы для строк и объектов.However, you can create separate .resources files for strings and objects.
-culture: de-culture: de Задает язык и региональные параметры компилируемого ресурса.Specifies the culture of the resource to compile. Среда CLR использует эти сведения в процессе поиска ресурсов, относящихся к указанному языку и региональным параметрам.The common language runtime uses this information when it searches for the resources for a specified culture. Если этот параметр не задан, программа Al.exe скомпилирует ресурс, но среда выполнения не сможет его найти по запросу пользователя.If you omit this option, Al.exe will still compile the resource, but the runtime will not be able to find it when a user requests it.
-out: Example.resources.dll-out: Example.resources.dll Задает имя выходного файла.Specifies the name of the output file. Имя должно соответствовать шаблону baseName.resources.extension, где baseName — имя основной сборки, а extension — допустимое расширение имени файла (например, DLL).The name must follow the naming standard baseName.resources.extension, where baseName is the name of the main assembly and extension is a valid file name extension (such as .dll). Обратите внимание, что среда выполнения не может определить язык и региональные параметры вспомогательной сборки, основываясь на имени выходного файла; необходимо использовать параметр /culture, чтобы указать их.Note that the runtime is not able to determine the culture of a satellite assembly based on its output file name; you must use the /culture option to specify it.
-template: Example.dll-template: Example.dll Задает сборку, от которой наследуют все метаданные сборки, кроме поля языка и региональных параметров.Specifies an assembly from which the satellite assembly will inherit all assembly metadata except the culture field. Этот параметр влияет на вспомогательные сборки только в том случае, если указана сборка, у которой есть строгое имя.This option affects satellite assemblies only if you specify an assembly that has a strong name.

Полный список параметров, доступных в программе Al.exe см. в разделе Компоновщик сборок (Al.exe).For a complete list of options available with Al.exe, see Assembly Linker (Al.exe).

Вспомогательные сборки: ПримерSatellite Assemblies: An Example

Ниже приведен простой пример "Hello world", который отображает окно сообщения, содержащее локализованное приветствие.The following is a simple "Hello world" example that displays a message box containing a localized greeting. Пример включает ресурсы для английского (США), французского (Франция) и русского (Россия) языка; в качестве нейтрального языка выступает английский.The example includes resources for the English (United States), French (France), and Russian (Russia) cultures, and its fallback culture is English. Для создания этого примера выполните следующие действия.To create the example, do the following:

  1. Создайте файл ресурсов с именем Greeting.resx и Greeting.txt, который будет содержать ресурсы для языка и региональных параметров по умолчанию.Create a resource file named Greeting.resx or Greeting.txt to contain the resource for the default culture. Сохраните одну строку с именем HelloString и значением "Hello world!"Store a single string named HelloString whose value is "Hello world!" в этом файле.in this file.

  2. Чтобы указать, что язык и региональные параметры по умолчанию для приложения — английский (en), необходимо добавить в файл AssemblyInfo приложения или в главный файл исходного кода, которые будут скомпилированы в основную сборку приложения, следующий атрибут System.Resources.NeutralResourcesLanguageAttribute.To indicate that English (en) is the application's default culture, add the following System.Resources.NeutralResourcesLanguageAttribute attribute to the application's AssemblyInfo file or to the main source code file that will be compiled into the application's main assembly.

    [assembly: NeutralResourcesLanguageAttribute("en")]
    
    <Assembly: NeutralResourcesLanguageAttribute("en")>
    
  3. Добавьте поддержку дополнительных языков и региональных параметров (en-US, fr-FR и ru-RU) в приложение следующим образом.Add support for additional cultures (en-US, fr-FR, and ru-RU) to the application as follows:

    • Для поддержки региональных настроек "en-US" (английского языка, США) создайте файл ресурсов с именем Greeting.en-US.resx или Greeting.en-US.txt и сохраните в нем одну строку с именем HelloString и значением "Hi world!".To support the en-US or English (United States) culture, create a resource file named Greeting.en-US.resx or Greeting.en-US.txt, and store in it a single string named HelloString whose value is "Hi world!"

    • Для поддержки языка и региональных параметров "fr-FR" (французского языка, Франция) создайте файл ресурсов с именем Greeting.fr-FR.resx или Greeting.fr-FR.txt и сохраните в нем одну строку с именем HelloString и значением "Salut tout le monde!".To support the fr-FR or French (France) culture, create a resource file named Greeting.fr-FR.resx or Greeting.fr-FR.txt, and store in it a single string named HelloString whose value is "Salut tout le monde!"

    • Для поддержки региональных настроек "ru-RU" (русского языка, Россия) создайте файл ресурсов с именем Greeting.ru-RU.resx или Greeting.ru-RU.txt и сохраните в нем одну строку с именем HelloString и значением "Всем привет!".To support the ru-RU or Russian (Russia) culture, create a resource file named Greeting.ru-RU.resx or Greeting.ru-RU.txt, and store in it a single string named HelloString whose value is "Всем привет!"

  4. Используйте Resgen.exe для компиляции каждого текстового файла или файла ресурсов XML в двоичный RESOURCES-файл.Use Resgen.exe to compile each text or XML resource file to a binary .resources file. Выходными данными будет набор файлов, имеющий то же корневое имя файла как и RESX- и TXT-файлы, но с расширением RESOURCES.The output is a set of files that have the same root file name as the .resx or .txt files, but a .resources extension. При создании примера с помощью Visual Studio процесс компиляции отрегулируется автоматически.If you create the example with Visual Studio, the compilation process is handled automatically. Если используется среда, отличная от Visual Studio, выполните следующие команды для компиляции RESX-файлов в RESOURCES-файлы.If you aren't using Visual Studio, run the following commands to compile the .resx files into .resources files:

    resgen Greeting.resx  
    resgen Greeting.en-us.resx  
    resgen Greeting.fr-FR.resx  
    resgen Greeting.ru-RU.resx  
    

    Если ресурсы располагаются в текстовых файлах вместо XML-файлов, замените расширение RESX на TXT.If your resources are in text files instead of XML files, replace the .resx extension with .txt.

  5. Скомпилируйте следующий исходный код и ресурсы для языка и региональных параметров по умолчанию в основную сборку приложения:Compile the following source code along with the resources for the default culture into the application's main assembly:

    Важно!

    При использовании командной строки, а не Visual Studio, для создания примера, необходимо изменить вызов конструктора класса ResourceManager на следующий: ResourceManager rm = new ResourceManager("Greetings", typeof(Example).Assembly);If you are using the command line rather than Visual Studio to create the example, you should modify the call to the ResourceManager class constructor to the following: ResourceManager rm = new ResourceManager("Greetings", typeof(Example).Assembly);

    using System;
    using System.Globalization;
    using System.Reflection;
    using System.Resources;
    using System.Threading;
    using System.Windows.Forms;
    
    class Example
    {
       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;
    
          try {
             CultureInfo newCulture = new CultureInfo(cultures[cultureNdx]);
             Thread.CurrentThread.CurrentCulture = newCulture;
             Thread.CurrentThread.CurrentUICulture = newCulture;
             ResourceManager rm = new ResourceManager("Example.Greetings", 
                                                      typeof(Example).Assembly); 
             string greeting = String.Format("The current culture is {0}.\n{1}",
                                             Thread.CurrentThread.CurrentUICulture.Name,
                                             rm.GetString("HelloString"));
    
             MessageBox.Show(greeting);
          }
          catch (CultureNotFoundException e) {
             Console.WriteLine("Unable to instantiate culture {0}", e.InvalidCultureName);
          }
          finally {
             Thread.CurrentThread.CurrentCulture = originalCulture;
             Thread.CurrentThread.CurrentUICulture = originalCulture;
          }
       }
    }
    
    Imports System.Globalization
    Imports System.Resources
    Imports System.Threading
    
    Module Module1
    
       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
    
          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, My.Resources.Greetings.HelloString)
    
             MsgBox(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
    

    Если приложение называется Example и компилируется из командной строки, то команда для компилятора C# имеет вид:If the application is named Example and you are compiling from the command line, the command for the C# compiler is:

    csc Example.cs -res:Greeting.resources  
    

    Соответствующая команда для компилятора Visual Basic имеет вид:The corresponding Visual Basic compiler command is:

    vbc Example.vb -res:Greeting.resources  
    
  6. Создайте вложенный каталог в каталоге основного приложения для каждого локализованного языка и региональных параметров, поддерживаемых приложением.Create a subdirectory in the main application directory for each localized culture supported by the application. Необходимо создать вложенные каталоги en-US, fr-FR и ru-RU.You should create an en-US, an fr-FR, and an ru-RU subdirectory. Visual Studio автоматически создает эти вложенные каталоги в процессе компиляции.Visual Studio creates these subdirectories automatically as part of the compilation process.

  7. Внедрите отдельные RESOURCES-файлы для определенного языка и региональных параметров во вспомогательные сборки и сохраните их в соответствующем каталоге.Embed the individual culture-specific .resources files into satellite assemblies and save them to the appropriate directory. Для этого можно воспользоваться командой для каждого RESOURCES-файла:The command to do this for each .resources file is:

    al -target:lib -embed:Greeting.culture.resources -culture:culture -out:culture\Example.resources.dll  
    

    где culture — имя языка и региональных параметров, ресурсы которых содержит вспомогательная сборка.where culture is the name of the culture whose resources the satellite assembly contains. Visual Studio автоматически обрабатывает этот процесс.Visual Studio handles this process automatically.

Затем можно запустить пример.You can then run the example. Он будет случайным образом выбирать один из поддерживаемых языков и региональных параметров и отображать локализованное приветствие.It will randomly make one of the supported cultures the current culture and display a localized greeting.

Установка вспомогательных сборок в глобальный кэш сборокInstalling Satellite Assemblies in the Global Assembly Cache

Вместо установки сборок во вложенном каталоге локального приложения их можно установить в глобальный кэш сборок.Instead of installing assemblies in a local application subdirectory, you can install them in the global assembly cache. Это особенно полезно, если библиотеки классов и сборки ресурсов библиотеки классов используются несколькими приложениями.This is particularly useful if you have class libraries and class library resource assemblies that are used by multiple applications.

Все сборки, устанавливаемые в глобальный кэш сборок, должны иметь строгие имена.Installing assemblies in the global assembly cache requires that they have strong names. Сборки со строгими именами должны быть подписаны допустимой парой открытого и закрытого ключей.Strong-named assemblies are signed with a valid public/private key pair. Они содержат сведения о версии, с помощью которых среда выполнения определяет, какую сборку следует использовать для удовлетворения запроса привязки.They contain version information that the runtime uses to determine which assembly to use to satisfy a binding request. Дополнительные сведения о строгих именах и управлении версиями см. в разделе Управление версиями сборки.For more information about strong names and versioning, see Assembly Versioning. Дополнительные сведения о строгих именах см. в разделе Сборки со строгими именами.For more information about strong names, see Strong-Named Assemblies.

Разработчик приложения, как правило, не имеет доступа к итоговой паре открытого и закрытого ключей.When you are developing an application, it is unlikely that you will have access to the final public/private key pair. Чтобы установить вспомогательную сборку в глобальный кэш сборок и обеспечить ее работоспособность, можно воспользоваться средством отложенной подписи.In order to install a satellite assembly in the global assembly cache and ensure that it works as expected, you can use a technique called delayed signing. Если подписание сборки откладывается, во время построения в файле резервируется место для подписи строгим именем.When you delay sign an assembly, at build time you reserve space in the file for the strong name signature. Фактически подписание откладывается до того момента, когда становится доступной итоговая пара открытого и закрытого ключей.The actual signing is delayed until later, when the final public/private key pair is available. Дополнительные сведения об отложенной подписи см. в разделе Отложенная подпись сборки.For more information about delayed signing, see Delay Signing an Assembly.

Получение открытого ключаObtaining the Public Key

Чтобы отложить подпись сборки, необходимо иметь доступ к открытому ключу.To delay sign an assembly, you must have access to the public key. Открытый ключ можно либо получить в организации, которая будет заниматься окончательным подписанием, либо создать самостоятельно с помощью программы строгих имен (Sn.exe).You can either obtain the real public key from the organization in your company that will do the eventual signing, or create a public key by using the Strong Name Tool (Sn.exe).

Следующая команда Sn.exe создает тестовые пары открытого и закрытого ключей.The following Sn.exe command creates a test public/private key pair. Параметр –k указывает, что необходимо создать новую пару ключей и сохранить ее в заданном файле с именем TestKeyPair.snk.The –k option specifies that Sn.exe should create a new key pair and save it in a file named TestKeyPair.snk.

sn –k TestKeyPair.snk   

Открытый ключ можно извлечь из файла, содержащего тестовую пару ключей.You can extract the public key from the file that contains the test key pair. Следующая команда извлекает открытый ключ из TestKeyPair.snk и сохраняет его в PublicKey.snk:The following command extracts the public key from TestKeyPair.snk and saves it in PublicKey.snk:

sn –p TestKeyPair.snk PublicKey.snk  

Отложенная подпись сборкиDelay Signing an Assembly

После получения или создания открытого ключа, можно скомпилировать сборку и указать отложенную подпись, используя компоновщик сборок (Al.exe).After you obtain or create the public key, you use the Assembly Linker (Al.exe) to compile the assembly and specify delayed signing.

Для создания вспомогательной сборки со строгим именем для приложения StringLibrary из файла strings.ja.resources служит следующая команда Al.exe:The following Al.exe command creates a strong-named satellite assembly for the application StringLibrary from the strings.ja.resources file:

al -target:lib -embed:strings.ja.resources -culture:ja -out:StringLibrary.resources.dll -delay+ -keyfile:PublicKey.snk  

Параметр -delay+ указывает, что компоновщик сборок должен отложить подпись сборки.The -delay+ option specifies that the Assembly Linker should delay sign the assembly. Параметр -keyfile задает имя файла ключа, в котором содержится открытый ключ, применяемый для откладывания подписи сборки.The -keyfile option specifies the name of the key file that contains the public key to use to delay sign the assembly.

Повторная подпись сборкиRe-signing an Assembly

Прежде чем развертывать приложение, можно заново подписать вспомогательную сборку, подписание которой было отложено, реальной парой ключей.Before you deploy your application, you must re-sign the delay signed satellite assembly with the real key pair. Это можно сделать с помощью программы Sn.exe.You can do this by using Sn.exe.

Для подписи StringLibrary.resources.dll парой ключей, хранящихся в файле RealKeyPair.snk, используется следующая команда Sn.exe.The following Sn.exe command signs StringLibrary.resources.dll with the key pair stored in the file RealKeyPair.snk. Параметр –R указывает, что нужно заново подписать сборку с отложенной подписью или сборку, которая должна быть подписана заново.The –R option specifies that a previously signed or delay signed assembly is to be re-signed.

sn –R StringLibrary.resources.dll RealKeyPair.snk   

Установка вспомогательной сборки в глобальный кэш сборокInstalling a Satellite Assembly in the Global Assembly Cache

Когда среда выполнения ищет ресурсы в процессе перехода на резервные средства, в первую очередь она ищет глобальный кэш сборок.When the runtime searches for resources in the resource fallback process, it looks in the global assembly cache first. (Дополнительные сведения см. в подразделе "Процесс использования резервных ресурсов" раздела Упаковка и развертывание ресурсов.) Как только вспомогательная сборка подписана строгим именем, ее можно установить в глобальном кэше сборок с помощью программы глобального кэша сборок (Gacutil.exe).(For more information, see the "Resource Fallback Process" section of the Packaging and Deploying Resources topic.) As soon as a satellite assembly is signed with a strong name, it can be installed in the global assembly cache by using the Global Assembly Cache Tool (Gacutil.exe).

Следующая команда Gacutil.exe устанавливает StringLibrary.resources.dll в глобальный кэш сборок:The following Gacutil.exe command installs StringLibrary.resources.dll in the global assembly cache:

gacutil -i:StringLibrary.resources.dll  

Параметр /I указывает программе Gacutil.exe, что данную сборку требуется установить в глобальный кэш сборок.The /i option specifies that Gacutil.exe should install the specified assembly into the global assembly cache. После того, как вспомогательная сборка установлена в кэше, ресурсы, которые она содержит, становятся доступны для всех приложений, которые предназначены для использования вспомогательной сборки.After the satellite assembly is installed in the cache, the resources it contains become available to all applications that are designed to use the satellite assembly.

Ресурсы в глобальном кэше сборок: ПримерResources in the Global Assembly Cache: An Example

В следующем примере используется метод библиотеки классов .NET Framework для извлечения и возврата локализованных приветствий из файла ресурсов.The following example uses a method in a .NET Framework class library to extract and return a localized greeting from a resource file. Библиотека и ее ресурсы зарегистрированы в глобальном кэше сборок.The library and its resources are registered in the global assembly cache. Пример включает ресурсы для английского (США), французского (Франция), русского (Россия) и английского языков и региональных параметров.The example includes resources for the English (United States), French (France), Russian (Russia), and English cultures. Английский является языком по умолчанию; ресурсы для него хранятся в основной сборке.English is the default culture; its resources are stored in the main assembly. Пример изначально задерживает подпись библиотеки и вспомогательных сборок открытым ключом, а затем заново подписывает их парой открытого и закрытого ключей.The example initially delay signs the library and its satellite assemblies with a public key, then re-signs them with a public/private key pair. Для создания этого примера выполните следующие действия.To create the example, do the following:

  1. Если вы не используете Visual Studio, используйте следующую команду средства строгих имен (Sn.exe), чтобы создать пару открытого и закрытого ключей с именем ResKey.snk:If you are not using Visual Studio, use the following Strong Name Tool (Sn.exe) command to create a public/private key pair named ResKey.snk:

    sn –k ResKey.snk  
    

    Если вы используете Visual Studio, воспользуйтесь вкладкой Подпись диалогового окна Свойства проекта, чтобы создать ключ.If you are using Visual Studio, use the Signing tab of the project Properties dialog box to generate the key file.

  2. Используйте следующую команду средства строгих имен (Sn.exe), чтобы создать файл открытого ключа с именем PublicKey.snk:Use the following Strong Name Tool (Sn.exe) command to create a public key file named PublicKey.snk:

    sn –p ResKey.snk PublicKey.snk  
    
  3. Создайте файл ресурсов с именем Strings.resx, который будет содержать ресурсы для языка и региональных параметров по умолчанию.Create a resource file named Strings.resx to contain the resource for the default culture. Сохраните одну строку с именем Greeting и значением "How do you do?"Store a single string named Greeting whose value is "How do you do?" в этом файле.in that file.

  4. Чтобы указать, что язык и региональные параметры по умолчанию для приложения — "en", необходимо добавить в файл AssemblyInfo приложения или в главный файл исходного кода, которые будут скомпилированы в основную сборку приложения, следующий атрибут System.Resources.NeutralResourcesLanguageAttribute:To indicate that "en" is the application's default culture, add the following System.Resources.NeutralResourcesLanguageAttribute attribute to the application's AssemblyInfo file or to the main source code file that will be compiled into the application's main assembly:

    [assembly:NeutralResourcesLanguageAttribute("en")]
    
    <Assembly:NeutralResourcesLanguageAttribute("en")>
    
  5. Добавьте поддержку дополнительных языков и региональных параметров (en-US, fr-FR и ru-RU) в приложение следующим образом.Add support for additional cultures (the en-US, fr-FR, and ru-RU cultures) to the application as follows:

    • Для поддержки региональных настроек "en-US" (английского языка, США) создайте файл ресурсов с именем Strings.en-US.resx или Strings.en-US.txt, и сохраните в нем одну строку с именем Greeting и значением "Hello!".To support the "en-US" or English (United States) culture, create a resource file named Strings.en-US.resx or Strings.en-US.txt, and store in it a single string named Greeting whose value is "Hello!".

    • Для поддержки языка и региональных параметров "fr-FR" (французского языка, Франция) создайте файл ресурсов с именем Strings.fr-FR.resx или Strings.fr-FR.txt и сохраните в нем одну строку с именем Greeting и значением "Bon jour!"To support the "fr-FR" or French (France) culture, create a resource file named Strings.fr-FR.resx or Strings.fr-FR.txt and store in it a single string named Greeting whose value is "Bon jour!"

    • Для поддержки языка и региональных параметров "ru-RU" (русского языка, Россия) создайте файл ресурсов с именем Strings.ru-RU.resx или Strings.ru-RU.txt и сохраните в нем одну строку с именем Greeting и значением — "Привет!".To support the "ru-RU" or Russian (Russia) culture, create a resource file named Strings.ru-RU.resx or Strings.ru-RU.txt and store in it a single string named Greeting whose value is "Привет!"

  6. Используйте Resgen.exe для компиляции каждого текстового файла или файла ресурсов XML в двоичный RESOURCES-файл.Use Resgen.exe to compile each text or XML resource file to a binary .resources file. Выходными данными будет набор файлов, имеющий то же корневое имя файла как и RESX- и TXT-файлы, но с расширением RESOURCES.The output is a set of files that have the same root file name as the .resx or .txt files, but a .resources extension. При создании примера с помощью Visual Studio процесс компиляции отрегулируется автоматически.If you create the example with Visual Studio, the compilation process is handled automatically. Если используется среда, отличная от Visual Studio, выполните следующую команду для компиляции RESX-файлов в RESOURCES-файлы:If you aren't using Visual Studio, run the following command to compile the .resx files into .resources files:

    resgen filename  
    

    где filename — дополнительный путь, имя и расширение RESX-файла или текстового файла.where filename is the optional path, file name, and extension of the .resx or text file.

  7. Скомпилируйте следующий исходный код для StringLibrary.vb или StringLibrary.cs с ресурсами для региональных настроек по умолчанию в библиотеки сборки с отложенной подписью с именем StringLibrary.dll:Compile the following source code for StringLibrary.vb or StringLibrary.cs along with the resources for the default culture into a delay signed library assembly named StringLibrary.dll:

    Важно!

    При использовании командной строки, а не Visual Studio, для создания примера следует изменить вызов конструктора класса ResourceManager на следующий: ResourceManager rm = new ResourceManager("Strings", typeof(Example).Assembly);.If you are using the command line rather than Visual Studio to create the example, you should modify the call to the ResourceManager class constructor to ResourceManager rm = new ResourceManager("Strings", typeof(Example).Assembly);.

    using System;
    using System.Globalization;
    using System.Reflection;
    using System.Resources;
    using System.Threading;
    
    [assembly:NeutralResourcesLanguageAttribute("en")]
    
    public class StringLibrary
    {
       public string GetGreeting()
       {
          ResourceManager rm = new ResourceManager("Strings", 
                               Assembly.GetAssembly(typeof(StringLibrary)));
          string greeting = rm.GetString("Greeting");
          return greeting;
       }
    }
    
    Imports System.Globalization
    Imports System.Reflection
    Imports System.Resources
    Imports System.Threading
    
    <Assembly:NeutralResourcesLanguageAttribute("en")>
    
    Public Class StringLibrary
       Public Function GetGreeting() As String
          Dim rm As New ResourceManager("Strings", _
                                        Assembly.GetAssembly(GetType(StringLibrary)))
          Dim greeting As String = rm.GetString("Greeting")
          Return greeting
       End Function
    End Class
    

    Команда для компилятора C# имеет вид:The command for the C# compiler is:

    csc -t:library -resource:Strings.resources -delaysign+ -keyfile:publickey.snk StringLibrary.cs  
    

    Соответствующая команда для компилятора Visual Basic имеет вид:The corresponding Visual Basic compiler command is:

    vbc -t:library -resource:Strings.resources -delaysign+ -keyfile:publickey.snk StringLibrary.vb  
    
  8. Создайте вложенный каталог в каталоге основного приложения для каждого локализованного языка и региональных параметров, поддерживаемых приложением.Create a subdirectory in the main application directory for each localized culture supported by the application. Необходимо создать вложенные каталоги en-US, fr-FR и ru-RU.You should create an en-US, an fr-FR, and an ru-RU subdirectory. Visual Studio автоматически создает эти вложенные каталоги в процессе компиляции.Visual Studio creates these subdirectories automatically as part of the compilation process. Так как все вспомогательные сборки имеют одно и то же имя файла, вложенные каталоги используются для хранения отдельных вспомогательных сборок для языка и региональных параметров до тех пор, пока они не подписаны парой открытого и закрытого ключей.Because all satellite assemblies have the same file name, the subdirectories are used to store individual culture-specific satellite assemblies until they are signed with a public/private key pair.

  9. Внедрите отдельные RESOURCES-файлы ресурсов для определенного языка и региональных параметров во вспомогательные сборки с отложенной подписью и сохраните в соответствующем каталоге.Embed the individual culture-specific .resources files into delay signed satellite assemblies and save them to the appropriate directory. Для этого можно воспользоваться командой для каждого RESOURCES-файла:The command to do this for each .resources file is:

    al -target:lib -embed:Strings.culture.resources -culture:culture -out:culture\StringLibrary.resources.dll -delay+ -keyfile:publickey.snk  
    

    где culture — название языка и региональных параметров.where culture is the name of a culture. В этом примере имена региональных настроек: en-US, fr-FR, и ru-RU.In this example, the culture names are en-US, fr-FR, and ru-RU.

  10. Подпишите заново StringLibrary.dll с помощью средства строгих имен (Sn.exe) следующим образом:Re-sign StringLibrary.dll by using the Strong Name Tool (Sn.exe) as follows:

    sn –R StringLibrary.dll RealKeyPair.snk  
    
  11. Подпишите заново отдельные вспомогательные сборки.Re-sign the individual satellite assemblies. Для этого используйте средство строгих имен (Sn.exe) для каждой вспомогательной сборки, как показано ниже.To do this, use the Strong Name Tool (Sn.exe) as follows for each satellite assembly:

    sn –R StringLibrary.resources.dll RealKeyPair.snk  
    
  12. Зарегистрируйте StringLibrary.dll и все вспомогательные сборки в глобальном кэше сборок с помощью следующей команды:Register StringLibrary.dll and each of its satellite assemblies in the global assembly cache by using the following command:

    gacutil -i filename  
    

    где filename — имя регистрируемого файла.where filename is the name of the file to register.

  13. Если вы используете Visual Studio, создайте проект консольного приложения с именем Example, добавьте в него следующий исходный код и ссылку на StringLibrary.dll и скомпилируйте.If you are using Visual Studio, create a new Console Application project named Example, add a reference to StringLibrary.dll and the following source code to it, and compile.

    using System;
    using System.Globalization;
    using System.Threading;
    
    public class Example
    {
       public static void Main()
       {
          string[] cultureNames = { "en-GB", "en-US", "fr-FR", "ru-RU" };
          Random rnd = new Random();
          string cultureName = cultureNames[rnd.Next(0, cultureNames.Length)]; 
          Thread.CurrentThread.CurrentUICulture = CultureInfo.CreateSpecificCulture(cultureName);
          Console.WriteLine("The current UI culture is {0}", 
                            Thread.CurrentThread.CurrentUICulture.Name);
          StringLibrary strLib = new StringLibrary();
          string greeting = strLib.GetGreeting();
          Console.WriteLine(greeting);
       }
    }
    
    Imports System.Globalization
    Imports System.Threading
    
    Module Example
       Public Sub Main()
          Dim cultureNames() As String = { "en-GB", "en-US", "fr-FR", "ru-RU" }
          Dim rnd As New Random()
          Dim cultureName As String = cultureNames(rnd.Next(0, cultureNames.Length)) 
          Thread.CurrentThread.CurrentUICulture = CultureInfo.CreateSpecificCulture(cultureName)
          Console.WriteLine("The current UI culture is {0}", 
                            Thread.CurrentThread.CurrentUICulture.Name)
          Dim strLib As New StringLibrary()
          Dim greeting As String = strLib.GetGreeting()
          Console.WriteLine(greeting)
       End Sub
    End Module
    

    Чтобы скомпилировать из командной строки используйте следующую команду для компилятора C#:To compile from the command line, use the following command for the C# compiler:

    csc Example.cs -r:StringLibrary.dll   
    

    Команда компилятора для Visual Basic:The command line for the Visual Basic compiler is:

    vbc Example.vb -r:StringLibrary.dll   
    
  14. Запустите Example.exe.Run Example.exe.

См. такжеSee also