> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# C# Multicast Delegate
A multicast delegate in C# is a delegate object that holds references to multiple methods within a single invocation list. When the multicast delegate is invoked, it executes all the methods in its invocation list synchronously, in the exact order they were added. Under the hood, all C# delegates implicitly inherit from the `System.MulticastDelegate` class, which in turn inherits from `System.Delegate`.
You construct a multicast delegate by combining individual delegate instances using the overloaded `+` or `+=` operators. Conversely, you remove methods from the invocation list using the `-` or `-=` operators.
```csharp theme={"dark"}
public delegate void OperationDelegate(string message);
public class MulticastMechanics
{
public void MethodA(string msg) => Console.WriteLine($"A: {msg}");
public void MethodB(string msg) => Console.WriteLine($"B: {msg}");
public void MethodC(string msg) => Console.WriteLine($"C: {msg}");
public void Execute()
{
// 1. Instantiate the initial delegate
OperationDelegate del = MethodA;
// 2. Combine delegates to create a multicast delegate
del += MethodB;
del += MethodC;
// 3. Invocation: Executes MethodA, then MethodB, then MethodC
del("Executing sequence");
// 4. Remove a delegate from the invocation list
del -= MethodB;
// 5. Invocation: Executes MethodA, then MethodC
del("Executing modified sequence");
}
}
```
## Architectural Characteristics
**Immutability**
Delegate instances in C# are immutable. When you use the `+=` operator, the compiler translates this into a call to `Delegate.Combine()`. This method does not mutate the existing delegate; instead, it allocates and returns a completely new delegate instance containing the merged invocation lists. The `-=` operator similarly calls `Delegate.Remove()`, returning a new instance with the specified method omitted.
**Return Value Resolution**
While multicast delegates typically define a `void` return type, they are permitted to return values. If a multicast delegate has a non-void return type, the caller receives the return value of the *last* method executed in the invocation list. The return values of all preceding methods are evaluated but discarded.
```csharp theme={"dark"}
public delegate int NumberDelegate();
public class ReturnValueMechanics
{
public int ReturnOne() => 1;
public int ReturnTwo() => 2;
public void Execute()
{
NumberDelegate del = ReturnOne;
del += ReturnTwo;
// result will be 2. The return value of ReturnOne is lost.
int result = del();
}
}
```
**Exception Propagation**
Because a multicast delegate processes its invocation list sequentially, an unhandled exception thrown by any method in the list will immediately halt execution. The exception propagates up the call stack to the invoker, and any subsequent methods remaining in the invocation list are not executed.
**Manual Invocation Control**
To bypass default behaviors—such as capturing all return values or preventing a single exception from halting the entire chain—you can manually iterate through the invocation list using the `GetInvocationList()` method. This method returns an array of `System.Delegate` objects representing the individual methods.
```csharp theme={"dark"}
public void ExecuteSafely(OperationDelegate multiDel)
{
if (multiDel == null) return;
// Extract the underlying array of individual delegates
Delegate[] invocationList = multiDel.GetInvocationList();
foreach (OperationDelegate singleDel in invocationList)
{
try
{
// Invoke each delegate independently
singleDel.Invoke("Safe execution");
}
catch (Exception ex)
{
// Handle exception without breaking the multicast chain
Console.WriteLine($"Delegate threw an exception: {ex.Message}");
}
}
}
```
Tired of Poor C# Skills? Fix That With Deep Grasping!
Learn More
