Membuat file sumber daya untuk aplikasi .NET
Anda dapat menyertakan sumber daya, seperti string, gambar, atau data objek, dalam file sumber daya untuk membuatnya mudah tersedia untuk aplikasi Anda. .NET Framework menawarkan lima cara untuk membuat file sumber daya:
Buat file teks yang berisi sumber daya string. Anda dapat menggunakan Resource File Generator (resgen.exe) untuk mengonversi file teks menjadi file sumber daya biner (.resources). Anda kemudian dapat menyematkan file sumber daya biner dalam aplikasi yang dapat dieksekusi atau pustaka aplikasi dengan menggunakan pengkompilasi bahasa, atau Anda dapat menyematkannya di rakitan satelit dengan menggunakan Assembly Linker (Al.exe). Untuk informasi selengkapnya, lihat bagian Sumber Daya di file teks.
Buat file sumber daya XML (.resx) yang berisi data string, gambar, atau objek. Anda dapat menggunakan Resource File Generator (resgen.exe) untuk mengonversi file .resx menjadi file sumber daya biner (.resources). Anda kemudian dapat menyematkan file sumber daya biner dalam aplikasi yang dapat dieksekusi atau pustaka aplikasi dengan menggunakan pengkompilasi bahasa, atau Anda dapat menyematkannya di rakitan satelit dengan menggunakan Assembly Linker (Al.exe). Untuk informasi selengkapnya, lihat bagian Sumber Daya di File .resx.
Buat file sumber daya XML (.resx) secara terprogram dengan menggunakan jenis di System.Resources namespace. Anda dapat membuat file .resx, menghitung sumber dayanya, dan mengambil sumber daya tertentu berdasarkan nama. Untuk informasi selengkapnya, lihat Bekerja dengan File .resx Secara Terprogram.
Buat file sumber daya biner (.resources) secara terprogram. Anda kemudian dapat menyematkan file dalam aplikasi yang dapat dieksekusi atau pustaka aplikasi dengan menggunakan pengkompilasi bahasa, atau Anda dapat menyematkannya dalam rakitan satelit dengan menggunakan Assembly Linker (Al.exe). Untuk informasi selengkapnya, lihat bagian Sumber Daya di File .resources.
Gunakan Visual Studio untuk membuat file sumber daya dan menyertakannya dalam proyek Anda. Visual Studio menyediakan editor sumber daya yang memungkinkan Anda menambahkan, menghapus, dan memodifikasi sumber daya. Pada waktu kompilasi, file sumber daya secara otomatis dikonversi ke file .resources biner dan disematkan dalam rakitan aplikasi atau rakitan satelit. Untuk informasi selengkapnya, lihat bagian File sumber daya di Visual Studio .
Sumber daya dalam file teks
Anda dapat menggunakan file teks (.txt atau .restext) untuk menyimpan sumber daya string saja. Untuk sumber daya non-string, gunakan file .resx atau buat secara terprogram. File teks yang berisi sumber daya string memiliki format berikut:
# 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
Format file sumber daya file .txt dan .restext identik. Ekstensi file .restext hanya berfungsi untuk membuat file teks segera dapat diidentifikasi sebagai file sumber daya berbasis teks.
Sumber daya string muncul sebagai pasangan nama/nilai , di mana nama adalah string yang mengidentifikasi sumber daya, dan nilai adalah string sumber daya yang dikembalikan saat Anda meneruskan nama ke metode pengambilan sumber daya seperti ResourceManager.GetString. nama dan nilai harus dipisahkan dengan tanda sama dengan (=). Misalnya:
FileMenuName=File
EditMenuName=Edit
ViewMenuName=View
HelpMenuName=Help
Perhatian
Jangan gunakan file sumber daya untuk menyimpan kata sandi, informasi yang sensitif keamanan, atau data privat.
String kosong (yaitu, sumber daya yang nilainya String.Empty) diizinkan dalam file teks. Misalnya:
EmptyString=
Dimulai dengan .NET Framework 4.5 dan di semua versi .NET Core, file teks mendukung kompilasi kondisional dengan #ifdefsimbol ... #endif dan #if !simbol ... #endif konstruksi. Anda kemudian dapat menggunakan sakelar /define dengan Resource File Generator (resgen.exe) untuk menentukan simbol. Setiap sumber daya membutuhkan simbolnya sendiri#ifdef... #endif atau #if !simbol... #endif konstruksi. Jika Anda menggunakan #ifdef pernyataan dan simbol didefinisikan, sumber daya terkait disertakan dalam file .resources; jika tidak, itu tidak disertakan. Jika Anda menggunakan #if ! pernyataan dan simbol tidak ditentukan, sumber daya terkait disertakan dalam file .resources; jika tidak, itu tidak disertakan.
Komentar bersifat opsional dalam file teks dan didahului oleh titik koma (;) atau dengan tanda pagar (#) di awal baris. Baris yang berisi komentar dapat ditempatkan di mana saja dalam file. Komentar tidak disertakan dalam file .resources yang dikompilasi yang dibuat dengan menggunakan Resource File Generator (resgen.exe).
Setiap baris kosong dalam file teks dianggap sebagai spasi kosong dan diabaikan.
Contoh berikut mendefinisikan dua sumber daya string bernama OKButton dan CancelButton.
#Define resources for buttons in the user interface.
OKButton=OK
CancelButton=Cancel
Jika file teks berisi kemunculan nama duplikat, Resource File Generator (resgen.exe) menampilkan peringatan dan mengabaikan nama kedua.
nilai tidak boleh berisi karakter baris baru, tetapi Anda dapat menggunakan karakter escape gaya bahasa C seperti \n untuk mewakili baris baru dan \t untuk mewakili tab. Anda juga dapat menyertakan karakter garis miring terbelakang jika lolos (misalnya, "\\"). Selain itu, string kosong diizinkan.
Simpan sumber daya dalam format file teks dengan menggunakan pengodean UTF-8 atau pengodean UTF-16 dalam urutan byte little-endian atau big-endian. Namun, Resource File Generator (resgen.exe), yang mengonversi file .txt ke file .resources, memperlakukan file sebagai UTF-8 secara default. Jika Anda ingin Resgen.exe mengenali file yang dikodekan menggunakan UTF-16, Anda harus menyertakan tanda urutan byte Unicode (U+FEFF) di awal file.
Untuk menyematkan file sumber daya dalam format teks ke dalam rakitan .NET, Anda harus mengonversi file ke file sumber daya biner (.resources) dengan menggunakan Resource File Generator (resgen.exe). Anda kemudian dapat menyematkan file .resources dalam rakitan .NET dengan menggunakan pengkompilasi bahasa atau menyematkannya di rakitan satelit dengan menggunakan Assembly Linker (Al.exe).
Contoh berikut menggunakan file sumber daya dalam format teks bernama GreetingResources.txt untuk aplikasi konsol "Halo Dunia" sederhana. File teks menentukan dua string, prompt dan greeting, yang meminta pengguna untuk memasukkan nama mereka dan menampilkan salam.
# 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}!
File teks dikonversi ke file .resources dengan menggunakan perintah berikut:
resgen GreetingResources.txt
Contoh berikut menunjukkan kode sumber untuk aplikasi konsol yang menggunakan file .resources untuk menampilkan pesan kepada pengguna.
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!
Jika Anda menggunakan Visual Basic, dan file kode sumber diberi nama Greeting.vb, perintah berikut membuat file yang dapat dieksekusi yang menyertakan file .resources yang disematkan:
vbc greeting.vb -resource:GreetingResources.resources
Jika Anda menggunakan C#, dan file kode sumber diberi nama Greeting.cs, perintah berikut membuat file yang dapat dieksekusi yang menyertakan file .resources yang disematkan:
csc greeting.cs -resource:GreetingResources.resources
Sumber daya dalam file .resx
Tidak seperti file teks, yang hanya dapat menyimpan sumber daya string, file sumber daya XML (.resx) dapat menyimpan string, data biner seperti gambar, ikon, dan klip audio, dan objek terprogram. File .resx berisi header standar, yang menjelaskan format entri sumber daya dan menentukan informasi penerapan versi untuk XML yang digunakan untuk mengurai data. Data file sumber daya mengikuti header XML. Setiap item data terdiri dari pasangan nama/nilai yang terkandung dalam data tag. Atributnya name mendefinisikan nama sumber daya, dan tag berlapis value berisi nilai sumber daya. Untuk data string, value tag berisi string.
Misalnya, tag berikut data menentukan sumber daya string bernama prompt yang nilainya adalah "Masukkan nama Anda:".
<data name="prompt" xml:space="preserve">
<value>Enter your name:</value>
</data>
Peringatan
Jangan gunakan file sumber daya untuk menyimpan kata sandi, informasi yang sensitif keamanan, atau data privat.
Untuk objek sumber daya, tag data menyertakan type atribut yang menunjukkan jenis data sumber daya. Untuk objek yang terdiri dari data biner, data tag juga menyertakan mimetype atribut, yang menunjukkan base64 jenis data biner.
Catatan
Semua file .resx menggunakan formatter serialisasi biner untuk menghasilkan dan mengurai data biner untuk jenis yang ditentukan. Akibatnya, file .resx dapat menjadi tidak valid jika format serialisasi biner untuk objek berubah dengan cara yang tidak kompatibel.
Contoh berikut menunjukkan sebagian file .resx yang menyertakan Int32 sumber daya dan gambar bitmap.
<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>
Penting
Karena file .resx harus terdiri dari XML yang terbentuk dengan baik dalam format yang telah ditentukan sebelumnya, kami tidak menyarankan untuk bekerja dengan file .resx secara manual, terutama ketika file .resx berisi sumber daya selain string. Sebagai gantinya, Visual Studio menyediakan antarmuka transparan untuk membuat dan memanipulasi file .resx. Untuk informasi selengkapnya, lihat bagian File sumber daya di Visual Studio . Anda juga dapat membuat dan memanipulasi file .resx secara terprogram. Untuk informasi selengkapnya, lihat Bekerja dengan file .resx secara terprogram.
Sumber daya dalam file .resources
Anda dapat menggunakan System.Resources.ResourceWriter kelas untuk membuat file sumber daya biner (.resources) secara terprogram langsung dari kode. Anda juga dapat menggunakan Resource File Generator (resgen.exe) untuk membuat file .resources dari file teks atau file .resx. File .resources dapat berisi data biner (array byte) dan data objek selain data string. Membuat file .resources secara terprogram memerlukan langkah-langkah berikut:
Buat ResourceWriter objek dengan nama file unik. Anda dapat melakukan ini dengan menentukan nama file atau aliran file ke ResourceWriter konstruktor kelas.
Panggil salah satu kelebihan beban ResourceWriter.AddResource metode untuk setiap sumber daya bernama untuk ditambahkan ke file. Sumber daya dapat berupa string, objek, atau kumpulan data biner (array byte).
ResourceWriter.Close Panggil metode untuk menulis sumber daya ke file dan untuk menutup ResourceWriter objek.
Catatan
Jangan gunakan file sumber daya untuk menyimpan kata sandi, informasi yang sensitif keamanan, atau data privat.
Contoh berikut secara terprogram membuat file .resources bernama CarResources.resources yang menyimpan enam string, ikon, dan dua objek yang ditentukan aplikasi (dua Automobile objek). Kelas Automobile , yang didefinisikan dan dibuat dalam contoh, ditandai dengan SerializableAttribute atribut , yang memungkinkannya untuk dipertahankan oleh formatter serialisasi biner.
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
Setelah membuat file .resources, Anda dapat menyematkannya dalam run-time executable atau library dengan menyertakan sakelar pengkompilasi /resource bahasa, atau menyematkannya di rakitan satelit dengan menggunakan Assembly Linker (Al.exe).
File sumber daya di Visual Studio
Saat Anda menambahkan file sumber daya ke proyek Visual Studio, Visual Studio membuat file .resx di direktori proyek. Visual Studio menyediakan editor sumber daya yang memungkinkan Anda menambahkan string, gambar, dan objek biner. Karena editor dirancang untuk menangani data statis saja, editor tidak dapat digunakan untuk menyimpan objek terprogram; Anda harus menulis data objek ke file .resx atau ke file .resources secara terprogram. Untuk informasi selengkapnya, lihat Bekerja dengan file .resx secara terprogram dan bagian Sumber Daya di file .resources.
Jika Anda menambahkan sumber daya yang dilokalkan, beri nama file akar yang sama dengan file sumber daya utama. Anda juga harus menunjuk budaya mereka dalam nama file. Misalnya, jika Anda menambahkan file sumber daya bernama Resources.resx, Anda mungkin juga membuat file sumber daya bernama Resources.en-US.resx dan Resources.fr-FR.resx untuk menyimpan sumber daya yang dilokalkan untuk budaya Inggris (Amerika Serikat) dan Prancis (Prancis). Anda juga harus menunjuk budaya default aplikasi Anda. Ini adalah budaya yang sumber dayanya digunakan jika tidak ada sumber daya yang dilokalkan untuk budaya tertentu yang dapat ditemukan.
Untuk menentukan budaya default, dalam Penjelajah Solusi di Visual Studio:
- Buka properti proyek, klik kanan proyek dan pilih Properti (atau Alt + Enter saat proyek dipilih).
- Pilih tab Paket .
- Di area Umum, pilih bahasa/budaya yang sesuai dari kontrol bahasa netral Assembly.
- Simpan perubahan.
Pada waktu kompilasi, Visual Studio terlebih dahulu mengonversi file .resx dalam proyek ke file sumber daya biner (.resources) dan menyimpannya dalam subdirektori direktori obj proyek. Visual Studio menyematkan file sumber daya apa pun yang tidak berisi sumber daya yang dilokalkan di perakitan utama yang dihasilkan oleh proyek. Jika ada file sumber daya yang berisi sumber daya yang dilokalkan, Visual Studio menyematkannya dalam rakitan satelit terpisah untuk setiap budaya yang dilokalkan. Kemudian menyimpan setiap rakitan satelit dalam direktori yang namanya sesuai dengan budaya yang dilokalkan. Misalnya, sumber daya bahasa Inggris (Amerika Serikat) yang dilokalkan disimpan dalam rakitan satelit di subdirektori en-US.
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk