5.3 Removing Individual Delegates from Multicast Delegates

You want to remove an individual delegate from the invocation list of a multicast delegate.

Technique

Use the subtraction assignment operator to remove a delegate that appears at any point within the invocation list of a multicast delegate. You can use the same object that you used to add the delegate and allow the delegate class to find the corresponding delegate within the multicast delegate:

 StringPrinterDelegate.PrintString[] printDelegates =     new StringPrinterDelegate.PrintString[3]; StringPrinterDelegate.PrintString stringPrinters; printDelegates[0] = new StringPrinterDelegate.PrintString( NormalPrint ); printDelegates[1] = new StringPrinterDelegate.PrintString( FirstCharPrint ); printDelegates[2] = new StringPrinterDelegate.PrintString( LastCharPrint ); stringPrinters = (StringPrinterDelegate.PrintString)     Delegate.Combine( printDelegates ); // remove index 1 from invocation list stringPrinters -= printDelegates[1]; 

You can also access the invocation list directly and use an individual delegate with the subtraction assignment operator to remove the delegate:

 Delegate[] delegateList = stringPrinters.GetInvocationList(); stringPrinters -= (StringPrinterDelegate.PrintString)     delegateList[delegateList.Length-1]; 

To remove a range of delegates, you must use another multicast delegate whose invocation list contains the delegates you want to remove. When you use the static Remove method defined in System.Delegate , you remove the last occurrence of a list of delegates within a source multicast delegate. The list of delegates to remove is contained within the second parameter to the function:

 Delegate.Remove( delegateSource, delegateList ); 

If you, however, want to remove all occurrences of an invocation list from a multicast delegate, you can use the RemoveAll static method. Whereas the Remove function only removes the last occurrence of an invocation list, RemoveAll removes any and all occurrences of that list within a multicast delegate. The parameters of this method are the same as those for the Remove method.

Comments

As in physics where every action has an equal and opposite reaction, every addition should have an equal and opposite subtraction within an API. In the recipes leading up to this one, you looked at different ways to add delegates to form multicast delegates. This recipe takes the opposite approach and shows you how to remove individual delegates.

The process of removing delegates is essentially the same but, of course, uses different operator and method names . The easiest way to remove a delegate from a multicast delegate is to use the subtraction assignment operator. If the variables that were used to create the initial delegate objects are still within scope, you can use those as the operands to the subtraction assignment operator. When you do so, the delegate class uses object equality methods to find the correct delegate within its invocation list and remove that delegate. If however those variables are no longer in scope, you can still remove them by accessing the invocation list directly via the GetInvocationList method. It simply returns an array of delegate objects, which you can then index to retrieve the delegate you want to remove.

One thing we haven't mentioned up to this point is that you can combine multicast delegates with other multicast delegates. The previous samples showed how to combine single delegates to form a multicast delegate, but the process is the same if you want to then take the resultant multicast delegate and combine it with the invocation list of another multicast delegate. This process results in a merge of the two invocation lists of those multicast delegates to form yet another object. Likewise, you can remove the invocation list of one multicast delegate from the invocation list of another, as mentioned earlier. If you call the Remove method defined in System.Delegate , the delegate class finds the matching list of delegates in a source multicast delegate and removes the last occurrence of that list in its invocation list.

In other words, just as you can add the list of delegates from one multicast delegate to another, you can also turn around and remove that list. If a certain invocation list was added multiple times, then only the last occurrence of that list is removed from the multicast delegate. In other words, you have to call Remove for each associated Combine . If you would rather remove all invocation lists from a multicast delegate given another list, you can call the RemoveAll method. Therefore, any time a matching invocation list appears in the source multicast delegate, it is removed regardless of its location in the entire list.