Appeler des API Windows Runtime dans les applications de bureau

Cet article explique comment configurer vos projets d’application de bureau pour appeler des API Windows Runtime (WinRT), les API qui alimentent les fonctionnalités modernes Windows telles que les notifications, les sélecteurs de fichiers, le partage, etc.

Certaines API WinRT ne sont pas prises en charge dans les applications de bureau. Pour plus d’informations, consultez APIs Windows Runtime non prises en charge dans les applications de bureau.

Configurer un projet .NET

.NET 6 et versions ultérieures : utiliser l’option Moniker du Framework cible

Spécifiez un Moniker de Framework Cible (TFM) spécifique à la version du système d’exploitation Windows dans votre fichier projet. Cela ajoute une référence au package de ciblage Windows SDK approprié au moment de la compilation.

1. Dans Visual Studio, cliquez avec le bouton droit sur votre project dans Explorateur de solutions et choisissez Edit Project Fichier.

2. Remplacez la valeur TargetFramework par une valeur TFM spécifique à Windows :

   Cible	TFM
   Windows 11, version 24H2	net8.0-windows10.0.26100.0
   Windows 11, version 22H2	net8.0-windows10.0.22621.0
   Windows 11 (version initiale)	net8.0-windows10.0.22000.0
   Windows 10, version 2004	net8.0-windows10.0.19041.0
   Windows 10, version 1903	net8.0-windows10.0.18362.0
   Windows 10, version 1809	net8.0-windows10.0.17763.0

   Exemple :

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

3. Enregistrez et fermez le fichier projet.

Prise en charge d’une version minimale de Windows

Pour permettre à votre application de s’exécuter sur une version Windows antérieure à votre cible TFM, définissez TargetPlatformMinVersion explicitement :

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

Lorsque vous ciblez une plage de versions du système d’exploitation, protégez les appels aux API qui ne sont pas disponibles sur toutes les versions à l’aide de vérifications ApiInformation . Pour plus d’informations, consultez Applications s’adaptant aux versions.

API WinRT non prises en charge dans .NET 6 et versions ultérieures

Dans .NET 6 et versions ultérieures, plusieurs API WinRT dans le Windows.UI espace de noms ne sont pas prises en charge. Utilisez les API équivalentes dans le Microsoft. Interface utilisateur espace de noms (fourni par le SDK d'application Windows) à la place :

.NET Core 3.x ou .NET Framework : installer le package NuGet

Si votre application cible .NET Core 3.x ou .NET Framework, installez le package NuGet Microsoft.Windows.SDK.Contracts :

1. Dans Visual Studio, cliquez avec le bouton droit sur votre projet et choisissez Manage des packages NuGet.

2. Recherchez Microsoft.Windows.SDK.Contracts.

3. Sélectionnez la version du package correspondant à votre cible minimale Windows :

   Version du package	cible Windows
   10.0.19041.xxxx	Windows 10, version 2004
   10.0.18362.xxxx	Windows 10, version 1903
   10.0.17763.xxxx	Windows 10, version 1809
   10.0.17134.xxxx	Windows 10, version 1803

4. Cliquez sur Installer.

Ciblage multiple .NET 6+ et .NET versions antérieures

Configurez le fichier projet pour utiliser l’approche TFM pour .NET 6+ et le package NuGet pour les versions antérieures :

<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>
    <PackageReference Condition="'$(TargetFramework)' == 'netcoreapp3.1'"
                     Include="Microsoft.Windows.SDK.Contracts"
                     Version="10.0.19041.0" />
  </ItemGroup>
</Project>

Configurer un projet C++ (Win32)

Utilisez C++/WinRT pour consommer des API WinRT à partir d’applications de bureau C++.

• Nouveaux projets : installez l'C++/WinRT Visual Studio Extension (VSIX) et utilisez l’un des modèles de projet inclus.
• Projets existants : installez le package NuGet Microsoft.Windows.CppWinRT.

Pour plus d’informations, consultez la prise en charge de Visual Studio pour C++/WinRT.

Exemple : Envoyer une notification toast

Une fois votre projet configuré, vous pouvez appeler directement des API WinRT. L’exemple suivant envoie une notification toast à partir d’une application WPF ou Win32.

using System.Security;
using Windows.Data.Xml.Dom;
using Windows.UI.Notifications;

void ShowToast(string title, string content, string image, string logo)
{
    string xmlString =
        $@"<toast><visual><binding template='ToastGeneric'>" +
        $"<text>{SecurityElement.Escape(title)}</text><text>{SecurityElement.Escape(content)}</text>" +
        $"<image src='{SecurityElement.Escape(image)}'/>" +
        $"<image src='{SecurityElement.Escape(logo)}' placement='appLogoOverride' hint-crop='circle'/>" +
        "</binding></visual></toast>";

    XmlDocument toastXml = new XmlDocument();
    toastXml.LoadXml(xmlString);
    ToastNotificationManager.CreateToastNotifier().Show(new ToastNotification(toastXml));
}

#include <sstream>
#include <string>
#include <string_view>
#include <winrt/Windows.Data.Xml.Dom.h>
#include <winrt/Windows.UI.Notifications.h>

using namespace winrt::Windows::UI::Notifications;
using namespace winrt::Windows::Data::Xml::Dom;

std::wstring XmlEscape(std::wstring_view input)
{
    std::wstring result;
    result.reserve(input.size());
    for (wchar_t ch : input) {
        switch (ch) {
            case L'&':  result += L"&amp;";  break;
            case L'<':  result += L"&lt;";   break;
            case L'>':  result += L"&gt;";   break;
            case L'\'': result += L"&apos;"; break;
            case L'"':  result += L"&quot;"; break;
            default:    result += ch;        break;
        }
    }
    return result;
}

void ShowToast(std::wstring title, std::wstring content, std::wstring image, std::wstring logo)
{
    std::wostringstream xml;
    xml << L"<toast><visual><binding template='ToastGeneric'>"
        << L"<text>" << XmlEscape(title) << L"</text><text>" << XmlEscape(content) << L"</text>"
        << L"<image src='" << XmlEscape(image) << L"'/>"
        << L"<image src='" << XmlEscape(logo) << L"' placement='appLogoOverride' hint-crop='circle'/>"
        << L"</binding></visual></toast>";

    XmlDocument toastXml;
    toastXml.LoadXml(xml.str().c_str());
    ToastNotificationManager::CreateToastNotifier().Show(ToastNotification(toastXml));
}

Pour plus de scénarios de notification, consultez les notifications toast adaptatives et interactives.

Compilation conditionnelle

Lorsque vous ciblez plusieurs versions entre .NET 6 et les versions antérieures, utilisez la compilation conditionnelle pour écrire du code spécifique à la version dans un seul projet :

#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

Contenu connexe

• Windows Runtime APIs pas prises en charge dans les applications de bureau
• Integrate votre application avec Windows à l’aide d’extensions d’empaquetage
• Moderniser vos applications de bureau