Improvements to the Blazor website

[marinasundstrom]

Is there an existing issue for this?

• [X] I have searched the existing issues

Is your feature request related to a problem? Please describe the problem.

The Blazor website is not clearly showing what Blazor is. There is just a bunch of text which alone wouldn't appeal to developers considering checking out Blazor.

So my impression of the website is:

"We have this shiny thing that we want you to use, but we are not showing it to you. You have to click here to see it."

In a sense, it doesn't seem to be aimed a developers, but people making decisions based on sales pitches alone.

Consider making the site more community-friendly.

Describe the solution you'd like

The site should demonstrate Blazor to the developers. Giving them a sneak peek and feel of the syntax and framework. As well as bringing up the relevant resources to get started.

I really enjoyed when there at least was some piece of code showing a simple Blazor component.

Developers should get the minimal information required to make a decision to try it out.

The site should also highlight the most common component libraries - both free and commercial options: MudBlazor, Fluent UI etc. Synchfusion etc.

Additional context

No response

[guardrex]

Cross-references for the current round of updates to the Blazor overview article:

• Issue: https://github.com/dotnet/AspNetCore.Docs/issues/30285
• PR: https://github.com/dotnet/AspNetCore.Docs/pull/30353

[marinasundstrom]

@guardrex How do you handle the distinction between Razor Components vs Razor Views and Razor View Components?

I think that is source for potential confusion both for beginners and developer with experience of the latter.

I have seen developers using Razor View helpers in Razor component files - when coming from Blazor Server.

Anyway, I think that Blazor/Razor Components should be presented as a clean slate for Razor.

[guardrex]

The Blazor docs don't directly remark much on it, but additional content can be added ... I'm thinking specifically about the Razor syntax section of the Components overview article.

The main Blazor overview states ...

Blazor Server apps render content differently than traditional models for rendering UI in ASP.NET Core apps using Razor views or Razor Pages. Both models use the Razor language to describe HTML content for rendering, but they significantly differ in how markup is rendered.

The Components overview article states that Razor components use Razor syntax with a cross-link to the main doc set's Razor syntax article at ...

https://learn.microsoft.com/aspnet/core/mvc/views/razor

"Razor view" is only used in one sentence in the Razor syntax article, pertaining to MVC (Razor) views (the engine that compiles them).

The only other mention is just a passing remark in the Layouts article that the _Imports.razor file is similar to the _ViewImports.cshtml file of an MVC/RP app.

AFAIK, "Razor view component" isn't a thing in the framework. We don't document the existence of any such beast.

I've opened an issue to work on this, but it will take a little while to reach it given the high priority work going on for .NET 8.

[guardrex]

I think that Blazor/Razor Components should be presented as a clean slate for Razor.

Not sure what you mean by that ... explain further.

[marinasundstrom]

@guardrex I meant that when a beginner comes to Blazor they should not have to worry about the other stuff (MVC Razor, Pages) - unless actually necessary.

I will respond to the other comment later.

[marinasundstrom]

@guardrex View components are a thing: https://learn.microsoft.com/en-us/aspnet/core/mvc/views/view-components?view=aspnetcore-7.0

[guardrex]

They don't if they're following the Blazor guidance. Anything in Blazor Server apps pertaining to pages/views are clearly called out along the way, and the content is fairly minimal.

Oh, yeah ... you said "Razor view component" which didn't trigger anything in my head! :smile: I've been up since 3:30am working, and it's noon here. My 🧠 is fried on Blazor + EF Core! 😵 I'll add that to my issue so that I don't forget.

[marinasundstrom]

@guardrex OK. That's early! It's about 6:20 pm here. Didn't wake up that early though. 🙂

[guardrex]

I didn't mean to, but I had a nightmare ... which is extremely rare for me ... like once a year. So, I woke up ... kind'a wide awake at that point ... then I knew that I was going to fix up our Blazor + EF Core article for 8.0+ and make a new Blazor Web App sample app today. That's what I scheduled to work on. I decided to just go for it. That's all done now, so it's been a good day. I'm happy with the outcome ... but yeah ... I'm TOAST. I need a nap 🛌💤😆.

"Razor" is widely used now because the syntax is so critical across these app types, and I agree that we should have more clarity going in with Razor components that the other Razor-y Things™ aren't directly related and mostly aren't used, just in cases where a page or view in a server app plays a role. I think a new section might be the best way to accomplish that right under the existing Razor syntax section. That should make it all super-clear. I'll probably reach it around the 🎁 holidays ⛄, after .NET 8 releases.

[marinasundstrom]

@guardrex Doesn't happen me either as much as it used to. Nightmares that make you doubt what is reality or not are the worse, even when you wake up. It's always good to find something to focus on while processing it. Trying to make it a source for creativity.

Yeah, there are so many technologies that use Razor. I guess there are commonalities in the templating language and engine, such as basic directives, but there are stuff that map to different things - but in the end, it is all about producing some C#. That is when whatever framework, MVC or Blazor, handles that bit.

I'm looking at the Razor syntax reference, and I wonder if it's a good idea to mix constructs that are specific to different technologies.

[guardrex]

When everyone started using the name "Blazor components" instead of the formal name "Razor components," there was a discussion about dropping the "Razor component" naming, but it was decided by management that we needed to stick with "Razor components." Now, "Blazor components" is an unofficial name ... and not used in the documentation. You'll find it all over the Net. IIRC, at least part of the reason that they can't be called "Blazor components" officially is that they aren't just for Blazor (i.e., the Blazor framework). They also work in MVC and RP apps. "Razor components" is general enough to cover that. I don't recall if there were other reasons. That discussion/determination took place years ago.

[guardrex]

When I added the Razor syntax directive attributes and element attributes to the Razor syntax doc, I added lines on which ones are specifically for Razor components. I used this line ...

This scenario only applies to Razor components (.razor).

I know that management didn't want a separate Razor syntax article just for Blazor. There would be a large amount of duplication with what's there because I think most of it applies.

[marinasundstrom]

I remember that someone decided that they wanted to drop the name "Blazor" - which they had to reverse, obviously. I do understand that they wanted brand uniformity. But Blazor had become a known brand by itself. If it wasn't for the other Razor stuff, I would go for it. But why confuse people? Already having, in particular, Razor View components. And the argument now would probably be that Razor components should be the name since it is now even more integrated into ASP.NET Core.

I call them "Razor components" interchangeably with "Blazor components".

It if wasn't for the name "Blazor", it wouldn't have got that much exposure, and fewer people would have cared about it today.

[guardrex]

I hear you.

Just as a side-note on that naming, "Razor view components" (and that at least partially explains why my zoned out 🧠 didn't catch what it was), we don't call them that. It's just "View components" everywhere AFAIK. I don't think it's in our documentation as "Razor view components." Folks on the Net might be calling them that ... talks, blogs, etc.

[marinasundstrom]

Sure. I honestly don't know what they are called out there - probably just "View components". But the issue that someone had was that they tried to render .razor file with the Component "Razor" View helper class, from a .cshtmlpage.

On the other comment:

I think it is a matter of who they expect to read the docs. Is it a developer working for a paying company, someone who is driven by docs, or the broader community of enthusiasts who want to get started quickly? I think it reflects in both docs and the Blazor homepage.

[marinasundstrom]

It's a matter of striking the balance, I think.

[guardrex]

render .razor file with the Component "Razor" View helper class, from a .cshtmlpage.

They must use a Component Tag Helper. We explain it out in this article ...

https://learn.microsoft.com/aspnet/core/blazor/components/prerendering-and-integration?view=aspnetcore-7.0&pivots=server

... but that article is a little bit too complicated trying to cover both at once. It deals with both Razor component prerendering and integration of Razor components into non-Blazor apps, namely MVC and RP. I think we're going to split that into two articles, one just on prerendering ... the other on integrating components. That should happen by 8.0 RTM, but it also might not apply to <8.0. We might version that current topic (unchanged) for <8.0 and create two new topics for >=8.0. We'll see when I get there! 🏃😅

The TH itself is covered with the rest of them in the main doc set here ...

https://learn.microsoft.com/aspnet/core/mvc/views/tag-helpers/built-in/component-tag-helper?view=aspnetcore-7.0

[marinasundstrom]

@guardrex I was refering to #50762 about rendering components in Blazor views using the component tag helper.

There is the added confusion of how to enable interactive components in Minimal API endpoints that return RazorComponentResult. That you have to embed it in an SSR page, whether Razor View or Component.

Then there is no way of exposing the blazor.web.js script without mapping components using the MapRazorComponents<T> extension method.

In my effort to explorer this, I wrote my own extension to map those static files separately.

https://github.com/marinasundstrom/BlazorMvcViewTest/blob/main/BlazorWebJSExtensions.cs

[guardrex]

I don't know. The product unit will need to address that scenario on #50762.

[danroth27]

@mairaw @claudiaregio Feedback on the Blazor landing page from the community.

[mairaw]

And just to confirm: @marinasundstrom's feedback was for https://dotnet.microsoft.com/en-us/apps/aspnet/web-apps/blazor and not docs, correct? Because I see the comments dovetail into a discussion of docs improvements and components, which are not related to the landing page.

[marinasundstrom]

@mairaw Yes. https://dotnet.microsoft.com/en-us/apps/aspnet/web-apps/blazor

Sorry, for the confusion. 🙂

[mairaw]

No worries. Thank you for confirming.