Use classes de interoperabilidade COM do WinRT em .NET

Alguns objetos WinRT (seletores de ficheiros, diálogos, interface de partilha) precisam de um handle de janela (HWND) antes de funcionarem numa aplicação de ambiente de trabalho. As projeções .NET destas interfaces de interoperabilidade COM do WinRT dão-lhe classes C# seguras para tipos — como WinRT.Interop.InitializeWithWindow e WinRT.Interop.WindowNative — por isso não precisa de escrever chamadas COM QueryInterface manuais.

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

Configure um projeto de desktop .NET para usar as classes Interop do C#

As classes de interoperabilidade C# listadas na secção seguinte (Classes de interoperabilidade C# disponíveis) estão disponíveis em .NET quer como parte do SDK de Aplicações Windows, quer usando um particular Target Framework Moniker, como veremos.

Num projeto de WinUI 3 em C# para desktop

Quando crias um novo project WinUI no Visual Studio (ver Cria o teu primeiro WinUI project), o teu project já está configurado e podes começar a usar todas as classes de interoperabilidade em C# imediatamente.

Noutros tipos de projetos de ambiente de trabalho C# (WPF ou WinForms)

Para outros tipos de projeto .NET para desktop — como Windows Presentation Foundation (WPF) ou Windows Forms (WinForms) — terá de configurar o seu projeto antes de poder aceder às classes de interoperabilidade em C#. Para o primeiro conjunto de disciplinas listadas abaixo, terá de consultar o SDK de Aplicações Windows. Para o segundo conjunto, terá de configurar um Target Framework Moniker que seja direcionado para Windows 10, versão 1809 ou posterior, desta forma:

1. Abra o ficheiro do seu projeto de ambiente de trabalho C# .NET.

2. No ficheiro .csproj, modifique o elemento TargetFramework para direcionar uma versão específica do .NET e do SDK do Windows. Por exemplo, o seguinte elemento é apropriado para um projeto .NET 8 que tem como alvo o Windows 10, versão 2004.

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

Para obter mais informações, incluindo uma lista de outros valores suportados, consulte opção Usar o Moniker da estrutura de destino.

Classes de interoperabilidade C# disponíveis

Aqui estão as classes de interoperabilidade C# disponíveis, mapeadas a partir de sua função de interoperabilidade subjacente ou interface de interoperabilidade WinRT COM. Cada classe listada implementa a função/métodos de sua API de interoperabilidade subjacente e fornece wrappers seguros para parâmetros e valores de retorno. Por exemplo, o Windows.ApplicationModel.DataTransfer.DragDrop.Core.DragDropManagerInterop.GetForWindow requer um parâmetro IntPtr window handle (HWND) e devolve um objeto CoreDragDropManager . Todas as classes de interoperabilidade C# abaixo e os métodos associados são estáticos.

Disponível como parte do SDK de Aplicações Windows

A classe Microsoft.UI.Win32Interop implementa os métodos de interoperabilidade C# na tabela abaixo. Para obter um exemplo de código, consulte Gerenciar janelas de aplicativos.

Disponível via Target Framework Moniker

Exemplo de código

Este exemplo de código demonstra como usar duas das classes de interoperabilidade C# numa aplicação WinUI (ver Crie o seu primeiro WinUI project). O exemplo de cenário é exibir um Windows.Storage.Pickers.FolderPicker. Mas antes de exibir o seletor em um aplicativo de desktop, é necessário inicializá-lo com o identificador (HWND) da janela-mãe.

1. Pode obter um handle de janela (HWND) utilizando a interface de interoperabilidade WinRT COM IWindowNative. E (olhando na tabela da secção anterior) essa interface é representada pela classe de interoperabilidade WinRT.Interop.WindowNative C#. Aqui, o this objeto é uma referência a um objeto Microsoft.UI.Xaml.Window do ficheiro principal window-code-behind.
2. Para inicializar um componente da interface de utilizador com uma janela proprietária, utiliza-se a interface de interoperabilidade COM WinRT IInitializeWithWindow. E essa interface é representada pela classe de interop WinRT.Interop.InitializeWithWindow C#.

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 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();
}

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

Background

Versões anteriores do .NET Framework e do .NET Core tinham conhecimento incorporado do WinRT. Com essas versões anteriores, podias definir uma interface de interoperabilidade diretamente em C# com o atributo ComImport , e depois lançar diretamente uma classe projetada para essa interface de interoperabilidade.

Como o WinRT é uma tecnologia específica para Windows, para suportar os objetivos de portabilidade e eficiência do .NET, retirámos o suporte de projeção WinRT do compilador C# e do tempo de execução .NET, e transferimo-lo para o toolkit C#/WinRT (ver O suporte incorporado para WinRT foi removido do .NET).

Embora a técnica ComImport ainda funcione para interfaces de interoperabilidade baseadas em IUnknown, já não funciona para as interfaces baseadas em IInspectable que são usadas para interoperar com o WinRT.

Assim, como substituição, no .NET, pode utilizar as classes de interoperabilidade em C# descritas neste tópico.

Resolução de problemas e problemas conhecidos

Atualmente, não há problemas conhecidos para as classes de interoperabilidade C#. Para dar feedback ou reportar outros problemas, adicione o seu feedback a um problema existente ou arquive um novo problema no WindowsAppSDK GitHub repositório.

Tópicos relacionados

• Escolha a sua abordagem de interoperabilidade
• Chamar APIs Win32 a partir de C# (CsWin32)
• Crie o seu primeiro projecto WinUI
• Gerenciar janelas de aplicativos
• Recuperar um identificador de janela (HWND)
• Exibir objetos da interface do usuário do WinRT que dependem do CoreWindow
• Gerador de código-fonte C#/Win32 P/Invoke (CsWin32)
• Ferramenta de projeção C#/WinRT (CsWinRT)
• Interoperabilidade do .NET com código nativo