Everyday C#: Null safety tutorials

[BillWagner]

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:

• docs/csharp/fundamentals/null-safety/nullable-reference-types.md
• docs/csharp/fundamentals/null-safety/resolve-warnings.md
• docs/csharp/advanced/update-applications/nullable-migration-strategies.md
• docs/csharp/fundamentals/null-safety/migration-strategies.md

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.md into two new fundamentals concept articles. Add redirects, update docs/csharp/toc.yml. Depends on PR 8 (#53509) landing the Null safety toc node first.

Phases

Phase 1 — Concept articles (parallel-safe)

1. fundamentals/null-safety/nullable-reference-types.md — apply template-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.
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. 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.
3. 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)

4. fundamentals/tutorials/nullable-reference-types.md — apply template-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)

5. 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.

Phase 4 — TOC + redirects + deletes (depends on Phases 1–3)

7. 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: 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-migration-strategies.md, docs/csharp/tutorials/nullable-reference-types.md.

Phase 5 — Cross-link cleanup (depends on Phase 4)

10. Repoint inbound links across docs/. Critical: docs/csharp/language-reference/compiler-messages/nullable-warnings.md has multiple links to moved files.

Verification

1. Each new snippet project builds: dotnet build; tutorial sample runs: dotnet run.
2. git grep -n "nullable-references.md\|nullable-migration-strategies.md\|tutorials/nullable-reference-types.md" returns 0 hits in docs/.
3. python -m json.tool .openpublishing.redirection.csharp.json validates JSON.
4. Visual confirmation of TOC ordering against project map.
5. Every new/edited article has ai-usage: ai-assisted; no F1/helpviewer keywords; 4-tier audience tip near top.
6. Spot-check 2–3 samples per article for Everyday C# saturation (file-scoped namespaces, primary constructors, collection expressions, raw strings, var).
7. After PR opens, resolve any OpenPublishing.Build warnings introduced.

Decisions

• Split confirmed: planning content → migration-strategies.md; address-warnings/contexts → resolve-warnings.md. Reference page stays untouched.
• resolve-warnings.md is concept-level (5 techniques) — does not duplicate the per-CS86xx catalog; cross-links to it.
• Move + revise in same PR per overall plan.
• ~14 files total — slightly above the ~10 guideline, acceptable per project guideline ("guideline, not a strict rule").

Further considerations

1. PR 8 merge ordering. Recommendation: wait for PR 8 to merge, then rebase PR 9 onto it (avoids toc conflicts). Alternative: include the Null safety toc node creation in PR 9 (would conflict with PR 8 at merge).
2. Snippet reuse. Recommendation: do NOT share with language-reference/compiler-messages/snippets/null-warnings/. Create fresh, smaller fundamentals-style snippets so reference vs. fundamentals can evolve independently.
3. Tutorial vs concept article overlap. Recommendation: trim concept-duplicating prose from the tutorial and add a short "Before you start, see Nullable reference types" pointer near the top.

---

Internal previews

Toggle expand/collapse

📄 File	🔗 Preview link
docs/core/compatibility/sdk/6.0/csharp-template-code.md	C# code in templates not supported by earlier versions
docs/core/extensions/windows-service.md	Create Windows Service using BackgroundService
docs/core/whats-new/dotnet-5.md	What's new in .NET 5
docs/core/whats-new/dotnet-core-3-0.md	What's new in .NET Core 3.0
docs/csharp/advanced-topics/update-applications/nullable-migration-strategies.md	Nullable migration strategies
docs/csharp/fundamentals/null-safety/index.md	docs/csharp/fundamentals/null-safety/index
docs/csharp/fundamentals/null-safety/null-operators.md	C# null operators
docs/csharp/fundamentals/null-safety/nullable-reference-types.md	Nullable reference types
docs/csharp/fundamentals/null-safety/nullable-value-types.md	Nullable value types: C# Fundamentals
docs/csharp/fundamentals/null-safety/resolve-warnings.md	Resolve nullable warnings
docs/csharp/fundamentals/tutorials/nullable-reference-types.md	Tutorial: Express your design intent with nullable and non-nullable reference types
docs/csharp/language-reference/attributes/nullable-analysis.md	docs/csharp/language-reference/attributes/nullable-analysis
docs/csharp/language-reference/builtin-types/arrays.md	Arrays
docs/csharp/language-reference/builtin-types/nullable-reference-types.md	"Nullable reference types"
docs/csharp/language-reference/compiler-messages/interface-implementation-errors.md	Resolve errors and warnings related to members that implement an interface
docs/csharp/language-reference/compiler-messages/nullable-warnings.md	Nullable reference type warnings
docs/csharp/language-reference/compiler-options/language.md	"Compiler Options - language feature rules"
docs/csharp/language-reference/keywords/where-generic-type-constraint.md	where (generic type constraint) (C# Reference)
docs/csharp/language-reference/operators/null-forgiving.md	docs/csharp/language-reference/operators/null-forgiving
docs/csharp/toc.yml	Taken from https://github.com/dotnet/roslyn/wiki/Samples-and-Walkthroughs
docs/csharp/tour-of-csharp/tips-for-java-developers.md	Tips for Java Developers
docs/csharp/tour-of-csharp/tips-for-javascript-developers.md	Roadmap for JavaScript and TypeScript developers learning C#
docs/csharp/tour-of-csharp/tips-for-python-developers.md	Python
docs/framework/debug-trace-profile/code-contracts.md	docs/framework/debug-trace-profile/code-contracts
docs/fundamentals/code-analysis/style-rules/ide0370.md	Remove unnecessary suppression (IDE0370)
docs/fundamentals/syslib-diagnostics/syslib1026.md	SYSLIB1026 error

[Copilot]

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.yml accordingly.
• 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.

[BillWagner]

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.