webforms-to-angular

A Claude Skill for migrating ASP.NET Web Forms (2008-era, .NET Framework 2.0/3.5/4.x) projects to a modern stack: Angular 17+ on the frontend and ASP.NET Core .NET 8 on the backend.

This is not a code generator that promises one-click migration. It's a structured playbook that Claude follows page-by-page — analyzing the original .aspx + code-behind, separating UI plumbing from business logic, designing resource-oriented endpoints, and producing idiomatic Angular components.

Why this exists

Web Forms migrations fail when teams try to translate markup one-to-one. A GridView is not a directive — it's paging + sorting + row actions, each of which has a separate modern equivalent. This skill encodes that translation philosophy so Claude doesn't generate "Web Forms in Angular clothing."

What it does

The skill works in four phases, one page at a time:

1. Inventory — scan the solution, count pages, detect cross-cutting concerns (FormsAuthentication, Session, UpdatePanel, ViewState, raw SQL).
2. Analyze a single page — parse the .aspx, classify every line of code-behind into UI plumbing / presentational / business logic, surface red flags before generating anything.
3. Generate .NET 8 API — Minimal API endpoints, DTOs, an application service decoupled from HttpContext, plus the Program.cs diff to wire it in.
4. Generate Angular component — standalone component, signals for state, typed reactive forms, @if/@for control flow, with a matching HTTP service.

Installation

Option 1: Install the packaged skill

Download webforms-to-angular.skill and upload it via your Claude client's skill installation flow (Settings → Capabilities → Skills, on platforms that support skills).

Option 2: Use the source

Clone the repo and point your skill loader at the root directory:

git clone https://github.com/<you>/webforms-to-angular.git

The SKILL.md at the root is the entry point.

Repo layout

.
├── SKILL.md                          # Orchestrator — phase routing
├── references/
│   ├── control-mapping.md            # GridView → table, validators → reactive forms, …
│   ├── codebehind-extraction.md      # The three-bucket extraction model
│   ├── viewstate-and-postback.md     # What disappears, what becomes signals
│   ├── api-design-net8.md            # Minimal API patterns, DTOs, IUserContext
│   ├── angular-patterns.md           # Standalone components, signals, forms
│   └── auth-and-session.md           # FormsAuth → cookie auth or JWT
├── scripts/
│   ├── inventory.py                  # Solution-wide scan → JSON inventory
│   └── analyze_aspx.py               # Single-page parse → structured JSON
├── assets/
│   ├── templates/                    # Scaffolding for endpoint, component, service
│   └── examples/                     # Worked before/after for CustomerList.aspx
├── README.md
├── CONTRIBUTING.md
├── LICENSE
└── CHANGELOG.md

Quick start

Once the skill is installed, prompts like these will trigger it:

• "I have a Web Forms solution at ./Legacy/MyApp.Web. Help me plan the migration." → inventory pass.
• "Migrate OrdersGrid.aspx to Angular 17 and .NET 8." → analysis → API → component.
• "Here's my .aspx.cs. Separate it into an API layer and an Angular component." → extraction pass.

The skill will ask before making big choices (UI library, auth strategy, REST vs RPC style) and remember the answers for the rest of the migration.

Design principles

• One page at a time. No big-bang migrations. The unit of work is one .aspx and its code-behind.
• Behavior over markup. Translate what the user sees and does, not the implementation mechanism.
• Code-behind is not application logic. Every line gets classified before being generated anywhere.
• ViewState is not state. Figure out what was being remembered and put it in the right place — signal, route param, or server.
• Resource-oriented endpoints, not RPC. btnApprove_Click becomes PATCH /orders/{id}/status, not POST /api/btnApprove.
• Strangler fig over big bang. The legacy app keeps running until the new one is verified, page by page behind a reverse proxy.

Extending the skill

This is the initial version. Two places you'll likely want to extend as you migrate real pages:

1. references/control-mapping.md — add a section for any third-party control suite your project uses (Telerik, DevExpress, Infragistics, AjaxControlToolkit). Mapping one custom control well saves hours on every page that uses it.
2. scripts/analyze_aspx.py — the parser is a tolerant regex scan. If your project has nested templates or unusual control patterns it misses, extend the regex set or swap to an HTML parser like lxml with recover=True.

PRs welcome — see CONTRIBUTING.md.

What this skill is not

• A database migration tool. It doesn't change your schema, your ORM, or your stored procedures. Wrap the data layer behind a repository; don't rewrite it as part of this migration.
• A one-click upgrade. Expect ~1–4 hours of human work per non-trivial page, even with the skill helping.
• A replacement for understanding your own application. The skill makes Claude better at the mechanical parts so you can spend your attention on the parts that need judgment.

License

MIT — see LICENSE.