Создание файлов ресурсов для приложений .NET

Статья
04/11/2023

Ресурсы, такие как строки, изображения или данные объектов, можно включать в файлы ресурсов, чтобы сделать их легко доступными для приложения. В платформе .NET Framework предлагается пять способов создания файлов ресурсов.

Создайте текстовый файл, содержащий строковые ресурсы. Для преобразования текстового файла в двоичный файл ресурсов (RESOURCES-файл) можно использовать генератор файлов ресурсов (resgen.exe). Затем двоичный файл ресурсов можно внедрить в исполняемый файл приложения или библиотеку приложения с помощью компилятора языка или во вспомогательную сборку с помощью компоновщика сборок (Al.exe). Дополнительные сведения см. в разделе Ресурсы в текстовых файлах.
Создайте XML-файл ресурсов (RESX-файл), который содержит строки, изображения или данные объектов. Для преобразования RESX-файла в двоичный файл ресурсов (RESOURCES-файл) можно использовать генератор файлов ресурсов (resgen.exe). Затем двоичный файл ресурсов можно внедрить в исполняемый файл приложения или библиотеку приложения с помощью компилятора языка или во вспомогательную сборку с помощью компоновщика сборок (Al.exe). Дополнительные сведения см. в разделе Ресурсы в RESX-файлах.
Создайте XML-файл ресурсов (RESX-файл) программным способом с помощью типов в пространстве имен System.Resources. Можно создать RESX-файл, перечислить его ресурсы и извлечь конкретные ресурсы по имени. Дополнительные сведения см. в разделе Работа с RESX-файлами программным способом.
Создайте двоичный файл ресурсов (RESOURCES-файл) программным способом. Затем этот файл можно внедрить в исполняемый файл приложения или библиотеку приложения с помощью компилятора языка или во вспомогательную сборку с помощью компоновщика сборок (Al.exe). Дополнительные сведения см. в разделе Ресурсы в RESOURCES-файлах.
Создайте файл ресурсов в Visual Studio и включите этот файл в проект. В Visual Studio есть редактор ресурсов,с помощью которого можно добавлять, удалять и изменять ресурсы. Во время компиляции файл ресурсов автоматически преобразуется в двоичный RESOURCES-файл и внедряется в сборку приложения или вспомогательную сборку. Дополнительные сведения см. в разделе Файлы ресурсов в Visual Studio.

Ресурсы в формате текстовых файлов

В текстовых файлах (TXT или RESTEXT) можно сохранять только строковые ресурсы. Для нестроковых ресурсов используйте RESX-файлы или создавайте их программными средствами. Текстовые файлы, содержащие строковые ресурсы, имеют следующий формат.

# This is an optional comment.
name = value

; This is another optional comment.
name = value

; The following supports conditional compilation if X is defined.
#ifdef X
name1=value1
name2=value2
#endif

# The following supports conditional compilation if Y is undefined.
#if !Y
name1=value1
name2=value2
#endif

Форматы TXT- и RESTEXT-файлов ресурсов идентичны. Расширение файла RESTEX служит для того, чтобы текстовые файлы сразу опознавались как файлы ресурсов на основе текста.

Строковые ресурсы представляются в виде пар имя/значение, где имя — строка, определяющая ресурс, а значение — строка ресурса, которая возвращается при передаче имени методу извлечения ресурсов, например, ResourceManager.GetString. Имя и значение должны быть разделены знаком равенства (=). Например:

FileMenuName=File
EditMenuName=Edit
ViewMenuName=View
HelpMenuName=Help

Внимание

Не следует использовать файлы ресурсов для хранения паролей, конфиденциальной информации или личных данных.

В текстовых файлах допускаются пустые строки (то есть, ресурсы, значение которых равно String.Empty). Например:

EmptyString=

Начиная с .NET Framework 4.5 и во всех версиях .NET Core текстовые файлы поддерживают условную компиляцию с конструкциями #ifdefсимвол... #endif и #if !символ... #endif. Для определения символов можно использовать генератор файлов ресурсов (resgen.exe) с параметром /define. Каждый ресурс должен иметь собственную конструкцию #ifdefсимвол... #endif или #if !символ... #endif. Если при использовании оператора #ifdef указан символ, связанный ресурс добавляется в RESOURCES-файл; в противном случае он не добавляется. Если при использовании оператора #if !символ не указан, связанный ресурс добавляется в RESOURCES-файл; в противном случае он не добавляется.

Комментарии в текстовых файлах необязательны и начинаются с точки с запятой (;) или знака решетки (#) в начале строки. Строки с комментариями могут находиться в любом месте файла. Комментарии не включаются в скомпилированный RESOURCES-файл, созданный с помощью генератора файлов ресурсов (resgen.exe).

Любые пустые строки в текстовых файлах считаются содержащими пробелы и игнорируются.

В следующем примере определяются два строковых ресурса с именами OKButton и CancelButton.

#Define resources for buttons in the user interface.
OKButton=OK
CancelButton=Cancel

Если в текстовом файле содержатся дубликаты имен, генератор файлов ресурсов (resgen.exe) отображает предупреждение и игнорирует второе имя.

Значение не может содержать новые символы строки, но можно использовать escape-символы в стиле C, например \n , для представления новой строки и \t представления вкладки. Можно также включить символ обратной косой черты, если он экранируется (например, "\\"). Также допускаются пустые строки.

Сохраняйте ресурсы в формате текстового файла с кодировкой UTF-8 или UTF-16 с прямым или обратным порядком байтов. Но генератор файлов ресурсов (resgen.exe), преобразующий TXT-файл в RESOURCES-файл, по умолчанию обрабатывает файлы в кодировке UTF-8. Если вы хотите, чтобы программа Resgen.exe могла работать с файлом в кодировке UTF-16, необходимо указать метку порядка байтов Юникода (U+FEFF) в начале файла.

Чтобы внедрить файл ресурсов в текстовом формате в сборку .NET, необходимо преобразовать текстовый файл в двоичный файл ресурсов (RESOURCES) с помощью генератора файлов ресурсов (resgen.exe). Затем можно внедрить RESOURCES-файл в сборку .NET с помощью компилятора языка или во вспомогательную сборку с помощью компоновщика сборок (Al.exe).

В следующем примере используется файл ресурсов в текстовом формате GreetingResources.txt для простого консольного приложения "Hello World". В этом текстовом файле определены две строки — prompt и greeting, которые предлагают пользователю ввести свое имя и отображают приветствие.

# GreetingResources.txt
# A resource file in text format for a "Hello World" application.
#
# Initial prompt to the user.
prompt=Enter your name:
# Format string to display the result.
greeting=Hello, {0}!

Текстовый файл преобразуется в RESOURCES-файл с помощью следующей команды:

resgen GreetingResources.txt

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

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

public class Example
{
   public static void Main()
   {
      ResourceManager rm = new ResourceManager("GreetingResources",
                               typeof(Example).Assembly);
      Console.Write(rm.GetString("prompt"));
      string name = Console.ReadLine();
      Console.WriteLine(rm.GetString("greeting"), name);
   }
}
// The example displays output like the following:
//       Enter your name: Wilberforce
//       Hello, Wilberforce!

Imports System.Reflection
Imports System.Resources

Module Example
    Public Sub Main()
        Dim rm As New ResourceManager("GreetingResources",
                                      GetType(Example).Assembly())
        Console.Write(rm.GetString("prompt"))
        Dim name As String = Console.ReadLine()
        Console.WriteLine(rm.GetString("greeting"), name)
    End Sub
End Module
' The example displays output like the following:
'       Enter your name: Wilberforce
'       Hello, Wilberforce!

Если вы используете Visual Basic и файл с исходным кодом называется Greeting.vb, используйте следующую команду для создания исполняемого файла, содержащего внедренный RESOURCES-файл:

vbc greeting.vb -resource:GreetingResources.resources

Если вы используете C# и файл исходного кода называется Greeting.cs, исполняемый файл, содержащий внедренный RESOURCES-файл, создается с помощью следующей команды:

csc greeting.cs -resource:GreetingResources.resources

Ресурсы в RESX-файлах

В отличие от текстовых файлов, в которых могут храниться только строковые ресурсы, в XML-файлах ресурсов (RESX) могут храниться строки, двоичные данные (такие как изображения, значки и аудиоклипы) и программные объекты. RESX-файл содержит стандартный заголовок, который описывает формат записей ресурсов и включает сведения о версии XML, которые используются для анализа данных. За заголовком XML следуют данные в файле ресурсов. Каждый элемент данных состоит из пары "имя-значение", заключенной в тег data. Атрибут name этого тега определяет имя ресурса, а вложенный тег value содержит значение ресурса. Для строковых данных тег value содержит строку.

Например, следующий тег data определяет строковый ресурс с именем prompt и значением "Enter your name:".

<data name="prompt" xml:space="preserve">
  <value>Enter your name:</value>
</data>

Внимание

Для объектов ресурсов тег data содержит атрибут type, указывающий тип данных ресурса. Для объектов, состоящих из двоичных данных, тег data также включает атрибут mimetype, который указывает тип base64 двоичных данных.

Примечание.

Во всех RESX-файлах для создания и анализа двоичных данных заданного типа используется форматтер двоичной сериализации. В результате, если формат двоичной сериализации для объекта изменится недопустимым образом, RESX-файл может стать недействительным.

В следующем примере показана часть RESX-файла, в которой содержится ресурс Int32 и растровое изображение.

<data name="i1" type="System.Int32, mscorlib">
  <value>20</value>
</data>

<data name="flag" type="System.Drawing.Bitmap, System.Drawing,
    Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"
    mimetype="application/x-microsoft.net.object.bytearray.base64">
  <value>
    AAEAAAD/////AQAAAAAAAAAMAgAAADtTeX…
  </value>
</data>

Внимание

Так как RESX-файлы должны представлять собой XML-код с правильным, заранее определенным форматом, с ними не рекомендуется работать вручную, особенно если они содержат нестроковые ресурсы. Вместо этого в Visual Studio предусмотрен прозрачный интерфейс для создания RESX-файлов и управления ими. Дополнительные сведения см. в разделе Файлы ресурсов в Visual Studio. Создавать RESX-файлы и управлять ими можно также программно. Дополнительные сведения см. в разделе Работа с RESX-файлами программным способом.

Ресурсы в RESOURCES-файлах

Для программного создания двоичного файла ресурсов (RESOURCES-файла) непосредственно из кода можно использовать класс System.Resources.ResourceWriter. Для создания RESOURCES-файла из текстового файла или RESX-файла можно также использовать генератор файлов ресурсов (resgen.exe). Помимо строковых данных, RESOURCES-файл может содержать двоичные данные (массивы байтов) и данные объектов. Для программного создания RESOURCES-файла необходимо выполнить следующие действия.

Создайте объект ResourceWriter с уникальным именем файла. Это можно сделать, указав имя файла или файловый поток для конструктора класса ResourceWriter.
Вызовите одну из перегрузок метода ResourceWriter.AddResource для каждого именованного ресурса, который требуется добавить в файл. Ресурсом может быть строка, объект или коллекция двоичных данных (массив байтов).
Вызовете метод ResourceWriter.Close, чтобы записать ресурсы в файл и закрыть объект ResourceWriter.

Внимание

В следующем примере программным способом создается RESOURCES-файл с именем CarResources.resources, в котором хранятся шесть строк, значок и два объекта, определяемые приложением (два объекта Automobile). Класс Automobile, определенный и созданный в этом примере, отмечен атрибутом SerializableAttribute, который позволяет ему сохраняться модулем форматирования при двоичной сериализации.

using System;
using System.Drawing;
using System.Resources;

[Serializable()] public class Automobile
{
   private string carMake;
   private string carModel;
   private int carYear;
   private int carDoors;
   private int carCylinders;

   public Automobile(string make, string model, int year) :
                     this(make, model, year, 0, 0)
   { }

   public Automobile(string make, string model, int year,
                     int doors, int cylinders)
   {
      this.carMake = make;
      this.carModel = model;
      this.carYear = year;
      this.carDoors = doors;
      this.carCylinders = cylinders;
   }

   public string Make {
      get { return this.carMake; }
   }

   public string Model {
      get { return this.carModel; }
   }

   public int Year {
      get { return this.carYear; }
   }

   public int Doors {
      get {
         return this.carDoors; }
   }

   public int Cylinders {
      get {
         return this.carCylinders; }
   }
}

public class Example
{
   public static void Main()
   {
      // Instantiate an Automobile object.
      Automobile car1 = new Automobile("Ford", "Model N", 1906, 0, 4);
      Automobile car2 = new Automobile("Ford", "Model T", 1909, 2, 4);
      // Define a resource file named CarResources.resx.
      using (ResourceWriter rw = new ResourceWriter(@".\CarResources.resources"))
      {
         rw.AddResource("Title", "Classic American Cars");
         rw.AddResource("HeaderString1", "Make");
         rw.AddResource("HeaderString2", "Model");
         rw.AddResource("HeaderString3", "Year");
         rw.AddResource("HeaderString4", "Doors");
         rw.AddResource("HeaderString5", "Cylinders");
         rw.AddResource("Information", SystemIcons.Information);
         rw.AddResource("EarlyAuto1", car1);
         rw.AddResource("EarlyAuto2", car2);
      }
   }
}

Imports System.Drawing
Imports System.Resources

<Serializable()> Public Class Automobile
    Private carMake As String
    Private carModel As String
    Private carYear As Integer
    Private carDoors AS Integer
    Private carCylinders As Integer

    Public Sub New(make As String, model As String, year As Integer)
        Me.New(make, model, year, 0, 0)
    End Sub

    Public Sub New(make As String, model As String, year As Integer,
                   doors As Integer, cylinders As Integer)
        Me.carMake = make
        Me.carModel = model
        Me.carYear = year
        Me.carDoors = doors
        Me.carCylinders = cylinders
    End Sub

    Public ReadOnly Property Make As String
        Get
            Return Me.carMake
        End Get
    End Property

    Public ReadOnly Property Model As String
        Get
            Return Me.carModel
        End Get
    End Property

    Public ReadOnly Property Year As Integer
        Get
            Return Me.carYear
        End Get
    End Property

    Public ReadOnly Property Doors As Integer
        Get
            Return Me.carDoors
        End Get
    End Property

    Public ReadOnly Property Cylinders As Integer
        Get
            Return Me.carCylinders
        End Get
    End Property
End Class

Module Example
    Public Sub Main()
        ' Instantiate an Automobile object.
        Dim car1 As New Automobile("Ford", "Model N", 1906, 0, 4)
        Dim car2 As New Automobile("Ford", "Model T", 1909, 2, 4)
        ' Define a resource file named CarResources.resx.
        Using rw As New ResourceWriter(".\CarResources.resources")
            rw.AddResource("Title", "Classic American Cars")
            rw.AddResource("HeaderString1", "Make")
            rw.AddResource("HeaderString2", "Model")
            rw.AddResource("HeaderString3", "Year")
            rw.AddResource("HeaderString4", "Doors")
            rw.AddResource("HeaderString5", "Cylinders")
            rw.AddResource("Information", SystemIcons.Information)
            rw.AddResource("EarlyAuto1", car1)
            rw.AddResource("EarlyAuto2", car2)
        End Using
    End Sub
End Module

После создания RESOURCES-файла его можно внедрить в исполняемый файл среды выполнения или библиотеку, используя параметр /resource компилятора языка, или во вспомогательную сборку с помощью компоновщик сборок (Al.exe).

Файлы ресурсов в Visual Studio

При добавлении файла ресурсов в проект Visual Studio среда Visual Studio создает RESX-файл в каталоге проекта. В Visual Studio имеются редакторы ресурсов, позволяющие добавлять строки, изображения и двоичные объекты. Так как редакторы предназначены для обработки только статических данных, их нельзя использовать для хранения программных объектов; данные объектов необходимо записывать в RESX- или RESOURCES-файл программным способом. Дополнительные сведения см. в статье Работа с RESX-файлами программным способом и разделе Ресурсы в RESOURCES-файлах.

При добавлении локализованных ресурсов указывайте для них то же имя корневого файла, что и для основного файла ресурсов. Также в имени файла необходимо указать язык и региональные параметры. Например, если добавить файл ресурсов с именем Resources.resx, можно также создать файлы ресурсов с именем Resources.en-US.resx и Resources.fr-FR.resx, чтобы хранить локализованные ресурсы для языков английского языка (США) и французского языка (Франция) соответственно. Следует также указать язык и региональные параметры по умолчанию для приложения. Это язык и региональные параметры, ресурсы которых используются в том случае, если для конкретного языка и региональных параметров никаких локализованных ресурсов обнаружить не удается.

Чтобы указать язык и региональные параметры по умолчанию, в Обозреватель решений в Visual Studio:

Откройте свойства проекта, щелкните проект правой кнопкой мыши и выберите "Свойства" (или "Alt + ВВОД", когда выбран проект).
Перейдите на вкладку Package (Пакет).
В области "Общие" выберите соответствующий язык или язык и региональные параметры в элементе управления "Нейтральный язык сборки".
Сохранение изменений.

Во время компиляции среда Visual Studio сначала преобразует RESX-файлы проекта в двоичные файлы ресурсов (RESOURCES) и сохраняет их в подкаталоге каталога obj проекта. Visual Studio внедряет любые файлы ресурсов, не содержащие локализованные ресурсы, в основную сборку, созданную проектом. Если в каких-либо файлах ресурсов есть локализованные ресурсы, Visual Studio внедряет их в отдельные вспомогательные сборки для каждого локализованного языка и региональных параметров. Затем Visual Studio сохраняет каждую вспомогательную сборку в каталоге, имя которого соответствует локализованному языку и региональным параметрам. Например, локализованные ресурсы английского языка (США) сохраняются во вспомогательной сборке в подкаталоге en-US.

Поделиться через

Создание файлов ресурсов для приложений .NET

Ресурсы в формате текстовых файлов

Ресурсы в RESX-файлах

Ресурсы в RESOURCES-файлах

Файлы ресурсов в Visual Studio

См. также

Дополнительные ресурсы