Vytváření souborů prostředků pro aplikace .NET

Do souborů prostředků můžete zahrnout prostředky, jako jsou řetězce, obrázky nebo data objektů, aby byly pro vaši aplikaci snadno dostupné. Rozhraní .NET Framework nabízí pět způsobů vytváření souborů prostředků:

Prostředky v textových souborech

K ukládání řetězcových prostředků můžete použít textové soubory (.txt nebo .restext). Pro prostředky, které nejsou řetězcové, použijte soubory .resx nebo je vytvořte programově. Textové soubory, které obsahují prostředky řetězců, mají následující formát:

# 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

Formát souboru prostředku .txt a souborů .restext je stejný. Přípona souboru .restext slouží pouze k tomu, aby textové soubory okamžitě identifikovatelné jako textové soubory prostředků.

Řetězcové prostředky se zobrazují jako páry názvů a hodnot , kde název je řetězec, který identifikuje prostředek, a hodnota je řetězec prostředku, který se vrátí při předání názvu do metody načítání prostředku, jako je například ResourceManager.GetString. název a hodnota musí být odděleny znaménkem rovná se (=). Příklad:

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

Upozornění

Nepoužívejte soubory prostředků k ukládání hesel, informací citlivých na zabezpečení nebo privátních dat.

Prázdné řetězce (tj. prostředek, jehož hodnota je String.Empty) jsou povoleny v textových souborech. Příklad:

EmptyString=

Počínaje rozhraním .NET Framework 4.5 a ve všech verzích .NET Core podporují textové soubory podmíněnou kompilaci pomocí symbolu#endif#ifdef a #if !symbolu... #endif konstruktorů. Potom můžete použít /define přepínač s generátorem souborů prostředků (resgen.exe) k definování symbolů. Každý prostředek vyžaduje vlastní #ifdefsymbol... #endif nebo #if !symbol... #endif konstruktor. Pokud použijete #ifdef příkaz a symbol , bude přidružený prostředek zahrnutý do souboru .resources. V opačném případě není zahrnutý. Pokud použijete #if ! příkaz a symbol není definován, přidružený prostředek je součástí souboru .resources; jinak není zahrnutý.

Komentáře jsou volitelné v textových souborech a předcházejí středníkem (;) nebo znakem libry (#) na začátku řádku. Řádky, které obsahují komentáře, se dají umístit kamkoli do souboru. Komentáře nejsou zahrnuty do kompilovaného souboru .resources, který je vytvořen pomocí generátoru souborů prostředků (resgen.exe).

Všechny prázdné řádky v textových souborech se považují za prázdné a jsou ignorovány.

Následující příklad definuje dva řetězcové prostředky pojmenované OKButton a CancelButton.

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

Pokud textový soubor obsahuje duplicitní výskyty názvu, generátor souborů prostředků (resgen.exe) zobrazí upozornění a ignoruje druhý název.

hodnota nemůže obsahovat nové znaky řádku, ale můžete použít řídicí znaky ve stylu jazyka C, například \n k reprezentaci nového řádku a \t k reprezentaci karty. Můžete také zahrnout znak zpětného lomítka, pokud je řídicí znak (například "\\"). Kromě toho je povolený prázdný řetězec.

Uložte prostředky ve formátu textového souboru pomocí kódování UTF-8 nebo kódování UTF-16 v malém nebo big-endian pořadí. Generátor souborů prostředků (resgen.exe), který převede soubor .txt na soubor .resources, ve výchozím nastavení považuje soubory za UTF-8. Pokud chcete Resgen.exe rozpoznat soubor, který byl kódován pomocí UTF-16, musíte na začátku souboru zahrnout značku pořadí bajtů Unicode (U+FEFF).

Chcete-li vložit soubor prostředku v textovém formátu do sestavení .NET, musíte soubor převést na binární soubor (.resources) pomocí Generátoru souborů prostředků (resgen.exe). Soubor .resources pak můžete vložit do sestavení .NET pomocí kompilátoru jazyka nebo ho vložit do satelitního sestavení pomocí linkeru sestavení (Al.exe).

Následující příklad používá soubor prostředků v textovém formátu s názvem GreetingResources.txt pro jednoduchou konzolovou aplikaci Hello World. Textový soubor definuje dva řetězce prompt , které greetinguživatele vyzve k zadání jména a zobrazení pozdravu.

# 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}!

Textový soubor se převede na soubor .resources pomocí následujícího příkazu:

resgen GreetingResources.txt

Následující příklad ukazuje zdrojový kód konzolové aplikace, která používá soubor .resources k zobrazení zpráv uživateli.

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!

Pokud používáte Visual Basic a zdrojový soubor kódu má název Greeting.vb, vytvoří následující příkaz spustitelný soubor, který obsahuje vložený soubor .resources:

vbc greeting.vb -resource:GreetingResources.resources

Pokud používáte C# a zdrojový soubor kódu má název Greeting.cs, vytvoří následující příkaz spustitelný soubor, který obsahuje vložený soubor .resources:

csc greeting.cs -resource:GreetingResources.resources

Prostředky v souborech .resx

Na rozdíl od textových souborů, které mohou ukládat pouze řetězcové prostředky, můžou soubory prostředků XML (.resx) ukládat řetězce, binární data, jako jsou obrázky, ikony a zvukové klipy a programové objekty. Soubor .resx obsahuje standardní hlavičku, která popisuje formát položek prostředků a určuje informace o správě verzí pro XML, které slouží k analýze dat. Data souboru prostředků se řídí hlavičkou XML. Každá datová položka se skládá z dvojice názvů a hodnot, která je obsažena ve data značce. Jeho name atribut definuje název prostředku a vnořená value značka obsahuje hodnotu prostředku. U řetězcových dat value značka obsahuje řetězec.

Například následující data značka definuje řetězcový prostředek s názvem prompt , jehož hodnota je "Zadejte název:".

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

Upozornění

Nepoužívejte soubory prostředků k ukládání hesel, informací citlivých na zabezpečení nebo privátních dat.

U objektů prostředků obsahuje typeznačka dat atribut, který označuje datový typ prostředku. U objektů, které se skládají z binárních dat, data značka obsahuje mimetype také atribut, který označuje base64 typ binárních dat.

Poznámka

Všechny soubory .resx používají binární serializační formátovač k vygenerování a parsování binárních dat pro zadaný typ. V důsledku toho může být soubor .resx neplatný, pokud se binární serializace formátu objektu změní nekompatibilním způsobem.

Následující příklad ukazuje část souboru .resx, která obsahuje Int32 prostředek a rastrový obrázek.

<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>

Důležité

Vzhledem k tomu, že soubory .resx se musí skládat z dobře vytvořeného XML v předdefinovaném formátu, nedoporučujeme pracovat se soubory .resx ručně, zejména pokud soubory .resx obsahují jiné prostředky než řetězce. Místo toho sada Visual Studio poskytuje transparentní rozhraní pro vytváření a manipulaci se soubory .resx. Další informace najdete v části Soubory prostředků v sadě Visual Studio . Soubory .resx můžete vytvářet a manipulovat s nimi programově. Další informace naleznete v tématu Práce se soubory .resx programově.

Prostředky v souborech .resources

Pomocí třídy můžete System.Resources.ResourceWriter programově vytvořit soubor binárního prostředku (.resources) přímo z kódu. Pomocí generátoru souborů prostředků (resgen.exe) můžete také vytvořit soubor .resources z textového souboru nebo souboru .resx. Soubor .resources může obsahovat binární data (bajtová pole) a data objektů kromě řetězcových dat. Programové vytvoření souboru .resources vyžaduje následující kroky:

  1. ResourceWriter Vytvořte objekt s jedinečným názvem souboru. Můžete to provést zadáním názvu souboru nebo datového proudu souboru do konstruktoru ResourceWriter třídy.

  2. Volání jednoho z přetížení ResourceWriter.AddResource metody pro každý pojmenovaný prostředek přidat do souboru. Prostředek může být řetězec, objekt nebo kolekce binárních dat (bajtové pole).

  3. Zavolejte metodu ResourceWriter.Close pro zápis prostředků do souboru a zavření objektu ResourceWriter .

Poznámka

Nepoužívejte soubory prostředků k ukládání hesel, informací citlivých na zabezpečení nebo privátních dat.

Následující příklad programově vytvoří soubor .resources s názvem CarResources.resources, který ukládá šest řetězců, ikonu a dva objekty definované aplikací (dva Automobile objekty). Třída Automobile , která je definována a vytvořena instance v příkladu, je označena SerializableAttribute atributem, který umožňuje zachovat binární serializační formátovací.

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

Po vytvoření souboru .resources ho můžete vložit do spustitelného souboru nebo knihovny za běhu zahrnutím přepínače kompilátoru /resource jazyka nebo vložením do satelitního sestavení pomocí nástroje Assembly Linker (Al.exe).

Soubory prostředků v sadě Visual Studio

Když do projektu sady Visual Studio přidáte soubor zdroje, Visual Studio vytvoří soubor .resx v adresáři projektu. Visual Studio poskytuje editory prostředků, které umožňují přidávat řetězce, obrázky a binární objekty. Vzhledem k tomu, že editory jsou navržené tak, aby zpracovávaly pouze statická data, nelze je použít k ukládání programových objektů; Data objektu je nutné zapisovat do souboru .resx nebo do souboru .resources programově. Další informace naleznete v tématu Práce se soubory .resx programově a prostředky v části Soubory .resources .

Pokud přidáváte lokalizované prostředky, dejte jim stejný název kořenového souboru jako hlavní soubor prostředků. Měli byste také určit jejich jazykovou verzi v názvu souboru. Pokud například přidáte soubor prostředků s názvem Resources.resx, můžete také vytvořit soubory prostředků s názvem Resources.en-US.resx a Resources.fr-FR.resx pro lokalizované prostředky pro jazykové verze angličtiny (USA) a francouzštiny (Francie). Měli byste také určit výchozí jazykovou verzi aplikace. Toto je jazyková verze, jejíž prostředky se používají, pokud nelze najít žádné lokalizované prostředky pro konkrétní jazykovou verzi.

Pokud chcete zadat výchozí jazykovou verzi, v Průzkumník řešení v sadě Visual Studio:

  • Otevřete vlastnosti projektu, klikněte pravým tlačítkem myši na projekt a vyberte Vlastnosti (nebo Alt + Enter při výběru projektu).
  • Vyberte kartu Balíček .
  • V oblasti Obecné vyberte příslušný jazyk/jazykovou verzi z ovládacího prvku Sestavení neutrální jazyk .
  • Uložte provedené změny.

V době kompilace sada Visual Studio nejprve převede soubory .resx v projektu na soubory binárních prostředků (.resources) a uloží je do podadresáře adresáře obj projektu. Visual Studio vloží všechny soubory prostředků, které neobsahují lokalizované prostředky do hlavního sestavení, které je generováno projektem. Pokud některé soubory prostředků obsahují lokalizované prostředky, Visual Studio je vloží do samostatných satelitních sestavení pro každou lokalizovanou jazykovou verzi. Potom uloží každé satelitní sestavení do adresáře, jehož název odpovídá lokalizované jazykové verzi. Například lokalizované anglické (USA) prostředky se ukládají do satelitního sestavení v podadresáři en-US.

Viz také