C#/WinRT

C#/WinRT, C# dili için Windows Runtime (WinRT) projeksiyon desteği sağlayan NuGet paketli bir araç setidir. Projeksiyon derlemesi, WinRT API'lerini hedef dil için doğal ve tanıdık bir şekilde programlamayı sağlayan bir birlikte çalışma derlemesidir. C#/WinRT projeksiyonu, C# ve WinRT arabirimleri arasındaki birlikte çalışma ayrıntılarını gizler ve dizeler, URI'ler, ortak değer türleri ve genel koleksiyonlar gibi uygun .NET eşdeğerleri birçok WinRT türünün eşlemelerini sağlar.

C#/WinRT şu anda .NET'da Target Framework Moniker (TFM) kullanarak WinRT API'lerini kullanma desteği sağlamaktadır. TFM'yi belirli bir Windows SDK sürümüyle ayarlamak, C#/WinRT tarafından oluşturulan Windows SDK projeksiyon ve çalışma zamanı derlemelerine başvurular ekler.

C#/WinRT NuGet paketi, .NET tüketicileri için kendi WinRT birlikte çalışma derlemelerinizi oluşturmanıza ve başvurmanıza olanak tanır. En son C#/WinRT sürümü, C# dilinde WinRT türlerini yazma önizlemesini de içerir.

Ek bilgi için bkz. C#/WinRT GitHub deposu.

C#/WinRT için motivasyon

.NET (eski adıyla .NET Core), cihaz, bulut ve IoT uygulamaları oluşturmak için kullanılabilecek açık kaynaklı, platformlar arası bir çalışma zamanıdır.

.NET Framework ve .NET Core'un önceki sürümlerinde Windows'a özgü bir teknoloji olan WinRT hakkında yerleşik bilgi vardı. .NET 6+ sürümünün taşınabilirlik ve verimlilik hedeflerini desteklemek için, WinRT projeksiyon desteğini .NET derleyici ve çalışma zamanından kaldırdık ve C#/WinRT araç setine taşıdık (bkz. WinRT için yerleşik destek .NET'ten kaldırıldı). C#/WinRT'nin amacı, C# derleyicisinin ve .NET çalışma zamanının önceki sürümleri tarafından sağlanan yerleşik WinRT desteğiyle eşlik sağlamaktır. Ayrıntılar için bkz. Windows Runtime türlerinin .NET eşlemeleri.

C#/WinRT, WinUI 3 dahil olmak üzere Windows App SDK bileşenlerini de destekler. Windows App SDK, yerel Microsoft kullanıcı arabirimi denetimlerini ve diğer yerel bileşenleri işletim sisteminden kaldırır. Bu, uygulama geliştiricilerinin Windows 10, sürüm 1809 ve sonraki sürümlerde en son denetimleri ve bileşenleri kullanmasına olanak tanır.

Son olarak, C#/WinRT genel bir araç setidir ve WinRT için yerleşik desteğin C# derleyicisinde veya .NET çalışma zamanında kullanılamadığı diğer senaryoları desteklemeye yöneliktir.

Yeni neler var

En son C#/WinRT sürümleri Github deposundaki release notes sayfamızda bulunabilir.

Usage

C#/WinRT NuGet paketi hem WinRT bileşenlerinden C# projeksiyonları (birlikte çalışma derlemeleri olarak da adlandırılır) hem de Authoring C#/WinRT bileşenleri oluşturmak için kullanılabilir. C#/WinRT kullanım senaryolarıyla ilgili daha fazla ayrıntı için depomuzdaki usage kılavuzu bakın.

Birlikte çalışma derlemesi oluşturun ve dağıtın

WinRT API'leri Windows Meta Verileri (WinMD) dosyalarında tanımlanır. C#/WinRT NuGet paketi (Microsoft.Windows.CsWinRT), WinMD dosyalarını işlemek ve .NET C# kodu oluşturmak için kullanabileceğiniz C#/WinRT derleyicisi cswinrt.exe içerir. C#/WinRT, bu kaynak dosyalarını bir birlikte çalışma derlemesine derleyerek C++/WinRT'nin C++ dil projeksiyonu için başlık dosyaları oluşturmasına benzer şekilde çalışır. Daha sonra C#/WinRT birlikte çalışma derlemesini, genellikle NuGet paketi olarak başvuracak .NET uygulamaları için uygulama derlemesiyle birlikte dağıtabilirsiniz.

Birlikte çalışabilirlik derlemesi oluşturma ve dağıtma hakkında daha fazla bilgi için bkz. C++/WinRT bileşeninden C# projeksiyonu oluşturma ve .NET uygulamaları için bir NuGet olarak dağıtma.

Birlikte çalışabilirlik derlemesine referans verme

Genellikle, C#/WinRT birlikte çalışma derlemelerine uygulama projeleri tarafından başvurulur. Ancak bunlara ara birlikte çalışma derlemeleri tarafından da başvurulabilir. Örneğin, WinUI birlikte çalışma derlemesi Windows SDK birlikte çalışma derlemesine başvurur.

Bir üçüncü taraf WinRT bileşenini resmi birlikte çalışma derlemesi olmadan dağıtırsanız, bir uygulama project kendi özel projeksiyon kaynaklarını oluşturmak için birlikte çalışma derlemesi oluşturma yordamını izleyebilir. Bir işlem içinde aynı türde çakışan projeksiyonlar üretebileceğinden bu yaklaşımı önermiyoruz. Anlamsal Sürüm Oluşturma şemasını izleyen NuGet paketleme, bunu önlemek için tasarlanmıştır. Resmi bir üçüncü taraf birlikte çalışma derlemesi tercih edilir.

WinRT türleri için yerleşik destek (Önizleme)

C#/WinRT sürüm 1.4.1'den başlayarak, kitaplığınızın veya uygulamanızın çıkışına hem .NET hem de .NET Standard 2.0 için Windows SDK projeksiyonu ve çalışma zamanı kaynaklarını ekleme desteği eklenmiştir. Bu, Windows SDK türlerinin kullanımının bağımsız olduğu durumlarda kullanışlıdır. Katıştırılmış destek, kitaplık veya uygulama çıktı boyutunu azaltan WinRT.Runtime.dll ve Microsoft.Windows.SDK.NET.dll bağımlılıklarını kaldırır. Ayrıca kitaplık geliştiricilerinin alt düzey desteği sağlamasına olanak tanır ve çoklu hedefleme gereksinimini ortadan kaldırır.

Daha fazla ayrıntı için depomuzdaki C#/WinRT embedded belgelerine bakın.

WinRT türü etkinleştirme

C#/WinRT, işletim sistemi tarafından barındırılan WinRT türlerinin yanı sıra Win2D gibi üçüncü taraf bileşenlerinin etkinleştirilmesini destekler. Windows 10, sürüm 1903 ve sonraki sürümlerde sağlanan kayıt ücretsiz WinRT etkinleştirmesi (bkz. > Windows Runtime Components kullanarak Paketlenmemiş Masaüstü Uygulamalarını başlatma) ile birlikte üçüncü taraf bileşen etkinleştirme desteği etkinleştirilir. Yerel C++ bileşenleri, Microsoft.VCLibs.Desktop ikili dosyalarına başvurmak ve bunları kullanan uygulamalara iletmek amacıyla, Windows Masaüstü Uyumlu özelliğini ya proje özellikleri ya da .vcxproj dosyası aracılığıyla True olarak ayarlamalıdır. Aksi takdirde, bileşen yalnızca UWP uygulamalarını hedef alıyorsa, VCRT İleticiler paketi uygulamaların tüketilmesi için gereklidir.

C#/WinRT, Windows'un yukarıda açıklandığı gibi türü etkinleştirememesi durumunda bir etkinleştirme geri dönüş yolu da sağlar. Bu durumda, C#/WinRT tam tür adına göre yerel bir uygulama DLL'sini bulmayı dener ve öğeleri aşamalı olarak kaldırır. Örneğin, geri dönüş mantığı aşağıdaki modüllerden Contoso.Controls.Widget türünü sırayla etkinleştirmeyi dener:

1. Contoso.Controls.Widget.dll
2. Contoso.Controls.dll
3. Contoso.dll

C#/WinRT, uygulama DLL'sini bulmak için LoadLibrary alternatif arama sırasını kullanır. Bu geri dönüş davranışına dayanan bir uygulama, uygulama modülünün yanı sıra uygulama DLL'sini de paketlemelidir.

Yaygın hatalar ve sorun giderme

• Hata: "Windows Meta Verileri sağlanmadı veya algılanmadı."

  <CsWinRTWindowsMetadata> project özelliğini kullanarak Windows Meta Verileri belirtebilirsiniz, örneğin:

  <CsWinRTWindowsMetadata>10.0.19041.0</CsWinRTWindowsMetadata>
  

  C#/WinRT sürüm 1.2.1 ve sonraki sürümlerinde, bu özellik varsayılan olarak TargetPlatformVersionözelliğinde TargetFramework belirtilen Windows SDK sürümünden türetilir.

• Hata CS0246: 'Windows' türü veya ad alanı adı bulunamadı (kullanma yönergesi veya derleme başvurusu eksik mi?)

  Bu hatayı gidermek için, belirli bir Windows sürümünü hedeflemek için özelliğinizi <TargetFramework> düzenleyin, örneğin:

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

  özelliğini belirtme hakkında daha fazla bilgi için <TargetFramework> belgelerine bakın.

• Özniteliğine sahip bir arabirime yayınlanırken

  Bir nesneyi özniteliği bulunan bir arabirime dönüştürürken, açık bir dönüşüm ifadesi kullanmak yerine işlecini kullanmanız gerekir. Örneğin:

  someObject.As<SomeComImportInterface>
  

  Daha fazla ayrıntı için bkz. COM birlikte çalışma kılavuzu.

• System.Runtime.InteropServices.COMException: Sınıf kaydedilmedi (0x80040154 (REGDB_E_CLASSNOTREG))

  • C++/WinRT bileşeninden C#/WinRT projeksiyonu kullanırken bu özel durumu görürseniz, bileşenin Windows Desktop Compatible özelliğini project özellikleri aracılığıyla veya dosyası aracılığıyla .vcxproj olarak ayarladığınızdan emin olun.

.NET SDK sürüm oluşturma hataları

Proje, bağımlılıklarından daha eski bir .NET SDK sürümüyle oluşturulmuşsa, aşağıdaki hatalar veya uyarılarla karşılaşabilirsiniz.

Hata veya uyarı iletisi	Reason
Uyarı MSB3277: WinRT.Runtime veya Microsoft.Windows.SDK.NET'nın farklı sürümleri arasında çözümlenemeyen çakışmalar bulundu.	Bu derleme uyarısı, API yüzeyinde Windows SDK türlerini sunan bir kitaplığa başvururken oluşur.
Hata CS1705: 'AssemblyName1' derlemesi başvurulan 'AssemblyName2' derlemesinden daha yüksek bir sürüme sahip 'TypeName' kullanıyor	Bu derleme derleyicisi hatası, bir kitaplıkta kullanıma sunulan Windows SDK türlerine başvururken ve kullanırken oluşur.
System.IO.FileLoadException	Bu çalışma zamanı hatası, Windows SDK türlerini kullanıma sunmayan bir kitaplıkta belirli API'leri çağırırken oluşabilir.

Bu hataları düzeltmek için .NET SDK'nızı en son sürüme güncelleştirin. Bunun yapılması, uygulamanız tarafından kullanılan çalışma zamanı ve Windows SDK derleme sürümlerinin tüm bağımlılıklarla uyumlu olmasını sağlar. Çalışma zamanı düzeltmeleri derleme sürümlerimize güncelleştirme gerektirebileceğinden, bu hatalar .NET SDK'sına yönelik erken hizmet/özellik güncelleştirmeleriyle oluşabilir.

Bilinen sorunlar

Bilinen sorunlar ve hataya neden olan değişiklikler C#/WinRT GitHub deposunda belirtilir.

C#/WinRT NuGet paketi, cswinrt.exe derleyicisi veya oluşturulan projeksiyon kaynaklarıyla ilgili işlevsel sorunlarla karşılaşırsanız sorunları C#/WinRT sorunları sayfası aracılığıyla bize gönderin.

Ek kaynaklar

• C#/WinRT GitHub deposu