Como: realizar e cancelar a assinatura de eventos (Guia de Programação em C#)How to: Subscribe to and Unsubscribe from Events (C# Programming Guide)

Você assina um evento publicado por outra classe quando quer escrever um código personalizado que é chamado quando esse evento é gerado.You subscribe to an event that is published by another class when you want to write custom code that is called when that event is raised. Por exemplo, você pode assinar o evento click de um botão para fazer com que seu aplicativo faça algo útil quando o usuário clicar no botão.For example, you might subscribe to a button's click event in order to make your application do something useful when the user clicks the button.

Para assinar eventos usando o IDE do Visual StudioTo subscribe to events by using the Visual Studio IDE

  1. Se você não vir a janela Propriedades, no modo de exibição de Design, clique com o botão direito do mouse no formulário ou controle para o qual deseja criar um manipulador de eventos e selecione Propriedades.If you cannot see the Properties window, in Design view, right-click the form or control for which you want to create an event handler, and select Properties.

  2. Na parte superior da janela Propriedades, clique no ícone Eventos.On top of the Properties window, click the Events icon.

  3. Clique duas vezes no evento que deseja criar, por exemplo, o evento Load.Double-click the event that you want to create, for example the Load event.

    O Visual C# cria um método de manipulador de eventos vazio e adiciona-o ao código.Visual C# creates an empty event handler method and adds it to your code. Como alternativa, você pode adicionar o código manualmente no modo de exibição Código.Alternatively you can add the code manually in Code view. Por exemplo, as linhas de código a seguir declaram um método de manipulador de eventos que será chamado quando a classe Form gerar o evento Load.For example, the following lines of code declare an event handler method that will be called when the Form class raises the Load event.

    private void Form1_Load(object sender, System.EventArgs e)
    {
        // Add your form load event handling code here.
    }
    

    A linha de código que é necessária para assinar o evento também é gerada automaticamente no método InitializeComponent no arquivo Form1.Designer.cs em seu projeto.The line of code that is required to subscribe to the event is also automatically generated in the InitializeComponent method in the Form1.Designer.cs file in your project. Ele é semelhante a isto:It resembles this:

    this.Load += new System.EventHandler(this.Form1_Load);  
    

Para assinar eventos de forma programáticaTo subscribe to events programmatically

  1. Defina um método de manipulador de eventos cuja assinatura corresponda à assinatura do delegado do evento.Define an event handler method whose signature matches the delegate signature for the event. Por exemplo, se o evento se basear no tipo de delegado EventHandler, o código a seguir representará o stub do método:For example, if the event is based on the EventHandler delegate type, the following code represents the method stub:

    void HandleCustomEvent(object sender, CustomEventArgs a)  
    {  
       // Do something useful here.  
    }  
    
  2. Use o operador de atribuição de adição (+=) para anexar um manipulador de eventos ao evento.Use the addition assignment operator (+=) to attach an event handler to the event. No exemplo a seguir, suponha que um objeto chamado publisher tem um evento chamado RaiseCustomEvent.In the following example, assume that an object named publisher has an event named RaiseCustomEvent. Observe que a classe do assinante precisa de uma referência à classe do editor para assinar seus eventos.Note that the subscriber class needs a reference to the publisher class in order to subscribe to its events.

    publisher.RaiseCustomEvent += HandleCustomEvent;  
    

    Observe que a sintaxe anterior é nova no C# 2.0.Note that the previous syntax is new in C# 2.0. Ela é exatamente equivalente à sintaxe C# 1.0, em que o delegado de encapsulamento deve ser criado explicitamente usando a palavra-chave new:It is exactly equivalent to the C# 1.0 syntax in which the encapsulating delegate must be explicitly created by using the new keyword:

    publisher.RaiseCustomEvent += new CustomEventHandler(HandleCustomEvent);  
    

    Você também pode usar uma expressão lambda para especificar um manipulador de eventos:You also can use a lambda expression to specify an event handler:

    public Form1()  
    {  
        InitializeComponent();  
        this.Click += (s,e) =>
            {
                MessageBox.Show(((MouseEventArgs)e).Location.ToString());
            };
    }  
    

Para assinar eventos usando um método anônimoTo subscribe to events by using an anonymous method

  • Se não precisar cancelar a assinatura de um evento posteriormente, você pode usar o operador de atribuição de adição (+=) para anexar um método anônimo ao evento.If you will not have to unsubscribe to an event later, you can use the addition assignment operator (+=) to attach an anonymous method to the event. No exemplo a seguir, suponha que um objeto chamado publisher tenha um evento chamado RaiseCustomEvent e que uma classe CustomEventArgs também tenha sido definida para conter algum tipo de informação de evento específico.In the following example, assume that an object named publisher has an event named RaiseCustomEvent and that a CustomEventArgs class has also been defined to carry some kind of specialized event information. Observe que a classe do assinante precisa de uma referência a publisher para assinar seus eventos.Note that the subscriber class needs a reference to publisher in order to subscribe to its events.

    publisher.RaiseCustomEvent += delegate(object o, CustomEventArgs e)  
    {  
      string s = o.ToString() + " " + e.ToString();  
      Console.WriteLine(s);  
    };  
    

    É importante observar que você não pode, com facilidade, cancelar a assinatura de um evento se tiver usado uma função anônima para assiná-lo.It is important to notice that you cannot easily unsubscribe from an event if you used an anonymous function to subscribe to it. Para cancelar a assinatura nesse cenário, é necessário voltar ao código em que você assinou o evento, armazenar o método anônimo em uma variável do delegado e, então, adicionar o delegado ao evento.To unsubscribe in this scenario, it is necessary to go back to the code where you subscribe to the event, store the anonymous method in a delegate variable, and then add the delegate to the event. De modo geral, é recomendável que você não use funções anônimas para assinar eventos se precisar cancelar a assinatura do evento posteriormente no código.In general, we recommend that you do not use anonymous functions to subscribe to events if you will have to unsubscribe from the event at some later point in your code. Para obter mais informações sobre funções anônimas, consulte Funções anônimas.For more information about anonymous functions, see Anonymous Functions.

Cancelando a assinaturaUnsubscribing

Para impedir que o manipulador de eventos seja invocado quando o evento for gerado, cancele a assinatura do evento.To prevent your event handler from being invoked when the event is raised, unsubscribe from the event. Para evitar perda de recursos, cancele a assinatura de eventos antes de descartar um objeto de assinante.In order to prevent resource leaks, you should unsubscribe from events before you dispose of a subscriber object. Até que você cancele a assinatura de um evento, o delegado multicast subjacente ao evento no objeto de publicação terá uma referência ao delegado que encapsula o manipulador de eventos do assinante.Until you unsubscribe from an event, the multicast delegate that underlies the event in the publishing object has a reference to the delegate that encapsulates the subscriber's event handler. Desde que o objeto de publicação contenha essa referência, a coleta de lixo não excluirá seu objeto de assinante.As long as the publishing object holds that reference, garbage collection will not delete your subscriber object.

Para cancelar a assinatura de um eventoTo unsubscribe from an event

  • Use o operador de atribuição de subtração (-=) para cancelar a assinatura de um evento:Use the subtraction assignment operator (-=) to unsubscribe from an event:

    publisher.RaiseCustomEvent -= HandleCustomEvent;  
    

    Quando todos os assinantes tiverem cancelado a assinatura de um evento, a instância do evento na classe do publicador será definida como null.When all subscribers have unsubscribed from an event, the event instance in the publisher class is set to null.

Consulte tambémSee also