Mengemas dan menyebarkan sumber daya di aplikasi .NET

Aplikasi mengandalkan .NET Framework Resource Manager, yang ResourceManager diwakili oleh kelas , untuk mengambil sumber daya yang dilokalkan. Resource Manager mengasumsikan bahwa model hub dan spoke digunakan untuk mengemas dan menyebarkan sumber daya. Hub adalah rakitan utama yang berisi kode yang dapat dieksekusi yang tidak dapat diskalakan dan sumber daya untuk satu budaya, yang disebut budaya netral atau default. Budaya bawaan adalah budaya cadangan untuk aplikasi; ini adalah budaya yang sumber dayanya dipakai jika sumber daya yang dilokalisasi tidak dapat ditemukan. Setiap spoke terhubung ke rakitan satelit yang berisi sumber daya untuk satu budaya, tetapi tidak berisi kode apa pun.

Ada beberapa keuntungan dari model ini:

Anda dapat secara bertahap menambahkan sumber daya untuk budaya baru setelah Anda menyebarkan aplikasi. Karena pengembangan sumber daya khusus budaya berikutnya dapat membutuhkan waktu yang signifikan, ini memungkinkan Anda untuk merilis aplikasi utama Anda terlebih dahulu, dan memberikan sumber daya khusus budaya di kemudian hari.
Anda dapat memperbarui dan mengubah rakitan satelit aplikasi tanpa mengolah ulang aplikasi.
Aplikasi hanya perlu memuat rakitan satelit yang berisi sumber daya yang diperlukan untuk budaya tertentu. Ini dapat secara signifikan mengurangi penggunaan sumber daya sistem.

Namun, ada juga kerugian untuk model ini:

Anda harus mengelola beberapa set sumber daya.
Biaya awal pengujian aplikasi meningkat, karena Anda harus menguji beberapa konfigurasi. Perhatikan bahwa dalam jangka panjang akan lebih mudah dan lebih murah untuk menguji satu aplikasi inti dengan beberapa satelit, daripada menguji dan memelihara beberapa versi internasional paralel.

Konvensi penamaan sumber daya

Ketika Anda mengemas sumber daya aplikasi, Anda harus menamainya menggunakan konvensi penamaan sumber daya yang diharapkan oleh lingkungan runtime bahasa umum. Runtime mengidentifikasi sumber daya dengan nama budayanya. Setiap budaya diberi nama yang unik, yang biasanya merupakan kombinasi dari nama budaya huruf kecil dua huruf yang terkait dengan bahasa dan, jika diperlukan, nama subkultur dua huruf besar yang terkait dengan negara atau wilayah. Nama subkultur mengikuti nama budaya, dipisahkan oleh tanda hubung (-). Contohnya termasuk ja-JP untuk bahasa Jepang seperti yang diucapkan di Jepang, en-US untuk bahasa Inggris seperti yang diucapkan di Amerika Serikat, de-DE untuk bahasa Jerman seperti yang diucapkan di Jerman, atau de-AT untuk bahasa Jerman seperti yang diucapkan di Austria. Lihat kolom Tag bahasa dalam daftar nama bahasa/wilayah yang didukung oleh Windows. Nama budaya mengikuti standar yang ditentukan oleh BCP 47.

Nota

Ada beberapa pengecualian untuk nama budaya dua huruf, seperti zh-Hans untuk Bahasa Tionghoa (Disederhanakan).

Untuk informasi selengkapnya, lihat Membuat file sumber daya dan Membuat rakitan satelit.

Proses cadangan sumber daya

Model hub dan spoke untuk pengemasan dan penyebaran sumber daya menggunakan proses fallback untuk menemukan sumber daya yang sesuai. Jika aplikasi meminta sumber daya yang dilokalkan yang tidak tersedia, waktu proses bahasa umum mencari hierarki budaya untuk sumber daya cadangan yang paling sesuai dengan permintaan aplikasi pengguna, dan menghasilkan pengecualian hanya sebagai upaya terakhir. Pada setiap tingkat hierarki, jika sumber daya yang sesuai ditemukan, runtime menggunakannya. Jika sumber daya tidak ditemukan, pencarian berlanjut di tingkat berikutnya.

Untuk meningkatkan performa pencarian, terapkan NeutralResourcesLanguageAttribute atribut ke assembly utama Anda, dan berikan nama bahasa netral yang akan berfungsi dengan assembly utama Anda.

Proses pemulihan sumber daya .NET Framework

Proses fallback sumber daya .NET Framework melibatkan langkah-langkah berikut:

Petunjuk / Saran

Anda mungkin dapat menggunakan elemen konfigurasi <relativeBindForResources> untuk mengoptimalkan proses fallback sumber daya dan proses di mana runtime mencari rakitan sumber daya. Untuk informasi selengkapnya, lihat Mengoptimalkan proses fallback sumber daya.

Runtime pertama memeriksa global assembly cache untuk assembly yang sesuai dengan lingkungan budaya yang diminta untuk aplikasi Anda.

Cache rakitan global dapat menyimpan rakitan sumber daya yang dibagikan oleh banyak aplikasi. Ini membebaskan Anda dari harus menyertakan set sumber daya tertentu dalam struktur direktori setiap aplikasi yang Anda buat. Jika runtime menemukan referensi ke assembly, runtime akan mencari assembly untuk sumber daya yang diminta. Jika menemukan entri dalam perakitan, sistem menggunakan sumber daya yang diminta. Jika entri tidak ditemukan, pencarian akan dilanjutkan.
Runtime berikutnya memeriksa direktori rakitan yang saat ini dijalankan untuk subdirektori yang cocok dengan budaya yang diminta. Jika menemukan subdirektori, akan dilakukan pencarian dalam subdirektori tersebut untuk perakitan satelit yang valid bagi budaya yang diminta. Runtime kemudian mencari rakitan satelit untuk sumber daya yang diminta. Jika menemukan sumber daya di perakitan, sistem akan menggunakannya. Jika tidak menemukan sumber daya, proses pencarian akan dilanjutkan.
Runtime selanjutnya meminta Penginstal Windows untuk menentukan apakah rakitan satelit perlu diinstal sesuai permintaan. Jika demikian, ia menangani penginstalan, memuat komponen, dan mencari komponen atau sumber daya yang diminta. Jika menemukan sumber daya di perakitan, sistem akan menggunakannya. Jika tidak menemukan sumber daya, proses pencarian akan dilanjutkan.
Runtime memunculkan event AppDomain.AssemblyResolve untuk menunjukkan bahwa tidak dapat menemukan satellite assembly. Jika Anda memilih untuk menangani kejadian, pengendali peristiwa Anda dapat mengembalikan referensi ke assemblasi satelit yang sumber dayanya akan digunakan untuk pencarian. Jika tidak, penanganan aktivitas akan kembali null dan pencarian berlanjut.
Runtime berikutnya mencari cache assembly global lagi, kali ini untuk assembly induk dari kultur yang diminta. Jika rakitan induk ada di cache perakitan global, runtime mencari perakitan untuk sumber daya yang diminta.

Budaya induk ditetapkan sebagai budaya cadangan yang tepat. Anggap orang tua sebagai kandidat fallback, karena menyediakan sumber daya apa pun lebih disukai untuk memberikan pengecualian. Proses ini juga memungkinkan Anda untuk menggunakan kembali sumber daya. Anda harus menyertakan sumber daya tertentu di tingkat induk hanya jika budaya anak tidak perlu melokalisasi sumber daya yang diminta. Misalnya, jika Anda menyediakan rakitan satelit untuk en (bahasa Inggris netral), en-GB (bahasa Inggris dari Inggris), dan en-US (bahasa Inggris dari Amerika Serikat), en satelit akan berisi terminologi umum, dan en-GB serta en-US satelit dapat memberikan pembatalan hanya untuk istilah-istilah yang berbeda.
Runtime kemudian memeriksa direktori dari rakitan yang sedang dijalankan untuk menentukan apakah rakitan tersebut memiliki direktori induk. Jika direktori induk ada, runtime mencari direktori untuk rakitan satelit yang valid untuk budaya induk. Jika menemukan assembly, runtime mencari assembly untuk sumber daya yang diminta. Jika menemukan sumber daya, maka akan menggunakannya. Jika tidak menemukan sumber daya, proses pencarian akan dilanjutkan.
Runtime berikutnya meminta Penginstal Windows untuk menentukan apakah rakitan satelit induk akan diinstal sesuai permintaan. Jika demikian, ia menangani penginstalan, memuat komponen, dan mencari komponen atau sumber daya yang diminta. Jika menemukan sumber daya di perakitan, sistem akan menggunakannya. Jika tidak menemukan sumber daya, proses pencarian akan dilanjutkan.
Runtime memicu peristiwa AppDomain.AssemblyResolve untuk menunjukkan bahwa tidak dapat menemukan sumber daya fallback yang sesuai. Jika Anda memilih untuk menangani kejadian, pengendali peristiwa Anda dapat mengembalikan referensi ke assemblasi satelit yang sumber dayanya akan digunakan untuk pencarian. Jika tidak, penanganan aktivitas akan kembali null dan pencarian berlanjut.
Lingkungan eksekusi berikutnya memeriksa rakitan induk, seperti pada tiga langkah sebelumnya, melalui berbagai tingkat potensial. Setiap budaya hanya memiliki satu induk, yang didefinisikan oleh properti CultureInfo.Parent, tetapi induk mungkin memiliki induk sendiri. Pencarian budaya induk akan berhenti ketika properti Parent dari suatu budaya mengembalikan CultureInfo.InvariantCulture; dalam hal cadangan sumber daya, budaya invarian tidak dianggap sebagai budaya induk atau sebagai budaya yang dapat memiliki sumber daya.
Jika budaya yang awalnya ditentukan dan semua orang tua telah dicari dan sumber daya masih belum ditemukan, sumber daya untuk budaya default (fallback) digunakan. Biasanya, sumber daya untuk budaya default disertakan dalam perakitan aplikasi utama. Namun, Anda dapat menentukan nilai Satellite untuk properti Location atribut NeutralResourcesLanguageAttribute untuk menunjukkan bahwa lokasi cadangan terakhir untuk sumber daya adalah satelit assembly, bukan assembly utama.

Nota

Sumber daya default adalah satu-satunya sumber daya yang dapat dikompilasi dengan rakitan utama. Kecuali Anda menentukan rakitan satelit dengan menggunakan atribut NeutralResourcesLanguageAttribute, itu adalah cadangan utama (induk akhir). Oleh karena itu, kami sarankan Anda selalu menyertakan sekumpulan sumber daya default di perakitan utama Anda. Ini membantu mencegah terjadinya pengecualian. Dengan menyertakan file sumber daya default, Anda memberikan cadangan untuk semua sumber daya dan memastikan bahwa setidaknya satu sumber daya selalu tersedia untuk pengguna, meskipun tidak secara khusus sesuai budaya.
Terakhir, jika runtime tidak menemukan sumber daya untuk kebudayaan default (fallback), maka pengecualian MissingManifestResourceException atau MissingSatelliteAssemblyException akan dilemparkan untuk menunjukkan bahwa sumber daya tidak dapat ditemukan.

Misalnya, aplikasi meminta sumber daya yang dilokalkan untuk Spanyol (Meksiko) ( es-MX budaya). Runtime pertama mencari cache rakitan global untuk rakitan yang cocok es-MX, tetapi tidak menemukannya. Runtime kemudian mencari direktori assembly yang sedang dijalankan untuk sebuah direktori bernama es-MX. Gagal itu, runtime mencari cache perakitan global lagi untuk assembly induk yang mencerminkan budaya fallback yang sesuai — dalam hal ini, es (Spanyol). Jika rakitan induk tidak ditemukan, runtime mencari semua tingkat potensi rakitan induk untuk es-MX budaya sampai menemukan sumber daya yang sesuai. Jika sumber daya tidak ditemukan, runtime menggunakan sumber daya untuk budaya default.

Pengoptimalan proses bawaan sumber daya .NET Framework

Dalam kondisi berikut, Anda dapat mengoptimalkan proses di mana runtime mencari sumber daya di rakitan satelit:

Rakitan satelit disebarkan di lokasi yang sama dengan rakitan kode. Jika rakitan kode diinstal di Global Assembly Cache, rakitan satelit juga diinstal di cache perakitan global. Jika pemasangan kode diinstal di sebuah direktori, komponen satelit diinstal di folder yang spesifik untuk budaya dalam direktori tersebut.
Rakitan satelit tidak diinstal berdasarkan permintaan.
Kode aplikasi tidak menangani AppDomain.AssemblyResolve event.

Anda mengoptimalkan pemeriksaan untuk rakitan satelit dengan menyertakan <elemen relativeBindForResources> dan mengatur atributnya enabled ke true dalam file konfigurasi aplikasi, seperti yang ditunjukkan dalam contoh berikut.

<configuration>
   <runtime>
      <relativeBindForResources enabled="true" />
   </runtime>
</configuration>

Probe yang dioptimalkan untuk rakitan satelit adalah fitur pilihan. Artinya, waktu proses mengikuti langkah-langkah yang didokumenkan dalam Proses fallback sumber daya kecuali jika elemen <relativeBindForResources> ada dalam file konfigurasi aplikasi dan atribut enabled diatur ke true. Jika demikian, proses pemeriksaan untuk rakitan satelit dimodifikasi sebagai berikut:

Runtime menggunakan lokasi perakitan kode induk untuk menyelidiki perakitan satelit. Jika rakitan induk diinstal di cache perakitan global, runtime menyelidiki di cache namun tidak di direktori aplikasi. Jika assemblies induk diinstal dalam direktori aplikasi, runtime akan memeriksa di direktori aplikasi tetapi tidak di dalam cache global perakitan.
Runtime tidak mengkueri Penginstal Windows untuk penginstalan rakitan satelit sesuai permintaan.
Jika pemeriksaan untuk rakitan sumber daya tertentu gagal, runtime tidak memicu event AppDomain.AssemblyResolve.

Proses penggantian sumber daya .NET Core

Proses fallback sumber daya .NET Core melibatkan langkah-langkah berikut:

Runtime mencoba memuat rakitan satelit untuk budaya yang diminta.
- Memeriksa direktori dari assembly yang sedang dijalankan untuk subdirektori yang sesuai dengan lokalisasi yang diminta. Jika menemukan subdirektori, ia mencari perakitan satelit yang valid di subdirektori tersebut sesuai dengan budaya yang diminta dan memuatnya.
  
  Nota
  
  Pada sistem operasi dengan sistem berkas sensitif huruf besar/kecil (yaitu, Linux dan macOS), pencarian subdirektori dengan nama lokal peka terhadap huruf besar/kecil. Nama subdirektori harus persis sama dengan bentuk huruf (case sensitive) dari CultureInfo.Name (misalnya, es atau es-MX).
  
  Nota
  
  Jika programmer telah memperoleh konteks beban rakitan kustom dari AssemblyLoadContext, situasinya rumit. Jika rakitan yang dijalankan dimuat ke dalam konteks kustom, runtime memuat rakitan satelit ke dalam konteks kustom. Detailnya di luar cakupan untuk dokumen ini. Lihat AssemblyLoadContext.
- Jika rakitan satelit belum ditemukan, AssemblyLoadContext memicu peristiwa AssemblyLoadContext.Resolving untuk mengindikasikan bahwa ia tidak dapat menemukan rakitan satelit. Jika Anda memilih untuk menangani peristiwa, fungsi penanganan peristiwa Anda dapat memuat dan mengembalikan referensi ke perakitan satelit.
- Jika rakitan satelit masih belum ditemukan, AssemblyLoadContext menyebabkan AppDomain memicu AppDomain.AssemblyResolve peristiwa untuk menunjukkan bahwa tidak dapat menemukan rakitan satelit. Jika Anda memilih untuk menangani peristiwa, fungsi penanganan peristiwa Anda dapat memuat dan mengembalikan referensi ke perakitan satelit.
Jika rakitan satelit ditemukan, runtime mencarinya untuk sumber daya yang diminta. Jika menemukan sumber daya di perakitan, sistem akan menggunakannya. Jika tidak menemukan sumber daya, proses pencarian akan dilanjutkan.

Nota

Untuk menemukan sumber daya dalam assembly satelit, runtime mencari file sumber daya yang diminta oleh ResourceManager untuk CultureInfo.Name saat ini. Dalam file sumber daya, ia mencari nama sumber daya yang diminta. Jika keduanya tidak ditemukan, sumber daya diperlakukan sebagai tidak ditemukan.
Runtime berikutnya mencari rakitan budaya induk melalui banyak tingkat potensial, setiap kali mengulangi langkah 1 & 2.

Budaya induk didefinisikan sebagai budaya cadangan yang sesuai. Anggap orang tua sebagai kandidat fallback, karena menyediakan sumber daya apa pun lebih disukai untuk memberikan pengecualian. Proses ini juga memungkinkan Anda untuk menggunakan kembali sumber daya. Anda harus menyertakan sumber daya tertentu di tingkat induk hanya jika budaya anak tidak perlu melokalisasi sumber daya yang diminta. Misalnya, jika Anda menyediakan rakitan satelit untuk en (bahasa Inggris netral), en-GB (bahasa Inggris seperti yang diucapkan di Inggris), dan en-US (bahasa Inggris seperti yang diucapkan di Amerika Serikat), satelit en berisi terminologi umum, dan satelit en-GB serta en-US memberikan penggantian hanya untuk istilah-istilah yang berbeda.

Setiap budaya hanya memiliki satu induk, yang didefinisikan oleh properti CultureInfo.Parent, tetapi induk mungkin memiliki induk sendiri. Pencarian budaya induk berhenti ketika properti Parent dari budaya tersebut menjadi CultureInfo.InvariantCulture. Untuk fallback sumber daya, budaya invarian tidak dianggap sebagai budaya induk atau budaya yang dapat memiliki sumber daya.
Jika budaya yang awalnya ditentukan dan semua orang tua telah dicari dan sumber daya masih belum ditemukan, sumber daya untuk budaya default (fallback) digunakan. Biasanya, sumber daya untuk budaya default disertakan dalam perakitan aplikasi utama. Namun, Anda dapat menentukan nilai Satellite untuk properti Location guna menunjukkan bahwa lokasi fallback utama untuk sumber daya adalah perakitan satelit daripada perakitan utama.

Nota

Sumber daya default adalah satu-satunya sumber daya yang dapat dikompilasi dengan rakitan utama. Kecuali Anda menentukan rakitan satelit dengan menggunakan atribut NeutralResourcesLanguageAttribute, itu adalah cadangan utama (induk akhir). Oleh karena itu, kami sarankan Anda selalu menyertakan sekumpulan sumber daya default di perakitan utama Anda. Ini membantu mencegah terjadinya pengecualian. Dengan menyertakan file sumber daya default, Anda menyediakan fallback untuk semua sumber daya dan memastikan bahwa setidaknya satu sumber daya selalu ada untuk pengguna, meskipun tidak spesifik secara budaya.
Terakhir, jika runtime tidak menemukan file sumber daya untuk budaya default (fallback), pengecualian MissingManifestResourceException atau MissingSatelliteAssemblyException dilempar untuk menunjukkan bahwa sumber daya tidak dapat ditemukan. Jika file sumber daya ditemukan tetapi sumber daya yang diminta tidak ada, dan permintaan mengembalikan null.

Cadangan terakhir ke rakitan satelit

Anda dapat secara opsional menghapus sumber daya dari rakitan utama dan menentukan bahwa runtime harus memuat sumber daya fallback utama dari rakitan satelit yang sesuai dengan budaya tertentu. Untuk mengontrol proses fallback, Anda menggunakan NeutralResourcesLanguageAttribute(String, UltimateResourceFallbackLocation) konstruktor dan menyediakan nilai untuk UltimateResourceFallbackLocation parameter yang menentukan apakah Resource Manager harus mengekstrak sumber daya fallback dari rakitan utama atau dari rakitan satelit.

Contoh .NET Framework berikut memanfaatkan NeutralResourcesLanguageAttribute atribut guna penyimpanan sumber daya cadangan aplikasi dalam rakitan satelit dalam bahasa Prancis (fr). Contohnya memiliki dua file sumber daya berbasis teks yang menentukan satu sumber daya string bernama Greeting. Yang pertama, resources.fr.txt, berisi sumber daya bahasa Prancis.

Greeting=Bon jour!

Yang kedua, sumber daya,ru.txt, berisi sumber daya bahasa Rusia.

Greeting=Добрый день

Kedua file ini dikompilasi ke file .resources dengan menjalankan Resource File Generator (resgen.exe) dari baris perintah. Untuk sumber daya bahasa Prancis, perintahnya adalah:

resgen.exe resources.fr.txt

Untuk sumber daya bahasa Rusia, perintahnya adalah:

resgen.exe resources.ru.txt

File .resources disematkan ke dalam pustaka tautan dinamis dengan menjalankan Assembly Linker (al.exe) dari baris perintah untuk sumber daya bahasa Prancis sebagai berikut:

al /t:lib /embed:resources.fr.resources /culture:fr /out:fr\Example1.resources.dll

dan untuk sumber daya bahasa Rusia sebagai berikut:

al /t:lib /embed:resources.ru.resources /culture:ru /out:ru\Example1.resources.dll

Kode sumber aplikasi berada dalam file bernama Example1.cs atau Example1.vb. Ini termasuk NeutralResourcesLanguageAttribute atribut untuk menunjukkan bahwa sumber daya aplikasi default berada di subdirektori fr. Ini membuat instans Resource Manager, mengambil nilai Greeting sumber daya, dan menampilkannya di konsol.

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

[assembly:NeutralResourcesLanguage("fr", UltimateResourceFallbackLocation.Satellite)]

public class Example
{
   public static void Main()
   {
      ResourceManager rm = new ResourceManager("resources",
                                               typeof(Example).Assembly);
      string greeting = rm.GetString("Greeting");
      Console.WriteLine(greeting);
   }
}

Imports System.Reflection
Imports System.Resources

<Assembly: NeutralResourcesLanguage("fr", UltimateResourceFallbackLocation.Satellite)>
Module Example
    Public Sub Main()
        Dim rm As New ResourceManager("resources", GetType(Example).Assembly)
        Dim greeting As String = rm.GetString("Greeting")
        Console.WriteLine(greeting)
    End Sub
End Module

Anda kemudian dapat mengkompilasi kode sumber C# dari baris perintah sebagai berikut:

csc Example1.cs

Perintah untuk pengkompilasi Visual Basic sangat mirip:

vbc Example1.vb

Karena tidak ada sumber daya yang disematkan di rakitan utama, Anda tidak perlu mengkompilasi dengan menggunakan sakelar /resource .

Saat Anda menjalankan contoh dari sistem yang bahasanya apa pun selain Bahasa Rusia, contoh tersebut akan menampilkan output berikut:

Bon jour!

Alternatif pengemasan yang disarankan

Batasan waktu atau anggaran dapat mencegah Anda membuat sekumpulan sumber daya untuk setiap subkultur yang didukung aplikasi Anda. Sebagai gantinya, Anda dapat membuat satu rakitan satelit untuk budaya induk yang dapat digunakan semua subkultur terkait. Misalnya, Anda dapat menyediakan satu komponen satelit Bahasa Inggris (en) yang tersedia bagi pengguna yang meminta sumber daya Bahasa Inggris khusus wilayah, dan satu komponen satelit Jerman (de) bagi pengguna yang meminta sumber daya Bahasa Jerman khusus wilayah. Misalnya, permintaan untuk bahasa Jerman seperti yang diucapkan di Jerman (de-DE), Austria (de-AT), dan Swiss (de-CH) akan kembali ke perakitan satelit Jerman (de). Sumber daya default adalah fallback akhir dan oleh karena itu harus menjadi sumber daya yang akan diminta oleh sebagian besar pengguna aplikasi Anda, jadi pilih sumber daya ini dengan hati-hati. Pendekatan ini menyebarkan sumber daya yang kurang spesifik secara budaya, tetapi dapat secara signifikan mengurangi biaya pelokalan aplikasi Anda.

Lihat juga

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-06-17