Wywoływanie międzyoperacyjnych interfejsów API z poziomu aplikacji .NET

Jako deweloper aplikacji desktopowych w języku C# na platformie .NET, można używać klas międzyoperacyjnych C#, które reprezentują różne funkcje interoperacyjności oraz interfejsy interoperacyjności środowiska Windows Runtime (WinRT) COM. Należą do nich klasy języka C# reprezentujące funkcję IWindowNative, IInitializeWithWindow, getWindowIdFromWindow i wiele innych.

W tym temacie wymieniono dostępne klasy międzyoperacyjności języka C# i pokazano, jak z nich korzystać. W sekcji Tło na końcu tematu opisano, jak interfejsy międzyoperacyjne były używane w poprzednich wersjach platformy .NET i dlaczego wprowadzono zmiany.

Skonfiguruj projekt platformy .NET do używania klas międzyoperacyjnych C#

Klasy międzyoperacyjności języka C# wymienione w następnej sekcji (Dostępne klasy międzyoperacyjności języka C#) są dostępne na platformie .NET w ramach zestawu SDK aplikacji systemu Windowslub przy użyciu określonego monikera platformy docelowej, jak zobaczymy.

W projekcie pulpitowym WinUI 3 w języku C#

Podczas tworzenia nowego projektu WinUI 3 w programie Visual Studio (zobacz Tworzenie pierwszego projektu WinUI 3), projekt jest już skonfigurowany i możesz rozpocząć korzystanie z wszystkich klas międzyoperacyjności języka C#.

W innych typach projektów pulpitowych C# (WPF lub WinForms)

W przypadku innych typów projektów klasycznych platformy .NET, takich jak Windows Presentation Foundation (WPF) lub Windows Forms (WinForms)— należy skonfigurować projekt przed uzyskaniem dostępu do klas międzyoperacyjności języka C#. W przypadku pierwszego zestawu klas wymienionych poniżej należy odwołać się do Windows App SDK . W drugim zestawie należy skonfigurować Target Framework Moniker, który jest przeznaczony dla systemu Windows 10 w wersji 1809 lub nowszej, w następujący sposób:

1. Otwórz plik projektu dla aplikacji desktopowej w C# na platformie .NET.

2. W pliku .csproj zmodyfikuj element TargetFramework, aby docelowo odnosił się do określonej wersji .NET i Windows SDK. Na przykład poniższy element jest odpowiedni dla projektu platformy .NET 6 przeznaczonego dla systemu Windows 10 w wersji 2004.

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

Aby uzyskać więcej informacji — w tym listę innych obsługiwanych wartości — zobacz Użyj opcji Moniker platformy docelowej.

Dostępne klasy międzyoperacyjności języka C#

Poniżej przedstawiono dostępne klasy międzyoperacyjności języka C#, mapowane z ich podstawowej funkcji międzyoperacyjnej lub interfejsu międzyoperacyjności WinRT COM. Każda wymieniona klasa implementuje funkcje/metody swojego podstawowego interfejsu API międzyoperacyjności oraz zapewnia typowo bezpieczne otoki dla parametrów i zwracanych wartości. Na przykład Windows.ApplicationModel.DataTransfer.DragDrop.Core.DragDropManagerInterop.GetForWindow wymaga parametru uchwytu okna IntPtr (HWND) i zwraca obiekt CoreDragDropManager . Wszystkie poniższe klasy międzyoperacyjności języka C# i skojarzone metody są statyczne.

Dostępny jako część zestawu SDK aplikacji systemu Windows

Klasa Microsoft.UI.Win32Interop implementuje metody międzyoperacyjności języka C# w poniższej tabeli. Aby zapoznać się z przykładem kodu, zobacz Zarządzanie oknami aplikacji.

Dostępne za pośrednictwem identyfikatora platformy docelowej

Przykład kodu

W tym przykładzie kodu pokazano, jak używać dwóch klas międzyoperacyjności języka C# w aplikacji WinUI 3 (zobacz Tworzenie pierwszego projektu WinUI 3). Przykładowym scenariuszem jest wyświetlenie elementu Windows.Storage.Pickers.FolderPicker. Jednak przed wyświetleniem selektora w aplikacji komputerowej należy zainicjować go przy użyciu uchwytu (HWND) okna właściciela.

1. Uchwyt okna (HWND) można uzyskać przy użyciu interfejsu międzyoperacyjnego IWindowNative WinRT COM. A (zaglądając w tabelę w poprzedniej sekcji) ten interfejs jest reprezentowany przez klasę C# WinRT.Interop.WindowNative. this W tym miejscu obiekt jest odwołaniem do obiektu Microsoft.UI.Xaml.Window z głównego pliku kodu za pomocą okna.
2. Aby zainicjować fragment interfejsu użytkownika za pomocą okna właściciela, należy użyć interfejsu międzyoperacyjności IInitializeWithWindow WinRT COM. Ten interfejs jest reprezentowany przez klasę międzyoperacyjną 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();
}

Zobacz również Pobieranie uchwytu okna (HWND) i Wyświetlanie obiektów interfejsu użytkownika WinRT, które są zależne od CoreWindow.

Background

Poprzednie wersje programów .NET Framework i .NET Core zawierały wbudowaną wiedzę na temat środowiska WinRT. W poprzednich wersjach można zdefiniować interfejs międzyoperacyjności bezpośrednio w języku C# za pomocą atrybutu ComImport , a następnie bezpośrednio rzutować projektowaną klasę na ten interfejs międzyoperacyjności.

Ponieważ WinRT jest technologią specyficzną dla systemu Windows, aby zapewnić obsługę przenośności i wydajności platformy .NET, z kompilatora języka C# i środowiska uruchomieniowego platformy .NET usunięto obsługę projekcji WinRT i przenieśliśmy ją do zestawu narzędzi C#/WinRT (zobacz Wbudowana obsługa winRT została usunięta z platformy .NET).

Chociaż technika ComImport nadal działa w przypadku interfejsów międzyoperacyjności opartych na protokole IUnknown, nie działa już w przypadku interfejsów opartych na protokole IInspectable, które są używane do współdziałania z WinRT.

Zamiast tego, w .NET można użyć klas międzyoperacyjności C# opisanych w tym temacie.

Rozwiązywanie problemów i znane problemy

Obecnie nie ma znanych problemów z klasami międzyoperacyjnymi C#. Aby przekazać opinię lub zgłosić inne problemy, dodaj swoją opinię do istniejącego problemu lub zgłoś nowy problem w repozytorium GitHub WindowsAppSDK.

Tematy pokrewne

• Tworzenie pierwszego projektu WinUI 3
• Zarządzanie oknami aplikacji
• Pobierz uchwyt okna (HWND)
• Wyświetlanie obiektów WinRT interfejsu użytkownika zależnych od CoreWindow