Aktualizace základu kódu s odkazovými typy s možnou hodnotou null za účelem zlepšení upozornění diagnostiky s hodnotou null

Odkazové typy s možnou hodnotou null umožňují deklarovat, jestli by proměnné typu odkazu měly nebo neměly být přiřazeny hodnotě null . Nejdůležitější výhodou této funkce je statická analýza a upozornění kompilátoru, když váš kód může dereferencovat null. Po povolení kompilátor vygeneruje upozornění, která vám pomohou vyhnout se vyvolání System.NullReferenceException při spuštění kódu.

Pokud je základ kódu relativně malý, můžete funkci v projektu zapnout, řešit upozornění a využívat výhody vylepšené diagnostiky. Větší základ kódu může vyžadovat strukturovanější přístup k řešení upozornění v průběhu času a povolit funkci pro některé z nich, když řešíte upozornění v různých typech nebo souborech. Tento článek popisuje různé strategie aktualizace základu kódu a kompromisů spojených s těmito strategiemi. Před zahájením migrace si přečtěte koncepční přehled typů odkazů typu nullable. Zahrnuje statickou analýzu kompilátoru, stav nulových hodnot u možná null a ne-null a anotace ukazující možnost null hodnoty. Jakmile tyto koncepty a termíny znáte, můžete svůj kód migrovat.

Naplánujte si migraci

Cílem bez ohledu na to, jak aktualizujete základ kódu, je, že v projektu jsou povolena upozornění s možnou hodnotou null a poznámky s možnou hodnotou null. Jakmile dosáhnete tohoto cíle, budete mít nastavení <nullable>Enable</nullable> ve svém projektu. K úpravě nastavení jinde nebudete potřebovat žádné direktivy preprocesoru.

Poznámka:

Můžete nastavit Nullable pro svůj projekt pomocí značky <Nullable>. Další informace najdete v možnostech kompilátoru.

První volbou je nastavení výchozího nastavení projektu. Na výběr máte:

1. Zákaz s možnou hodnotou Null jako výchozí: Zakázat je výchozí, pokud do souboru projektu nepřidáte Nullable prvek. Toto výchozí nastavení použijte, když do základu kódu aktivně nepřidáte nové soubory. Hlavní aktivitou je aktualizace knihovny, aby používala nullable reference types. Použití tohoto výchozího nastavení znamená, že při aktualizaci kódu přidáte do každého souboru direktivu preprocesoru s možnou hodnotou null.
2. Povolit Nullable jako výchozí: Nastavte toto výchozí nastavení při aktivním vývoji nových funkcí. Chcete, aby všechny nové kódy využívaly odkazové typy s možnou hodnotou null a statickou analýzu s možnou hodnotou null. Použití tohoto výchozího nastavení znamená, že musíte přidat #nullable disable na začátek každého souboru. Tyto direktivy preprocesoru odeberete při řešení upozornění v každém souboru.
3. Upozornění na nulovatelnost jako výchozí: Zvolte toto výchozí nastavení pro dvoufázovou migraci. V první fázi adresujte upozornění. Ve druhé fázi zapněte anotace pro deklaraci očekávaného null-stavu proměnné. Použití tohoto výchozího nastavení znamená, že musíte přidat #nullable disable na začátek každého souboru.
4. Anotace s podporou nullových hodnot jako výchozí. Před vyřešením upozornění označte kód poznámkami.

Povolení nullability jako výchozí vytvoří více práce na začátku pro přidání direktiv preprocesoru do každého souboru. Výhodou je, že každý nový soubor kódu přidaný do projektu bude mít povolenou hodnotu null. Každý nový kód bude zohledňovat nullable; pouze stávající kód musí být aktualizován. Zakázání explicitní nullovatelnosti jako výchozího nastavení funguje lépe, pokud je knihovna stabilní a hlavním cílem vývoje je přijmout nullable reference types. Při anotaci rozhraní API povolíte odkazové typy s možnou hodnotou null. Po dokončení povolíte nulovatelné odkazové typy pro celý projekt. Při vytváření nového souboru je nutné přidat direktivy preprocesoru a zajistit, aby měl hodnotu nullable. Pokud některý z vývojářů ve vašem týmu zapomene, bude nový kód nyní v backlogu práce, aby se všechny kódy s možnou hodnotou null dozvěděly.

Která z těchto strategií závisí na tom, kolik aktivního vývoje se ve vašem projektu provádí. Čím je váš projekt vyspělejší a stabilní, tím lepší druhá strategie. Čím více funkcí se vyvíjí, tím lepší je první strategie.

Důležité

Globální kontext s možnou hodnotou null se nevztahuje na vygenerované soubory kódu. V obou strategiích je kontext s možnou hodnotou null zakázán pro jakýkoli zdrojový soubor označený jako vygenerovaný. To znamená, že žádná rozhraní API ve vygenerovaných souborech nejsou opatřena poznámkami. Soubor je označený jako vygenerovaný čtyřmi způsoby:

1. V souboru .editorconfig zadejte generated_code = true v oddílu, který se vztahuje na tento soubor.
2. Umístěte <auto-generated> nebo <auto-generated/> jako komentář na začátek souboru. Může být na libovolném řádku v daném komentáři, ale blok komentáře musí být prvním prvkem v souboru.
3. Začněte název souboru textem TemporaryGeneratedFile_
4. Ukončete název souboru jako .designer.cs, .generated.cs, .g.cs nebo .g.i.cs.

Generátory se můžou přihlásit pomocí direktivy preprocesoru #nullable .

Vysvětlení kontextů a upozornění

Povolení varování a anotací ovlivňuje, jak kompilátor nahlíží na referenční typy a možnost nulové hodnoty. Každý typ má jednu ze tří nullovatelností:

• Oblivious: Všechny odkazové typy jsou prázdné, pokud je kontext poznámek zakázán.
• nenulovatelný: Odkazový typ bez poznámky je C nenulovatelný, pokud je povolen kontext anotací.
• nullable: Typ odkazu s poznámkami, C?je nullable, ale upozornění může být vydáno, pokud je kontext poznámky zakázán. Proměnné deklarované pomocí var mají hodnotu null , pokud je povolen kontext poznámek.

Kompilátor generuje upozornění na základě této možnosti null:

• Nenulovatelné typy způsobují upozornění, pokud je k nim přiřazena potenciální null hodnota.
• Nullable typy způsobují upozornění, pokud jsou dereferencovány, když jsou možná null.
• Oblivious typy způsobují upozornění, pokud se dereferencují, když jsou možná null a je povolen kontext upozornění.

Každá proměnná má výchozí stav nulovatelnosti, který závisí na její nulovatelnosti.

• Proměnné typu nullable mají výchozí stavmožná-null.
• Proměnné, které nemohou obsahovat hodnotu null, mají výchozí stav nullnení null.
• Proměnné s neznámou hodnotou null mají výchozí stav null jako není null.

Než povolíte odkazové typy s možnou hodnotou null, budou všechny deklarace v základu kódu neplatné. To je důležité, protože všechny odkazové typy mají výchozí stav null, který je ne-null.

Upozornění na adresu

Pokud váš projekt používá Entity Framework Core, měli byste si přečíst pokyny k práci s odkazovými typy s možnou hodnotou null.

Při spuštění migrace byste měli začít tím, že povolíte jenom upozornění. Všechny deklarace zůstanou nullable oblivious, ale zobrazí se upozornění, když dereferencujete hodnotu poté, co se její null-stav změní na možná-null. Při řešení těchto upozornění budete kontrolovat hodnotu null ve více umístěních a základ kódu bude odolnější. Pokud se chcete dozvědět konkrétní techniky pro různé situace, přečtěte si článek o technikách řešení varování z hodnotou null.

Před pokračováním v jiném kódu můžete řešit upozornění a povolit poznámky v každém souboru nebo třídě. Často je ale efektivnější řešit vygenerovaná upozornění, když je kontext warnings, před povolením poznámek typu. Tímto způsobem jsou všechny typy lhostejné, dokud neřešíte první sadu upozornění.

Povolení typových poznámek

Po vyřešení první sady upozornění můžete kontext poznámek povolit. Tím se změní odkazové typy z nenulovatelné na nenulovatelné. Všechny proměnné deklarované s var jsou nulovatelné. Tato změna často přináší nová upozornění. Prvním krokem při řešení upozornění kompilátoru je použití ? poznámky u parametru a návratových typů k označení, kdy mohou být null argumenty nebo návratové hodnoty. Při tomto úkolu není vaším cílem pouze opravit upozornění. Důležitějším cílem je, aby kompilátor rozuměl vašemu záměru potenciálních hodnot null.

Atributy rozšiřují poznámky k typům

Bylo přidáno několik atributů k vyjádření dalších informací o stavu null proměnných. Pravidla pro vaše rozhraní API jsou pravděpodobně složitější než nenulová nebo možná null pro všechny parametry a návratové hodnoty. Mnoho z vašich rozhraní API má složitější pravidla pro to, kdy proměnné mohou nebo nemohou být null. V těchto případech použijete atributy k vyjádření těchto pravidel. Atributy, které popisují sémantiku vašeho rozhraní API, najdete v článku o atributech, které ovlivňují analýzu s možnou hodnotou null.

Další kroky

Jakmile po povolení poznámek vyřešíte všechna upozornění, můžete nastavit výchozí kontext svého projektu na povoleno. Pokud jste do kódu přidali jakákoli pragmata pro anulovatelné anotace nebo kontext upozornění, můžete je odebrat. V průběhu času se můžou zobrazovat nová upozornění. Můžete napsat kód, který zavádí upozornění. Závislost knihovny může být aktualizována pro odkazové typy s možnou hodnotou null. Tyto aktualizace změní typy v této knihovně z zřejmě nullable na nenulovatelné nebo nulovatelné.

Tyto koncepty můžete prozkoumat také v našem modulu Learn o bezpečnosti s možnou hodnotou Null v jazyce C#.