Blazor Hybrid Static Files topic

[guardrex]

Fixes #25674

Internal Review Topic

Notes ...

• Rather rough at the moment 🚧👷. I'll 🛌💤 on it tonight with a round of updates on Thursday morning. You can review it now tho if you want. It's ready for review.
• I put the component-only static asset web root approach (wwwroot) on here in a section at the end because I wonder if a Hybrid app that only uses components can rely upon the Blazor-y-ish™ way of hosting and referencing static assets, not getting into additional complexity with localized resources (i.e., Resource Manager). I was able to get it working on Windows for MAUI, WPF, and WinForms. Idk about perf, security, or platform/OS problems that might crop up with it. If InSaNe 😵, I'll pull it off the PR ... and we'll never mention that these RexHax™ ever happened! 😆
• Later, I'm probably going to use pivots to shield readers from frameworks that they aren't working in.
• These cross-references don't seem ideal, but they are on the PR for .NET MAUI ...
  • Improve consistency with resizetizer maui#4367 is a GH PR ... definitely not a good form of documentation.
  • https://docs.microsoft.com/dotnet/maui/fundamentals/single-project probably isn't updated with the latest bits that the PR addresses ... but IDK if that's correct, just guessing at this point.
• Tanay to review first. After Tanay's signoff, I'll ping DR and Artak.

[TanayParikh]

• Improve consistency with resizetizer maui#4367 is a GH PR ... definitely not a good form of documentation.

💯 , I was hoping eventually we may get .NET MAUI docs covering MauiAsset. cc/ @mattleibow is anything planned in this area?

[mattleibow]

@davidbritch do we have docs on MauiAsset? I recall I saw some, but it may be in the review stuff still?

[TanayParikh]

Thanks @guardrex!

[guardrex]

That's good if that's all you spotted. I'll take care of these updates on Friday morning, edit the whole thing again, and ping u back.

[guardrex]

@TanayParikh ... I addressed your feedback and found several other nits and bits to update. You might be able to just look at the last commit to speed up your review of the changes ...

8a1da5e

For ".NET MAUI Essentials," it looks like we'll need to link to the blog post for the time being. I only do it once on the first mention at the top of the doc. Later, I'll point that link at a formal doc in the MAUI doc set.

After you see this and provide any additional feedback, I'll ping DR and Artak to look.

[davidbritch]

@guardrex The "Essentials" docs will be live on Monday. I can provide an URL if required.

[guardrex]

Thanks @davidbritch ... Yes, please. I think we can hold this until Monday. It might not even be likely for Dan and/or Artak to see this by then anyway.

[davidbritch]

@guardrex There's no root URL for Essentials, because there's no concept of Essentials in MAUI. It's all just functionality that's in MAUI. Do you want to link to a specific doc?

[guardrex]

The following lines refer to ".NET MAUI Essentials."

• If the general phrasing is incorrect, let's fix it.
• If ".NET MAUI Essentials" is retained anywhere here, we can link the text to something ... or not ... whatever makes sense.

btw - I'm mostly a web dev coming into desktop/mobile subjects. I'm learning as we go 👨‍🏫.

In a Blazor Hybrid app, static files are *app resources*, accessed by Razor components using the following approaches:

• [.NET MAUI](#net-maui): [:::no-loc text=".NET MAUI Essentials":::](https://devblogs.microsoft.com/xamarin/xamarin-essentials-1-7-and-introducing-net-maui-essentials/#net-maui-essentials)
• ...

... and ...

In .NET MAUI apps, [raw assets](/dotnet/maui/fundamentals/single-project#raw-assets) using the `MauiAsset` build action and :::no-loc text=".NET MAUI Essentials"::: are used for static assets.

... and ...

In a Razor component:

• The static text file contents can be read using the following techniques:
  • .NET MAUI: :::no-loc text=".NET MAUI Essentials"::: (Microsoft.Maui.Storage.FileSystem.OpenAppPackageFileAsync)
  • ...
• ...

[guardrex]

It might make sense to change ".NET MAUI Essentials" to ".NET MAUI framework" or similar lingo ... and not link it.

[davidbritch]

Yes, there's no concept of ".NET MAUI Essentials". We still call it Essentials internally, but it's no longer a brand, and the functionality that was in the Xamarin.Essentials namespace is now split over multiple Microsoft.Maui.* namespaces (e.g. Microsoft.Maui.Devices, Microsoft.Maui.ApplicationModel etc.). What was .NET MAUI Essentials is now just .NET MAUI.

The blog link can be replaced with /dotnet/maui/platform-integration/storage/file-system-helpers. If you have access to the review site you can see it at https://review.docs.microsoft.com/en-us/dotnet/maui/platform-integration/storage/file-system-helpers?branch=pr-en-us-536&tabs=android

[guardrex]

Should I change the text (for that cross-link) to ".NET MAUI File System Helpers"?

UPDATE: I'll compose it that way for the next commit, and we can further modify/replace it from there.

btw ... No, I can't get internal builds. We can set that up at any time but decided not to bother with it. It's more trouble than it's worth to deal with the red tape.

UPDATE: Marking as DRAFT to make sure that this doesn't get merged until the cross-linked content goes live on Monday.

[guardrex]

btw @davidbritch in case ur wondering about the no-loc entries ...

We devised an approach to supply a global no-loc via fileMetadata in the docfx.json file. We haven't implemented it yet. For now, I'm going to lock them out of loc this way. Later, the no-loc markdown will be removed.

[TanayParikh]

Content LGTM, thanks @guardrex!

[guardrex]

The cross-link to ...

https://docs.microsoft.com/dotnet/maui/platform-integration/storage/file-system-helpers

... is LIVE. Taking this off of its HOLD/DRAFT status.