[2.0] Migration tool

[stsrki]

There will be a lot of breaking changes in 2.0. And, I am thinking of how to make it easy for our users to migrate. One idea is to create a CLI tool that the users can install and the run on their project to automate the migration. We will need to parse razor code and replace any parameter on component that could be renamed.

Example

Rule 1 - two way binding

<TextEdit @bind-Text="@value" />

<TextEdit @bind-Value="@value" />

---

Rule 2 - one way binding

<TextEdit Text="@value" />

<TextEdit Value="@value" />

---

Rule 3 - manual two way binding

<TextEdit Text="@value" TextChanged="@((v)=>value=v)" />

<TextEdit Value="@value" ValueChanged="@((v)=>value=v)" />

---

Rule 4 - no closing tag

<TextEdit Text="@value">
  Some content
</TextEdit/>

<TextEdit Value="@value">
  Some content
</TextEdit/>

---

Rule 5 - expressions

<TextEdit Text="@value" TextChanged="@((v)=>value=v)" TextExpression="@(()=>value)" />

<TextEdit Value="@value" ValueChanged="@((v)=>value=v)" ValueExpression="@(()=>value)" />

Rule 6 - Collapse in Accordion replaced by Accordion "inner" components

<Collapse>
    <CollapseHeader Padding="Padding.Is1.OnY">
        <Heading Size="HeadingSize.Is5" TextAlignment="TextAlignment.Start">
            <AccordionToggle>Some text</AccordionToggle>
        </Heading>
    </CollapseHeader>
    <CollapseBody TextAlignment="TextAlignment.Start">
        Some body
    </CollapseBody>
</Collapse>

<AccordionItem>
    <AccordionHeader Padding="Padding.Is1.OnY">
        <Heading Size="HeadingSize.Is5" TextAlignment="TextAlignment.Start">
            <AccordionToggle>Some text</AccordionToggle>
        </Heading>
    </AccordionHeader>
    <AccordionBody TextAlignment="TextAlignment.Start">
        Some body
    </AccordionBody>
</AccordionItem>

[tesar-tech]

I spent some time thinking about this, and with more features implemented for 2.0.

We want to create a tool that will actually help developers with migration.

I don't think we should approach this by parsing the Razor file. There are so many things that can go wrong. Maybe it would work for a simple Razor file that just renames a parameter, but the rest is not so straightforward—it’s becoming clearer with all the updates we are bringing to 2.0.

Not all migration steps can be decided by us. For example, the NavigationAllowed in the Steps component now returns a Task, and the Next and Previous are changed as well - developer will need to step into the process anyway.

What I am suggesting is this:

• Create a "Migration Assistant Tool"—a CLI tool that scans through the code and outputs the points that need attention.
• It can output results as a file (PDF, TXT, HTML), inside the console environment, or as a Blazor web app running on localhost.
• The tool should only advise, not edit code. For example: "Here in file SomePage.razor on line 33, there is an issue you need to solve after the upgrade."
• Use source generators.

What do you think?

[stsrki]

I like the Migration Assistant idea. But in the end, it is not different from building an app and seeing all the errors and warnings. It might be more details true. But is it going to be that much of a different to an end user?

I am aware that the migration tool would not be perfect. If we could make it 50% good, even that would make it easy for our users to migrate.

We need to focus primarily on razor syntax because that is how the majority of users write their Blazor(ise) code. In case there is a code-behind component reference, they can quickly fix it. In situations like NavigationAllowed to Task, I believe it will not impact many users, so as long as it is documented properly, they can easily fix it.

[stsrki]

PS. Even we brake the code somehow, they will try it, build it, and it will fail. Anx, they can easily undo changes with git.

[tesar-tech]

Ok, so what about combining the best of both worlds within the familiar UI of a programmer's IDE?

I’m talking about custom analyzers (e.g., Blazorise.MigrationAnalyzers) installable via a NuGet package.

A good example of such an approach is Meziantou.Analyzer. While not used for migration, it simplifies working with Blazor.

Advantages:

• No need to reinvent the wheel: Leverages existing Razor parsers.
• Familiar developer environment: Warnings and errors appear in the Errors or Problems window of the IDE.
• No additional CLI development required: Eliminates the time spent creating and maintaining a CLI tool.
• Customizable code fixes: Developers can choose when and how to apply fixes:
  • Only apply code fixes when they make sense.
  • Optionally perform fixes globally if desired.
• Supports non-standard use cases: Handles cases, like defining components outside Razor files.

[stsrki]

Can this analyzer change the user's code, or is it just for displaying errors and warnings?

[tesar-tech]

Can this analyzer change the user's code, or is it just for displaying errors and warnings?

yes it can, these are called Fixes. It is basically what you are already using within an IDE, like adding cost keyword, etc...

[stsrki]

And does it work with razor code? If yes, it might be a good approach.

[tesar-tech]

And does it work with Razor code? If yes, it might be a good approach.

It analyzes the generated files but can propagate warnings back to the Razor files, as seen here. (This behavior seems to be somewhat IDE-dependent, though.)

I’m not entirely sure how this would work for Razor components usage - e.g. when renaming parameters—but I assume it should be possible. For instance, the [EditorRequired] attribute can raise warnings on component usage and even provide a fix.

I’ll start by checking the possibilities for renaming parameters.

[stsrki]

I’ll start by checking the possibilities for renaming parameters.

Please do, and see how it goes.

---

PS. I've stumbled on this tool for refactoring APIs https://martinfowler.com/articles/codemods-api-refactoring.html. If something like this is possible with Blazor it would be great.