Everyday C#: Null safety tutorials#53542
Open
BillWagner wants to merge 13 commits into
Open
Conversation
BillWagner
force-pushed
the
null-safety-tutorials
branch
from
b9c933b to
13fb2be
Compare
Contributor
There was a problem hiding this comment.
Pull request overview
This PR restructures the C# nullable reference types (NRT) documentation into a Fundamentals “null safety” concept + tutorial set, moves/creates supporting snippet projects, and updates inbound links and TOC entries to point at the new locations.
Changes:
- Adds new Fundamentals null-safety concept articles (NRT overview, warning resolution, and migration strategies) plus a Fundamentals tutorial and snippet projects.
- Removes legacy C# NRT concept/tutorial pages and updates
docs/csharp/toc.ymlaccordingly. - Repoints links across C#, Core, Framework, and analyzer docs to the new Fundamentals URLs.
Reviewed changes
Copilot reviewed 39 out of 42 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/fundamentals/syslib-diagnostics/syslib1026.md | Updates NRT link target to the new Fundamentals article. |
| docs/fundamentals/code-analysis/style-rules/ide0370.md | Updates NRT link target to the new Fundamentals article. |
| docs/framework/debug-trace-profile/code-contracts.md | Updates guidance link to point at the new Fundamentals NRT article. |
| docs/csharp/tutorials/snippets/NullableIntroduction/SurveyQuestion.cs | Removes legacy tutorial snippet file as part of moving the tutorial snippets. |
| docs/csharp/tutorials/nullable-reference-types.md | Removes legacy tutorial page in favor of the new Fundamentals tutorial. |
| docs/csharp/tour-of-csharp/tips-for-python-developers.md | Repoints “Nullable types” link to the new Fundamentals NRT article. |
| docs/csharp/tour-of-csharp/tips-for-javascript-developers.md | Repoints nullable types link to the new Fundamentals NRT article. |
| docs/csharp/tour-of-csharp/tips-for-java-developers.md | Repoints nullable types links to the new Fundamentals NRT article. |
| docs/csharp/toc.yml | Removes legacy tutorial entry and adds a “Null safety” section pointing at new Fundamentals pages. |
| docs/csharp/nullable-references.md | Removes legacy NRT concept page replaced by Fundamentals content. |
| docs/csharp/nullable-migration-strategies.md | Removes legacy migration strategies page replaced by Fundamentals content. |
| docs/csharp/language-reference/operators/null-forgiving.md | Updates links to the new Fundamentals tutorial and NRT overview. |
| docs/csharp/language-reference/keywords/where-generic-type-constraint.md | Updates nullable context link to point at the new Fundamentals NRT overview. |
| docs/csharp/language-reference/compiler-options/language.md | Updates nullable contexts/migration links to new Fundamentals pages. |
| docs/csharp/language-reference/compiler-messages/nullable-warnings.md | Updates links to new Fundamentals NRT overview and migration page. |
| docs/csharp/language-reference/compiler-messages/interface-implementation-errors.md | Updates NRT link to the new Fundamentals NRT overview. |
| docs/csharp/language-reference/builtin-types/nullable-reference-types.md | Updates migration strategies link to new Fundamentals page. |
| docs/csharp/language-reference/builtin-types/arrays.md | Updates NRT links to the new Fundamentals NRT overview (including known pitfalls anchor). |
| docs/csharp/language-reference/attributes/nullable-analysis.md | Updates generics section link to the new Fundamentals NRT overview. |
| docs/csharp/fundamentals/tutorials/snippets/NullableIntroduction/SurveyRun.cs | Adds moved tutorial snippet code for SurveyRun. |
| docs/csharp/fundamentals/tutorials/snippets/NullableIntroduction/SurveyResponse.cs | Updates moved tutorial snippet code (uses primary constructor and snippet markers). |
| docs/csharp/fundamentals/tutorials/snippets/NullableIntroduction/SurveyQuestion.cs | Adds moved tutorial snippet code for SurveyQuestion. |
| docs/csharp/fundamentals/tutorials/snippets/NullableIntroduction/Program.cs | Adds moved tutorial snippet code for the top-level program and snippet markers. |
| docs/csharp/fundamentals/tutorials/snippets/NullableIntroduction/NullableIntroduction.csproj | Updates tutorial snippet project to net10.0. |
| docs/csharp/fundamentals/tutorials/nullable-reference-types.md | Adds new Fundamentals tutorial page for nullable reference types. |
| docs/csharp/fundamentals/null-safety/snippets/resolve-warnings/resolve-warnings.csproj | Adds new snippet project for the “Resolve warnings” article. |
| docs/csharp/fundamentals/null-safety/snippets/resolve-warnings/project-snippet.xml | Adds minimal XML snippet used to show <Nullable>enable</Nullable>. |
| docs/csharp/fundamentals/null-safety/snippets/resolve-warnings/Program.cs | Adds runnable examples backing the “Resolve warnings” article snippets. |
| docs/csharp/fundamentals/null-safety/snippets/nullable-reference-types/project-snippet.xml | Adds minimal XML snippet used to show <Nullable>enable</Nullable>. |
| docs/csharp/fundamentals/null-safety/snippets/nullable-reference-types/Program.cs | Adds runnable examples backing the “Nullable reference types” article snippets. |
| docs/csharp/fundamentals/null-safety/snippets/nullable-reference-types/nullable-reference-types.csproj | Adds new snippet project for the NRT overview article. |
| docs/csharp/fundamentals/null-safety/snippets/migration-strategies/project-snippet.xml | Adds minimal XML snippet for migration strategy examples. |
| docs/csharp/fundamentals/null-safety/snippets/migration-strategies/Program.cs | Adds runnable examples backing the migration strategies article snippets. |
| docs/csharp/fundamentals/null-safety/snippets/migration-strategies/migration-strategies.csproj | Adds new snippet project for the migration strategies article. |
| docs/csharp/fundamentals/null-safety/resolve-warnings.md | Adds new Fundamentals concept article describing warning-resolution techniques. |
| docs/csharp/fundamentals/null-safety/nullable-reference-types.md | Adds new Fundamentals concept article for nullable reference types. |
| docs/csharp/fundamentals/null-safety/migration-strategies.md | Adds new Fundamentals concept article for migration strategies. |
| docs/core/whats-new/dotnet-core-3-0.md | Updates tutorial link to the new Fundamentals tutorial location. |
| docs/core/whats-new/dotnet-5.md | Updates NRT link to the new Fundamentals NRT overview. |
| docs/core/extensions/windows-service.md | Updates NRT link to the new Fundamentals NRT overview. |
| docs/core/compatibility/sdk/6.0/csharp-template-code.md | Updates NRT link to the new Fundamentals NRT overview. |
1. `fundamentals/null-safety/nullable-reference-types.md` — apply `template-concept.md`. Body from [docs/csharp/nullable-references.md](docs/csharp/nullable-references.md), with conceptual prose lifted from the existing tutorial. 4-tier audience tip, `ms.topic: concept-article`, `ai-usage: ai-assisted`. All code via `:::code:::` snippet refs. 2. `fundamentals/null-safety/resolve-warnings.md` — concept article. Pull "Understand contexts and warnings" / "Address warnings" / "Enable type annotations" / "Attributes extend type annotations" sections from [docs/csharp/nullable-migration-strategies.md](docs/csharp/nullable-migration-strategies.md). Frame as **5 resolution techniques** with worked examples (NOT a per-CS86xx catalog). Cross-link to [docs/csharp/language-reference/compiler-messages/nullable-warnings.md](docs/csharp/language-reference/compiler-messages/nullable-warnings.md) for per-warning lookup. 3. `fundamentals/null-safety/migration-strategies.md` — concept article. Pull "Plan your migration" / "Next steps" / intro from [docs/csharp/nullable-migration-strategies.md](docs/csharp/nullable-migration-strategies.md). Cover the four default-context strategies and recommended phased order.
4. `fundamentals/tutorials/nullable-reference-types.md` — apply `template-tutorial.md`. Source: [docs/csharp/tutorials/nullable-reference-types.md](docs/csharp/tutorials/nullable-reference-types.md). Restructure to template (checklist, Prerequisites, numbered task H2s, "Get the code", "Next step"). Trim concept-duplicating prose; replace with cross-links.
. New snippet projects under `docs/csharp/fundamentals/null-safety/snippets/{nullable-reference-types,resolve-warnings,migration-strategies}/`. Each minimal `.csproj`, `<Nullable>enable</Nullable>`, latest TFM. Build + execute per docs `copilot-instructions.md`.
6. Move `docs/csharp/tutorials/snippets/NullableIntroduction/` → `docs/csharp/fundamentals/tutorials/snippets/NullableIntroduction/`. Update tutorial `:::code:::` source paths.
[docs/csharp/toc.yml](docs/csharp/toc.yml): remove lines 205–206 (legacy tutorial) and 293–296 (legacy concepts); add 4 new entries inside the `Null safety` node from PR 8. 8. [.openpublishing.redirection.csharp.json](.openpublishing.redirection.csharp.json): add 3 new redirects (alphabetical insertion); repoint existing redirects on lines 3126, 5389, 5447 (currently target `/dotnet/csharp/nullable-migration-strategies`) to new fundamentals URL to avoid chains. Run `sort-redirects` skill. 9. Delete [docs/csharp/nullable-references.md](docs/csharp/nullable-references.md), [docs/csharp/nullable-migration-strategies.md](docs/csharp/nullable-migration-strategies.md), [docs/csharp/tutorials/nullable-reference-types.md](docs/csharp/tutorials/nullable-reference-types.md).
***When reviewing commit-by-commit, this can be skimmed*** 10. Repoint inbound links across `docs/`. Critical: [docs/csharp/language-reference/compiler-messages/nullable-warnings.md](docs/csharp/language-reference/compiler-messages/nullable-warnings.md) has multiple links to moved files.
Review the drafts, make several changes in style, tone and substance.
…ions Relocate the migration article out of fundamentals/null-safety into a new Advanced topics > Update existing apps subsection. Rename to nullable-migration-strategies.md, repath snippets, update inbound links from sibling articles and language-reference, repoint redirects, and add a redirect from the vacated path.
BillWagner
force-pushed
the
null-safety-tutorials
branch
from
13fb2be to
08fa13e
Compare
Rename language-reference compiler-messages H1 'Resolve nullable warnings' to 'Nullable reference type warnings' to avoid collision with the new fundamentals article. Rename the H2 'Enable nullable reference types' to 'Nullable context' so existing inbound bookmarks #nullable-context resolve.
Member
Author
|
Note for reviewers: During a rebase, the redirection file got quite mangled. The diffs look better if you hide whitespace, but Copilot still decided to sort all the entries so the diffs are much larger than expected. I did verify the substantive changes by hand. |
adegeo
requested changes
May 13, 2026
| - *Null-state analysis* tracks whether the value of an expression is *not-null* or *maybe-null* at each point in your code. | ||
| - *Attributes* on APIs describe more nuanced contracts, such as "this argument can be `null`, but the return value is null only when the argument is null." | ||
|
|
||
| The compiler combines these signals to produce diagnostics. Warnings on a non-nullable variable mean the variable might receive `null`. Warnings on a nullable variable mean the code might *dereference* it without a null check. *Dereference* means to use the value the variable refers to—for example, to call a method on it (`variable.Method()`), read a property (`variable.Property`), or index into it (`variable[0]`). Dereferencing `null` throws an exception at run time. Either kind of warning means the code's behavior doesn't match its stated design. |
Contributor
There was a problem hiding this comment.
This could be slightly clearer for the new coder
Suggested change
| The compiler combines these signals to produce diagnostics. Warnings on a non-nullable variable mean the variable might receive `null`. Warnings on a nullable variable mean the code might *dereference* it without a null check. *Dereference* means to use the value the variable refers to—for example, to call a method on it (`variable.Method()`), read a property (`variable.Property`), or index into it (`variable[0]`). Dereferencing `null` throws an exception at run time. Either kind of warning means the code's behavior doesn't match its stated design. | |
| The compiler combines these signals to produce diagnostics. Warnings on a non-nullable variable mean the variable might receive `null`. Warnings on a nullable variable mean the code might *dereference* it without a null check. *Dereference* means to use the value the variable refers to—for example, to call a method on it (`variable.Method()`), read a property (`variable.Property`), or index into it (`variable[0]`). Dereferencing a variable that has a value of `null` throws an exception at run time. Either kind of warning means the code's behavior doesn't match its stated design. |
|
|
||
| ## Nullable context | ||
|
|
||
| For new projects targeting .NET 6 or later, the project template includes the `<Nullable>enable</Nullable>` element by default. To enable the feature in an existing project, add it manually: |
Contributor
There was a problem hiding this comment.
I wouldn't say this. .NET ships with a lot of templates and there is no guarantee that the code a user is looking at has this in the project. Further, projects migrated from .NET Framework won't have this enabled.
I would just say that if they're working with a newly created project, it's more than likely that nullable context is enabled in the project file with <Nullable>enable</Nullable>. And that if it's missing, it can be added manually...
|
|
||
| ## Express intent with annotations | ||
|
|
||
| When you enable the feature, every reference type variable is *non-nullable* by default. Append `?` to declare a *nullable* reference type: |
Contributor
There was a problem hiding this comment.
Nit:
Suggested change
| When you enable the feature, every reference type variable is *non-nullable* by default. Append `?` to declare a *nullable* reference type: | |
| When the feature is enabled, every reference type variable is *non-nullable* by default. Append `?` to declare a *nullable* reference type: |
|
|
||
| Use the annotation to make required and optional values visible in the type system. The following `Person` type declares `FirstName` and `LastName` as non-nullable—every person must have both—and `MiddleName` as nullable, because not everyone has one: | ||
|
|
||
| :::code language="csharp" source="snippets/nullable-reference-types/Program.cs" id="DesignIntent"::: |
Contributor
There was a problem hiding this comment.
Nit:
This code could be improved to show a second person without a middle name. Further, the output of the ToString should be printed as a comment at the end. That will really drive home the concept of how the null check changed the code path. Although that might not really be the focus of the code... So, total nit 😁
| - *not-null* — the expression is known to be not `null`. | ||
| - *maybe-null* — the expression might be `null`. | ||
|
|
||
| A local variable's null-state can change on any line of code. The rule is simple: after an assignment, the variable takes on the null-state of the expression on the right-hand side; after a check against `null`, the variable takes on the null-state implied by the branch you're in. For example, assigning a non-null literal or checking that a variable isn't `null` makes it *not-null*, while assigning `null`, the result of a method whose return type is nullable, or a variable that's currently *maybe-null* makes it *maybe-null*: |
Contributor
There was a problem hiding this comment.
For a "simple" rule, I find this entire paragraph very complex and verbose. I iterated with copilot to simplify the wording. How's this?
Suggested change
| A local variable's null-state can change on any line of code. The rule is simple: after an assignment, the variable takes on the null-state of the expression on the right-hand side; after a check against `null`, the variable takes on the null-state implied by the branch you're in. For example, assigning a non-null literal or checking that a variable isn't `null` makes it *not-null*, while assigning `null`, the result of a method whose return type is nullable, or a variable that's currently *maybe-null* makes it *maybe-null*: | |
| A local variable's null-state is updated as the compiler analyzes your code. Two things change it: **assignments** and **null checks**. After an assignment, the variable's null-state matches the expression on the right-hand side—if the expression is null or nullable, the variable becomes maybe-null; if the expression is a non-null literal, the variable becomes not-null. After a null check, the variable's null-state reflects whichever branch is taken.: |
|
|
||
| ## Generics | ||
|
|
||
| Generic type parameters without constraints can be reference types or value types, so `T?` follows different rules depending on the type argument: |
Contributor
There was a problem hiding this comment.
I think we should link to a generics overview. This is another feature of .NET that is interpreting things differently. If the user is unfamiliar with generics, they may want to know more before reading further.
Comment on lines
+90
to
+100
| - If `T` is a non-nullable reference type, `T?` is the corresponding nullable reference type. | ||
| - If `T` is a value type, `T?` is the same value type. (Add the `struct` constraint to get <xref:System.Nullable%601> behavior.) | ||
| - If `T` is already nullable, `T?` is the same type. | ||
|
|
||
| Constraints refine the rules: | ||
|
|
||
| - `class` requires a non-nullable reference type. | ||
| - `class?` allows either a nullable or a non-nullable reference type. | ||
| - `struct` requires a non-nullable value type. `T?` then means <xref:System.Nullable%601>. | ||
| - `notnull` requires a non-nullable reference or value type. | ||
| - A base class constraint such as `where T : BaseType` requires a non-nullable reference type that derives from `BaseType`. Append `?` (`where T : BaseType?`) to allow either a nullable or a non-nullable reference type. |
Contributor
There was a problem hiding this comment.
I find this very confusing because it's talking about the generic type passed and also the use of that generic type. Or is it? I'm not sure. It's not differentiating what it's talking about, so it makes it sound like the types used are declared as nullable or not-nullable, because when you use T it can be T or T?. So seeing T around is just confusing.
For example, on the first statement:
- If
Tis a non-nullable reference type,T?is the corresponding nullable reference type.
Is it talking about the T provided on the declaration? void Method<T>(). If so, how could it be a non-nullable reference type? All reference types are nullable, right? A string variable is always nullable because it's a reference type. It's the enablement of the nullability feature and declaration of the variable that give it a non-nullable characteristic, right?
|
|
||
| Two patterns can leave a non-nullable reference holding `null` without a warning. Both patterns are limitations of the static analysis, not bugs in your code. | ||
|
|
||
| **Default structs.** You can create a struct with non-nullable reference fields by using `default` or `new()`. This approach leaves the struct's fields uninitialized: |
Contributor
There was a problem hiding this comment.
I think this should be an H3 section
|
|
||
| The fields hold `null` at run time, but the compiler doesn't warn. The same pitfall extends to *arrays of structs*: a new array initializes every element to the struct's default value, so each element's non-nullable reference fields start as `null`. If you must use a struct, prefer [required members](../../language-reference/keywords/required.md) (members the caller must initialize through an object initializer) or a parameterized constructor that callers must invoke, and populate every element of any array you create. | ||
|
|
||
| **Arrays of references.** A new array of a non-nullable reference type contains all `null` elements until you assign each one: |
Contributor
There was a problem hiding this comment.
I think this should be an H3 section
|
|
||
| :::code language="csharp" source="snippets/nullable-reference-types/Program.cs" id="DefaultStructPitfall"::: | ||
|
|
||
| The fields hold `null` at run time, but the compiler doesn't warn. The same pitfall extends to *arrays of structs*: a new array initializes every element to the struct's default value, so each element's non-nullable reference fields start as `null`. If you must use a struct, prefer [required members](../../language-reference/keywords/required.md) (members the caller must initialize through an object initializer) or a parameterized constructor that callers must invoke, and populate every element of any array you create. |
Contributor
There was a problem hiding this comment.
This should be a new paragraph
Suggested change
| The fields hold `null` at run time, but the compiler doesn't warn. The same pitfall extends to *arrays of structs*: a new array initializes every element to the struct's default value, so each element's non-nullable reference fields start as `null`. If you must use a struct, prefer [required members](../../language-reference/keywords/required.md) (members the caller must initialize through an object initializer) or a parameterized constructor that callers must invoke, and populate every element of any array you create. | |
| The fields hold `null` at run time, but the compiler doesn't warn. | |
| The same pitfall extends to *arrays of structs*: a new array initializes every element to the struct's default value, so each element's non-nullable reference fields start as `null`. If you must use a struct, prefer [required members](../../language-reference/keywords/required.md) (members the caller must initialize through an object initializer) or a parameterized constructor that callers must invoke, and populate every element of any array you create. |
Also, I don't know how "required" could work? Does that force the user to create every element of the array at declaration?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #52838
If you review commit-by-commit, the 4th commit is updating links, and can be skimmed.
Note for reviewers
The following files had the major changes. Others were updating links:
Note that the migration strategies moved out from fundamentals. It's not meant for new C# developers.
Plan: PR 9 — Null safety: NRT, warnings, migration, tutorial
Consolidate the existing NRT concept article + tutorial into a fundamentals-style concept + tutorial pair, and split
nullable-migration-strategies.mdinto two new fundamentals concept articles. Add redirects, update docs/csharp/toc.yml. Depends on PR 8 (#53509) landing theNull safetytoc node first.Phases
Phase 1 — Concept articles (parallel-safe)
fundamentals/null-safety/nullable-reference-types.md— applytemplate-concept.md. Body from docs/csharp/nullable-references.md, with conceptual prose lifted from the existing tutorial. 4-tier audience tip,ms.topic: concept-article,ai-usage: ai-assisted. All code via:::code:::snippet refs.fundamentals/null-safety/resolve-warnings.md— concept article. Pull "Understand contexts and warnings" / "Address warnings" / "Enable type annotations" / "Attributes extend type annotations" sections from docs/csharp/nullable-migration-strategies.md. Frame as 5 resolution techniques with worked examples (NOT a per-CS86xx catalog). Cross-link to docs/csharp/language-reference/compiler-messages/nullable-warnings.md for per-warning lookup.fundamentals/null-safety/migration-strategies.md— concept article. Pull "Plan your migration" / "Next steps" / intro from docs/csharp/nullable-migration-strategies.md. Cover the four default-context strategies and recommended phased order.Phase 2 — Tutorial (depends on Phase 1 cross-links)
fundamentals/tutorials/nullable-reference-types.md— applytemplate-tutorial.md. Source: docs/csharp/tutorials/nullable-reference-types.md. Restructure to template (checklist, Prerequisites, numbered task H2s, "Get the code", "Next step"). Trim concept-duplicating prose; replace with cross-links.Phase 3 — Snippets (parallel-safe with Phases 1–2)
docs/csharp/fundamentals/null-safety/snippets/{nullable-reference-types,resolve-warnings,migration-strategies}/. Each minimal.csproj,<Nullable>enable</Nullable>, latest TFM. Build + execute per docscopilot-instructions.md.docs/csharp/tutorials/snippets/NullableIntroduction/→docs/csharp/fundamentals/tutorials/snippets/NullableIntroduction/. Update tutorial:::code:::source paths.Phase 4 — TOC + redirects + deletes (depends on Phases 1–3)
Null safetynode from PR 8./dotnet/csharp/nullable-migration-strategies) to new fundamentals URL to avoid chains. Runsort-redirectsskill.Phase 5 — Cross-link cleanup (depends on Phase 4)
docs/. Critical: docs/csharp/language-reference/compiler-messages/nullable-warnings.md has multiple links to moved files.Verification
dotnet build; tutorial sample runs:dotnet run.git grep -n "nullable-references.md\|nullable-migration-strategies.md\|tutorials/nullable-reference-types.md"returns 0 hits indocs/.python -m json.tool .openpublishing.redirection.csharp.jsonvalidates JSON.ai-usage: ai-assisted; no F1/helpviewer keywords; 4-tier audience tip near top.var).Decisions
migration-strategies.md; address-warnings/contexts →resolve-warnings.md. Reference page stays untouched.resolve-warnings.mdis concept-level (5 techniques) — does not duplicate the per-CS86xx catalog; cross-links to it.Further considerations
Null safetytoc node creation in PR 9 (would conflict with PR 8 at merge).language-reference/compiler-messages/snippets/null-warnings/. Create fresh, smaller fundamentals-style snippets so reference vs. fundamentals can evolve independently.Internal previews
Toggle expand/collapse