Menggunakan Sistem Manajemen Sumber Daya Windows 10 di aplikasi atau game warisan
Aplikasi dan game .NET dan Win32 sering dilokalkan ke dalam bahasa yang berbeda untuk memperluas total pasar yang dapat diatasi. Untuk informasi selengkapnya tentang proposisi nilai pelokalan aplikasi Anda, lihat Globalisasi dan pelokalan. Dengan mengemas aplikasi atau game .NET atau Win32 Anda sebagai paket .msix atau .appx, Anda dapat memanfaatkan Sistem Manajemen Sumber Daya untuk memuat sumber daya aplikasi yang disesuaikan dengan konteks run-time. Topik mendalam ini menjelaskan tekniknya.
Ada banyak cara untuk melokalisasi aplikasi Win32 tradisional, tetapi Windows 8 memperkenalkan sistem manajemen sumber daya baru yang berfungsi di seluruh bahasa pemrograman, di seluruh jenis aplikasi, dan menyediakan fungsionalitas di atas dan di atas pelokalan sederhana. Sistem ini akan disebut sebagai "MRT" dalam topik ini. Secara historis, itu berdiri untuk "Teknologi Sumber Daya Modern" tetapi istilah "Modern" telah dihentikan. Manajer sumber daya mungkin juga dikenal sebagai MRM (Modern Resource Manager) atau PRI (Indeks Sumber Daya Paket).
Dikombinasikan dengan penyebaran berbasis MSIX atau berbasis .appx (misalnya, dari Microsoft Store), MRT dapat secara otomatis mengirimkan sumber daya yang paling berlaku untuk pengguna/perangkat tertentu yang meminimalkan ukuran unduhan dan penginstalan aplikasi Anda. Pengurangan ukuran ini dapat signifikan untuk aplikasi dengan sejumlah besar konten yang dilokalkan, mungkin pada urutan beberapa gigabyte untuk game AAA. Manfaat tambahan MRT termasuk daftar yang dilokalkan di Windows Shell dan Microsoft Store, logika fallback otomatis saat bahasa pilihan pengguna tidak cocok dengan sumber daya yang tersedia.
Dokumen ini menjelaskan arsitektur MRT tingkat tinggi dan menyediakan panduan porting untuk membantu memindahkan aplikasi Win32 warisan ke MRT dengan perubahan kode minimal. Setelah perpindahan ke MRT dibuat, manfaat tambahan (seperti kemampuan untuk mensegmentasi sumber daya berdasarkan faktor skala atau tema sistem) tersedia untuk pengembang. Perhatikan bahwa pelokalan berbasis MRT berfungsi untuk aplikasi UWP dan aplikasi Win32 yang diproses oleh Desktop Bridge (alias "Centennial").
Dalam banyak situasi, Anda dapat terus menggunakan format pelokalan dan kode sumber yang ada sambil mengintegrasikan dengan MRT untuk menyelesaikan sumber daya pada runtime dan meminimalkan ukuran unduhan - ini bukan pendekatan semua atau tidak sama sekali. Tabel berikut ini meringkas pekerjaan dan perkiraan biaya/manfaat setiap tahap. Tabel ini tidak menyertakan tugas non-pelokalan, seperti menyediakan ikon aplikasi resolusi tinggi atau kontras tinggi. Untuk informasi selengkapnya tentang menyediakan beberapa aset untuk petak peta, ikon, dll., Lihat Menyesuaikan sumber daya Anda untuk bahasa, skala, kontras tinggi, dan kualifikasi lainnya.
Kerja | Keuntungan | Perkiraan biaya |
---|---|---|
Melokalisasi manifes paket | Pekerjaan minimum kosong diperlukan agar konten yang dilokalkan muncul di Windows Shell dan di Microsoft Store | Bentuk dan |
Menggunakan MRT untuk mengidentifikasi dan menemukan sumber daya | Prasyarat untuk meminimalkan ukuran pengunduhan dan penginstalan; fallback bahasa otomatis | Medium |
Membangun paket sumber daya | Langkah terakhir untuk meminimalkan ukuran pengunduhan dan penginstalan | Bentuk dan |
Bermigrasi ke format sumber daya MRT dan API | Ukuran file yang jauh lebih kecil (tergantung pada teknologi sumber daya yang ada) | Bentuk dan |
Pendahuluan
Sebagian besar aplikasi non-sepele berisi elemen antarmuka pengguna yang dikenal sebagai sumber daya yang dipisahkan dari kode aplikasi (kontras dengan nilai yang dikodekan secara permanen yang ditulis dalam kode sumber itu sendiri). Ada beberapa alasan untuk lebih memilih sumber daya daripada nilai yang dikodekan secara permanen - kemudahan pengeditan oleh non-pengembang, misalnya - tetapi salah satu alasan utamanya adalah untuk memungkinkan aplikasi memilih representasi yang berbeda dari sumber daya logis yang sama saat runtime. Misalnya, teks yang akan ditampilkan pada tombol (atau gambar yang ditampilkan dalam ikon) mungkin berbeda tergantung pada bahasa yang dipahami pengguna, karakteristik perangkat tampilan, atau apakah pengguna mengaktifkan teknologi bantuan.
Dengan demikian tujuan utama dari teknologi manajemen sumber daya apa pun adalah untuk menerjemahkan, pada runtime, permintaan untuk nama sumber daya logis atau simbolis (seperti SAVE_BUTTON_LABEL
) ke nilai aktualterbaik (misalnya, "Simpan") dari sekumpulan kandidat yang mungkin (misalnya, "Simpan", "Speichern", atau "저장"). MRT menyediakan fungsi seperti itu, dan memungkinkan aplikasi mengidentifikasi kandidat sumber daya menggunakan berbagai atribut, yang disebut kualifikasi, seperti bahasa pengguna, faktor skala tampilan, tema yang dipilih pengguna, dan faktor lingkungan lainnya. MRT bahkan mendukung kualifikasi kustom untuk aplikasi yang membutuhkannya (misalnya, aplikasi dapat menyediakan aset grafis yang berbeda untuk pengguna yang telah masuk dengan akun vs. pengguna tamu, tanpa secara eksplisit menambahkan pemeriksaan ini ke setiap bagian aplikasi mereka). MRT bekerja dengan sumber daya string dan sumber daya berbasis file, di mana sumber daya berbasis file diimplementasikan sebagai referensi ke data eksternal (file itu sendiri).
Contoh
Berikut adalah contoh sederhana aplikasi yang memiliki label teks pada dua tombol (openButton
dan saveButton
) dan file PNG yang digunakan untuk logo (logoImage
). Label teks dilokalkan ke dalam bahasa Inggris dan Jerman, dan logo dioptimalkan untuk tampilan desktop normal (faktor skala 100%) dan ponsel resolusi tinggi (faktor skala 300%). Perhatikan bahwa diagram ini menyajikan tampilan konseptual model tingkat tinggi; tidak memetakan dengan tepat ke implementasi.
Dalam grafik, kode aplikasi mereferensikan tiga nama sumber daya logis. Saat runtime, GetResource
fungsi pseudo menggunakan MRT untuk melihat nama sumber daya tersebut di tabel sumber daya (dikenal sebagai file PRI) dan menemukan kandidat yang paling tepat berdasarkan kondisi sekitar (bahasa pengguna dan faktor skala tampilan). Dalam kasus label, string digunakan secara langsung. Dalam kasus gambar logo, string ditafsirkan sebagai nama file dan file dibaca dari disk.
Jika pengguna berbicara bahasa selain bahasa Inggris atau Jerman, atau memiliki faktor skala tampilan selain 100% atau 300%, MRT memilih kandidat yang cocok "terdekat" berdasarkan serangkaian aturan fallback (lihat Sistem Manajemen Sumber Daya untuk latar belakang lebih lanjut).
Perhatikan bahwa MRT mendukung sumber daya yang disesuaikan dengan lebih dari satu kualifikasi - misalnya, jika gambar logo berisi teks tersemat yang juga perlu dilokalkan, logo akan memiliki empat kandidat: EN/Scale-100, DE/Scale-100, EN/Scale-300 dan DE/Scale-300.
Bagian dalam dokumen ini
Bagian berikut menguraikan tugas tingkat tinggi yang diperlukan untuk mengintegrasikan MRT dengan aplikasi Anda.
Fase 0: Membangun paket aplikasi
Bagian ini menguraikan cara membuat aplikasi Desktop yang ada sebagai paket aplikasi. Tidak ada fitur MRT yang digunakan pada tahap ini.
Fase 1: Melokalkan manifes aplikasi
Bagian ini menguraikan cara melokalisasi manifes aplikasi Anda (sehingga muncul dengan benar di Windows Shell) sementara masih menggunakan format sumber daya warisan dan API Anda untuk mengemas dan menemukan sumber daya.
Fase 2: Gunakan MRT untuk mengidentifikasi dan menemukan sumber daya
Bagian ini menguraikan cara memodifikasi kode aplikasi Anda (dan mungkin tata letak sumber daya) untuk menemukan sumber daya menggunakan MRT, sementara masih menggunakan format sumber daya dan API yang ada untuk memuat dan menggunakan sumber daya.
Fase 3: Membangun paket sumber daya
Bagian ini menguraikan perubahan akhir yang diperlukan untuk memisahkan sumber daya Anda menjadi paket sumber daya terpisah, meminimalkan ukuran unduhan (dan penginstalan) aplikasi Anda.
Tidak tercakup dalam dokumen ini
Setelah menyelesaikan Fase 0-3 di atas, Anda akan memiliki "bundel" aplikasi yang dapat dikirimkan ke Microsoft Store dan yang akan meminimalkan ukuran pengunduhan dan penginstalan untuk pengguna dengan menghilangkan sumber daya yang tidak mereka butuhkan (misalnya, bahasa yang tidak mereka bicarakan). Peningkatan lebih lanjut dalam ukuran aplikasi dan fungsionalitas dapat dilakukan dengan mengambil satu langkah terakhir.
Fase 4: Bermigrasi ke format dan API sumber daya MRT
Fase ini berada di luar cakupan dokumen ini; ini memerlukan pemindahan sumber daya Anda (terutama string) dari format warisan seperti DLL MUI atau rakitan sumber daya .NET ke dalam file PRI. Ini dapat menyebabkan penghematan ruang lebih lanjut untuk ukuran pengunduhan & pemasangan. Ini juga memungkinkan penggunaan fitur MRT lainnya seperti meminimalkan pengunduhan dan penginstalan file gambar berdasarkan faktor skala, pengaturan aksesibilitas, dan sebagainya.
Fase 0: Membangun paket aplikasi
Sebelum membuat perubahan pada sumber daya aplikasi, Anda harus terlebih dahulu mengganti teknologi pengemasan dan penginstalan Anda saat ini dengan teknologi pengemasan dan penyebaran UWP standar. Ada tiga cara untuk melakukannya:
- Jika Anda memiliki aplikasi desktop besar dengan alat penginstal kompleks atau Anda menggunakan banyak titik ekstensibilitas OS, Anda dapat menggunakan alat Pengonversi Aplikasi Desktop untuk menghasilkan tata letak file UWP dan informasi manifes dari penginstal aplikasi yang ada (misalnya, MSI).
- Jika Anda memiliki aplikasi desktop yang lebih kecil dengan file yang relatif sedikit atau alat penginstal sederhana dan tanpa kait ekstensibilitas, Anda dapat membuat tata letak file dan informasi manifes secara manual.
- Jika Anda membangun kembali dari sumber dan ingin memperbarui aplikasi Anda menjadi aplikasi UWP murni, Anda dapat membuat proyek baru di Visual Studio dan mengandalkan IDE untuk melakukan banyak pekerjaan untuk Anda.
Jika Anda ingin menggunakan Pengonversi Aplikasi Desktop, lihat Mengemas aplikasi desktop menggunakan Pengonversi Aplikasi Desktop untuk informasi selengkapnya tentang proses konversi. Serangkaian sampel Konverter Desktop lengkap dapat ditemukan di repositori GitHub sampel Desktop Bridge ke UWP.
Jika Anda ingin membuat paket secara manual, Anda harus membuat struktur direktori yang mencakup semua file aplikasi Anda (dapat dieksekusi dan konten, tetapi bukan kode sumber) dan file manifes paket (.appxmanifest). Contoh dapat ditemukan dalam sampel Hello, World GitHub, tetapi file manifes paket dasar yang menjalankan desktop yang dapat dieksekusi bernama ContosoDemo.exe
sebagai berikut, di mana teks yang disorot akan digantikan oleh nilai Anda sendiri.
<?xml version="1.0" encoding="utf-8" ?>
<Package xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
xmlns:mp="http://schemas.microsoft.com/appx/2014/phone/manifest"
xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"
xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"
IgnorableNamespaces="uap mp rescap">
<Identity Name="Contoso.Demo"
Publisher="CN=Contoso.Demo"
Version="1.0.0.0" />
<Properties>
<DisplayName>Contoso App</DisplayName>
<PublisherDisplayName>Contoso, Inc</PublisherDisplayName>
<Logo>Assets\StoreLogo.png</Logo>
</Properties>
<Dependencies>
<TargetDeviceFamily Name="Windows.Desktop" MinVersion="10.0.14393.0"
MaxVersionTested="10.0.14393.0" />
</Dependencies>
<Resources>
<Resource Language="en-US" />
</Resources>
<Applications>
<Application Id="ContosoDemo" Executable="ContosoDemo.exe"
EntryPoint="Windows.FullTrustApplication">
<uap:VisualElements DisplayName="Contoso Demo" BackgroundColor="#777777"
Square150x150Logo="Assets\Square150x150Logo.png"
Square44x44Logo="Assets\Square44x44Logo.png"
Description="Contoso Demo">
</uap:VisualElements>
</Application>
</Applications>
<Capabilities>
<rescap:Capability Name="runFullTrust" />
</Capabilities>
</Package>
Untuk informasi selengkapnya tentang file manifes paket dan tata letak paket, lihat Manifes paket aplikasi.
Terakhir, jika Anda menggunakan Visual Studio untuk membuat proyek baru dan memigrasikan kode yang ada, lihat Membuat aplikasi "Halo, dunia". Anda dapat menyertakan kode yang ada ke dalam proyek baru, tetapi Anda mungkin harus membuat perubahan kode yang signifikan (terutama di antarmuka pengguna) untuk berjalan sebagai aplikasi UWP murni. Perubahan ini berada di luar lingkup dokumen ini.
Fase 1: Melokalkan manifes
Langkah 1.1: Memperbarui string & aset dalam manifes
Pada Fase 0 Anda membuat file manifes paket dasar (.appxmanifest) untuk aplikasi Anda (berdasarkan nilai yang disediakan untuk pengonversi, diekstrak dari MSI, atau dimasukkan secara manual ke dalam manifes) tetapi tidak akan berisi informasi yang dilokalkan, juga tidak akan mendukung fitur tambahan seperti aset petak peta Mulai resolusi tinggi, dll.
Untuk memastikan nama dan deskripsi aplikasi Anda dilokalkan dengan benar, Anda harus menentukan beberapa sumber daya dalam sekumpulan file sumber daya, dan memperbarui manifes paket untuk mereferensikannya.
Membuat file sumber daya default
Langkah pertama adalah membuat file sumber daya default dalam bahasa default Anda (misalnya, Bahasa Inggris AS). Anda dapat melakukan ini secara manual dengan editor teks, atau melalui Resource Designer di Visual Studio.
Jika Anda ingin membuat sumber daya secara manual:
- Buat file XML bernama
resources.resw
dan letakkan diStrings\en-us
subfolder proyek Anda. Gunakan kode BCP-47 yang sesuai jika bahasa default Anda bukan bahasa Inggris AS. - Dalam file XML, tambahkan konten berikut, di mana teks yang disorot diganti dengan teks yang sesuai untuk aplikasi Anda, dalam bahasa default Anda.
Catatan
Ada batasan pada panjang beberapa string ini. Untuk informasi selengkapnya, lihat VisualElements.
<?xml version="1.0" encoding="utf-8"?>
<root>
<data name="ApplicationDescription">
<value>Contoso Demo app with localized resources (English)</value>
</data>
<data name="ApplicationDisplayName">
<value>Contoso Demo Sample (English)</value>
</data>
<data name="PackageDisplayName">
<value>Contoso Demo Package (English)</value>
</data>
<data name="PublisherDisplayName">
<value>Contoso Samples, USA</value>
</data>
<data name="TileShortName">
<value>Contoso (EN)</value>
</data>
</root>
Jika Anda ingin menggunakan perancang di Visual Studio:
Strings\en-us
Buat folder (atau bahasa lain yang sesuai) di proyek Anda dan tambahkan Item Baru ke folder akar proyek Anda, menggunakan namaresources.resw
default . Pastikan untuk memilih File Sumber Daya (.resw) dan bukan Kamus Sumber Daya - Kamus Sumber Daya adalah file yang digunakan oleh aplikasi XAML.- Menggunakan perancang, masukkan string berikut (gunakan yang sama
Names
tetapi gantiValues
dengan teks yang sesuai untuk aplikasi Anda):
Catatan
Jika Anda mulai dengan desainer Visual Studio, Anda selalu dapat mengedit XML secara langsung dengan menekan F7
. Tetapi jika Anda mulai dengan file XML minimal, perancang tidak akan mengenali file karena kehilangan banyak metadata tambahan; Anda dapat memperbaikinya dengan menyalin informasi XSD boilerplate dari file yang dihasilkan desainer ke dalam file XML yang diedit tangan Anda.
Memperbarui manifes untuk mereferensikan sumber daya
Setelah Anda memiliki nilai yang ditentukan dalam .resw
file, langkah selanjutnya adalah memperbarui manifes untuk mereferensikan string sumber daya. Sekali lagi, Anda dapat mengedit file XML secara langsung, atau mengandalkan Visual Studio Manifest Designer.
Jika Anda mengedit XML secara langsung, buka AppxManifest.xml
file dan buat perubahan berikut pada nilai yang disorot - gunakan teks yang tepat ini, bukan teks khusus untuk aplikasi Anda. Tidak ada persyaratan untuk menggunakan nama sumber daya yang tepat ini—Anda dapat memilih nama Anda sendiri—tetapi apa pun yang Anda pilih harus sama persis dengan apa pun yang ada dalam .resw
file. Nama-nama ini harus cocok dengan yang Names
Anda buat dalam .resw
file, diawali dengan ms-resource:
skema dan Resources/
namespace.
Catatan
Banyak elemen manifes telah dihilangkan dari cuplikan ini - jangan hapus apa pun!
<?xml version="1.0" encoding="utf-8"?>
<Package>
<Properties>
<DisplayName>ms-resource:Resources/PackageDisplayName</DisplayName>
<PublisherDisplayName>ms-resource:Resources/PublisherDisplayName</PublisherDisplayName>
</Properties>
<Applications>
<Application>
<uap:VisualElements DisplayName="ms-resource:Resources/ApplicationDisplayName"
Description="ms-resource:Resources/ApplicationDescription">
<uap:DefaultTile ShortName="ms-resource:Resources/TileShortName">
<uap:ShowNameOnTiles>
<uap:ShowOn Tile="square150x150Logo" />
</uap:ShowNameOnTiles>
</uap:DefaultTile>
</uap:VisualElements>
</Application>
</Applications>
</Package>
Jika Anda menggunakan perancang manifes Visual Studio, buka file .appxmanifest dan ubah nilai yang disorot di tab *Aplikasi dan tab Kemasan:
Langkah 1.2: Buat file PRI, buat paket MSIX, dan verifikasi bahwa file tersebut berfungsi
Anda sekarang dapat membangun .pri
file dan menyebarkan aplikasi untuk memverifikasi bahwa informasi yang benar (dalam bahasa default Anda) muncul di Menu Mulai.
Jika Anda membangun di Visual Studio, cukup tekan Ctrl+Shift+B
untuk membangun proyek lalu klik kanan pada proyek dan pilih Deploy
dari menu konteks.
Jika Anda membangun secara manual, ikuti langkah-langkah ini untuk membuat file konfigurasi untuk MakePRI
alat dan membuat file itu .pri
sendiri (informasi lebih lanjut dapat ditemukan di Kemasan aplikasi manual):
Buka perintah pengembang dari folder Visual Studio 2017 atau Visual Studio 2019 di menu Mulai.
Beralih ke direktori akar proyek (yang berisi file .appxmanifest dan folder String).
Ketik perintah berikut, ganti "contoso_demo.xml" dengan nama yang cocok untuk proyek Anda, dan "en-US" dengan bahasa default aplikasi Anda (atau pertahankan en-US jika berlaku). Perhatikan bahwa file XML dibuat di direktori induk (bukan di direktori proyek) karena bukan bagian dari aplikasi (Anda dapat memilih direktori lain yang Anda inginkan, tetapi pastikan untuk menggantinya di perintah mendatang).
makepri createconfig /cf ..\contoso_demo.xml /dq en-US /pv 10.0 /o
Anda dapat mengetik
makepri createconfig /?
untuk melihat apa yang dilakukan setiap parameter, tetapi dalam ringkasan:/cf
mengatur Nama File Konfigurasi (output perintah ini)/dq
mengatur Kualifikasi Default, dalam hal ini bahasaen-US
/pv
mengatur Versi Platform, dalam hal ini Windows 10/o
mengaturnya untuk Menimpa file output jika ada
Sekarang Anda memiliki file konfigurasi, jalankan
MakePRI
lagi untuk benar-benar mencari sumber daya disk dan mengemasnya ke dalam file PRI. Ganti "contoso_demop.xml" dengan nama file XML yang Anda gunakan di langkah sebelumnya, dan pastikan untuk menentukan direktori induk untuk input dan output:makepri new /pr . /cf ..\contoso_demo.xml /of ..\resources.pri /mf AppX /o
Anda dapat mengetik
makepri new /?
untuk melihat apa yang dilakukan setiap parameter, tetapi singkatnya:/pr
mengatur Akar Proyek (dalam hal ini, direktori saat ini)/cf
mengatur Nama File Konfigurasi, yang dibuat di langkah sebelumnya/of
mengatur File Output/mf
membuat File Pemetaan (sehingga kita dapat mengecualikan file dalam paket di langkah selanjutnya)/o
mengaturnya untuk Menimpa file output jika ada
Sekarang Anda memiliki
.pri
file dengan sumber daya bahasa default (misalnya, en-US). Untuk memverifikasi bahwa ini berfungsi dengan benar, Anda bisa menjalankan perintah berikut:makepri dump /if ..\resources.pri /of ..\resources /o
Anda dapat mengetik
makepri dump /?
untuk melihat apa yang dilakukan setiap parameter, tetapi singkatnya:/if
mengatur Nama File Input/of
mengatur Nama File Output (.xml
akan ditambahkan secara otomatis)/o
mengaturnya untuk Menimpa file output jika ada
Terakhir, Anda dapat membuka
..\resources.xml
di editor teks dan memverifikasinya mencantumkan nilai Anda<NamedResource>
(sepertiApplicationDescription
danPublisherDisplayName
) bersama dengan<Candidate>
nilai untuk bahasa default yang Anda pilih (akan ada konten lain di awal file; abaikan itu untuk saat ini).
Anda dapat membuka file pemetaan untuk memverifikasi bahwa file ..\resources.map.txt
tersebut berisi file yang diperlukan untuk proyek Anda (termasuk file PRI, yang bukan bagian dari direktori proyek). Pentingnya, file pemetaan tidak akan menyertakan referensi ke file Anda resources.resw
karena konten file tersebut telah disematkan dalam file PRI. Namun, ini akan berisi sumber daya lain seperti nama file gambar Anda.
Membangun dan menandatangani paket
Sekarang file PRI dibuat, Anda dapat membangun dan menandatangani paket:
Untuk membuat paket aplikasi, jalankan perintah
contoso_demo.appx
berikut mengganti dengan nama file .msix/.appx yang ingin Anda buat dan pastikan untuk memilih direktori yang berbeda untuk file (sampel ini menggunakan direktori induk; dapat berada di mana saja tetapi tidak boleh menjadi direktori proyek).makeappx pack /m AppXManifest.xml /f ..\resources.map.txt /p ..\contoso_demo.appx /o
Anda dapat mengetik
makeappx pack /?
untuk melihat apa yang dilakukan setiap parameter, tetapi singkatnya:/m
mengatur file Manifes yang akan digunakan/f
mengatur File pemetaan yang akan digunakan (dibuat pada langkah sebelumnya)/p
mengatur nama Paket output/o
mengaturnya untuk Menimpa file output jika ada
Setelah paket dibuat, paket harus ditandatangani. Cara term mudah untuk mendapatkan sertifikat penandatanganan adalah dengan membuat proyek Universal Windows kosong di Visual Studio dan menyalin
.pfx
file yang dibuatnya, tetapi Anda dapat membuatnya secara manual menggunakanMakeCert
utilitas danPvk2Pfx
seperti yang dijelaskan dalam Cara membuat sertifikat penandatanganan paket aplikasi.Penting
Jika Anda membuat sertifikat penandatanganan secara manual, pastikan Anda menempatkan file di direktori yang berbeda dari proyek sumber atau sumber paket Anda, jika tidak, itu mungkin disertakan sebagai bagian dari paket, termasuk kunci privat!
Untuk menandatangani paket, gunakan perintah berikut. Perhatikan bahwa yang
Publisher
ditentukan dalamIdentity
elemenAppxManifest.xml
harus cocokSubject
dengan sertifikat (ini bukan<PublisherDisplayName>
elemen, yang merupakan nama tampilan yang dilokalkan untuk ditampilkan kepada pengguna). Seperti biasa, ganticontoso_demo...
nama file dengan nama yang sesuai untuk proyek Anda, dan (sangat penting) pastikan.pfx
file tidak ada di direktori saat ini (jika tidak, file tersebut akan dibuat sebagai bagian dari paket Anda, termasuk kunci penandatanganan privat!):signtool sign /fd SHA256 /a /f ..\contoso_demo_key.pfx ..\contoso_demo.appx
Anda dapat mengetik
signtool sign /?
untuk melihat apa yang dilakukan setiap parameter, tetapi singkatnya:/fd
mengatur algoritma File Digest (SHA256 adalah default untuk .appx)/a
akan secara otomatis memilih sertifikat terbaik/f
menentukan File input yang berisi sertifikat penandatanganan
Terakhir, Anda sekarang dapat mengklik dua kali pada .appx
file untuk menginstalnya, atau jika Anda lebih suka baris perintah, Anda dapat membuka prompt PowerShell, mengubah ke direktori yang berisi paket, dan mengetik yang berikut (mengganti contoso_demo.appx
dengan nama paket Anda):
add-appxpackage contoso_demo.appx
Jika Anda menerima kesalahan tentang sertifikat yang tidak tepercaya, pastikan sertifikat ditambahkan ke penyimpanan mesin (bukan penyimpanan pengguna). Untuk menambahkan sertifikat ke penyimpanan komputer, Anda dapat menggunakan baris perintah atau Windows Explorer.
Untuk menggunakan baris perintah:
Jalankan perintah Visual Studio 2017 atau Visual Studio 2019 sebagai Administrator.
Beralih ke direktori yang berisi
.cer
file (ingatlah untuk memastikan ini berada di luar sumber atau direktori proyek Anda!)Ketik perintah berikut, ganti
contoso_demo.cer
dengan nama file Anda:certutil -addstore TrustedPeople contoso_demo.cer
Anda dapat menjalankan
certutil -addstore /?
untuk melihat apa yang dilakukan setiap parameter, tetapi singkatnya:-addstore
menambahkan sertifikat ke penyimpanan sertifikatTrustedPeople
menunjukkan penyimpanan tempat sertifikat ditempatkan
Untuk menggunakan Windows Explorer:
- Navigasi ke folder yang berisi
.pfx
file - Klik dua kali pada
.pfx
file dan Wizard Impor Certicicate akan muncul - Pilih
Local Machine
dan klikNext
- Terima perintah elevasi admin Kontrol Akun Pengguna, jika muncul, dan klik
Next
- Masukkan kata sandi untuk kunci privat, jika ada, dan klik
Next
- Pilih
Place all certificates in the following store
- Klik
Browse
, dan pilihTrusted People
folder (bukan "Penerbit Tepercaya") - Klik
Next
laluFinish
Setelah menambahkan sertifikat ke penyimpanan Trusted People
, coba instal paket lagi.
Sekarang Anda akan melihat aplikasi Anda muncul di daftar "Semua Aplikasi" Menu Mulai, dengan informasi yang benar dari .resw
/ .pri
file. Jika Anda melihat string kosong atau string ms-resource:...
, maka ada yang salah - periksa kembali pengeditan Anda dan pastikan string tersebut benar. Jika Anda mengklik kanan aplikasi di Menu Mulai, Anda dapat menyematkannya sebagai petak peta dan memverifikasi bahwa informasi yang benar juga ditampilkan di sana.
Langkah 1.3: Menambahkan lebih banyak bahasa yang didukung
Setelah perubahan dilakukan pada manifes paket dan file awal resources.resw
telah dibuat, menambahkan bahasa tambahan mudah.
Membuat sumber daya tambahan yang dilokalkan
Pertama, buat nilai sumber daya tambahan yang dilokalkan.
Strings
Dalam folder, buat folder tambahan untuk setiap bahasa yang Anda dukung menggunakan kode BCP-47 yang sesuai (misalnya, Strings\de-DE
). Dalam setiap folder ini, buat resources.resw
file (menggunakan editor XML atau perancang Visual Studio) yang menyertakan nilai sumber daya yang diterjemahkan. Diasumsikan Anda sudah memiliki string yang dilokalkan yang tersedia di suatu tempat, dan Anda hanya perlu menyalinnya ke dalam .resw
file; dokumen ini tidak mencakup langkah terjemahan itu sendiri.
Misalnya, Strings\de-DE\resources.resw
file mungkin terlihat seperti ini, dengan teks yang disorot diubah dari en-US
:
<?xml version="1.0" encoding="utf-8"?>
<root>
<data name="ApplicationDescription">
<value>Contoso Demo app with localized resources (German)</value>
</data>
<data name="ApplicationDisplayName">
<value>Contoso Demo Sample (German)</value>
</data>
<data name="PackageDisplayName">
<value>Contoso Demo Package (German)</value>
</data>
<data name="PublisherDisplayName">
<value>Contoso Samples, DE</value>
</data>
<data name="TileShortName">
<value>Contoso (DE)</value>
</data>
</root>
Langkah-langkah berikut mengasumsikan Anda menambahkan sumber daya untuk dan de-DE
fr-FR
, tetapi pola yang sama dapat diikuti untuk bahasa apa pun.
Memperbarui manifes paket untuk mencantumkan bahasa yang didukung
Manifes paket harus diperbarui untuk mencantumkan bahasa yang didukung oleh aplikasi. Pengonversi Aplikasi Desktop menambahkan bahasa default, tetapi yang lain harus ditambahkan secara eksplisit. Jika Anda mengedit AppxManifest.xml
file secara langsung, perbarui Resources
simpul sebagai berikut, tambahkan elemen sebanyak yang Anda butuhkan, dan ganti bahasa yang sesuai yang Anda dukung dan pastikan entri pertama dalam daftar adalah bahasa default (fallback).
Dalam contoh ini, defaultnya adalah Bahasa Inggris (AS) dengan dukungan tambahan untuk Jerman (Jerman) dan Prancis (Prancis):
<Resources>
<Resource Language="EN-US" />
<Resource Language="DE-DE" />
<Resource Language="FR-FR" />
</Resources>
Jika Anda menggunakan Visual Studio, Anda tidak perlu melakukan apa pun; jika Anda melihat Package.appxmanifest
Anda akan melihat nilai khusus yang dihasilkan x, yang menyebabkan proses build menyisipkan bahasa yang ditemukan dalam proyek Anda (berdasarkan folder bernama dengan kode BCP-47). Perhatikan bahwa ini bukan nilai yang valid untuk manifes paket nyata; ini hanya berfungsi untuk proyek Visual Studio:
<Resources>
<Resource Language="x-generate" />
</Resources>
Membangun ulang dengan nilai yang dilokalkan
Sekarang Anda dapat membangun dan menyebarkan aplikasi Anda, sekali lagi, dan jika Anda mengubah preferensi bahasa Anda di Windows, Anda akan melihat nilai yang baru dilokalkan muncul di menu Mulai (instruksi tentang cara mengubah bahasa Anda ada di bawah).
Untuk Visual Studio, sekali lagi Anda hanya dapat menggunakan Ctrl+Shift+B
untuk membuat, dan mengklik kanan proyek ke Deploy
.
Jika Anda membangun proyek secara manual, ikuti langkah yang sama seperti di atas tetapi tambahkan bahasa tambahan, dipisahkan oleh garis bawah, ke daftar kualifikasi default (/dq
) saat membuat file konfigurasi. Misalnya, untuk mendukung sumber daya Bahasa Inggris, Jerman, dan Prancis yang ditambahkan pada langkah sebelumnya:
makepri createconfig /cf ..\contoso_demo.xml /dq en-US_de-DE_fr-FR /pv 10.0 /o
Ini akan membuat file PRI yang berisi semua bahasa yang ditentukanyang dapat Anda gunakan dengan mudah untuk pengujian. Jika ukuran total sumber daya Anda kecil, atau Anda hanya mendukung sejumlah kecil bahasa, ini mungkin dapat diterima untuk aplikasi pengiriman Anda; itu hanya jika Anda ingin manfaat meminimalkan ukuran penginstalan / unduhan untuk sumber daya Anda yang Perlu Anda lakukan pekerjaan tambahan untuk membangun paket bahasa terpisah.
Menguji dengan nilai yang dilokalkan
Untuk menguji perubahan baru yang dilokalkan, Anda cukup menambahkan bahasa UI pilihan baru ke Windows. Tidak perlu mengunduh paket bahasa, me-reboot sistem, atau membuat seluruh UI Windows Anda muncul dalam bahasa asing.
- Jalankan
Settings
aplikasi (Windows + I
) - Buka
Time & language
- Buka
Region & language
- Klik
Add a language
- Ketik (atau pilih) bahasa yang Anda inginkan (misalnya
Deutsch
atauGerman
)
- Jika ada sub-bahasa, pilih sub-bahasa yang Anda inginkan (misalnya,
Deutsch / Deutschland
)
- Pilih bahasa baru dalam daftar bahasa
- Klik
Set as default
Sekarang buka menu Mulai dan cari aplikasi Anda, dan Anda akan melihat nilai yang dilokalkan untuk bahasa yang dipilih (aplikasi lain mungkin juga muncul dilokalkan). Jika Anda tidak segera melihat nama yang dilokalkan, tunggu beberapa menit hingga cache Menu Mulai disegarkan. Untuk kembali ke bahasa asli Anda, cukup jadikan bahasa default dalam daftar bahasa.
Langkah 1.4: Melokalisasi lebih banyak bagian dari manifes paket (opsional)
Bagian lain dari manifes paket dapat dilokalkan. Misalnya, jika aplikasi Anda menangani ekstensi file maka harus memiliki windows.fileTypeAssociation
ekstensi dalam manifes, menggunakan teks yang disorot hijau persis seperti yang ditunjukkan (karena akan merujuk ke sumber daya), dan mengganti teks yang disorot kuning dengan informasi khusus untuk aplikasi Anda:
<Extensions>
<uap:Extension Category="windows.fileTypeAssociation">
<uap:FileTypeAssociation Name="default">
<uap:DisplayName>ms-resource:Resources/FileTypeDisplayName</uap:DisplayName>
<uap:Logo>Assets\StoreLogo.png</uap:Logo>
<uap:InfoTip>ms-resource:Resources/FileTypeInfoTip</uap:InfoTip>
<uap:SupportedFileTypes>
<uap:FileType ContentType="application/x-contoso">.contoso</uap:FileType>
</uap:SupportedFileTypes>
</uap:FileTypeAssociation>
</uap:Extension>
</Extensions>
Anda juga dapat menambahkan informasi ini menggunakan Visual Studio Manifest Designer, menggunakan Declarations
tab , dengan mencatat nilai yang disorot:
Sekarang tambahkan nama sumber daya yang sesuai ke setiap file Anda .resw
, ganti teks yang disorot dengan teks yang sesuai untuk aplikasi Anda (ingatlah untuk melakukan ini untuk setiap bahasa yang didukung!):
... existing content...
<data name="FileTypeDisplayName">
<value>Contoso Demo File</value>
</data>
<data name="FileTypeInfoTip">
<value>Files used by Contoso Demo App</value>
</data>
Ini kemudian akan muncul di bagian shell Windows, seperti File Explorer:
Buat dan uji paket seperti sebelumnya, menjalankan skenario baru apa pun yang harus menampilkan string UI baru.
Fase 2: Gunakan MRT untuk mengidentifikasi dan menemukan sumber daya
Bagian sebelumnya menunjukkan cara menggunakan MRT untuk melokalisasi file manifes aplikasi Anda sehingga Windows Shell dapat menampilkan nama aplikasi dan metadata lainnya dengan benar. Tidak ada perubahan kode yang diperlukan untuk ini; itu hanya memerlukan penggunaan .resw
file dan beberapa alat tambahan. Bagian ini akan menunjukkan cara menggunakan MRT untuk menemukan sumber daya dalam format sumber daya yang ada dan menggunakan kode penanganan sumber daya yang ada dengan perubahan minimal.
Asumsi tentang tata letak file & kode aplikasi yang ada
Karena ada banyak cara untuk melokalisasi aplikasi Win32 Desktop, makalah ini akan membuat beberapa asumsi yang menyederhanakan tentang struktur aplikasi yang ada yang perlu Anda petakan ke lingkungan spesifik Anda. Anda mungkin perlu membuat beberapa perubahan pada basis kode atau tata letak sumber daya yang ada agar sesuai dengan persyaratan MRT, dan sebagian besar berada di luar cakupan untuk dokumen ini.
Tata letak file sumber daya
Artikel ini mengasumsikan sumber daya lokal Anda semuanya memiliki nama file yang sama (misalnya, contoso_demo.exe.mui
atau contoso.strings.xml
contoso_strings.dll
) tetapi ditempatkan di folder yang berbeda dengan nama BCP-47 (en-US
, , de-DE
dll.). Tidak masalah berapa banyak file sumber daya yang Anda miliki, apa namanya, apa format file/API terkaitnya, dll. Satu-satunya hal yang penting adalah bahwa setiap sumber daya logis memiliki nama file yang sama (tetapi ditempatkan di direktori fisik yang berbeda).
Sebagai contoh penghitung, jika aplikasi Anda menggunakan struktur file datar dengan satu Resources
direktori yang berisi file english_strings.dll
dan french_strings.dll
, itu tidak akan dipetakan dengan baik ke MRT. Struktur yang Resources
lebih baik adalah direktori dengan subdirektori dan file en\strings.dll
dan fr\strings.dll
. Dimungkinkan juga untuk menggunakan nama file dasar yang sama tetapi dengan kualifikasi yang disematkan, seperti strings.lang-en.dll
dan strings.lang-fr.dll
, tetapi menggunakan direktori dengan kode bahasa secara konseptual lebih sederhana sehingga itulah yang akan kita fokuskan.
Catatan
Masih dimungkinkan untuk menggunakan MRT dan manfaat kemasan bahkan jika Anda tidak dapat mengikuti konvensi penamaan file ini; itu hanya membutuhkan lebih banyak pekerjaan.
Misalnya, aplikasi mungkin memiliki sekumpulan perintah UI kustom (digunakan untuk label tombol dll.) dalam file teks sederhana bernama ui.txt, yang ditata di bawah folder UICommands :
+ ProjectRoot |--+ Strings | |--+ en-US | | \--- resources.resw | \--+ de-DE | \--- resources.resw |--+ UICommands | |--+ en-US | | \--- ui.txt | \--+ de-DE | \--- ui.txt |--- AppxManifest.xml |--- ...rest of project...
Kode pemuatan sumber daya
Artikel ini mengasumsikan bahwa pada titik tertentu dalam kode Anda, Anda ingin menemukan file yang berisi sumber daya yang dilokalkan, memuatnya, lalu menggunakannya. API yang digunakan untuk memuat sumber daya, API yang digunakan untuk mengekstrak sumber daya, dll. tidak penting. Dalam pseudocode, pada dasarnya ada tiga langkah:
set userLanguage = GetUsersPreferredLanguage() set resourceFile = FindResourceFileForLanguage(MY_RESOURCE_NAME, userLanguage) set resource = LoadResource(resourceFile) // now use 'resource' however you want
MRT hanya memerlukan perubahan dua langkah pertama dalam proses ini - bagaimana Anda menentukan sumber daya kandidat terbaik dan bagaimana Anda menemukannya. Tidak mengharuskan Anda untuk mengubah cara Anda memuat atau menggunakan sumber daya (meskipun menyediakan fasilitas untuk melakukannya jika Anda ingin memanfaatkannya).
Misalnya, aplikasi mungkin menggunakan API GetUserPreferredUILanguages
Win32 , fungsi sprintf
CRT , dan API CreateFile
Win32 untuk menggantikan tiga fungsi pseudocode di atas, lalu mengurai file teks secara manual yang mencari name=value
pasangan. (Detailnya tidak penting; ini hanya untuk menggambarkan bahwa MRT tidak berdampak pada teknik yang digunakan untuk menangani sumber daya setelah mereka ditemukan).
Langkah 2.1: Perubahan kode untuk menggunakan MRT untuk menemukan file
Mengalihkan kode Anda untuk menggunakan MRT untuk menemukan sumber daya tidaklah sulit. Ini membutuhkan penggunaan beberapa jenis WinRT dan beberapa baris kode. Jenis utama yang akan Anda gunakan adalah sebagai berikut:
- ResourceContext, yang merangkum kumpulan nilai kualifikasi yang saat ini aktif (bahasa, faktor skala, dll.)
- ResourceManager (versi WinRT, bukan versi .NET), yang memungkinkan akses ke semua sumber daya dari file PRI
- ResourceMap, yang mewakili subset sumber daya tertentu dalam file PRI (dalam contoh ini, sumber daya berbasis file vs. sumber daya string)
- NamedResource, yang mewakili sumber daya logis dan semua kandidat yang mungkin
- ResourceCandidate, yang mewakili satu sumber daya kandidat konkret
Dalam pseudo-code, cara Anda menyelesaikan nama file sumber daya tertentu (seperti UICommands\ui.txt
dalam sampel di atas) adalah sebagai berikut:
// Get the ResourceContext that applies to this app set resourceContext = ResourceContext.GetForViewIndependentUse() // Get the current ResourceManager (there's one per app) set resourceManager = ResourceManager.Current // Get the "Files" ResourceMap from the ResourceManager set fileResources = resourceManager.MainResourceMap.GetSubtree("Files") // Find the NamedResource with the logical filename we're looking for, // by indexing into the ResourceMap set desiredResource = fileResources["UICommands\ui.txt"] // Get the ResourceCandidate that best matches our ResourceContext set bestCandidate = desiredResource.Resolve(resourceContext) // Get the string value (the filename) from the ResourceCandidate set absoluteFileName = bestCandidate.ValueAsString
Perhatikan secara khusus bahwa kode tidak meminta folder bahasa tertentu - seperti UICommands\en-US\ui.txt
- meskipun begitulah file ada di disk. Sebaliknya, ia meminta nama UICommands\ui.txt
file logis dan bergantung pada MRT untuk menemukan file pada disk yang sesuai di salah satu direktori bahasa.
Dari sini, aplikasi sampel dapat terus digunakan CreateFile
untuk memuat absoluteFileName
dan mengurai name=value
pasangan seperti sebelumnya; tidak ada logika yang perlu diubah di aplikasi. Jika Anda menulis dalam C# atau C++/CX, kode aktual tidak jauh lebih rumit daripada ini (dan sebenarnya banyak variabel perantara yang dapat diteruskan) - lihat bagian tentang Memuat sumber daya .NET, di bawah ini. Aplikasi berbasis C++/WRL akan lebih kompleks karena API berbasis COM tingkat rendah yang digunakan untuk mengaktifkan dan memanggil API WinRT, tetapi langkah-langkah mendasar yang Anda ambil sama - lihat bagian tentang Memuat sumber daya MUI Win32, di bawah ini.
Memuat sumber daya .NET
Karena .NET memiliki mekanisme bawaan untuk menemukan dan memuat sumber daya (dikenal sebagai "Rakitan Satelit"), tidak ada kode eksplisit untuk diganti seperti dalam contoh sintetis di atas - di .NET Anda hanya memerlukan DLL sumber daya Anda di direktori yang sesuai dan secara otomatis terletak untuk Anda. Ketika aplikasi dikemas sebagai MSIX atau .appx menggunakan paket sumber daya, struktur direktori agak berbeda - daripada meminta direktori sumber daya menjadi subdirektori direktori aplikasi utama, mereka adalah serekan darinya (atau tidak ada sama sekali jika pengguna tidak memiliki bahasa yang tercantum dalam preferensi mereka).
Misalnya, bayangkan aplikasi .NET dengan tata letak berikut, di mana semua file ada di MainApp
bawah folder:
+ MainApp |--+ en-us | \--- MainApp.resources.dll |--+ de-de | \--- MainApp.resources.dll |--+ fr-fr | \--- MainApp.resources.dll \--- MainApp.exe
Setelah konversi ke .appx, tata letak akan terlihat seperti ini, dengan en-US
asumsi adalah bahasa default dan pengguna memiliki bahasa Jerman dan Prancis yang tercantum dalam daftar bahasa mereka:
+ WindowsAppsRoot |--+ MainApp_neutral | |--+ en-us | | \--- MainApp.resources.dll | \--- MainApp.exe |--+ MainApp_neutral_resources.language_de | \--+ de-de | \--- MainApp.resources.dll \--+ MainApp_neutral_resources.language_fr \--+ fr-fr \--- MainApp.resources.dll
Karena sumber daya yang dilokalkan tidak lagi ada di sub-direktori di bawah lokasi penginstalan utama yang dapat dieksekusi, resolusi sumber daya .NET bawaan gagal. Untungnya, .NET memiliki mekanisme yang terdefinisi dengan baik untuk menangani upaya pemuatan rakitan yang gagal - peristiwa tersebut AssemblyResolve
. Aplikasi .NET yang menggunakan MRT harus mendaftar untuk peristiwa ini dan menyediakan rakitan yang hilang untuk subsistem sumber daya .NET.
Contoh singkat tentang cara menggunakan API WinRT untuk menemukan rakitan satelit yang digunakan oleh .NET adalah sebagai berikut; kode seperti yang disajikan sengaja dikompresi untuk menunjukkan implementasi minimal, meskipun Anda dapat melihatnya memetakan hampir ke kode semu di atas, dengan passed-in ResolveEventArgs
yang memberikan nama rakitan yang perlu kita temukan. Versi kode ini yang dapat dijalankan (dengan komentar terperinci dan penanganan kesalahan) dapat ditemukan dalam file PriResourceRsolver.cs
dalam sampel .NET Assembly Resolver di GitHub.
static class PriResourceResolver
{
internal static Assembly ResolveResourceDll(object sender, ResolveEventArgs args)
{
var fullAssemblyName = new AssemblyName(args.Name);
var fileName = string.Format(@"{0}.dll", fullAssemblyName.Name);
var resourceContext = ResourceContext.GetForViewIndependentUse();
resourceContext.Languages = new[] { fullAssemblyName.CultureName };
var resource = ResourceManager.Current.MainResourceMap.GetSubtree("Files")[fileName];
// Note use of 'UnsafeLoadFrom' - this is required for apps installed with .appx, but
// in general is discouraged. The full sample provides a safer wrapper of this method
return Assembly.UnsafeLoadFrom(resource.Resolve(resourceContext).ValueAsString);
}
}
Mengingat kelas di atas, Anda akan menambahkan yang berikut di suatu tempat awal dalam kode startup aplikasi Anda (sebelum sumber daya yang dilokalkan perlu dimuat):
void EnableMrtResourceLookup()
{
AppDomain.CurrentDomain.AssemblyResolve += PriResourceResolver.ResolveResourceDll;
}
Runtime .NET akan meningkatkan AssemblyResolve
peristiwa setiap kali tidak dapat menemukan DLL sumber daya, di mana penanganan aktivitas yang disediakan akan menemukan file yang diinginkan melalui MRT dan mengembalikan rakitan.
Catatan
Jika aplikasi Anda sudah memiliki AssemblyResolve
handler untuk tujuan lain, Anda harus mengintegrasikan kode penyelesaian sumber daya dengan kode yang ada.
Memuat sumber daya WIN32 MUI
Memuat sumber daya WIN32 MUI pada dasarnya sama dengan memuat Rakitan Satelit .NET, tetapi menggunakan kode C++/CX atau C++/WRL sebagai gantinya. Menggunakan C++/CX memungkinkan kode yang jauh lebih sederhana yang sangat cocok dengan kode C# di atas, tetapi menggunakan ekstensi bahasa C++, sakelar kompiler, dan overheard runtime tambahan yang mungkin ingin Anda hindari. Jika demikian, menggunakan C++/WRL memberikan solusi dampak yang jauh lebih rendah dengan biaya kode yang lebih verbose. Namun demikian, jika Anda terbiasa dengan pemrograman ATL (atau COM secara umum) maka WRL harus merasa akrab.
Contoh fungsi berikut menunjukkan cara menggunakan C++/WRL untuk memuat DLL sumber daya tertentu dan mengembalikan HINSTANCE
yang dapat digunakan untuk memuat sumber daya lebih lanjut menggunakan API sumber daya Win32 biasa. Perhatikan bahwa tidak seperti sampel C# yang secara eksplisit menginisialisasi ResourceContext
dengan bahasa yang diminta oleh runtime .NET, kode ini bergantung pada bahasa pengguna saat ini.
#include <roapi.h>
#include <wrl\client.h>
#include <wrl\wrappers\corewrappers.h>
#include <Windows.ApplicationModel.resources.core.h>
#include <Windows.Foundation.h>
#define IF_FAIL_RETURN(hr) if (FAILED((hr))) return hr;
HRESULT GetMrtResourceHandle(LPCWSTR resourceFilePath, HINSTANCE* resourceHandle)
{
using namespace Microsoft::WRL;
using namespace Microsoft::WRL::Wrappers;
using namespace ABI::Windows::ApplicationModel::Resources::Core;
using namespace ABI::Windows::Foundation;
*resourceHandle = nullptr;
HRESULT hr{ S_OK };
RoInitializeWrapper roInit{ RO_INIT_SINGLETHREADED };
IF_FAIL_RETURN(roInit);
// Get Windows.ApplicationModel.Resources.Core.ResourceManager statics
ComPtr<IResourceManagerStatics> resourceManagerStatics;
IF_FAIL_RETURN(GetActivationFactory(
HStringReference(
RuntimeClass_Windows_ApplicationModel_Resources_Core_ResourceManager).Get(),
&resourceManagerStatics));
// Get .Current property
ComPtr<IResourceManager> resourceManager;
IF_FAIL_RETURN(resourceManagerStatics->get_Current(&resourceManager));
// get .MainResourceMap property
ComPtr<IResourceMap> resourceMap;
IF_FAIL_RETURN(resourceManager->get_MainResourceMap(&resourceMap));
// Call .GetValue with supplied filename
ComPtr<IResourceCandidate> resourceCandidate;
IF_FAIL_RETURN(resourceMap->GetValue(HStringReference(resourceFilePath).Get(),
&resourceCandidate));
// Get .ValueAsString property
HString resolvedResourceFilePath;
IF_FAIL_RETURN(resourceCandidate->get_ValueAsString(
resolvedResourceFilePath.GetAddressOf()));
// Finally, load the DLL and return the hInst.
*resourceHandle = LoadLibraryEx(resolvedResourceFilePath.GetRawBuffer(nullptr),
nullptr, LOAD_LIBRARY_AS_DATAFILE | LOAD_LIBRARY_AS_IMAGE_RESOURCE);
return S_OK;
}
Fase 3: Membangun paket sumber daya
Sekarang setelah Anda memiliki "paket lemak" yang berisi semua sumber daya, ada dua jalur menuju membangun paket utama dan paket sumber daya terpisah untuk meminimalkan ukuran unduhan dan penginstalan:
- Ambil paket lemak yang ada dan jalankan melalui alat Generator Bundel untuk membuat paket sumber daya secara otomatis. Ini adalah pendekatan yang disukai jika Anda memiliki sistem build yang sudah menghasilkan paket lemak dan Anda ingin pasca-proses untuk menghasilkan paket sumber daya.
- Langsung menghasilkan paket sumber daya individual dan membangunnya menjadi bundel. Ini adalah pendekatan yang disukai jika Anda memiliki lebih banyak kontrol atas sistem build Anda dan dapat membangun paket secara langsung.
Langkah 3.1: Membuat bundel
Menggunakan alat Generator Bundel
Untuk menggunakan alat Generator Bundel, file konfigurasi PRI yang dibuat untuk paket perlu diperbarui secara manual untuk menghapus bagian <packaging>
.
Jika Anda menggunakan Visual Studio, lihat Memastikan bahwa sumber daya diinstal pada perangkat terlepas dari apakah perangkat mengharuskannya untuk informasi tentang cara membangun semua bahasa ke dalam paket utama dengan membuat file priconfig.packaging.xml
dan priconfig.default.xml
.
Jika Anda mengedit file secara manual, ikuti langkah-langkah berikut:
Buat file konfigurasi dengan cara yang sama seperti sebelumnya, mengganti jalur, nama file, dan bahasa yang benar:
makepri createconfig /cf ..\contoso_demo.xml /dq en-US_de-DE_es-MX /pv 10.0 /o
Buka file yang dibuat
.xml
secara manual dan hapus seluruh<packaging&rt;
bagian (tetapi pertahankan semua yang lain tetap utuh):<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <resources targetOsVersion="10.0.0" majorVersion="1"> <!-- Packaging section has been deleted... --> <index root="\" startIndexAt="\"> <default> ... ...
.pri
Buat file dan.appx
paket seperti sebelumnya, menggunakan file konfigurasi yang diperbarui dan direktori dan nama file yang sesuai (lihat di atas untuk informasi selengkapnya tentang perintah ini):makepri new /pr . /cf ..\contoso_demo.xml /of ..\resources.pri /mf AppX /o makeappx pack /m AppXManifest.xml /f ..\resources.map.txt /p ..\contoso_demo.appx /o
AFter paket telah dibuat, gunakan perintah berikut untuk membuat bundel, menggunakan direktori dan nama file yang sesuai:
BundleGenerator.exe -Package ..\contoso_demo.appx -Destination ..\bundle -BundleName contoso_demo
Sekarang Anda dapat pindah ke langkah terakhir, menandatangani (lihat di bawah).
Membuat paket sumber daya secara manual
Membuat paket sumber daya secara manual mengharuskan menjalankan serangkaian perintah yang sedikit berbeda untuk membangun terpisah .pri
dan .appx
file - ini semua mirip dengan perintah yang digunakan di atas untuk membuat paket lemak, sehingga penjelasan minimal diberikan. Catatan: Semua perintah mengasumsikan bahwa direktori saat ini adalah direktori yang berisi AppXManifest.xml
file, tetapi semua file ditempatkan ke direktori induk (Anda dapat menggunakan direktori yang berbeda, jika perlu, tetapi Anda tidak boleh mencemari direktori proyek dengan salah satu file ini). Seperti biasa, ganti nama file "Contoso" dengan nama file Anda sendiri.
Gunakan perintah berikut untuk membuat file konfigurasi yang hanya menamai bahasa default sebagai kualifikasi default - dalam hal ini,
en-US
:makepri createconfig /cf ..\contoso_demo.xml /dq en-US /pv 10.0 /o
Buat default
.pri
dan.map.txt
file untuk paket utama, ditambah sekumpulan file tambahan untuk setiap bahasa yang ditemukan di proyek Anda, dengan perintah berikut:makepri new /pr . /cf ..\contoso_demo.xml /of ..\resources.pri /mf AppX /o
Gunakan perintah berikut untuk membuat paket utama (yang berisi kode yang dapat dieksekusi dan sumber daya bahasa default). Seperti biasa, ubah nama sesuai keinginan Anda, meskipun Anda harus memasukkan paket ke direktori terpisah untuk membuat pembuatan bundel lebih mudah nanti (contoh ini menggunakan
..\bundle
direktori):makeappx pack /m .\AppXManifest.xml /f ..\resources.map.txt /p ..\bundle\contoso_demo.main.appx /o
Setelah paket utama dibuat, gunakan perintah berikut sekali untuk setiap bahasa tambahan (yaitu, ulangi perintah ini untuk setiap file peta bahasa yang dihasilkan pada langkah sebelumnya). Sekali lagi, output harus berada di direktori terpisah (yang sama dengan paket utama). Perhatikan bahwa bahasa ditentukan baik dalam
/f
opsi/p
maupun opsi, dan penggunaan argumen baru/r
(yang menunjukkan Paket Sumber Daya diinginkan):makeappx pack /r /m .\AppXManifest.xml /f ..\resources.language-de.map.txt /p ..\bundle\contoso_demo.de.appx /o
Gabungkan semua paket dari direktori bundel ke dalam satu
.appxbundle
file. Opsi baru/d
menentukan direktori yang akan digunakan untuk semua file dalam bundel (inilah sebabnya file.appx
dimasukkan ke dalam direktori terpisah di langkah sebelumnya):makeappx bundle /d ..\bundle /p ..\contoso_demo.appxbundle /o
Langkah terakhir untuk membangun paket adalah penandatanganan.
Langkah 3.2: Menandatangani bundel
Setelah Anda membuat .appxbundle
file (baik melalui alat Generator Bundel atau secara manual) Anda akan memiliki satu file yang berisi paket utama ditambah semua paket sumber daya. Langkah terakhir adalah menandatangani file sehingga Windows akan menginstalnya:
signtool sign /fd SHA256 /a /f ..\contoso_demo_key.pfx ..\contoso_demo.appxbundle
Ini akan menghasilkan file bertanda .appxbundle
tangan yang berisi paket utama ditambah semua paket sumber daya khusus bahasa. Ini dapat diklik dua kali seperti file paket untuk menginstal aplikasi ditambah bahasa yang sesuai berdasarkan preferensi bahasa Windows pengguna.
Topik terkait
Saran dan Komentar
https://aka.ms/ContentUserFeedback.
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:Kirim dan lihat umpan balik untuk