[Preview 4] Razor components renaming

[guardrex]

For Preview 4 RTM

dotnet/aspnetcore#8931

Because sample and code example updates are concurrent with the naming changes, this should be worked the day that Preview 4 releases.

Details:

• Rename the Razor Components template in .NET Core 3.0 back to “Blazor (server-side)”.
• Rename the Blazor template to "Blazor (client-side)" for full clarity.
• Rename services.AddRazorComponents() -> services.AddServerSideBlazor()
• Rename routes.MapComponentHub<TComponent>() -> routes.MapBlazorHub<TComponent>()
• Rename components.server.js back to blazor.server.js and components.webassembly.js back to blazor.webassembly.js.
• Blazor on WebAssembly will no longer be experimental: Remove INCLUDE.
• Get Started: One topic
  • Install SDK + templates
  • Tooling tabs: VS2019+VSIX; VSC+C# extension (New Blazor App Throws Many Problems in VS Code #11971 (comment)); check for other VSC
  • Template choice for desired experience
• All .razor and all components in Pages.
• Host & Deploy: Place the four topics under one node/folder.
• Tutorial: Already a single topic: Clean it up for .razor, Pages folder, and tooling instructions.
• Common sample to P4 bits. REGRESSION REPAIRS
• Remove the Razor Components (Blazor server-side) common sample.
• "Razor components" app model language changed to "Blazor."
• Recombine Overviews into one topic.
• TOC work
• Components in pages+views are interactive.
• Blazor client-side get prerendering support for Preview 5. Update the language to reflect the push back to Pre5 for this scenario.
• Update topic dates.
• Mirror additional updates from the blog post in the docs.
• _Imports.razor
• Spit-'n-polish ... it's the spit that really makes the docs shine. 🌞

Additional Info:

We will still refer to the component model as Razor components (i.e. a .razor file will still be a Razor component), but when talking about the application model we are finding it very cumbersome to have different names.

We're planning to keep the .razor extension for components. Components are based on Razor syntax, but components are handled differently by the Razor compiler, so they need a different file extension.

What about the blazor hosted template? Answer: It stays as is. So there will be three Blazor templates: standalone client-side, ASP.NET Core hosted, and server-side

Convo on this issue resolves to ...

Physical folder layout

• aspnetcore
  • blazor

client-side > spa > blazor 👋 Bye! 👋

TOC

• Web apps
  • Blazor (after MVC)
  • Client-side development (after Blazor)

Client-side Development > SPA > Blazor 👋 Bye! 👋

[guardrex]

@tdykstra and I discussed this over a dozen virtual 🍺 and came up with ...

Physical folder layout

Either ...

• aspnetcore
  • client-side
    • blazor
      • client-side
      • server-side

... or (root-based) ...

• aspnetcore
  • blazor
    • client-side
    • server-side

No consensus reached at this point.

TOC

• Client-side development
  • Blazor
    • Client-side hosting
    • Server-side hosting

Notes

Consensus thus far is that it's best to keep client-side and server-side in the same folder/under the same TOC entry as opposed to splitting Blazor client-side to client-side > spa and Blazor server-side to client-side. Current spit-ball'in yields links like 👍 ...

• aspnet/core/client-side/blazor/client-side/XXXXXXXX
• aspnet/core/client-side/blazor/server-side/XXXXXXXX

... which seems better than 👎 ...

• aspnet/core/client-side/spa/blazor-client-side/XXXXXXXX
• aspnet/core/client-side/blazor-server-side/XXXXXXXX (ugh ... plz NO!)

cc: @danroth27, @scottaddie, @Rick-Anderson, and @wadepickett

[danroth27]

I don't think we want to have a top level fork between server-side and client-side Blazor. Blazor is one app model with multiple hosting models. Most of what you do with Blazor is the same regardless of whether you host client-side or server-side: you write components, add routes, inject services, etc. The only place where client-side vs server-side should come up is when your talking about different hosting. We want one doc TOC for Blazor, not two.

[danroth27]

I would rename the razor-components folder to blazor. The razor components tutorial should become the new Get Started with Blazor tutorial, which shows getting started with the server side model since that's what's shipping first. I think we will then need to add some content to this tutorial that highlights where you need to do something different if you want to run on WebAssembly instead.

[guardrex]

Similar then to what we originally had on blazor.net.

Physical folder layout

Either ...

• aspnetcore
  • client-side
    • blazor

... or (root-based) ...

• aspnetcore
  • blazor

@tdykstra's call on that. My recommendation is that with a client-side folder it seems logical to it to go there, not be root based.

TOC

• Client-side development
  • Blazor

[guardrex]

highlights where you need to do something different if you want to run on WebAssembly instead

Easy if/when ...

• All components go to .razor extension.
• Layout of folders (location of components) is similar across hosting model.

Otherwise, it gets dicey ... e.g. #11953 ... but not necessarily super bad. Just need to be careful.

[tdykstra]

My recommendation is that with a client-side folder it seems logical to it to go there, not be root based.

Sounds good, let's go with that.

[danroth27]

Hold on 😄

Note that we already have an aspnetcore/razor-components folder with all of the relevant Blazor content. It seems logical to rename that folder to blazor. There is also a blazor folder under client-side/spa. Anything important from that folder should be somehow merged into the top level blazor folder.

[guardrex]

Yes ... but it will be a rename and move. "razor-components" is currently at the root of the repo.

[guardrex]

btw - We aren't messing with redirects during preview. (I knew this was going to happen, so I said to the team, "Let's not bother with that until RTM.")

[tdykstra]

It could go either way -- we have MVC and Razor Pages at top level in the folder structure but under Web apps in the ToC, so Blazor could go top level in the folder structure and under client side in the ToC

[guardrex]

🤔 ... root permits locations to carry "server-side" better.

/aspnet/core/blazor/something-with-server-side-in-folder-name

... is better than ...

/aspnet/core/client-side/blazor/something-with-server-side-in-folder-name

[guardrex]

@tdykstra Per offline chat with @danroth27 ... latest i-dears:

TOC

Place the Blazor node directly under Web Apps (not under Client-side Development). Client-side Development > SPA > Blazor is going 👋 adios 👋. Place the Client-side Development node directly under Web Apps (i.e., it won't be on the root of the TOC).

Physical

Leave the blazor folder under the root (as planned; just renaming razor-components to blazor). Leave the client-side folder under root (as exists today).

If you and DR proceed with the TOC updates, let me know if you want me to take care of both. I'll get the Blazor stuff; do you want me to also take care of the Client-side update at the same time if that turns out to be the direction? [Noting that there are no physical folder shifts for Client-side; therefore, no redirects required ... just TOC updates.]

Next, I'm going to update the opening post of this issue with the latest. It will include the other details on the topic work for Blazor P4.

[tdykstra]

• Blazor node directly under Web Apps
• Client-side Development node directly under Web Apps
• Leave the blazor folder under the root
• Leave the client-side folder under root

These all make sense to me, as does including them in your PR. Web apps node will have a long list, we'll have to give some thought to the right order.

[guardrex]

@tdykstra When you determine the order, I recommending updating the OP on this issue. I intend to work from the OP when the time comes, so I've been keeping it updated with latest guidance.

[tdykstra]

OP?

[guardrex]

original post ...... aka first comment

Where did I get that from? ... AOL??!! 🙈

[tdykstra]

Ok I added placement suggestions in the main comment box.