Blazor Hybrid tracking

[guardrex]

Articles (ToC and physical/URL locations)

Topic	Location/filename	Issue	PR
Static files1	aspnetcore/blazor/hybrid/static-files.md	#25674	#25891	Live Topic
Routing & Navigation2	aspnetcore/blazor/hybrid/routing-and-navigation.md	—	#25130	Live Topic
Reuse Razor components3	aspnetcore/blazor/hybrid/reuse-razor-components.md	#25675	#25847	Live Topic
Integrate with native UI4 DROPPED†	aspnetcore/blazor/hybrid/integrate-with-native-ui.md	#25676	❌	❌
Access native platform features5 DROPPED†	aspnetcore/blazor/hybrid/access-to-platform-features.md	#25677	❌	❌
Native look and feel6 DROPPED†	aspnetcore/blazor/hybrid/native-look-and-feel.md	#25678	❌	❌
Globalization & Localization7	aspnetcore/blazor/hybrid/globalization-localization.md	#25679	—	—
Use browser dev tools8	aspnetcore/blazor/hybrid/developer-tools.md	#25382	#25384 #25484	Live Topic
Security & Identity Overview9	blazor/hybrid/security/index.md	#25453, #25461, #25771	#25555, #25791	Live Topic
Security considerations (added per Security Overview updates)	blazor/hybrid/security/security-considerations.md	—	#25791	Live Topic
Security & Identity Threat mitigation10 DROPPED†	blazor/hybrid/security/threat-mitigation.md	#25680	❌	❌
Security & Identity With AAD11 DROPPED†	blazor/hybrid/security/azure-active-directory.md	#25681	❌	❌
Security & Identity With AAD B2C12 DROPPED†	blazor/hybrid/security/azure-active-directory-b2c.md	#25682	❌	❌
Publish Overview13 publish folder	blazor/hybrid/publish/index.md	#25683	—	—

†See the issue for details.

Notes:

5 — Will be covered by #25675 in the Reuse web components topic.
7 — Document dotnet/maui#2532.
9 — Create a folder at aspnetcore/blazor/hybrid/security.
13 — Create a folder at blazor/hybrid/publish.Cross-link landing and general guidance. Cross-link out to the Blazor host and deploy overview, and cross-link to this Hybrid apps publish overview from there.

Additional Tasks

• In the Error handling topic for macOS with .NET MAUI dev tools, react to resolution of Blazor Hybrid Mac Catalyst Dev Tools not Supported maui#5561. Context at Blazor Hybrid dev tools topic #25384 (comment). UPDATE: This now has a dedicated issue at Mac Catalyst dev tools support #26039.
• To fix Keeping webviews up-to-date in deployed Blazor Hybrid apps #25453, un-comment the remarks in the topic. PR: [RC2] Keep WebViews current #25670

Process

Working in order down this list ...

• Thursday (2/10): General tutorials work for existing tutorials. This isn't directly related to Hybrid apps coverage outside of preparing for cross-links, but I'd like to get this resolved first. Blazor tutorial organization #24960
• Thursday-Thursday (2/10-2/17): PRs loaded for review as they're ready with GH and email pings for review.
  • PR 1 Blazor Hybrid PR1 #24965
    • Preview notice INCLUDE
    • Blazor Overview (blazor/index.md) update
    • Tooling topic Additional Resources cross-link to the Hybrid tutorials overview
    • Supported platforms update
    • Hosting models update
    • Hybrid Overview (blazor/hybrid/index.md)
    • Hybrid Tutorials folder and overview (placed on PR 1 to unblock the remaining PRs)
  • PR 2: .NET MAUI tutorial .NET MAUI Blazor tutorial (PR 2) #24977
  • PR 3: WinForms tutorial Blazor Hybrid WinForms tutorial (PR3) #24989
  • PR 4: WPF tutorial Blazor Hybrid WPF tutorial (PR 4) #25043
• Friday (2/18): no-loc update to add "Blazor Hybrid" Add Blazor Hybrid to no-loc metadata #25064

Notes

• All topics to receive a preview notice at the top.
• A 'Blazor Hybrid' column as already been added to the Blazor.Docs project for tracking work.
• Although final release is apparently 7.0, we'll version topics for 6.0 or later so that they'll show up during preview.
• Some overview topics, at least initially, may only contain minimal guidance. The main value of some of them is to provide a cross-link landing from other places around the doc set and for external links. I recommend their use and have included them where needed here.
• I defer on "contextual ToCs" but mention that whatever is done I recommend not breaking a reader's location in the ToC as they read and work down our ToC.
• After further reflection, especially along the lines of the prior bullet, I think Hybrid apps security and host/deploy content should be in the Hybrid node. Again, I seek to avoid readers losing their place and getting frustrated trying to figure out where they just were.
• Conforms to the plan for Blazor tutorial location (ToC and physical location) for the reasons discussed at Question on tutorial location for current and upcoming Blazor tutorials #24900.
• Samples
  • https://github.com/danroth27/BlazorWinForms
  • https://github.com/danroth27/BlazorHybridWpf (we're reacting to WPF app with BlazorWebView fails to compile the Razor components maui#3526 with an RCL workaround)
  • In the .NET MAUI repo: https://github.com/dotnet/maui/tree/main/src/BlazorWebView/samples

Additional remarks from the discussion

There's no formal name for using Blazor with WPF and WinForms. The ".NET MAUI Blazor app" name comes from the corresponding template name, but we don't have templates for using Blazor with WPF and WinForms. ".NET MAUI Blazor app" merely refers to a .NET MAUI app with at least one BlazorWebView control. We will avoid defining a name for Blazor-WPF and Blazor-WinForms for now and instead refer to the task, something such as, "Add a BlazorWebView to a {WPF|Windows Forms} app."

Hybrid apps use a blend of native and web technologies. A Blazor Hybrid app uses Blazor in a native client app. Razor components always run natively in the .NET process and render web UI to an embedded web view control using a local interop channel. WebAssembly isn't used at all in Hybrid apps.

There's no plan to add BlazorWebView articles to the WPF and Windows Forms doc sets. .NET MAUI is a bit different in that the BlazorWebView is built into the framework. .NET MAUI docs will link to the Blazor docs wherever appropriate.

Additional remarks for the content and tutorials

• .NET MAUI tutorial
  • Include instructions both for getting started using the .NET MAUI Blazor template and manually adding a BlazorWebView to an existing .NET MAUI app, similar to what we'll need to document for WPF & WinForms.
  • Getting started guidance on both Windows and non-Windows machines.
• WPF and WinForms tutorials: Go off of the sample apps.
• Blazor Hybrid overview: Check out the presentations (email) as a starting point.

Archived work on this issue

Initial coverage

• Overview - In blazor/index.md, add a Blazor Hybrid section. Blazor Hybrid PR1 #24965
• Tutorials (ToC entry) - Create a folder named tutorials. Move the current tutorials.md file content to an overview, and add a redirect. Move this node down two spots under "Tooling". Blazor tutorial organization #24960
  • Overview - Dervied from existing tutorials.md with additional remarks, as needed. Include a cross-link to the Hybrid app tutorials overview. (aspnetcore/blazor/tutorials/index.md)
  • Get-started (ToC cross-link to the Learn Module for Blazor Server)
  • Build a Blazor todo list app (Server or WASM) (aspnetcore/blazor/tutorials/build-a-blazor-app.md)
  • SignalR with Blazor (Server or WASM) (aspnetcore/blazor/tutorials/signalr-blazor.md)
• Supported platforms - In blazor/supported-platforms.md, mention Blazor Hybrid. "We test on and support the latest platform webview control versions (WebView2 on Windows, Chrome on Android, Safari on iOS and macOS)." Blazor Hybrid PR1 #24965
• Tooling - In blazor/tooling.md, cross-link to the Blazor Hybrid tutorials overview. Blazor Hybrid PR1 #24965
• Hosting models - In blazor/hosting-models.md, add a Blazor Hybrid section that covers the arch and pros/cons. Blazor Hybrid PR1 #24965
• Hybrid apps (ToC entry) - Create a folder named hybrid.
  • Overview - Add blazor/hybrid/index.md with initial (minimal) overview remarks (anything more detailed than what the Hosting Models article covers). This article mostly serves as a cross-link landing. Blazor Hybrid PR1 #24965
  • Tutorials (ToC entry) - Create a folder at blazor/hybrid/tutorials.
    • Overview - Cross-link landing page. (blazor/hybrid/tutorials/index.md)
    • Blazor Hybrid with .NET MAUI (aspnetcore/blazor/hybrid/tutorials/maui.md) .NET MAUI Blazor tutorial (PR 2) #24977
    • Blazor Hybrid with WPF (aspnetcore/blazor/hybrid/tutorials/wpf.md) - Supply components via an RCL workaround (WPF app with BlazorWebView fails to compile the Razor components maui#3526). Blazor Hybrid WPF tutorial (PR 4) #25043
    • Blazor Hybrid with Windows Forms (aspnetcore/blazor/hybrid/tutorials/windows-forms.md) Blazor Hybrid WinForms tutorial (PR3) #24989

[guardrex]

@danroth27 @mkArtakMSFT

There's no plan to add BlazorWebView articles to the WPF and Windows Forms doc sets. .NET MAUI is a bit different in that the BlazorWebView is built into the framework. .NET MAUI docs will link to the Blazor docs wherever appropriate.

Let's clarify this further. Where is BlazorWebView is going to be covered? Is it supposed to be part of the upcoming topic "Integrate with native UI" (aspnetcore/blazor/hybrid/integrate-with-native-ui.md)? ... to then be THE platform-agnostic place for coverage (covers for WPF and WinForms, too)? ... and the .NET MAUI topic will be deleted and redirected to the "Integrate with native UI" topic over here?

WRT the unblocked dotnet/docs-maui#281 ...

There's no topic in this tracking issue for the subject of error handling/error processing. The PU remarks seem to indicate that such a topic would be added to the list of topics to write for this doc set. Should the .NET MAUI repo unblocked issue should be moved over here?

[danroth27]

Where is BlazorWebView is going to be covered? Is it supposed to be part of the upcoming topic "Integrate with native UI" (aspnetcore/blazor/hybrid/integrate-with-native-ui.md)? ... to then be THE platform-agnostic place for coverage (covers for WPF and WinForms, too)? ... and the .NET MAUI topic will be deleted and redirected to the "Integrate with native UI" topic over here?

The high level concept of using a BlazorWebView to build a Blazor Hybrid app should be covered in the Blazor Hybrid Overview and in the Blazor hosting models topic. The individual BlazorWebView controls for .NET MAUI, WPF, and Windows Forms will get covered in the onboarding tutorials and through API docs. The .NET MAUI BlazorWebView ships as part of .NET MAUI and is documented along with the other MAUI controls. This topic has a bunch of overlapping content with the Blazor Hybrid docs that we can replaced with links to the Blazor Hybrid Overview and .NET MAUI Blazor onboarding tutorial. The "Integrate with native UI" topic was intended specifically for discussing how you can use a BlazorWebView alongside other native UI.

I'm not sure what doc content is needed for dotnet/docs-maui#281. I've reached out to @TanayParikh
to get more clarity on that.