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 překážet 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ů s možnou hodnotou null. Zahrnuje statickou analýzu kompilátoru, hodnoty stavu null s hodnotou možná null a not-null a poznámky s možnou hodnotou null. 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 <nullable>Enable</nullable> v projektu nastavení. K úpravě nastavení jinde nebudete potřebovat žádné direktivy preprocesoru.

Poznámka:

Nastavení projektu můžete určit Nullable 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 tak, aby používala odkazové typy s možnou hodnotou null. 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 s možnou hodnotou null 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í s možnou hodnotou null 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 poznámky pro deklaraci očekávaného stavu null 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. Poznámky s možnou hodnotou null jako výchozí. Před vyřešením upozornění označte kód poznámkami.

Povolení hodnoty null, protože výchozí hodnota vytvoří více front-front work 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á práce bude mít hodnotu nullable; musí být aktualizován pouze existující kód. Zakázání hodnoty nullable jako výchozí funguje lépe, pokud je knihovna stabilní a hlavním cílem vývoje je přijmout odkazové typy s možnou hodnotou null. Při přidávání poznámek k rozhraním API zapnete odkazové typy s možnou hodnotou null. Po dokončení povolíte odkazové typy s možnou hodnotou null 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> komentář do horní části souboru nebo <auto-generated/> do komentáře. 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. Spusťte název souboru pomocí TemporaryGeneratedFile_
4. Ukončete název souboru .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í upozornění a poznámek určuje, jak kompilátor zobrazuje odkazové typy a možnosti null. Každý typ má jednu ze tří závazků null:

• Oblivious: Všechny odkazové typy jsou prázdné, pokud je kontext poznámek zakázán.
• nenulovatelný: Nenulovaný odkazový typ není možné zrušit, C pokud je povolen kontext poznámek.
• 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.
• Typy s možnou hodnotou null způsobují upozornění, pokud se při možné hodnotě null přepojí.
• Nečinné typy způsobují upozornění, pokud se přepojí, když je povolená hodnota null a kontext upozornění.

Každá proměnná má výchozí stav s možnou hodnotou null, který závisí na jeho možnosti null:

• Proměnné s možnou hodnotou null mají výchozí stav null s možnou hodnotou null.
• Proměnné bez hodnoty null mají výchozí stav null, který není null.
• Prázdné proměnné s možnou hodnotou null mají výchozí stav null not-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 not-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 nepozorné, ale když se hodnota změní na hodnotu null, zobrazí se upozornění, když se změní její stav null na hodnotu 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í upozornění s možnou 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 upozornění vygenerovaná, zatímco kontext je upozornění před povolením poznámek typu. Tímto způsobem jsou všechny typy nepochybné , dokud nezadáte první sadu upozornění.

Povolení poznámek k typům

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 možnou var hodnotou null. Tato změna často přináší nová upozornění. Prvním krokem při řešení upozornění kompilátoru je použití ? poznámek u parametru a návratových typů k označení, kdy mohou být nullargumenty 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 pro povolení projektu. Pokud jste do kódu přidali jakékoli pragmasy pro kontext upozornění nebo poznámku s možnou hodnotou null, 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 hodnoty nullable na nenulovatelné nebo nullable.

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