d189bb9748
* remove tip in docs about SocketEntity.Discord * Expose the 'Fields' collection on EmbedBuilder After some discussion I decided that there was really no reason to keep this private, and it didn't really go along with the rest of the design of the EmbedBuilder. This is NOT a breaking change. Exposing this property should not have any negative effects. * Don't allow EmbedBuilder's Fields to be set to null
2.3 KiB
title
| title |
|---|
| Entities |
Note
This article is written with the Socket variants of entities in mind, not the general interfaces or Rest/Rpc entities.
Discord.Net provides a versatile entity system for navigating the Discord API.
Inheritance
Due to the nature of the Discord API, some entities are designed with
multiple variants, for example, SocketUser and SocketGuildUser.
All models will contain the most detailed version of an entity possible, even if the type is less detailed.
For example, in the case of the MessageReceived event, a
SocketMessage is passed in with a channel property of type
SocketMessageChannel. All messages come from channels capable of
messaging, so this is the only variant of a channel that can cover
every single case.
But that doesn't mean a message can't come from a
SocketTextChannel, which is a message channel in a guild. To
retrieve information about a guild from a message entity, you will
need to cast its channel object to a SocketTextChannel.
Navigation
All socket entities have navigation properties on them, which allow you to easily navigate to an entity's parent or children. As explained above, you will sometimes need to cast to a more detailed version of an entity to navigate to its parent.
Accessing Entities
The most basic forms of entities, SocketGuild, SocketUser, and
SocketChannel can be pulled from the DiscordSocketClient's global
cache, and can be retrieved using the respective GetXXX method on
DiscordSocketClient.
Tip
It is vital that you use the proper IDs for an entity when using a GetXXX method. It is recommended that you enable Discord's developer mode to allow easy access to entity IDs, found in Settings > Appearance > Advanced
More detailed versions of entities can be pulled from the basic
entities, e.g. SocketGuild.GetUser, which returns a
SocketGuildUser, or SocketGuild.GetChannel, which returns a
SocketGuildChannel. Again, you may need to cast these objects to get
a variant of the type that you need.
Samples
[!code-csharpEntity Sample]
Tips
Avoid using boxing-casts to coerce entities into a variant, use the
as keyword, and a null-conditional operator.
This allows you to write safer code, and avoid InvalidCastExceptions.
For example, (message.Author as SocketGuildUser)?.Nickname.