Anropa Windows Runtime API:er i skrivbordsappar

Den här artikeln beskriver hur du konfigurerar dina skrivbordsappprojekt för att anropa API:er för Windows Runtime (WinRT) – DE API:er som driver moderna Windows funktioner som meddelanden, filväljare, delning med mera.

Vissa WinRT-API:er stöds inte i skrivbordsappar. Mer information finns i Windows Runtime API:er som inte stöds i skrivbordsappar.

Konfigurera ett .NET projekt

.NET 6 och senare: Använd monikeralternativet Target Framework

Ange ett Windows OS-specifik Target Framework Moniker (TFM) i din projektfil. Detta lägger till en referens till lämpligt Windows SDK-målpaket vid bygget.

1. I Visual Studio högerklickar du på din project i Prieskumník riešení och väljer Redigera Project Fil.

2. Ersätt värdet TargetFramework med en Windows specifik TFM:

   Mål	TFM
   Windows 11 version 24H2	net8.0-windows10.0.26100.0
   Windows 11 version 22H2	net8.0-windows10.0.22621.0
   Windows 11 (första versionen)	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

   Exempel:

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

3. Spara och stäng projektfilen.

Stöd för en lägsta Windows version

Om du vill tillåta att appen körs på en Windows version som är äldre än TFM-målet anger du TargetPlatformMinVersion explicit:

<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>

När du riktar in dig på ett antal OS-versioner, skydda anrop till API:er som inte är tillgängliga för alla versioner med hjälp av ApiInformation-kontroller. Mer information finns i Version av anpassningsbara appar.

WinRT-API:er stöds inte i .NET 6 och senare

I .NET 6 och senare stöds flera WinRT-API:er i Windows.UI-namnutrymmet inte. Använd motsvarande API:er i Microsoft. UI namnområde (tillhandahålls av Windows App SDK) i stället:

.NET Core 3.x eller .NET Framework: Installera NuGet-paketet

Om din app är avsedd för .NET Core 3.x eller .NET Framework installerar du nuget-paketet Microsoft.Windows.SDK.Contracts:

1. I Visual Studio högerklickar du på projektet och väljer Hantera NuGet-paket.

2. Sök efter Microsoft.Windows.SDK.Contracts.

3. Välj den paketversion som matchar ditt lägsta Windows mål:

   Paketversion	Windows-mål
   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. Klicka på Installera.

Målrikta flera plattformar: .NET 6+ och tidigare .NET-versioner

Konfigurera projektfilen så att den använder TFM-metoden för .NET 6+ och NuGet-paketet för tidigare versioner:

<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>

Konfigurera ett C++-projekt (Win32)

Använd C++/WinRT för att använda WinRT-API:er från C++-skrivbordsappar.

• Nya projekt: Installera C++/WinRT Visual Studio Extension (VSIX) och använd en av de inkluderade projektmallarna.
• Existerande projekt: Installera Microsoft.Windows.CppWinRT NuGet-paket.

Mer information finns i Visual Studio support för C++/WinRT.

Exempel: Skicka ett toast-meddelande

När projektet har konfigurerats kan du anropa WinRT-API:er direkt. I följande exempel skickas ett toast-meddelande från en WPF- eller Win32-app.

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));
}

Fler meddelandescenarier finns i Anpassningsbara och interaktiva toast-meddelanden.

Villkorsstyrd kompilering

När multi-targeting i .NET 6+ och tidigare versioner använder du villkorlig kompilering för att skriva versionsspecifik kod i ett enda projekt:

#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

Relaterat innehåll

• Windows Runtime API:er stöds inte i skrivbordsappar
• Integrera din app med Windows med hjälp av paketeringstillägg
• Modernisera dina skrivbordsappar