Best Practices for Displaying Error Messages from Controller to View in ASP.NET MVC 5

Introduction

In ASP.NET MVC 5 application development, data transfer between controllers and views is a core interaction pattern. After users submit form data, controllers need to handle business logic and provide clear error feedback when validation fails. This article uses a common scenario as an example: users search for database records by email address, with error messages displayed if records are not found.

Comparison of Two Error Message Passing Methods

Developers typically face two choices for passing error messages: using the ViewBag dynamic object or the ModelState dictionary. The following code examples illustrate both methods.

Using ViewBag to Pass Error Messages

In the controller's POST method, when validation fails, error messages can be assigned to the ViewBag.ErrorMessage property:

[HttpPost]
[ValidateAntiForgeryToken]
public ActionResult Search(ForgotPasswordMV viewModel)
{
    if (Temp.Check(viewModel.Email))
        return RedirectToAction("VerifyToken", new { query = viewModel.Email });
    else
    {
        ViewBag.ErrorMessage = "Email not found or matched";
        return View();
    }
}

In the view, error messages are displayed via @ViewBag.ErrorMessage:

<p>@ViewBag.ErrorMessage</p>

This approach is straightforward but has limitations: error messages are not associated with specific form fields, making field-level validation feedback difficult; it also bypasses MVC's built-in validation mechanisms, potentially leading to code duplication and maintenance challenges.

Using ModelState to Pass Error Messages (Recommended Approach)

A better approach leverages the ModelState dictionary, a core component of the ASP.NET MVC framework. The ModelState.AddModelError() method associates error messages with specific model properties:

[HttpPost]
[ValidateAntiForgeryToken]
public ActionResult Search(ForgotPasswordMV viewModel)
{
    if (Temp.Check(viewModel.Email))
        return RedirectToAction("VerifyToken", new { query = viewModel.Email });
    else
    {
        ModelState.AddModelError(nameof(ForgotPasswordMV.Email), "Email not found or matched");
        return View(viewModel);
    }
}

In the view, the Html.ValidationMessageFor() helper displays error messages related to specific fields:

@Html.ValidationMessageFor(m => m.Email)

This method binds error messages directly to the Email property, providing precise user feedback near the corresponding field when the view reloads.

Why ModelState Is the Superior Choice

Using ModelState offers several advantages: it integrates seamlessly with ASP.NET MVC's validation framework, supporting unified client and server-side validation; it maintains separation of concerns, with error logic centralized in controllers and display logic handled by view helpers; and it enhances testability, as ModelState can be easily mocked and validated in unit tests.

Additionally, ModelState supports complex validation scenarios, such as multiple error messages and custom validation rules. For example, if different error messages are needed based on business conditions, AddModelError() can be called multiple times:

if (!IsValidEmail(viewModel.Email))
    ModelState.AddModelError(nameof(ForgotPasswordMV.Email), "Invalid email format");
else if (!Temp.Check(viewModel.Email))
    ModelState.AddModelError(nameof(ForgotPasswordMV.Email), "Email not found in database");

This allows the view to display all relevant error messages without modifying display logic.

Implementation Steps and Best Practices

To correctly implement error message passing in ASP.NET MVC 5, follow these steps:

1. In controllers, use ModelState.AddModelError() to add error messages associated with specific model properties.
2. Ensure POST methods return views with model instances (return View(viewModel)) to maintain form data persistence.
3. In views, use @Html.ValidationMessageFor() to display error messages near corresponding form fields.
4. Consider using CSS styles to customize error message appearance according to application design standards.
5. For global errors (not associated with specific fields), use ModelState.AddModelError("", "Global error message") and display via @Html.ValidationSummary() in views.

By adhering to these practices, developers can build more robust, maintainable, and user-friendly ASP.NET MVC applications.