CA1003: Algemene gebeurtenis-handler-exemplaren gebruiken

Oorzaak

Een type bevat een gedelegeerde die niets retourneert en waarvan de signatuur twee parameters bevat (de eerste een object en de tweede een type dat kan worden toegewezen aan EventArgs) en de bijbehorende assembly die .NET als doelplatform heeft.

Deze regel kijkt standaard alleen naar extern zichtbare typen, maar dit kan worden geconfigureerd.

Beschrijving van regel

Voor .NET Framework 2.0 moest, om aangepaste informatie door te geven aan de event handler, een nieuwe gedelegeerde worden gedeclareerd die een klasse specificeerde die was afgeleid van de System.EventArgs klasse. In .NET Framework 2.0 en latere versies stelt de generieke System.EventHandler<TEventArgs> gedelegeerde elke klasse die is afgeleid van EventArgs in staat om in combinatie met de event-handler te worden gebruikt.

Hoe schendingen te verhelpen

Als u een schending van deze regel wilt oplossen, verwijdert u de gemachtigde en vervangt u het gebruik ervan door de System.EventHandler<TEventArgs> gemachtigde te gebruiken.

Als de gemachtigde automatisch wordt gegenereerd door de Visual Basic-compiler, wijzigt u de syntaxis van de gebeurtenisdeclaratie om de System.EventHandler<TEventArgs> gemachtigde te gebruiken.

Wanneer waarschuwingen onderdrukken

Een waarschuwing van deze regel niet onderdrukken.

Code configureren om te analyseren

Gebruik de volgende optie om te configureren op welke onderdelen van uw codebase deze regel moet worden uitgevoerd.

• Specifieke API-oppervlakken opnemen

U kunt deze optie configureren voor alleen deze regel, voor alle regels waarop deze van toepassing is, of voor alle regels in deze categorie (ontwerp) waarop deze van toepassing is. Zie de configuratieopties voor de codekwaliteitsregel voor meer informatie.

Specifieke API-oppervlakken opnemen

U kunt configureren op welke onderdelen van uw codebase deze regel moet worden uitgevoerd, op basis van hun toegankelijkheid, door de optie api_surface in te stellen. Als u bijvoorbeeld wilt opgeven dat de regel alleen moet worden uitgevoerd op het niet-openbare API-oppervlak, voegt u het volgende sleutel-waardepaar toe aan een .editorconfig-bestand in uw project:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Voorbeeld

In het volgende voorbeeld ziet u een gemachtigde die de regel schendt. In het Visual Basic-voorbeeld beschrijven opmerkingen hoe u het voorbeeld kunt wijzigen om aan de regel te voldoen. Voor het C#-voorbeeld volgt een voorbeeld waarin de gewijzigde code wordt weergegeven.

Imports System

Namespace ca1003

    Public Class CustomEventArgs
        Inherits EventArgs

        Public info As String = "data"

    End Class

    Public Class ClassThatRaisesEvent

        ' This statement creates a new delegate, which violates the rule.
        Event SomeEvent(sender As Object, e As CustomEventArgs)

        ' To satisfy the rule, comment out the previous line 
        ' and uncomment the following line.
        'Event SomeEvent As EventHandler(Of CustomEventArgs)

        Protected Overridable Sub OnSomeEvent(e As CustomEventArgs)
            RaiseEvent SomeEvent(Me, e)
        End Sub

        Sub SimulateEvent()
            OnSomeEvent(New CustomEventArgs())
        End Sub

    End Class

    Public Class ClassThatHandlesEvent

        Sub New(eventRaiser As ClassThatRaisesEvent)
            AddHandler eventRaiser.SomeEvent, AddressOf HandleEvent
        End Sub

        Private Sub HandleEvent(sender As Object, e As CustomEventArgs)
            Console.WriteLine("Event handled: {0}", e.info)
        End Sub

    End Class

    Class Test

        Shared Sub Main1003()

            Dim eventRaiser As New ClassThatRaisesEvent()
            Dim eventHandler As New ClassThatHandlesEvent(eventRaiser)

            eventRaiser.SimulateEvent()

        End Sub

    End Class

End Namespace

// This delegate violates the rule.
public delegate void CustomEventHandler(object sender, CustomEventArgs e);

public class CustomEventArgs : EventArgs
{
    public string info = "data";
}

public class ClassThatRaisesEvent
{
    public event CustomEventHandler? SomeEvent;

    protected virtual void OnSomeEvent(CustomEventArgs e)
    {
        SomeEvent?.Invoke(this, e);
    }

    public void SimulateEvent()
    {
        OnSomeEvent(new CustomEventArgs());
    }
}

public class ClassThatHandlesEvent
{
    public ClassThatHandlesEvent(ClassThatRaisesEvent eventRaiser)
    {
        eventRaiser.SomeEvent += new CustomEventHandler(HandleEvent);
    }

    private void HandleEvent(object sender, CustomEventArgs e)
    {
        Console.WriteLine($"Event handled: {e.info}");
    }
}

class Test
{
    static void MainEvent()
    {
        var eventRaiser = new ClassThatRaisesEvent();
        var eventHandler = new ClassThatHandlesEvent(eventRaiser);

        eventRaiser.SimulateEvent();
    }
}

Met het volgende codefragment wordt de declaratie van de gemachtigde uit het vorige voorbeeld verwijderd, die voldoet aan de regel. Het vervangt het gebruik in de ClassThatRaisesEvent en ClassThatHandlesEvent methoden door gebruik te maken van de System.EventHandler<TEventArgs> gemachtigde.

public class CustomEventArgs : EventArgs
{
    public string info = "data";
}

public class ClassThatRaisesEvent
{
    public event EventHandler<CustomEventArgs>? SomeEvent;

    protected virtual void OnSomeEvent(CustomEventArgs e)
    {
        SomeEvent?.Invoke(this, e);
    }

    public void SimulateEvent()
    {
        OnSomeEvent(new CustomEventArgs());
    }
}

public class ClassThatHandlesEvent
{
    public ClassThatHandlesEvent(ClassThatRaisesEvent eventRaiser)
    {
        eventRaiser.SomeEvent += new EventHandler<CustomEventArgs>(HandleEvent);
    }

    private void HandleEvent(object? sender, CustomEventArgs e)
    {
        Console.WriteLine($"Event handled: {e.info}");
    }
}

class Test
{
    static void MainEvent()
    {
        var eventRaiser = new ClassThatRaisesEvent();
        var eventHandler = new ClassThatHandlesEvent(eventRaiser);

        eventRaiser.SimulateEvent();
    }
}

Gerelateerde regels

• CA1005: Vermijd overmatige parameters voor algemene typen
• CA1010: Verzamelingen moeten algemene interface implementeren
• CA1000: Geen statische leden declareren voor algemene typen
• CA1002: algemene lijsten niet beschikbaar maken

Zie ook

• Generics