Update tutorials and program guide for modern extensions #50132
Conversation
Update the sample code and snippet tags for the LINQ tutorial missed one edit. fix build
BillWagner
force-pushed
the
extensions-tutorial-linq
branch
from
f14cd92 to
ed1fa8a
Compare
BillWagner
force-pushed
the
extensions-tutorial-linq
branch
from
eccb2f5 to
c0562e8
Compare
BillWagner
force-pushed
the
extensions-tutorial-linq
branch
from
c0562e8 to
b8fcd03
Compare
|
I marked this as ready, and changed from "fixes" to "contributes to". The one folder remaining is the LINQ section, which will have quite a few changes. Splitting to make reviews a bit easier. |
There was a problem hiding this comment.
Pull request overview
This pull request modernizes the LINQ tutorial and programming guide for C# extension members. The primary focus is updating the sample code to use the modern extension syntax introduced in C# 14, along with editorial improvements to align with documentation style guidelines.
Key changes:
- Updates the LINQ tutorial with modernized extension member syntax and improved editorial clarity
- Reorganizes the table of contents to elevate "Extension members" to a top-level section
- Updates project files to target .NET 10.0 (net10.0)
Reviewed changes
Copilot reviewed 16 out of 17 changed files in this pull request and generated 10 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/csharp/tutorials/working-with-linq.md | Updated LINQ tutorial with editorial improvements, modernized terminology, and corrected date/metadata |
| docs/csharp/tutorials/snippets/console-linq/Program.cs | New main program file using modern extension syntax and updated enum-based card deck |
| docs/csharp/tutorials/snippets/console-linq/extensions.cs | Refactored to use modern extension container syntax instead of traditional static extension methods |
| docs/csharp/tutorials/snippets/console-linq/InterimSteps.cs | New file containing tutorial step-by-step code snippets for progressive learning |
| docs/csharp/tutorials/snippets/console-linq/playingcard.cs | Modernized to use record type with sealed modifier |
| docs/csharp/tutorials/snippets/console-linq/README.md | New README documenting the sample project |
| docs/csharp/tutorials/snippets/console-linq/LInqFaroShuffle.csproj | Updated to target net10.0 with ImplicitUsings enabled |
| docs/csharp/programming-guide/generics/snippets/GenericWhereConstraints.cs | Updated extension method examples to use modern extension syntax |
| docs/csharp/programming-guide/generics/snippets/generics.csproj | Updated to target net10.0 |
| docs/csharp/programming-guide/classes-and-structs/snippets/how-to-implement-and-call-a-custom-extension-method/Program.cs | Refactored to demonstrate modern extension member syntax |
| docs/csharp/programming-guide/classes-and-structs/snippets/how-to-implement-and-call-a-custom-extension-method/how-to-implement-and-call-a-custom-extension-method.csproj | Updated to target net10.0 |
| docs/csharp/programming-guide/classes-and-structs/how-to-use-implicitly-typed-local-variables-and-arrays-in-a-query-expression.md | Updated cross-reference from "Extension Methods" to "Extension members" |
| docs/csharp/programming-guide/classes-and-structs/how-to-create-a-new-method-for-an-enumeration.md | Updated date metadata |
| docs/csharp/programming-guide/generics/constraints-on-type-parameters.md | Updated date metadata |
| docs/csharp/toc.yml | Reorganized to promote "Extension members" to a top-level section under "Classes, Structs, and Records" |
| samples/snippets/csharp/getting-started/console-linq/playingcard.cs | Removed old file (replaced by tutorial snippets version) |
| samples/snippets/csharp/getting-started/console-linq/Program.cs | Removed old file (replaced by tutorial snippets version) |
| - Using LINQ queries to aggregate data into a meaningful sequence. | ||
| - Writing extension methods to add custom functionality to LINQ queries. | ||
| - Locating areas in code where LINQ queries might run into performance issues like degraded speed. | ||
| - Lazy and eager evaluation in LINQ queries and the implications they might have on query performance. |
There was a problem hiding this comment.
The list items in the conclusion section need periods. According to the documentation style guidelines, list items with more than three words must end with periods.
Suggestion:
- Using LINQ queries to aggregate data into a meaningful sequence.
- Writing extension methods to add custom functionality to LINQ queries.
- Locating areas in code where LINQ queries might run into performance issues like degraded speed.
- Lazy and eager evaluation in LINQ queries and the implications they might have on query performance.| - Generate sequences with LINQ. | ||
| - Write methods that can be easily used in LINQ queries. | ||
| - Write methods that you can easily use in LINQ queries. | ||
| - Distinguish between eager and lazy evaluation. |
There was a problem hiding this comment.
These list items need periods according to the documentation style guidelines. List items with more than three words must end with periods.
Suggestion:
- Generate sequences with LINQ.
- Write methods that you can easily use in LINQ queries.
- Distinguish between eager and lazy evaluation.| - [Introduction to LINQ](../linq/index.md) | ||
| - [Basic LINQ Query Operations (C#)](../linq/standard-query-operators/index.md) | ||
| - [Data Transformations With LINQ (C#)](../linq/standard-query-operators/index.md) | ||
| - [Query Syntax and Method Syntax in LINQ (C#)](../linq/get-started/write-linq-queries.md) | ||
| - [C# Features That Support LINQ](../linq/get-started/features-that-support-linq.md) | ||
| - [Basic LINQ query operations (C#)](../linq/standard-query-operators/index.md) | ||
| - [Data transformations with LINQ (C#)](../linq/standard-query-operators/index.md) | ||
| - [Query syntax and method syntax in LINQ (C#)](../linq/get-started/write-linq-queries.md) | ||
| - [C# features that support LINQ](../linq/get-started/features-that-support-linq.md) |
There was a problem hiding this comment.
According to the documentation style guidelines, titles should use sentence case (capitalize only first word and proper nouns). The link text should match the actual article titles.
Suggestion:
- [Introduction to LINQ](../linq/index.md)
- [Basic LINQ query operations (C#)](../linq/standard-query-operators/index.md)
- [Data transformations with LINQ (C#)](../linq/standard-query-operators/index.md)
- [Query syntax and method syntax in LINQ (C#)](../linq/get-started/write-linq-queries.md)
- [C# features that support LINQ](../linq/get-started/features-that-support-linq.md)| // <StepTwo> | ||
| var startingDeck = from s in Suits() | ||
| from r in Ranks() | ||
| select (Suit: s, Rank: r); |
There was a problem hiding this comment.
There's an extra space before the tuple in the select clause. This should be a single space for consistency.
Suggestion:
select (Suit: s, Rank: r);| select (Suit: s, Rank: r); | |
| select (Suit: s, Rank: r); |
|
|
||
|
|
There was a problem hiding this comment.
The file has trailing blank lines that should be removed for cleaner code formatting.
| from r in Ranks() | ||
| select (Suit: s, Rank: r); | ||
|
|
||
| // Display each card that we've generated and placed in startingDeck in the console |
There was a problem hiding this comment.
The comment says "Display each card that we've generated and placed in startingDeck in the console". According to the documentation style guidelines, avoid using "we" when referring to documentation authors.
Suggestion:
// Display each card that's generated and placed in startingDeck| // Display each card that we've generated and placed in startingDeck in the console | |
| // Display each card that's generated and placed in startingDeck |
| from r in Ranks() | ||
| select (Suit: s, Rank: r); | ||
|
|
||
| // Display each card that we've generated and placed in startingDeck in the console |
There was a problem hiding this comment.
The comment says "Display each card that we've generated and placed in startingDeck in the console". According to the documentation style guidelines, avoid using "we" when referring to documentation authors.
Suggestion:
// Display each card that's generated and placed in startingDeck| // Display each card that we've generated and placed in startingDeck in the console | |
| // Display each card that's generated and placed in startingDeck |
|
|
||
| // <Snippet18> | ||
| public static Dictionary<int, string> EnumNamedValues<T>() where T : System.Enum | ||
| extension<T>(T) where T : System.Enum |
There was a problem hiding this comment.
The receiver parameter name T is ambiguous and unclear. In extension member declarations, the receiver parameter should have a descriptive name. Since this extension operates on enum instances, a more descriptive name like enumValue or value would be clearer.
Suggestion:
extension<T>(T value) where T : System.Enum
{
public static Dictionary<int, string> EnumNamedValues()
{
// ... rest of implementation
}
}Note: The receiver parameter would need to be used in the method if it's meant to be an instance extension, or the method should remain static as it currently is.
| extension<T>(T) where T : System.Enum | |
| extension<T>(T value) where T : System.Enum |
| // <StepThree> | ||
| var startingDeck = from s in Suits() | ||
| from r in Ranks() | ||
| select (Suit: s, Rank: r); | ||
|
|
||
| // Display each card that we've generated and placed in startingDeck in the console | ||
| foreach (var card in startingDeck) | ||
| { | ||
| Console.WriteLine(card); | ||
| } | ||
|
|
||
| var top = startingDeck.Take(26); | ||
| var bottom = startingDeck.Skip(26); | ||
| // </StepThree> |
There was a problem hiding this comment.
The snippet tag "StepThree" is used twice in this file (lines 47-50 and lines 56-69). This creates ambiguity when referencing the snippet in documentation. Each snippet should have a unique identifier.
Consider renaming the second occurrence to something like "StepThreeWithSetup" or adjusting the snippet boundaries to avoid duplication.
| var shuffledDeck = top.InterleaveSequenceWith(bottom); | ||
|
|
||
| var times = 0; | ||
| // We can re-use the shuffle variable from earlier, or you can make a new one |
There was a problem hiding this comment.
According to the documentation style guidelines, avoid using "we" when referring to documentation authors or the code.
Suggestion:
// You can re-use the shuffle variable from earlier, or you can make a new one1 participant
Contributes to #45758
Commit history: (It may be easiest to review commit-by-commit)
Internal previews