Documentation Overhaul (#1161)
* 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
263
docs/guides/getting_started/first-bot.md
Normal file
263
docs/guides/getting_started/first-bot.md
Normal 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`.
|
||||
|
||||
|
||||
|
||||
5. Click on `Add Bot`.
|
||||
|
||||
|
||||
|
||||
6. Confirm the popup.
|
||||
7. (Optional) If this bot will be public, tick `Public Bot`.
|
||||
|
||||
|
||||
|
||||
[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`.
|
||||
|
||||
|
||||
|
||||
3. Scroll down to `OAuth2 URL Generator` and under `Scopes` tick `bot`.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
## 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."
|
||||
|
||||
|
||||
|
||||
> [!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
|
||||
Reference in New Issue
Block a user