Aspnetcore.docs: Improve coverage on special purpose Blazor files+components

[guardrex]

Per feedback from @tdykstra ...

• _Host.cshtml
• _Imports.razor
• App.razor
• NavMenu component [include remarks on Bootstrap use and the toggle button code (responsive design)]

We should improve coverage on first mention. The docs do speak to these on a here's where you do this or that basis, but the files aren't defined explicitly/clearly enough.

:question: Should these be briefly described in the build-your-first experience?

---

Document Details

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

• ID: 36e7dc3c-54c4-35de-203e-d230869e8417
• Version Independent ID: dc5b52d5-c8c6-1440-6b3a-fda898167d0c
• Content: Build your first Blazor app
• Content Source: aspnetcore/tutorials/build-your-first-blazor-app.md
• Product: aspnet-core
• Technology: aspnetcore-tutorials
• GitHub Login: @guardrex
• Microsoft Alias: riande

[tdykstra]

Should these be briefly described in the build-your-first experience?

@guardrex I vote yes. My goal as the user of a build-your-first-app tutorial is that I would come away from it knowing:

1. How to handle typical/basic tasks for building my own app
2. Where to find documentation on how to do such basic/typical tasks that aren't covered explicitly in the tutorial.

So based on my own experience trying to build an app after going through this tutorial, I'd like to see either in the tutorial itself or in Additional resources links:

• The files you list in this issue description.

• How to add Razor components that include SignalR server-side Blazor functionality to an existing Razor Pages project. Or a note saying it can't be done / what can be done, for example:

  • A Blazor server-side app can't be maintained within an RP/MVC app at this time.
  • In an existing RP/MVC project, components can only be placed into pages/views.
  • A Blazor client-side app can be hosted as a sub-app from within an RP/MVC app. (if so, how?)

• How to do multiple-level (drop-down/fly-out) menus. Any realistic app would need that, and it may be that a link to bootstrap nav docs would help here, but the template has a lot of nav customization that complicates matters. Earlier RP/MVC templates made this easy to do.

[surfmuggle]

I struggled with step 4 add "Todo.razor" to the solution. After my fix-attempt it worked but syntax highlighting is incomplete: see https://stackoverflow.com/questions/57699508/visual-studio-2019-preview-razor-page-syntax-highlighting-for-code-block-missi

[guardrex]

@surfmuggle Those should be point-in-time problems with the IDE. 🤞 If we get to 3.0 RTM at year's end and you see those types of things happening with the latest VS (whatever version is out at year's end for 3.0), then use the feedback system built into VS to report it ... it opens an issue directly for the VS team.

[surfmuggle]

Closing VS helped - syntax highlighting is now working in Todo.razor.
What is the recommended way to add a "foo.razor" file to a project?

[guardrex]

Eventually, there will be a gesture inside of VS to do it. For now, I add a Razor View and change the extension. A Razor View won't create a code-behind file the way that a Razor Page will, so it's a little faster. A Razor View will have a Build Action of Content.

[surfmuggle]

@guardrex Thanks will try that.

[guardrex]

| Item/File | Covered at ... |
| --- | --- |
| _Host.cshtml | https://docs.microsoft.com/en-us/aspnet/core/blazor/routing?view=aspnetcore-3.0#aspnet-core-endpoint-routing-integration |
| _Imports.razor | https://docs.microsoft.com/en-us/aspnet/core/blazor/layouts?view=aspnetcore-3.0#centralized-layout-selection |
| App.razor | https://docs.microsoft.com/en-us/aspnet/core/blazor/routing?view=aspnetcore-3.0#route-templates |
| NavMenu | There's nothing really super special about NavMenu, per se. It's just a component in template-based Blazor apps provided as a convenience. NavLink is a thing ... a framework-supplied component ... and covered at: https://docs.microsoft.com/en-us/aspnet/core/blazor/routing?view=aspnetcore-3.0#navlink-component |

Since we have the coverage, I think we just want to state briefly (without cross-links) what these files are in the tutorial. I'm going to go ahead and schedule this one for work.

The tutorial is due for replacement. I'll add the content in a section so that it can be moved easily into the new topic.

[guardrex]

What if instead we created a new topic called "Project structure" that walks you through the files in a default Blazor project and explains how they all fit together? Something like this (but with a @guardrex touch): https://github.com/danroth27/IntroToBlazorWorkshop/blob/master/docs/02-project-structure.md

WRT _Host.cshtml ...

This is actually the root Razor page, where the App component is rendered.
DR do you like this phrasing, or should it rather be "the root Razor page, where the components are rendered"?

Blazor apps use the following special files and components:

* [\_Host.cshtml](xref:blazor/routing#aspnet-core-endpoint-routing-integration) – A Razor page where the app's components are rendered.
* [\_Imports.razor](xref:blazor/layouts#centralized-layout-selection) – Imports namespaces for Razor components.
* [App.razor](xref:blazor/routing#route-templates) – Maintains the `Router` component, which enables routing to the app's components. The `App` component is the root Razor component in the app and hosts the rest of the app's components.
* [NavLink component](xref:blazor/routing#navlink-component) – A framework-provided component that renders navigational links to other Razor components. The `NavLink` component automatically indicates a selected state when its component is loaded, which helps the user understand which component is currently displayed.

[guardrex]

@danroth27 Where in the TOC would you like the upcoming topic? The current lineup is ...

• Overview
• Supported platforms
• Get started
• Hosting models
• Build your first app
• Components
• Forms and validation
• Component libraries
• Layouts
• Dependency injection
• Routing
• JavaScript interop
• Security and Identity
• State management
• Handle errors
• Debug
• Call a web API
• Host and deploy
• Samples

I'll toss out a bunch of possible titles along your structure concept ...

• ASP.NET Core Blazor project structure
• ASP.NET Core Blazor project layout
• ASP.NET Core Blazor project architecture
• ASP.NET Core Blazor project design
• ASP.NET Core Blazor project framework
• ASP.NET Core Blazor project organization
• ASP.NET Core Blazor project anatomy
• ASP.NET Core Blazor project template

... the interesting thing about that last one is that some additional guidance WRT the template (if we have it now or later) can roll right in under that title no problem.

[danroth27]

Where in the TOC would you like the upcoming topic?

How about right after "Build your first app"?

I'll toss out a bunch of possible titles along your structure concept

I'm fine with most of the proposed options except for the ones I've crossed out below. Feel free to pick the one you like best:

ASP.NET Core Blazor project structure
ASP.NET Core Blazor project layout
ASP.NET Core Blazor project architecture
ASP.NET Core Blazor project design
ASP.NET Core Blazor project framework
ASP.NET Core Blazor project organization
ASP.NET Core Blazor project anatomy
ASP.NET Core Blazor project template

[danroth27]

DR do you like this phrasing, or should it rather be "the root Razor page, where the components are rendered"?

Your proposed phrasing sounds fine.