BinaryFormatter panduan migrasi

2025-06-17

Perhatian

Kami sangat menyarankan untuk tidak menggunakan BinaryFormatter karena risiko keamanan terkait. Pengguna yang ada harus bermigrasi jauh dari BinaryFormatter.

Dimulai dengan .NET 9, kami tidak lagi menyertakan implementasi BinaryFormatter dalam runtime. API masih ada, tetapi implementasinya selalu melempar PlatformNotSupportedException, terlepas dari jenis proyek. Oleh karena itu, mengatur parameter kompatibilitas mundur yang ada tidak lagi memadai untuk menggunakan BinaryFormatter.

Anda memiliki dua opsi untuk mengatasinya:

Bermigrasi jauh dari BinaryFormatter. Kami sangat menyarankan Anda untuk menyelidiki opsi untuk berhenti menggunakan BinaryFormatter karena risiko keamanan terkait. Kami mencantumkan beberapa opsi di bawah ini.
Tetap gunakan BinaryFormatter. Jika Anda perlu terus menggunakan BinaryFormatter di .NET 9, Anda perlu bergantung pada System.Runtime yang tidak didukung.Serialization Memformat paket NuGet, yang menggantikan implementasi pelemparan.

Apa risiko dalam menggunakan BinaryFormatter?

Setiap deserializer, biner atau teks, yang memungkinkan inputnya untuk membawa informasi tentang objek yang akan dibuat adalah masalah keamanan yang menunggu untuk terjadi. Ada enumerasi kelemahan umum (CWE) yang menjelaskan masalah: CWE-502 "Deserialisasi Data Tidak Tepercaya". BinaryFormatter, termasuk dalam rilis awal .NET Framework pada tahun 2002, adalah *deserializer* (penyerialisasi ulang). Kami juga membahas ini dalam panduan keamanan BinaryFormater.

Karena risiko penggunaan BinaryFormatteryang diketahui , fungsionalitas dikecualikan dari .NET Core 1.0. Tetapi tanpa jalur migrasi yang jelas untuk menggunakan sesuatu yang lebih aman, permintaan pelanggan menyebabkan BinaryFormatter dimasukkan dalam .NET Core 2.0. Sejak itu, tim .NET telah berada di jalur untuk menghapus BinaryFormatter, secara perlahan menonaktifkannya secara default dalam beberapa jenis proyek tetapi memungkinkan konsumen ikut serta melalui bendera jika masih diperlukan untuk kompatibilitas mundur.

Untuk detail selengkapnya tentang keputusan, lihat BinaryFormatter sedang dihapus dalam pengumuman .NET 9 .

Jika Anda mengalami masalah terkait penghapusan BinaryFormatter yang belum diatasi dalam panduan migrasi ini, laporkan masalah tersebut pada github.com/dotnet/runtime dan tunjukkan bahwa masalah tersebut terkait dengan penghapusan BinaryFormatter.

Topik migrasi

Bermigrasi jauh dari BinaryFormatter biasanya berarti memilih serializer yang berbeda. Namun, itu biasanya hanya dapat dilakukan jika Anda mengontrol produsen dan konsumen data yang dikodekan. Jika Anda tidak mengontrol produsen, Anda juga dapat beralih ke API baru kami untuk membaca BinaryFormatter payload tanpa menggunakan salah satu jenis yang dikodekan.

Kedua opsi dieksplorasi di bawah ini.

Pilih serializer

Langkah pertama migrasi dari BinaryFormatter adalah memilih serializer untuk digunakan sebagai gantinya. Bergantung pada kebutuhan spesifik Anda, tim .NET merekomendasikan migrasi ke empat serializer yang berbeda.

Membaca BinaryFormatter payload (NRBF)

Banyak aplikasi memuat dan mendeserialisasi payload yang telah disimpan ke dalam penyimpanan, dan tidak selalu mungkin untuk mengubah semua payload yang sudah disimpan secara langsung. Skenario lain dapat melibatkan sistem atau layanan yang menerima data yang dihasilkan oleh BinaryFormatter, di mana sistem ini perlu dimigrasikan secara independen.

Dalam skenario ini dan lainnya, perlu untuk mempertahankan dukungan untuk membaca payload yang disediakan serta beralih ke format baru secara bertahap. Untuk memenuhi kebutuhan ini, sekarang dimungkinkan untuk membaca payload NRBF yang dibuat dengan BinaryFormatter dengan aman tanpa melakukan deserialisasi yang bersifat tujuan umum dan rentan.

Memigrasikan aplikasi Windows Forms dan WPF

Aplikasi Windows Forms dan WPF mungkin memerlukan perubahan tambahan. Lihat aplikasi Windows Forms, aplikasi WPF, dan clipboard WinForms/WPF dan panduan seret dan letakkan untuk panduan migrasi lebih lanjut.

Memigrasikan sumber daya terkelola (ResX)

Jenis sumber daya yang paling umum (seperti string dan ikon) akan berfungsi tanpa BinaryFormatter. Untuk jenis kustom, Anda perlu menggunakan BinaryFormatter dan mengaktifkan sakelar kompatibilitas, lihat Memuat sumber daya saat runtime.

Menggunakan paket kompatibilitas

Untuk skenario di mana migrasi menjauh dari BinaryFormatter tidak dapat dilakukan pada saat peningkatan ke .NET 9, paket kompatibilitas yang tidak didukung tersedia. System.Runtime.Serialization. Paket Formatters NuGet berisi implementasi yang berfungsi dari BinaryFormatter, termasuk kerentanan dan risikonya.

Meskipun tidak didukung dan tidak direkomendasikan, panduan untuk menggunakan paket kompatibilitas mencakup detail untuk menginstal paket dan mengaktifkan fungsionalitas.