Invocar APIs de interoperabilidade de uma aplicação .NET

Como desenvolvedor de aplicativos de desktop C#, no .NET você pode usar classes de interoperabilidade C# que representam várias funções de interoperabilidade e interfaces de interoperabilidade COM do Tempo de Execução do Windows (WinRT). Estas incluem classes C# que representam IWindowNative, IInitializeWithWindow, a função GetWindowIdFromWindow , entre muitas outras.

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

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

As classes de interoperabilidade C# listadas na próxima seção (Classes de Interoperabilidade C# Disponíveis) estão disponíveis no .NET, quer como parte do SDK do Aplicativo Windows, ou então usando um Moniker específico do Target Framework, como veremos.

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

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

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

Para outros tipos de projeto de área de trabalho .NET, como Windows Presentation Foundation (WPF) ou Windows Forms (WinForms), você precisará configurar seu projeto antes de poder acessar as classes de interoperabilidade C#. Para o primeiro conjunto de classes listado abaixo, você precisará fazer referência ao SDK do Aplicativo Windows. Para o segundo conjunto, você precisará configurar um Target Framework Moniker destinado ao Windows 10, versão 1809 ou posterior, da seguinte forma:

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

2. No .csproj ficheiro, modifique o elemento TargetFramework para direcionar uma versão específica do .NET e do SDK do Windows. Por exemplo, o elemento a seguir é apropriado para um projeto .NET 6 destinado ao 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 do Aplicativo 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# em um aplicativo WinUI 3 (consulte Criar seu primeiro projeto WinUI 3). O exemplo de cenário é mostrar 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 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();
}

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

Background

As versões anteriores do .NET Framework e do .NET Core tinham conhecimento interno 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 a projeção do WinRT do compilador C# e do runtime .NET, e transferimo-lo para o toolkit C#/WinRT (ver 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.

Portanto, como substituto, no .NET, você pode usar as classes de interoperabilidade 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 fornecer comentários ou relatar outros problemas, adicione seus comentários a um problema existente ou registre um novo problema no repositório GitHub do WindowsAppSDK.

Tópicos relacionados

• Crie seu primeiro projeto WinUI 3
• Gerenciar janelas de aplicativos
• Recuperar um identificador de janela (HWND)
• Exibir objetos da interface do usuário do WinRT que dependem do CoreWindow