-
Notifications
You must be signed in to change notification settings - Fork 25.1k
Closed
Description
This issue will ...
- Maintain a set of doc ideas for Blazor topics that we either don't want to (or can't) address in the near-term or are just ideas for consideration that don't warrant an issue at this time.
- Track work on topic UE (user experience) passes (i.e., topic overhauls).
Doc ideas
- Confirm with the PU that runtime relinking is a publish-and-Release config gesture. Building only produced 51.5 MB. Publishing in
Debugwas 9.3 MB without relevant console compiler output. Publishing inReleasewas 6.6 with console compiler output that looked like runtime relinking was taking place. - When Document blazor msbuild configuration options docs#27395 is resolved and Mono/WASM MSBuild props are covered, update the cross-links from the targets file to the new official doc. Links can be located on the PR that added them at Mono/WASM MSBuild property guidance #24493.
- It seems like everyplace that we have hosted WASM, we should call out that the project must be run from the
Serverproject. The errors for not doing so can be quite cryptic 😵. For example, the File Uploads topic example throws a "JSON token" error when the solution is run from the client app. It's not at all clear that it was simply run from the wrong project. - The pivots for the Handle Errors topic were dropped, then the content was reorganized on Blazor Handle Errors content reorganization #24195 for its final layout. However, the Prerendering section is currently only for Blazor Server apps. That section should be made to generically cover both WASM and Server prerendering. Hosting model-agnostic Prerender section #24211
- For
NavLinkcomponents in examples: It will harden docs against past and future deltas to merely mention adding example components to theNavMenuand not actually show the markup, which seems to change quite a bit. Drop NavLink boilerplate examples #24130 - A number of spots show project file XML markup for adding packages to apps. There are also Package Manager and CLI commands. I think mentioning the package would be better and having an INCLUDE for the options: edit the project file, use the Package Manager, or use the CLI add package command. I should be able to filter the locations for these updates with
<PackageReference. Add package guidance INCLUDE #24212 - In the Prerender and Integrate topic, clarify the line that speaks to the dev starting with RP/MVC and then including Blazor Server app in order to render components from pages/views. About component's render from Razor Page #23948 (comment) Related: I add a
HeadOutletcomponent to the layout at Line 212 for the scenario of an RP/MVC app that embeds components from a hosted WASM app (render-mode="ServerPrerendered") to allow components to control head content. Due to time constraints at the moment, the coverage is going in. When I address this item and touch that line ☝️ also run a quick test and confirm the scenario for Line 212 actually works ... or did I just make up a new Blazor feature all by myself?! 🙈😄 - Drop the images added by Blazor environments for App Service #23959. They're provided by the PU for quick coverage, but we don't want images of the Azure portal unless absolutely necessary given the UI churn of the portal. Also, improve the naming (e.g., app name) ... and this will require text changes (e.g.,
https://bwhappsettingsasdf-staging.azurewebsites.netis in the doc text). Hosted Blazor App Service environments updates #24234 -
InputFilecomponent preview guidance (6.0) is in the new Blazor Images topic and probably should be better cross-linked. Blazor Wasm InputFile Preview Content Faster #23802 - Drop hosting model pivots from a few topics where they aren't needed, especially in Fundamentals node topics b/c readers are probably consuming all of these docs early and without regard to an explicit choice of hosting model. Drop pivots in Blazor fundamental topics #23736 PR for Call web API Demo 3 test (live now) & Additional updates for Call web API
- Sub-app hosting: Let's firm up a prohibition on the use of IIS virtual folders and firm up recommendation to host separate apps in separate app pools, including for sub-apps. Blazor app pool guidance #24235
- Clarify use case/config for Blazor Server
MapFallbackToPageconfiguration. Started on: App base path/sub-app hosting updates #23698 Finished up on (but it's rather draftish and needs more work later): Activate new/working MapFallbackToPage coverage #23735 Later, ask about Blazor Server Multiple _Host.cshtml Not Working aspnetcore#32333 (comment) relative to what I did here with my ordering of the fallbacks. PU Issue PU Issue (vaguely related without full discussion) - Ask Pranav about Example update #23566 (comment).
- Test some solutions for the content-hidden-in-a-pivot and search-results-don't-link-to-visible-content problems:
- Demo 1: Show version using the old style, where each section calls out what hosting model is applies to.
- Demo 2: Show a stacked H1 version where the hosting model is the H1 section and it's following sections are H2s or lower.
- Demo 3: Show a version where the section content of each pivot is displayed at the top of the alternate pivot.
- Ask RA for an internal issue on pivot search results. The problem is that the whole topic is indexed but the links to the topics don't point to the pivot where the content lives ... the topic loads with whatever default pivot the user has selected earlier (or the default). I think the search results should be by-pivot with a clear pivot indication and with a pivot-specific landing link. This would mean that it's possible for the reader to receive two or more search result links, but the reader would be taken directly to the pivot and not get confused when the land to find no content for what they searched.
- For Blazor AOT, add remark ... .NET 6.0 RC1 on macOS Apple M1: Blazor WASM AOT build generates & serves both, large dotnet.wasm and all the .DLLs aspnetcore#37092 (comment) ... also see 👉 Blazor AOT .Net6 Preview 7 - Still downloading Dlls aspnetcore#35302
- Ping Steve to take a look at the new guidance on Blazor event delegate performance #23223. The guidance+example might be incorrect, but the pattern was signed off by Artak at Blazor Binary message size send from server to client increases aspnetcore#17886 (comment). I tried not to totally make something up 😆, but I may have done so in this case. Ping back Darragh Jones on the outcome.
- Confirm that in spots where we're running a hosted WASM project in a command shell that the Server project is where the dev runs the app (Tried the steps in this Document, but was running into error #23166). Although VS gets a fix (Preview 4, Wrong startup project in Blazor WASM ASP.NET Core Hosted template aspnetcore#35356) not to default the startup project to the Client project for VS 2022, confirm it with VS 2022 at GA. Update: Done! Hosted WASM app start update #23227
- Explicit example of lazy loading (e.g., in the snippet sample apps). I'm rejecting on the grounds that its a straight-forward, well-described scenario in the topic and there isn't a lot of time to include it in the snippet sample app. There's no comprehensive example blazor wasm project with lazy loading #20154
- Check on the feature request for
Support WebSocket connections on Azure Front Doorin the Threat Mitigation topic added on Long Polling disabled update #23033: Update the text and/or kill the link when they either close it out as awon't-fixor decide to proceed with implementing the feature. Remove Blazor Server with Azure Front Door remarks #23279 - Dashes in filenames for Security node projects. See Dashes in a hosted Blazor WebAssembly project name break OIDC security aspnetcore#35337 (comment). Docs PR
- Check on encoding in query strings: We want
%20for spaces everywhere. Checked 8/25: No instances found to update. - Bit concerned about 3.1 (not 3.2 ... 3.1) coverage for Blazor loc. The MSBuild prop isn't involved, and framework churn might have led to poor guidance for 3.1. It will be low priority, but I'll check if I can find time 🏃😅. Update 8/25: Checking this one off as a
wont-fix: Given the arrival of 6.0 soon and the sunset of 3.1 LTS in 12/2022, this is a low enough priority item to merely see if reader feedback indicates a problem with 3.x coverage. - Target-typed new expressions. See 👉 https://devblogs.microsoft.com/dotnet/announcing-net-5-0-preview-8/#target-typed-new-expressions — First pass on Implement C# 9 target-typed expressions in the code samples #21934. Additional opportunities will be addressed as I go forward with UE passes after 3/31/21.
- Move the Layouts topic into the Components node? UPDATE: Done ... Move Blazor Layouts topic to Components ToC node #22368
-
ShouldRenderreferenced in the Rendering topic looks to be based in the perf topic, also appears in the Lifecycle topic, but perhaps would be better in the Rendering topic itself with cross-links from perf and Lifecycle topics. Move Blazor ShouldRender section #22475 - Call out heuristic scanner false positives with an INCLUDE. We've had ~3 issues now opened on (probably) false positives (for example, Virus Detected! #21829). Include strong lingo that it's the dev's responsibility to manage scanner exceptions, since we can't really know if the local copy of a file was modified after it was pulled down from somewhere where the source isn't infected. Also, there's something at https://docs.microsoft.com/en-us/aspnet/core/blazor/host-and-deploy/webassembly?view=aspnetcore-5.0#troubleshoot-integrity-powershell-script to address for this item. PR: Blazor 'integrity.ps1' script security #22338
- The MVC scenarios in the Prerender and Integrate topic weren't fully tested due to time constraints. Perform local testing of those aspects to confirm the guidance. Update 8/25: Checking this one off here because it's going to be tracked by the 6.0 tracking issue. I plan to verify all scenarios in the doc for 6.0 at RC1 and not further test prior releases unless a dev writes in with a problem with 3.1 or 5.0.
- Review Introducing mess with "Blazor" first word #21277 in the context of all Blazor doc set docs. Originally, components could only be used in Blazor apps (and the content was written that way), but they can be used in ASP.NET Core apps now. UPDATE (7/19): We won't be able to address this unless the PU were to move Razor components away from WASM/Server ... e.g., they become part of Razor formally and not just be based on Razor syntax ... which doesn't seem like its going to happen. Components will be Blazor framework objects made available to other frameworks in parallel with those frameworks, so they'll continue to be documented that way AFAICT. The Components node will stay in the Blazor node. The inclusion of "Blazor" as a web tech tho is a bit funky now tho with MAUI, which doesn't have to be a web tech.
- Re-evaluate the RCL topic for snippet app use. Overkill, or good i-dear? UPDATE: Done ... Let's not given the workload. It can be done the next time the RCL topic is overhauled in a few years.
- Document that
<head>element interaction is only supported via JS interop? See: Nonce/Hash in Blazor (CSP) #22121. UPDATE: Done ... This has been placed on the 6.0 tracking issue to resolve when the<head>element features are added to the doc set (see: Blazor 6.0 content tracking issue #22045). - Take a look at https://docs.microsoft.com/en-us/aspnet/core/blazor/hosting-models?view=aspnetcore-5.0#comparison-to-server-rendered-ui and further sections in light of the discussion on CSS Isolation topic addresses Razor components, but what about Pages? #22165. There are probably opportunities for improving the coverage that compares and contrasts RP/MVC and Blazor frameworks. Update 8/25: Checking off because this is going to be tracked by RP/MVC CSS isolation coverage for 6.0 #23120 as part of the 6.0 updates.
- Address the use of Bootstrap JS in a suitable spot. We warn off of interacting with the DOM in the JS interop topic, but Bootstrap guidance (for styles) appears earlier in the doc set. It's bound to be a question in devs' minds. See 👉 Guidance on Blazor wasm app that uses some bootstrap.js functionality #22213. Blazor interaction with the DOM #22489
- Create an Overview in the Fundamentals node with a bare bones explanation of a component in order to understand fundamental concepts+examples better, orient on any doc consumption features (e.g., use of working examples, sample apps, use of the
thiskeyword, resolve Blazor common sample enhancements #14216, etc.), and any other prelim remarks before the reader gets into the meat of the coverage. Blazor docs need to be streamlined #22230 (comment) - Consistency of Razor component directive order — Razor component directive order and heading levels #22357
- Confirm/update topic redirection is correct (e.g., check for double-redirection) — Blazor topic redirection updates #22358
- WRT the early use of the snippets sample app: I'm not favoring using partial components that require mocked pieces and inlined
<snippet>tags. This approach is generating a lot of local DocFX build warnings that are clouding real (important) warnings that I need to address. It's slowing me down 🐌. Either move these snippets back into the topics or recompose them or relink them without the use of<snippet>tags in their markup. — Blazor snippet sample app updates #22359 - Confirm null check in object disposal (e.g.,
objRef?.Dispose();). Blazor object disposal updates #22597 - JS interop
- Call JS from .NET doesn't demo cancellation token use. I think a working cut-'n-paste example wouldn't take up much space and would be nice to show.
- The Call .NET from JS topic mentions but doesn't show an example of calling an open generic method ... include one? Cross-ref: PU
InteropComponent.razorandGenericType<TValue> - The JS interop topics have no guidance on reporting explicit exceptions from JS (e.g., wrap the invoke and then
catch (JSException e)) ... include a section and one or more examples? Cross-ref: PUInteropComponent.razorDocs PR: Catch JS interop exceptions #22772 - Is there anything else in the family of JS interop JS function calls that should be mentioned or explained out with examples? Cross-ref: PU
Microsoft.JSInterop.ts - React to Update Blazor Call .NET from JS + fix a regression #19734 (comment). Update: A fix was made at the time, and no further negative feedback has been received. AFAIK, the sections+examples are composed correctly.
- "server API" and "web API" are both in use across Blazor docs. Stabilize on "web API" to match general terminology in ASP.NET Core docs. Blazor Call web API UE pass #22410
- For the file upload topic (and perhaps the one in the main doc set, too), consider adding a blurb about how PS can create dummy test files. Call out PS for dummy test files #22591
- Confirm/add null checks on element references (
ElementReference,@ref) before calling methods on them. Null-check ElementReferences #22771 - Obtaining v2.0 JWT tokens. See convo at 👉 Blazor Webassembly (standalone) does not work with v2.0 endpoints aspnetcore#35794 (comment)
- Old sample apps dropped on Blazor drop old sample apps #23228. Do we want to make the snippet sample apps into running apps and link them in the Blazor docs? Related ?: Whether or not we make snippet samples for download, should sample apps in general be kept/cross-linked in the official MS samples repo for easy download. This was a long-range plan for all ASP.NET Core sample apps AFAIK, but it hasn't taken place due to constant higher-priority work. We could at least make the Blazor Server-EF Core final app and the two Blazor-SignalR tutorial final apps available via that mechanism for easy download.
- Do we want to make the Static files topic hosting model agnostic and get into static asset caching behavior, including how to control/manage it during development. Alternatively, we could document caching behaviors/scenarios in the Environments topic at https://docs.microsoft.com/aspnet/core/blazor/fundamentals/environments. The (possibly temporary) PR that focuses on JS file caching went in on Blazor JS file cache/no-cache guidance #23235.
UE pass tracking
🔴 = Snippets update complete
- Overview — 🔴
- Supported platforms 🔴
- Tooling — 🔴
- Hosting models — Blazor hosting models UE pass #20868 🔴
- Tutorials
- Build a Blazor todo list app — Blazor tutorial UE pass #20941 🔴
- SignalR with Blazor WebAssembly — SignalR with Blazor Server samples+pivot #21271 🔴
- Project structure — Improve readability of Blazor project structure doc #21247 🔴
- Fundamentals
- Routing — Improve readability and apply ASP.NET Core 5.0 updates to Blazor routing doc #20900 🔴
- Configuration — Improve readability of the Blazor configuration doc #20908 🔴
- Dependency injection — Improve readability and introduce Server/WASM zone pivots to Blazor dependency injection doc #20920 🔴
- Startup — Blazor startup topic #22279 🔴
- Environments — Blazor Environments & Logging topics UE pass #20929 🔴
- Logging — Blazor Environments & Logging topics UE pass #20929 🔴
- Handle errors — Blazor Handle Errors topic UE pass #21601 🔴
- SignalR — Blazor SignalR UE pass #21620 🔴
- Static files — Reorganize the Blazor SignalR guidance content #21331 🔴
- Components
- Overview — Blazor Components Overview UE pass #22053 🔴
- Cascading values and parameters — Cascading values and parameters UE pass #21366 🔴
- Data binding — Improve readability of Blazor Data Binding doc #21678 🔴
- Event handling — Improve readability of Blazor Event Handling doc #21755 🔴
- Lifecycle — Improve readability of Blazor Lifecycle doc #21822 🔴
- Rendering — Blazor Rendering topic UE pass #21766 🔴
- Component virtualization — Blazor Virtualize topic UE pass #21623 🔴
- Templated components — Improve readability of Blazor Templated Components doc #21666 🔴
- CSS isolation 🔴
- Prerender and integrate components — Improve readability of Blazor Prerendering and Integration content #21881 🔴
- Component libraries — Blazor RCL topic UE pass #21946
- Globalization and localization — Blazor Global/Loc UE pass #22525 🔴
- Layouts — Blazor Layouts UE pass #21636 🔴
- Forms and validation — Blazor forms and validation UE pass #22106 🔴
- File uploads — Blazor File Uploads topic UE pass #22161 🔴
- JS interop
- Overview
- Call JavaScript from .NET — Blazor Call JS from .NET UE pass #22229 🔴
- Call .NET from JavaScript — Blazor Call .NET from JS UE pass #22304 🔴
- Call a web API from WebAssembly — Blazor Call web API UE pass #22410 🔴
- Security and Identity — See 👉 Would it be too much to ask to properly explain this #20708, Explain schemes in Blazor WASM security #19807, and AzureADDefaults.JwtBearerAuthenticationScheme vs AzureADDefaults.BearerAuthenticationScheme #19226. I placed an ellipsis in the
Appcomponent example INCLUDE(s) to cover 6.0 churn. See: Missing code which is generated from project template #23696- Overview — Either here or in the Blazor Server Overview: How to refresh updated Claims without login out #22405
- Blazor WebAssembly — See 👉 Two App Registrations? #20512 & This page does not describe authentication with "MS Account" #21816 (comment). Also, consider surfacing a smidgen of WebAssembly "sandbox" content in a new section with a cross-link or two (e.g., https://webassembly.github.io/spec/core/intro/introduction.html#security-considerations, https://webassembly.org/docs/security/). It would be nice to clarify that WebAssembly (as a non-MS technology) is constantly undergoing security patching, and there is a place (I'll find the link) where devs can see potential security vulnerabilities, work on WebAssembly security, and patches being put into place.
- Overview — See 👉 The significance of accessTokenAcceptedVersion attribute should be mentioned #21741 (cross-link to an Azure doc from all of our AAD/B2C docs)
- Standalone with Authentication library — See 👉 Blazor std-alone oidc authorization not requesting prompt #21510, Blazor standalone oidc authorization not requesting prompt aspnetcore#30068, "offline_access" scope with AddOidcAuthentication? #23712
- Standalone with Microsoft Accounts
- Standalone with AAD
- Standalone with AAD B2C — "custom user flows" language Can't log in or create account or reset password #21144. Take a look at signup-signin Azure UI per Blazor WASM AADB2C template fetchdata failed due to The issuer '(null)' is invalid aspnetcore#39401 (comment).
- Hosted with AAD — See 👉 Question/Clarification wanted for Blazor WebAssembly Azure AD Setup Documentation #21983
- Hosted with AAD B2C — "custom user flows" language Can't log in or create account or reset password #21144; see 👉 Critical error out of the box. #21640. Take a look at signup-signin Azure UI per Blazor WASM AADB2C template fetchdata failed due to The issuer '(null)' is invalid aspnetcore#39401 (comment).
- Hosted with Identity Server — See 👉 Can't find certificate in store when deploy in production. #21842 and also see CAN'T DEPLOY BLAZOR WASM ON AZURE #22753 (Was it just VS not creating the project with the correct Identity config to run OOB when deployed to Azure directly from VS?) Consider splitting out custom domains from IdS, and check on the B1 requirement IdS-only scnearios (it might not be a requirement in that case). See 👉 Confirm hosted Blazor IdS AKV certificate access guidance #24067 (comment).
- Additional scenarios - Look for split-out opportunities. Possibly add an introductory ToC with section descriptions. Consider if the Unauthenticated or unauthorized web API requests in an app with a secure default client section could be better cross-linked/mentioned explicitly in the individual WASM security topics (Blazor Server Authorize Attribute #22217 and Additional HTTP client reference in note section #22220). Consider making an INCLUDE out of the prerendering guidance and shooting a copy of that into the Prerendering and Integration topic (Add Blazor hosted WASM prerendering steps when using Azure Ad authentication #23441).
- AAD groups and roles — Update Blazor Azure Active Directory groups and roles doc for ASP.NET Core 5.0 #20856; do we need a Blazor Server pivot, or can we cross-link? See 👉 sample for Blazor Server #22422
- Graph API — See 👉 Several question related to this page #22657
- Blazor Server
- Overview — Review, work was done on 👉 Update Blazor Server authentication topics for ASP.NET Core 5.0 #20119 and mention Miss a strategy to handle the refresh of tokens #19797 (comment).
- Threat mitigation
- Additional scenarios — Review, work was done on 👉 Update Blazor Server authentication topics for ASP.NET Core 5.0 #20119. Also, see 👉 Provide More Details on "Common Services" #22122.
- Content Security Policy
- State management 🔴
- Debug WebAssembly &mdash: Resolve 👉 Something is missing in this instructions on how to debug a Blazor Webassembly hosted. #23373 ... and we'll probably need to show full files everywhere we refer to
tasks.json/launch.jsondue to Errors when running .net generate assets to build .vscode folder vscode-csharp#4542. See 👉 small clarification #23777 - Lazy load assemblies with WebAssembly — Blazor WASM lazy loading topic UE pass #22603 🔴
- WebAssembly performance — Blazor Performance UE and pivot updates #23135
- Test components 🔴
- Progressive Web Applications — See 👉 Blazor SPA PWA offline auth #21100
- Host and deploy: Apache for hosted WASM/sub-app scenarios might need more work. See 👉 Blazor Linux hosting #24519 (comment).
- Overview — Perhaps for Routing, too, but clarify the navigation behavior of
NavigationManager.NavigateTo. See :point-right: Use relative path in NavigateTo #22146 (comment). - Blazor WebAssembly — See 👉 Revert to minified Google Brotli script in Blazor WASM hosting #19979 and Virus Detected! #21829 (comment)
- Blazor Server — See 👉 Publishing Blazor to IIS from Visual Studio #21226
- Configure the Trimmer — Configure Trimmer UE pass #21480 🔴
- Overview — Perhaps for Routing, too, but clarify the navigation behavior of
- Blazor Server and EF Core
- Advanced scenarios — Blazor Advanced Scenarios topic UE pass #21768 🔴
- Scaffolding topic sections that pertain to Blazor — See 👉 Blazor and jwt problems with Scaffold Identity #8434 (comment)
- File downloads topic: Use fully-working examples, place code into snippet sample apps, and see the cross-linked discussion and bits mentioned in Blazor file download updates #24560 (comment).
- Images topic: Use fully-working examples.
Ricardoaraujo00 and PhilParisotPhilParisotPhilParisot
Metadata
Metadata
Assignees
Type
Projects
Status
Done