CA1009: Declare event handlers correctly

Cause

A delegate that handles a public or protected event does not have the correct signature, return type, or parameter names.

Rule Description

Event handler methods take two parameters. The first is of type System.Object and is named 'sender'. This is the object that raised the event. The second parameter is of type System.EventArgs and is named 'e'. This is the data that is associated with the event. For example, if the event is raised whenever a file is opened, the event data typically contains the name of the file.

Event handler methods should not return a value. In the C# programming language, this is indicated by the return type void. An event handler can invoke multiple methods in multiple objects. If the methods were allowed to return a value, multiple return values would occur for each event, and only the value of the last method that was invoked would be available.

How to Fix Violations

To fix a violation of this rule, correct the signature, return type, or parameter names of the delegate. For details, see the following example.

When to Suppress Warnings

Do not suppress a warning from this rule.

Example

The following example shows a delegate that is suited to handling events. The methods that can be invoked by this event handler comply with the signature that is specified in the Design Guidelines. AlarmEventHandler is the type name of the delegate. AlarmEventArgs derives from the base class for event data, EventArgs, and holds alarm event data.

Imports System

Namespace DesignLibrary

   Public Delegate Sub AlarmEventHandler(sender As Object, e As AlarmEventArgs)

   Public Class AlarmEventArgs
      Inherits EventArgs
   End Class 

End Namespace

using System;

namespace DesignLibrary
{
   public class AlarmEventArgs : EventArgs {}
   public delegate void AlarmEventHandler(object sender, AlarmEventArgs e);
}

using namespace System;

namespace DesignLibrary
{
   public ref class AlarmEventArgs : public EventArgs {};
   public delegate void AlarmEventHandler(
      Object^ sender, AlarmEventArgs^ e);
}

Related Rules

CA2109: Review visible event handlers

See Also

Reference

System.EventArgs

System.Object

Concepts

Events and Delegates