Tutorial: Menggunakan API bootstrapper dalam aplikasi yang dikemas dengan lokasi eksternal atau tidak dikemas yang menggunakan SDK Aplikasi Windows

Artikel ini menunjukkan cara mengonfigurasi aplikasi yang tidak diinstal dengan menggunakan MSIX (artinya, dikemas dengan lokasi eksternal atau tidak dikemas) untuk menggunakan API bootstrapper sehingga secara eksplisit memuat runtime SDK Aplikasi Windows, dan memanggil API SDK Aplikasi Windows. Aplikasi yang tidak diinstal melalui MSIX menyertakan aplikasi yang dikemas dengan lokasi eksternal, dan aplikasi yang tidak dikemas.

Penting

Mulai dari SDK Aplikasi Windows 1.0, pendekatan bawaan untuk memuat SDK Aplikasi Windows dari aplikasi yang dikemas dengan lokasi eksternal atau aplikasi yang tidak dikemas adalah menggunakan auto-inisialisasi melalui properti <WindowsPackageType> proyek (serta membuat perubahan konfigurasi tambahan). Untuk langkah-langkah yang terlibat dalam inisialisasi otomatis dalam konteks proyek WinUI 3, lihat Buat proyek WinUI pertama Anda. Atau, jika memiliki project yang sudah ada yang bukan WinUI, lihat Gunakan SDK Aplikasi Windows di project.

Jika Anda memiliki kebutuhan lanjutan (seperti penanganan kesalahan kustom, atau untuk memuat versi SDK Aplikasi Windows tertentu), maka Anda dapat memanggil API bootstrapper secara eksplisit. Dan itulah pendekatan yang ditunjukkan topik ini. Selain itu, untuk informasi selengkapnya, lihat Gunakan runtime SDK Aplikasi Windows untuk aplikasi yang dikemas dengan lokasi eksternal atau tidak dikemas.

Topik ini menunjukkan cara memanggil API bootstrapper secara eksplisit dari project aplikasi Konsol dasar; tetapi langkah-langkahnya berlaku untuk aplikasi desktop tanpa kemasan yang menggunakan SDK Aplikasi Windows.

Sebelum menyelesaikan tutorial ini, kami sarankan Anda meninjau arsitektur Runtime untuk mempelajari lebih lanjut tentang Framework dependensi paket yang dibutuhkan aplikasi Anda saat menggunakan SDK Aplikasi Windows, dan komponen tambahan yang diperlukan untuk bekerja dalam paket dengan lokasi eksternal atau aplikasi yang tidak dikemas.

Prasyarat

1. Pasang peralatan untuk SDK Aplikasi Windows.
2. Pastikan bahwa semua dependensi untuk aplikasi yang dikemas beserta komponen eksternal dan aplikasi mandiri diinstal (lihat panduan penyebaran SDK Aplikasi Windows untuk aplikasi yang bergantung pada kerangka kerja yang dikemas dengan komponen eksternal atau aplikasi mandiri). Cara mudah untuk melakukan ini adalah dengan menjalankan penginstal runtime SDK Aplikasi Windows.

Petunjuk

Anda dapat mengikuti tutorial ini menggunakan C# atau project C++.

Catatan

Dependensi dinamis dan API bootstrapper gagal saat dipanggil oleh proses yang ditingkatkan. Akibatnya, Visual Studio tidak boleh diluncurkan lebih tinggi. Lihat Dependensi Dinamis tidak mendukung elevasi #567 untuk informasi lebih lanjut.

C#

Ikuti petunjuk ini untuk mengonfigurasi project C# WinUI yang dikemas dengan lokasi eksternal, atau tidak dikemas.

1. Di Visual Studio, buat proyek Console App C# baru. Beri nama project DynamicDependenciesTest. Setelah membuat project, Anda harus memiliki aplikasi konsol C# "Halo, Dunia!".

2. Selanjutnya, konfigurasikan project Anda.

   1. Di Penjelajah Solusi, klik kanan project Anda dan pilih Edit File Project.
   2. Ganti nilai elemen TargetFramework dengan Target Framework Moniker. Misalnya, gunakan hal berikut jika aplikasi Anda menargetkan Windows 10, versi 2004.

   <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
   

   1. Simpan dan tutup file project.

3. Ubah platform untuk solusi Anda menjadi x64. Nilai default dalam .NET project adalah AnyCPU, tetapi WinUI tidak mendukung platform tersebut.

   1. Pilih Build>Configuration Manager.
   2. Pilih menu drop-down di bawah Platform solusi aktif dan klik Baru untuk membuka kotak dialog Platform Solusi Baru.
   3. Di menu drop-down di bawah Jenis atau pilih platform baru, pilih x64.
   4. Klik OK untuk menutup kotak dialog Platform Solusi Baru.
   5. Di Configuration Manager, klik Tutup.

4. Pasang paket SDK Aplikasi Windows NuGet di proyek Anda.

   1. Di Penjelajah Solusi, klik kanan simpul Dependensi dan pilih Kelola Paket Nuget.
   2. Di jendela NuGet Package Manager, pilih tab Browse, dan instal paket Microsoft.WindowsAppSDK.

5. Anda sekarang siap untuk menggunakan API bootstrapper (lihat Gunakan runtime SDK Aplikasi Windows untuk aplikasi yang dikemas dengan lokasi eksternal atau dibongkar) untuk mengambil dependensi secara dinamis pada paket kerangka kerja SDK Aplikasi Windows. Ini memungkinkan Anda menggunakan API SDK Aplikasi Windows di aplikasi Anda.

   Buka file kode Program.cs, dan ganti kode default dengan kode berikut untuk memanggil metode Bootstrap.Initialize untuk menginisialisasi bootstrapper. Kode ini menentukan versi SDK Aplikasi Windows yang diperlukan oleh aplikasi saat menginisialisasi bootstrapper.

   Penting

   Anda harus mengedit kode di bawah ini agar sesuai dengan konfigurasi spesifik Anda. Lihat deskripsi parameter metode Bootstrap.Initialize sehingga Anda dapat menentukan salah satu versi SDK Aplikasi Windows yang telah Anda instal.

   using System;
   using Microsoft.Windows.ApplicationModel.DynamicDependency;
   
   namespace DynamicDependenciesTest
   {
       class Program
       {
           static void Main(string[] args)
           {
               Bootstrap.Initialize(0x00010002);
               Console.WriteLine("Hello, World!");
   
               // Release the DDLM and clean up.
               Bootstrap.Shutdown();
           }
       }
   }
   

   Pada akarnya, API bootstrapper adalah API C/C++ asli yang memungkinkan Anda menggunakan API SDK Aplikasi Windows di aplikasi Anda. Tetapi dalam aplikasi .NET yang menggunakan SDK Aplikasi Windows 1.0 atau yang lebih baru, Anda dapat menggunakan pembungkus .NET untuk API bootstrapper. Pembungkus itu menyediakan cara yang lebih mudah untuk memanggil API bootstrapper di aplikasi .NET daripada memanggil fungsi C/C++ asli secara langsung. Contoh kode sebelumnya memanggil metode statis Initialize dan Shutdown dari kelas Bootstrap dalam pembungkus .NET untuk API bootstrapper.

6. Untuk menunjukkan bahwa komponen runtime SDK Aplikasi Windows dimuat dengan benar, tambahkan beberapa kode yang menggunakan kelas ResourceManager di SDK Aplikasi Windows untuk memuat sumber daya string.

   1. Tambahkan file Resources baru (.resw) ke project Anda (biarkan nama default).

   2. Dengan file sumber daya terbuka di editor, buat sumber daya string baru dengan properti berikut.

      • Nama: Pesan
      • Nilai: Halo, sumber daya!

   3. Simpan file sumber daya.

   4. Buka file kode Program.cs, dan ganti Console.WriteLine("Hello, World!"); baris dengan kode berikut.

   // Create a resource manager using the resource index generated during build.
      var manager = new Microsoft.Windows.ApplicationModel.Resources.ResourceManager("DynamicDependenciesTest.pri");
   
   // Look up a string in the .resw file using its name.
   Console.WriteLine(manager.MainResourceMap.GetValue("Resources/Message").ValueAsString);
   

   1. Klik Mulai Tanpa Penelusuran Kesalahan (atau Mulai Penelusuran Kesalahan) untuk membuat dan menjalankan aplikasi Anda. Anda akan melihat string Hello, resources! berhasil ditampilkan.

C++

Ikuti petunjuk ini untuk mengonfigurasi proyek C++ WinUI yang dikemas dengan lokasinya di luar, atau tidak dikemas.

1. Di Visual Studio, buat Console App C++ baru. Beri nama project DynamicDependenciesTest.

   

   Setelah membuat project, Anda harus memiliki aplikasi konsol C++ "Halo, Dunia!".

2. Selanjutnya, instal paket NuGet SDK Aplikasi Windows di project Anda.

   1. Dalam Penjelajah Solusi, klik kanan simpul Referensi dan pilih Kelola Paket Nuget.
   2. Di jendela NuGet Package Manager, pilih tab Browse, dan cari Microsoft.WindowsAppSDK.

3. Anda sekarang siap untuk menggunakan API bootstrapper (lihat Gunakan runtime SDK Aplikasi Windows untuk aplikasi yang dikemas dengan lokasi eksternal atau tidak dikemas) untuk menginisialisasi runtime SDK Aplikasi Windows di aplikasi Anda. Ini memungkinkan Anda menggunakan API SDK Aplikasi Windows di aplikasi.

   1. Tambahkan file yang disertakan berikut ke bagian atas file DynamicDependenciesTest.cpp Anda. Header mddbootstrap.h tersedia melalui paket NuGet SDK Aplikasi Windows.

   #include <windows.h>
   #include <MddBootstrap.h>
   

   1. Selanjutnya, tambahkan kode ini di awal metode utama Anda untuk memanggil fungsi MddBootstrapInitialize untuk menginisialisasi bootstrapper, dan menangani kesalahan apa pun. Kode ini menentukan versi SDK Aplikasi Windows yang diperlukan oleh aplikasi saat menginisialisasi bootstrapper.

   Penting

   Anda harus mengedit kode di bawah ini agar sesuai dengan konfigurasi spesifik Anda. Lihat deskripsi parameter fungsi MddBootstrapInitialize sehingga Anda dapat menentukan salah satu versi SDK Aplikasi Windows yang telah Anda instal.

   const UINT32 majorMinorVersion{ 0x00010002 }; 
   PCWSTR versionTag{ L"" }; 
   const PACKAGE_VERSION minVersion{};
   
   const HRESULT hr{ MddBootstrapInitialize(majorMinorVersion, versionTag, minVersion) }; 
   
   // Check the return code for errors. If there is an error, display the result.
   if (FAILED(hr)) 
   { 
       wprintf(L"Error 0x%X in MddBootstrapInitialize(0x%08X, %s, %hu.%hu.%hu.%hu)\n", 
           hr, majorMinorVersion, versionTag, minVersion.Major, minVersion.Minor, minVersion.Build, minVersion.Revision); 
       return hr; 
   } 
   

   1. Terakhir, tambahkan kode ini untuk menampilkan string Hello, World! dan memanggil fungsi MddBootstrapShutdown untuk membatalkan inisialisasi bootstrapper.

   std::cout << "Hello, World!\n"; 
   
   // Release the DDLM and clean up.
   MddBootstrapShutdown(); 
   

   1. Kode akhir Anda akan terlihat seperti ini.

   #include <iostream> 
   #include <windows.h> 
   #include <MddBootstrap.h>
   
   int main() 
   { 
       // Take a dependency on Windows App SDK Stable.
       const UINT32 majorMinorVersion{ 0x00010002 }; 
       PCWSTR versionTag{ L"" }; 
       const PACKAGE_VERSION minVersion{};
   
       const HRESULT hr{ MddBootstrapInitialize(majorMinorVersion, versionTag, minVersion) }; 
   
       // Check the return code. If there is a failure, display the result.
       if (FAILED(hr)) 
       { 
           wprintf(L"Error 0x%X in MddBootstrapInitialize(0x%08X, %s, %hu.%hu.%hu.%hu)\n", 
               hr, majorMinorVersion, versionTag, minVersion.Major, minVersion.Minor, minVersion.Build, minVersion.Revision); 
           return hr; 
       } 
   
       std::cout << "Hello, World!\n"; 
   
       // Release the DDLM and clean up.
       MddBootstrapShutdown(); 
   } 
   

4. Klik Mulai Tanpa Penelusuran Kesalahan (atau Mulai Penelusuran Kesalahan) untuk membuat dan menjalankan aplikasi Anda.

Jika project Anda WPF

Untuk aplikasi Windows Presentation Foundation (WPF), lihat Gunakan SDK Aplikasi Windows di proyek yang sudah ada.

Topik terkait

• Panduan penempatan SDK Aplikasi Windows untuk aplikasi yang bergantung pada kerangka yang dikemas di lokasi eksternal atau tidak dikemas
• Arsitektur waktu proses