bwfc-custom-control-migration

Custom WebControl → Blazor Migration

Overview

ASP.NET Web Forms custom server controls inherit from System.Web.UI.WebControls.WebControl and render HTML imperatively via HtmlTextWriter. BlazorWebFormsComponents provides a drop-in replacement that lets this code work unchanged in Blazor.

The key principle: change one using statement, keep your code.

// Before (Web Forms)
using System.Web.UI.WebControls;

// After (Blazor + BWFC)
using BlazorWebFormsComponents.CustomControls;

How It Works

The BWFC WebControl class overrides Blazor's BuildRenderTree:

1. Creates an HtmlTextWriter instance (backed by StringBuilder)
2. Calls AddAttributesToRender(writer) — emits ID, class, style, tooltip, disabled
3. Calls Render(writer) → RenderBeginTag → RenderContents → RenderEndTag
4. Captures the HTML string via writer.GetHtml()
5. Emits it via builder.AddMarkupContent(0, html)

Your imperative rendering code produces the exact same HTML it did in Web Forms.

Supported Patterns

Pattern 1: TagKey + RenderContents (Most Common)

The classic Web Forms pattern — override TagKey for the outer element, RenderContents for the inner HTML:

using BlazorWebFormsComponents.CustomControls;
using Microsoft.AspNetCore.Components;

public class StatusBadge : WebControl
{
    [Parameter]  // Only addition for Blazor
    public string Status { get; set; }

    protected override HtmlTextWriterTag TagKey => HtmlTextWriterTag.Span;

    protected override void RenderContents(HtmlTextWriter writer)
    {
        writer.RenderBeginTag(HtmlTextWriterTag.Strong);
        writer.Write(Status);
        writer.RenderEndTag();
    }
}

Pattern 2: Full Render Override

For controls that need complete control over output:

public class CustomButton : WebControl
{
    [Parameter]
    public string Text { get; set; }

    [Parameter]
    public string ButtonType { get; set; } = "button";

    protected override void Render(HtmlTextWriter writer)
    {
        writer.AddAttribute(HtmlTextWriterAttribute.Type, ButtonType);
        writer.RenderBeginTag(HtmlTextWriterTag.Button);
        writer.Write(Text);
        writer.RenderEndTag();
    }
}