Review delegate content in the C# programming guide (#44046)

* Move delegate samples

* Fix the open issues

- Add an example using an anonymouse method
- Remove the references to C++ function pointers
- Rewrite one heading

* Proofread

Refactor code, proofread and grammar check.

Remove one example. It more or less repeated the previous full example.

* Update docs/csharp/programming-guide/delegates/using-delegates.md

Co-authored-by: Genevieve Warren <[email protected]>

---------

Co-authored-by: Genevieve Warren <[email protected]>

Author: BillWagner

docs/csharp/programming-guide/delegates/delegates-with-named-vs-anonymous-methods.md

@@ -1,26 +1,27 @@
 ---
 title: "Delegates with Named vs. Anonymous Methods"
-description: Learn about delegates with named vs. anonymous methods. See code examples and view additional available resources.
-ms.date: 11/22/2024
+description: Learn about delegates with named vs. anonymous methods. See code examples and view other available resources.
+ms.date: 12/20/2024
 helpviewer_keywords: 
   - "delegates [C#], with named vs. anonymous methods"
   - "methods [C#], in delegates"
-ms.assetid: 98fa8c61-66b6-4146-986c-3236c4045733
 ---
 # Delegates with Named vs. Anonymous Methods (C# Programming Guide)
 
 A [delegate](../../language-reference/builtin-types/reference-types.md) can be associated with a named method. When you instantiate a delegate by using a named method, the method is passed as a parameter, for example:
 
-[!code-csharp[csProgGuideDelegates#1](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDelegates/CS/Delegates.cs#1)]
+:::code language="csharp" source="./snippets/NamedAnonymousDelegates.cs" id="NamedDelegate":::
 
-This is called using a named method. Delegates constructed with a named method can encapsulate either a [static](../../language-reference/keywords/static.md) method or an instance method. Named methods are the only way to instantiate a delegate in earlier versions of C#. However, in a situation where creating a new method is unwanted overhead, C# enables you to instantiate a delegate and immediately specify a code block that the delegate will process when it is called. The block can contain either a [lambda expression](../../language-reference/operators/lambda-expressions.md) or an [anonymous method](../../language-reference/operators/delegate-operator.md).
+The preceding example uses a named method. Delegates constructed with a named method can encapsulate either a [static](../../language-reference/keywords/static.md) method or an instance method. Named methods are the only way to instantiate a delegate in earlier versions of C#. C# enables you to instantiate a delegate and immediately specify a code block that the delegate processes when called. The block can contain either a [lambda expression](../../language-reference/operators/lambda-expressions.md) or an [anonymous method](../../language-reference/operators/delegate-operator.md), as shown in the following example:
 
-The method that you pass as a delegate parameter must have the same signature as the delegate declaration. A delegate instance may encapsulate either static or instance method.
+:::code language="csharp" source="./snippets/NamedAnonymousDelegates.cs" id="SnippetAnonymousMethod":::
+
+The method that you pass as a delegate parameter must have the same signature as the delegate declaration. A delegate instance can encapsulate either static or instance method.
 
 > [!NOTE]
 > Although the delegate can use an [out](../../language-reference/keywords/method-parameters.md#out-parameter-modifier) parameter, we do not recommend its use with multicast event delegates because you cannot know which delegate will be called.
 
-Method groups with a single overload have a *natural type*. This means the compiler can infer the return type and parameter types for the delegate type:
+Method groups with a single overload have a *natural type*. The compiler can infer the return type and parameter types for the delegate type:
 
 ```csharp
 var read = Console.Read; // Just one overload; Func<int> inferred
@@ -29,13 +30,13 @@ var write = Console.Write; // ERROR: Multiple overloads, can't choose
 
 ## Examples
 
-The following is a simple example of declaring and using a delegate. Notice that both the delegate, `MultiplyCallback`, and the associated method, `MultiplyNumbers`, have the same signature
+The following example is a simple example of declaring and using a delegate. Notice that both the delegate, `MultiplyCallback`, and the associated method, `MultiplyNumbers`, have the same signature
 
-[!code-csharp[csProgGuideDelegates#2](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDelegates/CS/Delegates.cs#2)]
+:::code language="csharp" source="./snippets/NamedAnonymousDelegates.cs" id="DeclareAndUse":::
 
 In the following example, one delegate is mapped to both static and instance methods and returns specific information from each.
 
-[!code-csharp[csProgGuideDelegates#3](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDelegates/CS/Delegates.cs#3)]
+:::code language="csharp" source="./snippets/NamedAnonymousDelegates.cs" id="AnotherSample":::
 
 ## See also
 

docs/csharp/programming-guide/delegates/how-to-combine-delegates-multicast-delegates.md

@@ -1,23 +1,18 @@
 ---
 title: "How to combine delegates (Multicast Delegates)"
-description: Learn how to combine delegates to create multicast delegates. See a code example and view additional available resources.
+description: Learn how to combine delegates to create multicast delegates. See a code example and view more available resources.
 ms.topic: how-to
-ms.date: 07/20/2015
+ms.date: 12/20/2024
 helpviewer_keywords: 
   - "delegates [C#], combining"
   - "multicast delegates [C#]"
-ms.assetid: 4e689450-6d0c-46de-acfd-f961018ae5dd
 ---
 # How to combine delegates (Multicast Delegates) (C# Programming Guide)
 
-This example demonstrates how to create multicast delegates. A useful property of [delegate](../../language-reference/builtin-types/reference-types.md) objects is that multiple objects can be assigned to one delegate instance by using the `+` operator. The multicast delegate contains a list of the assigned delegates. When the multicast delegate is called, it invokes the delegates in the list, in order. Only delegates of the same type can be combined.  
-  
- The `-` operator can be used to remove a component delegate from a multicast delegate.  
-  
-## Example  
+This example demonstrates how to create multicast delegates. A useful property of [delegate](../../language-reference/builtin-types/reference-types.md) objects is that multiple objects can be assigned to one delegate instance by using the `+` operator. The multicast delegate contains a list of the assigned delegates. When the multicast delegate is called, it invokes the delegates in the list, in order. Only delegates of the same type can be combined. The `-` operator can be used to remove a component delegate from a multicast delegate.
+
+:::code language="csharp" source="./snippets/MulticastExample.cs":::
 
- [!code-csharp[csProgGuideDelegates#11](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDelegates/CS/Delegates.cs#11)]  
-  
 ## See also
 
 - <xref:System.MulticastDelegate>

docs/csharp/programming-guide/delegates/how-to-declare-instantiate-and-use-a-delegate.md

@@ -1,76 +1,41 @@
 ---
 title: "How to declare, instantiate, and use a delegate"
-description: Learn how to declare, instantiate, and use a delegate. See examples that cover C# 1.0, 2.0, and 3.0 and later.
+description: Learn how to declare, instantiate, and use a delegate. This article provides several examples of declaring, instantiating, and invoking delegates.
 ms.topic: how-to
-ms.date: 07/20/2015
+ms.date: 12/20/2024
 helpviewer_keywords: 
   - "delegates [C#], declaring and instantiating"
-ms.assetid: 61c4895f-f785-48f8-8bfe-db73b411c4ae
 ---
 # How to declare, instantiate, and use a Delegate (C# Programming Guide)
 
 You can declare delegates using any of the following methods:
 
 - Declare a delegate type and declare a method with a matching signature:
-  
- [!code-csharp[csProgGuideDelegates#13](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDelegates/CS/Delegates.cs#13)]  
-  
- [!code-csharp[csProgGuideDelegates#14](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDelegates/CS/Delegates.cs#14)]  
-  
+
+  :::code language="csharp" source="./snippets/HowToDeclareAndUse.cs" id="DeclareNamedDelegate":::
+
+  :::code language="csharp" source="./snippets/HowToDeclareAndUse.cs" id="CreateNamedInstance":::
+
 - Assign a method group to a delegate type:
-  
- [!code-csharp[csProgGuideDelegates#32](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDelegates/CS/Delegates.cs#32)]  
-  
-- Declare an anonymous method:
-  
- [!code-csharp[csProgGuideDelegates#15](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDelegates/CS/Delegates.cs#15)]  
-  
+
+  :::code language="csharp" source="./snippets/HowToDeclareAndUse.cs" id="MethodGroup":::
+
+- Declare an anonymous method
+
+  :::code language="csharp" source="./snippets/HowToDeclareAndUse.cs" id="AnonymousMethod":::
+
 - Use a lambda expression:
-  
- [!code-csharp[csProgGuideDelegates#31](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDelegates/CS/Delegates.cs#31)]  
-  
- For more information, see [Lambda Expressions](../../language-reference/operators/lambda-expressions.md).  
-  
- The following example illustrates declaring, instantiating, and using a delegate. The `BookDB` class encapsulates a bookstore database that maintains a database of books. It exposes a method, `ProcessPaperbackBooks`, which finds all paperback books in the database and calls a delegate for each one. The `delegate` type that is used is named `ProcessBookCallback`. The `Test` class uses this class to print the titles and average price of the paperback books.  
-  
- The use of delegates promotes good separation of functionality between the bookstore database and the client code. The client code has no knowledge of how the books are stored or how the bookstore code finds paperback books. The bookstore code has no knowledge of what processing is performed on the paperback books after it finds them.  
-  
-## Example  
-
- [!code-csharp[csProgGuideDelegates#12](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDelegates/CS/Delegates.cs#12)]  
-  
-## Robust Programming  
-  
-- Declaring a delegate.  
-  
-     The following statement declares a new delegate type.  
-  
-     [!code-csharp[csProgGuideDelegates#16](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDelegates/CS/Delegates.cs#16)]  
-  
-     Each delegate type describes the number and types of the arguments, and the type of the return value of methods that it can encapsulate. Whenever a new set of argument types or return value type is needed, a new delegate type must be declared.  
-  
-- Instantiating a delegate.  
-  
-     After a delegate type has been declared, a delegate object must be created and associated with a particular method. In the previous example, you do this by passing the `PrintTitle` method to the `ProcessPaperbackBooks` method as in the following example:  
-  
-     [!code-csharp[csProgGuideDelegates#17](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDelegates/CS/Delegates.cs#17)]  
-  
-     This creates a new delegate object associated with the [static](../../language-reference/keywords/static.md) method `Test.PrintTitle`. Similarly, the non-static method `AddBookToTotal` on the object `totaller` is passed as in the following example:  
-  
-     [!code-csharp[csProgGuideDelegates#18](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDelegates/CS/Delegates.cs#18)]  
-  
-     In both cases a new delegate object is passed to the `ProcessPaperbackBooks` method.  
-  
-     After a delegate is created, the method it is associated with never changes; delegate objects are immutable.  
-  
-- Calling a delegate.  
-  
-     After a delegate object is created, the delegate object is typically passed to other code that will call the delegate. A delegate object is called by using the name of the delegate object, followed by the parenthesized arguments to be passed to the delegate. Following is an example of a delegate call:  
-  
-     [!code-csharp[csProgGuideDelegates#19](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDelegates/CS/Delegates.cs#19)]  
-  
-     A delegate can be either called synchronously, as in this example, or asynchronously by using `BeginInvoke` and `EndInvoke` methods.  
-  
+
+  :::code language="csharp" source="./snippets/HowToDeclareAndUse.cs" id="LambdaExpression":::
+
+For more information, see [Lambda Expressions](../../language-reference/operators/lambda-expressions.md).
+
+The following example illustrates declaring, instantiating, and using a delegate. The `BookDB` class encapsulates a bookstore database that maintains a database of books. It exposes a method, `ProcessPaperbackBooks`, which finds all paperback books in the database and calls a delegate for each one. The `delegate` type is named `ProcessBookCallback`. The `Test` class uses this class to print the titles and average price of the paperback books.
+
+The use of delegates promotes good separation of functionality between the bookstore database and the client code. The client code has no knowledge of how the books are stored or how the bookstore code finds paperback books. The bookstore code has no knowledge of what processing is performed on the paperback books after it finds them.
+
+:::code language="csharp" source="./snippets/BookStore.cs":::
+
 ## See also
 
 - [Events](../events/index.md)

docs/csharp/programming-guide/delegates/index.md

@@ -1,19 +1,18 @@
 ---
 title: "Delegates"
 description: A delegate in C# is a type that refers to methods with a parameter list and return type. Delegates are used to pass methods as arguments to other methods.
-ms.date: 02/02/2021
+ms.date: 12/20/2024
 helpviewer_keywords: 
   - "C# language, delegates"
   - "delegates [C#]"
-ms.assetid: 97de039b-c76b-4b9c-a27d-8c1e1c8d93da
 ---
 # Delegates (C# Programming Guide)
 
 A [delegate](../../language-reference/builtin-types/reference-types.md) is a type that represents references to methods with a particular parameter list and return type. When you instantiate a delegate, you can associate its instance with any method with a compatible signature and return type. You can invoke (or call) the method through the delegate instance.
 
 Delegates are used to pass methods as arguments to other methods. Event handlers are nothing more than methods that are invoked through delegates. You create a custom method, and a class such as a windows control can call your method when a certain event occurs. The following example shows a delegate declaration:
 
-[!code-csharp[csProgGuideDelegates#20](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDelegates/CS/Delegates.cs#20)]
+:::code language="csharp" source="./snippets/Overview.cs" id="DelegateDeclaration":::
 
 Any method from any accessible class or struct that matches the delegate type can be assigned to the delegate. The method can be either static or an instance method. This flexibility means you can programmatically change method calls, or plug new code into existing classes.
 
@@ -28,7 +27,6 @@ This ability to refer to a method as a parameter makes delegates ideal for defin
 
 Delegates have the following properties:
 
-- Delegates are similar to C++ function pointers, but delegates are fully object-oriented, and unlike C++ pointers to member functions, delegates encapsulate both an object instance and a method.
 - Delegates allow methods to be passed as parameters.
 - Delegates can be used to define callback methods.
 - Delegates can be chained together; for example, multiple methods can be called on a single event.

docs/csharp/programming-guide/delegates/snippets/BookStore.cs

@@ -0,0 +1,101 @@
+using System;
+using System.Collections.Generic;
+
+// A set of classes for handling a bookstore:
+namespace Bookstore;
+
+// Describes a book in the book list:
+public record struct Book(string Title, string Author, decimal Price, bool Paperback);
+
+// Declare a delegate type for processing a book:
+public delegate void ProcessBookCallback(Book book);
+
+// Maintains a book database.
+public class BookDB
+{
+    // List of all books in the database:
+    List<Book> list = new();
+
+    // Add a book to the database:
+    public void AddBook(string title, string author, decimal price, bool paperBack) =>
+        list.Add(new Book(title, author, price, paperBack));
+
+    // Call a passed-in delegate on each paperback book to process it:
+    public void ProcessPaperbackBooks(ProcessBookCallback processBook)
+    {
+        foreach (Book b in list)
+        {
+            if (b.Paperback)
+            {
+                // Calling the delegate:
+                processBook(b);
+            }
+        }
+    }
+}
+
+// Using the Bookstore classes:
+
+// Class to total and average prices of books:
+class PriceTotaller
+{
+    private int countBooks = 0;
+    private decimal priceBooks = 0.0m;
+
+    internal void AddBookToTotal(Book book)
+    {
+        countBooks += 1;
+        priceBooks += book.Price;
+    }
+
+    internal decimal AveragePrice() => priceBooks / countBooks;
+}
+
+// Class to test the book database:
+class Test
+{
+    // Print the title of the book.
+    static void PrintTitle(Book b) => Console.WriteLine($"   {b.Title}");
+
+    // Execution starts here.
+    static void Main()
+    {
+        BookDB bookDB = new BookDB();
+
+        // Initialize the database with some books:
+        AddBooks(bookDB);
+
+        // Print all the titles of paperbacks:
+        Console.WriteLine("Paperback Book Titles:");
+
+        // Create a new delegate object associated with the static
+        // method Test.PrintTitle:
+        bookDB.ProcessPaperbackBooks(PrintTitle);
+
+        // Get the average price of a paperback by using
+        // a PriceTotaller object:
+        PriceTotaller totaller = new PriceTotaller();
+
+        // Create a new delegate object associated with the nonstatic
+        // method AddBookToTotal on the object totaller:
+        bookDB.ProcessPaperbackBooks(totaller.AddBookToTotal);
+
+        Console.WriteLine($"Average Paperback Book Price: ${totaller.AveragePrice():#.##}");
+    }
+
+    // Initialize the book database with some test books:
+    static void AddBooks(BookDB bookDB)
+    {
+        bookDB.AddBook("The C Programming Language", "Brian W. Kernighan and Dennis M. Ritchie", 19.95m, true);
+        bookDB.AddBook("The Unicode Standard 2.0", "The Unicode Consortium", 39.95m, true);
+        bookDB.AddBook("The MS-DOS Encyclopedia", "Ray Duncan", 129.95m, false);
+        bookDB.AddBook("Dogbert's Clues for the Clueless", "Scott Adams", 12.00m, true);
+    }
+}
+/* Output:
+Paperback Book Titles:
+   The C Programming Language
+   The Unicode Standard 2.0
+   Dogbert's Clues for the Clueless
+Average Paperback Book Price: $23.97
+*/

docs/csharp/programming-guide/delegates/snippets/DelegateExamples.csproj

@@ -0,0 +1,11 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>true</ImplicitUsings>
+
+    <StartupObject>Bookstore.Test</StartupObject>
+  </PropertyGroup>
+</Project>

docs/csharp/programming-guide/delegates/snippets/HowToDeclareAndUse.cs

@@ -0,0 +1,48 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace DelegateExamples;
+public class HowToDeclareAndUse
+{
+    //<DeclareNamedDelegate>
+    // Declare a delegate.
+    delegate void NotifyCallback(string str);
+
+    // Declare a method with the same signature as the delegate.
+    static void Notify(string name)
+    {
+        Console.WriteLine($"Notification received for: {name}");
+    }
+    //</DeclareNamedDelegate>
+
+
+    public static void Examples()
+    {
+        //<CreateNamedInstance>
+        // Create an instance of the delegate.
+        NotifyCallback del1 = new NotifyCallback(Notify);
+        //</CreateNamedInstance>
+
+        //<MethodGroup>
+        NotifyCallback del2 = Notify;
+        //</MethodGroup>
+
+        //<AnonymousMethod>
+        // Instantiate NotifyCallback by using an anonymous method.
+        NotifyCallback del3 = delegate (string name)
+        {
+            Console.WriteLine($"Notification received for: {name}");
+        };
+        //</AnonymousMethod>
+
+        //<LambdaExpression>
+        // Instantiate NotifyCallback by using a lambda expression.
+        NotifyCallback del4 = name => Console.WriteLine($"Notification received for: {name}");
+        //</LambdaExpression>
+
+    }
+
+}