APIs do Windows Runtime sem suporte em aplicativos para desktop

  • Artigo

Embora você possa usar a maioria das APIs do WinRT (Windows Runtime) (confira Namespaces UWP do Windows) em seu aplicativo para desktop C# ou C++, há dois conjuntos principais de APIs do WinRT que não têm suporte em aplicativos para desktop ou que têm restrições:

  • APIs que têm dependências em recursos de interface do usuário que foram projetados para uso somente em um aplicativo da UWP (Plataforma Universal do Windows).
  • APIs que exigem identificador de pacote (confira Recursos que exigem identificador de pacote). Essas APIs só são compatíveis com aplicativos para desktop que são empacotados usando o MSIX.

Este artigo fornece detalhes sobre esses dois conjuntos de APIs do WinRT. Quando disponível, este artigo sugere APIs alternativas para obter a mesma funcionalidade que as APIs não compatíveis com aplicativos para desktop. A maioria das APIs alternativas está disponível no WinUI 3 ou por meio de interfaces COM do WinRT que estão disponíveis no SDK do Windows.

Observação

Aplicativos que usam o .NET podem usar implementações de classe fornecidas em algumas das interfaces COM do WinRT listadas neste artigo. Essas classes são mais fáceis de trabalhar do que usar as interfaces COM do WinRT diretamente. Para obter mais informações sobre as implementações de classe disponíveis, confira Chamar APIs de interoperabilidade com um aplicativo .NET. Observe que essas classes exigem o SDK do .NET 6 ou posterior.

Este artigo será atualizado à medida que mais soluções alternativas e substituições forem identificadas. Se você encontrar um problema com uma API não listada aqui, crie um problema no repositório microsoft-ui-xaml com o nome da API e forneça detalhes sobre o que você está tentando realizar ao usá-la.

APIs que têm dependências em recursos de interface do usuário projetados somente para uso em UWP

Algumas APIs do WinRT foram projetadas especificamente para cenários de interface do usuário no aplicativo UWP. Essas APIs não se comportam corretamente em aplicativos para desktop, devido a modelos de threading e outras diferenças de plataforma. Essas APIs e outras APIs do WinRT que têm dependências nelas não são compatíveis com aplicativos para desktop.

Principais classes não compatíveis

Estas classes do WinRT não têm suporte em aplicativos de área de trabalho:

Classe APIs alternativas
ApplicationView Nenhum
CoreApplicationView Em vez disso, use a classe Window fornecida pelo WinUI 3.
CoreApplicationViewTitleBar Em vez da propriedade ExtendViewIntoTitleBar, use a propriedade Window.ExtendsContentIntoTitleBar fornecida pelo WinUI 3.
CoreDispatcher Em vez disso, use a propriedade Microsoft.UI.Xaml.Window.DispatcherQueue fornecida pelo WinUI 3.

Observe que as propriedades Windows.UI.Xaml.Window.Dispatcher e Windows.UI.Xaml.DependencyObject.Dispatcher retornam null em um aplicativo da área de trabalho.
CoreWindow Veja também a seção Classes que implementam IInitializeWithWindow abaixo.

Em vez do método GetKeyState, use o método InputKeyboardSource.GetKeyStateForCurrentThread fornecido pelo WinUI 3.

Em vez da propriedade PointerCursor, use a propriedade UIElement.ProtectedCursor fornecida pelo WinUI 3. Você precisará ter uma subclasse do UIElement para acessar essa propriedade.
UserActivity Em vez disso, use a interface COM IUserActivitySourceHostInterop (em useractivityinterop.h).

Para outras APIs do WinRT não compatíveis com aplicativos para desktop, confira Membros incompatíveis mais adiante neste tópico.

Classes com um método XxxForCurrentView

Muitas classes do WinRT têm um método GetForCurrentView ou CreateForCurrentView estático, como UIViewSettings.GetForCurrentView. Esses métodos XxxForCurrentView têm uma dependência implícita ao tipo ApplicationView, que não é compatível com aplicativos para desktop. Como o ApplicationView não é compatível com aplicativos para desktop, nenhum dos métodos XxxForCurrentView também tem suporte. Alguns métodos XxxForCurrentView sem suporte vão retornar null e também vão gerar exceções.

Observação

CoreInputView.GetForCurrentViewé compatível com aplicativos para desktop e pode ser usado mesmo sem um CoreWindow. Você pode usar esse método para recuperar um objeto CoreInputView em qualquer thread e, se esse thread tiver uma janela em primeiro plano, esse objeto produzirá eventos.

As classes a seguir são compatíveis com aplicativos da área de trabalho; mas para recuperar uma instância em um aplicativo da área de trabalho, você usa um mecanismo diferente dos métodos GetForCurrentView ou CreateForCurrentView. Nas classes abaixo que têm uma interface COM listada como API alternativa, os desenvolvedores C# também podem consumir essas interfaces COM do WinRT (confira Chamar APIs de interoperabilidade de um aplicativo .NET). A lista pode não ser abrangente.

Classe APIs alternativas
AccountsSettingsPane Em vez disso, use a interface COM IAccountsSettingsPaneInterop (em accountssettingspaneinterop.h).
CoreDragDropManager Em vez disso, use a interface COM IDragDropManagerInterop (em dragdropinterop.h).
CoreTextServicesManager Atualmente, essa classe tem suporte em aplicativos para desktop somente em builds do Windows Insider Preview.
DataTransferManager Em vez disso, use a interface COM IDataTransferManagerInterop (em shobjidl_core.h).
DisplayInformation Para recuperar uma instância de DisplayInformation, use a interface IDisplayInformationStaticsInterop.

Ou, em vez de usar a propriedade LogicalDpi, você pode usar a propriedade XamlRoot.RasterizationScale, bem como observar as alterações no evento XamlRoot.Changed (a propriedade XamlRoot.RasterizationScale é fornecida no WinUI 3).

E, em vez da propriedade RawPixelsPerViewPixel, você tem a opção de usar a propriedade XamlRoot.RasterizationScale fornecida pelo WinUI 3.
InputPane Em vez disso, use a interface COM IInputPaneInterop (em inputpaneinterop.h).
PlayToManager Em vez disso, use a interface COM IPlayToManagerInterop (em playtomanagerinterop.h).
Print3DManager Em vez disso, use a interface COM IPrinting3DManagerInterop (em print3dmanagerinterop.h).
PrintManager Em vez disso, use a interface COM IPrintManagerInterop (em printmanagerinterop.h).
RadialController Em vez disso, use a interface COM IRadialControllerInterop (em radialcontrollerinterop.h).
RadialControllerConfiguration Em vez disso, use a interface COM IRadialControllerConfigurationInterop (em radialcontrollerinterop.h).
ResourceContext Confira Migração do MRT para MRT Core.
ResourceLoader Confira Migração do MRT para MRT Core.
SpatialInteractionManager Em vez disso, use a interface COM ISpatialInteractionManagerInterop (em spatialinteractionmanagerinterop.h).
SystemMediaTransportControls Em vez disso, use a interface COM ISystemMediaTransportControlsInterop (em systemmediatransportcontrolsinterop.h).
UserActivityRequestManager Em vez disso, use a interface COM IUserActivityRequestManagerInterop (em useractivityinterop.h).
UIViewSettings Em vez disso, use a interface COM IUIViewSettingsInterop (em uiviewsettingsinterop.h).

As classes a seguir não são compatíveis com aplicativos para desktop porque as APIs não fornecem uma alternativa para o método GetForCurrentView ou CreateForCurrentView desses aplicativos. A lista pode não ser abrangente.

Classe APIs alternativas
AppCapture Nenhum
BrightnessOverride Nenhum
ConnectedAnimationService Nenhum
CoreInputView Nenhum
CoreWindowResizeManager Nenhum
DisplayEnhancementOverride Nenhum
EdgeGesture Nenhum
GazeInputSourcePreview Nenhum
HdmiDisplayInformation Nenhum
HolographicKeyboardPlacementOverridePreview Nenhum
KeyboardDeliveryInterceptor Nenhum
LockApplicationHost Nenhum
MouseDevice Nenhum
PointerVisualizationSettings Nenhum
ProtectionPolicyManager Nenhum
SearchPane Nenhum
SettingsPane Nenhum
SystemNavigationManager Nenhum
SystemNavigationManagerPreview Nenhum
WebAuthenticationBroker Nenhum. para obter mais detalhes, confira o problema WebAuthenticationBroker.AuthenticateAsync lança COMException no GitHub.

Classes que implementam IInitializeWithWindow

Determinados seletores, pop-ups, caixas de diálogo e outros objetos do WinRT (Windows Runtime) dependem de um CoreWindow; normalmente, para exibir uma interface do usuário. Embora não haja suporte para CoreWindow em aplicativos da área de trabalho (veja Classes Core sem suporte acima), ainda é possível usar muitas dessas classes do WinRT nesses aplicativos adicionando algum código de interoperação.

Para saber mais (incluindo uma lista de tipos afetados) e ver exemplos de código, confira Exibir objetos da interface do usuário do WinRT que dependem do CoreWindow.

Membros sem suporte

Esta seção lista (ou descreve, em situações em que uma lista abrangente não é possível) membros específicos de classes do WinRT que não têm suporte para uso em aplicativos para da área de trabalho. Salvo indicação em contrário, o restante das classes, exceto esses membros, é compatível com aplicativos para desktop.

Eventos

As classes a seguir são compatíveis com aplicativos para desktop, exceto para os eventos especificados.

Classe Eventos sem suporte
UISettings ColorValuesChanged
AccessibilitySettings HighContrastChanged

Métodos

As classes a seguir são compatíveis com aplicativos para desktop, exceto para os métodos especificados.

Classe Métodos sem suporte
DeviceInformationPairing PairAsync

Métodos que usam o padrão de nomenclatura de Solicitação

A maioria dos métodos que seguem o padrão de nomenclatura de Solicitação – como AppCapability.RequestAccessAsync e StoreContext.RequestPurchaseAsync– não são compatíveis com um aplicativo da área de trabalho. Internamente, esses métodos usam a classe Windows.UI.Popups. Essa classe requer que o thread tenha um objeto CoreWindow, que não é compatível com aplicativos para desktop.

A lista completa de métodos que seguem o padrão de nomenclatura de Solicitação é muito longa, e este artigo não fornece uma lista abrangente desses métodos.

APIs que exigem o identificador de pacote

As classes do WinRT a seguir exigem o identificador de pacote (confira Recursos que exigem o identificador de pacote). Essas APIs são compatíveis apenas com aplicativos para desktop empacotados (ou seja, que têm um identificador de pacote em runtime). A lista pode não ser abrangente.

Além disso, quando chamados de um aplicativo da área de trabalho que não tem identificador de pacote, os métodos AdaptiveMediaSource.CreateFromUriAsync não dão suporte aos formatos de URI ms-appx e ms-resource.