How to build clean, professional dialogs inside Revit add-ins

If you’ve ever built a Revit add-in, you know the quickest way to talk to your users is with a simple TaskDialog. It’s lightweight, native to Revit, and far more flexible than a standard .NET MessageBox.

In this post, we’ll walk through how a TaskDialog works, what each property does, and how you can use it to guide users through decisions, warnings, or confirmations inside your workflows.

Below is a full example showing almost every feature of the Revit API’s TaskDialog class:

TaskDialog td = new TaskDialog("TaskDialog Demo by Triple Zero Labs");

td.Id = "Sample_TD";
td.MainIcon = TaskDialogIcon.TaskDialogIconWarning;
td.Title = "This is 'Title'.";
td.TitleAutoPrefix = true;
td.AllowCancellation = true;

td.MainInstruction = "This is 'MainInstruction'.";
td.MainContent = "This is 'MainContent'.";
td.FooterText = "This is 'FooterText'.";
td.ExpandedContent = "This is 'ExpandedContent'.\nLine1: blar blar...\nLine2: blar blar...\nLine3: blar blar...";

td.VerificationText = "This is 'VerificationText'.";

td.AddCommandLink(TaskDialogCommandLinkId.CommandLink1, "This is 'CommandLink1'.");
td.AddCommandLink(TaskDialogCommandLinkId.CommandLink2, "This is 'CommandLink2'.");
td.AddCommandLink(TaskDialogCommandLinkId.CommandLink3, "This is 'CommandLink3'.");
td.AddCommandLink(TaskDialogCommandLinkId.CommandLink4, "This is 'CommandLink4'.");

td.CommonButtons =
    TaskDialogCommonButtons.Cancel | TaskDialogCommonButtons.Ok | TaskDialogCommonButtons.Close |
    TaskDialogCommonButtons.No | TaskDialogCommonButtons.Yes | TaskDialogCommonButtons.Retry |
    TaskDialogCommonButtons.None;

td.DefaultButton = TaskDialogResult.Ok;

TaskDialogResult tdRes = td.Show();

MessageBox.Show($"Button result: {tdRes}\nVerificationText checked: {td.WasVerificationChecked()}");

---

Breaking It Down

Let’s go line-by-line and talk about what each part does.

1. Creating the Dialog

TaskDialog td = new TaskDialog("TaskDialog Demo by Triple Zero Labs");

This initializes a new TaskDialog with an internal name. This name appears in the Revit journal, so it’s great for debugging and tracking user actions.

---

2. Basic Appearance Settings

Id

td.Id = "Sample_TD";

A unique identifier for analytics or add-in logging. Optional, but good practice.

MainIcon

td.MainIcon = TaskDialogIcon.TaskDialogIconWarning;

Sets the icon at the top-left of the dialog. Options include:

• Information
• Warning
• Error
• None

Title + AutoPrefix

td.Title = "This is 'Title'.";
td.TitleAutoPrefix = true;

TitleAutoPrefix = true makes Revit prepend your add-in’s name automatically, giving you a nice professional dialog header.

AllowCancellation

td.AllowCancellation = true;

Adds the ESC-key cancellation behavior.

---

3. Main Text Sections

Revit splits the TaskDialog into several text zones:

MainInstruction

Large, bold text at the top.
Use it like a headline.

MainContent

The descriptive body text.
Explain context, actions, or warnings here.

FooterText

Shows up at the bottom in a dimmer style.
Useful for disclaimers or secondary info.

ExpandedContent

A collapsible “more info” section.
Great for long instructions or debug details.

td.ExpandedContent = "…";

This keeps your dialog clean while still giving power users more information.

---

4. Verification Checkbox

td.VerificationText = "This is 'VerificationText'.";

This creates a checkbox at the bottom of the dialog.
Common uses:

• “Don’t show this again.”
• “I understand the risk.”
• “Apply this choice automatically next time.”

Later you can check:

td.WasVerificationChecked()

---

5. Command Links

This is one of the most powerful features of TaskDialog.

td.AddCommandLink(TaskDialogCommandLinkId.CommandLink1, "Label text...");

Command Links appear as large button-style options.
Use them when you want clean, opinionated choices instead of cramped OK/Cancel buttons.

Examples:

• “Select Room”
• “Load Family”
• “Purge Unused”
• “Fix Automatically”

You can add up to 4.

---

6. Common Buttons

td.CommonButtons =
    TaskDialogCommonButtons.Cancel | TaskDialogCommonButtons.Ok | TaskDialogCommonButtons.Close |
    TaskDialogCommonButtons.No | TaskDialogCommonButtons.Yes | TaskDialogCommonButtons.Retry |
    TaskDialogCommonButtons.None;

These are the small bottom-right buttons.
Most dialogs only need:

• Ok
• Cancel
• Yes | No

But the example shows all available flags.

DefaultButton

td.DefaultButton = TaskDialogResult.Ok;

Defines which button is triggered when the user presses Enter.

---

7. Showing the Dialog

TaskDialogResult tdRes = td.Show();

Now Revit displays the dialog and pauses your code until the user responds.

---

8. Reading the Result

MessageBox.Show($"Button result: {tdRes}\nVerificationText checked: {td.WasVerificationChecked()}");

You can now route your logic:

• Did they click OK?
• Did they click CommandLink2?
• Did they decline?
• Did they check the “remember me” box?

Example:

if (tdRes == TaskDialogResult.CommandLink1)
{
    // User chose Command Link 1
}

---

When Should You Use a TaskDialog?

Use it anytime you need:

• Simple user decisions
• Warnings or risk confirmations
• Multi-option choices
• Clean UI without building a whole WPF window

TaskDialogs are native to Revit and feel consistent with Autodesk’s UX, making them perfect for professional add-ins.

---

Final Tips for Beginners

• Keep dialogs short. Users hate clicking through walls of text.
• Use Command Links instead of “OK / Cancel” when you have multiple actions.
• Use ExpandedContent to hide advanced details.
• Don’t overuse VerificationText—only when there’s something to remember.