.NET Core中Html Helper扩展无法在页面渲染的问题排查

在ASP.NET Core 8 MVC应用中，自定义HtmlHelperExtensions生成Bootstrap轮播组件时，视图调用后页面仅输出Microsoft.AspNetCore.Mvc.Rendering.TagBuilder文本，而非预期的HTML结构。尝试过@Html.Raw(Html.Carousel(...))及修改返回类型为IHtmlContent均未解决问题。

问题代码 #

轮播扩展代码

public static IHtmlContent Carousel(this IHtmlHelper html, IList<string> imageSources)
{
    var carouselWrapper = new TagBuilder("div");
    carouselWrapper.AddCssClass("carousel slide");
    carouselWrapper.MergeAttribute("data-ride", "carousel");
    
    var innerDiv = new TagBuilder("div");
    innerDiv.AddCssClass("carousel-inner");
    
    for (int i = 0; i < imageSources.Count; i++)
    {
        var itemDiv = new TagBuilder("div");
        itemDiv.AddCssClass("carousel-item");
    
        if (i == 0)
        {
            itemDiv.AddCssClass("active");
        }
    
        var image = new TagBuilder("img");
        image.MergeAttribute("src", imageSources[i]);
        image.AddCssClass("d-block w-100");
        image.MergeAttribute("alt", "Image " + (i + 1));
    
        itemDiv.InnerHtml.AppendHtml(image);
        innerDiv.InnerHtml.AppendHtml(itemDiv);
    }
    
    carouselWrapper.InnerHtml.AppendHtml(innerDiv);

    var prevButton = CreateControlButton("carousel-control-prev", "prev", "Previous");
    var nextButton = CreateControlButton("carousel-control-next", "next", "Next");

    carouselWrapper.InnerHtml.AppendHtml(prevButton);
    carouselWrapper.InnerHtml.AppendHtml(nextButton);

    return new HtmlString(carouselWrapper.ToString());
}

private static TagBuilder CreateControlButton(string className, string slideDirection, string ariaLabel)
{
    var button = new TagBuilder("button");
    button.AddCssClass(className);
    button.MergeAttribute("type", "button");
    button.MergeAttribute("data-target", "#carouselExampleAutoplaying");
    button.MergeAttribute("data-slide", slideDirection);

    var iconSpan = new TagBuilder("span");
    iconSpan.AddCssClass("carousel-control-" + slideDirection + "-icon");
    iconSpan.MergeAttribute("aria-hidden", "true");

    var visuallyHiddenSpan = new TagBuilder("span");
    visuallyHiddenSpan.AddCssClass("visually-hidden");
    visuallyHiddenSpan.InnerHtml.AppendHtml(ariaLabel);

    button.InnerHtml.AppendHtml(iconSpan);
    button.InnerHtml.AppendHtml(visuallyHiddenSpan);

    return button;
}

_ViewImports配置

@using ThatDaleDudes_Plugins.Infrastructure.Extensions

视图调用代码

@Html.Carousel(Model.TestSources.ToList())

解决方案 #

问题根源在于：

1. TagBuilder.ToString()默认返回类型名称而非HTML内容，将其包装为HtmlString无法正确触发视图引擎的HTML渲染逻辑。
2. TagBuilder本身已实现IHtmlContent接口，直接返回实例即可让视图引擎正确解析输出完整HTML。

修改步骤：

1. 直接返回TagBuilder实例：移除return new HtmlString(carouselWrapper.ToString());，改为返回carouselWrapper。
2. 修正Bootstrap属性兼容：Bootstrap 5+使用data-bs-*前缀替代旧版data-*，同时确保轮播容器ID与控制按钮的data-target匹配。

修改后的完整扩展代码：

public static IHtmlContent Carousel(this IHtmlHelper html, IList<string> imageSources)
{
    var carouselWrapper = new TagBuilder("div");
    carouselWrapper.AddCssClass("carousel slide");
    carouselWrapper.MergeAttribute("data-bs-ride", "carousel");
    // 生成匹配控制按钮data-target的ID
    carouselWrapper.GenerateId("carouselExampleAutoplaying", "");
    
    var innerDiv = new TagBuilder("div");
    innerDiv.AddCssClass("carousel-inner");
    
    for (int i = 0; i < imageSources.Count; i++)
    {
        var itemDiv = new TagBuilder("div");
        itemDiv.AddCssClass("carousel-item");
    
        if (i == 0)
        {
            itemDiv.AddCssClass("active");
        }
    
        var image = new TagBuilder("img");
        image.MergeAttribute("src", imageSources[i]);
        image.AddCssClass("d-block w-100");
        image.MergeAttribute("alt", $"Image {i+1}");
    
        itemDiv.InnerHtml.AppendHtml(image);
        innerDiv.InnerHtml.AppendHtml(itemDiv);
    }
    
    carouselWrapper.InnerHtml.AppendHtml(innerDiv);

    var prevButton = CreateControlButton("carousel-control-prev", "prev", "Previous");
    var nextButton = CreateControlButton("carousel-control-next", "next", "Next");

    carouselWrapper.InnerHtml.AppendHtml(prevButton);
    carouselWrapper.InnerHtml.AppendHtml(nextButton);

    // 直接返回TagBuilder，它实现了IHtmlContent接口
    return carouselWrapper;
}

private static TagBuilder CreateControlButton(string className, string slideDirection, string ariaLabel)
{
    var button = new TagBuilder("button");
    button.AddCssClass(className);
    button.MergeAttribute("type", "button");
    button.MergeAttribute("data-bs-target", "#carouselExampleAutoplaying");
    button.MergeAttribute("data-bs-slide", slideDirection);

    var iconSpan = new TagBuilder("span");
    iconSpan.AddCssClass($"carousel-control-{slideDirection}-icon");
    iconSpan.MergeAttribute("aria-hidden", "true");

    var visuallyHiddenSpan = new TagBuilder("span");
    visuallyHiddenSpan.AddCssClass("visually-hidden");
    visuallyHiddenSpan.InnerHtml.Append(ariaLabel);

    button.InnerHtml.AppendHtml(iconSpan);
    button.InnerHtml.AppendHtml(visuallyHiddenSpan);

    return button;
}

视图调用保持不变

@Html.Carousel(Model.TestSources.ToList())

修改后，视图引擎会正确调用TagBuilder的WriteTo方法输出完整的轮播HTML结构，同时兼容Bootstrap 5+的属性要求。

内容的提问来源于stack exchange，提问作者ThatDaleDude