Add examples for BaseSocketClient.Events

src/Discord.Net.Examples/WebSocket/BaseSocketClient.Events.Examples.cs

@@ -0,0 +1,90 @@
+#region ReactionAdded
+public void HookReactionAdded(BaseSocketClient client)
+{
+    client.ReactionAdded += HandleReactionAddedAsync;
+}
+public async Task HandleReactionAddedAsync(Cacheable<IUserMessage, ulong> cachedMessage, 
+    ISocketMessageChannel originChannel, SocketReaction reaction)
+{
+    var message = await cachedMessage.GetOrDownloadAsync();
+    if (message != null && reaction.User.IsSpecified)
+        Console.WriteLine($"{message.User.Value} just added a reaction '{reaction.Emote}' " + 
+            $"to {message.Author}'s message ({message.Id}).");
+}
+#endregion
+
+#region ChannelCreated
+public void HookChannelCreated(BaseSocketClient client)
+{
+    client.ChannelCreated += HandleChannelCreated;
+}
+public Task HandleChannelCreated(SocketChannel channel)
+{
+    Console.WriteLine($"A new channel '{channel.Name}'({channel.Id}, {channel.GetType()})"
+        + $"has been created at {channel.CreatedAt}.");
+    return Task.CompletedTask;
+}
+#endregion
+
+#region ChannelDestroyed
+public void HookChannelDestroyed(BaseSocketClient client)
+{
+    client.ChannelDestroyed += HandleChannelDestroyed;
+}
+public Task HandleChannelDestroyed(SocketChannel channel)
+{
+    Console.WriteLine($"A new channel '{channel.Name}'({channel.Id}, {channel.GetType()}) has been deleted.");
+    return Task.CompletedTask;
+}
+#endregion
+
+#region ChannelUpdated
+public void HookChannelUpdated(BaseSocketClient client)
+{
+    client.ChannelUpdated += HandleChannelRename;
+}
+public Task HandleChannelRename(SocketChannel beforeChannel, SocketChannel afterChannel)
+{
+    if (beforeChannel.Name != afterChannel.Name)
+        Console.WriteLine($"A channel ({beforeChannel.Id}) is renamed from {beforeChannel.Name} to {afterChannel.Name}.");
+    return Task.CompletedTask;
+}
+#endregion
+
+#region MessageReceived
+private readonly ulong[] _targetUserIds = new {168693960628371456, 53905483156684800};
+public void HookMessageReceived(BaseSocketClient client)
+{
+    client.MessageReceived += HandleMessageReceived;
+}
+public Task HandleMessageReceived(SocketMessage message)
+{
+    // check if the message is a user message as opposed to a system message (e.g. Clyde, pins, etc.)
+    if (!(message is SocketUserMessage userMessage)) return;
+    // check if the message origin is a guild message channel
+    if (!(userMessage.Channel is SocketTextChannel textChannel)) return;
+    // check if the target user was mentioned
+    var targetUsers = userMessage.MentionedUsers.Where(x => _targetUserIds.Contains(x));
+    if (targetUsers == null) return;
+    foreach (var targetUser in targetUsers)
+        Console.WriteLine($"{targetUser} was mentioned in the message '{message.Content}' by {message.Author}.");
+    return Task.CompletedTask;
+}
+#endregion
+
+#region MessageDeleted
+public void HookMessageDeleted(BaseSocketClient client)
+{
+    client.MessageDeleted += HandleMessageDelete;
+}
+public Task HandleMessageDelete(Cacheable<IMessage, ulong> cachedMessage, ISocketMessageChannel channel)
+{
+    // check if the message exists in cache; if not, we cannot report what was removed
+    if (!cachedMessage.HasValue) return;
+    var message = cachedMessage.Value;
+    Console.WriteLine($"A message ({message.Id}) from {message.Author} was removed from the channel {channel.Name} ({channel.Id}):"
+        + Environment.NewLine
+        + message.Content);
+    return Task.CompletedTask;
+}
+#endregion

src/Discord.Net.WebSocket/BaseSocketClient.Events.cs

@@ -18,6 +18,9 @@ namespace Discord.WebSocket
         ///         see the derived classes of <see cref="SocketChannel"/> for more details.
         ///     </para>
         /// </remarks>
+        /// <example>
+        ///     <code source="..\Discord.Net.Examples\WebSocket\BaseSocketClient.Events.Examples.cs" region="ChannelCreated"></code>
+        /// </example>
         public event Func<SocketChannel, Task> ChannelCreated 
         {
             add { _channelCreatedEvent.Add(value); }
@@ -36,6 +39,9 @@ namespace Discord.WebSocket
         ///         see the derived classes of <see cref="SocketChannel"/> for more details.
         ///     </para>
         /// </remarks>
+        /// <example>
+        ///     <code source="..\Discord.Net.Examples\WebSocket\BaseSocketClient.Events.Examples.cs" region="ChannelDestroyed"></code>
+        /// </example>
         public event Func<SocketChannel, Task> ChannelDestroyed {
             add { _channelDestroyedEvent.Add(value); }
             remove { _channelDestroyedEvent.Remove(value); }
@@ -54,6 +60,9 @@ namespace Discord.WebSocket
         ///         <see cref="SocketChannel"/> for more details.
         ///     </para>
         /// </remarks>
+        /// <example>
+        ///     <code source="..\Discord.Net.Examples\WebSocket\BaseSocketClient.Events.Examples.cs" region="ChannelUpdated"></code>
+        /// </example>
         public event Func<SocketChannel, SocketChannel, Task> ChannelUpdated {
             add { _channelUpdatedEvent.Add(value); }
             remove { _channelUpdatedEvent.Remove(value); }
@@ -74,6 +83,10 @@ namespace Discord.WebSocket
         ///         derived classes of <see cref="SocketMessage"/> for more details.
         ///     </para>
         /// </remarks>
+        /// <example>
+        ///     The example below checks if the newly received message contains the target user.
+        ///     <code source="..\Discord.Net.Examples\WebSocket\BaseSocketClient.Events.Examples.cs" region="MessageReceived"></code>
+        /// </example>
         public event Func<SocketMessage, Task> MessageReceived {
             add { _messageReceivedEvent.Add(value); }
             remove { _messageReceivedEvent.Remove(value); }
@@ -102,6 +115,9 @@ namespace Discord.WebSocket
         ///         <see cref="ISocketMessageChannel"/> parameter.
         ///     </para>
         /// </remarks>
+        /// <example>
+        ///     <code source="..\Discord.Net.Examples\WebSocket\BaseSocketClient.Events.Examples.cs" region="MessageDeleted"></code>
+        /// </example>
         public event Func<Cacheable<IMessage, ulong>, ISocketMessageChannel, Task> MessageDeleted {
             add { _messageDeletedEvent.Add(value); }
             remove { _messageDeletedEvent.Remove(value); }
@@ -134,6 +150,34 @@ namespace Discord.WebSocket
         }
         internal readonly AsyncEvent<Func<Cacheable<IMessage, ulong>, SocketMessage, ISocketMessageChannel, Task>> _messageUpdatedEvent = new AsyncEvent<Func<Cacheable<IMessage, ulong>, SocketMessage, ISocketMessageChannel, Task>>();
         /// <summary> Fired when a reaction is added to a message. </summary>
+        /// <remarks>
+        ///     <para>
+        ///         This event is fired when a reaction is added to a user message. The event handler must return a
+        ///         <see cref="Task"/> and accept a <see cref="Cacheable{TEntity,TId}"/>, an 
+        ///         <see cref="ISocketMessageChannel"/>, and a <see cref="SocketReaction"/> as its parameter.
+        ///     </para>
+        ///     <para>
+        ///         If caching is enabled via <see cref="DiscordSocketConfig"/>, the
+        ///         <see cref="Cacheable{TEntity,TId}"/> entity will contain the original message; otherwise, in event
+        ///         that the message cannot be retrieved, the snowflake ID of the message is preserved in the 
+        ///         <see cref="ulong"/>.
+        ///     </para>
+        ///     <para>
+        ///         The source channel of the reaction addition will be passed into the 
+        ///         <see cref="ISocketMessageChannel"/> parameter.
+        ///     </para>
+        ///     <para>
+        ///         The reaction that was added will be passed into the <see cref="SocketReaction"/> parameter.
+        ///     </para>
+        ///     <note>
+        ///         When fetching the reaction from this event, a user may not be provided under 
+        ///         <see cref="SocketReaction.User"/>. Please see the documentation of the property for more
+        ///         information.
+        ///     </note>
+        /// </remarks>
+        /// <example>
+        ///     <code source="..\Discord.Net.Examples\WebSocket\BaseSocketClient.Events.Examples.cs" region="ReactionAdded"></code>
+        /// </example>
         public event Func<Cacheable<IUserMessage, ulong>, ISocketMessageChannel, SocketReaction, Task> ReactionAdded {
             add { _reactionAddedEvent.Add(value); }
             remove { _reactionAddedEvent.Remove(value); }