Condividi tramite

API di Windows Runtime non supportate nelle app desktop

  • Articolo

Sebbene sia possibile usare la maggior parte delle API Windows Runtime (WinRT) (vedi Spazi dei nomi UWP Windows) nell'app desktop C# o C++, esistono due set principali di API WinRT non supportate nelle app desktop o che presentano restrizioni:

  • API con dipendenze dalle funzionalità dell'interfaccia utente progettate per l'uso solo in un'app UWP (Universal Windows Platform).
  • API che richiedono l'identità del pacchetto (vedi Funzionalità che richiedono l'identità del pacchetto). Tali API sono supportate solo nelle app desktop incluse in pacchetti con MSIX.

Questo articolo fornisce informazioni dettagliate su entrambi i set di API WinRT. Se disponibile, questo articolo suggerisce API alternative per ottenere le stesse funzionalità delle API non supportate nelle app desktop. La maggior parte delle API alternative è disponibile in WinUI 3 o tramite interfacce COM WinRT disponibili in Windows SDK.

Nota

Le app che usano .NET possono usare le implementazioni di classi fornite per alcune delle interfacce COM WinRT elencate in questo articolo. Queste classi sono più facili da usare rispetto all'utilizzo diretto delle interfacce COM WinRT. Per altre informazioni sulle implementazioni di classi disponibili, vedi Chiamare API di interoperabilità da un'app .NET. Nota che queste classi richiedono .NET 6 SDK o versione successiva.

Questo articolo verrà aggiornato man mano che vengono identificate altre soluzioni alternative e sostituzioni. Se si verifica un problema con un'API non elencata qui, crea un problema nel repository microsoft-ui-xaml con il nome dell'API e i dettagli su ciò che speri di ottenere usandolo.

API con dipendenze dalle funzionalità dell'interfaccia utente solo UWP

Alcune API WinRT sono state progettate appositamente per gli scenari di interfaccia utente in un'app UWP. Queste API non si comportano correttamente nelle app desktop a causa del modello di threading e di altre differenze di piattaforma. Queste API e altre API WinRT con dipendenze non sono supportate per l'uso nelle app desktop.

Classi core non supportate

Queste classi WinRT non sono supportate nelle app desktop:

Classe API alternative
ApplicationView Nessuno
CoreApplicationView Usa invece la classe Window fornita da WinUI 3.
CoreApplicationViewTitleBar Anziché la proprietà ExtendViewIntoTitleBar, utilizza la proprietà Window.ExtendsContentIntoTitleBar fornita da WinUI 3.
CoreDispatcher Usa invece la proprietà Microsoft.UI.Xaml.Window.DispatcherQueue fornita da WinUI 3.

Nota che le proprietà Windows.UI.Xaml.Window.Dispatcher e Windows.UI.Xaml.DependencyObject.Dispatcher restituiscono null in un'app desktop.
CoreWindow Vedi anche la sezione Classi che implementano IInitializeWithWindow di seguito.

Anziché il metodo GetKeyState, usa il metodo InputKeyboardSource.GetKeyStateForCurrentThread fornito da WinUI 3.

Anziché la proprietà PointerCursor, usa la proprietà UIElement.ProtectedCursor fornita da WinUI 3. Per accedere a tale proprietà, è necessario avere una sottoclasse di UIElement.
UserActivity Usa invece l'interfaccia COM IUserActivitySourceHostInterop (in useractivityinterop.h).

Per altre API WinRT non supportate nelle app desktop, vedi Membri non supportati più avanti in questo argomento.

Classi con un metodo XxxForCurrentView

Molte classi WinRT hanno un metodo GetForCurrentView o CreateForCurrentView statico, ad esempio UIViewSettings.GetForCurrentView. Questi metodi XxxForCurrentView hanno una dipendenza implicita dal tipo ApplicationView, che non è supportato nelle app desktop. Poiché ApplicationView non è supportato nelle app desktop, nessuno dei metodi XxxForCurrentView è supportato. Alcuni metodi XxxForCurrentView non supportati non solo restituiscono null, ma generano anche eccezioni.

Nota

CoreInputView.GetForCurrentView è supportato nelle app desktop e può essere usato anche senza CoreWindow. È possibile utilizzare questo metodo per recuperare un oggetto CoreInputView in qualsiasi thread e, se tale thread ha una finestra in primo piano, tale oggetto genererà eventi.

Le classi seguenti sono supportate in app desktop, ma per recuperare un'istanza di una di queste in un'app desktop, si usa un meccanismo diverso dai metodi GetForCurrentView o CreateForCurrentView. Per le classi seguenti che hanno un'interfaccia COM elencata come API alternativa, gli sviluppatori C# possono usare anche queste interfacce COM WinRT (vedi Chiamare le API di interoperabilità da un'app .NET). L'elenco potrebbe non essere completo.

Classe API alternative
AccountsSettingsPane Usa invece l'interfaccia COM IAccountsSettingsPaneInterop (in accountssettingspaneinterop.h).
CoreDragDropManager Usa invece l'interfaccia COM IDragDropManagerInterop (in dragdropinterop.h).
CoreTextServicesManager Questa classe è attualmente supportata nelle app desktop solo nelle build di anteprima Windows Insider.
DataTransferManager Usa invece l'interfaccia COM IDataTransferManagerInterop (in shobjidl_core.h).
DisplayInformation Per recuperare un'istanza di DisplayInformation, usa l'interfaccia IDisplayInformationStaticsInterop.

In alternativa, invece della proprietà LogicalDpi, puoi usare la proprietà XamlRoot.RasterizationScale e ascoltare le modifiche tramite l'evento XamlRoot.Changed (la proprietà XamlRoot.RasterizationScaleviene fornita in WinUI 3).

Invece della proprietà RawPixelsPerViewPixel, puoi usare la proprietà XamlRoot.RasterizationScale fornita da WinUI 3.
InputPane Usa invece l'interfaccia COM IInputPaneInterop (in inputpaneinterop.h).
PlayToManager Usa invece l'interfaccia COM IPlayToManagerInterop (in playtomanagerinterop.h).
Print3DManager Usa invece l'interfaccia COM IPrinting3DManagerInterop (in print3dmanagerinterop.h).
PrintManager Usare invece l'interfaccia COM IPrintManagerInterop (in printmanagerinterop.h).
RadialController Usa invece l'interfaccia COM IRadialControllerInterop (in radialcontrollerinterop.h).
RadialControllerConfiguration Usa invece l'interfaccia COM IRadialControllerConfigurationInterop (in radialcontrollerinterop.h).
ResourceContext Vedi Migrazione da MRT a MRT Core.
ResourceLoader Vedi Migrazione da MRT a MRT Core.
SpatialInteractionManager Usa invece l'interfaccia COM ISpatialInteractionManagerInterop (in spatialinteractionmanagerinterop.h).
SystemMediaTransportControls Usa invece l'interfaccia COM ISystemMediaTransportControlsInterop (in systemmediatransportcontrolsinterop.h).
UserActivityRequestManager Usa invece l'interfaccia COM IUserActivityRequestManagerInterop (in useractivityinterop.h).
UIViewSettings Usa invece l'interfaccia COM IUIViewSettingsInterop (in uiviewsettingsinterop.h).

Le classi seguenti non sono supportate nelle app desktop perché le API non forniscono un'alternativa al metodo GetForCurrentView o CreateForCurrentView. L'elenco potrebbe non essere completo.

Classe API alternative
AppCapture Nessuno
BrightnessOverride Nessuno
ConnectedAnimationService Nessuno
CoreInputView Nessuno
CoreWindowResizeManager Nessuno
DisplayEnhancementOverride Nessuno
EdgeGesture Nessuno
GazeInputSourcePreview Nessuno
HdmiDisplayInformation Nessuno
HolographicKeyboardPlacementOverridePreview Nessuno
KeyboardDeliveryInterceptor Nessuno
LockApplicationHost Nessuno
MouseDevice Nessuno
PointerVisualizationSettings Nessuno
ProtectionPolicyManager Nessuno
SearchPane Nessuno
SettingsPane Nessuno
SystemNavigationManager Nessuno
SystemNavigationManagerPreview Nessuno
WebAuthenticationBroker Nessuno. Per altre informazioni, vedi il problema GitHub WebAuthenticationBroker.AuthenticateAsync genera COMException.

Classi che implementano IInitializeWithWindow

Alcuni strumenti di selezione, popup, finestre di dialogo e altri oggetti Windows Runtime (WinRT) dipendono da CoreWindow, in genere per visualizzare un'interfaccia utente. Anche se CoreWindow non è supportato nelle app desktop (vedi sopra Classi core non supportate), puoi comunque usare molte di queste classi WinRT nell'app desktop aggiungendo una parte del codice di interoperabilità.

Per altre info (incluso un elenco di tipi interessati) ed esempi di codice, vedi Visualizzare gli oggetti dell'interfaccia utente WinRT che dipendono da CoreWindow.

Membri non supportati

Questa sezione elenca, o descrive, (un elenco completo non è possibile) membri specifici delle classi WinRT che non sono supportate per l'uso nelle app desktop. Se non diversamente specificato, le altre classi a parte questi membri sono supportate nelle app desktop.

evento

Le classi seguenti sono supportate nelle app desktop, ad eccezione degli eventi specificati.

Classe Eventi non supportati
UISettings ColorValuesChanged
AccessibilitySettings HighContrastChanged

Metodi

Le classi seguenti sono supportate nelle app desktop, ad eccezione dei metodi specificati.

Classe Metodi non supportati
DeviceInformationPairing PairAsync

Metodi che usano il modello di denominazione delle richieste

La maggior parte dei metodi che seguono il modello di denominazione Request - come AppCapability.RequestAccessAsync e StoreContext.RequestPurchaseAsync- non sono supportati nelle applicazioni desktop. Internamente, questi metodi usano la classe Windows.UI.Popups. Tale classe richiede che il thread abbia un oggetto CoreWindow, che non è supportato nelle app desktop.

L'elenco completo dei metodi che seguono il modello di denominazione delle richieste è molto lungo e questo articolo non fornisce un elenco completo di tali metodi.

API che richiedono l'identità del pacchetto

Le classi WinRT seguenti richiedono l'identità del pacchetto (vedi Funzionalità che richiedono l'identità del pacchetto). Queste API sono supportate solo nelle app desktop incluse in un pacchetto, ovvero con identità del pacchetto in fase di esecuzione. L'elenco potrebbe non essere completo.

Inoltre, quando chiamati da un'app desktop che non dispone dell'identità del pacchetto, i metodi AdaptiveMediaSource.CreateFromUriAsync non supportano i formati URI ms-appx e ms-resource.