Migrating Mvc Razor Views

ASP.NET MVC Razor Views Migration

Overview

Migrate ASP.NET MVC Razor views to ASP.NET Core. Razor syntax is mostly compatible, but the helper ecosystem changed significantly: HtmlHelpers are replaced by TagHelpers, child actions are replaced by ViewComponents, and layout infrastructure requires a _ViewImports.cshtml file. For bundle-specific migration (@Scripts.Render, @Styles.Render, BundleConfig.cs), see the migrating-mvc-bundling skill.

Workflow

Migration Progress:
- [ ] Step 1: Set up _ViewImports.cshtml
- [ ] Step 2: Convert HtmlHelpers to TagHelpers
- [ ] Step 3: Convert child actions to ViewComponents
- [ ] Step 4: Update partial view references
- [ ] Step 5: Migrate custom HtmlHelper extensions
- [ ] Step 6: Update view data passing patterns
- [ ] Step 7: Clean up removed APIs
- [ ] Step 8: Verify build

Step 1: Set Up _ViewImports.cshtml

Create Views/_ViewImports.cshtml if it does not exist. This file replaces per-view @using statements and activates TagHelpers globally:

@using MyApp
@using MyApp.Models
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

Replace MyApp with the actual project namespace. The @addTagHelper directive is required for all built-in TagHelpers to work. Without it, TagHelper syntax renders as plain HTML attributes.

Verify that _ViewStart.cshtml still references the correct layout path. The default _Layout.cshtml path is compatible between MVC and Core.

Step 2: Convert HtmlHelpers to TagHelpers

Replace @Html.* helper calls with TagHelper equivalents. TagHelpers use HTML attributes prefixed with asp- instead of C# method calls, making views closer to standard HTML.

Links and Navigation

Before:

@Html.ActionLink("View Details", "Details", "Products", new { id = item.Id }, new { @class = "btn" })

After:

<a asp-controller="Products" asp-action="Details" asp-route-id="@item.Id" class="btn">View Details</a>

Forms

Before:

@using (Html.BeginForm("Create", "Products", FormMethod.Post, new { @class = "form" }))
{
    @Html.AntiForgeryToken()
    @Html.LabelFor(m => m.Name)
    @Html.TextBoxFor(m => m.Name, new { @class = "form-control" })
    @Html.ValidationMessageFor(m => m.Name, "", new { @class = "text-danger" })
}

After:

<form asp-controller="Products" asp-action="Create" method="post" class="form">
    <label asp-for="Name"></label>
    <input asp-for="Name" class="form-control" />
    <span asp-validation-for="Name" class="text-danger"></span>
</form>

The asp-for TagHelper generates id, name, type, and validation attributes automatically. The antiforgery token is injected automatically by the form TagHelper when method="post".

Dropdowns

Before:

@Html.DropDownListFor(m => m.CategoryId, Model.Categories, "-- Select --", new { @class = "form-control" })

After:

<select asp-for="CategoryId" asp-items="Model.Categories" class="form-control">
    <option value="">-- Select --</option>
</select>

Validation Summary

Before:

@Html.ValidationSummary(true, "", new { @class = "text-danger" })

After:

<div asp-validation-summary="ModelOnly" class="text-danger"></div>

Use All instead of ModelOnly if the original excludePropertyErrors parameter was false.

Step 3: Convert Child Actions to ViewComponents

Child actions (Html.Action / Html.RenderAction with [ChildActionOnly]) are removed in ASP.NET Core. Replace them with ViewComponents, which follow a mini-controller pattern.

Create the ViewComponent Class

Before (child action in controller):

[ChildActionOnly]
public ActionResult RecentProducts(int count = 5)
{
    var products = _repository.GetRecent(count);
    return PartialView("_RecentProducts", products);
}

After (ViewComponent class):

public class RecentProductsViewComponent : ViewComponent
{
    private readonly IProductRepository _repository;

    public RecentProductsViewComponent(IProductRepository repository)
    {
        _repository = repository;
    }

    public IViewComponentResult Invoke(int count = 5)
    {
        var products = _repository.GetRecent(count);
        return View(products);
    }
}

Place ViewComponent classes in a ViewComponents/ folder or any folder — they are discovered by convention (suffix ViewComponent) or by the [ViewComponent] attribute. ViewComponents support constructor dependency injection natively.

Move the View

Move the partial view from Views/<Controller>/_RecentProducts.cshtml (or Views/Shared/_RecentProducts.cshtml) to Views/Shared/Components/RecentProducts/Default.cshtml. The view content stays the same.

Update the Invocation

Before:

@Html.Action("RecentProducts", "Home", new { count = 10 })

After:

@await Component.InvokeAsync("RecentProducts", new { count = 10 })

Alternatively, use the TagHelper syntax after registering the assembly in _ViewImports.cshtml:

<vc:recent-products count="10"></vc:recent-products>

For the TagHelper syntax, add to _ViewImports.cshtml:

@addTagHelper *, MyApp

Step 4: Update Partial View References

Partial views are supported in ASP.NET Core but the invocation syntax changed.

Before:

@Html.Partial("_ProductCard", item)
@{ Html.RenderPartial("_Sidebar"); }

After:

<partial name="_ProductCard" model="item" />

The <partial> TagHelper is preferred over @Html.PartialAsync and @await Html.PartialAsync. The synchronous Html.Partial is removed in ASP.NET Core because views run asynchronously.

View discovery paths are the same by default: Views/<Controller>/ then Views/Shared/. Display templates (DisplayTemplates/) and editor templates (EditorTemplates/) follow the same conventions and are compatible.

Step 5: Migrate Custom HtmlHelper Extensions

Custom HtmlHelper extension methods use a different pattern in ASP.NET Core because the return type changed from HtmlString/MvcHtmlString to IHtmlContent.

Before:

public static MvcHtmlString IconLink(this HtmlHelper html, string text, string icon)
{
    return new MvcHtmlString($"<span class=\"{icon}\"></span> {HttpUtility.HtmlEncode(text)}");
}

After (option A — IHtmlHelper extension):

public static IHtmlContent IconLink(this IHtmlHelper html, string text, string icon)
{
    return new HtmlString($"<span class=\"{icon}\"></span> {HtmlEncoder.Default.Encode(text)}");
}

After (option B — custom TagHelper, preferred for new code):

[HtmlTargetElement("icon-link")]
public class IconLinkTagHelper : TagHelper
{
    public string Text { get; set; }
    public string Icon { get; set; }

    public override void Process(TagHelperContext context, TagHelperOutput output)
    {
        output.TagName = "span";
        output.Content.AppendHtml($"<span class=\"{Icon}\"></span> ");
        output.Content.Append(Text);
    }
}

Option A preserves the existing call sites (@Html.IconLink(...)). Option B is the ASP.NET Core idiomatic approach and uses <icon-link text="Click" icon="fa-home"></icon-link> syntax. Prefer Option A during migration to minimize view changes, then refactor to Option B as a follow-up.

Replace HttpUtility.HtmlEncode with HtmlEncoder.Default.Encode (from System.Text.Encodings.Web). Replace MvcHtmlString / HtmlString from System.Web with HtmlString from Microsoft.AspNetCore.Html or the IHtmlContent interface.

Step 6: Update View Data Passing Patterns

These patterns are mostly compatible but have behavioral differences:

• @model — fully compatible, no changes needed.
• ViewBag — works in ASP.NET Core MVC controllers and views. Not available in Razor Pages.
• ViewData — works in ASP.NET Core. The ViewData["Title"] pattern for page titles is the standard approach.
• TempData — works in ASP.NET Core but the default backing store changed from session state to cookies (CookieTempDataProvider). If the app stores large objects in TempData, configure SessionStateTempDataProvider in Program.cs:

builder.Services.AddControllersWithViews()
    .AddSessionStateTempDataProvider();
builder.Services.AddSession();

• WebViewPage<T> — if the project uses a custom base class derived from WebViewPage<T>, migrate to a custom RazorPage<T> base class or use _ViewImports.cshtml with @inject directives instead.

Step 7: Clean Up Removed APIs

Search for and remove these patterns that have no direct equivalent in ASP.NET Core:

For bundling cleanup (@Scripts.Render, @Styles.Render, BundleConfig.cs), follow the migrating-mvc-bundling skill.

Step 8: Verify Build

Build the project to confirm no compilation errors. Search for any remaining System.Web references in .cshtml and .cs files. Common post-migration build errors:

• Missing TagHelper attributes: Verify @addTagHelper directive in _ViewImports.cshtml.
• Html.Partial errors: Replace synchronous Html.Partial with <partial> TagHelper.
• MvcHtmlString not found: Replace with IHtmlContent.

HtmlHelper to TagHelper Quick Reference

Success Criteria

• _ViewImports.cshtml exists with @addTagHelper directive
• All @Html.ActionLink, @Html.BeginForm, @Html.TextBoxFor, and similar calls replaced with TagHelpers
• All @Html.Action / @Html.RenderAction calls replaced with ViewComponent invocations
• All @Html.Partial / @Html.RenderPartial calls replaced with <partial> TagHelper
• Custom HtmlHelper extensions updated to return IHtmlContent
• No [ChildActionOnly], MvcHtmlString, System.Web.Mvc, or @helper blocks remain
• ViewComponent classes created with corresponding views under Views/Shared/Components/
• Bundle references migrated per migrating-mvc-bundling skill
• Project builds without errors