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.
Consider the following simple .razor file:
@if (someFlag)
{
<text>First</text>
}
SecondThis 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
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.
- 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
.razorfiles and let the compiler deal with this for you, or if you can't, split up your code into smaller pieces wrapped inOpenRegion/CloseRegioncalls. 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.
- A: Don't write really long blocks of manually-implemented RenderTreeBuilder logic. Preferably use
- 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/.cshtmlfiles.
- 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
@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.