[11.0 P6] Blazor Preview 6 coverage

[guardrex]

Addresses #37274

The following is on this PR:

• C# unions coverage for Blazor
• Rename EnvironmentBoundary component to EnvironmentView component
• Rename NavigationManager.GetUriWithHash to NavigationManager.GetUriWithFragment
• Rename DisableDomPreservation to PreserveDom ... BUT note that we don't have coverage anywhere for the rest of the mentioned browser options changes. The following are NOT currently covered ...
  • WithBrowserConfiguration is now WithBrowserOptions
  • BrowserConfiguration is now BrowserOptions
  • ServerBrowserOptions is now InteractiveServerBrowserOptions
  • CircuitInactivityTimeoutMs is now CircuitInactivityTimeout (a TimeSpan)
• Fix TempData and SupplyParameterFromSession persistence for streaming SSR case: Only the Behavior Change to Call Out section has been placed into the What's New remarks with a cross-link to the PU PR (and a note not to comment on closed issues/PRs).
• The Virtualize component is now CSP-compliant.
• Redundant app.UseAntiforgery() removed from Blazor Web templates: I placed a brief remark cross-linked to the new migration article.
• CSRF Protection Middleware coverage in the Blazor node. Please scroll down! There are comments/questions in a separate comment below.

To do (I'll take care of these prior to P6 release) ...

• Cross-link What's New blurb for Virtualize component features to the reference coverage on it, which is on a different PR.

Not covered ...

• Added annotation for execution of RenderFragments during serialization ... Do we at least need a little bit on the new [SerializationExecutionPolicy] attribute for RenderFragment parameters. If so, may I have content or some content scope suggestions from the PR?
• Blazor Hybrid @rendermode no longer throws in WebView. I didn't cover it because it's a bug fix, but I certainly will drop something in on it if you like.

Dan ... Prelim remarks and then a question on the introductory union coverage in the Components overview article ...

Prelim

• You requested something short, leaving detail to the C# reference, but I'd like to pitch examples that appeal to my inclination to provide a fully working, cut-'n-paste examples that cover a couple of bases, namely ...

  • A C# switch-ed RenderFragment for rendering.
  • An inline Razor syntax switch-ed SlotContent approach for rendering.

  I'll shorten the examples to your liking.

• The DynamicComponent presentation explains out the boxing requirement with a fully (not 😄) working unboxed case before presenting the correct coding approach. Overkill? Maybe. Let me know if you want that to only show the working approach with merely a passing remark on the boxing requirement.

• The links used earlier were to the What's New content on unions; but for reference content, we should link the C# reference, which is available now ...

  https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/union

  I leave the What's New link in our What's New coverage (and I place Bill's blog link temporarily in the reference content), but I add the C# reference link to that coverage on this PR. BTW ... that C# What's New link is pointing to the wrong page. It was going to C# 14 content, but I fix that here, too.

❓ Question ❓

Currently, the Components overview article example assigns a C#-built RenderFragment, which works 🎉 ...

<Slot Content="@content" />

@code {
    private SlotContent content;

    protected override void OnInitialized()
    {
        content = new SlotContent((RenderFragment)(b =>
        {
            ...
        }));
    }

...
}

However, I was expecting (hoping for) a Razor markup approach to work ...

<Slot>
    <button @onclick="Increment">@currentCount</button>
</Slot>

... but I couldn't get that to work (even if I named the SlotContent type in the Slot component to "ChildContent").

If there's a Razor markup way to pass that SlotContent, I think we should show it. If it can't be done, then perhaps we should warn devs off of trying it. Otherwise, some folks will probably waste a lot of time trying to get it to work.

---

Internal previews

Toggle expand/collapse

📄 File	🔗 Preview link
aspnetcore/blazor/components/dynamiccomponent.md	aspnetcore/blazor/components/dynamiccomponent
aspnetcore/blazor/components/index.md	aspnetcore/blazor/components/index
aspnetcore/blazor/components/virtualization.md	aspnetcore/blazor/components/virtualization
aspnetcore/blazor/forms/index.md	aspnetcore/blazor/forms/index
aspnetcore/blazor/fundamentals/environments.md	aspnetcore/blazor/fundamentals/environments
aspnetcore/blazor/fundamentals/navigation.md	aspnetcore/blazor/fundamentals/navigation
aspnetcore/blazor/fundamentals/routing.md	aspnetcore/blazor/fundamentals/routing
aspnetcore/blazor/fundamentals/startup.md	aspnetcore/blazor/fundamentals/startup
aspnetcore/blazor/fundamentals/static-files.md	aspnetcore/blazor/fundamentals/static-files
aspnetcore/blazor/javascript-interoperability/call-dotnet-from-javascript.md	aspnetcore/blazor/javascript-interoperability/call-dotnet-from-javascript
aspnetcore/blazor/javascript-interoperability/call-javascript-from-dotnet.md	aspnetcore/blazor/javascript-interoperability/call-javascript-from-dotnet
aspnetcore/blazor/security/index.md	aspnetcore/blazor/security/index
aspnetcore/blazor/state-management/prerendered-state-persistence.md	aspnetcore/blazor/state-management/prerendered-state-persistence
aspnetcore/breaking-changes/11/blazor-enhanced-nav-preloading-disabled.md	aspnetcore/breaking-changes/11/blazor-enhanced-nav-preloading-disabled
aspnetcore/fundamentals/middleware/request-decompression.md	aspnetcore/fundamentals/middleware/request-decompression
aspnetcore/fundamentals/url-rewriting.md	aspnetcore/fundamentals/url-rewriting
aspnetcore/mvc/models/model-binding.md	aspnetcore/mvc/models/model-binding
aspnetcore/performance/response-compression.md	aspnetcore/performance/response-compression
aspnetcore/security/authentication/configure-jwt-bearer-authentication.md	aspnetcore/security/authentication/configure-jwt-bearer-authentication
aspnetcore/signalr/hubs.md	aspnetcore/signalr/hubs

[Copilot]

Pull request overview

Updates ASP.NET Core documentation for .NET 11 Preview 6, focusing on C# union types coverage across Blazor, SignalR, MVC, and Minimal APIs, and aligning union-type links with current C# reference material.

Changes:

• Update several union-type references to point to the C# union type language reference.
• Add/expand Blazor guidance for union types (component parameters, DynamicComponent boxing, JS interop support note, and a PCS/serialization caveat).
• Refresh article metadata dates where substantial content was added/updated.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
aspnetcore/signalr/hubs.md	Updates the union types link used in the SignalR JsonHubProtocol note.
aspnetcore/release-notes/aspnetcore-11/includes/csharp-unions-preview-6.md	Adds a language-reference cross-link for union types in the .NET 11 Preview 6 release notes include.
aspnetcore/mvc/models/model-binding.md	Updates union types link in the model-binding note about [FromBody] support.
aspnetcore/fundamentals/minimal-apis/includes/parameter-binding8-10.md	Updates union types link in Minimal API parameter binding note.
aspnetcore/blazor/state-management/prerendered-state-persistence.md	Adds a .NET 11 note about JsonSerializerContext not flowing into union deserialization; updates metadata date.
aspnetcore/blazor/javascript-interoperability/call-javascript-from-dotnet.md	Adds a .NET 11 note that union types are supported; updates metadata date.
aspnetcore/blazor/javascript-interoperability/call-dotnet-from-javascript.md	Adds a .NET 11 note that union types are supported; updates metadata date.
aspnetcore/blazor/fundamentals/routing.md	Updates union types link in the note about route parameters not supporting unions.
aspnetcore/blazor/fundamentals/navigation.md	Updates union types link in the note about [SupplyParameterFromQuery]/[SupplyParameterFromForm] not supporting unions.
aspnetcore/blazor/components/index.md	Adds union-typed component parameter guidance + examples and updates metadata (including ai-usage).
aspnetcore/blazor/components/dynamiccomponent.md	Adds guidance and examples for boxing union-typed parameters passed via DynamicComponent dictionaries; updates metadata date.

[wadepickett]

@guardrex, just a heads up I will be unavailable from 7/10 Friday (tomorrow), all through next week until 7/21. So look to @tdykstra for any reviews you need here or on the samples repo, etc. @tdykstra is also handling the What's New. I'll start a draft today but he will be responsible for updates to keep in sync with any release note updates.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 6 comments.

[guardrex]

I'm only focusing the Blazor updates that pertain to automatic CSRF middleware on the Blazor articles. I have a couple of questions and observations on the new CSRF Protection Middleware coverage.

Note that I'm going by conventions that were established years ago for the repo, but those conventions might have been dropped. I hope to get some clarity on that subject separately later. Anyway ........

1. Middlewares are treated as proper nouns when referred to by name. However, the articles frequently refer to "antiforgery middleware." If the convention is still in effect, it should be capitalized as "Antiforgery Middleware." For the new CSRF middleware, it should also appear as a proper noun, perhaps "CSRF Protection Middleware."

   Opened Drop proper noun status for middleware references across the doc set #37345 ... but I recommend that we don't do it! 😄

2. Much of the language referring to Blazor scenarios speak to "static server-side rendering," which should have been abbreviated as "static SSR." Sometimes, the text only states "server-side rendering." There are also mentions of "Blazor SSR apps" without using the word "static." The coverage is a bit confusing because plain use of "server-side rendering" also includes interactive server-side rendering. The Blazor docs are careful to use ...

   • "Server-side rendering (SSR)" to mean either static or interactive SSR.
   • "Static server-side rendering (static SSR)" for static SSR.
   • "Interactive server-side rendering (interactive SSR)" for interactive SSR.

   I recommend using "static server-side rendering" ("static SSR" when abbreviated) everywhere that static SSR is the focus. Use "server-side rendering" (or "SSR") when there isn't a distinction for the type of SSR.

3. NIT ... The new CSRF article at https://learn.microsoft.com/aspnet/core/security/csrf-protection, titled Automatic CSRF protection in ASP.NET Core, breaks the reference article convention of avoiding referring to a specific version for versioned content in the reference article set (i.e., in the main doc set outside of What's New and Migration content).

4. Resolved

5. Resolved

6. Resolved

[danroth27]

Following up on the browser-options coverage: I confirmed the C# server-side WithBrowserOptions / BrowserOptions API isn't covered anywhere in the What's New content today (the includes only mention the client-side JS Blazor.start() format and the WASM IConfiguration env-var consumption). This is a real gap worth filling, since it's a user-facing feature and not just Aspire plumbing.

What it is: it configures client-side Blazor startup from the server in C# (client log level, interactive Server reconnection, SSR DOM preservation, and the WebAssembly environment name/culture/variables) instead of hand-writing Blazor.start JavaScript. The server serializes the options into the page and the Blazor script applies them across the Server, WebAssembly, and Auto render modes. Introduced in Preview 4 (server-to-browser config via the <!--Blazor-Configuration:--> comment) and reshaped in Preview 6 (dotnet/aspnetcore#67337, proposal dotnet/aspnetcore#66393).

We wrote it up for the Preview 6 release notes — see the "Configure Blazor client behavior from the server" section in dotnet/core#10455 (release-notes/11.0/preview/preview6/aspnetcore.md). Feel free to use that as a starting point for a What's New section. It pairs naturally with the existing "Environment variables in Blazor WebAssembly configuration" section, which is the client-side consumer of what WithBrowserOptions.WebAssembly.EnvironmentVariables sets on the server.

Example:

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode()
    .WithBrowserOptions(options =>
    {
        options.LogLevel = LogLevel.Warning;
        options.Server.ReconnectionMaxRetries = 10;
        options.Ssr.PreserveDom = true;
        options.WebAssembly.EnvironmentVariables["OTEL_EXPORTER_OTLP_ENDPOINT"] = "https://localhost:4318";
    });

You can also set these from a component with <ConfigureBrowser>, or read them via HttpContext.GetBrowserOptions().

[guardrex]

@danroth27 ... I'll take the release notes and apply some updates for the ASP.NET Core What's New content. I'll try to add reference coverage now, but this is arriving to me rather late in the game. I might need to add the reference coverage on a different PR later today.

UPDATE: Yes, let me try to resolve the reference article coverage by EOD (UPDATE: by EOD Wednesday b/c we didn't get release coverage released on Tuesday) as opposed to by release in a few hours. I just placed the What's New coverage, so we'll have that for release. I'd like to get the other high priority coverage here fixed up for release first.

[danroth27]

A few answers on the open questions:

• [SerializationExecutionPolicy] (Added annotation for execution of RenderFragments during serialization aspnetcore#66894): let's not cover it for P6. That PR is still open and unmerged (conflicting, untouched since early June), so SerializationExecutionPolicyAttribute isn't in the Preview 6 build. We can document it once it merges and ships.
• Union SlotContent: let's hold off on the union child-content pattern for now. Populating a union-typed parameter via child-content markup (<Slot>...</Slot>) isn't supported today — Razor child content only binds to RenderFragment-typed parameters. I opened Support Razor child content for union-typed component parameters (RenderFragment case) razor#13200 to track it. Until that's fixed, let's not show the union SlotContent example (or show direct assignment only), so we don't send developers down a path that doesn't work.
• DynamicComponent boxing example: agreed it's overkill — let's drop the working-then-correct version and show only the correct approach with a brief note on the boxing requirement.

[guardrex]

• [SerializationExecutionPolicy] ... 👍 Gotcha!

• show direct assignment only ... 👍 Let me try with an explicit remark on unsupported-at-this-time child content. IMO, anyone reading about this is going to wonder about it ... and possibly try to make it work ... 🦖 did! 😄

• drop the working-then-correct version ... 👍 Done!

[guardrex]

We're in mostly good shape here.

I need to get the reference coverage for Configure Blazor client behavior from the server in place later today. We have it covered in What's New here for now.

I still need feedback on the CSRF Protection Middleware coverage. My remarks are above at ...

#37322 (comment)

[danroth27]

Thanks, @guardrex! Answers to your questions:

1. Let's not capitalize middleware names as proper nouns — keep "antiforgery middleware", "CSRF protection middleware", etc. lowercase.

2. Agreed — let's be clear about which kind of server-side rendering is meant: static, interactive, or both. Use "static SSR" / "interactive SSR" where the distinction matters, and plain "SSR" only when it doesn't.

3. Agreed that titles shouldn't state versions. More broadly, the CSRF docs need some refactoring and cleanup: let's consolidate the anti-CSRF coverage into a single article that leads with the new automatic CSRF protection, rather than keeping the auto-CSRF migration content in a separate article. I believe @DeagleGross is planning to take care of this.

4. Cross-links to the antiforgery coverage sound fine.

5. Let's not position the automatic CSRF protection as a breaking change. Removing app.UseAntiforgery() — as we did in the Blazor Web App template — shouldn't break anything: AddRazorComponents still registers the antiforgery services, and the auto-injected CSRF protection middleware provides the protection, so the app stays protected without the token middleware. (One accuracy note: AddRazorComponents registers the antiforgery services, not the UseAntiforgery() middleware, so "implicitly through AddRazorComponents" isn't accurate.) Please drop the breaking-change framing from the forms/security guidance.

[guardrex]

1. Cringeworthy! 😖😆 ... but ok ... will do! 👍 This convention has been applied across the doc set for as long as I can remember ... at least 5-6 years. For now, I can adjust it here, but it will take a larger effort to adjust it in ~88 other places around the repo. I opened Drop proper noun status for middleware references across the doc set #37345 to address it. Please reconsider. I think this is going to confuse (or at least slow down) readers.

2. I suggest that @DeagleGross make the adjustments, and I'll react in the Blazor node from there.

3. I thought you and he had a plan. 👍

4. Done! 👍 We're good. I provided the links on your release notes PR if you want to use them over there.

5. "AddRazorComponents still registers the antiforgery services" ... Ah, yes!

   (One accuracy note: AddRazorComponents registers the antiforgery services, not the UseAntiforgery() middleware, so "implicitly through AddRazorComponents" isn't accurate.)

   I recall it now. Done! 👍

   Please drop the breaking-change framing from the forms/security guidance.

   Done! 👍

[guardrex]

@tdykstra ... Pre6 is released now. Do you want to review? I don't have a sign-off on this yet, so I can't merge it. Are you planning on pulling the trigger on the merge-to-live (after this and the other PRs go in)? ... and note that the What's New article will need a date update to pull the INCLUDES. Nevermind on the date update on that PR, as I was able to commit it.

We need this merged first. Then, the other one. Then, merge to live.

[DeagleGross]

Hey, sorry for delay, I am going to post PRs with doc changes for CSRF today, and we can reroute to them from here. Indeed as @danroth27 mentioned i'll consolidate the anti-CSRF coverage into a single article that leads with the new automatic CSRF protection; and there will not be a separate migration-only article. I'll send links to the PR soon

[guardrex]

@DeagleGross ... Clarification: Do you want to merge the existing PRs first, or do you have a different plan? It sounds like you don't plan to merge the current PRs on CSRF.

I'd like to get this PR merged, and I think I have all of Dan's feedback covered. Can you give me a quick review of this (with feedback for changes if you have any) and an approval of this PR, especially the CSRF bits in the forms and security articles? If so, I can get this PR merged this morning. I need at least one approval to get this merged, and you can provide it (with my thanks! 😄). Then ... if you want to ... we can work to get other PRs merged (existing or new PRs) if Tom isn't available.

Note that I'll be out from 10:30 to 11:30am EST. I'll be here and available otherwise for most of the day.

[DeagleGross]

Approving for unions / csrf - proposed different structure for CSRF + antiforgery explanation

[DeagleGross]

Not sure what kind of info we need to put here, but maybe extend a bit with usage?

:::moniker range=">= aspnetcore-11.0"

Blazor apps are protected against Cross-Site Request Forgery (CSRF/XSRF) by two complementary mechanisms.

Automatic header-based CSRF protection middleware

Automatic CSRF protection middleware is enabled by default in apps built with WebApplication.CreateBuilder. The middleware inspects the Sec-Fetch-Site and Origin headers on unsafe HTTP methods and records a validation verdict on the request. Blazor server-side rendering (SSR) form posts enforce that verdict and return a 400 Bad Request response for cross-origin form posts that aren't trusted. No pipeline configuration is required to enable this protection.

Token-based antiforgery

Token-based antiforgery services are added to the app when xref:Microsoft.Extensions.DependencyInjection.RazorComponentsServiceCollectionExtensions.AddRazorComponents%2A is called in the Program file. However, token validation only runs when Antiforgery Middleware is explicitly added to the request processing pipeline by calling xref:Microsoft.AspNetCore.Builder.AntiforgeryApplicationBuilderExtensions.UseAntiforgery%2A.

How the two mechanisms interact

Adding token-based antiforgery doesn't replace the automatic header-based middleware. When an app calls xref:Microsoft.AspNetCore.Builder.AntiforgeryApplicationBuilderExtensions.UseAntiforgery%2A, both defense mechanisms run for a form post: the header-based CSRF protection middleware runs first and records its verdict, then Antiforgery Middleware performs token-based validation. The token-based result is authoritative and overrides the earlier header-based verdict.

To explicitly add Antiforgery Middleware, call xref:Microsoft.AspNetCore.Builder.AntiforgeryApplicationBuilderExtensions.UseAntiforgery%2A after the call to xref:Microsoft.AspNetCore.Builder.EndpointRoutingApplicationBuilderExtensions.UseRouting%2A. If there are calls to xref:Microsoft.AspNetCore.Builder.EndpointRoutingApplicationBuilderExtensions.UseRouting%2A and xref:Microsoft.AspNetCore.Builder.EndpointRoutingApplicationBuilderExtensions.UseEndpoints%2A, the call to xref:Microsoft.AspNetCore.Builder.AntiforgeryApplicationBuilderExtensions.UseAntiforgery%2A must go between them. A call to xref:Microsoft.AspNetCore.Builder.AntiforgeryApplicationBuilderExtensions.UseAntiforgery%2A must be placed after calls to xref:Microsoft.AspNetCore.Builder.AuthAppBuilderExtensions.UseAuthentication%2A and xref:Microsoft.AspNetCore.Builder.AuthorizationAppBuilderExtensions.UseAuthorization%2A.

Disable the automatic CSRF protection middleware

To disable the automatic header-based CSRF protection middleware, set the DisableCsrfProtection configuration key to true. For example, in appsettings.json:

{
  "DisableCsrfProtection": true
}

The setting can be supplied by any configuration source, including an environment variable (DisableCsrfProtection=true).

Warning

Disabling the automatic CSRF protection middleware removes the default header-based (Sec-Fetch-Site/Origin) protection for the entire app. Only disable it if you provide an alternative CSRF defense, such as explicitly adopting token-based Antiforgery Middleware with xref:Microsoft.AspNetCore.Builder.AntiforgeryApplicationBuilderExtensions.UseAntiforgery%2A.

For more information, see xref:security/csrf-protection.

Important

The following guidance on the xref:Microsoft.AspNetCore.Components.Forms.AntiforgeryToken component and the xref:Microsoft.AspNetCore.Components.Forms.AntiforgeryStateProvider service only apply to an app that explicitly adopts token-based Antiforgery Middleware by calling xref:Microsoft.AspNetCore.Builder.AntiforgeryApplicationBuilderExtensions.UseAntiforgery%2A in its request processing pipeline.

:::moniker-end

[DeagleGross]

@guardrex I'll work on #37329 to merge, but it will refactored differently. I'll remove a separate "migration" article and we'll have one big article explaining CSRF (with relation to Antiforgery), and another will be net10 -> net11 migration doc, where we'll inline migration recommendations.

I have approved PR, proposing change to CSRF - but you know the doc purpose better so its OK as it is.

[guardrex]

Thanks, @DeagleGross! I'll work that into the Blazor node forms and security coverage before merging this shortly. I won't touch anything else, so this PR shouldn't create merge conflicts with anything that you're working on today.

Otherwise, I'll be around outside of 10:30-11:30 EST, but @tdykstra is taking the lead on getting everything else into place AFAIK. However, I can help where needed.

Note to @tdykstra that this should go in first ... I'll have it done and merged within an hour ... and then the Blazor INCLUDES file will get sucked into the other PR when it builds. This PR doesn't touch the main What's New ms.date, so it won't get included until the other PR is merged.

[guardrex]

I rolled in all of your new remarks from above.

I'm going to edit and improve this coverage further on a future preview/RC PR. I'd like to see what the release CSRF docs in the main doc set cover after you're done. Ideally, the Blazor node should link out for all of this coverage. I think that I'll be able to shed quite a bit of what I'm adding here.

If you get build report warnings on your PR(s), they will probably be for cross-links from this. I'm cross-linking the breaking change announcement for Blazor static SSR and the CSRF article. I think the links will change, so you'll just update the cross-links in these Blazor articles when you set up your new PR. The build report should flag them for you. Ping me if you need help with it. I'll get back to you as soon as I can.

[guardrex]

@DeagleGross ... Can you give me one more approval? 😩

The new rules require it because I just made changes. [These new rules SUCK!!!! 😆]

Review from DeagleGross is stale because it was submitted before the most recent code changes.