Add DiscordShardedClient sample project & Client FAQ entry. (#1177)

* Add DiscordShardedClient sample project & Client FAQ entry.

* Revise language, fix typo, add xrefs

* Adjust placement of message handler.

* Resolve DI issue with initialized client; properly initialize command handling service.

Discord.Net.sln

@@ -26,10 +26,12 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Discord.Net.Analyzers", "sr
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Samples", "Samples", "{BB59D5B5-E7B0-4BF4-8F82-D14431B2799B}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "01_basic_ping_bot", "samples\01_basic_ping_bot\01_basic_ping_bot.csproj", "{F2FF84FB-F6AD-47E5-9EE5-18206CAE136E}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "01_basic_ping_bot", "samples\01_basic_ping_bot\01_basic_ping_bot.csproj", "{F2FF84FB-F6AD-47E5-9EE5-18206CAE136E}"
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "02_commands_framework", "samples\02_commands_framework\02_commands_framework.csproj", "{4E1F1F40-B1DD-40C9-A4B1-A2046A4C9C76}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "03_sharded_client", "samples\03_sharded_client\03_sharded_client.csproj", "{9B4C4AFB-3D15-44C6-9E36-12ED625AAA26}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -160,6 +162,18 @@ Global
 		{4E1F1F40-B1DD-40C9-A4B1-A2046A4C9C76}.Release|x64.Build.0 = Release|Any CPU
 		{4E1F1F40-B1DD-40C9-A4B1-A2046A4C9C76}.Release|x86.ActiveCfg = Release|Any CPU
 		{4E1F1F40-B1DD-40C9-A4B1-A2046A4C9C76}.Release|x86.Build.0 = Release|Any CPU
+		{9B4C4AFB-3D15-44C6-9E36-12ED625AAA26}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{9B4C4AFB-3D15-44C6-9E36-12ED625AAA26}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{9B4C4AFB-3D15-44C6-9E36-12ED625AAA26}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{9B4C4AFB-3D15-44C6-9E36-12ED625AAA26}.Debug|x64.Build.0 = Debug|Any CPU
+		{9B4C4AFB-3D15-44C6-9E36-12ED625AAA26}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{9B4C4AFB-3D15-44C6-9E36-12ED625AAA26}.Debug|x86.Build.0 = Debug|Any CPU
+		{9B4C4AFB-3D15-44C6-9E36-12ED625AAA26}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{9B4C4AFB-3D15-44C6-9E36-12ED625AAA26}.Release|Any CPU.Build.0 = Release|Any CPU
+		{9B4C4AFB-3D15-44C6-9E36-12ED625AAA26}.Release|x64.ActiveCfg = Release|Any CPU
+		{9B4C4AFB-3D15-44C6-9E36-12ED625AAA26}.Release|x64.Build.0 = Release|Any CPU
+		{9B4C4AFB-3D15-44C6-9E36-12ED625AAA26}.Release|x86.ActiveCfg = Release|Any CPU
+		{9B4C4AFB-3D15-44C6-9E36-12ED625AAA26}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -173,6 +187,7 @@ Global
 		{BBA8E7FB-C834-40DC-822F-B112CB7F0140} = {CC3D4B1C-9DE0-448B-8AE7-F3F1F3EC5C3A}
 		{F2FF84FB-F6AD-47E5-9EE5-18206CAE136E} = {BB59D5B5-E7B0-4BF4-8F82-D14431B2799B}
 		{4E1F1F40-B1DD-40C9-A4B1-A2046A4C9C76} = {BB59D5B5-E7B0-4BF4-8F82-D14431B2799B}
+		{9B4C4AFB-3D15-44C6-9E36-12ED625AAA26} = {BB59D5B5-E7B0-4BF4-8F82-D14431B2799B}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {D2404771-EEC8-45F2-9D71-F3373F6C1495}

docs/faq/basics/client-basics.md

@@ -63,4 +63,32 @@ use the cached message entity. Read more about it [here](xref:Guides.Concepts.Ev
 
 [MessageCacheSize]: xref:Discord.WebSocket.DiscordSocketConfig.MessageCacheSize
 [DiscordSocketConfig]: xref:Discord.WebSocket.DiscordSocketConfig
-[MessageUpdated]: xref:Discord.WebSocket.BaseSocketClient.MessageUpdated
+[MessageUpdated]: xref:Discord.WebSocket.BaseSocketClient.MessageUpdated
+
+## What is a shard/sharded client, and how is it different from the `DiscordSocketClient`?
+As your bot grows in popularity, it is recommended that you should section your bot off into separate processes.
+The [DiscordShardedClient] is essentially a class that allows you to easily create and manage multiple [DiscordSocketClient]
+instances, with each one serving a different amount of guilds.
+
+There are very few differences from the [DiscordSocketClient] class, and it is very straightforward
+to modify your existing code to use a [DiscordShardedClient] when necessary.
+
+1. You need to specify the total amount of shards, or shard ids, via [DiscordShardedClient]'s constructors.
+2. The [Connected], [Disconnected], [Ready], and [LatencyUpdated] events
+ are replaced with [ShardConnected], [ShardDisconnected], [ShardReady], and [ShardLatencyUpdated].
+3. Every event handler you apply/remove to the [DiscordShardedClient] is applied/removed to each shard.
+ If you wish to control a specific shard's events, you can access an individual shard through the `Shards` property.
+
+If you do not wish to use the [DiscordShardedClient] and instead reuse the same [DiscordSocketClient] code and manually shard them,
+you can do so by specifying the [ShardId] for the [DiscordSocketConfig] and pass that to the [DiscordSocketClient]'s constructor.
+
+[DiscordSocketClient]: xref:Discord.WebSocket.DiscordSocketClient
+[DiscordShardedClient]: xref:Discord.WebSocket.DiscordShardedClient
+[Connected]: xref:Discord.WebSocket.DiscordSocketClient.Connected
+[Disconnected]: xref:Discord.WebSocket.DiscordSocketClient.Disconnected
+[LatencyUpdated]: xref:Discord.WebSocket.DiscordSocketClient.LatencyUpdated
+[ShardConnected]: xref:Discord.WebSocket.DiscordShardedClient.ShardConnected
+[ShardDisconnected]: xref:Discord.WebSocket.DiscordShardedClient.ShardDisconnected
+[ShardReady]: xref:Discord.WebSocket.DiscordShardedClient.ShardReady
+[ShardLatencyUpdated]: xref:Discord.WebSocket.DiscordShardedClient.ShardLatencyUpdated
+[ShardId]: xref:Discord.WebSocket.DiscordSocketConfig.ShardId

samples/03_sharded_client/03_sharded_client.csproj

@@ -0,0 +1,14 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>netcoreapp2.1</TargetFramework>
+    <RootNamespace>_03_sharded_client</RootNamespace>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\Discord.Net.Commands\Discord.Net.Commands.csproj" />
+    <ProjectReference Include="..\..\src\Discord.Net.WebSocket\Discord.Net.WebSocket.csproj" />
+  </ItemGroup>
+
+</Project>

samples/03_sharded_client/Modules/PublicModule.cs

@@ -0,0 +1,17 @@
+using System.Threading.Tasks;
+using Discord.Commands;
+
+namespace _03_sharded_client.Modules
+{
+    // Remember to make your module reference the ShardedCommandContext
+    public class PublicModule : ModuleBase<ShardedCommandContext>
+    {
+        [Command("info")]
+        public async Task InfoAsync()
+        {
+            var msg = $@"Hi {Context.User}! There are currently {Context.Client.Shards} shards!
+                This guild is being served by shard number {Context.Client.GetShardFor(Context.Guild).ShardId}";
+            await ReplyAsync(msg);
+        }
+    }
+}

samples/03_sharded_client/Program.cs

@@ -0,0 +1,69 @@
+using System;
+using System.Threading.Tasks;
+using _03_sharded_client.Services;
+using Discord;
+using Discord.Commands;
+using Discord.WebSocket;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace _03_sharded_client
+{
+    // This is a minimal example of using Discord.Net's Sharded Client
+    // The provided DiscordShardedClient class simplifies having multiple
+    // DiscordSocketClient instances (or shards) to serve a large number of guilds.
+    class Program
+    {
+        private DiscordShardedClient _client;
+
+        static void Main(string[] args)
+            => new Program().MainAsync().GetAwaiter().GetResult();
+        public async Task MainAsync()
+        {
+            // You specify the amount of shards you'd like to have with the
+            // DiscordSocketConfig. Generally, it's recommended to 
+            // have 1 shard per 1500-2000 guilds your bot is in.
+            var config = new DiscordSocketConfig
+            {
+                TotalShards = 2
+            };
+
+            _client = new DiscordShardedClient(config);
+            var services = ConfigureServices();
+
+            // The Sharded Client does not have a Ready event.
+            // The ShardReady event is used instead, allowing for individual
+            // control per shard.
+            _client.ShardReady += ReadyAsync;
+            _client.Log += LogAsync;
+
+            await services.GetRequiredService<CommandHandlingService>().InitializeAsync();
+
+            await _client.LoginAsync(TokenType.Bot, Environment.GetEnvironmentVariable("token"));
+            await _client.StartAsync();
+
+            await Task.Delay(-1);
+        }
+
+        private IServiceProvider ConfigureServices()
+        {
+            return new ServiceCollection()
+                .AddSingleton(_client)
+                .AddSingleton<CommandService>()
+                .AddSingleton<CommandHandlingService>()
+                .BuildServiceProvider();
+        }
+
+
+        private Task ReadyAsync(DiscordSocketClient shard)
+        {
+            Console.WriteLine($"Shard Number {shard.ShardId} is connected and ready!");
+            return Task.CompletedTask;
+        }
+
+        private Task LogAsync(LogMessage log)
+        {
+            Console.WriteLine(log.ToString());
+            return Task.CompletedTask;
+        }
+    }
+}

samples/03_sharded_client/Services/CommandHandlingService.cs

@@ -0,0 +1,52 @@
+using System;
+using System.Reflection;
+using System.Threading.Tasks;
+using Microsoft.Extensions.DependencyInjection;
+using Discord;
+using Discord.Commands;
+using Discord.WebSocket;
+
+namespace _03_sharded_client.Services
+{
+    public class CommandHandlingService
+    {
+        private readonly CommandService _commands;
+        private readonly DiscordShardedClient _discord;
+        private readonly IServiceProvider _services;
+
+        public CommandHandlingService(IServiceProvider services)
+        {
+            _commands = services.GetRequiredService<CommandService>();
+            _discord = services.GetRequiredService<DiscordShardedClient>();
+            _services = services;
+        }
+
+        public async Task InitializeAsync()
+        {
+            await _commands.AddModulesAsync(Assembly.GetEntryAssembly(), _services);
+            _discord.MessageReceived += MessageReceivedAsync;
+        }
+
+        public async Task MessageReceivedAsync(SocketMessage rawMessage)
+        {
+            // Ignore system messages, or messages from other bots
+            if (!(rawMessage is SocketUserMessage message))
+                return;
+            if (message.Source != MessageSource.User)
+                return;
+
+            // This value holds the offset where the prefix ends
+            var argPos = 0;
+            if (!message.HasMentionPrefix(_discord.CurrentUser, ref argPos))
+                return;
+
+            // A new kind of command context, ShardedCommandContext can be utilized with the commands framework
+            var context = new ShardedCommandContext(_discord, message);
+            var result = await _commands.ExecuteAsync(context, argPos, _services);
+
+            if (result.Error.HasValue &&
+                result.Error.Value != CommandError.UnknownCommand) // it's bad practice to send 'unknown command' errors
+                await context.Channel.SendMessageAsync(result.ToString());
+        }
+    }
+}