Memperbarui basis kode dengan jenis referensi nullable untuk memperbaiki peringatan diagnostik null

Jenis referensi yang dapat diubah ke null memungkinkan Anda untuk mendeklarasikan apakah variabel jenis referensi harus atau tidak seharusnya diberi nilai null. Manfaat paling penting dari fitur ini adalah analisis statik dan peringatan kompilator ketika kode Anda mungkin dereferensi null. Setelah diaktifkan, kompilator menghasilkan peringatan yang membantu Anda menghindari pelemparan System.NullReferenceException saat kode Anda berjalan.

Jika basis kode Anda relatif kecil, Anda dapat mengaktifkan fitur dalam proyek, mengatasi peringatan, dan menikmati manfaat diagnostik yang ditingkatkan. Basis kode yang lebih besar mungkin memerlukan pendekatan yang lebih terstruktur untuk mengatasi peringatan dari waktu ke waktu. Anda dapat mengaktifkan fitur ini untuk beberapa basis kode ketika Anda menangani peringatan dalam berbagai jenis atau file. Artikel ini menjelaskan berbagai strategi untuk memperbarui basis kode dan tradeoff yang terkait dengan strategi ini. Sebelum memulai migrasi Anda, baca gambaran umum konseptual jenis referensi yang dapat diubah ke null. Ini mencakup analisis statik kompilator, nilai null-state dari maybe-null dan not-null dan anotasi yang dapat diubah ke null. Setelah terbiasa dengan konsep dan istilah tersebut, Anda siap untuk memigrasikan kode Anda.

Rencanakan migrasi Anda

Terlepas dari bagaimana Anda memperbarui basis kode Anda, tujuannya adalah agar peringatan nullable dan anotasi nullable diaktifkan dalam proyek Anda. Setelah mencapai tujuan tersebut, Anda akan memiliki pengaturan <nullable>Enable</nullable> dalam proyek Anda. Anda tidak memerlukan arahan pra-prosessor apa pun untuk menyesuaikan pengaturan di tempat lain.

Catatan

Anda dapat menunjuk Nullable pengaturan untuk proyek Anda menggunakan <Nullable> tag. Lihat Opsi pengkompilasi untuk informasi selengkapnya.

Pilihan pertama adalah mengatur default untuk proyek. Pilihan Anda adalah:

1. Nullability dinonaktifkan secara default: Dinonaktifkan adalah default jika Anda tidak menambahkan elemen Nullable ke file proyek Anda. Menggunakan default ini saat Anda tidak secara aktif menambahkan file baru ke basis kode. Aktivitas utamanya adalah memperbarui pustaka untuk menggunakan jenis referensi nullabel. Menggunakan default ini berarti Anda menambahkan direktif preprocessor yang dapat bernilai null ke setiap file saat Anda memperbarui kodenya.
2. Pengaktifan Nullable sebagai default: Gunakan pengaturan default ini saat Anda sedang aktif mengembangkan fitur baru. Anda ingin semua kode baru memanfaatkan tipe referensi nullable dan analisis statis nullable. Menggunakan default ini berarti Anda harus menambahkan #nullable disable ke bagian atas setiap file. Anda akan menghapus direktif pra-prosesor ini saat Anda mengatasi peringatan di setiap file.
3. Peringatan yang dapat diubah ke null sebagai default: Pilih default ini untuk migrasi dua fase. Pada fase pertama, atasi peringatan. Pada fase kedua, aktifkan anotasi untuk mendeklarasikan null-state variabel yang diharapkan. Menggunakan default ini berarti Anda harus menambahkan #nullable disable ke bagian atas setiap file.
4. Anotasi yang dapat diubah ke null sebagai default. Anotasi kode sebelum mengatasi peringatan.

Mengaktifkan opsi nullable sebagai default memerlukan lebih banyak pekerjaan awal untuk menambahkan direktif pra-prosesor ke setiap file. Keuntungannya adalah setiap file kode baru di proyek akan diaktifkan untuk nullable. Pekerjaan baru akan menyadari tipe null; hanya kode yang sudah ada yang harus diperbarui. Menonaktifkan fitur nullable sebagai pengaturan default akan lebih efektif jika pustaka stabil, dan fokus utama pengembangan adalah mengadopsi tipe referensi nullable. Anda mengaktifkan jenis referensi yang dapat diubah ke null saat Anda membuat anotasi API. Setelah selesai, Anda mengaktifkan jenis referensi nullable untuk seluruh proyek. Saat membuat file baru, Anda harus menambahkan direktif pra-prosesor dan membuatnya dapat diubah ke null secara sadar. Jika ada pengembang di tim Anda yang lupa, kode baru itu sekarang berada di backlog pekerjaan untuk membuat semua kode dapat diubah ke null secara sadar.

Strategi mana yang Anda pilih tergantung pada seberapa banyak pengembangan aktif yang terjadi dalam proyek Anda. Semakin matang dan stabil proyek Anda, semakin baik strategi kedua. Semakin banyak fitur yang dikembangkan, semakin baik strategi pertama.

Penting

Konteks nullable global tidak berlaku untuk file kode yang dihasilkan. Di bawah salah satu strategi, konteks nullable dinonaktifkan untuk file sumber apa pun yang ditandai sebagai hasil generasi. Ini berarti API apa pun dalam file yang dihasilkan tidak dianotasi. Ada empat cara sebuah file diberi tanda sebagai hasil produksi:

1. Dalam .editorconfig, tentukan generated_code = true di bagian yang berlaku untuk file tersebut.
2. Memasukkan <auto-generated> atau <auto-generated/> pada komentar di bagian atas file. Ini bisa berada di baris mana pun dalam komentar itu, tetapi blok komentar harus menjadi elemen pertama dalam file.
3. Memulai nama file dengan TemporaryGeneratedFile_
4. Mengakhiri nama file dengan .designer.cs, .generated.cs, .g.cs, atau .g.i.cs.

Generator dapat ikut serta dengan menggunakan direktif pra-prosesor #nullable.

Memahami konteks dan peringatan

Mengaktifkan peringatan dan anotasi mengontrol bagaimana kompilator memandang jenis referensi dan keter-null-an. Setiap jenis memiliki salah satu dari tiga nullabilitas:

• oblivious: Semua jenis referensi dapat bernilai null oblivious saat konteks anotasi dinonaktifkan.
• nonnullable: Jenis referensi yang tidak diannotasi, C adalah nonnullable saat konteks anotasi diaktifkan.
• dapat diubah ke null: Jenis referensi anotasi, C?, adalah dapat diubah ke null, tetapi peringatan dapat dikeluarkan saat konteks anotasi dinonaktifkan. Variabel yang dideklarasikan dengan var adalah dapat diubah ke null saat konteks anotasi diaktifkan.

Kompilator menghasilkan peringatan berdasarkan sifat *nullability* tersebut:

• Jenis nonnullable akan memunculkan peringatan jika nilai potensial null ditetapkan untuknya.
• Jenis yang dapat bernilai null menyebabkan peringatan jika direferensikan ketika mungkin null.
• Jenis oblivious akan menyebabkan peringatan jika direferensikan ketika maybe-null dan konteks peringatan aktif.

Setiap variabel memiliki status nullable default yang bergantung pada nullability-nya:

• Variabel yang dapat bernilai null memiliki null-state default dari maybe-null.
• Variabel yang tidak dapat diubah ke null memiliki null-state default dari not-null.
• Variabel nullable oblivious memiliki default status null dari not-null.

Sebelum Anda mengaktifkan jenis referensi yang dapat diubah ke null, semua deklarasi dalam basis kode Anda adalah nullable oblivious. Ini penting karena itu berarti bahwa semua tipe referensi memiliki null-state default dari not-null.

Memberikan peringatan

Jika proyek Anda menggunakan Entity Framework Core, Anda harus membaca panduannya tentang Bekerja dengan jenis referensi yang dapat diubah ke null.

Saat memulai migrasi, Anda harus memulai dengan mengaktifkan peringatan saja. Semua deklarasi tetap nullable oblivious, tetapi Anda akan melihat peringatan saat Anda men-dereferensikan nilai setelah null-state nya berubah menjadi maybe-null. Saat Anda mengatasi peringatan ini, Anda akan memeriksa null di lebih banyak lokasi, dan basis kode Anda menjadi lebih tangguh. Untuk mempelajari teknik khusus untuk situasi yang berbeda, lihat artikel tentang Teknik untuk menyelesaikan peringatan nullable.

Anda dapat memberikan peringatan dan mengaktifkan anotasi di setiap file atau kelas sebelum melanjutkan dengan kode lain. Namun, sering kali lebih efisien untuk mengatasi peringatan yang dihasilkan saat konteksnya adalah peringatan sebelum mengaktifkan anotasi jenis. Dengan begitu, semua jenis diabaikan sampai Anda mengatasi serangkaian peringatan pertama.

Menambahkan anotasi jenis

Setelah mengatasi serangkaian peringatan pertama, Anda dapat mengaktifkan konteks anotasi. Ini mengubah jenis referensi dari tidak memerhatikan menjadi tidak dapat bernilai null. Semua variabel yang dideklarasikan dengan var adalah dapat diubah ke null. Perubahan ini sering memperkenalkan peringatan baru. Langkah pertama dalam mengatasi peringatan kompilator adalah menggunakan anotasi ? pada parameter dan jenis nilai yang dikembalikan untuk menunjukkan jika argumen atau nilai yang dikembalikan mungkin null. Saat Anda melakukan tugas ini, tujuan Anda bukan hanya untuk memperbaiki peringatan. Tujuan yang lebih penting adalah membuat kompilator memahami niat Anda untuk nilai null potensial.

Atribut memperluas anotasi jenis

Beberapa atribut telah ditambahkan untuk mengekspresikan informasi tambahan tentang variabel status null. Aturan untuk API Anda kemungkinan lebih rumit daripada not-null atau maybe-null untuk semua parameter dan nilai yang dikembalikan. Banyak API Anda memiliki aturan yang lebih kompleks tentang kapan variabel dapat atau tidak dapat null. Dalam kasus ini, Anda akan menggunakan atribut untuk mengekspresikan aturan tersebut. Atribut yang menjelaskan semantik API Anda ditemukan dalam artikel tentang Atribut yang memengaruhi analisis yang dapat diubah ke null.

Langkah berikutnya

Setelah Anda mengatasi semua peringatan setelah mengaktifkan anotasi, Anda dapat mengatur konteks default agar proyek Anda diaktifkan. Jika Anda menambahkan pragma apa pun dalam kode Anda untuk anotasi nullable atau konteks peringatan, Anda dapat menghapusnya. Seiring waktu, Anda mungkin melihat peringatan baru. Anda dapat menulis kode yang memperkenalkan peringatan. Dependensi pustaka mungkin diperbarui untuk jenis referensi yang dapat bernilai null. Pembaruan tersebut akan mengubah jenis di pustaka tersebut dari nullable oblivious menjadi nonnullable atau nullable.

Anda juga dapat menjelajahi konsep-konsep ini dalam modul Learn kami tentang keamanan Nullable di C#.