Chamar APIs de interoperabilidade a partir de um aplicativo .NET

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

Este tópico lista as classes de interoperabilidade do C# disponíveis e mostra como usá-las. A seção Background 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 do WinUI 3 C#

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 do C# imediatamente.

Em outros tipos de projetos de desktop em C# (WPF ou WinForms)

Para outros tipos de projeto da área de trabalho do .NET, como do Windows Presentation Foundation (WPF) ou do Windows Forms (WinForms), você precisará configurar seu projeto antes de acessar as classes de interoperabilidade do 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 Target Framework Moniker que atenda ao Windows 10, versão 1809 ou posterior, desta forma:

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

2. .csproj No arquivo, 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 do .NET 6 direcionado 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 compatíveis, confira Usar a opção do Moniker da Estrutura de Destino.

Classes de interoperabilidade em C# disponíveis

Aqui estão as classes de interoperabilidade do C# disponíveis, mapeadas de sua função de interoperabilidade subjacente ou 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 requer um parâmetro HWND ( identificador de janela IntPtr ) e retorna 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 do 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 do aplicativo.

Disponível por meio do Moniker do Target Framework

Exemplo de código

Este exemplo de código demonstra como usar duas das classes de interoperabilidade do C# em um aplicativo WinUI 3 (consulte Criar seu primeiro projeto 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) utilizando a interface de interoperabilidade COM WinRT IWindowNative. E (olhando na tabela na seçã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 arquivo code-behind da janela principal.
2. Para inicializar um elemento da interface do usuário com uma janela proprietária, use a interface de interoperabilidade IInitializeWithWindow WinRT COM. E essa interface é representada pela classe de interoperabilidade 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();
}

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

Background

As versões anteriores do .NET Framework e do .NET Core tinham conhecimento interno do WinRT. Com essas versões anteriores, você poderia definir uma interface de interoperabilidade diretamente em C# com o atributo ComImport e, em seguida, converter diretamente uma classe projetada nessa interface de interoperabilidade.

Como o WinRT é uma tecnologia específica do Windows, para dar suporte às metas de portabilidade e eficiência do .NET, retiramos 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 (consulte o suporte interno para WinRT removido do .NET).

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

Portanto, como uma substituição, no .NET, você pode usar as classes de interoperabilidade C# descritas neste tópico.

Solução de problemas e problemas conhecidos

Atualmente, não há problemas conhecidos para as classes de interoperabilidade do 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

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