Not logged in▾
Log In Register
Forgot Password Resend Validation E-mail
In This Article

MessageBox

The MessageBox class is intentionally designed to be consistent with the native WPF MessageBox API and can be used to quickly display the most common prompts.

Screenshot

MessageBox dialog with optional status icon

Tip

See the Builder Pattern topic for additional details on showing more advanced user prompts.

Showing a MessageBox

The MessageBox.Show method is used to show a basic prompt based on the arguments passed. The only required argument is the text to be displayed, so the simplest prompt can be shown as follows:

await MessageBox.Show("Operation complete.");

There are two overloads of the Show method where one allows an owner TopLevel (typically a Window) to be passed, and the other doesn't. All other arguments are identical. The following basic arguments are available:

Argument Description
messageBoxText The primary message text to be displayed.
caption The title bar caption of the window.
button One or more of the MessageBoxButtons values for each button to display.
image One of the MessageBoxImage values indicating a status image to display.
defaultResult The default MessageBoxResult, which must correspond to one of the given button values.

The following code demonstrates prompting the user with a question and storing the result:

var result = await MessageBox.Show(
	"The specified file already exists. Do you want to overwrite the file?",
	"Overwrite existing file?",
	MessageBoxButtons.YesNo,
	MessageBoxImage.Question
	MessageBoxResult.No);
Warning

The return value of MessageBox.Show is a Task<MessageBoxResult> that must be awaited to prevent the calling thread from proceeding before the user responds. Attempting to read the Task.Result without awaiting its completion can result in thread deadlock.

Owner

The user prompt must have an owner TopLevel (typically a Window). One of the MessageBox.Show overloads allows an owner to be specified. If one is not specified, a default owner will be determined. With desktop applications, the default is the currently active Window. On single-view applications, the default is the TopLevel of the current view.

Advanced Configuration

Since the MessageBox API is intentionally designed to be consistent with the native WPF MessageBox API, it only supports basic prompts. By limiting the functionality, it makes MessageBox easy to use.

For more advanced configurations, it is typically best to use the UserPromptBuilder instead of MessageBox. In fact, UserPromptBuilder is exactly what MessageBox.Show uses to display a prompt!

If you still want to use MessageBox for advanced configurations, there is an optional configure argument to the Show method that allows you to define a callback that will receive the UserPromptBuilder used for the MessageBox before it is shown.

See the Builder Pattern topic for more details on configuration options, including a global configuration callback is always applied to a message box.

The following demonstrates defining a configure callback to add a header message:

await MessageBox.Show(
	"The project was successfully compiled and deployed to the remote server."
	configure: builder => builder.WithHeaderContent("Deploy successful!")
	);