Manual RenderTree snippets are incomplete

[ShawnDigital]

Unless I'm missing something the manual render example snippets are wrong/incomplete. @CustomRender is set by CreateComponent() in the method RenderComponent(), but nothing calls RenderComponent(). While prototyping Blazor I assumed this was a derived a method or convention like ChildContent but after a good bit of debugging blank screens realized nothing calls it.

Also, some explanation of the mechanism and lifecycle there would be nice for understanding it. A lambda/method is used to populate a RenderFragment Property which is then referenced in the razor/template sections. Altering things even slightly (e.g. referencing the lambda method directly, moving the population of the property, etc...) usually resulted in blank screen and only through (a lot of) trial and error could I get a successful render.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: be4c4d0c-149c-bde1-c7fa-f082916390ca
• Version Independent ID: 9d945996-ad02-bd4b-58ea-c465cc5cc74c
• Content: Create and use ASP.NET Core Razor components
• Content Source: aspnetcore/blazor/components.md
• Product: aspnet-core
• Technology: aspnetcore-blazor
• GitHub Login: @guardrex
• Microsoft Alias: riande

[ShawnDigital]

After cutting and pasting as is to visual studio while looking at the ComponentBase source I found the caller but it would be nice if it showed a more realistic example that isn't triggered by a user click as its been tricky to get it setup correctly with the page lifecycle.

[ShawnDigital]

Hi thanks for the interest and response. As I mentioned I did find where it was calling the method, I originally copied most of the code into an existing project with its own UI so totally missed the click event and somehow didn't notice it when troubleshooting. Things are a bit clearer after looking through the source and spending more time with it, the RenderFragment delegate versus RenderFragment or simply returning a RenderFragment caused some confusion when comparing various examples (not all of them were in this doco). I'm still trying to figure out the lifecycle or at least how it fits into our use case. I've gotten examples to work then tried to enhance it and broken things accidentally several times so learning through trial and error, which considering that things are still in flux, may be of questionable value at the moment.

Our system is an edge case I'm sure similar to use cases of UI control providers. We dynamically render views provided from a service. These views/forms are created and managed by departments or managers for their workflows and at times may even be customized for a single user. This component model is shared across many platforms and if modified should automatically update when the view is navigated to again or refreshed depending on platform. I have a prototype to demo about 90% of the way there but keep breaking the rendering and spend half a day or so getting it working again (which isn't abnormal while experimenting), but wish the doco had a little more info in this area. I am hoping when schedules normalize next week after the new year I can find time to really dig through the source more.

[ShawnDigital]

I think the most confusing things for me are:

1. sequence (of course) which is incorrectly explained all over including places like visual studio magazine online articles. As I understand the requirements, the value isn't important so much as they are a sequence of integrals that progress, are unique, and persist so can be used for differencing performance. Hard coding line numbers is often mentioned as a good solution but raises questions like unique within what scope since you have looping, splatting, templates etc... so how do they affect or are affected by this? Unique within what scope and timeframe e.g. do they need to persist across posts or complete page reloads or only to facilitate local routes short circuited by the router?
2. component lifecycle and rendering cycle. It wasn't clear until reading the source that most examples are referencing a property with a RenderFragment named delegate not a property of type RenderFragment. A full example versus snippets and text would help too, but attempts with "similar looking" architectures that got contents from methods or base/helper classes or used razor templates etc... often produced unexpected results causing more confusion as errors can be vague or more commonly simply nothing is rendered and since tooling isn't fleshed out in VS it can be hard to tell whats going with no errors for the browser tools and the elements simply don't exist which makes the docs extra valuable for understanding versus trial and error.
3. templating i.e. trying to use RenderFragment and razor templates combined with manual rendering has been difficult. Understanding the behavior based on testing alone has mixed results and rendering content that may be one thing (panel) which may recursively render its own contents or a collection of items (list) where using a razor template makes sense has been mostly trial and error resulting in solutions that feel clunky or like hacks and rely on internal functionality which is more likely to change and possibly invalidating any prototyping I do which makes documentation and best practices even more beneficial.

Its early days and a WIP so completely understandable, but blazor opens up web to existing .net code reuse so many ui control vendors and framework providers with advanced use cases will be very interested in and early adopters of this tech. I'd be happy to help/contribute, but I definitely don't feel like I understand anything well enough help document it yet lol.

Edit: Also Open/CloseRegion recommended then made internal then said it is or would be made not internal? Kind of relates to #2 but this topic specifically seems all over the map over time as things evolve.

[guardrex]

@ShawnDigital ... I'm back! ... it was a nice, restful break. Hope you had the same.

Ok ... so your feedback should be addressed by management, so I'm going to mark this for triage on the Blazor.Docs project. They'll come in at some point ... a few weeks probably ... and provide a response. Give them a few weeks because we're all just getting back from the extended holiday break. ⛄️ Everyone is digging out from a piles of email and issues! ⛏

A few notes to your points by numbered comment ...

1. I defer to engineering on content pertaining to sequence (e.g., Sequence numbers relate to code line numbers and not execution order). Standby for their response to your remarks.

2. RenderFragment

   referencing a property with a RenderFragment named delegate not a property of type RenderFragment

   I've been holding off on cross-linking to API docs in the Blazor docs. This made your research more difficult. When I get to Add Blazor API links #10931, I'll cross-link RenderFragment to RenderFragment ... and a few hundred other API mentions that need to be cross-linked. I apologize for this situation, and I plan to make a 👹 monster pass 👹 on the Blazor docs to get those cross-links in there. The problem was mostly 🕐 TIME ... high priority issues to address and the cost 💰 of the very-manual process of cross-linking. Also, Blazor WebAssembly hasn't released yet, and I favor one giant cross-linking pass after Blazor WebAssembly reaches GA. It's a 💲 cost savings 💲 to Microsoft to embrace this approach.

3. Absolutely, I hear you. I defer to Dan to react and let us know what we can do, if anything. In general, we focus on the most common scenarios. IMO, one of the most frequent feedback comments is, 'you don't cover enough advanced scenarios.'

Its early days and a WIP so completely understandable

Thank you for that! We're aware and working hard to cover Blazor scenarios most beneficial to developers.

I'd be happy to help/contribute, but I definitely don't feel like I understand anything well enough help document it yet

I'll work with you on that. Please feel free to open doc issues for any new topic idea, new sections to existing topics, or just feedback. If you're concerned about the framework itself (the source code), open with engineering. For an existing doc, use the This page feedback button+form at the bottom of the topic, which will automatically ping me. For a new doc opened directly on the repo, ping me in your opening comment ... I'll add the appropriate labels and set it up for triage on the Blazor.Docs project.

Open/CloseRegion recommended then made internal then said it is or would be made not internal

Just due to framework churn ... it's public now, and it will stay that way.

[guardrex]

OH! ... and btw --- totally off topic, but we were just there for a visit. No crazy crowds in the French Quarter. We had a great time. Some of our family who were on the trip were born and raised there, so it was a family history trip, too. It was great. I encourage others to visit New Orleans and enjoy the culture, food, and music! Landry's was highlight of the trip ... ❤️ it 🍤.

[ShawnDigital]

Generally we try to stay away from the quarter around holidays/mardi gras, but my wife and I decided to get away (from family and obligations) and had a little staycation in the quarter the week of new years to celebrate our 10 yr anniversary so were probably in the area. Glad you had a good time. There's a certain character here that makes it hard to live in places after you stay here a while although the hot months like Aug/Sept may make you seriously consider it. :)