search

dotnet / AspNetCore.Docs

Documentation for ASP.NET Core
https://docs.microsoft.com/aspnet/core
Creative Commons Attribution 4.0 International
12.6k stars 25.29k forks source link

Confusing use of terminology #31562

Closed MarcoGaribaldi closed 9 months ago

MarcoGaribaldi commented 9 months ago

Description

Please note that the use of terminology on this page and the following phrase are rather confusing:

Any components using the Interactive WebAssembly or Interactive Auto render modes must be built from the client project.

However, the layout of the server-side project has a folder called components, while the client-side project doesn't. This is confusing for those who are learning Blazor and have a hard time understanding where to place things with this 2 project setup. The above phrase contradicts how the projects are laid out. Does this mean I must create the component folder in the client-side project?

Also, interactive is used to refer to the server-side project, but it is also used for Interactive WebAssembly and Interactive Auto render modes, so it forces the reader to constantly double-check what is what.

Page URL

https://learn.microsoft.com/en-us/aspnet/core/blazor/project-structure?view=aspnetcore-8.0#location-of-the-blazor-script

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] commented 9 months ago

🎉🥳 Happy New Year! 💃🕺

A green dinosaur 🦖 will be along shortly to assist. Stand-by ........

guardrex commented 9 months ago

Hello @MarcoGaribaldi ... I can make a change to improve some of these lines regarding where the Interactive WebAssembly and Interactive Auto components are placed and add the reasoning for the delta on the folder structure of the two projects.

On the first point about where the components are placed, it just means that they must go in the .Client project of the solution. You can place them into whatever folder you like in the .Client project.

Does this mean I must create the component folder in the client-side project?

No, the phrase "must be built" only means what it says ... must be built. It doesn't imply anything about where the components reside in the .Client project.

the server-side project has a folder called components, while the client-side project doesn't.

I raised that issue with PU during design, and Dan Roth had a separate discussion on a dedicated issue with Steve about it as well ...

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

It's by-design. I think I should add the reasoning for it to the Project Structure article.

Also, interactive is used to refer to the server-side project, but it is also used for Interactive WebAssembly and Interactive Auto render modes, so it forces the reader to constantly double-check what is what.

Not really AFAIK ... you'd need to call out specific lines of text on that. Interactive means 'can process C#/.NET,' and that's all it should imply. There's guidance on the basic concepts in the following back-to-back sections of the Fundamentals article ...

Thanks for the issue. I'll see if I can clarify your first two points. Leave this issue open, as it will close automatically later when the PR merges.

MarcoGaribaldi commented 9 months ago

Thank you for your prompt reply, appreciated.