You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Move nullable-migration-strategies to advanced-topics/update-applications
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.
Copy file name to clipboardExpand all lines: docs/csharp/advanced-topics/update-applications/nullable-migration-strategies.md
+9-9Lines changed: 9 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,9 +9,9 @@ ai-usage: ai-assisted
9
9
# Nullable migration strategies
10
10
11
11
> [!TIP]
12
-
> **Starting a new project?** New projects created from .NET 6 or later templates already have `<Nullable>enable</Nullable>` set. You don't need a migration strategy—skip to [Resolve nullable warnings](resolve-warnings.md).
12
+
> **Starting a new project?** New projects created from .NET 6 or later templates already have `<Nullable>enable</Nullable>` set. You don't need a migration strategy—skip to [Resolve nullable warnings](../../fundamentals/null-safety/resolve-warnings.md).
13
13
>
14
-
> **Maintaining an existing codebase?** Read [Nullable reference types](nullable-reference-types.md) first to understand contexts, annotations, and null-state. This article assumes you're familiar with those concepts and ready to plan a rollout.
14
+
> **Maintaining an existing codebase?** Read [Nullable reference types](../../fundamentals/null-safety/nullable-reference-types.md) first to understand contexts, annotations, and null-state. This article assumes you're familiar with those concepts and ready to plan a rollout.
15
15
16
16
When you turn on nullable reference types on a large project that started before nullable reference types were introduced, the compiler produces many warnings at once. Migration is about *sequencing* the work: choosing a default context, exposing warnings file by file or section by section, and converging on `<Nullable>enable</Nullable>` for the whole project. The right sequence depends on how active the codebase is and how much risk you can take in a single pass.
17
17
@@ -37,17 +37,17 @@ Pick the strategy that makes the next file you create do the right thing automat
37
37
38
38
Your project file controls the global default. The `#nullable` preprocessor directives override it locally:
The most predictable way to migrate a large project is to enable warnings or annotations file by file. The pattern is the same regardless of which default you pick:
47
47
48
48
1. Pick a file. Start with the deepest leaf types in your dependency graph, then move outward. Annotating a type causes new warnings in its callers, so working bottom-up minimizes rework.
49
49
1. Add the `#nullable` directive that opts the file into the new behavior. Use `#nullable enable` if you want both flags. Use `#nullable enable warnings` for warning-only.
50
-
1. Address the warnings in the file using the techniques in [Resolve nullable warnings](resolve-warnings.md).
50
+
1. Address the warnings in the file using the techniques in [Resolve nullable warnings](../../fundamentals/null-safety/resolve-warnings.md).
51
51
1. Repeat for the next file.
52
52
1. When every file in the project has its directive, remove the directives and set `<Nullable>enable</Nullable>` at the project level.
53
53
@@ -69,7 +69,7 @@ Lead with warnings when fixing latent <xref:System.NullReferenceException?displa
69
69
Lead with annotations when stabilizing the public API surface is the priority. This sequence suits libraries: you can ship annotated signatures so consumers see the right contracts, then close out the internal warnings on your own schedule.
70
70
71
71
1.**Phase 1 — Add annotations.** Set the project default to `annotations`. Reference types become non-nullable by default, but the compiler doesn't emit warnings, so the noise stays out of your way. Walk the public API and add `?` to every member that may legitimately return or accept `null`. Tighten the signatures that shouldn't. Because warnings are off, you can settle the API shape in focused commits without untangling the implementation at the same time.
72
-
1.**Phase 2 — Address warnings.** Switch the project default to `enable`. The annotations you added in phase 1 now feed null-state analysis, so the warnings the compiler emits are higher quality from the start—each one points at code whose behavior doesn't match the contract you already published. Resolve them with the techniques in [Resolve nullable warnings](resolve-warnings.md).
72
+
1.**Phase 2 — Address warnings.** Switch the project default to `enable`. The annotations you added in phase 1 now feed null-state analysis, so the warnings the compiler emits are higher quality from the start—each one points at code whose behavior doesn't match the contract you already published. Resolve them with the techniques in [Resolve nullable warnings](../../fundamentals/null-safety/resolve-warnings.md).
73
73
74
74
### Choosing between the orderings
75
75
@@ -94,11 +94,11 @@ After every file participates in the project default and the `<Nullable>enable</
94
94
- Remove `null!` and `default!` initializers that you added only to silence warnings during migration. Replace them with proper initialization, or change the member type to nullable.
95
95
- Spot-check the public API. Every member that returns or accepts `null` should be annotated with `?`. The annotations are part of your contract once the package ships.
96
96
97
-
You're now in the same state as new projects: nullable reference types are part of the type system, and any new warnings reflect a real mismatch between declarations and code. Use [Resolve nullable warnings](resolve-warnings.md) to address them as they come up.
97
+
You're now in the same state as new projects: nullable reference types are part of the type system, and any new warnings reflect a real mismatch between declarations and code. Use [Resolve nullable warnings](../../fundamentals/null-safety/resolve-warnings.md) to address them as they come up.
For migration approaches that enable the feature gradually, file by file or warning-only first. For more information on migration, see [Nullable migration strategies](migration-strategies.md).
32
+
For migration approaches that enable the feature gradually, file by file or warning-only first. For more information on migration, see [Nullable migration strategies](../../advanced-topics/update-applications/nullable-migration-strategies.md).
33
33
34
34
## Express intent with annotations
35
35
@@ -123,6 +123,6 @@ Initialize array elements as part of creating the array. [Collection expressions
123
123
124
124
-[Tutorial: Express your design intent with nullable and non-nullable reference types](../tutorials/nullable-reference-types.md)
The context has two independent flags. The *annotation* flag controls whether `?` and `!` are meaningful in declarations. The *warning* flag controls whether the compiler emits diagnostics. You can enable each independently. Enabling warnings while leaving annotations off lets you address null-handling bugs before you take on annotating types. Enabling annotations while leaving warnings off lets you express your design intent in the API surface without producing diagnostics in implementation code that isn't ready yet. Either combination can be the right choice for a project at a given stage. For the migration trade-offs, see [Nullable migration strategies](migration-strategies.md).
42
+
The context has two independent flags. The *annotation* flag controls whether `?` and `!` are meaningful in declarations. The *warning* flag controls whether the compiler emits diagnostics. You can enable each independently. Enabling warnings while leaving annotations off lets you address null-handling bugs before you take on annotating types. Enabling annotations while leaving warnings off lets you express your design intent in the API surface without producing diagnostics in implementation code that isn't ready yet. Either combination can be the right choice for a project at a given stage. For the migration trade-offs, see [Nullable migration strategies](../../advanced-topics/update-applications/nullable-migration-strategies.md).
43
43
44
44
## Add a null check
45
45
@@ -126,12 +126,12 @@ If a helper method initializes the member, annotate the helper with <xref:System
126
126
127
127
When a warning doesn't fit any of these patterns, the [Resolve nullable warnings](../../language-reference/compiler-messages/nullable-warnings.md) reference article lists the technique for every CS86xx warning the compiler emits.
128
128
129
-
To plan a migration that progressively enables nullable reference types in an existing codebase, see [Nullable migration strategies](migration-strategies.md).
129
+
To plan a migration that progressively enables nullable reference types in an existing codebase, see [Nullable migration strategies](../../advanced-topics/update-applications/nullable-migration-strategies.md).
Copy file name to clipboardExpand all lines: docs/csharp/language-reference/builtin-types/nullable-reference-types.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -70,7 +70,7 @@ The preceding examples demonstrate how compiler's static analysis determines the
70
70
71
71
## Setting the nullable context
72
72
73
-
You can control the nullable context in two ways. At the project level, add the `<Nullable>enable</Nullable>` project setting. In a single C# source file, add the `#nullable enable` pragma to enable the nullable context. See the article on [setting a nullable strategy](../../fundamentals/null-safety/migration-strategies.md). Before .NET 6, new projects use the default, `<Nullable>disable</Nullable>`. Beginning with .NET 6, new projects include the `<Nullable>enable</Nullable>` element in the project file.
73
+
You can control the nullable context in two ways. At the project level, add the `<Nullable>enable</Nullable>` project setting. In a single C# source file, add the `#nullable enable` pragma to enable the nullable context. See the article on [setting a nullable strategy](../../advanced-topics/update-applications/nullable-migration-strategies.md). Before .NET 6, new projects use the default, `<Nullable>disable</Nullable>`. Beginning with .NET 6, new projects include the `<Nullable>enable</Nullable>` element in the project file.
Copy file name to clipboardExpand all lines: docs/csharp/language-reference/compiler-messages/nullable-warnings.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -206,7 +206,7 @@ You address almost all warnings using one of five techniques:
206
206
- Adding attributes that describe null semantics.
207
207
- Initializing variables correctly.
208
208
209
-
If you're new to using nullable reference types, the [overview of nullable reference types](../../fundamentals/null-safety/nullable-reference-types.md) provides a background on what nullable reference types solve and how they work to provide warnings to possible mistakes in your code. You can also check the guidance on [migrating to nullable reference types](../../fundamentals/null-safety/migration-strategies.md) to learn more about enabling nullable reference types in an existing project.
209
+
If you're new to using nullable reference types, the [overview of nullable reference types](../../fundamentals/null-safety/nullable-reference-types.md) provides a background on what nullable reference types solve and how they work to provide warnings to possible mistakes in your code. You can also check the guidance on [migrating to nullable reference types](../../advanced-topics/update-applications/nullable-migration-strategies.md) to learn more about enabling nullable reference types in an existing project.
210
210
211
211
## Configure nullable context
212
212
@@ -241,7 +241,7 @@ The nullable context has two independent flags that control different aspects:
241
241
For detailed information about nullable contexts and migration strategies, see:
0 commit comments