---
name: fritzandfriends/bwfc-custom-control-migration
source: https://app.decimal.ai/s/fritzandfriends-bwfc-custom-control-migration@1/SKILL.md
source_sha256: f4fa8773afab
---
# 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.**
```csharp
// 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:
```csharp
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:
```csharp
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();
}
}
```
### Pattern 3: AddAttributesToRender (Custom Attributes)
Add data attributes, ARIA attributes, or other custom attributes to the outer tag:
```csharp
public class DataPanel : WebControl
{
[Parameter]
public string DataId { get; set; }
protected override HtmlTextWriterTag TagKey => HtmlTextWriterTag.Div;
protected override void AddAttributesToRender(HtmlTextWriter writer)
{
base.AddAttributesToRender(writer); // ID, CssClass, Style, ToolTip, Enabled
writer.AddAttribute("data-panel-id", DataId);
writer.AddAttribute("role", "region");
}
protected override void RenderContents(HtmlTextWriter writer)
{
writer.Write("Panel content here");
}
}
```
### Pattern 4: CompositeControl (Child Controls)
For controls that compose multiple child controls:
```csharp
public class SearchBox : CompositeControl
{
[Parameter]
public string Placeholder { get; set; } = "Search...";
protected override void Render(HtmlTextWriter writer)
{
writer.AddAttribute(HtmlTextWriterAttribute.Class, "search-container");
writer.RenderBeginTag(HtmlTextWriterTag.Div);
writer.AddAttribute(HtmlTextWriterAttribute.Type, "text");
writer.AddAttribute(HtmlTextWriterAttribute.Placeholder, Placeholder);
writer.RenderBeginTag(HtmlTextWriterTag.Input);
writer.RenderEndTag();
writer.AddAttribute(HtmlTextWriterAttribute.Type, "submit");
writer.RenderBeginTag(HtmlTextWriterTag.Button);
writer.Write("Go");
writer.RenderEndTag();
writer.RenderEndTag(); // div
}
}
```
## Migration Steps
### Step 1: Change the Using
```diff
- using System.Web.UI;
- using System.Web.UI.WebControls;
+ using BlazorWebFormsComponents.CustomControls;
+ using Microsoft.AspNetCore.Components;
```
### Step 2: Add [Parameter] to Public Properties
```diff
+ [Parameter]
public string Title { get; set; }
+ [Parameter]
public bool ShowHeader { get; set; } = true;
```
### Step 3: Remove Web Forms-Only Members
Remove or stub these if present (they have no Blazor equivalent):
| Member | Action |
|--------|--------|
| `ViewState` property bags | Replace with private fields |
| `CreateChildControls()` | Move logic to `Render` or `RenderContents` |
| `EnsureChildControls()` | Remove (no lazy initialization needed) |
| `INamingContainer` | Remove (Blazor handles scoping differently) |
| `IPostBackDataHandler` | Remove (use Blazor events instead) |
| `IPostBackEventHandler` | Remove (use `EventCallback`) |
### Step 4: Verify Rendering
The control should render identical HTML. Test with bUnit:
```razor
@inherits BlazorWebFormsTestContext
@code {
[Fact]
public void MyControl_RendersExpectedHtml()
{
var cut = Render(@);
cut.Markup.ShouldContain("`
## Reference
- [Custom WebControl Migration Guide](../../docs/Migration/CustomWebControl.md)
- [WebControl source](../../src/BlazorWebFormsComponents/CustomControls/WebControl.cs)
- [HtmlTextWriter source](../../src/BlazorWebFormsComponents/CustomControls/HtmlTextWriter.cs)
- [CompositeControl source](../../src/BlazorWebFormsComponents/CustomControls/CompositeControl.cs)
- [Sample page](../../samples/AfterBlazorServerSide/Components/Pages/ControlSamples/Migration/CustomWebControlDemo.razor)