Wywoływanie interfejsów API środowisko wykonawcze systemu Windows w aplikacjach desktopowych

W tym artykule opisano sposób konfigurowania projektów aplikacji klasycznych w celu wywoływania interfejsów API środowisko wykonawcze systemu Windows (WinRT) — interfejsów API obsługujących nowoczesne funkcje Windows, takie jak powiadomienia, selektory plików, udostępnianie i nie tylko.

Note

Niektóre interfejsy API WinRT nie są obsługiwane w aplikacjach na pulpit. Aby uzyskać więcej informacji, zobacz Obsługa interfejsów API WinRT w aplikacjach desktopowych.

Konfigurowanie projektu .NET

.NET 6 i nowsze: użyj opcji Target Framework Moniker

Określ wersję systemu operacyjnego Windows dla Target Framework Moniker (TFM) w pliku projektu. Spowoduje to dodanie odwołania do odpowiedniego pakietu docelowego zestawu SDK Windows w czasie kompilacji.

1. W Visual Studio wybierz opcję Project > [ProjectName] Właściwości.

2. Na stronie właściwości znajdź pozycję Ogólne aplikacji>, wybierając ją w obszarze nawigacji po lewej stronie lub przewijając do niej.

3. Wybierz ustawienia dla:

   1. Target framework — jest to początkowo ustawiona wersja .NET wybrana podczas tworzenia projektu, ale możesz ją zmienić tutaj.
   2. Target OS — pozostaw to ustawienie ustawione na Windows.
   3. Docelowa wersja systemu operacyjnego — wybierz wersję zestawu interfejsu API, którego chcesz użyć, zazwyczaj najnowszą.
   4. Obsługiwana wersja systemu operacyjnego (opcjonalnie) — zobacz następną sekcję, aby uzyskać więcej informacji.

W Target Framework Moniker, te wartości przedstawiają się następująco:

• Struktura docelowa - net10.0
• Docelowy system operacyjny - -windows
• Docelowa wersja systemu operacyjnego - 10.0.22621.0

<TargetFramework>net10.0-windows10.0.22621.0</TargetFramework>
<!-- If set... -->
<SupportedOSPlatformVersion>10.0.19041.0</SupportedOSPlatformVersion>

Możesz również ustawić wartości, ręcznie edytując plik projektu.

1. W Visual Studio kliknij prawym przyciskiem myszy project w Eksplorator rozwiązań a następnie wybierz pozycję Edytuj plik Project.

2. Zastąp wartość TargetFramework wartością TFM specyficzną dla wersji systemu Windows.

   Target	moniker platformy docelowej
   Windows 11, wersja 24H2	net10.0-windows10.0.26100.0
   Windows 11, wersja 22H2	net10.0-windows10.0.22621.0
   Windows 11 (wersja początkowa)	net10.0-windows10.0.22000.0
   Windows 10, wersja 2004	net10.0-windows10.0.19041.0
   Windows 10, wersja 1903	net10.0-windows10.0.18362.0
   Windows 10, wersja 1809	net10.0-windows10.0.17763.0

   Note

   Wyświetlane wartości dotyczą .NET 10. Zaktualizuj w razie potrzeby inne wersje .NET: net8.0, net9.0.

   Example:

   <Project Sdk="Microsoft.NET.Sdk">
     <PropertyGroup>
       <OutputType>WinExe</OutputType>
       <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
     </PropertyGroup>
   </Project>
   

3. Zapisz i zamknij plik projektu.

Wskazówka

Wersja określona przez program TFM wskazuje, które interfejsy API są dostępne dla aplikacji. Nie kontroluje wersji systemu operacyjnego obsługiwanej przez aplikację w czasie wykonywania. Służy do wybierania zestawów referencyjnych kompilowanych przez projekt i wybierania zasobów z pakietów NuGet. Należy traktować tę wersję jako "wersję platformy" lub "wersję interfejsu API systemu operacyjnego", aby odróżnić ją od wersji systemu operacyjnego uruchomieniowego. Aby uzyskać więcej informacji, zobacz Platformy docelowe: wersja systemu operacyjnego w programie TFMs.

Obsługa minimalnej wersji Windows

Aby umożliwić uruchamianie aplikacji w wersji Windows starszej niż docelowa serwera TFM, ustaw SupportedOSVersion (SupportedOSPlatformVersion), jak pokazano w poprzedniej sekcji. Aby uzyskać więcej informacji, zobacz Platformy docelowe: obsługa starszych wersji systemu operacyjnego.

W przypadku określania zakresu wersji systemu operacyjnego należy chronić wywołania interfejsów API, które nie są dostępne we wszystkich wersjach przy użyciu kontroli ApiInformation . Aby uzyskać więcej informacji, zobacz aplikacje dostosowujące się do wersji.

Po ustawieniu SupportedOSVersion Visual Studio wyświetli ostrzeżenie dotyczące interfejsów API, które wymagają sprawdzenia środowiska uruchomieniowego. Jeśli na przykład wersja docelowa to 19041, a minimalna wersja to 17763, podczas wywoływania elementu AppInfo.Current zostanie wyświetlone ostrzeżenie podobne do tego.

CA1416	Using platform dependent API on a component makes the code no longer work across all platforms.

This call site is reachable on: 'Windows' 10.0.17763.0 and later. 'AppInfo.Current' is only supported on: 'Windows' 10.0.19041.0 and later.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
    <SupportedOSPlatformVersion>10.0.17763.0</SupportedOSPlatformVersion>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
  </PropertyGroup>
</Project>

Note

Można również ręcznie dodać TargetPlatformMinVersion ale nie zapewnia to ostrzeżeń czasu kompilacji w Visual Studio.

API WinRT nie są wspierane w .NET 6 i nowszych

W .NET 6 i nowszych kilka interfejsów API WinRT w przestrzeni nazw Windows.UI nie jest obsługiwanych. Użyj równoważnych interfejsów API w przestrzeni nazw Microsoft.UI (dostarczanej przez Zestaw SDK do aplikacji systemu Windows).

Unsupported	Użyj zamiast tego
Windows.UI.Colors	Microsoft.UI.Colors
Windows.UI.ColorHelper	Microsoft.UI.ColorHelper
Windows.UI.Text (większość typów)	Microsoft.UI.Text
Windows.UI.Xaml (wszystkie typy)	Microsoft.UI.Xaml

.NET Core 3.x lub .NET Framework: instalowanie pakietu NuGet

Note

.NET Core 3.x osiągnął koniec wsparcia w grudniu 2022 r. W przypadku nowych projektów należy użyć .NET 6 lub nowszej z podejściem TFM opisanym powyżej. Poniższe podejście do pakietu NuGet dotyczy projektów platformy .NET Framework 4.x i istniejących aplikacji .NET Core 3.x, które nie zostały jeszcze zaktualizowane.

Jeśli aplikacja jest przeznaczona dla platformy .NET Core 3.x lub .NET Framework, zainstaluj pakiet Microsoft.Windows.SDK.Contracts NuGet:

1. W Visual Studio kliknij prawym przyciskiem myszy projekt i wybierz pozycję Zarządzaj pakietami NuGet.

2. Wyszukaj Microsoft.Windows.SDK.Contracts.

3. Wybierz wersję pakietu zgodną z minimalną wersją systemu Windows:

   Wersja pakietu	platforma docelowa Windows
   10.0.19041.xxxx	Windows 10, wersja 2004
   10.0.18362.xxxx	Windows 10, wersja 1903
   10.0.17763.xxxx	Windows 10, wersja 1809
   10.0.17134.xxxx	Windows 10, wersja 1803

4. Kliknij przycisk Zainstaluj.

Wieloplatformowość w przypadku .NET 6+ i wcześniejszych wersji .NET

Skonfiguruj plik projektu, aby używać podejścia TFM dla .NET 6+ i pakietu NuGet dla wcześniejszych wersji:

<Project Sdk="Microsoft.NET.Sdk.WindowsDesktop">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFrameworks>netcoreapp3.1;net8.0-windows10.0.19041.0</TargetFrameworks>
    <UseWPF>true</UseWPF>
  </PropertyGroup>
  <ItemGroup>
    <!-- netcoreapp3.1 is EOL; include only when maintaining an existing app -->
    <PackageReference Condition="'$(TargetFramework)' == 'netcoreapp3.1'"
                     Include="Microsoft.Windows.SDK.Contracts"
                     Version="10.0.19041.0"/>
  </ItemGroup>
</Project>

Kompilacja warunkowa

W przypadku wielowersyjności w wersjach .NET 6+ i wcześniejszych wersjach, użyj kompilacji warunkowej, aby napisać kod specyficzny dla wersji w jednym projekcie. Aby uzyskać więcej informacji, zobacz Platformy docelowe: symbole preprocesora.

#if NET6_0_OR_GREATER
    // Code that uses .NET 6+ APIs or TFM-available WinRT APIs
#else
    // Fallback code for .NET Core 3.x / .NET Framework
#endif

Konfigurowanie projektu C++ (Win32)

Użyj C++/WinRT do korzystania z interfejsów API WinRT w desktopowych aplikacjach C++.

• Zainstaluj Microsoft.Windows. CppWinRT pakiet NuGet.
• Ponieważ język C++/WinRT używa funkcji ze standardu C++17, upewnij się, że właściwość projektu C/C++ > Language > C++ Language Standard jest ustawiona na ISO C++17 Standard (/std:c++17) lub nowszym w Visual Studio.

Aby uzyskać więcej informacji, zobacz Visual Studio obsługę języka C++/WinRT.

Następne kroki

Teraz możesz wywoływać interfejsy API środowisko wykonawcze systemu Windows (WinRT) z zestawu SDK Windows.

Aby również wywołać interfejsy API WinRT z Zestaw SDK do aplikacji systemu Windows, zobacz następujący artykuł:

Użyj Zestaw SDK do aplikacji systemu Windows w istniejącym projekcie

Niektóre interfejsy API WinRT wymagają tożsamości pakietu. Aby uzyskać więcej informacji, zobacz:

• Omówienie pakietowania
• Funkcje, które wymagają tożsamości pakietu
• Pakietuj swoją aplikację przy użyciu pojedynczego projektu MSIX
• Przyznaj tożsamość dla aplikacji niepakowanej

Treści powiązane

• Obsługiwane przez Zestaw SDK do aplikacji systemu Windows wersje Windows
• Obsługa interfejsów API WinRT w aplikacjach desktopowych
• Modernizuj aplikacje klasyczne