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

Článek
03/12/2024

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

Vytvořte textový soubor, který obsahuje řetězcové prostředky. Pomocí generátoru souborů prostředků (resgen.exe) můžete textový soubor převést na binární soubor (.resources). Pak můžete binární soubor prostředků vložit do spustitelného souboru aplikace nebo knihovny aplikací pomocí kompilátoru jazyka, nebo ho můžete vložit do satelitního sestavení pomocí Assembly Linkeru (Al.exe). Další informace najdete v části Zdroje informací v textových souborech .
Vytvořte soubor prostředku XML (.resx), který obsahuje řetězcová, image nebo data objektu. K převodu souboru .resx na binární soubor (.resources) můžete použít generátor souborů prostředků (resgen.exe). Pak můžete binární soubor prostředků vložit do spustitelného souboru aplikace nebo knihovny aplikací pomocí kompilátoru jazyka, nebo ho můžete vložit do satelitního sestavení pomocí Assembly Linkeru (Al.exe). Další informace najdete v části Zdroje informací v souboru .resx .
Programově vytvořte soubor prostředku XML (.resx) pomocí typů v System.Resources oboru názvů. Můžete vytvořit soubor .resx, vytvořit výčet jeho prostředků a načíst konkrétní prostředky podle názvu. Další informace naleznete v tématu Práce se soubory .resx programově.
Soubor binárního prostředku (.resources) vytvořte programově. Soubor pak můžete vložit do spustitelného souboru aplikace nebo knihovny aplikací pomocí kompilátoru jazyka nebo ho můžete vložit do satelitního sestavení pomocí assembly Linkeru (Al.exe). Další informace najdete v části Zdroje informací v souboru .resources .
Pomocí sady Visual Studio vytvořte soubor prostředku a zahrňte ho do projektu. Visual Studio poskytuje editor prostředků, který umožňuje přidávat, odstraňovat a upravovat prostředky. V době kompilace se soubor prostředků automaticky převede na binární soubor .resources a vloží se do sestavení aplikace nebo satelitního sestavení. Další informace najdete v části Soubory prostředků v sadě Visual Studio .

Prostředky v textových souborech

Textové soubory (.txt nebo .restext) můžete použít jenom k ukládání řetězcových prostředků. Pro jiné než řetězcové prostředky 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ředků .txt a souborů .restext je shodný. 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ázev/hodnota , kde název je řetězec identifikující prostředek a hodnota je řetězec prostředku, který se vrátí při předání názvu metodě načítání prostředku, například ResourceManager.GetString. název a hodnota musí být oddělené symbolem rovná se (=). Příklad:

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

Upozornění

Nepoužívejte soubory prostředků k ukládání hesel, citlivých informací o zabezpečení ani k soukromým datům.

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 #ifdefa #if !#endifsymbolu... #endif konstruktorů. Pak můžete pomocí přepínače s generátorem /define souborů prostředků (resgen.exe) definovat symboly. Každý prostředek vyžaduje vlastní #ifdefsymbol... #endif nebo #if !konstruktor symbolu... #endif Pokud použijete #ifdef příkaz a symbol , bude přidružený prostředek zahrnutý do souboru .resources, jinak se nezahrne. Pokud použijete #if ! příkaz a symbol není definován, přidružený prostředek se zahrne do souboru .resources, jinak se nezahrne.

Komentáře jsou v textových souborech volitelné a předcházejí buď 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 ignorují se.

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 druhý název ignoruje.

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 tabulátoru. Znak zpětného lomítka můžete zahrnout také v případě, že je řídicí znak (například \\). Kromě toho je povolený prázdný řetězec.

Prostředky můžete ukládat ve formátu textového souboru pomocí kódování UTF-8 nebo kódování UTF-16 v řádu malých nebo velkých bajtů. Generátor souborů prostředků (resgen.exe), který ve výchozím nastavení převádí soubor .txt na soubor .resources, zpracovává soubory jako UTF-8. Pokud chcete Resgen.exe rozpoznat soubor, který byl kódován pomocí UTF-16, musíte na začátku souboru zahrnout znak pořadí bajtů Unicode (U+FEFF).

Chcete-li vložit soubor prostředků v textovém formátu do sestavení .NET, musíte soubor převést na binární soubor prostředků (.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 soubor zdrojového kódu má název Greeting.vb, následující příkaz vytvoří spustitelný soubor, který obsahuje vložený soubor .resources:

vbc greeting.vb -resource:GreetingResources.resources

Pokud používáte C# a soubor zdrojového 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é můžou 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é se používají k analýze dat. Data souboru prostředků se řídí hlavičkou XML. Každá datová položka se skládá z dvojice název/hodnota obsažená data ve značce. Jeho name atribut definuje název prostředku a vnořená value značka obsahuje hodnotu prostředku. Pro řetězcová data value obsahuje značka řetězec.

Například následující data značka definuje prostředek řetězce 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, citlivých informací o zabezpečení ani k soukromým datům.

U objektů prostředků obsahuje type značka dat atribut, který označuje datový typ prostředku. U objektů, které se skládají z binárních dat, data obsahuje značka také mimetype 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 binární serializační formát objektu se 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 formátované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 také vytvářet a manipulovat s nimi programově. Další informace naleznete v tématu Práce se soubory .resx programově.

Prostředky v souborech .resources

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

Vytvořte ResourceWriter 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.
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 (pole bajtů).
ResourceWriter.Close Volání metody pro zápis prostředků do souboru a zavření objektuResourceWriter.

Upozornění

Nepoužívejte soubory prostředků k ukládání hesel, citlivých informací o zabezpečení ani k soukromým datům.

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 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 /resource můžete vložit do spustitelného souboru nebo knihovny za běhu zahrnutím přepínače kompilátoru jazyka nebo vložením do satelitního sestavení pomocí Assembly Linkeru (Al.exe).

Soubory prostředků v sadě Visual Studio

Když do projektu sady Visual Studio přidáte soubor prostředků, Visual Studio vytvoří v adresáři projektu soubor .resx. 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ženy tak, aby zpracovávaly pouze statická data, nelze je použít k ukládání programových objektů; Data objektu musíte 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.

Visual Studio při kompilaci 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é prostředky (USA) se ukládají do satelitního sestavení v podadresáři en-US.

Sdílet prostřednictvím

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

Prostředky v textových souborech

Prostředky v souborech .resx

Prostředky v souborech .resources

Soubory prostředků v sadě Visual Studio

Viz také

Další materiály