Resourcebestanden maken voor .NET-apps
U kunt resources, zoals tekenreeksen, afbeeldingen of objectgegevens, opnemen in resourcebestanden om ze eenvoudig beschikbaar te maken voor uw toepassing. Het .NET Framework biedt vijf manieren om resourcesbestanden te maken:
Maak een tekstbestand met tekenreeksbronnen. U kunt resourcebestandgenerator (resgen.exe) gebruiken om het tekstbestand te converteren naar een binair resourcebestand (.resources). U kunt vervolgens het binaire bronbestand insluiten in een uitvoerbaar toepassingsbestand of een toepassingsbibliotheek met behulp van een taalcompilator, of u kunt het insluiten in een satellietassembly met behulp van Assembly Linker (Al.exe). Zie de sectie Resources in tekstbestanden voor meer informatie.
Maak een XML-resourcebestand (.resx) dat tekenreeks-, afbeeldings- of objectgegevens bevat. U kunt resourcebestandgenerator (resgen.exe) gebruiken om het RESX-bestand te converteren naar een binair resourcebestand (.resources). U kunt vervolgens het binaire bronbestand insluiten in een uitvoerbaar toepassingsbestand of een toepassingsbibliotheek met behulp van een taalcompilator, of u kunt het insluiten in een satellietassembly met behulp van Assembly Linker (Al.exe). Zie de sectie Resources in .resx Files voor meer informatie.
Maak programmatisch een XML-resourcebestand (.resx) met behulp van typen in de System.Resources naamruimte. U kunt een RESX-bestand maken, de bijbehorende resources inventariseren en specifieke resources op naam ophalen. Zie Werken met .resx Files programmatisch voor meer informatie.
Programmatisch een binair resourcebestand (.resources) maken. U kunt het bestand vervolgens insluiten in een uitvoerbaar toepassingsbestand of een toepassingsbibliotheek met behulp van een taalcompilator, of u kunt het insluiten in een satellietassembly met behulp van Assembly Linker (Al.exe). Zie de sectie Resources in .resources Files voor meer informatie.
Gebruik Visual Studio om een resourcebestand te maken en op te nemen in uw project. Visual Studio biedt een resource-editor waarmee u resources kunt toevoegen, verwijderen en wijzigen. Tijdens het compileren wordt het resourcebestand automatisch geconverteerd naar een binair .resources-bestand en ingesloten in een toepassingsassembly of satellietassembly. Zie de sectie Resourcebestanden in Visual Studio voor meer informatie.
Resources in tekstbestanden
U kunt tekstbestanden (.txt of .restext) gebruiken om alleen tekenreeksresources op te slaan. Voor niet-tekenreeksresources gebruikt u .resx-bestanden of maakt u ze programmatisch. Tekstbestanden die tekenreeksbronnen bevatten, hebben de volgende indeling:
# 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
De resourcebestandsindeling van .txt- en .restext-bestanden is identiek. De bestandsextensie .restext dient alleen om tekstbestanden onmiddellijk identificeerbaar te maken als bronbestanden op basis van tekst.
Tekenreeksresources worden weergegeven als naam-/waardeparen, waarbij de naam een tekenreeks is die de resource identificeert en de waarde de resourcereeks is die wordt geretourneerd wanneer u de naam doorgeeft aan een methode voor het ophalen van resources, zoals ResourceManager.GetString. naam en waarde moeten worden gescheiden door een gelijkteken (=). Voorbeeld:
FileMenuName=File
EditMenuName=Edit
ViewMenuName=View
HelpMenuName=Help
Let op
Gebruik geen resourcebestanden om wachtwoorden, beveiligingsgevoelige informatie of persoonlijke gegevens op te slaan.
Lege tekenreeksen (een resource waarvan de waarde is String.Empty) zijn toegestaan in tekstbestanden. Voorbeeld:
EmptyString=
Vanaf .NET Framework 4.5 en in alle versies van .NET Core ondersteunen tekstbestanden voorwaardelijke compilatie met het #ifdefsymbool... #endif en#if ! symbool... #endif constructies. Vervolgens kunt u de /define switch gebruiken met resourcebestandgenerator (resgen.exe) om symbolen te definiëren. Elke resource vereist een eigen #ifdefsymbool... #endif of #if !symbool... #endif constructie. Als u een #ifdef instructie en symbool gebruikt, wordt de bijbehorende resource opgenomen in het .resources-bestand. Anders is deze niet opgenomen. Als u een #if ! instructie en symbool niet hebt gedefinieerd, wordt de bijbehorende resource opgenomen in het .resources-bestand. Anders is deze niet opgenomen.
Opmerkingen zijn optioneel in tekstbestanden en worden voorafgegaan door een puntkomma (;) of een hekje (#) aan het begin van een regel. Regels die opmerkingen bevatten, kunnen overal in het bestand worden geplaatst. Opmerkingen worden niet opgenomen in een gecompileerd .resources-bestand dat is gemaakt met resourcebestandgenerator (resgen.exe).
Lege regels in de tekstbestanden worden beschouwd als witruimte en worden genegeerd.
In het volgende voorbeeld worden twee tekenreeksbronnen gedefinieerd met de naam OKButton en CancelButton.
#Define resources for buttons in the user interface.
OKButton=OK
CancelButton=Cancel
Als het tekstbestand dubbele exemplaren van de naam bevat, geeft resourcebestandgenerator (resgen.exe) een waarschuwing weer en negeert u de tweede naam.
waarde mag geen nieuwe regeltekens bevatten, maar u kunt escapetekens in C-taalstijl gebruiken, zoals \n het weergeven van een nieuwe regel en \t het weergeven van een tabblad. U kunt ook een backslash-teken opnemen als het is ontsnapt (bijvoorbeeld '\\'). Daarnaast is een lege tekenreeks toegestaan.
Sla resources op in tekstbestandsindeling met behulp van UTF-8-codering of UTF-16-codering in bytevolgorde little-endian of big-endian. Bronbestandgenerator (resgen.exe), waarmee een .txt-bestand wordt geconverteerd naar een .resources-bestand, behandelt bestanden standaard als UTF-8. Als u wilt dat Resgen.exe een bestand herkent dat is gecodeerd met UTF-16, moet u aan het begin van het bestand een Unicode-bytevolgordemarkering (U+FEFF) opnemen.
Als u een resourcebestand in tekstindeling wilt insluiten in een .NET-assembly, moet u het bestand converteren naar een binair resourcebestand (.resources) met behulp van Resource File Generator (resgen.exe). Vervolgens kunt u het .resources-bestand insluiten in een .NET-assembly met behulp van een taalcompilator of insluiten in een satellietassembly met behulp van Assembly Linker (Al.exe).
In het volgende voorbeeld wordt een resourcebestand in tekstindeling met de naam GreetingResources.txt gebruikt voor een eenvoudige consoletoepassing 'Hallo wereld'. Het tekstbestand definieert twee tekenreeksen prompt en greeting, die de gebruiker vragen hun naam in te voeren en een begroeting weer te geven.
# 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}!
Het tekstbestand wordt geconverteerd naar een .resources-bestand met behulp van de volgende opdracht:
resgen GreetingResources.txt
In het volgende voorbeeld ziet u de broncode voor een consoletoepassing die gebruikmaakt van het .resources-bestand om berichten weer te geven aan de gebruiker.
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!
Als u Visual Basic gebruikt en het broncodebestand de naam Greeting.vb heeft, wordt met de volgende opdracht een uitvoerbaar bestand gemaakt dat het ingesloten .resources-bestand bevat:
vbc greeting.vb -resource:GreetingResources.resources
Als u C# gebruikt en het broncodebestand de naam Greeting.cs heeft, wordt met de volgende opdracht een uitvoerbaar bestand gemaakt dat het ingesloten .resources-bestand bevat:
csc greeting.cs -resource:GreetingResources.resources
Resources in .resx-bestanden
In tegenstelling tot tekstbestanden, die alleen tekenreeksresources kunnen opslaan, kunnen XML-resourcebestanden (.resx) tekenreeksen, binaire gegevens zoals afbeeldingen, pictogrammen en audioclips en programmatische objecten opslaan. Een RESX-bestand bevat een standaardheader, waarin de indeling van de resourcevermeldingen wordt beschreven en de versiegegevens worden opgegeven voor de XML die wordt gebruikt om de gegevens te parseren. De bronbestandsgegevens volgen de XML-header. Elk gegevensitem bestaat uit een naam/waardepaar dat is opgenomen in een data tag. Het name kenmerk definieert de resourcenaam en de geneste value tag bevat de resourcewaarde. Voor tekenreeksgegevens bevat de value tag de tekenreeks.
Met de volgende data tag wordt bijvoorbeeld een tekenreeksresource gedefinieerd met de naam prompt 'Voer uw naam in:'.
<data name="prompt" xml:space="preserve">
<value>Enter your name:</value>
</data>
Let op
Gebruik geen resourcebestanden om wachtwoorden, beveiligingsgevoelige informatie of persoonlijke gegevens op te slaan.
Voor resourceobjecten bevat de gegevenstag een type kenmerk dat het gegevenstype van de resource aangeeft. Voor objecten die bestaan uit binaire gegevens, bevat de data tag ook een mimetype kenmerk, dat het base64 type van de binaire gegevens aangeeft.
Notitie
Alle .resx-bestanden gebruiken een binaire serialisatie-formatter om de binaire gegevens voor een opgegeven type te genereren en te parseren. Als gevolg hiervan kan een RESX-bestand ongeldig worden als de binaire serialisatie-indeling voor een object op een niet-compatibele manier verandert.
In het volgende voorbeeld ziet u een gedeelte van een RESX-bestand dat een Int32 resource en een bitmapafbeelding bevat.
<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>
Belangrijk
Omdat .resx-bestanden moeten bestaan uit goed opgemaakte XML in een vooraf gedefinieerde indeling, raden we u niet aan handmatig met .resx-bestanden te werken, met name wanneer de RESX-bestanden andere resources bevatten dan tekenreeksen. In plaats daarvan biedt Visual Studio een transparante interface voor het maken en bewerken van .resx-bestanden. Zie de sectie Resourcebestanden in Visual Studio voor meer informatie. U kunt ook programmatisch .resx-bestanden maken en bewerken. Zie Werken met .resx-bestanden programmatisch voor meer informatie.
Resources in .resources-bestanden
U kunt de System.Resources.ResourceWriter klasse gebruiken om programmatisch een binair resourcebestand (.resources) rechtstreeks vanuit code te maken. U kunt resourcebestandgenerator (resgen.exe) ook gebruiken om een .resources-bestand te maken op basis van een tekstbestand of een RESX-bestand. Het .resources-bestand kan binaire gegevens (bytematrices) en objectgegevens bevatten naast tekenreeksgegevens. Voor het programmatisch maken van een .resources-bestand zijn de volgende stappen vereist:
Maak een ResourceWriter object met een unieke bestandsnaam. U kunt dit doen door een bestandsnaam of een bestandsstroom op te geven naar een ResourceWriter klasseconstructor.
Roep een van de overbelastingen van de ResourceWriter.AddResource methode aan voor elke benoemde resource die aan het bestand moet worden toegevoegd. De resource kan een tekenreeks, een object of een verzameling binaire gegevens (een bytematrix) zijn.
Roep de ResourceWriter.Close methode aan om de resources naar het bestand te schrijven en het ResourceWriter object te sluiten.
Let op
Gebruik geen resourcebestanden om wachtwoorden, beveiligingsgevoelige informatie of persoonlijke gegevens op te slaan.
In het volgende voorbeeld wordt programmatisch een .resources-bestand gemaakt met de naam CarResources.resources waarin zes tekenreeksen, een pictogram en twee toepassingsgedefinieerde objecten (twee Automobile objecten) worden opgeslagen. De Automobile klasse, die in het voorbeeld is gedefinieerd en geïnstantieerd, wordt gelabeld met het SerializableAttribute kenmerk, zodat deze kan worden behouden door de binaire serialisatie-formatter.
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
Nadat u het .resources-bestand hebt gemaakt, kunt u het insluiten in een uitvoerbaar uitvoerbare bestand of bibliotheek door de switch van /resource de taalcompilator op te nemen of in te sluiten in een satellietassembly met behulp van Assembly Linker (Al.exe).
Resourcebestanden in Visual Studio
Wanneer u een resourcebestand aan uw Visual Studio-project toevoegt, maakt Visual Studio een RESX-bestand in de projectmap. Visual Studio biedt resource-editors waarmee u tekenreeksen, afbeeldingen en binaire objecten kunt toevoegen. Omdat de editors zijn ontworpen om alleen statische gegevens te verwerken, kunnen ze niet worden gebruikt voor het opslaan van programmatische objecten; u moet objectgegevens schrijven naar een RESX-bestand of naar een .resources-bestand programmatisch. Zie Werken met .resx-bestanden programmatisch en de sectie Resources in .resources-bestanden voor meer informatie.
Als u gelokaliseerde resources toevoegt, geeft u deze dezelfde hoofdbestandsnaam als het hoofdresourcebestand. U moet ook hun cultuur in de bestandsnaam aanwijzen. Als u bijvoorbeeld een resourcebestand met de naam Resources.resx toevoegt, kunt u ook resourcebestanden maken met de naam Resources.en-US.resx en Resources.fr-FR.resx om gelokaliseerde resources te bewaren voor respectievelijk de Engelse culturen (Verenigde Staten) en Frans (Frankrijk). U moet ook de standaardcultuur van uw toepassing aanwijzen. Dit is de cultuur waarvan de resources worden gebruikt als er geen gelokaliseerde resources voor een bepaalde cultuur kunnen worden gevonden.
De standaardcultuur opgeven in Solution Explorer in Visual Studio:
- Open de projecteigenschappen, klik met de rechtermuisknop op het project en selecteer Eigenschappen (of Alt + Enter wanneer het project is geselecteerd).
- Selecteer het tabblad Pakket .
- Selecteer in het gebied Algemeen de juiste taal/cultuur in het neutraal taalbeheer van de assembly.
- Sla uw wijzigingen op.
Tijdens het compileren converteert Visual Studio eerst de RESX-bestanden in een project naar binaire resourcebestanden (.resources) en slaat ze op in een submap van de obj-map van het project. Visual Studio sluit resourcebestanden in die geen gelokaliseerde resources bevatten in de hoofdassembly die door het project wordt gegenereerd. Als resourcebestanden gelokaliseerde resources bevatten, worden deze in Visual Studio ingesloten in afzonderlijke satellietassembly's voor elke gelokaliseerde cultuur. Vervolgens wordt elke satellietassembly opgeslagen in een map waarvan de naam overeenkomt met de gelokaliseerde cultuur. Gelokaliseerde Engelse resources (Verenigde Staten) worden bijvoorbeeld opgeslagen in een satellietassembly in de submap en-US.
