Volání rozhraní API prostředí Windows Runtime v desktopových aplikacích

Toto téma popisuje, jak nastavit projekty desktopových aplikací tak, aby používaly rozhraní API prostředí Windows Runtime (WinRT), která poskytuje operační systém Windows, a jak do desktopových aplikací přidat moderní prostředí Windows 11 a Windows 10.

Některá rozhraní API prostředí Windows Runtime (WinRT) se v desktopových aplikacích nepodporují. Další informace najdete v tématu rozhraní API prostředí Windows Runtime, která nejsou podporována v desktopových aplikacích.

Úprava projektu .NET tak, aby používala rozhraní API prostředí Windows Runtime

Pro projekty .NET existuje několik možností:

• Počínaje rozhraním .NET 6 můžete v souboru projektu zadat moniker cílové architektury (TFM) pro přístup k rozhraním API WinRT. Tato možnost je podporovaná v projektech, které cílí na Windows 10 verze 1809 nebo novější.
• Pro starší verze rozhraní .NET můžete nainstalovat balíček Microsoft.Windows.SDK.Contracts NuGet a přidat do projektu všechny potřebné odkazy. Tato možnost je podporovaná v projektech, které cílí na Windows 10 verze 1803 nebo novější.
• Pokud má váš projekt více cílů .NET 6 (nebo novější) a starší verze .NET, můžete soubor projektu nakonfigurovat tak, aby používal obě možnosti.

.NET 6 a novější: Použijte možnost Moniker cílového frameworku

Tato možnost se podporuje jenom v projektech, které používají .NET 6 (nebo novější) a cílí na Windows 10 verze 1809 nebo novější verzi operačního systému. Zadáním TFM specifické verze operačního systému Windows v souboru projektu se přidá odkaz do příslušného balíček cílící na sadu Windows SDK. Více informací o tomto scénáři najdete v blogovém příspěvku Volání rozhraní API Windows v .NET.

1. Po otevření projektu v sadě Visual Studio klikněte pravým tlačítkem na projekt v průzkumníku řešení a zvolte Upravit soubor projektu. Soubor projektu bude vypadat nějak takto.

   Poznámka:

   Následující příklad ukazuje OutputTypeWinExe, který určuje spustitelný soubor grafického uživatelského rozhraní windows (a zabraňuje otevření okna konzoly při spuštění aplikace). Pokud vaše aplikace nemá grafické uživatelské rozhraní, OutputType bude mít jinou hodnotu. Rozhraní API WinRT můžete volat z aplikací grafického uživatelského rozhraní pro Windows, konzolových aplikací a knihoven. Vaše hodnota TargetFramework nemusí přesně odpovídat následujícímu příkladu.

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

2. Ponechte všechna ostatní nastavení tak, jak jsou, nahraďte hodnotu prvku TargetFramework jedním z následujících řetězců:

   • net8.0-windows10.0.17763.0: Pokud vaše aplikace cílí na Windows 10 verze 1809.
   • net8.0-windows10.0.18362.0: Pokud vaše aplikace cílí na Windows 10 verze 1903.
   • net8.0-windows10.0.19041.0: Pokud vaše aplikace cílí na Windows 10 verze 2004.
   • net8.0-windows10.0.22000.0: Pokud vaše aplikace cílí na počáteční vydání Windows 11.
   • net8.0-windows10.0.22621.0: Pokud vaše aplikace cílí na Windows 11 verze 22H2.
   • net8.0-windows10.0.26100.0: Pokud vaše aplikace cílí na Windows 11 verze 24H2.

   Následující prvek je například pro projekt, který cílí na Windows 10 verze 2004.

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

   V novějších verzích rozhraní .NET můžete hodnotu nahradit příslušnou verzí, například net8.0-windows10.0.19041.0.

3. Uložte změny a zavřete soubor projektu.

Rozhraní API WinRT nejsou podporována v .NET 6 nebo novějších verzích.

V rozhraní .NET 6 a novějších existuje několik rozhraní API prostředí Windows Runtime (WinRT) v oboru názvů Windows.UI, která nejsou podporována. Pro níže uvedená rozhraní API existují ekvivalentní verze rozhraní API v oboru názvů WinUI (Microsoft.UI) (například Microsoft.UI.Text). Následující rozhraní API WinRT nejsou podporována v rozhraní .NET 6 a novějším:

• třída Windows.UI.Colors
• třída Windows.UI.ColorHelper
• Windows.UI.Text (všechny třídy v tomto oboru názvů s výjimkou pro Windows.UI.Text.FontStretch, Windows.UI.Text.FontStyle, Windows.UI.Text.FontWeight, Windows.UI.Text.UnderlineTypea všechny třídy v oboru názvů Windows.UI.Text.Core)
• Windows.UI.Xaml (všechny třídy v tomto oboru názvů)

Podpora více verzí operačního systému Windows

Vlastnost TargetFramework verze operačního systému Windows určuje verzi sady Windows SDK, se kterou je vaše aplikace zkompilována. Tato vlastnost určuje sadu přístupných rozhraní API v době sestavení a poskytuje výchozí hodnoty pro TargetPlatformVersion a TargetPlatformMinVersion (pokud není explicitně nastaven). Vlastnost TargetPlatformVersion nemusí být explicitně definována v souboru projektu, protože je automaticky nastavena verzí operačního systému v TargetFramework.

TargetPlatformMinVersion lze přepsat tak, aby byla menší než TargetPlatformVersion (určená verzí ve vlastnosti TargetFramework). To umožňuje aplikaci spouštět ve starších verzích operačního systému. Například v souboru projektu můžete nastavit následující položky, které podporují vaši aplikaci na nižší úrovni než Windows 10 verze 1809.

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

Všimněte si, že nastavení TargetPlatformMinVersion na verzi pod TargetPlatformVersion vytváří potenciál pro volání nedostupných rozhraní API. Při volání rozhraní API WinRT, která nejsou k dispozici ve všech podporovaných verzích operačního systému, doporučujeme chránit tato volání pomocí kontrol ApiInformation. Další informace viz verze adaptivních aplikací.

Starší verze rozhraní .NET: Instalace balíčku NuGet Microsoft.Windows.SDK.Contracts

Tuto možnost použijte, pokud vaše aplikace používá .NET Core 3.x nebo .NET Framework. Tato možnost je podporovaná v projektech, které cílí na Windows 10 verze 1803 nebo novější.

1. Ujistěte se, že odkazy na balíčky jsou povolené:

   1. V sadě Visual Studio klikněte na Tools –> Správce balíčků NuGet –> Nastavení Správce balíčků.
   2. Ujistěte se, že PackageReference je vybraný pro výchozí formát správy balíčků.

2. Po otevření projektu v sadě Visual Studio klikněte pravým tlačítkem na projekt v průzkumníku řešení a zvolte Spravovat balíčky NuGet.

3. V okně správce balíčků NuGet vyberte kartu Procházet a vyhledejte Microsoft.Windows.SDK.Contracts.

4. Po nalezení balíčku Microsoft.Windows.SDK.Contracts v pravém podokně okna Správce balíčků NuGet vyberte verzi balíčku, který chcete nainstalovat na základě verze Windows 10, na kterou chcete cílit:

   • 10.0.19041.xxxx: Zvolte tuto možnost pro Windows 10 verze 2004.
   • 10.0.18362.xxxx: Zvolte tuto možnost pro Windows 10 verze 1903.
   • 10.0.17763.xxxx: Zvolte tuto možnost pro Windows 10 verze 1809.
   • 10.0.17134.xxxx: Zvolte tuto možnost pro Windows 10 verze 1803.

5. Klikněte na Nainstalovat.

Konfigurace projektů, které cílí na různé verze .NET

Pokud váš projekt cílí na .NET 6 (nebo novější) a současně na starší verze (včetně .NET Core 3.x a .NET Framework), můžete soubor projektu nakonfigurovat tak, aby pomocí identifikátoru cílového rozhraní (TFM) automaticky načítal odkazy rozhraní API WinRT pro .NET 6 (nebo novější) a používal balíček NuGet Microsoft.Windows.SDK.Contracts pro starší verze.

1. Po otevření projektu v sadě Visual Studio klikněte pravým tlačítkem na projekt v průzkumníku řešení a zvolte Upravit soubor projektu. Následující příklad ukazuje soubor projektu pro aplikaci, která používá .NET Core 3.1.

   Poznámka:

   Následující příklad ukazuje OutputTypeWinExe, který určuje spustitelný soubor grafického uživatelského rozhraní windows (a zabraňuje otevření okna konzoly při spuštění aplikace). Pokud vaše aplikace nemá grafické uživatelské rozhraní, OutputType bude mít jinou hodnotu. Rozhraní API WinRT můžete volat z aplikací grafického uživatelského rozhraní pro Windows, konzolových aplikací a knihoven. Vaše hodnota TargetFramework nemusí přesně odpovídat následujícímu příkladu.

   <Project Sdk="Microsoft.NET.Sdk.WindowsDesktop">
     <PropertyGroup>
       <OutputType>WinExe</OutputType>
       <TargetFramework>netcoreapp3.1</TargetFramework>
       <UseWindowsForms>true</UseWindowsForms>
     </PropertyGroup>
   </Project>
   

2. Element TargetFramework v souboru nahraďte elementem TargetFrameworks (všimněte si množného čísla). V tomto prvku zadejte identifikátory cílového rozhraní (TFM) pro všechny verze rozhraní .NET, na které chcete zaměřit, oddělené středníky.

   • Pro .NET 6 nebo novější použijte jeden z následujících monikerů cílového rozhraní (Target Framework Monikers, TFM):
     • net6.0-windows10.0.17763.0: Pokud vaše aplikace cílí na Windows 10 verze 1809.
     • net6.0-windows10.0.18362.0: Pokud vaše aplikace cílí na Windows 10 verze 1903.
     • net6.0-windows10.0.19041.0: Pokud vaše aplikace cílí na Windows 10 verze 2004.
     • net6.0-windows10.0.22000.0: Pokud vaše aplikace cílí na počáteční verzi Windows 11.
     • net6.0-windows10.0.22621.0: Pokud vaše aplikace cílí na Windows 11 verze 22H2.
     • net6.0-windows10.0.26100.0: Pokud vaše aplikace cílí na Windows 11 verze 24H2.
   • Pro .NET Core 3.x použijte netcoreapp3.0 nebo netcoreapp3.1.
   • Pro rozhraní .NET Framework použijte net46.

   Následující příklad ukazuje, jak cílit na více platforem .NET Core 3.1 a .NET 6 (pro Windows 10, verzi 2004).

   <TargetFrameworks>netcoreapp3.1;net6.0-windows10.0.19041.0</TargetFrameworks>
   

3. Za element PropertyGroup přidejte prvek PackageReference, který obsahuje podmíněný příkaz, který nainstaluje balíček NuGet Microsoft.Windows.SDK.Contracts pro všechny verze rozhraní .NET Core 3.x nebo .NET Framework, které cílí na vaši aplikaci. Element PackageReference musí být podřízeným elementem ItemGroup. Následující příklad ukazuje, jak to provést pro .NET Core 3.1.

   <ItemGroup>
     <PackageReference Condition="'$(TargetFramework)' == 'netcoreapp3.1'"
                       Include="Microsoft.Windows.SDK.Contracts"
                       Version="10.0.19041.0" />
   </ItemGroup>
   

   Až budete hotovi, soubor projektu by měl vypadat nějak takto.

   <Project Sdk="Microsoft.NET.Sdk.WindowsDesktop">
     <PropertyGroup>
       <OutputType>WinExe</OutputType>
       <TargetFrameworks>netcoreapp3.1;net6.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>
   

4. Uložte změny a zavřete soubor projektu.

Úprava projektu C++ desktopu (Win32) tak, aby používala rozhraní API prostředí Windows Runtime

K využívání rozhraní API WinRT použijte C++/WinRT. C++/WinRT je zcela standardní moderní projekce jazyka C++17 pro rozhraní API WinRT, implementovaná jako knihovna založená na hlavičkách a navržená tak, aby vám poskytovala prvotřídní přístup k modernímu rozhraní API systému Windows.

Konfigurace projektu pro C++/WinRT:

• Pro nové projekty můžete nainstalovat C++/WinRT Visual Studio Extension (VSIX) a použít některou ze šablon projektů C++/WinRT, které jsou součástí tohoto rozšíření.
• U existujících projektů můžete v projektu nainstalovat balíček NuGet Microsoft.Windows.CppWinRT.

Další podrobnosti o těchto možnostech najdete v tématu podpora sady Visual Studio pro C++/WinRT aVSIX .

Přidejte prostředí Windows 10

Teď jste připraveni přidat moderní prostředí, která se rozsvítí, když uživatelé spustí vaši aplikaci ve Windows 10. Použijte tento tok návrhu.

✅ Nejprve se rozhodněte, jaké zážitky chcete přidat

Můžete si vybrat ze spousty věcí. Tok nákupní objednávky můžete například zjednodušit pomocí rozhraní API pro monetizacinebo zaměřit pozornost na svou aplikaci, když máte něco zajímavého ke sdílení, například nový obrázek zveřejněný jiným uživatelem.

I když uživatelé vaši zprávu ignorují nebo zavřou, uvidí ji znovu v centru akcí a pak kliknutím na zprávu otevřete aplikaci. Tím se zvýší zapojení vaší aplikace a přidá se bonus k tomu, že se vaše aplikace zobrazí hluboko integrovaná s operačním systémem. Kód pro toto prostředí vám ukážeme později v tomto článku.

Další nápady najdete v dokumentaci k UWP.

✅ rozhodnout, jestli chcete vylepšit nebo rozšířit

Často uslyšíte, že používáme termíny, vylepšit a rozšířit, proto si na chvíli vysvětlíme, co jednotlivé termíny značí.

Termín vylepšujeme k popisu rozhraní API WinRT, která můžete volat přímo z desktopové aplikace bez ohledu na to, jestli se jedná o zabalenou aplikaci. Když zvolíte prostředí Windows 10, identifikujte rozhraní API, která potřebujete k jeho vytvoření, a pak se podívejte, jestli se toto rozhraní API zobrazí v tomto seznamu. Toto je seznam rozhraní API, která můžete volat přímo z desktopové aplikace. Pokud se vaše rozhraní API v tomto seznamu nezobrazí, je to proto, že funkce přidružené k tomuto rozhraní API se můžou spouštět jenom v rámci procesu UPW. Často se jedná o rozhraní API, která vykreslují UWP XAML, jako je mapový ovládací prvek UWP nebo bezpečnostní výzva Windows Hello.

Poznámka:

I když rozhraní API, která vykreslují XAML pro UPW, se obvykle nedají volat přímo z plochy, možná budete moct použít alternativní přístupy. Pokud chcete hostovat ovládací prvky XAML UWP nebo jiné vlastní vizuální prostředí, můžete použít ostrůvky XAML (počínaje Windows 10 verze 1903) a vizuální vrstvu (počínaje Windows 10 verze 1803). Tyto funkce je možné použít v zabalených nebo rozbalených desktopových aplikacích.

Pokud jste se rozhodli zabalit desktopovou aplikaci, další možností je rozšířit aplikaci přidáním projektu UWP k vašemu řešení. Desktopový projekt je stále vstupním bodem vaší aplikace, ale projekt UWP poskytuje přístup ke všem rozhraním API, která se nezobrazují v tomto seznamu. Desktopová aplikace může komunikovat s procesem UPW pomocí služby App Service a máme spoustu doprovodných materiálů k nastavení. Pokud chcete přidat prostředí, které vyžaduje projekt UPW, přečtěte si téma Rozšíření s komponentami UPW.

✅ referenční API kontrakty

Pokud můžete rozhraní API volat přímo z desktopové aplikace, otevřete prohlížeč a vyhledejte referenční téma pro toto rozhraní API. Pod souhrnem rozhraní API najdete tabulku, která popisuje kontrakt rozhraní API pro toto rozhraní API. Tady je příklad této tabulky:

Pokud máte desktopovou aplikaci založenou na .NET, přidejte odkaz na kontrakt pro API a potom nastavte vlastnost CopyLocal tohoto souboru na False. Pokud máte projekt založený na jazyce C++, přidejte do Additional Include Directoriescestu ke složce, která obsahuje tento kontrakt.

✅ Zavolejte rozhraní API pro přidání vaší zkušenosti

Tady je kód, který byste použili k zobrazení okna oznámení, na které jsme se podívali dříve. Tato rozhraní API se zobrazí v tomto seznamu , abyste mohli tento kód přidat do desktopové aplikace a spustit ho právě teď.

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

private void ShowToast()
{
    string title = "featured picture of the day";
    string content = "beautiful scenery";
    string image = "https://picsum.photos/360/180?image=104";
    string logo = "https://picsum.photos/64?image=883";

    string xmlString =
    $@"<toast><visual>
       <binding template='ToastGeneric'>
       <text>{title}</text>
       <text>{content}</text>
       <image src='{image}'/>
       <image src='{logo}' placement='appLogoOverride' hint-crop='circle'/>
       </binding>
      </visual></toast>";

    XmlDocument toastXml = new XmlDocument();
    toastXml.LoadXml(xmlString);

    ToastNotification toast = new ToastNotification(toastXml);

    ToastNotificationManager.CreateToastNotifier().Show(toast);
}

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

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

void UWP::ShowToast()
{
    std::wstring const title = L"featured picture of the day";
    std::wstring const content = L"beautiful scenery";
    std::wstring const image = L"https://picsum.photos/360/180?image=104";
    std::wstring const logo = L"https://picsum.photos/64?image=883";

    std::wostringstream xmlString;
    xmlString << L"<toast><visual><binding template='ToastGeneric'>" <<
        L"<text>" << title << L"</text>" <<
        L"<text>" << content << L"</text>" <<
        L"<image src='" << image << L"'/>" <<
        L"<image src='" << logo << L"'" <<
        L" placement='appLogoOverride' hint-crop='circle'/>" <<
        L"</binding></visual></toast>";

    XmlDocument toastXml;

    toastXml.LoadXml(xmlString.str().c_str());

    ToastNotificationManager::CreateToastNotifier().Show(ToastNotification(toastXml));
}

using namespace Windows::Foundation;
using namespace Windows::System;
using namespace Windows::UI::Notifications;
using namespace Windows::Data::Xml::Dom;

void UWP::ShowToast()
{
    Platform::String ^title = "featured picture of the day";
    Platform::String ^content = "beautiful scenery";
    Platform::String ^image = "https://picsum.photos/360/180?image=104";
    Platform::String ^logo = "https://picsum.photos/64?image=883";

    Platform::String ^xmlString =
        L"<toast><visual><binding template='ToastGeneric'>" +
        L"<text>" + title + "</text>" +
        L"<text>"+ content + "</text>" +
        L"<image src='" + image + "'/>" +
        L"<image src='" + logo + "'" +
        L" placement='appLogoOverride' hint-crop='circle'/>" +
        L"</binding></visual></toast>";

    XmlDocument ^toastXml = ref new XmlDocument();

    toastXml->LoadXml(xmlString);

    ToastNotificationManager::CreateToastNotifier()->Show(ref new ToastNotification(toastXml));
}

Další informace o oznámeních najdete v tématu adaptivních a interaktivních informačních oznámení.

Podpora instalačních bází systému Windows XP, Windows Vista a Windows 7/8

Aplikaci pro Windows 10 můžete modernizovat, aniž byste museli vytvářet novou větev a udržovat samostatné základy kódu.

Pokud chcete vytvořit samostatné binární soubory pro uživatele Windows 10, použijte podmíněnou kompilaci. Pokud chcete vytvořit jednu sadu binárních souborů, které nasadíte všem uživatelům Windows, použijte kontroly za běhu.

Pojďme se rychle podívat na jednotlivé možnosti.

Podmíněná kompilace

Můžete zachovat jeden základ kódu a zkompilovat sadu binárních souborů pouze pro uživatele Windows 10.

Nejprve do projektu přidejte novou konfiguraci sestavení.

Pro danou konfiguraci sestavení vytvořte konstantu, která identifikuje kód, který volá rozhraní API WinRT.

Pro projekty založené na technologii .NET se konstanta nazývá podmíněná kompilace konstanta.

U projektů založených na jazyce C++ se konstanta nazývá definice preprocesoru .

konstanta definice preprocesoru

Přidejte danou konstantu před libovolný blok kódu UPW.

[System.Diagnostics.Conditional("_UWP")]
private void ShowToast()
{
 ...
}

#if _UWP
void UWP::ShowToast()
{
 ...
}
#endif

Kompilátor sestaví tento kód pouze v případě, že je tato konstanta definovaná v aktivní konfiguraci sestavení.

Kontroly během běhu

Můžete zkompilovat jednu sadu binárních souborů pro všechny uživatele Windows bez ohledu na to, jakou verzi Windows používají. Aplikace volá rozhraní API WinRT pouze v případě, že uživatel spustí vaši aplikaci jako zabalenou aplikaci ve Windows 10.

Nejjednodušší způsob, jak do kódu přidat kontroly za běhu, je nainstalovat tento balíček NuGet: pomocné knihovny Desktop Bridge a pak pomocí metody IsRunningAsUWP() podmíněně spustit všechen kód, který volá rozhraní API WinRT. Další podrobnosti najdete v tomto blogovém příspěvku: Desktop Bridge – Identifikace kontextu aplikace.

Související ukázky

• Příklad Hello World
• sekundární dlaždice
• Ukázková API rozhraní úložiště
• aplikace pro WinForms, která implementuje UWP UpdateTask
• most desktopové aplikace na ukázky UPW

Vyhledání odpovědí na vaše otázky

Máte otázky? Zeptejte se nás na Stack Overflow. Náš tým monitoruje tyto značky. Můžete se také zeptat na našich fórech.