cli-transform-authoring

CLI Transform Authoring

This skill covers creating new transforms for the webforms-to-blazor CLI migration pipeline.

Architecture Overview

The migration CLI uses two transform interfaces that run in sequence during file conversion:

1. Markup transforms (IMarkupTransform) — Convert .aspx/.ascx/.master markup to .razor syntax
2. Code-behind transforms (ICodeBehindTransform) — Convert .aspx.cs code-behind to .razor.cs

Both interfaces share the same contract:

public interface IMarkupTransform  // (or ICodeBehindTransform)
{
    string Name { get; }
    int Order { get; }
    string Apply(string content, FileMetadata metadata);
}

• Name — Human-readable identifier (used in logs and diagnostics)
• Order — Execution sequence (ascending). Lower numbers run first.
• Apply — Takes current content + file metadata, returns transformed content

Pipeline Execution Order

MigrationPipeline runs transforms in this order:

1. Markup transforms (sorted by Order ascending) — all run on .razor content
2. Code-behind transforms (sorted by Order ascending) — all run on .razor.cs content
3. Semantic patterns (SemanticPatternCatalog) — page-level rewrites after all transforms

FileMetadata

Every transform receives FileMetadata which carries context about the file being processed:

• OriginalPath — Source .aspx path
• OutputPath — Target .razor path
• PageDirectives — Parsed directive info (CodeBehind, Inherits, MasterPageFile)
• MarkupContent — Can be set by code-behind transforms to modify the markup file
• CodeBehindContent — The code-behind source
• IsUserControl / IsMasterPage — File type flags

Creating a New Transform

Step 1: Create the Transform Class

src/BlazorWebFormsComponents.Cli/Transforms/Markup/MyNewTransform.cs
    — or —
src/BlazorWebFormsComponents.Cli/Transforms/CodeBehind/MyNewTransform.cs

using BlazorWebFormsComponents.Cli.Pipeline;

namespace BlazorWebFormsComponents.Cli.Transforms.Markup;  // or .CodeBehind

public class MyNewTransform : IMarkupTransform  // or ICodeBehindTransform
{
    public string Name => "MyNewTransform";
    public int Order => 500;  // Choose based on dependencies

    public string Apply(string content, FileMetadata metadata)
    {
        // Return content unchanged if this transform doesn't apply
        if (!content.Contains("pattern-to-match"))
            return content;

        // Apply transformation
        return content.Replace("old-pattern", "new-pattern");
    }
}