bwfc-ascx-migration

ASCX User Control → Blazor Component Migration

Overview

ASP.NET Web Forms User Controls (.ascx files) are reusable markup fragments with code-behind. They map directly to Blazor .razor components with .razor.cs code-behind files.

The webforms-to-blazor CLI tool handles L1 conversion automatically. This skill guides L2 repair for common patterns that require contextual understanding.

How the CLI Handles ASCX Files

Step	What Happens
1. Directive removal	<%@ Control ... %> is stripped
2. Markup transforms	asp: prefixes removed, expressions converted
3. Code-behind preservation	Base class remapped, usings updated
4. @inherits injection	Added to .razor when code-behind inherits a CustomControls type
5. Output	.razor + .razor.cs pair in the output project

Critical Rules

1. Preserve the Code-Behind

ASCX code-behind files contain business logic that should compile unchanged. The CLI:

• Strips System.Web.UI.* usings
• Adds using BlazorWebFormsComponents.CustomControls;
• Preserves UserControl base class (now mapped to BWFC's UserControl)
• Injects @inherits UserControl into the .razor file

Do NOT rewrite code-behind logic. Fix compile errors by adding missing shims or stubs.

2. Properties Become Parameters

Web Forms exposes ASCX properties to parent pages. In Blazor, these become [Parameter] properties:

// Web Forms (worked without attribute)
public string Title { get; set; }

// Blazor (requires [Parameter])
[Parameter]
public string Title { get; set; }

The CLI's ParameterAttributeTransform handles this automatically for public properties.

3. Events Become EventCallback

ASCX controls that raise events to parent pages:

// Web Forms
public event EventHandler ItemSelected;
protected void OnItemSelected(EventArgs e) => ItemSelected?.Invoke(this, e);

// Blazor
[Parameter]
public EventCallback<EventArgs> ItemSelected { get; set; }
protected async Task OnItemSelected(EventArgs e) => await ItemSelected.InvokeAsync(e);