Skip to content

Instantly share code, notes, and snippets.

@SteveSandersonMS
Last active November 28, 2023 20:28
  • Star 28 You must be signed in to star a gist
  • Fork 1 You must be signed in to fork a gist
Star You must be signed in to star a gist
Save SteveSandersonMS/ec232992c2446ab9a0059dd0fbc5d0c3 to your computer and use it in GitHub Desktop.
Why sequence numbers should relate to code line numbers, not execution order

Why sequence numbers should relate to code line numbers, not execution order

Or in other words, why you should hard-code sequence numbers, and not generate them programmatically.

Unlike .jsx files, .razor/.cshtml files are always compiled. This is potentially a great advantage for .razor, because we can use the compile step to inject information that makes things better or faster at runtime.

A key example of this are sequence numbers. These indicate to the runtime which outputs came from which distinct and ordered lines of code. The runtime uses this information to generate efficient tree diffs in linear time, which is far faster than is normally possible for a general tree diff algorithm.

Example

Consider the following simple .razor file:

@if (someFlag)
{
    <text>First</text>
}
Second

This compiles to something like the following:

if (someFlag)
{
    builder.AddContent(0, "First");
}
builder.AddContent(1, "Second");

When this executes for the first time, if someFlag == true, the builder receives:

Sequence Type Data
0 Text node First
1 Text node Second

Now imagine that someFlag becomes false, and we render again. This time the builder receives:

Sequence Type Data
1 Text node Second

When it performs a diff, it sees that the item at sequence 0 was removed, so it generates the following trivial edit script:

  • Remove the first text node

What goes wrong if you generate sequence numbers programmatically

Imagine instead that you wrote the following rendertree builder logic:

var seq = 0;

if (someFlag)
{
    builder.AddContent(seq++, "First");
}
builder.AddContent(seq++, "Second");

Now the first output would be:

Sequence Type Data
0 Text node First
1 Text node Second

... in other words, identical to before, so no issues yet. But then on the second render when someFlag==false, the output would be:

Sequence Type Data
0 Text node Second

This time, the diff algorithm will see that two changes have occurred, and will generate the following edit script:

  • Change the value of the first text node to Second
  • Remove the second text node

Generating the sequence numbers has lost all the useful information about where the if/else branches and loops were present in the original code, and has resulted in a diff that is now twice as long.

This is a very trivial example. In more realistic cases with complex and deeply nested structures, and especially with loops, the performance cost is more severe still. Instead of immediately identifying which loop blocks or branches have been inserted/removed, the diff algorithm would have to recurse deeply into your trees and would build far longer edit scripts, because you're misleading it about how the old and new structures relate to each other.

Questions

  • Q: Despite this, I still want to generate the sequence numbers dynamically. Can I?
    • A: You can, but it will make your app performance worse.
  • Q: Couldn't the framework make up its own sequence numbers automatically at runtime?
    • A: No. The necessary information doesn't exist unless it is captured at compile time. Please see the example above.
  • Q: I find it impractical to hard-code sequence numbers in really long blocks of manually-implemented RenderTreeBuilder logic. What should I do?
    • A: Don't write really long blocks of manually-implemented RenderTreeBuilder logic. Preferably use .razor files and let the compiler deal with this for you, or if you can't, split up your code into smaller pieces wrapped in OpenRegion/CloseRegion calls. Each region has its own separate space of sequence numbers, so you can restart from zero (or any other arbitrary number) inside each region if you want.
  • Q: OK, so I'm going to hardcode the sequence numbers. What actual numeric values should I use?
    • A: The diffing algorithm only cares that they should be an increasing sequence. It doesn't matter what initial value they start from, or whether there are gaps. One legitimate option would be to use the code line number as the sequence number. Or start from zero and increase by ones or hundreds or whatever interval you like.
  • Q: Why does Razor Components use sequence numbers, when other tree-diffing UI frameworks don't?
    • A: Because it makes diffing far faster, and Razor Components has the advantage of a compile step that deals with this automatically for people authoring .razor/.cshtml files.
@gingters
Copy link

You're welcome! I struggled a bit with that myself. I used ILSpy to look into what output of certain loops / conditions etc. generated from my Blazor components (the Razor syntax is compiled into a render tree builder, so you can see what C# code your Razor code is converted to) and learned from that how the sequence number is generated. It's a lot less magical once you see that ;)

@gyuzal
Copy link

gyuzal commented Apr 20, 2022

that's amazing @gingters
i'm sorry to be off the current topic but is there a way to get event object in the event handler when using RenderTreeBuilder?
Here's a piece of code where I try to apply StopPropagation() on the element click:

builder.AddAttribute(i++, "onclick", EventCallback.Factory.Create<MouseEventArgs>(this, OnClick));

private void OnClick(MouseEventArgs args)
{
   //e.StopPropagation() how do I get event here?      
}

@wstaelens
Copy link

regarding the loops, if I understand correctly the sequence should be the same in loops.

Instead of this:

 public RenderFragment Build()
    {
      return new RenderFragment(builder =>
      {
        var i = 0;
        builder.OpenComponent(i++, ComponentType);
        if (Attributes != null)
        {
          foreach (var kvp in Attributes)
          {
            builder.AddAttribute(i++, kvp.Key, kvp.Value);
          }
        }
        builder.CloseComponent();
      });
    }

it should be:

        public RenderFragment Build()
        {
            return new RenderFragment(builder =>
            {
                builder.OpenComponent(10, ComponentType);
                if (Attributes != null)
                {
                    foreach (var kvp in Attributes)
                    {
                        builder.AddAttribute(20, kvp.Key, kvp.Value);
                    }
                }
                builder.CloseComponent();
            });
        }

correct ?

@SteveSandersonMS
Copy link
Author

@wstaelens Correct!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment