C#/WinRT

C#/WinRT, C# dili için Windows Çalışma Zamanı (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 birçok WinRT türünün uygun .NET eşdeğerlerine eşlemesini sağlar.

C#/WinRT şu anda .NET'te Hedef Çerçeve Takma Adlarını (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 bunlara 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+'nın taşınabilirlik ve verimlilik hedeflerini desteklemek için WinRT projeksiyon desteğini .NET derleyicisinden 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ılmıştır). 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 Çalışma Zamanı türlerinin .NET eşlemeleri.

C#/WinRT, WinUI dahil olmak üzere Windows Uygulama SDK'sı bileşenlerini de destekler. Windows Uygulama SDK'sı, 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 sürüm notları sayfamızda bulunabilir.

Usage

C#/WinRT NuGet paketi, hem WinRT bileşenlerinden C# yansımaları (birlikte çalışma derlemeleri olarak da adlandırılır) oluşturmak hem de C#/WinRT bileşenleri geliştirmek için kullanılabilir. C#/WinRT kullanım senaryolarıyla ilgili daha fazla ayrıntı için depomuzdaki kullanım kılavuzuna 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.exeiç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 ,NET uygulamalarının başvuruda bulunabileceği uygulama derlemesiyle birlikte dağıtabilirsiniz( genellikle nuGet paketi olarak).

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, .NET uygulamaları için 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 projesi 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ıza 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 çıkış 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 Çalışma Zamanı Bileşenlerini kullanarak Paketlenmemiş Masaüstü Uygulamalarını Geliştirme) ile bir masaüstü uygulamasında üçüncü taraf bileşen etkinleştirme desteği etkinleştirilir. Yerel C++ bileşenleri, Microsoft.VCLibs.Desktop ikili dosyalarına referans vermek ve tüketici uygulamalara iletmek amacıyla, proje özellikleri veya .vcxproj dosyası aracılığıyla Windows Masaüstü Uyumlu özelliğini 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ı."

  Proje özelliğini kullanarak <CsWinRTWindowsMetadata> 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 Windows Çalışma Zamanı API'lerini çağırma belgelerine <TargetFramework> bakın.

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

  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 COM birlikte çalışma kılavuzuna bkz.

• 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 proje özellikleri veya dosya aracılığıyla Windows Masaüstü Uyumlu özelliğini .vcxproj olarak ayarladığından emin olun.

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

Bağımlılıklarından daha önceki bir .NET SDK sürümüyle oluşturulmuş bir projede aşağıdaki hatalarla veya uyarılarla karşılaşabilirsiniz.

Hata veya uyarı iletisi	Reason
Uyarı MSB3277: WinRT.Runtime veya Microsoft.Windows.SDK.NET farklı sürümleri arasında çözümlenemeyen çakışmalar bulundu.	Bu derleme uyarısı, API yüzeyinde Windows SDK türlerini kullanıma 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, C#/WinRT sorunları sayfası aracılığıyla sorunları bize gönderin.

Ek kaynaklar

• C#/WinRT GitHub depo