Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
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.
@Andrzej-W

This comment has been minimized.

Copy link

commented Mar 27, 2019

@SteveSandersonMS it was great explanation. Now everything is crystal clear. So far I was thinking that sequence numbers have to be consecutive. Thank you very much for your time and effort.

@Lupusa87

This comment has been minimized.

Copy link

commented Mar 28, 2019

Thank you, it is much clear now.

I can't stop using buildrendertree because I found it very convenient and powerful, so all I will do now is hard coding current line numbers in buildrendertree methods after finish to write component code.

It is sad to know that this procedure should be done again after any changes in code because line numbers will be changed, but not big tragedy before better times :)

OpenRegion/CloseRegion is good advise, it can be used in injected methods which itself have not any loops or conditionals, so numbering once will be enough and not requires line numbers anymore, thank you.

This was helpful but there are some component related bugs and missing features I am going to raise issues for.

Hope this gist will be used in docs and my main concern not to cover buildrendertree with razor will be considered in future.

@honkmother

This comment has been minimized.

Copy link

commented Mar 29, 2019

An almost irrelevant thought: Can C#8.x (in the future) provide us some kind of keyword that gives us access to the scope's local line number? This could be useful for a number of other use case scenarios. Something similar has to already exist for exceptions, right?

@EdCharbeneau

This comment has been minimized.

Copy link

commented Mar 29, 2019

@SteveSandersonMS I think some from of this post, a less detailed version, needs to make its way into the Blazing Pizza workshop docs. You covered this in person at NDC London but it's not written anywhere, so it's a bit of tribal knowledge at this point.

@SQL-MisterMagoo

This comment has been minimized.

Copy link

commented Mar 30, 2019

It seems like OpenRegion and CloseRegion were made internal in February last year

@shawty

This comment has been minimized.

Copy link

commented Apr 4, 2019

Forgive me for being stupid here, but let's suppose I want to for example, generate a menu component from a database list, or an XML or something, I might very well do something like:

foreach(var item in allItems)
{
  builder.OpenElement(xx, "a");
  builder.AddAttribute(xx, "href");
  builder.AddContent(xx, item.url");
  builder.CloseElement(xx, "a");
}

( Yes I know the syntax is wrong... I'm just trying to illustrate a point :-D )

Anyway, back to the above, in this case I have little choice but to auto generate the id's, because I don't know ahead of time how many tags I might be adding?

I bring this up, because an experiment I'm working with, actually does this. Depending on the logged in user and the "roles" they have available, the menu is drawn differently. Currently I do have it implemented in a razor page, and to be fair that actually works well, but if I'd wanted to do the menu in the manner above what would be the advice?

My thoughts would be hard code the static stuff, and autogen only the loop portions, would that be correct?

@Lupusa87

This comment has been minimized.

Copy link

commented May 7, 2019

You can just enter line number as sequence number parameter. Or numerate by yourself. If/loop does not matter, just numbers should increase in following LOCs from up to down.
Here is important that particular builder line of code always got same sequence number not depended on state changes.

@arivoir

This comment has been minimized.

Copy link

commented May 24, 2019

I have some doubt about the level of detail Blazor is able to reach to minimize the impact of the diff algorithm.

aspnet/AspNetCore.Docs#12504 (comment)

Specially in virtualizing components it would be desired to be able to preserve the elements that didn't change. I firstly thought it was related to the sequence number, but then I understood I was wrong. All the elements in a cycle must have the same number. So I'm wondering if there is any way to achieve more granularity in the elements so Blazor can identify every element thoroughly and avoid unwanted dom changes.

@guardrex

This comment has been minimized.

Copy link

commented May 26, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.