Bagikan melalui


SDK Aplikasi Windows panduan penyebaran untuk aplikasi yang bergantung pada kerangka kerja yang dikemas dengan lokasi eksternal atau tidak dikemas

Topik ini menyediakan panduan tentang menyebarkan aplikasi yang dikemas dengan lokasi eksternal, atau tidak dikemas, dan yang menggunakan SDK Aplikasi Windows.

  • Aplikasi tersebut adalah aplikasi desktop (bukan aplikasi UWP).
  • Mereka dapat ditulis dalam bahasa .NET seperti C#, atau di C++.
  • Untuk antarmuka pengguna mereka, mereka dapat menggunakan WinUI 3, atau WPF, atau WinForms, atau kerangka kerja UI lain.

Gambaran Umum

Pengembang yang dikemas dengan lokasi eksternal dan aplikasi yang tidak dikemas bertanggung jawab untuk menyebarkan paket runtime SDK Aplikasi Windows yang diperlukan kepada pengguna akhir mereka. Ini dapat dilakukan baik dengan menjalankan alat penginstal atau dengan menginstal paket MSIX secara langsung. Opsi ini dijelaskan secara lebih rinci di bagian Sebarkan SDK Aplikasi Windows runtime di bawah ini.

Dikemas dengan lokasi eksternal dan aplikasi yang tidak dikemas juga memiliki persyaratan runtime tambahan. Anda harus menginisialisasi akses ke runtime SDK Aplikasi Windows menggunakan API Bootstrapper. Selain itu, API Dependensi Dinamis dapat digunakan jika aplikasi Anda menggunakan paket kerangka kerja lain selain dari SDK Aplikasi Windows. Persyaratan ini dijelaskan secara lebih rinci dalam persyaratan Runtime untuk aplikasi yang dikemas dengan lokasi eksternal atau bagian yang tidak dikemas di bawah ini.

Prasyarat

  • Unduh paket penginstal & MSIX terbaru.
  • Untuk aplikasi yang dikemas dengan lokasi eksternal atau tidak dikemas, Visual C++ Redistributable adalah persyaratan. Untuk informasi selengkapnya, lihat Unduhan terbaru yang didukung Microsoft Visual C++ Redistributable.
  • C#. .NET 6 atau yang lebih baru diperlukan. Untuk informasi selengkapnya, lihat Unduhan .NET.

Prasyarat tambahan

  • Versi eksperimental dan pratinjau SDK Aplikasi Windows mengharuskan sideloading diaktifkan untuk menginstal runtime.
    • Sideloading diaktifkan secara otomatis pada Windows 10 versi 2004 dan yang lebih baru.

    • Jika komputer pengembangan atau komputer penyebaran Anda menjalankan Windows 11, konfirmasi apakah muatan samping diaktifkan:

      • Pengaturan>Privasi & keamanan>Untuk pengembang. Pastikan pengaturan Mode pengembang diaktifkan.
    • Jika komputer pengembangan atau komputer penyebaran Anda menjalankan Windows 10 versi 1909 atau versi yang lebih lama, konfirmasi apakah muatan samping diaktifkan:

      • Pengaturan>Pembaruan & Keamanan>Untuk pengembang>Gunakan fitur pengembang. Konfirmasikan bahwa aplikasi Sideload atau mode Pengembang dipilih.
    • Pengaturan mode Pengembang mencakup sideloading serta fitur lainnya.

      Catatan

      Jika komputer dikelola di lingkungan perusahaan, mungkin ada kebijakan yang mencegah pengaturan ini diubah. Dalam hal ini jika Anda mendapatkan kesalahan saat Anda atau aplikasi mencoba menginstal runtime SDK Aplikasi Windows, hubungi Profesional TI Anda untuk mengaktifkan sideloading atau mode Pengembang.

Menyebarkan runtime SDK Aplikasi Windows

Dikemas dengan lokasi eksternal dan aplikasi yang tidak dikemas memiliki dua opsi untuk menyebarkan runtime SDK Aplikasi Windows:

  • Opsi 1: Gunakan Alat Penginstal: Alat penginstal senyap mendistribusikan semua paket MSIX SDK Aplikasi Windows. Alat penginstal terpisah tersedia untuk setiap X64arsitektur ,X86 dan Arm64 .
  • Opsi 2: Instal paket secara langsung: Anda dapat memiliki penyiapan yang ada atau alat MSI membawa dan menginstal paket MSIX untuk SDK Aplikasi Windows.

Opsi 1: Gunakan Alat Penginstal

Anda dapat menyebarkan semua paket runtime SDK Aplikasi Windows dengan menjalankan alat penginstal. Alat penginstal tersedia di Unduhan untuk SDK Aplikasi Windows. Saat menjalankan alat penginstal (.exe), Anda akan melihat output yang mirip dengan yang berikut ini:

Deploying package: Microsoft.WindowsAppRuntime.1.0_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0

Deploying package: Microsoft.WindowsAppRuntime.1.0_0.318.928.0_x86__8wekyb3d8bbwe
Package deployment result : 0x0

Deploying package: MicrosoftCorporationII.WindowsAppRuntime.Main.1.0_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

Deploying package: Microsoft.WindowsAppRuntime.Singleton_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

Deploying package: Microsoft.WinAppRuntime.DDLM.0.318.928.0-x6_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

Deploying package: Microsoft.WinAppRuntime.DDLM.0.318.928.0-x8_0.318.928.0_x86__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

All install operations successful.

Anda dapat menjalankan alat penginstal tanpa interaksi pengguna dan menekan semua output teks dengan --quiet opsi :

WindowsAppRuntimeInstall.exe --quiet

Anda juga dapat memilih untuk memperbarui paksa paket MSIX dan mematikan proses SDK Aplikasi Windows yang sedang berjalan menggunakan opsi .--force Fitur ini diperkenalkan dalam 1.1.

WindowsAppRuntimeInstall.exe --force

Untuk melihat semua opsi baris perintah penginstal, jalankan WindowsAppRuntimeInstall --h.

Setelah penginstalan selesai, Anda dapat menjalankan paket dengan lokasi eksternal atau aplikasi yang tidak dikemas. Untuk contoh cara membuat dan menjalankan yang dikemas dengan lokasi eksternal atau aplikasi yang tidak dikemas yang menggunakan SDK Aplikasi Windows, lihat Tutorial: Menggunakan API bootstrapper dalam aplikasi yang dikemas dengan lokasi eksternal atau tidak dikemas yang menggunakan SDK Aplikasi Windows.

Rantai alat penginstal SDK Aplikasi Windows ke penyiapan aplikasi Anda

Jika Anda memiliki program penyiapan kustom untuk aplikasi, Anda dapat menautkan proses penyiapan SDK Aplikasi Windows dalam proses penyiapan aplikasi Anda. Alat penginstal SDK Aplikasi Windows saat ini tidak menyediakan UI default sehingga Anda perlu menautkan dengan menggunakan UI kustom penyiapan Anda.

Anda dapat meluncurkan dan melacak penyiapan SDK Aplikasi Windows secara diam-diam sambil menampilkan tampilan Anda sendiri tentang kemajuan penyiapan dengan menggunakan ShellExecute. Alat penginstal SDK Aplikasi Windows secara diam-diam membongkar bundel MSIX Aplikasi Windows dan memanggil metode PackageManager.AddPackageAsync untuk menyelesaikan penginstalan. Ini sangat mirip dengan alat penginstal runtime lain yang mungkin telah Anda gunakan, seperti .NET, Visual C++, atau DirectX.

Untuk contoh kode yang menunjukkan cara menjalankan penginstal SDK Aplikasi Windows dari program penyiapan Anda, lihat fungsi RunInstaller dalam pengujian fungsional penginstal.

Sampel alat penginstal

Lihat sampel di bawah ini untuk melihat cara meluncurkan alat penginstal dari program penyiapan Win32 tanpa memunculkan jendela konsol selama penyiapan:

Pemecahan Masalah

Mengembalikan kode

Tabel berikut mencantumkan kode pengembalian yang paling umum untuk penginstal SDK Aplikasi Windows .exe. Kode pengembalian sama untuk semua versi penginstal.

Mengembalikan kode Deskripsi
0x0 Penginstalan atau provisi paket berhasil diselesaikan.
0x80073d06 Satu atau beberapa paket gagal diinstal.
0x80070005 Penginstalan atau provisi di seluruh sistem tidak dimungkinkan karena aplikasi tidak berjalan ditingkatkan atau pengguna yang melakukan penginstalan tidak memiliki hak istimewa admin.

Kesalahan penginstalan

Jika alat penginstal SDK Aplikasi Windows mengembalikan kesalahan selama penginstalan, penginstalan akan mengembalikan kode kesalahan yang menjelaskan masalahnya.

  • Lihat daftar kode kesalahan umum.
  • Jika kode kesalahan tidak memberikan informasi yang cukup, Anda dapat menemukan informasi diagnostik lebih lanjut di log peristiwa terperinci.
  • Silakan ajukan masalah dengan kode kesalahan dan log peristiwa sehingga masalah dapat diselidiki.

Opsi 2: Menyebarkan paket runtime SDK Aplikasi Windows secara langsung

Sebagai alternatif untuk menggunakan alat penginstal SDK Aplikasi Windows untuk penyebaran kepada pengguna akhir, Anda dapat menyebarkan paket MSIX secara manual melalui program aplikasi atau MSI Anda. Opsi ini bisa menjadi yang terbaik untuk pengembang yang menginginkan kontrol lebih.

Untuk contoh yang menunjukkan bagaimana program penyiapan Anda dapat menginstal paket MSIX, lihat install.cpp dalam kode penginstal SDK Aplikasi Windows.

Untuk memeriksa apakah SDK Aplikasi Windows sudah diinstal (dan, jika demikian, versi apa), Anda dapat memeriksa keluarga paket tertentu dengan memanggil PackageManager.FindPackagesForUserWithPackageTypes.

Dari proses mediumIL (kepercayaan penuh) yang tidak dikemas (lihat Elemen aplikasi), Anda dapat menggunakan kode berikut untuk memeriksa paket yang terdaftar ke pengguna saat ini:

using Windows.Management.Deployment;

public class WindowsAppSDKRuntime
{
    public static IsPackageRegisteredForCurrentUser(
        string packageFamilyName,
        PackageVersion minVersion,
        Windows.System.ProcessorArchitecture architecture,
        PackageTypes packageType)
    {
        ulong minPackageVersion = ToVersion(minVersion);

        foreach (var p : PackageManager.FindPackagesForUserWithPackageTypes(
            string.Empty, packageFamilyName, packageType)
        {
            // Is the package architecture compatible?
            if (p.Id.Architecture != architecture)
            {
                continue;
            }

            // Is the package version sufficient for our needs?
            ulong packageVersion = ToVersion(p.Id.Version);
            if (packageVersion < minPackageVersion)
            {
                continue;
            }

            // Success.
            return true;
        }

        // No qualifying package found.
        return false;
    }

    private static ulong ToVersion(PackageVersion packageVersion)
    {
        return ((ulong)packageVersion.Major << 48) |
               ((ulong)packageVersion.Minor << 32) |
               ((ulong)packageVersion.Build << 16) |
               ((ulong)packageVersion.Revision);
    }
}

Untuk skenario di atas, memanggil FindPackagesForUserWithPackageTypes lebih disukai untuk memanggil FindPackagesForUser. Itu karena Anda dapat mempersempit pencarian ke (untuk contoh ini), hanya kerangka kerja atau paket utama. Dan itu menghindari pencocokan jenis paket lain (seperti sumber daya, opsional, atau bundel) yang tidak menarik untuk contoh ini.

Untuk menggunakan konteks pengguna saat ini/panggilan, atur parameter userSecurityId adalah ke string kosong.

Dan sekarang beberapa info untuk membantu Anda memutuskan cara memanggil fungsi dalam contoh kode di atas. Runtime yang diinstal dengan benar terdiri dari beberapa paket yang bergantung pada arsitektur CPU sistem:

  • Pada mesin x86: Fwk=[x86], Main=[x86], Singleton=[x86], DDLM=[x86].
  • Pada mesin x64: Fwk=[x86, x64], Main=[x64], Singleton=[x64], DDLM=[x86, x64].
  • Pada komputer arm64: Fwk=[x86, x64, arm64], Main=[arm64], Singleton=[arm64], DDLM=[x86, x64, arm64].

Untuk paket Utama dan Singleton, arsitekturnya harus sesuai dengan arsitektur CPU sistem; misalnya, paket x64 pada sistem x64. Untuk paket Framework, sistem x64 dapat menjalankan aplikasi x64 dan x86; demikian pula sistem arm64 dapat menjalankan aplikasi arm64, x64, dan x86. Pemeriksaan paket DDLM mirip dengan pemeriksaan Framework, kecuali bahwa PackageType=main, dan packagefamilyname berbeda, dan lebih dari satu (berbeda) packagefamilyname dapat berlaku, karena skema penamaan unik DDLM. Untuk informasi selengkapnya, lihat spesifikasi paket MSIX. Jadi pemeriksaannya lebih seperti ini:

public static bool IsRuntimeRegisteredForCurrentUser(PackageVersion minVersion)
{
    ProcessorArchitecture systemArchitecture = DetectSystemArchitecture();

    return IsFrameworkRegistered(systemArchitecture, minVersion) &&
           IsMainRegistered(systemArchitecture, minVersion) &&
           IsSingletonRegistered(systemArchitecture, minVersion) &&
           IsDDLMRegistered(systemArchitecture, minVersion);
}

private static ProcecssorArchitecture DetectSystemArchitecture()
{
    // ...see the call to IsWow64Process2(), and how the result is used...
    // ...as per `IsPackageApplicable()` in
    // [install.cpp](https://github.com/microsoft/WindowsAppSDK/blob/main/installer/dev/install.cpp)
    // line 99-116...
    // ...WARNING: Use IsWow64Process2 to detect the system architecture....
    // ...         Other similar APIs exist, but don't give reliably accurate results...
}

private static bool IsFrameworkRegistered(ProcessorArchitecture systemArchitecture,
    PackageVersion minVersion)
{
    // Check x86.
    if (!IsPackageRegisteredForCurrentUser(
        global::Microsoft.WindowsAppSDK.Runtime.Packages.Framework.PackageFamilyName,
        minVersion, ProcessorArchitecture.X86,
        PackageTypes.Framework))
    {
        return false;
    }

    // Check x64 (if necessary).
    if ((systemArchitecture == ProcessorArchitecture.X64) || 
        (systemArchitecture == ProcessorArchitcture.Arm64))
    {
        if (!IsPackageRegisteredForCurrentUser(
            global::Microsoft.WindowsAppSDK.Runtime.Packages.Framework.PackageFamilyName,
            minVersion, ProcessorArchitecture.X64,
            PackageTypes.Framework))
        {
            return false;
        }
    }

    // Check arm64 (if necessary).
    if (systemArchitecture == ProcessorArchitcture.Arm64)
    {
        if (!IsPackageRegisteredForCurrentUser(
            global::Microsoft.WindowsAppSDK.Runtime.Packages.Framework.PackageFamilyName,
            minVersion, ProcessorArchitecture.Arm64,
            PackageTypes.Framework))
        {
            return false;
        }
    }

    return true;
}

private static bool IsMainRegistered(ProcessorArchitecture systemArchitecture,
    PackageVersion minVersion)
{
    return IsPackageRegisteredForCurrentUser(
        global::Microsoft.WindowsAppSDK.Runtime.Packages.Main.PackageFamilyName,
        minVersion,
        systemArchitecture,
        PackageTypes.Main);
}

private static bool IsSingletonRegistered(ProcessorArchitecture systemArchitecture,
    PackageVersion minVersion)
{
    return IsPackageRegisteredForCurrentUser(
        global::Microsoft.WindowsAppSDK.Runtime.Packages.Singleton.PackageFamilyName,
        minVersion,
        systemArchitecture,
        PackageTypes.Main);
}

private static bool IsDDLMRegistered(ProcessorArchitecture systemArchitecture,
    PackageVersion minVersion)
{
    // ...similar to IsFrameworkRegistered, but the packageFamilyName is more complicated...
    // ...and no predefined constant is currently available...
    // ...for more details, see
    // https://github.com/microsoft/WindowsAppSDK/blob/main/specs/Deployment/MSIXPackages.md.
}

Info dan kode di atas mencakup skenario deteksi dasar. Untuk mendeteksi apakah runtime disediakan untuk semua pengguna, atau melakukan hal di atas dari Kontainer Aplikasi, dan/atau melakukannya dari proses yang dipaketkan mediumIL , diperlukan logika tambahan.

Skenario penyebaran

  • Menginstal SDK Aplikasi Windows Runtime system-wide: Penginstalan seluruh sistem mengubah komputer untuk semua pengguna, termasuk pengguna baru yang ditambahkan di masa mendatang. Jika aplikasi berjalan ditinggikan dan pengguna yang melakukan penginstalan memiliki hak istimewa admin, maka alat penginstal akan mendaftarkan paket MSIX di seluruh sistem dengan memanggil ProvisionPackageForAllUsersAsync. Jika pendaftaran di seluruh sistem tidak berhasil, penginstalan akan dilakukan untuk pengguna saat ini yang hanya melakukan penginstalan. Di lingkungan Enterprise terkelola, admin TI harus dapat memprovisikan untuk semua orang seperti biasa.

  • Arsitektur yang didistribusikan ulang oleh alat penginstal SDK Aplikasi Windows: Alat penginstal SDK Aplikasi Windows tersedia dalam x86arsitektur , , x64dan Arm64 . Setiap versi alat penginstal menyertakan paket MSIX hanya untuk arsitektur tertentu yang dinamainya. Misalnya, jika Anda menjalankan x86 WindowsAppRuntimeInstall.exe pada perangkat x64 atau dan Arm64, maka alat penginstal tersebut x86 akan disebarkan ke perangkat tersebut hanya paket untuk arsitektur x86.

  • Semua paket MSIX SDK Aplikasi Windows sudah diinstal di komputer: Paket MSIX diinstal ke lokasi di seluruh sistem dengan hanya satu salinan pada disk. Jika aplikasi mencoba penginstalan SDK Aplikasi Windows ketika semua dependensi paket MSIX sudah diinstal pada komputer, maka penginstalan tidak dilakukan.

  • Satu atau beberapa paket MSIX SDK Aplikasi Windows tidak diinstal di komputer: Saat menyebarkan SDK Aplikasi Windows, selalu coba instal semua paket MSIX (kerangka kerja, utama, singleton, DDLM) untuk memastikan bahwa semua dependensi diinstal dan Anda menghindari gangguan pada pengalaman pengguna akhir.

Persyaratan runtime untuk aplikasi yang dikemas dengan lokasi eksternal atau tidak dikemas

Aplikasi yang dikemas dengan lokasi eksternal atau tidak dikemas memiliki persyaratan runtime tambahan untuk menggunakan runtime SDK Aplikasi Windows. Ini melibatkan referensi dan menginisialisasi paket SDK Aplikasi Windows Framework saat runtime. Selain itu, API Dependensi Dinamis dapat digunakan untuk mereferensikan paket kerangka kerja lain di luar SDK Aplikasi Windows.

Menggunakan runtime SDK Aplikasi Windows

Dikemas dengan lokasi eksternal dan aplikasi yang tidak dikemas harus memanggil API Bootstrapper untuk menggunakan SDK Aplikasi Windows pada waktu proses. Ini diperlukan sebelum aplikasi dapat menggunakan fitur SDK Aplikasi Windows seperti WinUI, App Lifecycle, MRT Core, dan DWriteCore. Komponen bootstrapper memungkinkan dikemas dengan lokasi eksternal dan aplikasi yang tidak dikemas untuk melakukan tugas-tugas penting ini:

  • Temukan dan muat paket kerangka kerja SDK Aplikasi Windows ke grafik paket aplikasi.
  • Inisialisasi Dynamic Dependency Lifetime Manager (DDLM) untuk paket kerangka kerja SDK Aplikasi Windows. Tujuan dari DDLM adalah untuk mencegah layanan paket kerangka kerja SDK Aplikasi Windows saat digunakan oleh paket dengan lokasi eksternal atau aplikasi yang tidak dikemas.

Cara paling sederhana untuk memuat runtime SDK Aplikasi Windows untuk dikemas dengan lokasi eksternal dan aplikasi yang tidak dikemas adalah dengan mengatur <WindowsPackageType>None</WindowsPackageType> properti dalam file proyek Anda (.csproj atau .vcxproj). Anda juga dapat memanggil API bootstrapper langsung di kode startup aplikasi Anda untuk kontrol lebih besar atas inisialisasi. Untuk detail selengkapnya, lihat Menggunakan runtime SDK Aplikasi Windows untuk aplikasi yang dikemas dengan lokasi eksternal atau tidak dikemas dan Tutorial: Menggunakan API bootstrapper dalam aplikasi yang dikemas dengan lokasi eksternal atau tidak dikemas yang menggunakan SDK Aplikasi Windows.

Dukungan Dependensi Dinamis memungkinkan dikemas dengan lokasi eksternal dan aplikasi yang tidak dikemas untuk menjaga mekanisme penyebaran yang ada, seperti MSI atau alat penginstal apa pun, dan dapat memanfaatkan SDK Aplikasi Windows dalam aplikasi mereka. Dependensi dinamis dapat digunakan oleh dikemas, dikemas dengan lokasi eksternal, dan aplikasi yang tidak dikemas; meskipun terutama dimaksudkan untuk digunakan oleh dikemas dengan lokasi eksternal dan aplikasi yang tidak dikemas.

Ada satu DDLM untuk setiap versi dan arsitektur paket kerangka kerja SDK Aplikasi Windows. Ini berarti di x64 komputer, Anda mungkin memiliki x86 x64 dan versi DDLM untuk mendukung aplikasi kedua arsitektur.

Mereferensikan paket kerangka kerja lain menggunakan API Dependensi Dinamis

Jika Anda ingin menggunakan fitur dalam paket kerangka kerja lain di luar SDK Aplikasi Windows (misalnya, DirectX), yang dikemas dengan lokasi eksternal dan aplikasi yang tidak dikemas dapat memanggil API Dependensi Dinamis. Selain komponen bootstrapper, SDK Aplikasi Windows juga menyediakan serangkaian fungsi C/C++ yang lebih luas dan kelas WinRT yang mengimplementasikan API dependensi dinamis. API ini dirancang untuk digunakan untuk mereferensikan paket kerangka kerja apa pun secara dinamis pada waktu proses.

Untuk informasi selengkapnya, lihat Menggunakan paket kerangka kerja MSIX secara dinamis dari aplikasi desktop Anda dan sampel Dependensi Dinamis

Menyebarkan file .winmd ke komputer target

Bersama dengan aplikasi Anda, kami sarankan Anda melanjutkan dan menyebarkan file Metadata Windows (.winmd). Metadata dapat digunakan oleh berbagai API dan perilaku saat runtime, dan ketidakhadirannya dapat membatasi atau merusak fungsionalitas. Misalnya, metadata dapat digunakan untuk marshal objek di seluruh batas apartemen; dan kebutuhan untuk marshal dapat menjadi fungsi performa mesin. Karena tidak ada cara deterministik untuk mengetahui apakah Anda membutuhkan metadata, Anda harus menyebarkan .winmdkecuali Anda sangat khawatir tentang ukuran.