Memulai .NET Native

Penting

Modernisasi aplikasi UWP Anda dengan .NET dan Native AOT: Jika Anda mengembangkan aplikasi UWP baru atau ingin memodernisasi aplikasi UWP yang ada, sebaiknya gunakan dukungan UWP untuk .NET terbaru dengan Native AOT alih-alih .NET Native. Dukungan UWP untuk .NET modern sekarang tersedia secara umum dan merupakan jenis proyek default untuk aplikasi C# UWP di Visual Studio 2026. Ini menyediakan akses ke fitur .NET dan C# terbaru, dukungan alat dan debugging yang ditingkatkan, dan waktu build yang lebih cepat. .NET Native akan terus menerima perbaikan keamanan dan keandalan tetapi tidak akan menerima pembaruan fitur baru.

Baik Anda menulis aplikasi UWP baru atau memigrasikan aplikasi Windows 8.x yang ada (sebelumnya juga disebut aplikasi Microsoft Store), Anda dapat mengikuti serangkaian prosedur yang sama. Untuk membuat aplikasi .NET Native, ikuti langkah-langkah berikut:

  1. Kembangkan aplikasi Universal Windows Platform (UWP), dan uji build-debug aplikasi Anda untuk memastikan bahwa aplikasi berfungsi dengan baik.

  2. Menangani refleksi tambahan dan penggunaan serialisasi.

  3. Menyebarkan dan menguji build rilis aplikasi Anda.

  4. Atasi metadata yang hilang secara manual, dan ulangi langkah 3 hingga semua masalah diselesaikan.

Nota

Jika Anda memigrasikan aplikasi Windows 8.x yang ada ke .NET Native, pastikan untuk meninjau Migrating Aplikasi Windows 8.x Anda ke .NET Native.

Langkah 1: Mengembangkan dan menguji build debug aplikasi UWP Anda

Baik Anda mengembangkan aplikasi baru atau memigrasikan aplikasi yang sudah ada, Anda mengikuti proses yang sama seperti untuk aplikasi Windows apa pun.

  1. Buat proyek UWP baru di Visual Studio dengan menggunakan templat aplikasi Universal Windows untuk Visual C# atau Visual Basic. Secara default, semua aplikasi UWP menargetkan CoreCLR dan build rilisnya dikompilasi dengan menggunakan rantai alat .NET Native.

  2. Perhatikan bahwa ada beberapa masalah kompatibilitas yang diketahui antara mengkompilasi proyek aplikasi UWP dengan rantai alat .NET Native dan tanpanya. Lihat panduan migrasi untuk informasi selengkapnya.

Anda sekarang dapat menulis kode C# atau Visual Basic terhadap area permukaan asli .NET yang berjalan pada sistem lokal (atau di simulator).

Penting

Saat Anda mengembangkan aplikasi, perhatikan penggunaan serialisasi atau refleksi apa pun dalam kode Anda.

Secara default, build debug dikompilasi JIT untuk mengaktifkan penyebaran F5 yang cepat, sementara build rilis dikompilasi dengan menggunakan teknologi pra-kompilasi asli .NET. Ini berarti Anda harus membangun dan menguji build debug aplikasi Anda untuk memastikan bahwa mereka bekerja secara normal sebelum mengkompilasinya dengan rantai alat Native .NET.

Langkah 2: Menangani refleksi tambahan dan penggunaan serialisasi

File arahan runtime, Default.rd.xml, secara otomatis ditambahkan ke proyek Anda saat Anda membuatnya. Jika Anda mengembangkan di C#, itu dapat ditemukan di folder Properti proyek Anda. Jika Anda mengembangkan menggunakan Visual Basic, itu ditemukan di folder My Project proyek Anda.

Nota

Untuk gambaran umum proses kompilasi .NET Native yang menyediakan latar belakang mengapa file arahan runtime diperlukan, lihat .NET Native and Compilation.

File arahan runtime digunakan untuk menentukan metadata yang dibutuhkan aplikasi Anda pada waktu proses. Dalam beberapa kasus, versi default file mungkin memadai. Namun, beberapa kode yang bergantung pada serialisasi atau pantulan mungkin memerlukan entri tambahan dalam file arahan runtime.

Serialisasi

Ada dua kategori serializer, dan keduanya mungkin memerlukan entri tambahan dalam file arahan runtime:

  • Serializer yang tidak berbasis refleksi. Serializer yang ditemukan di pustaka kelas .NET Framework, seperti kelas DataContractSerializer, DataContractJsonSerializer, dan XmlSerializer, tidak bergantung pada refleksi. Namun, mereka mengharuskan kode dihasilkan berdasarkan objek untuk diserialisasi atau dideserialisasi. Untuk informasi selengkapnya, lihat bagian "Microsoft Serializer" di Serialisasi dan Metadata.

  • Serializer pihak ketiga. Pustaka serialisasi pihak ketiga, yang paling umum adalah serializer Newtonsoft JSON, umumnya berbasis refleksi dan memerlukan entri dalam file *.rd.xml untuk mendukung serialisasi objek dan deserialisasi. Untuk informasi selengkapnya, lihat bagian "Serializer Pihak Ketiga" di Serialisasi dan Metadata.

Metode yang mengandalkan refleksi

Dalam beberapa kasus, penggunaan refleksi dalam kode tidak jelas. Beberapa API umum atau pola pemrograman tidak dianggap sebagai bagian dari API refleksi tetapi mengandalkan refleksi untuk berhasil dijalankan. Ini termasuk jenis instansiasi dan metode konstruksi metode berikut:

Untuk informasi selengkapnya, lihat API yang Mengandalkan Refleksi.

Nota

Nama jenis yang digunakan dalam file arahan runtime harus sepenuhnya memenuhi syarat. Misalnya, file harus menentukan "System.String" alih-alih "String".

Langkah 3: Menyebarkan dan menguji build rilis aplikasi Anda

Setelah memperbarui file arahan runtime, Anda dapat membangun kembali dan menyebarkan build rilis aplikasi Anda. Biner .NET Native ditempatkan di subdirektori ILC.out dari direktori yang ditentukan dalam kotak teks Build output path pada kotak dialog Properties, tab Compile. Biner yang tidak ada di folder ini tidak dikompilasi dengan .NET Native. Uji aplikasi Anda secara menyeluruh, dan uji semua skenario, termasuk skenario kegagalan, pada setiap platform targetnya.

Jika aplikasi Anda tidak berfungsi dengan baik (terutama dalam kasus di mana aplikasi melemparkan pengecualian MissingMetadataException atau pengecualian MissingInteropDataException saat waktu proses), ikuti petunjuk di bagian selanjutnya, Langkah 4: Atasi metadata yang hilang secara manual. Mengaktifkan pengecualian kesempatan pertama dapat membantu Anda menemukan bug ini.

Setelah menguji dan men-debug build debug aplikasi Anda dan yakin telah menghilangkan pengecualian MissingMetadataException dan MissingInteropDataException, Anda harus menguji aplikasi sebagai aplikasi .NET Native yang dioptimalkan. Untuk melakukan ini, ubah konfigurasi proyek aktif Anda dari Debug menjadi Release.

Langkah 4: Mengatasi metadata yang hilang secara manual

Kegagalan paling umum yang akan Anda temui dengan .NET Native yang tidak Anda temui di desktop adalah runtime MissingMetadataException, MissingInteropDataException, atau KecualianMissingRuntimeArtifactException. Dalam beberapa kasus, tidak adanya metadata dapat memanifestasikan dirinya dalam perilaku yang tidak dapat diprediksi atau bahkan dalam kegagalan aplikasi. Bagian ini membahas bagaimana Anda dapat men-debug dan menyelesaikan pengecualian ini dengan menambahkan arahan ke file arahan runtime. Untuk informasi tentang format arahan waktu proses, lihat Arahan Waktu Proses (rd.xml) Referensi Berkas Konfigurasi. Setelah menambahkan arahan runtime, Anda harus menyebarkan dan menguji aplikasi Anda lagi dan menyelesaikan pengecualian baru MissingMetadataException, MissingInteropDataException, dan MissingRuntimeArtifactException sampai Anda tidak menemukan pengecualian lagi.

Petunjuk

Tentukan arahan runtime pada tingkat tinggi untuk memungkinkan aplikasi Anda tahan terhadap perubahan kode. Sebaiknya tambahkan arahan runtime di namespace dan tingkat tipe daripada tingkat anggota. Perhatikan bahwa mungkin ada kompromi antara ketahanan sistem dan file biner yang lebih besar dengan waktu kompilasi yang lebih lama.

Saat mengatasi pengecualian metadata yang hilang, pertimbangkan masalah ini:

  • Apa yang coba dilakukan aplikasi sebelum pengecualian?

    • Misalnya, apakah pengikatan data, men-serialisasi atau men-deserialisasi data, atau langsung menggunakan API refleksi?

  • Apakah ini kasus yang terisolasi, atau apakah Anda yakin akan mengalami masalah yang sama untuk jenis lain?

    • Misalnya, pengecualian MissingMetadataException dilemparkan saat menserialisasikan tipe dalam model objek aplikasi. Jika Anda mengetahui jenis lain yang akan diserialisasikan, Anda dapat menambahkan arahan runtime untuk jenis tersebut (atau untuk namespace yang menaungi jenis-jenis tersebut, tergantung pada seberapa baik pengorganisasian kode) pada saat yang sama.

  • Dapatkah Anda menulis ulang kode sehingga tidak menggunakan pantulan?

    • Misalnya, apakah kode menggunakan dynamic kata kunci saat Anda tahu jenis apa yang diharapkan?

    • Apakah kode memanggil metode yang bergantung pada pantulan ketika beberapa alternatif yang lebih baik tersedia?

Nota

Untuk informasi tambahan tentang penanganan masalah yang berasal dari perbedaan refleksi dan ketersediaan metadata di aplikasi desktop dan .NET Native, lihat APIs yang Mengandalkan Refleksi.

Untuk beberapa contoh spesifik penanganan pengecualian dan masalah lain yang terjadi saat menguji aplikasi Anda, lihat:

Lihat juga

  • Last updated on