Skip to content

Commit 3e029ce

Browse files
BillWagnerCopilotmeaghanlewis
authored
Create tutorial for C# 14 extension members (dotnet#48896)
* Rough draft * build warnings * typo * Improve sample organization * proofread * Apply suggestions from code review Co-authored-by: Copilot <[email protected]> Co-authored-by: Meaghan Osagie (Lewis) <[email protected]> --------- Co-authored-by: Copilot <[email protected]> Co-authored-by: Meaghan Osagie (Lewis) <[email protected]>
1 parent fd348a8 commit 3e029ce

File tree

9 files changed

+856
-0
lines changed

9 files changed

+856
-0
lines changed

‎docs/csharp/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -174,6 +174,8 @@ items:
174174
href: whats-new/version-update-considerations.md
175175
- name: Tutorials
176176
items:
177+
- name: Explore extension members
178+
href: whats-new/tutorials/extension-members.md
177179
- name: Explore compound assignment
178180
href: whats-new/tutorials/compound-assignment-operators.md
179181
- name: Explore primary constructors

‎docs/csharp/whats-new/tutorials/extension-members.md‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
---
2+
title: Explore extension members in C# 14 to enhance existing types
3+
description: "C# 14 provides new syntax for extensions that support properties and operators, and enables extensions on a type as well as an instance. Learn to use them, and how to migrate existing extension methods to extension members"
4+
author: billwagner
5+
ms.author: wiwagn
6+
ms.service: dotnet-csharp
7+
ms.topic: tutorial
8+
ms.date: 10/06/2025
9+
ai-usage: ai-assisted
10+
#customer intent: As a C# developer, I reduce repeated code by introducing extension members for common tasks
11+
---
12+
# Tutorial: Explore extension members in C# 14
13+
14+
C# 14 introduces extension members, an enhancement to the existing extension methods. Extension members enable you to add properties and operators. You can also extend types in addition to instances of types. This capability allows you to create more natural and expressive APIs when extending types you don't control.
15+
16+
In this tutorial, you explore extension members by enhancing the `System.Drawing.Point` type with mathematical operations, coordinate transformations, and utility properties. You learn how to migrate existing extension methods to the new extension member syntax and understand when to use each approach.
17+
18+
In this tutorial, you:
19+
20+
> [!div class="checklist"]
21+
>
22+
> * Create extension members with static properties and operators.
23+
> * Implement coordinate transformations using extension members.
24+
> * Migrate traditional extension methods to extension member syntax.
25+
> * Compare extension members with traditional extension methods.
26+
27+
## Prerequisites
28+
29+
- The .NET 10 preview SDK. Download it from the [.NET download site](https://dotnet.microsoft.com/download/dotnet/10.0).
30+
- Visual Studio 2026 (preview). Download it from the [Visual Studio insiders page](https://visualstudio.microsoft.com/insiders/).
31+
32+
## Create the sample application
33+
34+
Start by creating a console application that demonstrates both traditional extension methods and the new extension members syntax.
35+
36+
1. Create a new console application:
37+
38+
```dotnetcli
39+
dotnet new console -n PointExtensions
40+
cd PointExtensions
41+
```
42+
43+
1. Copy the following code into a new file named `ExtensionMethods.cs`:
44+
45+
:::code language="csharp" source="snippets/PointExtensions/ExtensionMethods.cs":::
46+
47+
1. Copy the following code that demonstrates these extension methods and other uses of the <xref:System.Drawing.Point?displayProperty=nameWithType>:
48+
49+
:::code language="csharp" source="snippets/PointExtensions/ExtensionMethodsDemonstrations.cs":::
50+
51+
1. Replace the content of `Program.cs` with the demonstration code:
52+
53+
:::code language="csharp" source="snippets/PointExtensions/Program.cs" id="TraditionalExtensionMethods":::
54+
55+
1. Run the sample application and examine the output.
56+
57+
Traditional extension methods can only add instance methods to existing types. Extension members enable you to add static properties, which provides a more natural way to extend types with constants or computed values.
58+
59+
## Add static properties with extension members
60+
61+
First, examine this code in the sample:
62+
63+
:::code language="csharp" source="snippets/PointExtensions/IncludedElements.cs" id="StaticPropertySubstitute":::
64+
65+
Many apps that use 2D geometry use the concept of an `Origin`, which is the same value as <xref:System.Drawing.Point.Empty?displayProperty=nameWithType>. This code uses that fact, but some developers might create a `new Point(0,0)`, which incurs some extra work. In a given domain, you want to express these common values through static properties.
66+
67+
Create `NewExtensionsMembers.cs` to create extension members that solve this problem:
68+
69+
```csharp
70+
using System.Drawing;
71+
using System.Numerics;
72+
73+
namespace ExtensionMembers;
74+
75+
public static class PointExtensions
76+
{
77+
extension (Point)
78+
{
79+
public static Point Origin => Point.Empty;
80+
}
81+
}
82+
```
83+
84+
The preceding code adds a static *extension property* to the `Point` struct. The `extension` keyword introduces an *extension block*. This extension block extends the `Point` struct.
85+
86+
You can use this static property as though it were a member of the `Point` struct.
87+
88+
:::code language="csharp" source="snippets/PointExtensions/ExtensionMemberDemonstrations.cs" id="StaticProperty":::
89+
90+
The `Point.Origin` property now appears as if it were part of the original `Point` type, providing a more intuitive API.
91+
92+
## Implement arithmetic operators
93+
94+
Next, examine the following code that performs arithmetic with points:
95+
96+
:::code language="csharp" source="snippets/PointExtensions/IncludedElements.cs" id="PointArithmetic":::
97+
98+
Traditional extension methods can't add operators to existing types. You must implement arithmetic operations manually, making the code verbose and harder to read. The algorithm gets duplicated whenever the operation is needed, which creates more opportunities for small mistakes to enter the code base. It's better to place that code in one location. Add the following operators to your extension block in `NewExtensionsMembers.cs`:
99+
100+
:::code language="csharp" source="snippets/PointExtensions/NewExtensionsMembers.cs" id="ArithmeticOperators":::
101+
102+
Extension members enable you to add operators directly to existing types. Now you can perform arithmetic operations using natural syntax:
103+
104+
:::code language="csharp" source="snippets/PointExtensions/ExtensionMemberDemonstrations.cs" id="PointArithmeticWithOperators":::
105+
106+
The extension operators make point arithmetic as natural as working with built-in numeric types.
107+
108+
## Add more operators
109+
110+
You can also add extension operators for the discrete operations shown in the following code example:
111+
112+
:::code language="csharp" source="snippets/PointExtensions/IncludedElements.cs" id="DiscreteXYOperators":::
113+
114+
The `+` and `-` operators are *binary operators* and require two operands, not three. Instead of two discrete integers, use a *tuple* to specify both the `X` and `Y` deltas:
115+
116+
:::code language="csharp" source="snippets/PointExtensions/NewExtensionsMembers.cs" id="TupleBasedXYOperators":::
117+
118+
The preceding operator enables elegant tuple-based operations:
119+
120+
:::code language="csharp" source="snippets/PointExtensions/ExtensionMemberDemonstrations.cs" id="DiscreteXYOperators":::
121+
122+
Your extensions can include multiple overloaded operators, as long as the operands are distinct.
123+
124+
## Migrate instance methods to extension members
125+
126+
Extension members also support instance methods. You don't have to change existing extension methods. The old and new forms are binary and source compatible. If you want to keep all your extensions in one container, you can. Migrating traditional extension methods to the new syntax maintains the same functionality.
127+
128+
### Traditional extension methods
129+
130+
The traditional approach uses the `this` parameter syntax:
131+
132+
:::code language="csharp" source="snippets/PointExtensions/IncludedElements.cs" id="ExtensionMethods":::
133+
134+
Extension members use a different syntax but provide the same functionality. Add the following code to your new extension members class:
135+
136+
:::code language="csharp" source="snippets/PointExtensions/NewExtensionsMembers.cs" id="TransformationMethods":::
137+
138+
The preceding code doesn't compile yet. It's the first extension you wrote that extends an *instance* of the `Point` class, instead of the type itself. To support instance extensions, your extension block needs to name the receiver parameter. Edit the following line:
139+
140+
```csharp
141+
extension (Point)
142+
```
143+
144+
So that it gives a name to the `Point` instance:
145+
146+
```csharp
147+
extension (Point point)
148+
```
149+
150+
Now, the code compiles. You can call these new instance methods exactly as you accessed traditional extension methods:
151+
152+
:::code language="csharp" source="snippets/PointExtensions/ExtensionMemberDemonstrations.cs" id="InstanceMethods":::
153+
154+
The key difference is syntax: extension members use `extension (Type variableName)` instead of `this Type variableName`.
155+
156+
## Completed sample
157+
158+
The final example shows the advantages when you combine static properties, operators, and instance methods to create comprehensive type extensions.
159+
160+
Compare the extension member version:
161+
162+
:::code language="csharp" source="snippets/PointExtensions/ExtensionMemberDemonstrations.cs" id="FinalScenarios":::
163+
164+
With the previous version:
165+
166+
:::code language="csharp" source="snippets/PointExtensions/IncludedElements.cs" id="FinalScenarios":::
167+
168+
This example demonstrates how extension members create a cohesive API that feels like part of the original type. You can:
169+
170+
- Use `Point.Origin` for a meaningful starting point
171+
- Apply mathematical operators naturally (`point + offset`, `point * scale`)
172+
- Chain transformations using both operators and methods
173+
- Convert between related types (`ToVector()`)
174+
175+
### Migration benefits
176+
177+
When migrating from traditional extension methods to extension members, you gain:
178+
179+
1. **Static properties**: Add constants and computed values to types.
180+
1. **Operators**: Enable natural mathematical and logical operations.
181+
1. **Unified syntax**: All extension logic uses the same `extension` declaration.
182+
1. **Type-level extensions**: Extend the type itself, not just instances.
183+
184+
Run the complete application to see both approaches side by side and observe how extension members provide a more integrated development experience.
185+
186+
## Related content
187+
188+
- [Extension methods (C# Programming Guide)](/dotnet/csharp/programming-guide/classes-and-structs/extension-methods)
189+
- [What's new in C# 14](/dotnet/csharp/whats-new/csharp-14)
190+
- [Operator overloading (C# reference)](/dotnet/csharp/language-reference/operators/operator-overloading)

‎docs/csharp/whats-new/tutorials/snippets/PointExtensions/ExtensionMemberDemonstrations.cs‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
using System.Drawing;
2+
using System.Numerics;
3+
using ExtensionMembers;
4+
5+
public static class ExtensionMemberDemonstrations
6+
{
7+
public static void NewExtensionMembers()
8+
{
9+
Console.WriteLine("Point Extension Members Demonstration");
10+
Console.WriteLine("=====================================\n");
11+
12+
OriginAsStaticProperty();
13+
ArithmeticWithPoints();
14+
DiscreteArithmeticWithPoints();
15+
ExtensionMethods();
16+
MoreExamples();
17+
}
18+
19+
static void OriginAsStaticProperty()
20+
{
21+
// <StaticProperty>
22+
Console.WriteLine("1. Static Properties");
23+
Console.WriteLine("-------------------");
24+
25+
Point origin = Point.Origin;
26+
Console.WriteLine($"Point.Origin: {origin}");
27+
Console.WriteLine($"Same as Point.Empty: {origin == Point.Empty}");
28+
Console.WriteLine();
29+
// </StaticProperty>
30+
}
31+
32+
static void ArithmeticWithPoints()
33+
{
34+
// <PointArithmeticWithOperators>
35+
Console.WriteLine("2. Arithmetic Operators (Point + Point, Point - Point)");
36+
Console.WriteLine("-----------------------------------------------------");
37+
38+
Point p1 = new Point(5, 3);
39+
Point p2 = new Point(2, 7);
40+
41+
Console.WriteLine($"Point 1: {p1}");
42+
Console.WriteLine($"Point 2: {p2}");
43+
Console.WriteLine($"Addition (p1 + p2): {p1 + p2}");
44+
Console.WriteLine($"Subtraction (p1 - p2): {p1 - p2}");
45+
Console.WriteLine($"Subtraction (p2 - p1): {p2 - p1}");
46+
Console.WriteLine();
47+
// </PointArithmeticWithOperators>
48+
}
49+
50+
static void DiscreteArithmeticWithPoints()
51+
{
52+
// <DiscreteXYOperators>
53+
Console.WriteLine("3. Discrete Operators using tuples (Point with (int, int))");
54+
Console.WriteLine("------------------------------------------");
55+
56+
Point point = new Point(10, 8);
57+
var offset = (3, -2);
58+
var scale = (2, 3);
59+
var divisor = (2, 4);
60+
61+
Console.WriteLine($"Original point: {point}");
62+
Console.WriteLine($"Offset tuple: {offset}");
63+
Console.WriteLine($"Scale tuple: {scale}");
64+
Console.WriteLine($"Divisor tuple: {divisor}");
65+
Console.WriteLine();
66+
67+
Console.WriteLine($"point + offset: {point + offset}");
68+
Console.WriteLine($"point - offset: {point - offset}");
69+
Console.WriteLine($"point * scale: {point * scale}");
70+
Console.WriteLine($"point / divisor: {point / divisor}");
71+
Console.WriteLine();
72+
// </DiscreteXYOperators>
73+
}
74+
75+
static void ExtensionMethods()
76+
{
77+
// <InstanceMethods>
78+
Console.WriteLine("4. Instance Methods");
79+
Console.WriteLine("------------------");
80+
81+
// ToVector demonstration
82+
Point vectorPoint = new Point(12, 16);
83+
Vector2 vector = vectorPoint.ToVector();
84+
Console.WriteLine($"Point {vectorPoint} as Vector2: {vector}");
85+
Console.WriteLine();
86+
87+
// Translate demonstration
88+
Point translatePoint = new Point(5, 5);
89+
Console.WriteLine($"Before Translate: {translatePoint}");
90+
translatePoint.Translate(3, -2);
91+
Console.WriteLine($"After Translate(3, -2): {translatePoint}");
92+
Console.WriteLine();
93+
94+
// Scale demonstration
95+
Point scalePoint = new Point(4, 6);
96+
Console.WriteLine($"Before Scale: {scalePoint}");
97+
scalePoint.Scale(2, 3);
98+
Console.WriteLine($"After Scale(2, 3): {scalePoint}");
99+
Console.WriteLine();
100+
101+
// Rotate demonstration
102+
Point rotatePoint1 = new Point(10, 0);
103+
Console.WriteLine($"Before Rotate: {rotatePoint1}");
104+
rotatePoint1.Rotate(90);
105+
Console.WriteLine($"After Rotate(90°): {rotatePoint1}");
106+
107+
Point rotatePoint2 = new Point(5, 5);
108+
Console.WriteLine($"Before Rotate: {rotatePoint2}");
109+
rotatePoint2.Rotate(45);
110+
Console.WriteLine($"After Rotate(45°): {rotatePoint2}");
111+
112+
Point rotatePoint3 = new Point(3, 4);
113+
Console.WriteLine($"Before Rotate: {rotatePoint3}");
114+
rotatePoint3.Rotate(180);
115+
Console.WriteLine($"After Rotate(180°): {rotatePoint3}");
116+
Console.WriteLine();
117+
// </InstanceMethods>
118+
}
119+
120+
static void MoreExamples()
121+
{
122+
// <FinalScenarios>
123+
Console.WriteLine("5. Complex Scenarios");
124+
Console.WriteLine("-------------------");
125+
126+
// Combining operators and methods
127+
Console.WriteLine("Scenario 1: Building a rectangle using operators");
128+
Point topLeft = Point.Origin;
129+
Point bottomRight = topLeft + (10, 8);
130+
Point topRight = new Point(bottomRight.X, topLeft.Y);
131+
Point bottomLeft = new Point(topLeft.X, bottomRight.Y);
132+
133+
Console.WriteLine($"Rectangle corners:");
134+
Console.WriteLine($" Top-Left: {topLeft}");
135+
Console.WriteLine($" Top-Right: {topRight}");
136+
Console.WriteLine($" Bottom-Left: {bottomLeft}");
137+
Console.WriteLine($" Bottom-Right: {bottomRight}");
138+
Console.WriteLine();
139+
140+
// Transformation chain
141+
Console.WriteLine("Scenario 2: Transformation chain");
142+
Point transformPoint = new Point(2, 3);
143+
Console.WriteLine($"Starting point: {transformPoint}");
144+
145+
// Scale up
146+
transformPoint.Scale(3, 2);
147+
Console.WriteLine($"After scaling by (3, 2): {transformPoint}");
148+
149+
// Translate
150+
transformPoint = transformPoint + (5, -3);
151+
Console.WriteLine($"After translating by (5, -3): {transformPoint}");
152+
153+
// Rotate
154+
transformPoint.Rotate(45);
155+
Console.WriteLine($"After rotating 45°: {transformPoint}");
156+
157+
// Convert to vector
158+
Vector2 finalVector = transformPoint.ToVector();
159+
Console.WriteLine($"Final result as Vector2: {finalVector}");
160+
Console.WriteLine();
161+
162+
// Distance calculation using operators
163+
Console.WriteLine("Scenario 3: Distance calculation");
164+
Point point1 = new Point(1, 1);
165+
Point point2 = new Point(4, 5);
166+
Point difference = point2 - point1;
167+
Vector2 diffVector = difference.ToVector();
168+
float distance = diffVector.Length();
169+
170+
Console.WriteLine($"Point 1: {point1}");
171+
Console.WriteLine($"Point 2: {point2}");
172+
Console.WriteLine($"Difference: {difference}");
173+
Console.WriteLine($"Distance: {distance:F2}");
174+
Console.WriteLine();
175+
176+
Console.WriteLine("Demonstration complete!");
177+
// </FinalScenarios>
178+
}
179+
}

0 commit comments

Comments
 (0)