feat: webforms-to-blazor C# global tool — full L1 transform pipeline

[csharpfritz]

webforms-to-blazor — C# Global Tool

Replaces bwfc-migrate.ps1 with a compiled C# dotnet global tool, addressing the strategic decision to:

• Reduce injection surface — compiled binary vs. PowerShell script
• Enable skill chaining — webforms-to-blazor migrate as a CLI command in SKILL.md
• NuGet distribution — dotnet tool install --global Fritz.WebFormsToBlazor

What's in this PR

Pipeline Infrastructure (5 core files)

• MigrationPipeline — orchestrates sequential transforms with explicit ordering
• MigrationContext / FileMetadata — per-file + project-wide state
• IMarkupTransform / ICodeBehindTransform — transform interfaces with Order property
• SourceScanner — discovers .aspx/.ascx/.master files, pairs with code-behind

16 Markup Transforms (ported from PowerShell)

Transform	Order	Covers
PageDirective	100	<%@ Page %> → @page + route
MasterDirective	110	<%@ Master %> removal
ControlDirective	120	<%@ Control %> → @inherits
ImportDirective	200	<%@ Import %> → @using
RegisterDirective	210	<%@ Register %> removal
ContentWrapper	300	asp:Content → HeadContent / strip
FormWrapper	310	<form runat> → <div>
Expression	500	<%: %>, <%# %>, Eval(), Bind(), Item.
AjaxToolkitPrefix	600	ajaxToolkit: → bare name
AspPrefix	610	asp: → bare name
AttributeStrip	700	runat, ItemType→TItem, ID→id
EventWiring	710	OnClick="X" → OnClick="@X"
UrlReference	720	~/ → /
TemplatePlaceholder	800	Placeholder elements → @context
AttributeNormalize	810	Boolean/enum/unit normalization
DataSourceId	820	DataSourceID removal + TODO

11 Code-Behind Transforms (ported from PowerShell)

Transform	Order	Covers
TodoHeader	50	Injects migration TODO banner
UsingStrip	100	Removes System.Web.*, Microsoft.AspNet.*
BaseClassStrip	200	Strips : Page, : System.Web.UI.Page
ResponseRedirect	300	→ NavigationManager.NavigateTo()
SessionDetect	400	Session["key"] → TODO guidance
ViewStateDetect	410	ViewState["key"] → TODO guidance
IsPostBack	500	Brace-counting unwrap / TODO annotation
PageLifecycle	600	Page_Load → OnInitializedAsync etc.
EventHandlerSignature	700	Strip sender, EventArgs
DataBind	800	Cross-file DataSource → Items correlation
UrlCleanup	900	.aspx literals → clean routes

CLI Commands (2 public, 0 private)

• webforms-to-blazor migrate --input <path> --output <path> [options]
• webforms-to-blazor convert --input <file> [options]
• Analysis runs internally as part of migrate — no public analyze command

Test Suite (72 tests, all passing)

• 21 markup L1 acceptance tests (TC01-TC21)
• 8 code-behind L1 acceptance tests (TC13-TC21)
• 3 data integrity tests
• 13 CLI argument parsing tests (including verify analyze is NOT exposed)
• 27 individual transform unit tests

Stats

• 48 C# source files / 2,895 lines
• Ports 27 transforms from 3,600 lines of PowerShell
• 72/72 tests passing ✅

Architecture

See dev-docs/global-tool-architecture.md for the full design doc.

What's NOT in this PR (future work)

• Project scaffolding (ProjectScaffolder, ShimGenerator)
• Config transforms (WebConfigTransformer)
• --use-ai integration with Copilot skills
• NuGet packaging and signing

Closes #18 (supersedes PR FritzAndFriends#328)

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

General fix: Replace Path.Combine with Path.Join when you are strictly concatenating path segments and do not want later absolute segments to discard earlier ones. Path.Join concatenates segments with directory separators but does not treat later absolute paths specially.

Concrete fix here: In CreateMockWebHostEnvironment in BlazorWebFormsTestContext, change the WebRootPath setup from Path.Combine(Path.GetTempPath(), "wwwroot") to Path.Join(Path.GetTempPath(), "wwwroot"). This preserves the existing behavior for the current arguments while eliminating the risk that a later absolute segment would drop the temp path. No additional imports are needed because Path.Join is in System.IO, already imported at the top of the file.

Only one line needs to change in src/BlazorWebFormsComponents.Test/BlazorWebFormsTestContext.cs, inside the CreateMockWebHostEnvironment method. No new methods, classes, or configuration are required.

In general, to avoid Path.Combine silently discarding earlier arguments when a later argument is an absolute path, replace it with Path.Join when you are constructing paths from a known base path and additional segments. Path.Join concatenates path segments with the appropriate directory separators without interpreting rooted later segments as overriding earlier ones.

For this file, the best fix that preserves existing behavior is to replace each Path.Combine call used for expectations in these tests with Path.Join, keeping the same arguments and order. System.IO is already imported at the top of ServerShimTests.cs, so no new using directives are required. Concretely:

• On line 36, change Path.Combine(WebRoot, "images", "logo.png") to Path.Join(WebRoot, "images", "logo.png").
• On line 46, change Path.Combine(WebRoot, "css", "site.css") to Path.Join(WebRoot, "css", "site.css").
• On line 56, change Path.Combine(ContentRoot, "images", "logo.png") to Path.Join(ContentRoot, "images", "logo.png").

No additional methods, definitions, or dependencies are needed.

General fix: replace uses of Path.Combine in these tests, where we are simply appending known-relative segments to an absolute base, with Path.Join. Path.Join does not discard earlier segments when later ones are absolute, so it is safer and aligns with the recommendation.

Best concrete fix here: in src/BlazorWebFormsComponents.Test/ServerShimTests.cs, change the five result.ShouldBe(Path.Combine(...)) expectations so they use Path.Join instead of Path.Combine, preserving all arguments and their order. No other logic or arguments need to change, and no imports need modification since Path.Join is also in System.IO.

Needed elements:

• No new methods or fields.
• No new imports (we already have using System.IO;).
• Only the five lines using Path.Combine in the shown region need to be updated.

General fix: Wherever Path.Combine is used with the risk that a later argument could be absolute (especially when earlier arguments are important), replace it with Path.Join, which concatenates path segments without treating absolute later segments as overriding earlier ones.

Best fix here: In ResponseShimTests.razor, line 30, change System.IO.Path.Combine(System.IO.Path.GetTempPath(), "wwwroot") to System.IO.Path.Join(System.IO.Path.GetTempPath(), "wwwroot"). This preserves behavior (joining the temp directory with wwwroot) while eliminating the analyzer warning about dropped arguments. No other parts of the file need changes, and no new imports are required because we are still using System.IO.Path.

Specifics:

• File: src/BlazorWebFormsComponents.Test/WebFormsPageBase/ResponseShimTests.razor
• In the RenderWithMockNav method, update the setup for WebRootPath to use Path.Join instead of Path.Combine.
• No additional methods, definitions, or using directives are needed.

In general, to avoid Path.Combine silently dropping earlier segments when later ones are absolute paths, replace such uses with Path.Join. Path.Join concatenates path segments with appropriate separators but does not treat later absolute paths as overriding previous ones.

For this specific file, the best fix without changing observable behavior is:

• In RegisterShimServices, change the WebRootPath setup from System.IO.Path.Combine(System.IO.Path.GetTempPath(), "wwwroot") to System.IO.Path.Join(System.IO.Path.GetTempPath(), "wwwroot").
• System.IO.Path.Join is available in the same namespace as Path.Combine, and the code already uses fully qualified names, so no new using directive is required.
• No other lines or methods need modification.

In general, to avoid Path.Combine silently dropping earlier segments, use Path.Join when you are just concatenating path segments and do not need the path normalization / rooted-path semantics of Path.Combine. Path.Join will not discard earlier segments when a later segment is rooted.

For this specific case, we should replace System.IO.Path.Combine(System.IO.Path.GetTempPath(), "wwwroot") with System.IO.Path.Join(System.IO.Path.GetTempPath(), "wwwroot") on line 35. This preserves the effective result for a relative "wwwroot" segment, keeps the mock environment behavior unchanged, and follows the recommendation given. No new imports are needed because Path.Join is in the same System.IO.Path class already in use.

General approach: Replace Path.Combine with Path.Join wherever there is a risk that a later argument might be (or might become) an absolute path. Path.Join concatenates path segments using the directory separator but does not discard earlier segments when later segments are absolute.

Best fix here: On line 33, change Path.Combine(_env.WebRootPath ?? _env.ContentRootPath, ...) to Path.Join(_env.WebRootPath ?? _env.ContentRootPath, ...). This keeps the logic, arguments, and behavior for relative paths identical while removing the risk that _env.WebRootPath ?? _env.ContentRootPath is ignored if the second argument is absolute. The existing using System.IO; already brings Path into scope, and Path.Join is available there, so no new imports or helpers are required.

Specific changes:

• File: src/BlazorWebFormsComponents/ServerShim.cs
• In MapPath(string virtualPath), update the "~/" branch to use Path.Join instead of Path.Combine.
• Leave the later Path.Combine for non-"~/" paths unchanged, as that case is already guarding with TrimStart('/'), making the second argument explicitly relative.

No additional methods, imports, or definitions are needed.

General approach: Avoid using Path.Combine when concatenating a base directory with a possibly rooted second argument; use Path.Join instead, which does not discard earlier segments when later ones are absolute. This keeps behavior for normal relative paths but removes the risk of silently dropping the base path.

Concrete fix here: In ServerShim.MapPath, change the Path.Combine call on line 36 to Path.Join. The arguments and the surrounding string manipulation should remain unchanged to preserve the existing behavior for virtual paths like /foo/bar. The earlier branch for ~/ can safely continue to use Path.Combine because the second argument is sliced from virtualPath[2..] and therefore cannot be rooted.

File/region to change:

• File: src/BlazorWebFormsComponents/ServerShim.cs
• Method: public string MapPath(string virtualPath)
• Line 36: return Path.Combine(_env.ContentRootPath, ...); → return Path.Join(_env.ContentRootPath, ...);

No new methods or using directives are needed; Path.Join is in System.IO, which is already imported at the top of the file.