Menggunakan Sistem Manajemen Sumber Daya Windows 10 di aplikasi atau game warisan

  • Artikel

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.

Screenshot of a Source code label, a Lookup table label, and a Files on disk label.

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:

  1. Buat file XML bernama resources.resw dan letakkan di Strings\en-us subfolder proyek Anda. Gunakan kode BCP-47 yang sesuai jika bahasa default Anda bukan bahasa Inggris AS.
  2. 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:

  1. Strings\en-us Buat folder (atau bahasa lain yang sesuai) di proyek Anda dan tambahkan Item Baru ke folder akar proyek Anda, menggunakan nama resources.reswdefault . Pastikan untuk memilih File Sumber Daya (.resw) dan bukan Kamus Sumber Daya - Kamus Sumber Daya adalah file yang digunakan oleh aplikasi XAML.
  2. Menggunakan perancang, masukkan string berikut (gunakan yang sama Names tetapi ganti Values dengan teks yang sesuai untuk aplikasi Anda):

Screenshot showing the Resources.resw file showing the Name and Value columns. for the resources.

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:

Screenshot of the Visual Studio Manifest Designer showing the Application tab with the Display name and Description text boxes called out.

Screenshot of the Visual Studio Manifest Designer showing the Packaging tab with the Package display name and Publisher display name text boxes called out.

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

  1. Buka perintah pengembang dari folder Visual Studio 2017 atau Visual Studio 2019 di menu Mulai.

  2. Beralih ke direktori akar proyek (yang berisi file .appxmanifest dan folder String).

  3. 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 bahasa en-US
    • /pv mengatur Versi Platform, dalam hal ini Windows 10
    • /o mengaturnya untuk Menimpa file output jika ada

  4. 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

  5. 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

  6. Terakhir, Anda dapat membuka ..\resources.xml di editor teks dan memverifikasinya mencantumkan nilai Anda <NamedResource> (seperti ApplicationDescription dan PublisherDisplayName) 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:

  1. 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

  2. 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 menggunakan MakeCert utilitas dan Pvk2Pfx 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!

  3. Untuk menandatangani paket, gunakan perintah berikut. Perhatikan bahwa yang Publisher ditentukan dalam Identity elemen AppxManifest.xml harus cocok Subject dengan sertifikat (ini bukan<PublisherDisplayName> elemen, yang merupakan nama tampilan yang dilokalkan untuk ditampilkan kepada pengguna). Seperti biasa, ganti contoso_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:

  1. Jalankan perintah Visual Studio 2017 atau Visual Studio 2019 sebagai Administrator.

  2. Beralih ke direktori yang berisi .cer file (ingatlah untuk memastikan ini berada di luar sumber atau direktori proyek Anda!)

  3. 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 sertifikat
    • TrustedPeople menunjukkan penyimpanan tempat sertifikat ditempatkan

Untuk menggunakan Windows Explorer:

  1. Navigasi ke folder yang berisi .pfx file
  2. Klik dua kali pada .pfx file dan Wizard Impor Certicicate akan muncul
  3. Pilih Local Machine dan klik Next
  4. Terima perintah elevasi admin Kontrol Akun Pengguna, jika muncul, dan klik Next
  5. Masukkan kata sandi untuk kunci privat, jika ada, dan klik Next
  6. Pilih Place all certificates in the following store
  7. Klik Browse, dan pilih Trusted People folder (bukan "Penerbit Tepercaya")
  8. Klik Next lalu Finish

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-DEfr-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.

  1. Jalankan Settings aplikasi (Windows + I)
  2. Buka Time & language
  3. Buka Region & language
  4. Klik Add a language
  5. Ketik (atau pilih) bahasa yang Anda inginkan (misalnya Deutsch atau German)
  • Jika ada sub-bahasa, pilih sub-bahasa yang Anda inginkan (misalnya, Deutsch / Deutschland)
  1. Pilih bahasa baru dalam daftar bahasa
  2. 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:

Screenshot of the Visual Studio Manifest Designer showing the Declarations tab with the Display name and Info tip text boxes called out.

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:

Screenshot of File Explorer showing a tooltip that says Files used by Contoso Demo App.

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.xmlcontoso_strings.dll ) tetapi ditempatkan di folder yang berbeda dengan nama BCP-47 (en-US, , de-DEdll.). 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 GetUserPreferredUILanguagesWin32 , fungsi sprintfCRT , 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:

  1. 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

  2. Buka file yang dibuat .xml secara manual dan hapus seluruh &lt;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>
    ...
    ...

  3. .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

  4. 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.

  1. 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

  2. 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

  3. 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

  4. 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

  5. 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.