BlazorWebFormsComponents

A collection of Blazor components that are drop-in replacements for the ASP.NET Web Forms control of the same name. The library also includes some other shims and modules that make migrating to Blazor a smooth experience

Live Samples running on Azure

Sample Site

The sample site showcases all components with interactive examples, code snippets, and a searchable catalog.

Homepage & Component Catalog

GridView with Interactive Data

Chart Component with Chart.js

Fuzzy Search

Approach + Considerations

We believe that Web Forms applications that have been well maintained and provide value should have a path forward to the new user-interface frameworks with minimal changes. This is not an application converted nor is it a patch that can be applied to your project that magically makes it work with ASP.NET Core. This repository contains a library and series of strategies that will allow you to re-use much of your markup, much of your business code and help shorten your application re-write process.

This is not for everyone, not everyone needs to migrate their application. They can continue being supported as Web Forms for a very long time (2029 EOL at the time of this writing) and the applications that are considered for migration to Blazor may be better suited with a complete re-write. For those applications that need to be migrated, this library should help make that process simpler by providing components with the same names, markup, and functionality as previously available.

Documentation is available online. Get started with your migration, steps ahead, and strategy documentation for various controls and tools used are available. Live versions of these components are availalbe on the Live Samples website

Portions of the original .NET Framework are contributed to this project under their MIT license.

Migration CLI Tool

The webforms-to-blazor CLI tool automates the first phase of Web Forms to Blazor migration. It applies deterministic transforms to your markup and code-behind, removing boilerplate and converting patterns:

# Full project migration
dotnet tool install --global Fritz.WebFormsToBlazor
webforms-to-blazor migrate --input ./MyWebFormsProject --output ./MyBlazorProject --scaffold

# Or convert individual files
webforms-to-blazor convert --input ProductCard.ascx --output ProductCard.razor

What it does:

• Converts directives: <%@ Page %> → @page, <%@ Control %> → @inherits
• Removes asp: prefixes: <asp:Button> → <Button>
• Converts expressions: <%: Model.Name %> → @(Model.Name)
• Detects patterns: Injects TODO comments for Copilot L2 automation
• Scaffolds projects: Generates Program.cs, shims, and services

See the CLI Tool Documentation for:

• Transform Reference — All 33 transforms with before/after examples
• TODO Categories — Understand migration guidance comments
• Report Schema — Interpret the migration report

JavaScript Migration & ClientScript Support

Migrating JavaScript from Web Forms' Page.ClientScript and ScriptManager to Blazor's IJSRuntime is crucial for any real Web Forms application. ClientScript Migration Guide covers:

• Converting RegisterStartupScript() to OnAfterRenderAsync()
• Migrating script includes and inline blocks
• Replacing postback event patterns with Blazor events
• Handling form validation with EditContext
• ScriptManager patterns and their Blazor equivalents

Diagnostic Rules help identify patterns that need migration:

• BWFC022 — Page.ClientScript usage
• BWFC023 — IPostBackEventHandler implementation
• BWFC024 — ScriptManager code-behind methods

Blazor Components for Controls

There are a significant number of controls in ASP.NET Web Forms, and we will focus on creating components in the following order:

• Editor Controls
  • AdRotator
  • BulletedList
  • Button
  • Calendar
  • CheckBox
  • CheckBoxList
  • DropDownList
  • FileUpload
  • HiddenField
  • Image
  • ImageButton
  • ImageMap
  • Label
  • LinkButton
  • ListBox
  • Literal
  • Localize
  • MultiView
  • Panel
  • PlaceHolder
  • RadioButton
  • RadioButtonList
  • Table
  • TextBox
  • View
  • Xml — Deferred (details)
• Data Controls
  • Chart
  • DataGrid
  • DataList
  • DataPager
  • DetailsView
  • FormView
  • GridView
  • ListView
  • Repeater
• Validation Controls
  • CompareValidator
  • CustomValidator
  • RangeValidator
  • RegularExpressionValidator
  • RequiredFieldValidator
  • ValidationSummary
• Navigation Controls
  • HyperLink
  • Menu
  • SiteMapPath
  • TreeView
• Login Controls
  • ChangePassword
  • CreateUserWizard
  • Login
  • LoginName
  • LoginStatus
  • LoginView
  • PasswordRecovery
• AJAX Controls
  • ScriptManager
  • ScriptManagerProxy
  • Substitution
  • Timer
  • UpdatePanel
  • UpdateProgress

Ajax Control Toolkit Components

The Ajax Control Toolkit extender components are available in a separate NuGet package:

These components enable seamless migration of Ajax Control Toolkit extenders to Blazor with minimal markup changes. Simply remove the ajaxToolkit: prefix and you're ready to go!

Supported extender and container components:

• Accordion — Collapsible content panes
• AutoCompleteExtender — Typeahead suggestions
• CalendarExtender — Popup date picker
• CollapsiblePanelExtender — Panel collapse/expand
• ConfirmButtonExtender — Browser confirmation dialogs
• FilteredTextBoxExtender — Character filtering
• HoverMenuExtender — Hover-triggered popups
• MaskedEditExtender — Input mask formatting
• ModalPopupExtender — Modal popup dialogs
• NumericUpDownExtender — Numeric spinner
• PopupControlExtender — Click-triggered popups
• SliderExtender — Range slider
• TabContainer — Tabbed content panels
• ToggleButtonExtender — Image toggle for checkboxes

See the full documentation for detailed examples, migration guidance, and render mode requirements.

We will NOT be convertingany DataSource objects (SqlDataSource, ObjectDataSource, EntityDataSource, LinqDataSource, XmlDataSource, SiteMapDataSource, AccessDataSource), Wizard components, skins or themes. Once this first collection of controls is written, we can consider additional features like modern tag formatting.

Utility Features

There are a handful of features that augment the ASP.NET development experience that are made available as part of this project in order to support migration efforts. Importantly, these features are NOT implemented the same way that they are in Web Forms, but rather have the same API and behave in a proper Blazor fashion. These features include:

• DataBinder
• ID Rendering - Render HTML IDs for JavaScript integration
• JavaScript Setup - Options for auto-loading required JavaScript
• Page System - WebFormsPageBase, IPageService, and Page renderer (Page.Title, IsPostBack equivalents)
• ViewState

Custom Control Migration Support

For applications with custom controls inheriting from WebControl or CompositeControl, the library provides:

• Adapter Classes: WebControl, CompositeControl, and HtmlTextWriter classes that enable minimal-change migration
  • Base attributes (ID, CssClass, Style) are automatically applied - no manual intervention needed
• Roslyn Analyzers: The BlazorWebFormsComponents.Analyzers NuGet package provides automated code analysis and fixes:
  • BWFC001: Detects public properties missing [Parameter] attributes with automatic fix

See the Custom Controls Migration Guide for details.

Compiling the project

There are three different types of .NET projects in this repository: .NET Framework, .NET Core, and .NET Standard. The sample projects are in the /samples folder, while the unit test project is next to the component library in the /src folder. From the root of the repository, you should be able to execute:

dotnet restore to restore packages

dotnet run --project samples/AfterBlazorServerSide to start the Blazor Server-Side samples

Testing

The project includes two types of tests:

Unit Tests

Unit tests for the component library are located in src/BlazorWebFormsComponents.Test/ and use xUnit with bUnit for component testing.

Run unit tests with:

dotnet test src/BlazorWebFormsComponents.Test

Integration Tests

Integration tests using Playwright validate the sample application pages. These tests are located in samples/AfterBlazorServerSide.Tests/.

To run integration tests locally:

1. Install Playwright browsers (first time only):

   pwsh samples/AfterBlazorServerSide.Tests/bin/Debug/net10.0/playwright.ps1 install

2. Run the tests:

   dotnet test samples/AfterBlazorServerSide.Tests

See samples/AfterBlazorServerSide.Tests/README.md for more details.

Releasing

This project uses automated scripts with Nerdbank.GitVersioning to help with version publishing and release management. See the scripts/README.md for detailed documentation on:

• prepare-release.sh - Uses nbgv to update version.json and generates release notes
• generate-release-notes.sh - Creates formatted release notes from git commits
• publish-release.sh - Uses nbgv tag to create and publish release tags

Quick workflow:

1. On dev branch: ./scripts/prepare-release.sh 0.14
2. Merge dev to main
3. On main branch: ./scripts/publish-release.sh

The NuGet package is automatically published via GitHub Actions when a version tag is pushed.