Share via

WINDOWS Runtime API tidak didukung di aplikasi desktop

  • Artikel

Meskipun Anda dapat menggunakan sebagian besar API Windows Runtime (WinRT) (lihat namespace Windows UWP) di aplikasi desktop C# atau C++Anda, ada dua set utama API WinRT yang tidak didukung di aplikasi desktop, atau yang memiliki batasan:

  • API yang memiliki dependensi pada fitur antarmuka pengguna (UI) yang dirancang untuk digunakan hanya di aplikasi Platform Windows Universal (UWP).
  • API yang memerlukan identitas paket (lihat Fitur yang memerlukan identitas paket). API tersebut hanya didukung di aplikasi desktop yang di kemas menggunakan MSIX.

Artikel ini menyediakan detail tentang kedua set API WinRT tersebut. Jika tersedia, artikel ini menyarankan API alternatif untuk mencapai fungsionalitas yang sama dengan API yang tidak didukung di aplikasi desktop. Sebagian besar API alternatif tersedia di WinUI 3 atau melalui antarmuka WinRT COM yang tersedia di Windows SDK.

Catatan

Aplikasi yang menggunakan .NET dapat menggunakan implementasi kelas yang disediakan untuk beberapa antarmuka WinRT COM yang tercantum dalam artikel ini. Kelas-kelas tersebut lebih mudah dikerjakan daripada menggunakan antarmuka WinRT COM secara langsung. Untuk informasi selengkapnya tentang implementasi kelas yang tersedia, lihat Memanggil API interop dari aplikasi .NET. Perhatikan bahwa kelas tersebut memerlukan .NET 6 SDK atau yang lebih baru.

Artikel ini akan diperbarui karena lebih banyak solusi dan penggantian diidentifikasi. Jika Anda mengalami masalah dengan API yang tidak tercantum di sini, buat masalah di repositori microsoft-ui-xaml dengan nama API dan detail tentang apa yang coba Anda capai dengan menggunakannya.

API yang memiliki dependensi pada fitur UI khusus UWP

Beberapa API WinRT dirancang khusus untuk skenario UI dalam aplikasi UWP. API tersebut tidak berperilaku baik di aplikasi desktop karena model utas dan perbedaan platform lainnya. API tersebut, dan API WinRT lainnya yang memiliki dependensi pada API tersebut, tidak didukung untuk digunakan di aplikasi desktop.

Kelas inti yang tidak didukung

Kelas WinRT ini tidak didukung di aplikasi desktop:

Kelas API alternatif
ApplicationView Tidak
CoreApplicationView Gunakan kelas Window yang disediakan oleh WinUI 3 sebagai gantinya.
CoreApplicationViewTitleBar Alih-alih properti ExtendViewIntoTitleBar, gunakan properti Window.ExtendsContentIntoTitleBar yang disediakan oleh WinUI 3.
CoreDispatcher Gunakan properti Microsoft.UI.Xaml.Window.DispatcherQueue yang disediakan oleh WinUI 3 sebagai gantinya.

Perhatikan bahwa properti Windows.UI.Xaml.Window.Dispatcher dan Windows.UI.Xaml.DependencyObject.Dispatcher ditampilkan null di aplikasi desktop.
CoreWindow Lihat juga Kelas yang mengimplementasikan bagian IInitializeWithWindow di bawah ini.

Alih-alih metode GetKeyState, gunakan metode InputKeyboardSource.GetKeyStateForCurrentThread yang disediakan oleh WinUI 3.

Alih-alih properti PointerCursor, gunakan properti UIElement.ProtectedCursor yang disediakan oleh WinUI 3. Anda harus memiliki subkelas UIElement untuk mengakses properti tersebut.
UserActivity Gunakan antarmuka IUserActivitySourceHostInterop COM sebagai gantinya (di useractivityinterop.h).

Untuk API WinRT lainnya yang tidak didukung di aplikasi desktop, lihat Anggota yang tidak didukung nanti dalam topik ini.

Kelas dengan metode XxxForCurrentView

Banyak kelas WinRT memiliki metode GetForCurrentView atau CreateForCurrentView statis, seperti UIView Pengaturan. GetForCurrentView. Metode XxxForCurrentView tersebut memiliki dependensi implisit pada jenis ApplicationView , yang tidak didukung di aplikasi desktop. Karena ApplicationView tidak didukung di aplikasi desktop, metode XxxForCurrentView juga tidak didukung. Beberapa metode XxxForCurrentView yang tidak didukung tidak hanya mengembalikan null, tetapi juga melemparkan pengecualian.

Catatan

CoreInputView.GetForCurrentView didukung di aplikasi desktop, dan dapat digunakan bahkan tanpa CoreWindow. Anda dapat menggunakan metode tersebut untuk mengambil objek CoreInputView pada utas apa pun; dan jika utas tersebut memiliki jendela latar depan, maka objek tersebut akan menghasilkan peristiwa.

Kelas berikut didukung di aplikasi desktop; tetapi untuk mengambil instans satu di aplikasi desktop, Anda menggunakan mekanisme yang berbeda dari metode GetForCurrentView atau CreateForCurrentView. Untuk kelas di bawah ini yang memiliki antarmuka COM yang tercantum sebagai API alternatif, pengembang C# juga dapat menggunakan antarmuka WINRT COM tersebut (lihat Memanggil API interop dari aplikasi .NET). Daftar mungkin tidak komprehensif.

Kelas API alternatif
Akun Pengaturan Pane Gunakan antarmuka COM IAccounts Pengaturan PaneInterop sebagai gantinya (di accountssettingspaneinterop.h).
CoreDragDropManager Gunakan antarmuka IDragDropManagerInterop COM sebagai gantinya (dalam dragdropinterop.h).
CoreTextServicesManager Kelas ini saat ini didukung di aplikasi desktop hanya di build Windows Insider Preview.
DataTransferManager Gunakan antarmuka IDataTransferManagerInterop COM sebagai gantinya (dalam shobjidl_core.h).
DisplayInformation Untuk mengambil instans DisplayInformation, gunakan antarmuka IDisplayInformationStaticsInterop.

Atau, alih-alih properti LogicalDpi, Anda dapat menggunakan properti XamlRoot.RasterizationScale, dan mendengarkan perubahan melalui peristiwa XamlRoot.Changed (properti XamlRoot.RasterizationScale disediakan di WinUI 3).

Dan, alih-alih properti RawPixelsPerViewPixel, Anda memiliki opsi untuk menggunakan properti XamlRoot.RasterizationScale yang disediakan oleh WinUI 3.
InputPane Gunakan antarmuka COM IInputPaneInterop sebagai gantinya (dalam inputpaneinterop.h).
PlayToManager Gunakan antarmuka IPlayToManagerInterop COM sebagai gantinya (di playtomanagerinterop.h).
Print3DManager Gunakan antarmuka IPrinting3DManagerInterop COM sebagai gantinya (dalam print3dmanagerinterop.h).
PrintManager Gunakan antarmuka IPrintManagerInterop COM sebagai gantinya (dalam printmanagerinterop.h).
RadialController Gunakan antarmuka IRadialControllerInterop COM sebagai gantinya (di radialcontrollerinterop.h).
RadialControllerConfiguration Gunakan antarmuka IRadialControllerConfigurationInterop COM sebagai gantinya (di radialcontrollerinterop.h).
ResourceContext Lihat migrasi MRT ke MRT Core.
ResourceLoader Lihat migrasi MRT ke MRT Core.
SpatialInteractionManager Gunakan antarmuka ISpatialInteractionManagerInterop COM sebagai gantinya (dalam spatialinteractionmanagerinterop.h).
SystemMediaTransportControls Gunakan antarmuka ISystemMediaTransportControlsInterop COM sebagai gantinya (di systemmediatransportcontrolsinterop.h).
UserActivityRequestManager Gunakan antarmuka IUserActivityRequestManagerInterop COM insead (dalam useractivityinterop.h).
UIView Pengaturan Gunakan antarmuka IUIView Pengaturan Interop COM sebagai gantinya (di uiviewsettingsinterop.h).

Kelas berikut tidak didukung di aplikasi desktop karena API tidak menyediakan alternatif untuk metode GetForCurrentView atau CreateForCurrentView mereka. Daftar mungkin tidak komprehensif.

Kelas API alternatif
AppCapture Tidak
BrightnessOverride Tidak
Koneksi edAnimationService Tidak
CoreInputView Tidak
CoreWindowResizeManager Tidak
DisplayEnhancementOverride Tidak
EdgeGesture Tidak
GazeInputSourcePreview Tidak
HdmiDisplayInformation Tidak
HolographicKeyboardPlacementOverridePreview Tidak
KeyboardDeliveryInterceptor Tidak
LockApplicationHost Tidak
MouseDevice Tidak
PointerVisualization Pengaturan Tidak
ProtectionPolicyManager Tidak
SearchPane Tidak
Pengaturan Pane Tidak
SystemNavigationManager Tidak
SystemNavigationManagerPreview Tidak
WebAuthenticationBroker Tidak ada. untuk detail selengkapnya, lihat masalah GitHub WebAuthenticationBroker.AuthenticateAsync.

Kelas yang mengimplementasikan IInitializeWithWindow

Pemilih tertentu, popup, dialog, dan objek Windows Runtime (WinRT) lainnya bergantung pada CoreWindow; biasanya, untuk menampilkan UI. Meskipun CoreWindow tidak didukung di aplikasi desktop (lihat Kelas inti yang tidak didukung di atas), Anda masih dapat menggunakan banyak kelas WinRT tersebut di aplikasi desktop Anda dengan menambahkan sedikit kode interoperabilitas.

Untuk informasi selengkapnya (termasuk daftar jenis yang terpengaruh), dan contoh kode, lihat Menampilkan objek UI WinRT yang bergantung pada CoreWindow.

Anggota yang tidak didukung

Bagian ini mencantumkan (atau menjelaskan, di mana daftar komprehensif tidak dimungkinkan) anggota tertentu dari kelas WinRT yang tidak didukung untuk digunakan di aplikasi desktop. Kecuali dinyatakan lain, kelas lainnya selain dari anggota ini didukung di aplikasi desktop.

Acara

Kelas berikut didukung di aplikasi desktop, kecuali untuk peristiwa yang ditentukan.

Kelas Kejadian yang tidak didukung
UI Pengaturan ColorValuesChanged
Aksesibilitas Pengaturan HighContrastChanged

Metode

Kelas berikut didukung di aplikasi desktop, kecuali untuk metode yang ditentukan.

Kelas Metode yang tidak didukung
DeviceInformationPairing PairAsync

Metode yang menggunakan pola penamaan Permintaan

Sebagian besar metode yang mengikuti pola penamaan Permintaan—seperti AppCapability.RequestAccessAsync dan StoreContext.RequestPurchaseAsync—tidak didukung di aplikasi desktop. Secara internal, metode ini menggunakan kelas Windows.UI.Popups. Kelas tersebut mengharuskan utas memiliki objek CoreWindow , yang tidak didukung di aplikasi desktop.

Daftar lengkap metode yang mengikuti pola penamaan Permintaan sangat panjang, dan artikel ini tidak menyediakan daftar lengkap metode tersebut.

API yang memerlukan identitas paket

Kelas WinRT berikut memerlukan identitas paket (lihat Fitur yang memerlukan identitas paket). API ini hanya didukung di aplikasi desktop yang di kemas (yaitu, yang memiliki identitas paket saat runtime). Daftar mungkin tidak komprehensif.

Selain itu, ketika dipanggil dari aplikasi desktop yang tidak memiliki identitas paket, metode AdaptiveMediaSource.CreateFromUriAsync tidak mendukung ms-appx format dan ms-resource URI.