github/Discord.Net
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Main docs update (#1304)

Browse Source 
* Remove template in favor of official samples

* Fixed a variable name copy pasta mistake

line 35 was _database.GetData() instead of DBService.GetData()

* Experimental theme change

* Change paragraph, code, heading fonts
* Widen viewport

* Update DocFX.Plugins.LastModified v1.2.3

* Exclude Discord.API in docs

* Add remarks for SocketReaction properties

* Add examples for BaseSocketClient.Events

* Add additional clarification for some methods

* Move IUser and IGuildChannel examples

* Clarify several guides samples with notes

- Reword TypeReader comment to avoid giving the idea that the sample itself is "obsolete"
- Remove CommandException logging comment regarding C#7.0 as the version is now the standard across VS2017 and up
- Remove suggestion about handling result in command handler since it is now advised to use CommandExecuted instead
+ Add additional comment to clarify ctor for DI setup

* Add/migrate code examples

* Incorporate material design theme

License @ https://github.com/ovasquez

* Update installation and nightly guide

* Fix improper indentations made obvious by the widen viewport
* Fix minor grammar issues
+ Add installation for nightly build using dotnet CLI

* Fix nav level indentation

* Revise "Your First Bot" article

* Merge some paragraphs to avoid clutter while keeping readability
* Reword the use of command framework
+ Add additional warning/note about environment variable

* Add additional indent level

* Fix indentation text warping

* Remove connections sample

* Update logging sample

Remove redundant part of the sample

* Remove mention of RPC

* Remove misleading section about commands

- Remove command sample from complete snippet
* Revise "Your First Bot" command paragraphs
* Change wording to hint devs that additional command parser packages may be available, as more and more begin to crop up

* Update themes

* Add XML docs contribution guidelines


Update guidelines

* Update CommandExecuted remarks

* Fix precondition remarks typo
no one saw that ok

* Fix permission sample in docfx

* Fix IMessageChannel samples

* Update docs/_template/light-dark-theme/styles/docfx.vendor.minify.css

Co-Authored-By: Still34 <341464@gmail.com>

* Update docs/_template/light-dark-theme/styles/material.css

Co-Authored-By: Still34 <341464@gmail.com>

* Update docs/_template/light-dark-theme/styles/material.css

Co-Authored-By: Still34 <341464@gmail.com>
This commit is contained in:
Still Hsu
2019-05-14 06:29:47 +08:00
committed by Christopher F
parent 5ea3e113b8
commit 4309550ca0
64 changed files with 986 additions and 345 deletions
Download Patch File Download Diff File Expand all files Collapse all files

98
docs/guides/getting_started/first-bot.md
View File

@@ -128,12 +128,10 @@ Finally, we can create a new connection to Discord.
Since we are writing a bot, we will be using a [DiscordSocketClient]
along with socket entities. See @Guides.GettingStarted.Terminology
if you are unsure of the differences.
To establish a new connection, we will create an instance of
[DiscordSocketClient] in the new async main. You may pass in an
optional @Discord.WebSocket.DiscordSocketConfig if necessary. For most
users, the default will work fine.
if you are unsure of the differences. To establish a new connection,
we will create an instance of [DiscordSocketClient] in the new async
main. You may pass in an optional @Discord.WebSocket.DiscordSocketConfig
if necessary. For most users, the default will work fine.
Before connecting, we should hook the client's `Log` event to the
log handler that we had just created. Events in Discord.Net work
@@ -142,22 +140,33 @@ similarly to any other events in C#.
Next, you will need to "log in to Discord" with the [LoginAsync]
method with the application's "token."
![Token](images/intro-token.png)
> [!NOTE]
> Pay attention to what you are copying from the developer portal!
> A token is not the same as the application's "client secret."
![Token](images/intro-token.png)
> [!IMPORTANT]
> Your bot's token can be used to gain total access to your bot, so
> **do __NOT__ share this token with anyone else!** It may behoove you
> to store this token in an external source if you plan on distributing
> **do not** share this token with anyone else! You should store this
> token in an external source if you plan on distributing
> the source code for your bot.
>
> In the following example, we retrieve the token from the environment
> variable `DiscordToken`. Please note that this is *not* designed to
> be used in a production environment, as the secrets are stored in
> plain-text.
>
> For information on how to set an environment variable, please see
> instructions below,
>
> * Windows: [How to Create Environment Variables Shortcut in Windows](https://www.tenforums.com/tutorials/121742-create-environment-variables-shortcut-windows.html)
> * Linux: [How To Read and Set Environmental and Shell Variables on a Linux VPS](https://www.digitalocean.com/community/tutorials/how-to-read-and-set-environmental-and-shell-variables-on-a-linux-vps)
> * macOS: [How do I set environment variables on OS X?](https://apple.stackexchange.com/questions/106778/how-do-i-set-environment-variables-on-os-x)
We may now invoke the client's [StartAsync] method, which will
start connection/reconnection logic. It is important to note that
**this method will return as soon as connection logic has been started!**
Any methods that rely on the client's state should go in an event
handler. This means that you should **not** directly be interacting with
the client before it is fully ready.
@@ -173,81 +182,34 @@ The following lines can now be added:
At this point, feel free to start your program and see your bot come
online in Discord.
> [!TIP]
> [!WARNING]
> Getting a warning about `A supplied token was invalid.` and/or
> having trouble logging in? Double-check whether you have put in
> the correct credentials and make sure that it is _not_ a client
> secret, which is different from a token.
> [!TIP]
> [!WARNING]
> Encountering a `PlatformNotSupportedException` when starting your bot?
> This means that you are targeting a platform where .NET's default
> WebSocket client is not supported. Refer to the [installation guide]
> for how to fix this.
> [!NOTE]
> For your reference, you may view the [completed program].
[DiscordSocketClient]: xref:Discord.WebSocket.DiscordSocketClient
[LoginAsync]: xref:Discord.Rest.BaseDiscordClient.LoginAsync*
[StartAsync]: xref:Discord.WebSocket.DiscordSocketClient.StartAsync*
[installation guide]: xref:Guides.GettingStarted.Installation
### Handling a 'ping'
> [!WARNING]
> Please note that this is *not* a proper way to create a command.
> Use the `CommandService` provided by the library instead, as explained
> in the [Command Guide](xref:Guides.Commands.Intro) section.
Now that we have learned to open a connection to Discord, we can
begin handling messages that the users are sending. To start out, our
bot will listen for any message whose content is equal to `!ping` and
will respond back with "Pong!".
Since we want to listen for new messages, the event to hook into
is [MessageReceived].
In your program, add a method that matches the signature of the
`MessageReceived` event - it must be a method (`Func`) that returns
the type `Task` and takes a single parameter, a [SocketMessage]. Also,
since we will be sending data to Discord in this method, we will flag
it as `async`.
In this method, we will add an `if` block to determine if the message
content fits the rules of our scenario - recall that it must be equal
to `!ping`.
Inside the branch of this condition, we will want to send a message,
`Pong!`, back to the channel from which the message comes from. To
find the channel, look for the `Channel` property on the message
parameter.
Next, we will want to send a message to this channel. Since the
channel object is of type [ISocketMessageChannel], we can invoke the
[SendMessageAsync] instance method. For the message content, send back
a string, "Pong!".
You should have now added the following lines,
[!code-csharp[Message](samples/first-bot/message.cs)]
Now that your first bot is complete. You may continue to add on to this
if you desire, but for any bots that will be carrying out multiple
commands, it is strongly recommended to use the command framework as
shown below.
> [!NOTE]
> For your reference, you may view the [completed program].
[MessageReceived]: xref:Discord.WebSocket.BaseSocketClient.MessageReceived
[SocketMessage]: xref:Discord.WebSocket.SocketMessage
[ISocketMessageChannel]: xref:Discord.WebSocket.ISocketMessageChannel
[SendMessageAsync]: xref:Discord.WebSocket.ISocketMessageChannel.SendMessageAsync*
[completed program]: samples/first-bot/complete.cs
# Building a bot with commands
@Guides.Commands.Intro will guide you through how to setup a program
that is ready for [CommandService], a service that is ready for
advanced command usage.
To create commands for your bot, you may choose from a variety of
command processors available. Throughout the guides, we will be using
the one that Discord.Net ships with. @Guides.Commands.Intro will
guide you through how to setup a program that is ready for
[CommandService].
For reference, view an [annotated example] of this structure.

58
docs/guides/getting_started/installing.md
View File

@@ -42,37 +42,45 @@ published to our [MyGet feed]. See
### [Using Visual Studio](#tab/vs-install)
1. Create a new solution for your bot.
1. Create a new solution for your bot
2. In the Solution Explorer, find the "Dependencies" element under your
bot's project.
3. Right click on "Dependencies", and select "Manage NuGet packages."
![Step 3](images/install-vs-deps.png)
4. In the "Browse" tab, search for `Discord.Net`.
5. Install the `Discord.Net` package.
![Step 5](images/install-vs-nuget.png)
bot's project
3. Right click on "Dependencies", and select "Manage NuGet packages"
![Step 3](images/install-vs-deps.png)
4. In the "Browse" tab, search for `Discord.Net`
5. Install the `Discord.Net` package
![Step 5](images/install-vs-nuget.png)
### [Using JetBrains Rider](#tab/rider-install)
1. Create a new solution for your bot.
2. Open the NuGet window (Tools > NuGet > Manage NuGet packages for
Solution).
![Step 2](images/install-rider-nuget-manager.png)
3. In the "Packages" tab, search for `Discord.Net`.
![Step 3](images/install-rider-search.png)
4. Install by adding the package to your project.
![Step 4](images/install-rider-add.png)
1. Create a new solution for your bot
2. Open the NuGet window (Tools > NuGet > Manage NuGet packages for Solution)
![Step 2](images/install-rider-nuget-manager.png)
3. In the "Packages" tab, search for `Discord.Net`
![Step 3](images/install-rider-search.png)
4. Install by adding the package to your project
![Step 4](images/install-rider-add.png)
### [Using Visual Studio Code](#tab/vs-code)
1. Create a new project for your bot.
2. Add `Discord.Net` to your .csproj.
1. Create a new project for your bot
2. Add `Discord.Net` to your `*.csproj`
[!code[Sample .csproj](samples/project.xml)]
### [Using dotnet CLI](#tab/dotnet-cli)
1. Open command-line and navigate to where your .csproj is located.
2. Enter `dotnet add package Discord.Net`.
1. Launch your terminal
2. Navigate to where your `*.csproj` is located
3. Enter `dotnet add package Discord.Net`
***
@@ -115,16 +123,16 @@ by installing one or more custom packages as listed below.
1. Install or compile the following packages:
* `Discord.Net.Providers.WS4Net`
* `Discord.Net.Providers.UDPClient` (Optional)
* This is _only_ required if your bot will be utilizing voice chat.
* `Discord.Net.Providers.WS4Net`
* `Discord.Net.Providers.UDPClient` (Optional)
* This is _only_ required if your bot will be utilizing voice chat.
2. Configure your [DiscordSocketClient] to use these custom providers
over the default ones.
* To do this, set the `WebSocketProvider` and the optional
`UdpSocketProvider` properties on the [DiscordSocketConfig] that you
are passing into your client.
* To do this, set the `WebSocketProvider` and the optional
`UdpSocketProvider` properties on the [DiscordSocketConfig] that you
are passing into your client.
[!code-csharp[Example](samples/netstd11.cs)]

17
docs/guides/getting_started/nightlies.md
View File

@@ -31,22 +31,33 @@ The following is the feed link of Discord.Net,
Depending on which IDE you use, there are many different ways of
adding the feed to your package source.
### [Visual Studio](#tab/vs)
### [Using Visual Studio](#tab/vs)
1. Go to `Tools` > `NuGet Package Manager` > `Package Manager Settings`
![VS](images/nightlies-vs-step1.png)
2. Go to `Package Sources`
![Package Sources](images/nightlies-vs-step2.png)
3. Click on the add icon
4. Fill in the desired name and source as shown below and hit `Update`
![Add Source](images/nightlies-vs-step4.png)
> [!NOTE]
> Remember to tick the `Include prerelease` checkbox to see the
> Remember to tick the `Include pre-release` checkbox to see the
> nightly builds!
> ![Checkbox](images/nightlies-vs-note.png)
### [Local NuGet.Config](#tab/local-nuget-config)
### [Using dotnet CLI](#tab/cli)
1. Launch your terminal
2. Navigate to where your `*.csproj` is located
3. Type `dotnet add package Discord.Net --source https://www.myget.org/F/discord-net/api/v3/index.json`
### [Using Local NuGet.Config](#tab/local-nuget-config)
If you plan on deploying your bot or developing outside of Visual
Studio, you will need to create a local NuGet configuration file for

10
docs/guides/getting_started/samples/first-bot/complete.cs
View File

@@ -9,7 +9,6 @@ public class Program
{
_client = new DiscordSocketClient();
_client.Log += Log;
_client.MessageReceived += MessageReceivedAsync;
await _client.LoginAsync(TokenType.Bot,
Environment.GetEnvironmentVariable("DiscordToken"));
await _client.StartAsync();
@@ -17,15 +16,6 @@ public class Program
// Block this task until the program is closed.
await Task.Delay(-1);
}
private async Task MessageReceivedAsync(SocketMessage message)
{
if (message.Content == "!ping")
{
await message.Channel.SendMessageAsync("Pong!");
}
}
private Task Log(LogMessage msg)
{
Console.WriteLine(msg.ToString());