Folder Layout doesn't match what is created with the current template.

[dbowser]

Description

There is a very frustrating lack of clear direction on the recommended approach in .NET 8 for retrieving content in a Blazor App from a database. Inaccurate documentation makes this even more frustrating. This page shows the components being in the Server section while the template puts them in the Client section even though I selected all the options to try to make this support the above basic scenario. Where should we put the Shared Classes? Where should we really put the page logic?

Including this basic scenario in the template would be VERY helpful so we can be sure we are aligning with the expectations of the platform and are not missing something. Having documentation which clearly explains any options/decisions related to this would be VERY helpful.

Thank you!

Page URL

https://learn.microsoft.com/en-us/aspnet/core/blazor/project-structure?view=aspnetcore-8.0&WT.mc_id=DT-MVP-7776

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/blazor/project-structure.md

Document ID

6f27ff37-6b3a-57f5-353a-5cf5aabba7cf

Article author

@guardrex

[github-actions[bot]]

😎🏖️🌴 — 🦖 is OOF until July 1 — 🏐🏄‍♀️🦩

Hello! The green dinosaur guy 🦖 (guardrex) is OOF from 6/24 to 6/28 and will return on July 1. Critical bug reports will be addressed during this period, but please standby for the 🦖 to return on July 1 for all other non-critical issues.

[guardrex]

Hello @dbowser ... A Blazor Web App is just server-side ASP.NET Core app, so most of the guidance in the main doc set for ASP.NET Core apps apply. There's an upcoming tutorial that will demonstrate the concepts along the lines of how the Razor Pages and MVC tutorials explain them. That tutorial will merge into the live docs in the first or second week of July. If you want to access the draft for that article, you can read the pages (in markdown format at this time) in the PR diff. The articles in the series are numbered (part-1, part-2, etc.) ...

Add new Blazor tutorial on BWA with EF Core https://github.com/dotnet/AspNetCore.Docs/pull/32747

... or wait until mid-July when the article will appear in the doc set.

WRT ...

This page shows the components being in the Server section while the template puts them in the Client section even though I selected all the options to try to make this support the above basic scenario.

Server-side components are placed in the Server app, while client-side WebAssembly or Auto components are placed in the client project. There's one rare caveat covered in the Render Modes article; but other than that, I'm not aware of any incorrect guidance in this article. You'll need to be more specific about what doesn't match the article in the project that you created and what you mean by "support the above scenario."

This article is only meant to describe the basic layout of a Blazor app based on the project templates. The project templates don't scaffold EF Core-based database access on their own. That will be covered by the upcoming tutorial that I mentioned ... and is currently covered by the existing articles in our doc set outside of the Blazor node for ASP.NET Core apps and in the EF Core doc set.

Where should we put the Shared Classes?

For apps that only adopt server-side rendering, there's only one project, so you place them in that project or in an added class library project. When there's a server and client project to support WebAssembly and Auto components, shared classes that are used by both projects typically go into a class library project referenced by both projects. If the components in the client project only use the shared classes, they can just go in the client project (or again, a class lib added to the solution).

The reason that we haven't spent much time addressing these aspects is that really it's up to the developer how to organize their shared classes. The real answer is that the platform has no specific recommendations outside of service classes, which are organized a bit more to be injected into components with different implementations depending on if the component is being rendered on the server or the client, which is covered further into the doc set. Even in that case tho, you always have the flexibility to place the classes in one or more class library projects to suit your needs.

Where should we really put the page logic?

Page logic is supplied either by shared classes referenced by components or in the component definition files themselves. The concepts are covered in the Components node of articles, especially the Components > Overview article. It's further covered for specific feature sets in the other articles in that node.

Including this basic scenario in the template would be VERY helpful

Any suggestions on what should be in the project template should be presented to the product unit team that maintains the framework. You can open an issue for them on their repo at ...

https://github.com/dotnet/aspnetcore/issues

I'll leave this open for a bit to give you a chance to respond. If you have some specific items for the Project Structure article for me to take a look at, I'm OOF on vacation until July 1. I'll take a look at your feedback when I return from vacation.

[guardrex]

... and I forgot to mention that the sample app for that tutorial is in the samples repo now. It's also a DRAFT at this time and subject to change as I finalize the article. However, you can look at that to see the basic setup. The tutorial walks a dev end-to-end creating the app from the Blazor Web App project template. That's the final end app after following all of the steps in the tutorial.

https://github.com/dotnet/blazor-samples/tree/main/8.0/BlazorWebAppMovies

[guardrex]

... and one more that I forgot to mention. We have EF Core with Blazor coverage in ...

https://learn.microsoft.com/en-us/aspnet/core/blazor/blazor-ef-core?view=aspnetcore-8.0

... and there's a sample app for that one, too ...

https://github.com/dotnet/blazor-samples/tree/main/8.0/BlazorWebAppEFCore

We'll need to work out a description that compares and contrasts that article and its examples from the upcoming tutorial. One worrisome aspect that I'm aware of is that the approaches we're pitching in the upcoming EF Core tutorial don't rely on OwningComponentBase and a factory-based database context. In fact, my initial analysis of the project unit scaffolding code for the new tutorial seems to violate some of the concepts that the current EF Core doc warns against, which was written by one of the product unit engineers. I'll take that up with the product unit when I get back from vacation. Both articles will live in the docs, but we need to state clearly the difference between the approaches ... pros/cons ... gotchas 😈.

I say that the differences are worrisome, but it might be that EF Core changed in some ways in the 8.0 release that make the guidance in the current EF Core article obsolete. Either way, I'll tend to the deltas when I get back.

[guardrex]

Haven't heard back, so I'll close as not actionable. I'll need more specific information on any discrepancies that you want to report between the project that you generated and the article. WRT your remarks on database access (EF Core, for example), it's covered by the articles that I mentioned, and please check back in mid-July for the new Blazor tutorial. If you add additional information to this issue, I'll re-open it to take a look.