Table of Contents

Class EmbedBuilder

Namespace
Discord
Assembly
Discord.Net.Core.dll

Represents a builder class for creating a RichEmbed.

public class EmbedBuilder
Inheritance
EmbedBuilder
Inherited Members
Extension Methods

Examples

Basic Usage

The example below builds an embed and sends it to the chat using the command system.

[Command("embed")]
public async Task SendRichEmbedAsync()
{
    var embed = new EmbedBuilder
        {
            // Embed property can be set within object initializer
            Title = "Hello world!",
            Description = "I am a description set by initializer."
        };
        // Or with methods
    embed.AddField("Field title",
        "Field value. I also support [hyperlink markdown](https://example.com)!")
        .WithAuthor(Context.Client.CurrentUser)
        .WithFooter(footer => footer.Text = "I am a footer.")
        .WithColor(Color.Blue)
        .WithTitle("I overwrote \"Hello world!\"")
        .WithDescription("I am a description.")
        .WithUrl("https://example.com")
        .WithCurrentTimestamp();
        
    //Your embed needs to be built before it is able to be sent
    await ReplyAsync(embed: embed.Build());
}

Embed Example

Usage with Local Images

The example below sends an image and has the image embedded in the rich embed. See SendFileAsync for more information about uploading a file or image.

[Command("embedimage")]
public async Task SendEmbedWithImageAsync()
{
    var fileName = "image.png";
    var embed = new EmbedBuilder()
        {
            ImageUrl = $"attachment://{fileName}"
        }.Build();
    await Context.Channel.SendFileAsync(fileName, embed: embed);
}

Remarks

This builder class is used to build an Embed (rich embed) object that will be ready to be sent via SendMessageAsync after Build is called.

Constructors

EmbedBuilder()

Initializes a new EmbedBuilder class.

public EmbedBuilder()

Fields

MaxDescriptionLength

Returns the maximum length of description allowed by Discord.

public const int MaxDescriptionLength = 4096

Field Value

int

MaxEmbedLength

Returns the maximum length of total characters allowed by Discord.

public const int MaxEmbedLength = 6000

Field Value

int

MaxFieldCount

Returns the maximum number of fields allowed by Discord.

public const int MaxFieldCount = 25

Field Value

int

MaxTitleLength

Returns the maximum length of title allowed by Discord.

public const int MaxTitleLength = 256

Field Value

int

Properties

Author

Gets or sets the EmbedAuthorBuilder of an Embed.

public EmbedAuthorBuilder Author { get; set; }

Property Value

EmbedAuthorBuilder

The author field builder of the embed, or null if none is set.

Color

Gets or sets the sidebar color of an Embed.

public Color? Color { get; set; }

Property Value

Color?

The color of the embed, or null if none is set.

Description

Gets or sets the description of an Embed.

public string Description { get; set; }

Property Value

string

The description of the embed.

Exceptions

ArgumentException

Description length exceeds MaxDescriptionLength.

Fields

Gets or sets the list of EmbedFieldBuilder of an Embed.

public List<EmbedFieldBuilder> Fields { get; set; }

Property Value

List<EmbedFieldBuilder>

The list of existing EmbedFieldBuilder.

Exceptions

ArgumentNullException

An embed builder's fields collection is set to null.

ArgumentException

Fields count exceeds MaxFieldCount.

Gets or sets the EmbedFooterBuilder of an Embed.

public EmbedFooterBuilder Footer { get; set; }

Property Value

EmbedFooterBuilder

The footer field builder of the embed, or null if none is set.

ImageUrl

Gets or sets the image URL of an Embed.

public string ImageUrl { get; set; }

Property Value

string

The image URL of the embed.

Exceptions

ArgumentException

Url is not a well-formed Uri.

Length

Gets the total length of all embed properties.

public int Length { get; }

Property Value

int

The combined length of Title, Name, Description, Text, Name, and Value.

ThumbnailUrl

Gets or sets the thumbnail URL of an Embed.

public string ThumbnailUrl { get; set; }

Property Value

string

The thumbnail URL of the embed.

Exceptions

ArgumentException

Url is not a well-formed Uri.

Timestamp

Gets or sets the timestamp of an Embed.

public DateTimeOffset? Timestamp { get; set; }

Property Value

DateTimeOffset?

The timestamp of the embed, or null if none is set.

Title

Gets or sets the title of an Embed.

public string Title { get; set; }

Property Value

string

The title of the embed.

Exceptions

ArgumentException

Title length exceeds MaxTitleLength.

Url

Gets or sets the URL of an Embed.

public string Url { get; set; }

Property Value

string

The URL of the embed.

Exceptions

ArgumentException

Url is not a well-formed Uri.

Methods

AddField(EmbedFieldBuilder)

Adds a field with the provided EmbedFieldBuilder to an Embed.

public EmbedBuilder AddField(EmbedFieldBuilder field)

Parameters

field EmbedFieldBuilder

The field builder class containing the field properties.

Returns

EmbedBuilder

The current builder.

Exceptions

ArgumentException

Field count exceeds MaxFieldCount.

AddField(Action<EmbedFieldBuilder>)

Adds an Embed field with the provided properties.

public EmbedBuilder AddField(Action<EmbedFieldBuilder> action)

Parameters

action Action<EmbedFieldBuilder>

The delegate containing the field properties.

Returns

EmbedBuilder

The current builder.

AddField(string, object, bool)

Adds an Embed field with the provided name and value.

public EmbedBuilder AddField(string name, object value, bool inline = false)

Parameters

name string

The title of the field.

value object

The value of the field.

inline bool

Indicates whether the field is in-line or not.

Returns

EmbedBuilder

The current builder.

Build()

Builds the Embed into a Rich Embed ready to be sent.

public Embed Build()

Returns

Embed

The built embed object.

Exceptions

InvalidOperationException

Total embed length exceeds MaxEmbedLength.

InvalidOperationException

Any Url must include its protocols (i.e http:// or https://).

Equals(EmbedBuilder)

Determines whether the specified EmbedBuilder is equal to the current EmbedBuilder

public bool Equals(EmbedBuilder embedBuilder)

Parameters

embedBuilder EmbedBuilder

The EmbedBuilder to compare with the current EmbedBuilder

Returns

bool

Equals(object)

Determines whether the specified object is equal to the current EmbedBuilder.

public override bool Equals(object obj)

Parameters

obj object

The object to compare with the current EmbedBuilder

Returns

bool

Remarks

If the object passes is an EmbedBuilder, Equals(EmbedBuilder) will be called to compare the 2 instances

GetHashCode()

Serves as the default hash function.

public override int GetHashCode()

Returns

int

A hash code for the current object.

WithAuthor(EmbedAuthorBuilder)

Sets the EmbedAuthorBuilder of an Embed.

public EmbedBuilder WithAuthor(EmbedAuthorBuilder author)

Parameters

author EmbedAuthorBuilder

The author builder class containing the author field properties.

Returns

EmbedBuilder

The current builder.

WithAuthor(Action<EmbedAuthorBuilder>)

Sets the author field of an Embed with the provided properties.

public EmbedBuilder WithAuthor(Action<EmbedAuthorBuilder> action)

Parameters

action Action<EmbedAuthorBuilder>

The delegate containing the author field properties.

Returns

EmbedBuilder

The current builder.

WithAuthor(string, string, string)

Sets the author field of an Embed with the provided name, icon URL, and URL.

public EmbedBuilder WithAuthor(string name, string iconUrl = null, string url = null)

Parameters

name string

The title of the author field.

iconUrl string

The icon URL of the author field.

url string

The URL of the author field.

Returns

EmbedBuilder

The current builder.

WithColor(Color)

Sets the sidebar color of an Embed.

public EmbedBuilder WithColor(Color color)

Parameters

color Color

The color to be set.

Returns

EmbedBuilder

The current builder.

WithCurrentTimestamp()

Sets the timestamp of an Embed to the current time.

public EmbedBuilder WithCurrentTimestamp()

Returns

EmbedBuilder

The current builder.

WithDescription(string)

Sets the description of an Embed.

public EmbedBuilder WithDescription(string description)

Parameters

description string

The description to be set.

Returns

EmbedBuilder

The current builder.

WithFooter(EmbedFooterBuilder)

Sets the EmbedFooterBuilder of an Embed.

public EmbedBuilder WithFooter(EmbedFooterBuilder footer)

Parameters

footer EmbedFooterBuilder

The footer builder class containing the footer field properties.

Returns

EmbedBuilder

The current builder.

WithFooter(Action<EmbedFooterBuilder>)

Sets the footer field of an Embed with the provided properties.

public EmbedBuilder WithFooter(Action<EmbedFooterBuilder> action)

Parameters

action Action<EmbedFooterBuilder>

The delegate containing the footer field properties.

Returns

EmbedBuilder

The current builder.

WithFooter(string, string)

Sets the footer field of an Embed with the provided name, icon URL.

public EmbedBuilder WithFooter(string text, string iconUrl = null)

Parameters

text string

The title of the footer field.

iconUrl string

The icon URL of the footer field.

Returns

EmbedBuilder

The current builder.

WithImageUrl(string)

Sets the image URL of an Embed.

public EmbedBuilder WithImageUrl(string imageUrl)

Parameters

imageUrl string

The image URL to be set.

Returns

EmbedBuilder

The current builder.

WithThumbnailUrl(string)

Sets the thumbnail URL of an Embed.

public EmbedBuilder WithThumbnailUrl(string thumbnailUrl)

Parameters

thumbnailUrl string

The thumbnail URL to be set.

Returns

EmbedBuilder

The current builder.

WithTimestamp(DateTimeOffset)

Sets the timestamp of an Embed.

public EmbedBuilder WithTimestamp(DateTimeOffset dateTimeOffset)

Parameters

dateTimeOffset DateTimeOffset

The timestamp to be set.

Returns

EmbedBuilder

The current builder.

WithTitle(string)

Sets the title of an Embed.

public EmbedBuilder WithTitle(string title)

Parameters

title string

The title to be set.

Returns

EmbedBuilder

The current builder.

WithUrl(string)

Sets the URL of an Embed.

public EmbedBuilder WithUrl(string url)

Parameters

url string

The URL to be set.

Returns

EmbedBuilder

The current builder.

Operators

operator ==(EmbedBuilder, EmbedBuilder) 

public static bool operator ==(EmbedBuilder left, EmbedBuilder right)

Parameters

left EmbedBuilder
right EmbedBuilder

Returns

bool

operator !=(EmbedBuilder, EmbedBuilder) 

public static bool operator !=(EmbedBuilder left, EmbedBuilder right)

Parameters

left EmbedBuilder
right EmbedBuilder

Returns

bool

See Also

EmbedFooterBuilder
EmbedAuthorBuilder
EmbedFieldBuilder
Edit this page