Aracılığıyla paylaş


Masaüstü uygulamalarında Windows Çalışma Zamanı API'lerini çağırma

Bu konuda, masaüstü uygulama projelerinizi Windows işletim sistemi tarafından sağlanan Windows Çalışma Zamanı (WinRT) API'lerini kullanacak ve masaüstü uygulamalarınıza modern Windows 11 ve Windows 10 deneyimleri ekleyecek şekilde nasıl ayarlanacağı açıklanır.

Bazı Windows Çalışma Zamanı (WinRT) API'leri masaüstü uygulamalarında desteklenmez. Daha fazla bilgi için bkz.masaüstü uygulamalarında desteklenmeyen Windows Çalışma Zamanı API'leri.

.NET projesini Windows Çalışma Zamanı API'lerini kullanacak şekilde değiştirme

.NET projeleri için çeşitli seçenekler vardır:

  • .NET 6'dan itibaren, proje dosyanızda TFM (Hedef Çerçeve Monikeri) belirterek WinRT API'lerine erişebilirsiniz. Bu seçenek Windows 10, sürüm 1809 veya üzerini hedefleyen projelerde desteklenir.
  • .NET'in önceki sürümlerinde, projenize tüm gerekli başvuruları eklemek için Microsoft.Windows.SDK.Contracts NuGet paketini yükleyebilirsiniz. Bu seçenek, Windows 10, sürüm 1803 veya üzerini hedefleyen projelerde desteklenir.
  • Projeniz .NET 6 (veya üzeri) ve önceki .NET sürümlerini birden çok hedeflediyse, proje dosyasını her iki seçeneği de kullanacak şekilde yapılandırabilirsiniz.

.NET 6 ve üzeri: Hedef Çerçeve Takma Adı seçeneğini kullanın

Bu seçenek yalnızca .NET 6 (veya üzeri) kullanan ve Windows 10, sürüm 1809 veya sonraki bir işletim sistemi sürümünü hedefleyen projelerde desteklenir. Proje dosyasında Windows işletim sistemi sürümüne özgü bir TFM belirterek, uygun Windows SDK hedef paketinebir başvuru eklenir. Bu senaryo hakkında daha fazla arka plan bilgisi için .NET'de Windows API'lerini çağırma blog gönderisine bakın.

  1. Projeniz Visual Studio'da açıkken, Çözüm Gezgini'nde projenize sağ tıklayın ve proje dosyasını düzenleseçin. Proje dosyanız buna benzer olacaktır.

    Not

    Aşağıdaki örnek, bir Windows GUI yürütülebilir dosyasını belirten (ve uygulama çalıştığında konsol penceresinin açılmasını engelleyen) OutputType olarak WinExe'i göstermektedir. Uygulamanızın GUI'leri yoksa OutputType farklı bir değere sahip olur. Windows GUI uygulamalarından, konsol uygulamalarından ve kitaplıklardan WinRT API'lerini çağırabilirsiniz. Ayrıca, TargetFramework değeriniz aşağıdaki örnekle tam olarak eşleşmeyebilir.

    <Project Sdk="Microsoft.NET.Sdk">
      <PropertyGroup>
        <OutputType>WinExe</OutputType>
        <TargetFramework>net5.0</TargetFramework>
      </PropertyGroup>
    </Project>
    
  2. Diğer tüm ayarları olduğu gibi bırakarak, TargetFramework öğesinin değerini aşağıdaki dizelerden biriyle değiştirin:

    • net6.0-windows10.0.17763.0: Uygulamanız Windows 10, sürüm 1809'u hedeflerse.
    • net6.0-windows10.0.18362.0: Uygulamanız Windows 10, sürüm 1903'i hedeflerse.
    • net6.0-windows10.0.19041.0: Uygulamanız Windows 10, sürüm 2004'i hedeflerse.
    • net6.0-windows10.0.22000.0: Uygulamanız Windows 11'in ilk sürümünü hedeflediyse.
    • net6.0-windows10.0.22621.0: Uygulamanız Windows 11, sürüm 22H2'yi hedeflerse.
    • net6.0-windows10.0.26100.0: Uygulamanız Windows 11, sürüm 24H2'yi hedeflerse.

    Örneğin, aşağıdaki öğe Windows 10, sürüm 2004'i hedefleyen bir proje içindir.

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

    .NET'in sonraki sürümlerinde, değerini ilgili sürümle değiştirebilirsiniz, örneğin net8.0-windows10.0.19041.0.

  3. Değişikliklerinizi kaydedin ve proje dosyasını kapatın.

.NET 6 veya sonraki sürümlerde desteklenmeyen WinRT API'leri

.NET 6 ve sonraki sürümlerde, Windows.UI ad alanında desteklenmeyen çeşitli Windows Çalışma Zamanı (WinRT) API'leri vardır. Aşağıda listelenen API'ler için, API'lerin eşdeğer sürümleri WinUI (Microsoft.UI) ad alanında (örneğin, Microsoft.UI.Text) bulunur. Aşağıdaki WinRT API'leri .NET 6 ve sonraki sürümlerde desteklenen değildir:

Birden çok Windows işletim sistemi sürümünü destekleme

Windows işletim sistemi sürümüne özgü TargetFramework özelliği, uygulamanızın derlediği Windows SDK sürümünü belirler. Bu özellik, derleme zamanında erişilebilir API'ler kümesini belirler ve hem TargetPlatformVersion hem de TargetPlatformMinVersion (açıkça ayarlanmadıysa) için varsayılan değerler sağlar. TargetPlatformVersion özelliğinin, TargetFramework işletim sistemi sürümü tarafından otomatik olarak ayarlandığı için proje dosyasında açıkça tanımlanması gerekmez.

TargetPlatformMinVersion, TargetPlatformVersion'den küçük olacak şekilde geçersiz kılınabilir (TargetFramework özelliğindeki sürüm tarafından belirlenir). Bu, bir uygulamanın önceki işletim sistemi sürümlerinde çalışmasına izin verir. Örneğin, uygulamanızın Windows 10, sürüm 1809'a alt düzey özelliğini desteklemek için proje dosyanızda aşağıdakileri ayarlayabilirsiniz.

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

TargetPlatformMinVersion değerini TargetPlatformVersion altındaki bir sürüme ayarlamanın, kullanılamayan API'leri çağırma olasılığı oluşturduğunu unutmayın. Desteklenen tüm işletim sistemi sürümlerinde bulunmayan WinRT API'lerini çağırırken, bu çağrıları ApiInformation denetimleriyle korumanızı öneririz. Daha fazla bilgi için bkz. Sürüm uyarlamalı uygulamalar.

.NET'in önceki sürümleri: Microsoft.Windows.SDK.Contracts NuGet paketini yükleyin

Uygulamanız .NET Core 3.x veya .NET Framework kullanıyorsa bu seçeneği kullanın. Bu seçenek, Windows 10, sürüm 1803 veya üzerini hedefleyen projelerde desteklenir.

  1. paket başvurularının'in etkinleştirildiğinden emin olun.

    1. Visual Studio'da, Araçları - NuGet Paket Yöneticisi> -> Paket Yöneticisi Ayarlarıöğesine tıklayın.
    2. PackageReference 'ın, Varsayılan paket yönetim biçimiolarak seçili olduğundan emin olun.
  2. Projeniz Visual Studio'da açıkken, Çözüm Gezgini'nde projenize sağ tıklayın ve nuget paketlerini yönetseçin.

  3. NuGet Paket Yöneticisi penceresinde Gözat sekmesini seçin ve için arama yapın.

  4. Microsoft.Windows.SDK.Contracts paketi bulunduktan sonra, NuGet Paket Yöneticisi penceresinin sağ bölmesinde, hedeflemek istediğiniz Windows 10 sürümüne göre yüklemek istediğiniz paketin Sürüm seçin:

    • 10.0.19041.xxxx: Windows 10, sürüm 2004 için bunu seçin.
    • 10.0.18362.xxxx: Windows 10, sürüm 1903 için bunu seçin.
    • 10.0.17763.xxxx: Windows 10, sürüm 1809 için bunu seçin.
    • 10.0.17134.xxxx: Windows 10, sürüm 1803 için bunu seçin.
  5. Tıklayın,Yükle.

.NET'in farklı sürümlerini birden çok hedefleyen projeleri yapılandırma

Projeniz .NET 6 (veya üzeri) ve önceki sürümleri (.NET Core 3.x ve .NET Framework dahil) birden çok hedeflediyse, proje dosyasını Hedef Çerçeve Takma Adını (TFM) kullanarak .NET 6 (veya üzeri) için WinRT API başvurularını otomatik olarak çekecek şekilde yapılandırabilir ve önceki sürümler için Microsoft.Windows.SDK.Contracts NuGet paketini kullanabilirsiniz.

  1. Projeniz Visual Studio'da açıkken, Çözüm Gezgini'nde projenize sağ tıklayın ve proje dosyasını düzenleseçin. Aşağıdaki örnekte .NET Core 3.1 kullanan bir uygulama için proje dosyası gösterilmektedir.

    Not

    Aşağıdaki örnek, Windows GUI yürütülebilir dosyasını belirten ve uygulama çalıştırıldığında konsol penceresinin açılmasını engelleyen bir OutputType olarak WinExe'yi göstermektedir. Uygulamanızın GUI'leri yoksa OutputType farklı bir değere sahip olur. Windows GUI uygulamalarından, konsol uygulamalarından ve kitaplıklardan WinRT API'lerini çağırabilirsiniz. Ayrıca, TargetFramework değeriniz aşağıdaki örnekle tam olarak eşleşmeyebilir.

    <Project Sdk="Microsoft.NET.Sdk.WindowsDesktop">
      <PropertyGroup>
        <OutputType>WinExe</OutputType>
        <TargetFramework>netcoreapp3.1</TargetFramework>
        <UseWindowsForms>true</UseWindowsForms>
      </PropertyGroup>
    </Project>
    
  2. Dosyadaki TargetFramework öğesini bir TargetFrameworks öğesiyle değiştirin (çoğul değerini not edin). Bu öğede, hedeflemek istediğiniz tüm .NET sürümleri için Hedef Çerçeve Takma Adlarını (TFM) noktalı virgülle ayırarak belirtin.

    • .NET 6 veya üzeri için aşağıdaki Hedef Çerçeve Kesimlerinden (TFM) birini kullanın:
      • net6.0-windows10.0.17763.0: Eğer uygulamanız Windows 10 sürüm 1809'u hedefliyorsa.
      • net6.0-windows10.0.18362.0: Uygulamanız Windows 10, sürüm 1903'i hedeflerse.
      • net6.0-windows10.0.19041.0: Uygulamanız Windows 10, sürüm 2004'i hedeflerse.
      • net6.0-windows10.0.22000.0: Uygulamanız Windows 11'in ilk sürümünü hedeflediyse.
      • net6.0-windows10.0.22621.0: Uygulamanız Windows 11, sürüm 22H2'yi hedeflerse.
      • net6.0-windows10.0.26100.0: Uygulamanız Windows 11, sürüm 24H2'yi hedeflerse.
    • .NET Core 3.x için netcoreapp3.0 veya netcoreapp3.1kullanın.
    • .NET Framework için net46kullanın.

    Aşağıdaki örnek, .NET Core 3.1 ve .NET 6'nın (Windows 10, sürüm 2004 için) nasıl birden fazla platforma yönelik hale getirileceğini gösterir.

    <TargetFrameworks>netcoreapp3.1;net6.0-windows10.0.19041.0</TargetFrameworks>
    
  3. PropertyGroup öğesinden sonra, uygulamanızın hedeflediği .NET Core 3.x veya .NET Framework'ün herhangi bir sürümü için Microsoft.Windows.SDK.Contracts NuGet paketini yükleyen bir koşullu deyim içeren bir PackageReference öğesi ekleyin. PackageReference öğesi, ItemGroup öğesinin alt öğesi olmalıdır. Aşağıdaki örnek, .NET Core 3.1 için bunun nasıl yapılacağını gösterir.

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

    İşiniz bittiğinde proje dosyanız şuna benzer görünmelidir.

    <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. Değişikliklerinizi kaydedin ve proje dosyasını kapatın.

C++ masaüstü (Win32) projesini Windows Çalışma Zamanı API'lerini kullanacak şekilde değiştirme

WinRT API'lerini kullanmak için C++/WinRT kullanın. C++/WinRT, üst bilgi dosyası tabanlı bir kitaplık olarak uygulanan ve modern Windows API'sine birinci sınıf erişim sağlamak üzere tasarlanmış, WinRT API'leri için tamamen standart bir modern C++17 dil projeksiyonudur.

Projenizi C++/WinRT için yapılandırmak için:

Bu seçenekler hakkında daha fazla bilgi için bkz. C++/WinRT için Visual Studio desteği ve VSIX.

Windows 10 deneyimleri ekleme

Artık kullanıcılar uygulamanızı Windows 10'da çalıştırdığında göze çarpan modern deneyimler eklemeye hazırsınız. Bu tasarım akışını kullanın.

İlk olarak, hangi deneyimleri eklemek istediğinize karar verin

Aralarından seçim yapabileceğiniz çok şey var. Örneğin,para kazanma API'lerini kullanarak satın alma siparişi akışınızı basitleştirebilir veya başka bir kullanıcının paylaştığı yeni bir resim gibi ilginç bir şey uygulamanıza doğrudan dikkat .

Anlık bildirim

Kullanıcılar iletinizi yoksaysa veya kapatsalar bile, iletinizi işlem merkezinde yeniden görebilir ve ardından iletiye tıklayarak uygulamanızı açabilir. Bu, uygulamanızla etkileşimi artırır ve uygulamanızın işletim sistemiyle derin bir şekilde tümleştirilmiş görünmesini sağlamanın ek bonusunu getirir. Bu deneyimin kodunu bu makalenin ilerleyen bölümlerinde göstereceğiz.

Daha fazla fikir edinmek için UWP belgeleri ziyaret edin.

geliştirme veya genişletme kararı verme

geliştirmek ve genişletmekterimlerini kullandığımızı sık sık duyarsınız, bu yüzden bu terimlerin tam olarak ne anlama geldiğini açıklamak için biraz zaman ayıracağız.

Paketlenmiş bir uygulama olsun veya olmasın doğrudan masaüstü uygulamanızdan çağırabileceğiniz WinRT API'lerini açıklamak için geliştirmek terimini kullanırız. Bir Windows 10 deneyimi seçtiğinizde, oluşturmanız gereken API'leri belirleyin ve bu API'nin bu listedegörünüp görünmediğini görün. Bu, doğrudan masaüstü uygulamanızdan çağırabileceğiniz API'lerin listesidir. API'niz bu listede görünmüyorsa, bunun nedeni söz konusu API ile ilişkili işlevselliğin yalnızca bir UWP işlemi içinde çalıştırılabilmesidir. Bunlar genellikle UWP eşleme denetimi veya Windows Hello güvenlik istemi gibi UWP XAML'yi işleyen API'leri içerir.

Not

UWP XAML'yi işleyen API'ler genellikle doğrudan masaüstünüzden çağrılamasa da, alternatif yaklaşımları kullanabilirsiniz. UWP XAML denetimlerini veya diğer özel görsel deneyimleri barındırmak istiyorsanız, XAML Adaları (Windows 10, sürüm 1903'den başlayarak) ve Görsel katmanı (Windows 10, sürüm 1803'den başlayarak) kullanabilirsiniz. Bu özellikler paketlenmiş veya paketlenmemiş masaüstü uygulamalarında kullanılabilir.

Masaüstü uygulamanızı paketlemeyi seçtiyseniz, çözümünüze bir UWP projesi ekleyerek uygulamanızı genişletmek için başka bir seçenek vardır. Masaüstü projesi hala uygulamanızın giriş noktasıdır, ancak UWP projesi bu listede görünmeyen tüm API'lereerişmenizi sağlar. Masaüstü uygulaması bir uygulama hizmeti kullanarak UWP işlemiyle iletişim kurabilir ve bunun nasıl ayarlanacağı konusunda birçok kılavuzumuz vardır. UWP projesi gerektiren bir deneyim eklemek istiyorsanız bkz. UWP bileşenleriyle genişletme.

Referans API sözleşmeleri

API'yi doğrudan masaüstü uygulamanızdan çağırabiliyorsanız bir tarayıcı açın ve bu API için başvuru konusunu arayın. API özetinin altında, bu API'nin API sözleşmesini açıklayan bir tablo bulacaksınız. Bu tabloya bir örnek aşağıda verilmişti:

API sözleşme tablosu

.NET tabanlı bir masaüstü uygulamanız varsa, bu API sözleşmesine bir erişim ekleyin ve ardından bu dosyanın Yerel Kopyala özelliğini Falseolarak ayarlayın. C++tabanlı bir projeniz varsa, bu sözleşmeyi içeren klasörün yolunuEk Ekleme Dizinleri'ne ekleyin.

Deneyiminizi eklemek için API'leri çağırın

Aşağıda, daha önce baktığımız bildirim penceresini göstermek için kullanacağınız kod yer alır. Bu API'ler bu liste görünür, böylece bu kodu masaüstü uygulamanıza ekleyebilir ve hemen çalıştırabilirsiniz.

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

Bildirimler hakkında daha fazla bilgi edinmek için bkz. Uyarlamalı ve Etkileşimli bildirimleri.

Windows XP, Windows Vista ve Windows 7/8 yükleme temellerini destekleme

Yeni bir dal oluşturmak ve ayrı kod temelleri tutmak zorunda kalmadan uygulamanızı Windows 10 için modernleştirebilirsiniz.

Windows 10 kullanıcıları için ayrı ikili dosyalar oluşturmak istiyorsanız koşullu derleme kullanın. Tüm Windows kullanıcılarına dağıttığınız bir ikili dizi oluşturmayı tercih ederseniz çalışma zamanı denetimlerini kullanın.

Şimdi her seçeneğe hızlıca göz atalım.

Koşullu derleme

Yalnızca Windows 10 kullanıcıları için bir kod tabanı tutabilir ve ikili dosyalar kümesi derleyebilirsiniz.

İlk olarak, projenize yeni bir derleme yapılandırması ekleyin.

Derleme Yapılandırması

Bu derleme yapılandırması için, WinRT API'lerini çağıran kodu tanımlamak için bir sabit oluşturun.

.NET tabanlı projeler için, bu sabite Koşullu Derleme Sabitidenir.

Koşullu Derleme sabiti

C++tabanlı projeler için sabit, Önişlemci Tanımıolarak adlandırılır.

Önişlemci Tanımı sabiti

Bu sabiti herhangi bir UWP kodu bloğunun önüne ekleyin.

[System.Diagnostics.Conditional("_UWP")]
private void ShowToast()
{
 ...
}
#if _UWP
void UWP::ShowToast()
{
 ...
}
#endif

Derleyici, bu kodu yalnızca bu sabit etkin derleme yapılandırmanızda tanımlandığında oluşturur.

Çalışma zamanı denetimleri

Hangi Windows sürümünü çalıştırdıklarına bakılmaksızın tüm Windows kullanıcılarınız için bir ikili dosya kümesi derleyebilirsiniz. Uygulamanız WinRT API'lerini yalnızca kullanıcı uygulamanızı Windows 10'da paketlenmiş bir uygulama olarak çalıştırıyorsa çağırır.

Kodunuza çalışma zamanı denetimleri eklemenin en kolay yolu şu Nuget paketini yüklemektir: Masaüstü Köprüsü Yardımcıları ve ardından WinRT API'lerini çağıran tüm kodları kapatmak için IsRunningAsUWP() yöntemini kullanın. Daha fazla bilgi için bu blog gönderisine bakın: masaüstü köprüsü - Uygulamanın bağlamınıtanımlayın.

Sorularınızın yanıtlarını bulun

Sorularınız mı var? Stack Overflow'da bize sorun. Ekibimiz bu etiketleriniizler. ayrıca forumlarımızdasorabilirsiniz.