Declare event handlers correctly

TypeName	DeclareEventHandlersCorrectly
CheckId	CA1009
Category	Microsoft.Design
Breaking Change	Breaking

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 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, there would be multiple return values for each event, and only the value of the last method 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 Exclude Warnings

Do not exclude a warning from this rule.

Example

The following example shows a delegate suitable for handling events. The methods that can be invoked by this event handler conform to the signature specified in the Design Guidelines. AlarmEventHandler is the delegate's type name. 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);
}

The following example shows a delegate suitable for handling events. The methods that can be invoked by this event handler conform to the signature specified in the Design Guidelines. AlarmEventHandler is the delegate's type name. 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);
}

Example

The following example shows a delegate suitable for handling events. The methods that can be invoked by this event handler conform to the signature specified in the Design Guidelines. AlarmEventHandler is the delegate's type name. 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);
}

The following example shows a delegate suitable for handling events. The methods that can be invoked by this event handler conform to the signature specified in the Design Guidelines. AlarmEventHandler is the delegate's type name. 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

Review visible event handlers

See Also

Reference

System.EventArgs
System.Object

Concepts

Events and Delegates