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

Documentation Overhaul (#1161)

Browse Source 
* Add XML docs

* Clean up style switcher

* Squash commits on branch docs/faq-n-patches

* Fix broken theme selector

* Add local image embed instruction

* Add a bunch of XML docs

* Add a bunch of XML docs

* Fix broken search
+ DocFX by default ships with an older version of jQuery, switching to a newer version confuses parts of the DocFX Javascript.

* Minor fixes for CONTRIBUTING.md and README.md

* Clean up filterConfig.yml

+ New config exposes Discord.Net namespace since it has several common public exceptions that may be helpful to users

* Add XML docs

* Read token from Environment Variable instead of hardcode

* Add XMLDocs

* Compress some assets & add OAuth2 URL generator

* Fix sample link & add missing pictures

* Add tag examples

* Fix embed docs consistency

* Add details regarding userbot support

* Add XML Docs

* Add XML Docs

* Add XML Docs

* Minor fixes in documentations
+ Fix unescaped '<'
+ Fix typo

* Fix seealso for preconditions and add missing descriptions

* Add missing exceptions

* Document exposed TypeReaders

* Fix letter-casing for files

* Add 'last modified' plugin

Source: https://github.com/Still34/DocFx.Plugin.LastModified
Licensed under MIT License

* XML Docs

* Fix minor consistencies & redundant impl

* Add properties examples to overwrite

* Fix missing Username prop

* Add warning for bulk-delete endpoint

* Replace note block

* Add BaseSocketClient docs

* Add XML docs

* Replace langword null to code block null instead

- Because DocFX sucks at rendering langword

* Replace all langword placements with code block

* Add more IGuild docs

* Add details to SpotifyGame

* Initial proofread of the articles

* Add explanation for RunMode

* Add event docs

- MessageReceived
- ChannelUpdated/Destroyed/Created

* Fix light theme link color

* Fix xml docs error

* Add partial documentation for audit log impl

* Add documentation for some REST-based objects

* Add partial documentation for audit log objects

* Add more XML comments to quotation mark alias map stuff, including an example

* Add reference to CommandServiceConfig from the util docs'

* Add explanation that if " is removed then it wont work

* Fix missing service provider in example

* Add documentation for new INestedChannel

* Add documentation

* Add documentation for new API version & few events

* Revise guide paragraphs/samples

+ Fix various formatting.
+ Provide a more detailed walkthrough for dependency injection.
+ Add C# note at intro.

* Fix typos & formatting

* Improve group module example

* Small amount to see if I'm doing it right

* Remove/cleanup redundant variables

* Fix EnterTypingState impl for doc inheritance

* Fix Test to resolve changes made in 15b58e

* Improve precondition documentation

+ Add precondition usage sample
+ Add precondition group usage sample
+ Move precondition samples to its own sample folder

* Move samples to individual folders

* Clarify token source

* Cleanup styling of README.md for docs

* Replace InvalidPathChars for NS1.3

* InvalidPathChars does not exist in NS1.3; replaced with GetInvalidPathChars instead.

* Add a missing change for 2c7cc738

* Update LastModified to v1.1.0 & add license

* Rewrite installation page for Core 2.1

* Fix anchor link

* Bump post-processor to v1.1.1

* Add fixes to partial file & add license

* Moved theme-switcher code to scripts partial file
+ Add author's MIT license to featherlight javascript

* Remove unused bootstrap plugin

* Bump LastModified plugin

* Changed the path from 'lastmodified' to 'last-modified' for consistency

* Cleanup README & Contribution guide

* Changes to last pr

* Fix GetCategoryAsync docs

* Proofread and cleanup articles

* Change passive voice in "Get Started" to active
* Fix improper preposition in Commands Introduction page
* Fix minor grammar mistakes in "Your First Bot" (future tense -> present tense/subjunctive mood -> indicative mood/proper noun casing/incorrect noun/add missing article)
* Fix minor grammar mistakes in "Installation" (missing article)

* no hablo ingles

* Try try try again

* I'm sure you're having as much fun as I am

* Cleanup TOC & fix titles

* Improve styling

+ Change title font to Noto Sans
+ Add materialized design for commit message box

* Add DescriptionGenerator plugin

* Add nightly section for clarification

* Fix typos in Nightlies & Post-execution

* Bump DescriptionGenerator to v1.1.0

+ This build adds the functionality of generating managed references' summary into the description tag.

* Initial emoji article draft

* Add 'additional information' section for emoji article

* Add cosmetic changes to the master css

* Alter info box color
+ Add transition to article content

* Add clarification in the emoji article

* Emphasize that normal emoji string will not translate to its Unicode representation.
* Clean up or add some of the samples featured in the article.
+ Add emoji/emote declaration section for clarification.
+ Add WebSocket emote sample.
- Remove inconsistent styling ('wacky memes' proves to be too out of place).

* Improve readability for nightlies article

* Move 'Bundled Preconditions' section

* Bump LastModified to fix UTC DateTime parsing

* Add langwordMapping.yml

* Add XML docs

* Add VSC workspace rule

* The root workspace limits the ruler to 120 characters for member documentations and excludes folders such as 'samples' and 'docs'.
* The docs workspace limits the ruler to 70 characters for standard conceptual article to comply with documentation's CONTRIBUTING.md rule, and excludes temprorary folders created by DocFX.

* Update CONTRIBUTING.md

* Add documentation style rule

* Fix styling of several member documentation

* Fix ' />' caused by Agent Smith oddities
* Fix styling to be more specific about the mention of IDs

* Fix exception summary to comply with official Microsoft Docs style

* References
https://docs.microsoft.com/en-us/dotnet/api/system.argumentnullexception?view=netframework-4.7.2
https://docs.microsoft.com/en-us/dotnet/api/system.platformnotsupportedexception?view=netframework-4.7.2
https://docs.microsoft.com/en-us/dotnet/api/system.badimageformatexception?view=netframework-4.7.2

* Add XML documentations

* Shift color return docs

* Fix minor docs

* Added documentation for SocketDMChannel, SocketGuildChannel, and SocketTextChannel

* Add XML docs

* Corrections to SocketGuildChannel

* Corrections to SocketTextChannel

* Corrections to SocketDMChannel

* Swapped out 'id' for 'snowflake identifier

* Swapped out 'id' for 'snowflake identifier'

* SocketDMChannel amendments

* SocketGuildChannel amendments

* SocketTextChannel amendments

* Add XML docs & patch return types
+ Starting from this commit, all return types for tasks will use style similar to most documentations featured on docs.microsoft.com

References:
https://docs.microsoft.com/en-us/dotnet/api/microsoft.entityframeworkcore.dbcontext.-ctor?view=efcore-2.1
https://docs.microsoft.com/en-us/dotnet/api/system.io.filestream.readasync?view=netcore-2.1
https://docs.microsoft.com/en-us/dotnet/api/system.io.textwriter.writelineasync?view=netcore-2.1#System_IO_TextWriter_WriteLineAsync_System_Char___
And many more other asynchronous method documentations featured in the latest BCL.

* Added documentation for many audit log data types, fixed vowel indefinite articles

* Change audit log data types to start with 'Contains' (verb) instead of an article

* Fix some documentation issues and document some more audit log data types

* Fix English posession

* Add XML doc

* Documented two more types

* Documented RoleCreateAuditLogData

* Document remaining audit log data types

* Added RestDMChannel documentation

* Added RestGuildChannel documentation

* Added RestTextChannel documentation

* Added RestVoiceChannel documentation

* Added RestUser documentation

* Added RestRole documentation

* Added RestMessage documentation

* Slightly better wording

* Contains -> Contains a piece of (describe article)

* [EN] Present perf. -> past perf.

* Add XML docs

* Fix arrow alignment

* Clarify supported nullable type

* Fixed a typo in ISnowflakeEntity

* Added RestUser Documentation

* Added RestInvite documentation

* Add XML docs & minor optimizations

* Minor optimization for doc rendering

* Rollback font optimization changes

* Amendments to RestUser

* Added SocketDMChannel documentation

* Added RestDMChannel documentation

* Added RestGuild documentation

* Adjustment to SocketDMChannel

* Added minimal descriptions from the API documentation for Integration types

* Added obsolete mention to the ReadMessages flag.

* Added remarks about 2FA requirement for guild permissions

* Added xmldoc for GuildPermission methods

* Added xml doc for ToAllowList and ToDenyList

* Added specification of how the bits of the color raw value are packed

* Added discord API documentation to IConnection interface

* I can spell :^)

* Fix whitespace in ChannelPermission

* fix spacing of values in guildpermission

* Made changes to get field descriptions from feedback, added returns tag to IConnection

* Added property get standard for IntegrationAccount

* Added property get pattern to xml docs and identical returns tag.

* Change all color class references to struct
...because it isn't a class.

* Add XML docs

* Rewrote the returns tags in IGuildIntegration, removed the ones I was unsure about.

* Rewrote the rest of the returns tags

* Amendments

* Cleanup doc for c1d78189

* Added types to <returns> tags where missing

* Added second sample for adding reactions

* Added some class summaries

* Missed a period

* Amendments

* restored the removed line break

* Removed unnecessary see tag

* Use consistent quotation marks around subscribers, the name for these users are dependant on the source of where they are integrated from (youtube or twitch), so we should not use a name that is specific to one platform

* Add <remarks> tag to the IGuildIntegration xmldocs

* Fix grammar issue

* Update DescriptionGenerator

* Cleanup of https://github.com/Still34/Discord.Net/pull/8

* Cleanup previous PR

* Fix for misleading behaviour in the emoji guide
+ Original lines stated that sending a emoji wrapped in colon will not be parsed, but that was incorrect; replaced with reactions instead of sending messages as the example

* Add strings for dictionary in DotSettings

* Add XML docs

* Fix lots of typos in comments
+ Geez, I didn't know there were so many.

* Add XML docs & rewrite GetMessagesAsync docs

This commit rewrites the remarks section of GetMessagesAsync, as well as adding examples to several methods.

* Update 'Your First Bot'
+ This commit reflects the new changes made to the Discord Application Developer Portal after its major update

* Initial optimization for DocFX render & add missing files

* Add examples in message methods

* Cleanup https://github.com/RogueException/Discord.Net/pull/1128

* Fix first bot note

* Cleanup FAQ structure

* Add XML docs

* Update docfx plugins

* Fix navbar collapsing issue

* Fix broken xref

* Cleanup FAQ section
+ Add introductory paragraphs to each FAQ section.
+ Add 'missing dependency' entry to commands FAQ.
* Split commands FAQ to 'General' and 'DI' sections.

* Cleanup https://github.com/RogueException/Discord.Net/pull/1139

* Fix missing namespace

* Add missing highlighting css for the light theme

* Add additional clarification for installing packages

* Add indentation to example for clarity

* Cleanup several articles to be more human-friendly and easier to read

* Remove RPC-related notes

* Cleanup slow-mode-related documentation strings

* Add an additional note about cross-guild emote usage

* Add CreateTextChannel sample

* Add XMLDocs
This commit is contained in:
Still Hsu
2018-10-01 05:44:33 +08:00
committed by Christopher F
parent 6b21b11f7d
commit ff0fea98a6
498 changed files with 16064 additions and 2633 deletions
Download Patch File Download Diff File Expand all files Collapse all files

263
docs/guides/getting_started/first-bot.md Normal file
View File

@@ -0,0 +1,263 @@
---
uid: Guides.GettingStarted.FirstBot
title: Start making a bot
---
# Making Your First Bot with Discord.Net
One of the ways to get started with the Discord API is to write a
basic ping-pong bot. This bot will respond to a simple command "ping."
We will expand on this to create more diverse commands later, but for
now, it is a good starting point.
## Creating a Discord Bot
Before writing your bot, it is necessary to create a bot account via
the Discord Applications Portal first.
1. Visit the [Discord Applications Portal].
2. Create a new application.
3. Give the application a name (this will be the bot's initial username).
4. On the left-hand side, under `Settings`, click `Bot`.
![Step 4](images/intro-bot-settings.png)
5. Click on `Add Bot`.
![Step 5](images/intro-add-bot.png)
6. Confirm the popup.
7. (Optional) If this bot will be public, tick `Public Bot`.
![Step 7](images/intro-public-bot.png)
[Discord Applications Portal]: https://discordapp.com/developers/applications/
## Adding your bot to a server
Bots **cannot** use invite links; they must be explicitly invited
through the OAuth2 flow.
1. Open your bot's application on the [Discord Applications Portal].
2. On the left-hand side, under `Settings`, click `OAuth2`.
![Step 2](images/intro-oauth-settings.png)
3. Scroll down to `OAuth2 URL Generator` and under `Scopes` tick `bot`.
![Step 3](images/intro-scopes-bot.png)
4. Scroll down further to `Bot Permissions` and select the
permissions that you wish to assign your bot with.
> [!NOTE]
> This will assign the bot with a special "managed" role that no
> one else can use. The permissions can be changed later in the
> roles settings if you ever change your mind!
5. Open the generated authorization URL in your browser.
6. Select a server.
7. Click on Authorize.
> [!NOTE]
> Only servers where you have the `MANAGE_SERVER` permission will be
> present in this list.
![Step 6](images/intro-authorize.png)
## Connecting to Discord
If you have not already created a project and installed Discord.Net,
do that now.
For more information, see @Guides.GettingStarted.Installation.
### Async
Discord.Net uses .NET's [Task-based Asynchronous Pattern (TAP)]
extensively - nearly every operation is asynchronous. It is highly
recommended for these operations to be awaited in a
properly established async context whenever possible.
To establish an async context, we will be creating an async main method
in your console application, and rewriting the static main method to
invoke the new async main.
[!code-csharp[Async Context](samples/first-bot/async-context.cs)]
As a result of this, your program will now start and immediately
jump into an async context. This allows us to create a connection
to Discord later on without having to worry about setting up the
correct async implementation.
> [!WARNING]
> If your application throws any exceptions within an async context,
> they will be thrown all the way back up to the first non-async method;
> since our first non-async method is the program's `Main` method, this
> means that **all** unhandled exceptions will be thrown up there, which
> will crash your application.
>
> Discord.Net will prevent exceptions in event handlers from crashing
> your program, but any exceptions in your async main **will** cause
> the application to crash.
[Task-based Asynchronous Pattern (TAP)]: https://docs.microsoft.com/en-us/dotnet/articles/csharp/async
### Creating a logging method
Before we create and configure a Discord client, we will add a method
to handle Discord.Net's log events.
To allow agnostic support of as many log providers as possible, we
log information through a `Log` event with a proprietary `LogMessage`
parameter. See the [API Documentation] for this event.
If you are using your own logging framework, this is where you would
invoke it. For the sake of simplicity, we will only be logging to
the console.
You may learn more about this concept in @Guides.Concepts.Logging.
[!code-csharp[Async Context](samples/first-bot/logging.cs)]
[API Documentation]: xref:Discord.Rest.BaseDiscordClient.Log
### Creating a Discord Client
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.
Before connecting, we should hook the client's `Log` event to the
log handler that we had just created. Events in Discord.Net work
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."
> [!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
> the source code for your bot.
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.
Finally, we will want to block the async main method from returning
when running the application. To do this, we can await an infinite delay
or any other blocking method, such as reading from the console.
The following lines can now be added:
[!code-csharp[Create client](samples/first-bot/client.cs)]
At this point, feel free to start your program and see your bot come
online in Discord.
> [!TIP]
> 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]
> 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.
[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.
For reference, view an [annotated example] of this structure.
[annotated example]: samples/first-bot/structure.cs
It is important to know that the recommended design pattern of bots
should be to separate...
1. the program (initialization and command handler)
2. the modules (handle commands)
3. the services (persistent storage, pure functions, data manipulation)
[CommandService]: xref:Discord.Commands.CommandService

BIN
docs/guides/getting_started/images/appveyor-artifacts.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.8 KiB

BIN
docs/guides/getting_started/images/appveyor-nupkg.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 9.2 KiB

BIN
docs/guides/getting_started/images/install-vs-nuget.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 117 KiB

After

Width:  |  Height:  |  Size: 48 KiB

BIN
docs/guides/getting_started/images/intro-add-bot.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 26 KiB

After

Width:  |  Height:  |  Size: 6.3 KiB

BIN
docs/guides/getting_started/images/intro-authorize.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 19 KiB

BIN
docs/guides/getting_started/images/intro-bot-settings.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.6 KiB

BIN
docs/guides/getting_started/images/intro-client-id.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 5.0 KiB

BIN
docs/guides/getting_started/images/intro-create-app.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 51 KiB

BIN
docs/guides/getting_started/images/intro-create-bot.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 45 KiB

BIN
docs/guides/getting_started/images/intro-oauth-settings.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.5 KiB

BIN
docs/guides/getting_started/images/intro-public-bot.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 11 KiB

BIN
docs/guides/getting_started/images/intro-scopes-bot.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 17 KiB

BIN
docs/guides/getting_started/images/intro-token.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 26 KiB

After

Width:  |  Height:  |  Size: 18 KiB

BIN
docs/guides/getting_started/images/nightlies-vs-note.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 9.9 KiB

BIN
docs/guides/getting_started/images/nightlies-vs-step1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB

BIN
docs/guides/getting_started/images/nightlies-vs-step2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB

BIN
docs/guides/getting_started/images/nightlies-vs-step4.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.0 KiB

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

@@ -1,146 +1,136 @@
---
uid: Guides.GettingStarted.Installation
title: Installing Discord.Net
---
Discord.Net is distributed through the NuGet package manager, and it
is recommended to use NuGet to get started.
# Discord.Net Installation
Optionally, you may compile from source and install yourself.
Discord.Net is distributed through the NuGet package manager; the most
recommended way for you to install this library. Alternatively, you
may also compile this library yourself should you so desire.
# Supported Platforms
## Supported Platforms
Currently, Discord.Net targets [.NET Standard] 1.3 and offers support
for .NET Standard 1.1. If your application will be targeting .NET
Standard 1.1, please see the [additional steps].
Discord.Net targets [.NET Standard] both 1.3 and 2.0; this also means
that creating applications using the latest version of [.NET Core] is
the most recommended. If you are bound by Windows-specific APIs or
other limitations, you may also consider targeting [.NET Framework]
4.6.1 or higher.
Since Discord.Net is built on the .NET Standard, it is also
recommended to create applications using [.NET Core], though not
required. When using .NET Framework, it is suggested to target
`.NET Framework 4.6.1` or higher.
> [!WARNING]
> Using this library with [Mono] is not supported until further
> notice. It is known to have issues with the library's WebSockets
> implementation and may crash the application upon startup.
[Mono]: https://www.mono-project.com/
[.NET Standard]: https://docs.microsoft.com/en-us/dotnet/articles/standard/library
[.NET Core]: https://docs.microsoft.com/en-us/dotnet/articles/core/
[.NET Framework]: https://docs.microsoft.com/en-us/dotnet/framework/get-started/
[additional steps]: #installing-on-net-standard-11
# Installing with NuGet
## Installing with NuGet
Release builds of Discord.Net 1.0 will be published to the
Release builds of Discord.Net will be published to the
[official NuGet feed].
Development builds of Discord.Net 1.0, as well as addons *(TODO)* are
published to our development [MyGet feed].
Direct feed link: `https://www.myget.org/F/discord-net/api/v3/index.json`
Not sure how to add a direct feed? See how [with Visual Studio] or
[without Visual Studio].
Development builds of Discord.Net, as well as add-ons, will be
published to our [MyGet feed]. See
@Guides.GettingStarted.Installation.Nightlies to learn more.
[official NuGet feed]: https://nuget.org
[MyGet feed]: https://www.myget.org/feed/Packages/discord-net
[with Visual Studio]: https://docs.microsoft.com/en-us/nuget/tools/package-manager-ui#package-sources
[without Visual Studio]: #configuring-nuget-without-visual-studio
## Using Visual Studio
### [Using Visual Studio](#tab/vs-install)
> [!TIP]
>Don't forget to change your package source if you're installing from
the developer feed.
>Also make sure to check "Enable Prereleases" if installing a dev
build!
1. Create a solution for your bot.
2. In Solution Explorer, find the "Dependencies" element under your
bot's project.
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)
![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)
![Step 5](images/install-vs-nuget.png)
## Using JetBrains Rider
> [!TIP]
Make sure to check the "Prerelease" box if installing a dev build!
### [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).
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
> [!TIP]
Don't forget to add the package source to a [NuGet.Config file] if
you're installing from the developer feed.
### [Using Visual Studio Code](#tab/vs-code)
1. Create a new project for your bot.
2. Add `Discord.Net` to your .csproj.
[!code-xml[Sample .csproj](samples/project.csproj)]
[!code[Sample .csproj](samples/project.xml)]
[NuGet.Config file]: #configuring-nuget-without-visual-studio
### [Using dotnet CLI](#tab/dotnet-cli)
# Compiling from Source
1. Open command-line and navigate to where your .csproj is located.
2. Enter `dotnet add package Discord.Net`.
In order to compile Discord.Net, you require the following:
***
## Compiling from Source
In order to compile Discord.Net, you will need the following:
### Using Visual Studio
- [Visual Studio 2017](https://www.visualstudio.com/)
- [.NET Core SDK 1.0](https://www.microsoft.com/net/download/core#/sdk)
* [Visual Studio 2017](https://www.visualstudio.com/)
* [.NET Core SDK]
The .NET Core and Docker (Preview) workload is required during Visual
Studio installation.
The .NET Core and Docker workload is required during Visual Studio
installation.
### Using Command Line
- [.NET Core SDK 1.0](https://www.microsoft.com/net/download/core#/sdk)
* [.NET Core SDK]
# Additional Information
## Additional Information
## Installing on .NET Standard 1.1
### Installing on Unsupported WebSocket Platform
For applications targeting a runtime corresponding with .NET Standard
1.1 or 1.2, the builtin WebSocket and UDP provider will not work. For
applications which utilize a WebSocket connection to Discord
(WebSocket or RPC), third-party provider packages will need to be
installed and configured.
When running any Discord.Net-powered bot on an older operating system
(e.g. Windows 7) that does not natively support WebSocket,
you may encounter a @System.PlatformNotSupportedException upon
connecting.
First, install the following packages through NuGet, or compile
yourself, if you prefer:
You may resolve this by either targeting .NET Core 2.1 or later, or
by installing one or more custom packages as listed below.
- Discord.Net.Providers.WS4Net
- Discord.Net.Providers.UDPClient
#### [Targeting .NET Core 2.1](#tab/core2-1)
Note that `Discord.Net.Providers.UDPClient` is _only_ required if your
bot will be utilizing voice chat.
1. Download the latest [.NET Core SDK].
2. Create or move your existing project to use .NET Core.
3. Modify your `<TargetFramework>` tag to at least `netcoreapp2.1`, or
by adding the `--framework netcoreapp2.1` switch when building.
Next, you will need to configure your [DiscordSocketClient] to use
these custom providers over the default ones.
#### [Custom Packages](#tab/custom-pkg)
To do this, set the `WebSocketProvider` and the optional
`UdpSocketProvider` properties on the [DiscordSocketConfig] that you
are passing into your client.
1. Install or compile the following packages:
[!code-csharp[NET Standard 1.1 Example](samples/netstd11.cs)]
* `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.
[!code-csharp[Example](samples/netstd11.cs)]
[DiscordSocketClient]: xref:Discord.WebSocket.DiscordSocketClient
[DiscordSocketConfig]: xref:Discord.WebSocket.DiscordSocketConfig
## Configuring NuGet without Visual Studio
***
If you plan on deploying your bot or developing outside of Visual
Studio, you will need to create a local NuGet configuration file for
your project.
To do this, create a file named `nuget.config` alongside the root of
your application, where the project solution is located.
Paste the following snippets into this configuration file, adding any
additional feeds as necessary.
[!code-xml[NuGet Configuration](samples/nuget.config)]
[.NET Core SDK]: https://www.microsoft.com/net/download/

237
docs/guides/getting_started/intro.md
View File

@@ -1,237 +0,0 @@
---
title: Getting Started
---
# Making a Ping-Pong bot
One of the first steps to getting started with the Discord API is to
write a basic ping-pong bot. We will expand on this to create more
diverse commands later, but for now, it is a good starting point.
## Creating a Discord Bot
Before you can begin writing your bot, it is necessary to create a bot
account on Discord.
1. Visit the [Discord Applications Portal].
2. Create a New Application.
3. Give the application a name (this will be the bot's initial
username).
4. Create the Application.
![Step 4](images/intro-create-app.png)
5. In the application review page, click **Create a Bot User**.
![Step 5](images/intro-create-bot.png)
6. Confirm the popup.
7. If this bot will be public, check "Public Bot." **Do not tick any
other options!**
[Discord Applications Portal]: https://discordapp.com/developers/applications/me
## Adding your bot to a server
Bots **cannot** use invite links, they must be explicitly invited
through the OAuth2 flow.
1. Open your bot's application on the [Discord Applications Portal].
2. Retrieve the app's **Client ID**.
![Step 2](images/intro-client-id.png)
3. Create an OAuth2 authorization URL
`https://discordapp.com/oauth2/authorize?client_id=<CLIENT ID>&scope=bot`
4. Open the authorization URL in your browser.
5. Select a server.
6. Click on authorize.
>[!NOTE]
Only servers where you have the `MANAGE_SERVER` permission will be
present in this list.
![Step 6](images/intro-add-bot.png)
## Connecting to Discord
If you have not already created a project and installed Discord.Net,
do that now. (see the [Installing](installing.md) section)
### Async
Discord.Net uses .NET's [Task-based Asynchronous Pattern (TAP)]
extensively - nearly every operation is asynchronous.
It is highly recommended that these operations are awaited in a
properly established async context whenever possible. Establishing an
async context can be problematic, but not hard.
To do so, we will be creating an async main in your console
application, and rewriting the static main method to invoke the new
async main.
[!code-csharp[Async Context](samples/intro/async-context.cs)]
As a result of this, your program will now start and immediately
jump into an async context. This will allow us to create a connection
to Discord later on without needing to worry about setting up the
correct async implementation.
>[!TIP]
If your application throws any exceptions within an async context,
they will be thrown all the way back up to the first non-async method;
since our first non-async method is the program's `Main` method, this
means that **all** unhandled exceptions will be thrown up there, which
will crash your application. Discord.Net will prevent exceptions in
event handlers from crashing your program, but any exceptions in your
async main **will** cause the application to crash.
[Task-based Asynchronous Pattern (TAP)]: https://docs.microsoft.com/en-us/dotnet/articles/csharp/async
### Creating a logging method
Before we create and configure a Discord client, we will add a method
to handle Discord.Net's log events.
To allow agnostic support of as many log providers as possible, we
log information through a `Log` event with a proprietary `LogMessage`
parameter. See the [API Documentation] for this event.
If you are using your own logging framework, this is where you would
invoke it. For the sake of simplicity, we will only be logging to
the Console.
[!code-csharp[Async Context](samples/intro/logging.cs)]
[API Documentation]: xref:Discord.Rest.BaseDiscordClient#Discord_Rest_BaseDiscordClient_Log
### Creating a Discord Client
Finally, we can create a connection to Discord. Since we are writing
a bot, we will be using a [DiscordSocketClient] along with socket
entities. See the [terminology](terminology.md) if you're unsure of
the differences.
To do so, create an instance of [DiscordSocketClient] in your async
main, passing in a configuration object only 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 was just created. Events in Discord.Net work
similarly to other events in C#, so hook this event the way that
you typically would.
Next, you will need to "login to Discord" with the `LoginAsync`
method.
You may create a variable to hold your bot's token (this can be found
on your bot's application page on the [Discord Applications Portal]).
![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 file if you plan on distributing
the source code for your bot.
We may now invoke the client's `StartAsync` method, which will
start connection/reconnection logic. It is important to note that
**this method returns as soon as connection logic has been started!**
Any methods that rely on the client's state should go in an event
handler.
Finally, we will want to block the async main method from returning
until after the application is exited. To do this, we can await an
infinite delay or any other blocking method, such as reading from
the console.
The following lines can now be added:
[!code-csharp[Create client](samples/intro/client.cs)]
At this point, feel free to start your program and see your bot come
online in Discord.
>[!TIP]
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.
[DiscordSocketClient]: xref:Discord.WebSocket.DiscordSocketClient
[installation guide]: installing.md#installing-on-net-standard-11
### 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] section.
Now that we have learned how to open a connection to Discord, we can
begin handling messages that users are sending.
To start out, our bot will listen for any message where the content
is equal to `!ping` and 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
back to the channel from which the message comes from - "Pong!". 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 [SocketMessageChannel], we can invoke the
`SendMessageAsync` instance method. For the message content, send back
a string containing "Pong!".
You should have now added the following lines:
[!code-csharp[Message](samples/intro/message.cs)]
Now 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.
For your reference, you may view the [completed program].
[MessageReceived]: xref:Discord.WebSocket.DiscordSocketClient#Discord_WebSocket_DiscordSocketClient_MessageReceived
[SocketMessage]: xref:Discord.WebSocket.SocketMessage
[SocketMessageChannel]: xref:Discord.WebSocket.ISocketMessageChannel
[completed program]: samples/intro/complete.cs
[Command Guide]: ../commands/commands.md
# Building a bot with commands
This section will show you how to write a program that is ready for
[Commands](../commands/commands.md). Note that we will not be
explaining _how_ to write Commands or Services, it will only be
covering the general structure.
For reference, view an [annotated example] of this structure.
[annotated example]: samples/intro/structure.cs
It is important to know that the recommended design pattern of bots
should be to separate the program (initialization and command handler),
the modules (handle commands), and the services (persistent storage,
pure functions, data manipulation).
**todo:** diagram of bot structure

86
docs/guides/getting_started/nightlies.md Normal file
View File

@@ -0,0 +1,86 @@
---
uid: Guides.GettingStarted.Installation.Nightlies
title: Installing Nightly Build
---
# Installing Discord.Net Nightly Build
Before Discord.Net pushes a new set of features into the stable
version, we use nightly builds to test the features with the
community for an extensive period of time. Each nightly build is
compiled by AppVeyor whenever a new commit is made and will be pushed
to our MyGet feed.
> [!IMPORTANT]
> Although nightlies are generally stable and have more features
> and bug fixes than the current stable build on NuGet, there
> will be breaking changes during the development or
> breaking bugs; these bugs are usually fixed as soon as they
> are discovered, but you should still be aware of that.
## Installing with MyGet (Recommended)
MyGet is typically used by many development teams to publish their
latest pre-release packages before the features are finalized and
pushed to NuGet.
The following is the feed link of Discord.Net,
* `https://www.myget.org/F/discord-net/api/v3/index.json`
Depending on which IDE you use, there are many different ways of
adding the feed to your package source.
### [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
> nightly builds!
> ![Checkbox](images/nightlies-vs-note.png)
### [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
your project.
To do this, create a file named `NuGet.Config` alongside the root of
your application, where the project is located.
Paste the following snippets into this configuration file, adding any
additional feeds if necessary.
[!code[NuGet Configuration](samples/nuget.config)]
After which, you may install the packages by directly modifying the
project file and specifying a version, or by using
the [Package Manager Console](https://docs.microsoft.com/en-us/nuget/tools/powershell-reference)
(`Install-Package Discord.Net -IncludePrerelease`).
***
## Installing from AppVeyor Artifacts
As mentioned in the first paragraph, we utilize AppVeyor to perform
automated tests and publish the new build. During the publishing
process, we also upload the NuGet packages onto
AppVeyor's Artifact collection.
The latest build status can be found within our [AppVeyor project].
[AppVeyor project]: https://ci.appveyor.com/project/rogueexception/discord-net
1. In the project, you may find our latest build including the
aforementioned artifacts.
![Artifacts](images/appveyor-artifacts.png)
2. In the artifacts collection, you should see the latest packages
packed in `*.nupkg` form which you could download from and use.
![NuPkgs](images/appveyor-nupkg.png)

9
docs/guides/getting_started/samples/first-bot/async-context.cs Normal file
View File

@@ -0,0 +1,9 @@
public class Program
{
public static void Main(string[] args)
=> new Program().MainAsync().GetAwaiter().GetResult();
public async Task MainAsync()
{
}
}

21
docs/guides/getting_started/samples/first-bot/client.cs Normal file
View File

@@ -0,0 +1,21 @@
private DiscordSocketClient _client;
public async Task MainAsync()
{
_client = new DiscordSocketClient();
_client.Log += Log;
// Remember to keep token private or to read it from an
// external source! In this case, we are reading the token
// from an environment variable. If you do not know how to set-up
// environment variables, you may find more information on the
// Internet or by using other methods such as reading from
// a configuration.
await _client.LoginAsync(TokenType.Bot,
Environment.GetEnvironmentVariable("DiscordToken"));
await _client.StartAsync();
// Block this task until the program is closed.
await Task.Delay(-1);
}

34
docs/guides/getting_started/samples/first-bot/complete.cs Normal file
View File

@@ -0,0 +1,34 @@
public class Program
{
private DiscordSocketClient _client;
public static void Main(string[] args)
=> new Program().MainAsync().GetAwaiter().GetResult();
public async Task MainAsync()
{
_client = new DiscordSocketClient();
_client.Log += Log;
_client.MessageReceived += MessageReceivedAsync;
await _client.LoginAsync(TokenType.Bot,
Environment.GetEnvironmentVariable("DiscordToken"));
await _client.StartAsync();
// 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());
return Task.CompletedTask;
}
}

5
docs/guides/getting_started/samples/first-bot/logging.cs Normal file
View File

@@ -0,0 +1,5 @@
private Task Log(LogMessage msg)
{
Console.WriteLine(msg.ToString());
return Task.CompletedTask;
}

2
docs/guides/getting_started/samples/intro/message.cs → docs/guides/getting_started/samples/first-bot/message.cs
View File

@@ -1,6 +1,6 @@
public async Task MainAsync()
{
// client.Log ...
// ...
_client.MessageReceived += MessageReceived;
// ...
}

0
docs/guides/getting_started/samples/intro/structure.cs → docs/guides/getting_started/samples/first-bot/structure.cs
View File

15
docs/guides/getting_started/samples/intro/async-context.cs
View File

@@ -1,15 +0,0 @@
using System;
using System.Threading.Tasks;
namespace MyBot
{
public class Program
{
public static void Main(string[] args)
=> new Program().MainAsync().GetAwaiter().GetResult();
public async Task MainAsync()
{
}
}
}

17
docs/guides/getting_started/samples/intro/client.cs
View File

@@ -1,17 +0,0 @@
// Program.cs
using Discord.WebSocket;
// ...
private DiscordSocketClient _client;
public async Task MainAsync()
{
_client = new DiscordSocketClient();
_client.Log += Log;
string token = "abcdefg..."; // Remember to keep this private!
await _client.LoginAsync(TokenType.Bot, token);
await _client.StartAsync();
// Block this task until the program is closed.
await Task.Delay(-1);
}

44
docs/guides/getting_started/samples/intro/complete.cs
View File

@@ -1,44 +0,0 @@
using Discord;
using Discord.WebSocket;
using System;
using System.Threading.Tasks;
namespace MyBot
{
public class Program
{
private DiscordSocketClient _client;
public static void Main(string[] args)
=> new Program().MainAsync().GetAwaiter().GetResult();
public async Task MainAsync()
{
_client = new DiscordSocketClient();
_client.Log += Log;
_client.MessageReceived += MessageReceived;
string token = "abcdefg..."; // Remember to keep this private!
await _client.LoginAsync(TokenType.Bot, token);
await _client.StartAsync();
// Block this task until the program is closed.
await Task.Delay(-1);
}
private async Task MessageReceived(SocketMessage message)
{
if (message.Content == "!ping")
{
await message.Channel.SendMessageAsync("Pong!");
}
}
private Task Log(LogMessage msg)
{
Console.WriteLine(msg.ToString());
return Task.CompletedTask;
}
}
}

22
docs/guides/getting_started/samples/intro/logging.cs
View File

@@ -1,22 +0,0 @@
using Discord;
using System;
using System.Threading.Tasks;
namespace MyBot
{
public class Program
{
public static void Main(string[] args)
=> new Program().MainAsync().GetAwaiter().GetResult();
public async Task MainAsync()
{
}
private Task Log(LogMessage msg)
{
Console.WriteLine(msg.ToString());
return Task.CompletedTask;
}
}
}

13
docs/guides/getting_started/samples/project.csproj
View File

@@ -1,13 +0,0 @@
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>netcoreapp1.1</TargetFramework>
<NoWin32Manifest>true</NoWin32Manifest>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Discord.Net" Version="1.*" />
</ItemGroup>
</Project>

17
docs/guides/getting_started/samples/project.xml Normal file
View File

@@ -0,0 +1,17 @@
<Project Sdk="Microsoft.NET.Sdk">
<!--
The following may differ depending on the latest version of
.NET Core or Discord.Net.
-->
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>netcoreapp2.1</TargetFramework>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Discord.Net" Version="2.0.0" />
</ItemGroup>
</Project>

40
docs/guides/getting_started/terminology.md
View File

@@ -1,5 +1,5 @@
---
uid: Terminology
uid: Guides.GettingStarted.Terminology
title: Terminology
---
@@ -7,34 +7,30 @@ title: Terminology
## Preface
Most terms for objects remain the same between 0.9 and 1.0. The major
difference is that the ``Server`` is now called ``Guild`` to stay in
line with Discord internally.
Most terms for objects remain the same between 0.9 and 1.0 and above.
The major difference is that the ``Server`` is now called ``Guild``
to stay in line with Discord internally.
## Implementation Specific Entities
Discord.Net 1.0 is split into a core library and three different
implementations - `Discord.Net.Core`, `Discord.Net.Rest`,
`Discord.Net.Rpc`, and `Discord.Net.WebSockets`.
Discord.Net is split into a core library and two different
implementations - `Discord.Net.Core`, `Discord.Net.Rest`, and
`Discord.Net.WebSockets`.
As a bot developer, you will only need to use `Discord.Net.WebSockets`,
As a bot developer, you will only need to use `Discord.Net.WebSockets`,
but you should be aware of the differences between them.
`Discord.Net.Core` provides a set of interfaces that models Discord's
API. These interfaces are consistent throughout all implementations of
Discord.Net, and if you are writing an implementation-agnostic library
or addon, you can rely on the core interfaces to ensure that your
`Discord.Net.Core` provides a set of interfaces that models Discord's
API. These interfaces are consistent throughout all implementations of
Discord.Net, and if you are writing an implementation-agnostic library
or addon, you can rely on the core interfaces to ensure that your
addon will run on all platforms.
`Discord.Net.Rest` provides a set of concrete classes to be used
**strictly** with the REST portion of Discord's API. Entities in this
implementation are prefixed with `Rest` (e.g. `RestChannel`).
`Discord.Net.Rest` provides a set of concrete classes to be used
**strictly** with the REST portion of Discord's API. Entities in this
implementation are prefixed with `Rest` (e.g., `RestChannel`).
`Discord.Net.Rpc` provides a set of concrete classes that are used
with Discord's RPC API. Entities in this implementation are prefixed
with `Rpc` (e.g. `RpcChannel`).
`Discord.Net.WebSocket` provides a set of concrete classes that are
`Discord.Net.WebSocket` provides a set of concrete classes that are
used primarily with Discord's WebSocket API or entities that are kept
in cache. When developing bots, you will be using this implementation.
All entities are prefixed with `Socket` (e.g. `SocketChannel`).
in cache. When developing bots, you will be using this implementation.
All entities are prefixed with `Socket` (e.g., `SocketChannel`).