Adding Entity guides, flowcharts, better sample system. (#2054)

* initial

* Interaction glossary entry

* Sharded Interaction sample

* Renames into solution

* Debugging samples

* Modify target location for webhookclient

* Finalizing docs work, resolving docfx errors.

* Adding threaduser to user chart

* Add branch info to readme.

* Edits to user chart

* Resolve format for glossary entries

* Patch sln target

* Issue with file naming fixed

* Patch 1/x for builds

* Appending suggestions

samples/ShardedClient/Modules/InteractionModule.cs

@@ -0,0 +1,18 @@
+using Discord.Interactions;
+using Discord.WebSocket;
+using System.Threading.Tasks;
+
+namespace ShardedClient.Modules
+{
+    // A display of portability, which shows how minimal the difference between the 2 frameworks is.
+    public class InteractionModule : InteractionModuleBase<ShardedInteractionContext<SocketSlashCommand>>
+    {
+        [SlashCommand("info", "Information about this shard.")]
+        public async Task InfoAsync()
+        {
+            var msg = $@"Hi {Context.User}! There are currently {Context.Client.Shards.Count} shards!
+                This guild is being served by shard number {Context.Client.GetShardFor(Context.Guild).ShardId}";
+            await RespondAsync(msg);
+        }
+    }
+}

samples/ShardedClient/Modules/PublicModule.cs

@@ -0,0 +1,17 @@
+using Discord.Commands;
+using System.Threading.Tasks;
+
+namespace ShardedClient.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.Count} shards!
+                This guild is being served by shard number {Context.Client.GetShardFor(Context.Guild).ShardId}";
+            await ReplyAsync(msg);
+        }
+    }
+}

samples/ShardedClient/Program.cs

@@ -0,0 +1,81 @@
+using Discord;
+using Discord.Commands;
+using Discord.Interactions;
+using Discord.WebSocket;
+using Microsoft.Extensions.DependencyInjection;
+using ShardedClient.Services;
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace ShardedClient
+{
+    // 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
+    {
+        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
+            };
+
+            // You should dispose a service provider created using ASP.NET
+            // when you are finished using it, at the end of your app's lifetime.
+            // If you use another dependency injection framework, you should inspect
+            // its documentation for the best way to do this.
+            using (var services = ConfigureServices(config))
+            {
+                var client = services.GetRequiredService<DiscordShardedClient>();
+
+                // 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<InteractionHandlingService>().InitializeAsync();
+                await services.GetRequiredService<CommandHandlingService>().InitializeAsync();
+
+                // Tokens should be considered secret data, and never hard-coded.
+                await client.LoginAsync(TokenType.Bot, Environment.GetEnvironmentVariable("token"));
+                await client.StartAsync();
+
+                await Task.Delay(Timeout.Infinite);
+            }
+        }
+
+        private ServiceProvider ConfigureServices(DiscordSocketConfig config)
+            => new ServiceCollection()
+                .AddSingleton(new DiscordShardedClient(config))
+                .AddSingleton<CommandService>()
+                .AddSingleton(x => new InteractionService(x.GetRequiredService<DiscordShardedClient>()))
+                .AddSingleton<CommandHandlingService>()
+                .AddSingleton<InteractionHandlingService>()
+                .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/ShardedClient/Services/CommandHandlingService.cs

@@ -0,0 +1,72 @@
+using Discord;
+using Discord.Commands;
+using Discord.WebSocket;
+using Microsoft.Extensions.DependencyInjection;
+using System;
+using System.Reflection;
+using System.Threading.Tasks;
+
+namespace ShardedClient.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;
+
+            _commands.CommandExecuted += CommandExecutedAsync;
+            _commands.Log += LogAsync;
+            _discord.MessageReceived += MessageReceivedAsync;
+        }
+
+        public async Task InitializeAsync()
+        {
+            await _commands.AddModulesAsync(Assembly.GetEntryAssembly(), _services);
+        }
+
+        public async Task MessageReceivedAsync(SocketMessage rawMessage)
+        {
+            // Ignore system messages, or messages from other bots
+            if (rawMessage is not 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);
+            await _commands.ExecuteAsync(context, argPos, _services);
+        }
+
+        public async Task CommandExecutedAsync(Optional<CommandInfo> command, ICommandContext context, IResult result)
+        {
+            // command is unspecified when there was a search failure (command not found); we don't care about these errors
+            if (!command.IsSpecified)
+                return;
+
+            // the command was successful, we don't care about this result, unless we want to log that a command succeeded.
+            if (result.IsSuccess)
+                return;
+
+            // the command failed, let's notify the user that something happened.
+            await context.Channel.SendMessageAsync($"error: {result}");
+        }
+
+        private Task LogAsync(LogMessage log)
+        {
+            Console.WriteLine(log.ToString());
+
+            return Task.CompletedTask;
+        }
+    }
+}

samples/ShardedClient/Services/InteractionHandlingService.cs

@@ -0,0 +1,57 @@
+using Discord;
+using Discord.Interactions;
+using Discord.WebSocket;
+using Microsoft.Extensions.DependencyInjection;
+using System;
+using System.Linq;
+using System.Threading.Tasks;
+
+namespace ShardedClient.Services
+{
+    public class InteractionHandlingService
+    {
+        private readonly InteractionService _service;
+        private readonly DiscordShardedClient _client;
+        private readonly IServiceProvider _provider;
+
+        public InteractionHandlingService(IServiceProvider services)
+        {
+            _service = services.GetRequiredService<InteractionService>();
+            _client = services.GetRequiredService<DiscordShardedClient>();
+            _provider = services;
+
+            _service.Log += LogAsync;
+            _client.InteractionCreated += OnInteractionAsync;
+            // For examples on how to handle post execution,
+            // see the InteractionFramework samples.
+        }
+
+        // Register all modules, and add the commands from these modules to either guild or globally depending on the build state.
+        public async Task InitializeAsync()
+        {
+            await _service.AddModulesAsync(typeof(InteractionHandlingService).Assembly, _provider);
+#if DEBUG
+            await _service.AddCommandsToGuildAsync(_client.Guilds.First(x => x.Id == 1));
+#else
+            await _service.AddCommandsGloballyAsync();
+#endif
+        }
+
+        private async Task OnInteractionAsync(SocketInteraction interaction)
+        {
+            _ = Task.Run(async () =>
+            {
+                var context = new ShardedInteractionContext(_client, interaction);
+                await _service.ExecuteCommandAsync(context, _provider);
+            });
+            await Task.CompletedTask;
+        }
+
+        private Task LogAsync(LogMessage log)
+        {
+            Console.WriteLine(log.ToString());
+
+            return Task.CompletedTask;
+        }
+    }
+}

samples/ShardedClient/_ShardedClient.csproj

@@ -0,0 +1,19 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net5.0</TargetFramework>
+    <RootNamespace>ShardedClient</RootNamespace>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="5.0.2" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\Discord.Net.Commands\Discord.Net.Commands.csproj" />
+    <ProjectReference Include="..\..\src\Discord.Net.Interactions\Discord.Net.Interactions.csproj" />
+    <ProjectReference Include="..\..\src\Discord.Net.WebSocket\Discord.Net.WebSocket.csproj" />
+  </ItemGroup>
+
+</Project>