Aspnetcore: ℹ️ **Looking for ideas from the community** for Blazor docs improvements

[danroth27]

We've received a some feedback from the in-product Blazor survey that the Blazor docs could use some improvement. Thank you for this feedback! We know that docs are a critical part of any software development framework, and we are committed to making the Blazor docs as helpful as we can.

Let us know how you think we can best improve the Blazor docs by commenting below with your suggestions. Specifically:

• What new content would you like to see added?
• How would you like to see the existing content improved?

To keep this issue manageable, only comments with suggestions will be allowed. No discussions or debates please!

Other ways you can help improve the Blazor docs:

• As you read the Blazor docs, let us know where we should focus our efforts by telling us if you find a topic helpful or not using the helpfulness widget at the top of each doc page:

  

• Use the Feedback section at the bottom of each doc page to let us know when a particular topic is unclear, inaccurate, or incomplete.

  

Thanks for your feedback!

[boukenka]

Hello,

Thank you first of all for the initiative.

I would like to find in the documentation one or more pages that would contain a summary table. This table would describe in several columns the essential information to implement a specific functionality. For Server or Client, which method (ConfigureServices, Configure or Main), Remarks, what other configuration must be done (Required and the order/position in the configuration), for a specific Feature (Database, Policy, Horns...), relevant links for the pages.

_Server / Client - ConfigureServices - Configure - Main - Remarks - Mandatory - Feature - Links_

The aim is to quickly get practical information if you want to add a specific feature, for example _authentication via a token_, without having to search all pages, with a sample code.

These pages would be a starting point to know how to begin implementing the desired functionality.

Today there are many options for service configuration. I think the majority of them are never used, either because they are rarely useful, or because they are not used at all, or because we have no idea what we can do or if they are still relevant.

They should be simplified to provide the basic functionality: _Authentication, Routing, Authorization, Session, Debugging ..._ to all developers who want to set up a website with the necessary bricks.

I hope this makes sense and you get the idea 😄

[Pilchie]

:eyes:

[anthcool]

I'd love to see walk-throughs of working with table data scenarios used in the real world. Creating Blazor components that showcase tables of data that can sort, filter, paginate, add records, edit records _(inline (whole row and single cell only), modal, new page)_, sticky headers, footers, theming, pivoting the data, sub-grids/accordions, etc. Not Hello World examples. Not examples tightly-coupled to Azure and all that adds. For apps that utilize in-house company web APIs hosted on-prem, where the API project _ONLY_ uses Entity Framework Core and _not_ the actual client-side apps. They are restricted to the API for data (so HttpClient). So, no examples that cheat with scaffolding generators meant for EF Core and APIs. <--- That will onboard the rest of the world to .NET that isn't wanting to or willing to buy into Azure or use EF Core for client-side applications.

[chelabitarik]

Here are some ideas

• Best practices ( components placements and naming .... )
• Handle state management using a real world exemple
• Make use of signalR with blazor building a real time one to one chat
• Epayment methodes and gateways available for blazor and how to use them
• Tutorials on how to upload files and the use of markdown editors and charts
• SEO and blazor
• Make the standard contoso university project with blazor
• Roles with client side blazor
• Caching, Compression and optimizations

PLEASE no tutorials with azure !!

[rogihee]

I think the documentation is really coming together quite nicely. But it needs some more good example projects tied to the documentation. It is difficult to get a good overview of a full blown Blazor WebAssembly project with component libraries, authentication, server pages, SignalR etc. @SteveSandersonMS demo of the currency converter was really nice and I hope he has enough toilet paper stocked to finish that soon and publish it somewhere :-).

Some extra ideas:

• Custom base url for an app
• Use multiple Blazor WebAssembly client projects with one Server project
• Mix server Razor pages with a Blazor WebAssembly Client project.
• Instead of an index.html in the Client project, bootstrap a Client from a Razor Page endpoint in the Server project. I want to protect my Blazor dll's with server side authorization. As far I as I understood, the index.html right now is always accessible, and thus the DLL's in the Client project, which anyone with decompiler can snoop information from. Authorization (Roles / Policy) inside a Blazor WebAssembly app has been documented quite well now.

[juant72]

With a complete application eShop style, full documented, It's a good approach, and very useful.

[JeepNL]

Code First EF Core DB (Relational Tables) Generation for Blazor WASM with API & gRPC on top of IdentityServer4 Tables.

"This content is coming soon. (_Dealing with Data / Data access and management_)"
https://docs.microsoft.com/en-us/dotnet/architecture/blazor-for-web-forms-developers/data

[MichaelSpranger]

Documentation of the command line options of the Blazor Wasm template, e.g. -ho. I know of no way of listing them with dotnet new, and could find nothing in the official docs.

[guardrex]

@MichaelSpranger ... dotnet new blazorwasm --help. I'll surface it in the Blazor Templates article. Opened https://github.com/dotnet/AspNetCore.Docs/issues/17905 to address it. Thanks.

[mrpmorris]

I'd love to see walk-throughs of working with table data scenarios used in the real world. Creating Blazor components that showcase tables of data that can sort, filter, paginate

Pagination : https://blazor-university.com/templating-components-with-renderfragements/passing-placeholders-to-renderfragments/

[GiffenGood]

Plunker or some other runner that would allow you to "try it" in the browser.

[zequential]

Answer challenges on speed by documenting best practice for setting up dual mode

Critics say the client side download is too large and you are doing great work to address that. Dual mode - launching Blazor Server and downloading Blazor Client in the background - would appear to be a low-tech way to immediately improve UX while getting the full WASM experience, PWAs, etc. For that reason, it seems to present a _lot_ of bang for buck in increasing commercial viability, while the framework matures.

I saw @danroth27 mention in the preview 4 release notes that there are no plans to create a template, which is fine. Are there any architectural reasons that MSFT is not supporting this approach (i.e. long term maintainability or some dead end in it at scale)?

If its architecturally viable, a best practices note on how to set it up seems from the outside to move the dial on using WASM, achieve backwards compatibility on IE11 through Blazor Server and for that reason real time dynamic switching on first load would appear to be a great enabler to drive adoption.

Appreciate that people will say its out there if you search GitHub; its going to be hard for new users assessing whether to use Blazor to know and find those examples and examples become out of date, may not be best practice, etc.

If this is a viable and fundamental enabler for take up, inclusion in the docs would raise visibility and make clear to those assessing the framework that WASM can be available at server speeds and still at mitigated hosting costs for first load only.

[SteveSandersonMS]

Are there any architectural reasons that MSFT is not supporting this approach (i.e. long term maintainability or some dead end in it at scale)?

Because it adds quite a few extra complications (needing to think about how things like auth and data access would work in two entirely different runtime scenarios), and it's not totally clear that there's enough customer demand for it, or whose specific problems it solves.

Long term I think we'll be guided by customer demand here. Usually if something like this is compelling enough, we see community implementations (e.g., shipped as NuGet packages). Eventually if such a package/technique gains enough broad adoption, that represents evidence that it should be considered as a framework feature.

[Lupusa87]

Hello,

It will be great if we add how to pass parameter and especially many parameters when calling dotnet method (static or instance) from JS.

What data types are supported and how to pass many parameters.

And to be honest here can be simpler example, existing one is complicated and hard to read and understand even for me (my eyes are more or less familiar with that staff) and I guess will be more harder for newbies.

https://docs.microsoft.com/en-us/aspnet/core/blazor/call-dotnet-from-javascript?view=aspnetcore-5.0

Thank you.

[guardrex]

@Lupusa87 ... Work on the JS interop doc will be scheduled shortly. The topic will be addressed after the 3.2 release. Updates will include an improved sample app experience for JS interop scenarios.

[burakakca]

It would be better if the blazor page does not host in microsoft, it is external.

[mkArtakMSFT]

Thanks everyone for participation.

I've scanned through the asks here which were somewhat repetitive and got the following set of issues / articles / samples for handling the feedback here:

• Differences between Blazor Client and Blazor Server
• Virtualization sample app (aspnet/samples GitHub repository)
• Best practices guidance for writing Blazor applications

Of course we will also tweak / update our existing docs to improve overall satisfaction going forward.