Memperbarui basis kode dengan jenis referensi dapat diubah ke null untuk meningkatkan peringatan diagnostik null

Artikel
04/07/2023

Jenis referensi yang dapat diubah ke null memungkinkan Anda untuk mendeklarasikan apakah variabel jenis referensi harus atau tidak seharusnya diberi nilai null. Analisis statik dan peringatan kompilator ketika kode Anda mungkin dereferensi null adalah keuntungan terpenting dari fitur ini. 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, memungkinkan fitur untuk beberapa saat Anda mengatasi 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 bahwa peringatan yang dapat diubah ke null dan anotasi yang dapat diubah ke null 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.

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

Penonaktifan yang dapat diubah ke null sebagai default: nonaktifkan 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 yang dapat diubah ke null. Menggunakan default ini berarti Anda menambahkan direktif preproscessor nullable ke setiap file saat Anda memperbarui kodenya.
Dapat diubah ke null diaktifkan sebagai default: Mengatur default ini saat Anda secara aktif mengembangkan fitur baru. Anda ingin semua kode baru mendapat manfaat dari jenis 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.
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.
Anotasi yang dapat diubah ke null sebagai default. Anotasi kode sebelum mengatasi peringatan.

Mengaktifkan yang dapat diubah ke null karena default membuat lebih banyak pekerjaan di muka untuk menambahkan direktif pra-prosesor ke setiap file. Keuntungannya adalah bahwa setiap file kode baru yang ditambahkan ke proyek akan diaktifkan pada yang dapat diubah ke null. Setiap pekerjaan baru akan dapat diubah ke null dengan sadar; hanya kode yang ada yang harus diperbarui. Menonaktifkan yang dapat diubah ke null karena default berfungsi lebih baik jika pustaka stabil, dan fokus utama pengembangan adalah mengadopsi jenis referensi yang dapat diubah ke null. Anda mengaktifkan jenis referensi yang dapat diubah ke null saat Anda membuat anotasi API. Setelah selesai, Anda mengaktifkan jenis referensi yang dapat diubah ke null 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 global yang dapat diubah ke null tidak berlaku untuk file kode yang dihasilkan. Di bawah salah satu strategi, konteks yang dapat diubah ke null dinonaktifkan untuk file sumber apa pun yang ditandai sebagai dihasilkan. Ini berarti API apa pun dalam file yang dihasilkan tidak dianotasi. Ada empat cara file ditandai sebagai dihasilkan:

Dalam .editorconfig, tentukan generated_code = true di bagian yang berlaku untuk file tersebut.
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.
Memulai nama file dengan TemporaryGeneratedFile_
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 jenis referensi tampilan kompilator dan kemampuan null. Setiap jenis memiliki salah satu dari tiga nullabilitas:

oblivious: Semua jenis referensi dapat diubah ke null tidak menyadari null 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 nullability tersebut:

Jenis nonnullable menyebabkan peringatan jika nilai null potensial ditetapkan untuknya.
Jenis yang dapat diubah ke null menyebabkan peringatan jika mereka men-dereferensi ketika maybe-null.
Jenis oblivious menyebabkan peringatan jika mereka di-dereferensi ketika maybe-null dan konteks peringatan diaktifkan.

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

Variabel yang dapat diubah ke null memiliki null-state default dari maybe-null.
Variabel yang tidak dapat diubah ke null memiliki null-state default dari not-null.
Variabel yang terlupa tidak dapat diubah ke null memiliki null-state default dari not-null.

Sebelum Anda mengaktifkan jenis referensi yang dapat diubah ke null, semua deklarasi dalam basis kode Anda adalah nullable oblivious. Hal itu penting karena itu berarti semua jenis 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 mengatasi peringatan yang dapat diubah ke null.

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 tidak sadar sampai Anda mengatasi serangkaian peringatan pertama.

Menambahkan anotasi jenis

Setelah memberikan serangkaian peringatan pertama, Anda dapat mengaktifkan konteks anotasi. Ini mengubah jenis referensi dari tidak sadar menjadi tidak dapat diubah ke null. Semua variabel yang dideklarasikan dengan var adalah dapat diubah ke null. Perubahan ini sering memperkenalkan peringatan baru. Langkah pertama dalam memberikan peringatan kompilator adalah menggunakan anotasi ? pada parameter dan mengembalikan jenis untuk menunjukkan kapan 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 ketika variabel dapat atau tidak bisa 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 atau konteks peringatan yang dapat diubah ke null, Anda dapat menghapusnya. Seiring waktu, Anda mungkin melihat peringatan baru. Anda dapat menulis kode yang memperkenalkan peringatan. Dependensi pustaka dapat diperbarui untuk jenis referensi yang dapat diubah ke null. Pembaruan tersebut akan mengubah jenis di pustaka tersebut dari nullable oblivious menjadi nonnullable atau tidak dapat diubah ke null.

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

Bagikan melalui