Bagikan melalui

C#/WinRT

  • Artikel

C#/WinRT adalah toolkit paket NuGet yang menyediakan dukungan proyeksi Windows Runtime (WinRT) untuk bahasa C#. Rakitan proyeksi adalah perakitan interop, yang memungkinkan pemrograman API WinRT dengan cara yang alami 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 dalam SDK Aplikasi Windows, termasuk WinUI 3. SDK Aplikasi Windows 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.

Yang baru

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

Penggunaan

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.

Mereferensikan perakitan 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 mereferensikan perakitan interop Windows SDK.

Jika Anda mendistribusikan komponen WinRT pihak ketiga tanpa perakitan interop resmi, proyek aplikasi dapat mengikuti prosedur untuk menghasilkan perakitan 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 yang disematkan 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 jenis Windows SDK 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++ asli harus mengatur properti Kompatibel Desktop Windows ke True baik melalui properti proyek atau .vcxproj file, untuk mereferensikan dan meneruskan biner Microsoft.VCLibs.Desktop ke mengonsumsi aplikasi. Jika tidak, paket Penerus VCRT akan diperlukan dengan menggunakan aplikasi jika komponen hanya menargetkan aplikasi UWP.

C#/WinRT juga menyediakan jalur fallback aktivasi jika Windows gagal mengaktifkan jenis 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 jenis 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 default ke TargetPlatformVersion, yang berasal dari versi Windows SDK yang ditentukan dalam TargetFramework properti .

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

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

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

    Lihat dokumen tentang Memanggil WINDOWS Runtime API untuk detail selengkapnya tentang menentukan <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 Alasan
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 di pustaka yang tidak mengekspos jenis Windows SDK.

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 umum

Masalah yang diketahui dan perubahan yang melanggar dicatat 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: