Static files overhaul

[guardrex]

Fixes #35810
Fixes #35833

After Javier technical review, I'll ping Wade and Tom.

Notes

• Let's combine articles. IMO, it's kind'a scatter-🧠 to have two static files articles.
• 'Look ma! No broken links!' 😆 Let's drop the horribad INCLUDES versioning for two great outcomes ...
  • Links aren't broken in prior-version content.
  • The team and community are prevented from only updating the latest version of the article. That will still be a problem if we ever go to group-topic versioning (aka "Version-by-file"), but I don't think that's ever going to happen. If we're on the current versioning model forever, this approach stops the poor practice of only making bug fixes to the latest release content (i.e., INCLUDES files are routinely ignored for bug and enhancement updates).
• Let's move the samples into the dotnet/AspNetCore.Docs.Samples repo. The sample apps were placed in that repo on Add static files sample apps AspNetCore.Docs.Samples#282. I'll delete them from this repo on this PR after reviews to avoid cluttering the diff.
• We're still running with the separate Blazor Static Files article with Blazor-focused scenarios. Dan, I can move that content (or selected bits of it) into this article if you want. 👂

---

Internal previews

📄 File	🔗 Preview link
aspnetcore/blazor/fundamentals/environments.md	aspnetcore/blazor/fundamentals/environments
aspnetcore/blazor/fundamentals/static-files.md	aspnetcore/blazor/fundamentals/static-files
aspnetcore/fundamentals/static-files.md	aspnetcore/fundamentals/static-files
aspnetcore/migration/50-to-60-samples.md	aspnetcore/migration/50-to-60-samples
aspnetcore/migration/70-80.md	aspnetcore/migration/70-80
aspnetcore/toc.yml	aspnetcore/toc

[danroth27]

Isn't the guidance the same? Can we remove this duplication?

[guardrex]

That's what I meant about deltas. It wasn't the same IIRC, but I'll have to look. I'll check and get back to you ... probably Tuesday morning.

[guardrex]

Removed my last response. I was incorrect about what happened.

A dev had a problem getting our main doc set guidance with the composite file provider to work in a BWA with two physical file providers (which BTW works for Blazor Server, just not BWAs) ...

#32891

I asked the dev to open a PU issue to see what we needed to do for BWAs ...

#32895

However, the issue was transferred to the docs repo without comment. I closed the transferred issue to work from the original docs issue (32891).

I presumed that what the dev did to solve the problem was a valid approach, so that's what's in the section. Instead of using two physical file providers in a composite file provider, the Blazor content pitches passing app.Environment.WebRootFileProvider as the primary provider ...

var secondaryProvider = new PhysicalFileProvider(
    Path.Combine(builder.Environment.ContentRootPath, "AdditionalStaticAssets"));
app.Environment.WebRootFileProvider = new CompositeFileProvider(
    app.Environment.WebRootFileProvider, secondaryProvider);

So, we still don't have an "official" Javier ruling 👨‍⚖️😄 on this delta (two physical providers in a composite doesn't work in a BWA). I'll leave the current coverage as it is for now, and then we can see on technical review what to do about BWA coverage for serving files from multiple locations.

[Note in passing that what I said in my stricken comment about the main doc set's section partially focusing the Image Tag Helper in this scenario is true. When I added the Blazor article coverage, I stripped that language out, so the Blazor article section may or may not be the right pitch on how to address the multiple locations scenario for BWAs, but it is better tailored to BWAs without the Tag Helper remarks. That's something that I'd try to address in the main doc set if we shed the Blazor article section after hearing back from Javier.]

Here are the two live sections for further analysis on their deltas to see if we should try combining them in the main doc set article ...

• Main doc set: Serve files from multiple locations
• Blazor doc set: Serve files from multiple locations

[danroth27]

OK. I'm going to assume the differences in this content for handling static files from multiple locations in Blazor Web Apps is correct then unless @javiercn states otherwise.

[danroth27]

@javiercn Is there more we should say about the default media type mapping for static web assets and how it can be configured?

[javiercn]

Yes, I included a section about that in my original technical description. it should be covered here if it's not covered later in the document. At leas a note/link here to where it can be configured later.

[guardrex]

I'm only going by what's here, so I need to understand where the original technical description is in order to add content ... or the content, possibly as just notes, has to be provided to me.

[danroth27]

The overall structure looks good to me. There is a fair bit of technical details that we'll need @javiercn to review.

Currently, I'm wondering why any fundamental coverage (or host/deploy ... or security) is covered in the Blazor node, given Blazor's preeminent position.

Yup, I agree we should look at what Blazor fundamentals content should really be in the top-level fundamentals docs. Let's just be careful not to overwhelm the top-level ASP.NET Core fundamentals docs with too many Blazor-specific details. We need the fundamental concepts of ASP.NET Core to be simple and straightforward.

I think it should be "Static File Middleware," not "Files" (plural). The API isn't plural.

Sounds good to me 👍

[guardrex]

This PR is ready for @javiercn's technical review.

[javiercn]

We should remove this property, I missed it when I created the list, it should not be here.

[javiercn]

This should ideally be on its own section as Customizing compression options and providing examples.

[javiercn]

This should be covered under a section about "adding new content type mappings at build time"

[guardrex]

I placed everything that you provided in dotnet/aspnetcore#63292. I need content or a link to additional information if I'm going to write it up (and note that @danroth27 asked me not to write up new features; leave it to the PU he instructed).

Also, I placed this section on MSBuild properties without versioning any of them. They don't all go back to 3.1, so I leave it to you guys to decide if versioning is something you want to get into the weeds with. If several came in at various times (and because I can't version individual rows of tables), this could get messy fast.

If you want to version without markdown versioning, then a table column can indicate the release that the property appeared.

[danroth27]

@guardrex @javiercn I've opened dotnet/aspnetcore#63698 to track providing the requested content. Let's merge this PR as is and add the content type mapping section separately.

[guardrex]

Ok ... I have one more pass to get the sample app out of here. It's in the samples repo now. I didn't do it yet because I didn't want to clutter the diff. I'll take care of it by EOD.

[javiercn]

<ItemGroup>
    <StaticWebAssetContentTypeMapping Include="image/bmp" Cache="<<Cache-Header-To-Use-For-Non-Fingerprinted-Endpoints>>" Pattern="*.bmp" />
</ItemGroup>

[javiercn]

Few comments, otherwise looks good.

[guardrex]

@danroth27 ... Ok, those two are done, and the samples are now only in the samples repo, not here.

I think we're good 👍. I'll see it live tomorrow morning and look for any lingering 😈.