C#/WinRT

C#/WinRT adalah toolkit paket NuGet yang menyediakan dukungan proyeksi Windows Runtime (WinRT) untuk bahasa C#. Perakitan proyeksi adalah perakitan interop, yang memungkinkan pemrograman API WinRT dengan cara yang intuitif dan akrab untuk bahasa target. Proyeksi C#/WinRT menyembunyikan detail interop antara antarmuka C# dan WinRT, dan menyediakan pemetaan banyak jenis WinRT ke setara .NET yang sesuai, seperti string, URI, jenis nilai umum, dan koleksi generik.

C#/WinRT saat ini menyediakan dukungan untuk menggunakan API WinRT melalui penggunaan Monikers Kerangka Kerja Target (TFM) di .NET. Mengatur TFM dengan versi Windows SDK tertentu menambahkan referensi ke proyeksi Windows SDK dan rakitan runtime yang dihasilkan oleh C#/WinRT.

Paket C#/WinRT NuGet memungkinkan Anda membuat dan mereferensikan rakitan interop WinRT Anda sendiri untuk konsumen .NET. Versi C#/WinRT terbaru juga menyertakan pratinjau penulisan jenis WinRT di C#.

Untuk informasi tambahan, lihat repositori GitHub C#/WinRT.

Motivasi untuk C#/WinRT

.NET (sebelumnya dikenal sebagai .NET Core) adalah runtime lintas platform sumber terbuka yang dapat digunakan untuk membangun aplikasi perangkat, cloud, dan IoT.

Versi .NET Framework dan .NET Core sebelumnya memiliki pengetahuan bawaan tentang WinRT—teknologi khusus Windows. Untuk mendukung tujuan portabilitas dan efisiensi .NET 6+, kami mengangkat dukungan proyeksi WinRT dari kompilator .NET dan runtime dan memindahkannya ke toolkit C#/WinRT (lihat Dukungan bawaan untuk WinRT dihapus dari .NET). Tujuan C#/WinRT adalah untuk memberikan paritas dengan dukungan WinRT bawaan yang disediakan oleh versi kompilator C# dan runtime .NET sebelumnya. Untuk detailnya, lihat Pemetaan .NET jenis Windows Runtime.

C#/WinRT juga mendukung komponen di Windows App SDK, termasuk WinUI. Windows App SDK mengangkat kontrol UI Microsoft asli dan komponen asli lainnya dari sistem operasi. Ini memungkinkan pengembang aplikasi untuk menggunakan kontrol dan komponen terbaru pada Windows 10, versi 1809, dan rilis yang lebih baru.

Terakhir, C#/WinRT adalah toolkit umum dan dimaksudkan untuk mendukung skenario lain di mana dukungan bawaan untuk WinRT tidak tersedia di kompilator C# atau runtime .NET.

Apa yang baru

Rilis C#/WinRT terbaru dapat ditemukan di halaman catatan rilis kami di repositori Github.

Usage

Paket C#/WinRT NuGet dapat digunakan untuk menghasilkan proyeksi C# (juga disebut rakitan interop) dari komponen WinRT dan di komponen Authoring C#/WinRT. Untuk detail selengkapnya mengenai skenario penggunaan untuk C#/WinRT, lihat panduan penggunaan pada repositori kami.

Membuat dan mendistribusikan rakitan interop

API WinRT didefinisikan dalam file Metadata Windows (WinMD). Paket C#/WinRT NuGet (Microsoft.Windows.CsWinRT) menyertakan pengkompilasi C#/WinRT, cswinrt.exe, yang dapat Anda gunakan untuk memproses file WinMD dan menghasilkan kode .NET C#. C#/WinRT mengkompilasi file sumber ini ke dalam rakitan interop, mirip dengan bagaimana C++/WinRT menghasilkan header untuk proyeksi bahasa C++. Anda kemudian dapat mendistribusikan rakitan interop C#/WinRT bersama dengan perakitan implementasi untuk aplikasi .NET untuk dirujuk, biasanya sebagai paket NuGet.

Untuk detail selengkapnya tentang cara membuat dan mendistribusikan perakitan interop, lihat Membuat proyeksi C# dari komponen C++/WinRT, mendistribusikan sebagai NuGet untuk aplikasi .NET.

Mengacu pada pustaka interop

Biasanya, rakitan interop C#/WinRT dirujuk oleh proyek aplikasi. Tetapi mereka juga dapat dirujuk pada gilirannya oleh rakitan interop perantara. Misalnya, perakitan interop WinUI akan mengacu pada perakitan interop Windows SDK.

Jika Anda mendistribusikan komponen WinRT pihak ketiga tanpa rakitan interop resmi, proyek aplikasi dapat mengikuti prosedur untuk menghasilkan rakitan interop untuk menghasilkan sumber proyeksi privatnya sendiri. Kami tidak merekomendasikan pendekatan ini, karena dapat menghasilkan proyeksi yang bertentangan dengan jenis yang sama dalam suatu proses. Kemasan NuGet, mengikuti skema Penerapan Versi Semantik , dirancang untuk mencegah hal ini. Majelis interop pihak ketiga resmi lebih disukai.

Dukungan terintegrasi untuk jenis WinRT (Pratinjau)

Dimulai dengan C#/WinRT versi 1.4.1, dukungan disertakan untuk menyematkan proyeksi Windows SDK dan sumber runtime untuk .NET dan .NET Standard 2.0 ke dalam output pustaka atau aplikasi Anda. Ini berguna dalam kasus di mana penggunaan Windows SDK bersifat mandiri. Dukungan yang disematkan menghapus dependensi pada WinRT.Runtime.dll dan Microsoft.Windows.SDK.NET.dll yang mengurangi ukuran output pustaka atau aplikasi. Ini juga memungkinkan pengembang pustaka untuk memberikan dukungan downlevel dan menghapus kebutuhan akan multi-penargetan.

Untuk detail selengkapnya, lihat dokumentasi C#/WinRT yang disematkan pada repositori kami.

Aktivasi jenis WinRT

C#/WinRT mendukung aktivasi jenis WinRT yang dihosting oleh sistem operasi, serta komponen pihak ketiga seperti Win2D. Dukungan untuk aktivasi komponen pihak ketiga dalam aplikasi desktop diaktifkan dengan aktivasi WinRT gratis pendaftaran (lihat Meningkatkan Aplikasi Desktop Non-paket menggunakan Komponen Runtime Windows), tersedia di Windows 10, versi 1903 dan yang lebih baru. Komponen C++ native harus mengatur properti Windows Desktop Compatible ke True baik melalui properti proyek atau file .vcxproj, untuk mereferensikan dan meneruskan biner Microsoft.VCLibs.Desktop ke aplikasi yang mengonsumsinya. Jika tidak, paket Penerus VCRT akan diperlukan oleh aplikasi yang menggunakannya, jika komponen tersebut hanya menargetkan aplikasi UWP.

C#/WinRT juga menyediakan jalur fallback aktivasi jika Windows gagal mengaktifkan tipe seperti yang dijelaskan di atas. Dalam hal ini, C#/WinRT mencoba menemukan DLL implementasi asli berdasarkan nama jenis yang sepenuhnya memenuhi syarat, menghapus elemen secara progresif. Misalnya, logika fallback akan mencoba mengaktifkan tipe Contoso.Controls.Widget dari modul berikut, secara berurutan:

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

C#/WinRT menggunakan urutan pencarian alternatif LoadLibrary untuk menemukan DLL implementasi. Aplikasi yang mengandalkan perilaku fallback ini harus mengemas DLL implementasi bersama modul aplikasi.

Kesalahan umum dan pemecahan masalah

• Kesalahan: "Metadata Windows tidak disediakan atau terdeteksi."

  Anda dapat menentukan Metadata Windows dengan menggunakan <CsWinRTWindowsMetadata> properti proyek, misalnya:

  <CsWinRTWindowsMetadata>10.0.19041.0</CsWinRTWindowsMetadata>
  

  Di C#/WinRT versi 1.2.1 dan yang lebih baru, properti ini secara default diatur ke TargetPlatformVersion, yang berasal dari versi Windows SDK yang ditentukan dalam properti TargetFramework.

• Kesalahan CS0246: Jenis atau nama namespace 'Windows' tidak dapat ditemukan (apakah Anda kehilangan direktif using atau referensi assembly?)

  Untuk mengatasi kesalahan ini, edit properti Anda <TargetFramework> untuk menargetkan versi Windows tertentu, misalnya:

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

  Lihat dokumen tentang Memanggil Windows Runtime API untuk informasi lebih lengkap mengenai penentuan <TargetFramework> properti.

• System.InvalidCastException saat mentransmisikan ke antarmuka yang memiliki ComImport atribut

  Saat mentransmisikan objek ke antarmuka yang memiliki ComImport atribut , Anda harus menggunakan .As<> operator alih-alih menggunakan ekspresi cast eksplisit. Contohnya:

  someObject.As<SomeComImportInterface>
  

  Untuk detail selengkapnya, lihat panduan interop COM.

• System.Runtime.InteropServices.COMException: Kelas tidak terdaftar (0x80040154 (REGDB_E_CLASSNOTREG))

  • Jika Anda melihat pengecualian ini saat mengkonsumsi proyeksi C#/WinRT dari komponen C++/WinRT, pastikan komponen telah mengatur properti Kompatibel Desktop Windows ke True baik melalui properti proyek atau melalui .vcxproj file.

Kesalahan penerapan versi .NET SDK

Anda mungkin mengalami kesalahan atau peringatan berikut dalam proyek yang dibangun dengan versi .NET SDK sebelumnya daripada dependensinya.

Pesan kesalahan atau peringatan	Reason
Peringatan MSB3277: Ditemukan konflik antara versi WinRT.Runtime yang berbeda atau Microsoft.Windows.SDK.NET yang tidak dapat diselesaikan.	Peringatan build ini terjadi saat mereferensikan pustaka yang mengekspos jenis Windows SDK di permukaan API-nya.
Kesalahan CS1705: Assembly 'AssemblyName1' menggunakan 'TypeName' yang memiliki versi lebih tinggi daripada rakitan yang dirujuk 'AssemblyName2'	Kesalahan kompilator build ini terjadi saat mereferensikan dan mengkonsumsi jenis Windows SDK yang terekspos dalam pustaka.
System.IO.FileLoadException	Kesalahan runtime ini dapat terjadi ketika memanggil API tertentu dalam pustaka yang tidak mengekspos tipe SDK Windows.

Untuk memperbaiki kesalahan ini, perbarui .NET SDK Anda ke versi terbaru. Melakukannya akan memastikan bahwa versi rakitan runtime dan Windows SDK yang digunakan oleh aplikasi Anda kompatibel dengan semua dependensi. Kesalahan ini dapat terjadi dengan pembaruan layanan/fitur awal ke .NET SDK, karena perbaikan runtime mungkin memerlukan pembaruan untuk versi rakitan kami.

Masalah yang diketahui

Masalah yang diketahui dan perubahan yang mengganggu tercatat dalam repositori GitHub C#/WinRT.

Jika Anda mengalami masalah fungsi dengan paket C#/WinRT NuGet, pengkompilasi cswinrt.exe, atau sumber proyeksi yang dihasilkan, kirimkan masalah kepada kami melalui halaman masalah C#/WinRT.

Sumber daya tambahan

• Repositori GitHub C#/WinRT