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
.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
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>
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.
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 (
- Windows.UI.Colors sınıfı
- Windows.UI.ColorHelper sınıfı
- Windows.UI.Text (bu ad alanındaki tüm sınıflar , yalnızca Windows.UI.Text.FontStretch, Windows.UI.Text.FontStyle, Windows.UI.Text.FontWeight, Windows.UI.Text.UnderlineTypehariç ve Windows.UI.Text.Core ad alanı altındaki tüm sınıflar)
- Windows.UI.Xaml (bu ad alanında tüm sınıflar)
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, 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.
paket başvurularının'in etkinleştirildiğinden emin olun.
- Visual Studio'da, Araçları - NuGet Paket Yöneticisi> -> Paket Yöneticisi Ayarlarıöğesine tıklayın.
- PackageReference 'ın, Varsayılan paket yönetim biçimiolarak seçili olduğundan emin olun.
Projeniz Visual Studio'da açıkken,
Çözüm Gezgini 'nde projenize sağ tıklayın ve nuget paketlerini yönetseçin. NuGet Paket Yöneticisi
penceresinde Gözat sekmesini seçin veiçin arama yapın. 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.
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.
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>
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>
- .NET 6 veya üzeri için aşağıdaki Hedef Çerçeve Kesimlerinden (TFM) birini kullanın:
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>
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:
- Yeni projeler için C++/WinRT Visual Studio Uzantısı (VSIX) yükleyebilir ve bu uzantıya dahil edilen C++/WinRT proje şablonlarından birini kullanabilirsiniz.
- Mevcut projeler için, projeye Microsoft.Windows.CppWinRT NuGet paketini yükleyebilirsiniz.
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,
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 listede
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'lere
✅ 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:
.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 yolunu
✅ 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.
İlgili Örnekler
- Merhaba Dünya Örneği
- İkincil Kutucuk
- Depolama API Örneği
- WinForms uygulaması , UWP UpdateTask'i uygular.
- Masaüstü uygulamalarını UWP Örneklerine bağlayan köprü
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.
Windows developer