Chamar APIs de interoperabilidade com um aplicativo .NET

  • Artigo

Como um desenvolvedor de aplicativos da área de trabalho em C#, no .NET, você pode usar classes de interoperabilidade em C# que representam várias funções de interoperabilidade e interfaces de interoperabilidade COM do WinRT (Windows Runtime). Elas incluem classes em C# que representam IWindowNative, IInitializeWithWindow, a função GetWindowIdFromWindow e muitas outras.

Este tópico lista as classes de interoperabilidade em C# disponíveis e mostra como usá-las. A seção Tela de fundo no final do tópico descreve como as interfaces de interoperabilidade foram usadas em versões anteriores do .NET e por que a alteração foi feita.

Configurar um projeto da área de trabalho do .NET para usar as classes de interoperabilidade do C#

As classes de interoperabilidade em C# listadas na próxima seção (Classes de interoperabilidade em C# disponíveis) estão disponíveis no .NET como parte do SDK de Aplicativo do Windows ou usando um Moniker da Estrutura de Destino específico, como veremos.

Em um projeto de área de trabalho em C# do WinUI 3

Quando você cria um projeto da WinUI 3 no Visual Studio (confira Criar seu primeiro projeto da WinUI 3), o projeto já fica configurado e você pode começar a usar todas as classes de interoperabilidade C# imediatamente.

Em outros tipos de projeto de área de trabalho em C# (WPF ou WinForms)

No caso de outros tipos de projeto de área de trabalho do .NET, como WPF (Windows Presentation Foundation) ou WinForms (Windows Forms), configure o projeto primeiro para acessar as classes de interoperabilidade em C#. Para o primeiro conjunto de classes listado abaixo, você precisará fazer referência ao SDK de Aplicativo do Windows. Para o segundo conjunto, você precisará configurar um Moniker da Estrutura de Destino que é direcionado ao Windows 10, versão 1809 ou posterior, desta forma:

  1. Abra o arquivo de projeto para seu projeto de área de trabalho .NET. em C#.

  2. No arquivo .csproj, modifique o elemento TargetFramework para direcioná-lo a uma versão específica do .NET e do SDK do Windows. Por exemplo, o elemento a seguir é adequado para um projeto .NET 6 direcionado para o Windows 10, versão 2004.

    <PropertyGroup>
  <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>
</PropertyGroup>

Para obter mais informações, incluindo uma lista de outros valores compatíveis, confira Usar a opção do Moniker da Estrutura de Destino.

Classes de interoperabilidade em C# disponíveis

Observação

As classes abaixo exigem o SDK do .NET 6 ou posterior.

Veja aqui as classes de interoperabilidade em C# disponíveis, mapeadas na função de interoperabilidade subjacente ou na interface de interoperabilidade COM do WinRT. Cada classe listada implementa a função/métodos da API de interoperabilidade subjacente e fornece wrappers fortemente tipados para parâmetros e valores de retorno. Por exemplo, Windows.ApplicationModel.DataTransfer.DragDrop.Core.DragDropManagerInterop.GetForWindow exige um parâmetro de identificador de janela IntPtr (HWND) e retorna um objeto CoreDragDropManager. Todas as classes de interoperabilidade em C# abaixo e os métodos associados são estáticos.

Disponível como parte do SDK do Aplicativo do Windows

A classe Microsoft.UI.Win32Interop implementa os métodos de interoperabilidade do C# na tabela abaixo. Para ver um exemplo de código, confira Gerenciar janelas de aplicativo.

Função de interoperabilidade Método de interoperabilidade do C#
GetDisplayIdFromMonitor (Microsoft.UI) DisplayId Win32Interop.GetDisplayIdFromMonitor(IntPtr hmonitor)
GetIconFromIconId (Microsoft.UI) IntPtr Win32Interop.GetIconFromIconId(IconId iconId)
GetIconIdFromIcon (Microsoft.UI) IconId Win32Interop.GetIconIdFromIcon(IntPtr hicon)
GetMonitorFromDisplayId (Microsoft.UI) IntPtr Win32Interop.GetMonitorFromDisplayId(DisplayId displayId)
GetWindowFromWindowId (Microsoft.UI) IntPtr Win32Interop.GetWindowFromWindowId(WindowId windowId)
GetWindowIdFromWindow (Microsoft.UI) WindowId Win32Interop.GetWindowIdFromWindow(IntPtr hwnd)

Disponível por meio do Moniker da Estrutura de Destino

Interface de interoperabilidade COM do WinRT Classe de interoperabilidade em C#
IAccountsSettingsPaneInterop (Windows.UI.ApplicationSettings) AccountsSettingsPaneInterop
IDisplayInformationStaticsInterop Apresentado com o TFM net6.0-windows10.0.22621.0 e o .NET 6.0.7.

(Windows.Graphics.Display) DisplayInformationInterop
IDragDropManagerInterop (Windows.ApplicationModel.DataTransfer.DragDrop.Core) DragDropManagerInterop
IInitializeWithWindow (WinRT.Interop) InitializeWithWindow
IInputPaneInterop (Windows.UI.ViewManagement) InputPaneInterop
IPlayToManagerInterop (Windows.Media.PlayTo) PlayToManagerInterop
IPrintManagerInterop (Windows.Graphics.Printing) PrintManagerInterop
IRadialControllerConfigurationInterop (Windows.UI.Input) RadialControllerConfigurationInterop
IRadialControllerIndependentInputSourceInterop (Windows.UI.Input.Core) RadialControllerIndependentInputSourceInterop
IRadialControllerInterop (Windows.UI.Input) RadialControllerInterop
ISpatialInteractionManagerInterop (Windows.UI.Input.Spatial) SpatialInteractionManagerInterop
ISystemMediaTransportControlsInterop (Windows.Media) SystemMediaTransportControlsInterop
IUIViewSettingsInterop (Windows.UI.ViewManagement) UIViewSettingsInterop
IUserConsentVerifierInterop (Windows.Security.Credentials.UI) UserConsentVerifierInterop
IWebAuthenticationCoreManagerInterop (Windows.Security.Authentication.Web.Core) WebAuthenticationCoreManagerInterop
IWindowNative Somente WinUI 3

(WinRT.Interop) WindowNative

Para ver alternativas ao WPF e ao WinForms, confira Recuperar um identificador de janela (HWND).

Exemplo de código

Este exemplo de código demonstra como usar duas das classes de interoperabilidade em C# em um aplicativo WinUI 3 (confira Criar seu primeiro projeto da WinUI 3). O cenário de exemplo é exibir um Windows.Storage.Pickers.FolderPicker. No entanto, antes de exibir o seletor em um aplicativo da área de trabalho, é necessário inicializá-lo com o identificador (HWND) da janela do proprietário.

  1. Você pode obter um identificador de janela (HWND) usando a interface de interoperabilidade COM IWindowNative do WinRT. E (observando a tabela na seção anterior) essa interface é representada pela classe de interoperabilidade em C# WinRT.Interop.WindowNative. Neste exemplo, o objeto this é uma referência a um objeto Microsoft.UI.Xaml.Window do arquivo code-behind da janela principal.
  2. Para inicializar uma parte da interface do usuário com uma janela do proprietário, use a interface de interoperabilidade COM IInitializeWithWindow do WinRT. E essa interface é representada pela classe de interoperabilidade em C# WinRT.Interop.InitializeWithWindow.
private async void myButton_Click(object sender, RoutedEventArgs e)
{
    // Create a folder picker.
    var folderPicker = new Windows.Storage.Pickers.FolderPicker();

    // 1. Retrieve the window handle (HWND) of the current WinUI 3 window.
    var hWnd = WinRT.Interop.WindowNative.GetWindowHandle(this);

    // 2. Initialize the folder picker with the window handle (HWND).
    WinRT.Interop.InitializeWithWindow.Initialize(folderPicker, hWnd);

    // Use the folder picker as usual.
    folderPicker.FileTypeFilter.Add("*");
    var folder = await folderPicker.PickSingleFolderAsync();
}

Veja também Recuperar um identificador de janela (HWND) e Exibir objetos da interface do usuário do WinRT que dependem do CoreWindow.

Tela de fundo

As versões anteriores do .NET Framework e do .NET Core tinham conhecimento integrado do WinRT. Com as versões anteriores, era possível definir uma interface de interoperabilidade diretamente no C# com o atributo ComImport e fazer a seleção direta de uma classe projetada para essa interface de interoperabilidade.

Como o WinRT é uma tecnologia específica do Windows, para dar suporte às metas de portabilidade e eficiência do .NET, removemos o suporte de projeção do WinRT do compilador C# e do runtime do .NET e o movemos para o kit de ferramentas C#/WinRT (confira O suporte integrado para o WinRT foi removido do .NET).

Embora a técnica ComImport ainda funcione para interfaces de interoperabilidade baseadas em IUnknown, ela não funciona mais para interfaces baseadas em IInspectable que são usadas para interoperação com o WinRT.

Portanto, como uma substituição, no .NET é possível usar as classes de interoperabilidade em C# descritas neste tópico.

Solução de problemas e problemas conhecidos

Atualmente, não há nenhum problema conhecido nas classes de interoperabilidade C#. Para fornecer comentários ou relatar outros problemas, adicione seus comentários sobre um problema existente ou registre um novo problema no repositório GitHub WindowsAppSDK.