name	semantic-pattern-guardrails
description	Guardrails for implementing Web Forms semantic page-pattern rewrites in the migration CLI
domain	migration-architecture
confidence	high
source	manual

Context

Use this when adding semantic catalog entries to the Web Forms migration CLI. These rules apply to cross-file page-shape rewrites where the mechanical transforms have already converted raw syntax and the remaining work is contract normalization.

Patterns

Master/content normalization belongs in the semantic pass

Let the markup transforms do the local tag conversion first.
Then normalize generated master/page pairs to the BWFC-tested contract:
- master shell markup → ChildContent
- migrated <Content ContentPlaceHolderID="..."> blocks → ChildComponents
- preserve exact placeholder IDs, including head slots

Query/detail pages must stay read-only

Safe matches:

SelectMethod/code-behind only filters by [QueryString] / [RouteData]
no writes, redirects, form access, auth calls, or postback branches
one clear data-display page shape

Stop and emit TODO/manual review if:

the page mutates state
the page mixes route/query entry points in a way you cannot preserve exactly
the code-behind depends on postback/event sequencing

Action pages must still act

Safe matches:

empty or scaffold-only page
action happens on load from deterministic query inputs
one redirect target
no auth cookies, no POST body dependency, no external provider workflow

Anti-pattern:

converting an action page into a visible informational page that does nothing

Account pages are high-risk and mostly manual

Treat these as manual/TODO boundaries unless you have explicit HTTP endpoint/handler output:

login/logout
register
password reset token issuance/consumption
external auth challenge/callback
2FA provider selection and verification
add/remove external logins
phone / security settings that resignal identity state

Why:

Web Forms account pages depend on live HTTP response semantics and OWIN/Identity middleware
a Blazor component event handler cannot safely fake that contract

Minimum valid output contract

Master shell

<MasterPage>
    <Head>...</Head>
    <ChildContent>
        ...chrome...
        <ContentPlaceHolder ID="MainContent" />
    </ChildContent>
    <ChildComponents>
        @ChildComponents
    </ChildComponents>
</MasterPage>

Child page

<Site>
    <ChildComponents>
        <Content ContentPlaceHolderID="MainContent">
            ...
        </Content>
    </ChildComponents>
</Site>

Anti-Patterns

Rewriting multi-placeholder masters to @Body
Dropping ContentPlaceHolderID names
Pretending auth pages are fully migrated when only the shell was understood
Converting redirect-only action pages into dead-end content pages
Collapsing query/route precedence to a single hard-coded id path

Más de este repositorio

mismo repositorio

skill-name

FritzAndFriends/BlazorWebFormsComponents

{what this skill teaches agents}

2026-06-15449

contoso-migration-test

FritzAndFriends/BlazorWebFormsComponents

**WORKFLOW SKILL** — Execute end-to-end ContosoUniversity migration benchmark: clear output folder, run L1 script + L2 Copilot transforms, build, run Playwright acceptance tests, and generate a numbered run report. WHEN: "run contoso migration test", "test contoso university migration", "contoso migration benchmark", "run CU migration". INVOKES: migration-toolkit (scripts + skills), dotnet CLI, Playwright tests.

2026-06-02449

wingtip-migration-test

FritzAndFriends/BlazorWebFormsComponents

**WORKFLOW SKILL** - Execute the end-to-end WingtipToys migration benchmark: clear samples\AfterWingtipToys, run the migration-toolkit against samples\WingtipToys, repair the generated app until Playwright acceptance tests pass, and write a numbered run report with embedded screenshots under dev-docs\migration-tests\wingtiptoys. WHEN: "run Wingtip migration", "test WingtipToys migration", "Wingtip benchmark", "migrate WingtipToys", "rerun Wingtip migration". INVOKES: migration-toolkit (scripts + skills), dotnet CLI, Playwright tests.

2026-06-02449

bwfc-ascx-migration

FritzAndFriends/BlazorWebFormsComponents

Migrate ASP.NET Web Forms User Controls (.ascx) to Blazor components using BlazorWebFormsComponents. Covers ASCX-to-Razor conversion, code-behind preservation, tag prefix resolution, property/event mapping, and partial-class base class alignment. WHEN: 'migrate ascx', 'convert user control', 'ascx to blazor', 'user control migration'. FOR SINGLE OPERATIONS: use /bwfc-migration for full page migration, /bwfc-custom-control-migration for WebControl-based controls.

2026-06-02449

bwfc-custom-control-migration

FritzAndFriends/BlazorWebFormsComponents

Migrate custom ASP.NET Web Forms server controls (WebControl, CompositeControl) to Blazor using BlazorWebFormsComponents. Covers RenderContents/HtmlTextWriter preservation, TagKey mapping, AddAttributesToRender, CreateChildControls, and the one-line-change migration pattern. WHEN: 'migrate custom control', 'webcontrol to blazor', 'rendercontents migration', 'htmltextwriter blazor', 'custom server control'. FOR SINGLE OPERATIONS: use /bwfc-ascx-migration for .ascx user controls, /bwfc-migration for full page migration.

2026-06-02449

migration-standards

FritzAndFriends/BlazorWebFormsComponents

Enforce canonical migration standards for ASP.NET Web Forms to Blazor using BWFC. Covers target architecture (.NET 10, Server Interactive), database provider detection, event handler preservation, SelectMethod patterns, and page lifecycle mapping. WHEN: "migration standards", "target architecture", "render mode placement", "page base class", "Layer 1 vs Layer 2".

2026-06-02449

<MasterPage> <Head>...</Head> <ChildContent> ...chrome... <ContentPlaceHolder ID="MainContent" /> </ChildContent> <ChildComponents> @ChildComponents </ChildComponents> </MasterPage>