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, serta menyediakan pemetaan berbagai jenis WinRT ke padanan .NET yang sesuai, seperti string, URI, tipe nilai umum, dan koleksi generik.

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

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

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

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 dan runtime .NET dan memindahkannya ke toolkit C#/WinRT (lihat dukungan Built-in untuk WinRT dihapus dari .NET). Tujuan C#/WinRT adalah untuk memberikan paritas dengan dukungan WinRT bawaan yang disediakan oleh versi kompilator C# sebelumnya dan runtime .NET. Untuk detailnya, lihat pemetaan jenis-jenis Windows Runtime di .NET.

C#/WinRT juga mendukung komponen dalam SDK Aplikasi Windows, termasuk WinUI 3. SDK Aplikasi Windows mengangkat kontrol antarmuka pengguna Microsoft asli dan komponen asli lainnya dari sistem operasi. Ini memungkinkan pengembang aplikasi untuk menggunakan kontrol dan komponen terbaru pada rilis Windows 10, versi 1809, dan 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 pada 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) mencakup pengkompilasi C#/WinRT, cswinrt.exe, yang dapat Anda gunakan untuk memproses file WinMD dan menghasilkan kode C# .NET. 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 assembly interop C#/WinRT bersama dengan assembly implementasi yang dapat dirujuk oleh aplikasi .NET, biasanya dalam bentuk 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, rakitan interop WinUI akan merujuk pada rakitan interop SDK Windows.

Jika Anda mendistribusikan komponen WinRT pihak ketiga tanpa rakitan interop resmi, proyek aplikasi dapat mengikuti prosedur untuk menghasilkan rakitan interop guna membuat 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 tertanam untuk jenis WinRT

Dimulai dengan C#/WinRT versi 1.4.1, dukungan disertakan untuk menyematkan proyeksi SDK Windows dan sumber runtime untuk .NET dan .NET Standar 2.0 ke dalam output pustaka atau aplikasi Anda. Ini berguna dalam kasus di mana penggunaan jenis SDK Windows terisolasi. 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 WinRT tanpa pendaftaran (lihat Mengaktifkan Aplikasi Desktop Non-paket menggunakan Komponen Windows Runtime), tersedia di Windows 10, versi 1903 dan yang lebih baru. Komponen C++ asli harus mengatur properti Windows Desktop Compatible ke True, baik melalui pengaturan proyek atau file .vcxproj, untuk merujuk dan meneruskan biner Microsoft.VCLibs.Desktop ke aplikasi yang menggunakannya. Jika tidak, paket VCRT Forwarders akan diperlukan dengan menggunakan aplikasi jika komponen hanya menargetkan aplikasi UWP.

C#/WinRT juga menyediakan jalur fallback aktivasi jika Windows gagal mengaktifkan tipe yang telah dijelaskan sebelumnya. 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: "Windows Metadata tidak disediakan atau terdeteksi."

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

  <CsWinRTWindowsMetadata>10.0.19041.0</CsWinRTWindowsMetadata>
  

  Dalam C#/WinRT versi 1.2.1 dan yang lebih baru, properti ini default ke TargetPlatformVersion, yang berasal dari versi SDK Windows 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 <TargetFramework> Anda untuk menargetkan versi Windows tertentu, misalnya:

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

  Lihat dokumen di Caling WINDOWS RUNTIME API untuk detail selengkapnya tentang menentukan properti <TargetFramework>.

• 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 informasi lebih lanjut, lihat panduan interop COM .

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

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

Kesalahan versi SDK .NET

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

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

Untuk memperbaiki kesalahan ini, perbarui SDK .NET 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 SDK .NET, karena perbaikan runtime mungkin memerlukan pembaruan untuk versi rakitan kami.

Masalah yang diketahui

Masalah yang diketahui dan perubahan yang memutus kompatibilitas dicatat dalam repositori C#/WinRT GitHub.

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

• C#/WinRT GitHub repo