Skip to content

Commit fbc0874

Browse files
BillWagnerBillWagner
committed
Finish all programming guide updates
1 parent 504145d commit fbc0874

File tree

14 files changed

+292
-137
lines changed

14 files changed

+292
-137
lines changed

‎docs/csharp/fundamentals/object-oriented/index.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: "Classes, structs, and records"
33
description: Describes the use of classes, structures (structs), and records in C#.
4-
ms.date: 04/11/2025
4+
ms.date: 04/17/2025
55
helpviewer_keywords:
66
- "structs [C#], about structs"
77
- "records [C#], about records"

‎docs/csharp/language-reference/keywords/base.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: "The base keyword"
33
description: Learn about the base keyword, which is used to access members of the base class from within a derived class in C#.
4-
ms.date: 04/11/2025
4+
ms.date: 04/17/2025
55
f1_keywords:
66
- "base"
77
- "BaseClass.BaseClass"

‎docs/csharp/language-reference/keywords/extension.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: "extension member declarations"
33
description: "Learn the syntax to declare extension members in C#. Extension members enable you to add functionality to types and interfaces in those instances where you don't have the source for the original type. Extensions are often paired with generic interfaces to implement a common set of functionality across all types that implement that interface."
4-
ms.date: 04/11/2025
4+
ms.date: 04/17/2025
55
f1_keywords:
66
- "extension_CSharpKeyword"
77
- "extension"

‎docs/csharp/language-reference/keywords/index.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
description: "C# Keywords: Find the reference material for the predefined keywords and contextual keywords defined in the C# language."
33
title: "C# Keywords and contextual keywords"
4-
ms.date: 04/11/2025
4+
ms.date: 04/17/2025
55
f1_keywords:
66
- "cs.keywords"
77
helpviewer_keywords:

‎docs/csharp/language-reference/keywords/this.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: "The this keyword"
33
description: The `this` keyword clarifies access to the current instance of a type, or declares an indexer on the type.
4-
ms.date: 04/11/2025
4+
ms.date: 04/17/2025
55
f1_keywords:
66
- "this"
77
- "this_CSharpKeyword"

‎docs/csharp/linq/how-to-extend-linq.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: "How to: Write your own extensions to LINQ"
33
description: Learn techniques to extend the standard LINQ methods. Query based on runtime state, modify query objects, and extend LINQ capabilities.
44
ms.topic: how-to
5-
ms.date: 04/11/2025
5+
ms.date: 04/17/2025
66
---
77
# How to extend LINQ
88

‎docs/csharp/methods.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Overview of methods
33
description: Overview of methods, method parameters, and method return values
44
ms.subservice: fundamentals
5-
ms.date: 04/15/2025
5+
ms.date: 04/17/2025
66
---
77

88
# Methods in C\#

‎docs/csharp/programming-guide/classes-and-structs/extension-methods.md

+47-51
Large diffs are not rendered by default.

‎docs/csharp/programming-guide/classes-and-structs/how-to-create-a-new-method-for-an-enumeration.md

+2-3
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: "How to create a new method for an enumeration"
33
description: Learn how to use extension methods to add functionality to an enum in C#. This example shows an extension method called Passing for an enum called Grades.
4-
ms.date: 04/15/2025
4+
ms.date: 04/17/2025
55
helpviewer_keywords:
66
- "enumerations [C#]"
77
- "extension methods [C#], for enums"
@@ -22,13 +22,12 @@ Beginning with C# 14, you can declare *extension members* in an extension block.
2222

2323
:::code language="csharp" source="./snippets/ExtensionMembers/CustomExtensionMembers.cs" id="EnumExtensionMembers":::
2424

25-
You call these new extension properties as though they are declared on the extended type:
25+
You call these new extension properties as though they're declared on the extended type:
2626

2727
:::code language="csharp" source="./snippets/ExtensionMembers/CustomExtensionMembers.cs" id="EnumExtensionMembers":::
2828

2929
You can learn more about the new extension members in the article on [extension members](./extension-methods.md) and in the language reference article on the ['extension` keyword](../../language-reference/keywords/extension.md).
3030

31-
3231
## See also
3332

3433
- [Extension Methods](./extension-methods.md)

‎docs/csharp/programming-guide/classes-and-structs/snippets/ExtensionMembers/CustomExtensionMembers.cs

+140-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,59 @@
1-
using CustomExtensionMethods;
2-
1+
// <ExtensionBlock>
32
namespace CustomExtensionMembers;
43

4+
public static class MyExtensions
5+
{
6+
extension(string str)
7+
{
8+
public int WordCount() =>
9+
str.Split([' ', '.', '?'], StringSplitOptions.RemoveEmptyEntries).Length;
10+
}
11+
}
12+
// </ExtensionBlock>
13+
14+
public interface IMyInterface
15+
{
16+
void MethodB();
17+
}
18+
19+
//<InterfaceAndExtensions>
20+
public static class Extension
21+
{
22+
extension(IMyInterface myInterface)
23+
{
24+
public void MethodA(int i) =>
25+
Console.WriteLine("Extension.MethodA(this IMyInterface myInterface, int i)");
26+
27+
public void MethodA(string s) =>
28+
Console.WriteLine("Extension.MethodA(this IMyInterface myInterface, string s)");
29+
30+
// This method is never called in ExtensionMethodsDemo1, because each
31+
// of the three classes A, B, and C implements a method named MethodB
32+
// that has a matching signature.
33+
public void MethodB() =>
34+
Console.WriteLine("Extension.MethodB(this IMyInterface myInterface)");
35+
}
36+
}
37+
//</InterfaceAndExtensions>
38+
39+
public class DomainEntity
40+
{
41+
public int Id { get; set; }
42+
public required string FirstName { get; set; }
43+
public required string LastName { get; set; }
44+
}
45+
46+
// <DomainEntity>
47+
static class DomainEntityExtensions
48+
{
49+
extension(DomainEntity value)
50+
{
51+
string FullName => $"{value.FirstName} {value.LastName}";
52+
}
53+
}
54+
// </DomainEntity>
55+
56+
557
public enum Grades
658
{
759
F = 0,
@@ -29,10 +81,69 @@ public static Grades MinimumPassingGrade
2981
}
3082
// </EnumExtensionMembers>
3183

84+
85+
//<RefExtensions>
86+
public static class IntExtensions
87+
{
88+
extension(int number)
89+
{
90+
public void Increment()
91+
=> number++;
92+
}
93+
94+
// Take note of the extra ref keyword here
95+
extension(ref int number)
96+
{
97+
public void RefIncrement()
98+
=> number++;
99+
}
100+
}
101+
//</RefExtensions>
102+
103+
public struct Account
104+
{
105+
public uint id;
106+
public float balance;
107+
108+
private int secret;
109+
}
110+
111+
//<UserDefinedRef>
112+
public static class AccountExtensions
113+
{
114+
extension(ref Account account)
115+
{
116+
// ref keyword can also appear before the this keyword
117+
public void Deposit(float amount)
118+
{
119+
account.balance += amount;
120+
121+
// The following line results in an error as an extension
122+
// method is not allowed to access private members
123+
// account.secret = 1; // CS0122
124+
}
125+
}
126+
}
127+
//</UserDefinedRef>
128+
32129
public static class ExtensionMemberUsage
33130
{
34131
public static void Examples()
35132
{
133+
{
134+
// <CallAsInstanceMethod>
135+
string s = "Hello Extension Methods";
136+
int i = s.WordCount();
137+
// </CallAsInstanceMethod>
138+
}
139+
140+
{
141+
// <CallAsStaticMethod>
142+
string s = "Hello Extension Methods";
143+
int i = MyExtensions.WordCount(s);
144+
// </CallAsStaticMethod>
145+
}
146+
// <CallExtensionMethods>
36147
// <ExampleExtendEnum>
37148
Grades g1 = Grades.D;
38149
Grades g2 = Grades.F;
@@ -53,5 +164,32 @@ First is not a passing grade.
53164
Second is not a passing grade.
54165
*/
55166
// </ExampleExtendEnum>
167+
168+
// <UseRefExtension>
169+
int x = 1;
170+
171+
// Takes x by value leading to the extension method
172+
// Increment modifying its own copy, leaving x unchanged
173+
x.Increment();
174+
Console.WriteLine($"x is now {x}"); // x is now 1
175+
176+
// Takes x by reference leading to the extension method
177+
// RefIncrement changing the value of x directly
178+
x.RefIncrement();
179+
Console.WriteLine($"x is now {x}"); // x is now 2
180+
// </UseRefExtensions>
181+
182+
// <TestUserDefinedRef>
183+
Account account = new()
184+
{
185+
id = 1,
186+
balance = 100f
187+
};
188+
189+
Console.WriteLine($"I have ${account.balance}"); // I have $100
190+
191+
account.Deposit(50f);
192+
Console.WriteLine($"I have ${account.balance}"); // I have $150
193+
// </TestUserDefinedRef>
56194
}
57195
}

‎docs/csharp/programming-guide/classes-and-structs/snippets/ExtensionMembers/CustomExtensionMethods.cs

+93-1
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ public static void MethodA(this IMyInterface myInterface, string s) =>
3232
public static void MethodB(this IMyInterface myInterface) =>
3333
Console.WriteLine("Extension.MethodB(this IMyInterface myInterface)");
3434
}
35-
//<InterfaceAndExtensions>
35+
//</InterfaceAndExtensions>
3636

3737
// <Classes>
3838
// Define three classes that implement IMyInterface, and then use them to test
@@ -58,6 +58,22 @@ public void MethodA(object obj)
5858
}
5959
// </Classes>
6060

61+
// <DomainEntity>
62+
public class DomainEntity
63+
{
64+
public int Id { get; set; }
65+
public required string FirstName { get; set; }
66+
public required string LastName { get; set; }
67+
}
68+
69+
static class DomainEntityExtensions
70+
{
71+
static string FullName(this DomainEntity value)
72+
=> $"{value.FirstName} {value.LastName}";
73+
}
74+
// </DomainEntity>
75+
76+
6177
//<ExtendEnumType>
6278
public enum Grades
6379
{
@@ -76,10 +92,59 @@ public static bool Passing(this Grades grade, Grades minPassing = Grades.D) =>
7692
}
7793
//</ExtendEnumType>
7894

95+
//<RefExtensions>
96+
public static class IntExtensions
97+
{
98+
public static void Increment(this int number)
99+
=> number++;
100+
101+
// Take note of the extra ref keyword here
102+
public static void RefIncrement(this ref int number)
103+
=> number++;
104+
}
105+
//</RefExtensions>
106+
107+
//<UserDefinedRef>
108+
public struct Account
109+
{
110+
public uint id;
111+
public float balance;
112+
113+
private int secret;
114+
}
115+
116+
public static class AccountExtensions
117+
{
118+
// ref keyword can also appear before the this keyword
119+
public static void Deposit(ref this Account account, float amount)
120+
{
121+
account.balance += amount;
122+
123+
// The following line results in an error as an extension
124+
// method is not allowed to access private members
125+
// account.secret = 1; // CS0122
126+
}
127+
}
128+
//</UserDefinedRef>
129+
130+
79131
public static class ExtensionMethodUsage
80132
{
81133
public static void Examples()
82134
{
135+
{
136+
// <CallAsInstanceMethod>
137+
string s = "Hello Extension Methods";
138+
int i = s.WordCount();
139+
// </CallAsInstanceMethod>
140+
}
141+
142+
{
143+
// <CallAsStaticMethod>
144+
string s = "Hello Extension Methods";
145+
int i = MyExtensions.WordCount(s);
146+
// </CallAsStaticMethod>
147+
}
83148
// <CallExtensionMethods>
84149
// Declare an instance of class A, class B, and class C.
85150
A a = new A();
@@ -146,5 +211,32 @@ First is not a passing grade.
146211
Second is not a passing grade.
147212
*/
148213
// </ExampleExtendEnum>
214+
215+
// <UseRefExtension>
216+
int x = 1;
217+
218+
// Takes x by value leading to the extension method
219+
// Increment modifying its own copy, leaving x unchanged
220+
x.Increment();
221+
Console.WriteLine($"x is now {x}"); // x is now 1
222+
223+
// Takes x by reference leading to the extension method
224+
// RefIncrement changing the value of x directly
225+
x.RefIncrement();
226+
Console.WriteLine($"x is now {x}"); // x is now 2
227+
// </UseRefExtensions>
228+
229+
// <TestUserDefinedRef>
230+
Account account = new()
231+
{
232+
id = 1,
233+
balance = 100f
234+
};
235+
236+
Console.WriteLine($"I have ${account.balance}"); // I have $100
237+
238+
account.Deposit(50f);
239+
Console.WriteLine($"I have ${account.balance}"); // I have $150
240+
// </TestUserDefinedRef>
149241
}
150242
}

0 commit comments

Comments
 (0)