Merge pull request #34752 from dotnet/main

Rick-Anderson · web-flow · commit 92712529cc8d · 2025-02-18T13:17:41.000-10:00
Merge to Live
diff --git a/aspnetcore/blazor/call-web-api.md b/aspnetcore/blazor/call-web-api.md
@@ -379,7 +379,7 @@ The preceding example sets the base address with `builder.HostEnvironment.BaseAd
 The most common use cases for using the client's own base address are:
 
 * The client project (`.Client`) of a Blazor Web App (.NET 8 or later) makes web API calls from WebAssembly components or code that runs on the client in WebAssembly to APIs in the server app.
-* The client project (**:::no-loc text="Client":::**) of a hosted Blazor WebAssembly app makes web API calls to the server project (**:::no-loc text="Server":::**). Note that the hosted Blazor WebAssembly project template is no longer available in .NET 8 or later. However, hosted Blazor WebAssembly apps remain supported for .NET 8.
+* The client project (**:::no-loc text="Client":::**) of a hosted Blazor WebAssembly app makes web API calls to the server project (**:::no-loc text="Server":::**). Note that the Hosted Blazor WebAssembly project template is no longer available in .NET 8 or later. However, hosted Blazor WebAssembly apps remain supported for .NET 8.
 
 If you're calling an external web API (not in the same URL space as the client app), set the URI to the web API's base address. The following example sets the base address of the web API to `https://localhost:5001`, where a separate web API app is running and ready to respond to requests from the client app:
 
diff --git a/aspnetcore/blazor/fundamentals/environments.md b/aspnetcore/blazor/fundamentals/environments.md
@@ -115,7 +115,7 @@ Using the `environment` property overrides the environment set by the [`Blazor-E
 
 The preceding approach sets the client's environment without changing the `Blazor-Environment` header's value, nor does it change the server project's console logging of the startup environment for a Blazor Web App that has adopted global Interactive WebAssembly rendering.
 
-To log the environment to the console in either a standalone Blazor WebAssembly project or the `.Client` project of a Blazor Web App, place the following C# code in the `Program` file after the <xref:Microsoft.AspNetCore.Components.WebAssembly.Hosting.WebAssemblyHost> is created with <xref:Microsoft.AspNetCore.Components.WebAssembly.Hosting.WebAssemblyHostBuilder.CreateDefault%2A?displayProperty=nameWithType> and before the line that builds and runs the project (`await builder.Build().RunAsync();`):
+To log the environment to the console in either a standalone Blazor WebAssembly app or the `.Client` project of a Blazor Web App, place the following C# code in the `Program` file after the <xref:Microsoft.AspNetCore.Components.WebAssembly.Hosting.WebAssemblyHost> is created with <xref:Microsoft.AspNetCore.Components.WebAssembly.Hosting.WebAssemblyHostBuilder.CreateDefault%2A?displayProperty=nameWithType> and before the line that builds and runs the project (`await builder.Build().RunAsync();`):
 
 ```csharp
 Console.WriteLine(
diff --git a/aspnetcore/blazor/host-and-deploy/configure-trimmer.md b/aspnetcore/blazor/host-and-deploy/configure-trimmer.md
@@ -16,8 +16,6 @@ This article explains how to control the Intermediate Language (IL) Trimmer when
 
 Blazor WebAssembly performs [Intermediate Language (IL)](/dotnet/standard/glossary#il) trimming to reduce the size of the published output. Trimming occurs when publishing an app.
 
-Trimming may have detrimental effects for the published app. In apps that use [reflection](/dotnet/csharp/advanced-topics/reflection-and-attributes/), the IL Trimmer often can't determine the required types for runtime reflection and trim them away. For example, complex framework types for JS interop, such as <xref:System.Collections.Generic.KeyValuePair>, might be trimmed and not available at runtime for JS interop calls. In these cases, we recommend creating your own custom types instead. The IL Trimmer is also unable to react to an app's dynamic behavior at runtime. To ensure the trimmed app works correctly once deployed, test published output frequently while developing.
-
 ## Configuration
 
 To configure the IL Trimmer, see the [Trimming options](/dotnet/core/deploying/trimming/trimming-options) article in the .NET Fundamentals documentation, which includes guidance on the following subjects:
@@ -42,6 +40,141 @@ The default trimmer granularity for Blazor apps is `partial`. To trim all assemb
 
 For more information, see [Trimming options (.NET documentation)](/dotnet/core/deploying/trimming/trimming-options#trimming-granularity).
 
+## Failure to preserve types used by a published app
+
+Trimming may have detrimental effects for a published app leading to runtime errors. In apps that use [reflection](/dotnet/csharp/advanced-topics/reflection-and-attributes/), the IL Trimmer often can't determine the required types for runtime reflection and trims them away or trims away parameter names from methods. This can happen with complex framework types used for JS interop, JSON serialization/deserialization, and other operations.
+
+The IL Trimmer is also unable to react to an app's dynamic behavior at runtime. To ensure the trimmed app works correctly once deployed, test published output frequently while developing.
+
+Consider the following client-side component in a Blazor Web App (ASP.NET Core 8.0 or later) that deserializes a <xref:System.Collections.Generic.KeyValuePair> collection (`List<KeyValuePair<string, string>>`):
+
+```razor
+@rendermode @(new InteractiveWebAssemblyRenderMode(false))
+@using System.Diagnostics.CodeAnalysis
+@using System.Text.Json
+
+<dl>
+    @foreach (var item in @items)
+    {
+        <dt>@item.Key</dt>
+        <dd>@item.Value</dd>
+    }
+</dl>
+
+@code {
+    private List<KeyValuePair<string, string>> items = [];
+
+    [StringSyntax(StringSyntaxAttribute.Json)]
+    private const string data =
+        """[{"key":"key 1","value":"value 1"},{"key":"key 2","value":"value 2"}]""";
+
+    protected override void OnInitialized()
+    {
+        JsonSerializerOptions options = new() { PropertyNameCaseInsensitive = true };
+
+        items = JsonSerializer
+            .Deserialize<List<KeyValuePair<string, string>>>(data, options)!;
+    }
+}
+```
+
+The preceding component executes normally when the app is run locally and produces the following rendered definition list (`<dl>`):
+
+> **:::no-loc text="key 1":::**  
+> :::no-loc text="value 1":::  
+> **:::no-loc text="key 2":::**  
+> :::no-loc text="value 2":::
+
+When the app is published, <xref:System.Collections.Generic.KeyValuePair> is trimmed from the app, even in spite of setting the [`<PublishTrimmed>` property](#configuration) to `false` in the project file. Accessing the component throws the following exception:
+
+> :::no-loc text="Unhandled exception rendering component: ConstructorContainsNullParameterNames, System.Collections.Generic.KeyValuePair`2[System.String,System.String]":::
+
+To address lost types, consider the following approaches.
+
+### Preserve the type as a dynamic dependency
+
+We recommend creating a dynamic dependency to preserve the type with the [`[DynamicDependency]` attribute](xref:System.Diagnostics.CodeAnalysis.DynamicDependencyAttribute).
+
+If not already present, add an `@using` directive for <xref:System.Diagnostics.CodeAnalysis?displayProperty=fullName>:
+
+```razor
+@using System.Diagnostics.CodeAnalysis
+```
+
+Add a [`[DynamicDependency]` attribute](xref:System.Diagnostics.CodeAnalysis.DynamicDependencyAttribute) to preserve the <xref:System.Collections.Generic.KeyValuePair>:
+
+```diff
++ [DynamicDependency(DynamicallyAccessedMemberTypes.PublicConstructors, typeof(KeyValuePair<string, string>))]
+private List<KeyValuePair<string, string>> items = [];
+```
+
+<!-- UPDATE 10.0 - Hold this for https://github.com/dotnet/aspnetcore/issues/52947
+
+### Use a Root Descriptor
+
+A [Root Descriptor](/dotnet/core/deploying/trimming/trimming-options#root-descriptors) can preserve the type.
+
+Add an `ILLink.Descriptors.xml` file to the root of the app&dagger; with the type:
+
+```xml
+<linker>
+  <assembly fullname="System.Runtime">
+    <type fullname="System.Collections.Generic.KeyValuePair`2">
+      <method signature="System.Void .ctor(TKey,TValue)" />
+    </type>
+  </assembly>
+</linker>
+```
+
+&dagger;The root of the app refers to the root of the Blazor WebAssembly app or the root of the `.Client` project of a Blazor Web App (.NET 8 or later).
+
+Add a `TrimmerRootDescriptor` item to the app's project file&Dagger; referencing the `ILLink.Descriptors.xml` file:
+
+```xml
+<ItemGroup>
+  <TrimmerRootDescriptor Include="$(MSBuildThisFileDirectory)ILLink.Descriptors.xml" />
+</ItemGroup>
+```
+
+&Dagger;The project file is either the project file of the Blazor WebAssembly app or the project file of the `.Client` project of a Blazor Web App (.NET 8 or later).
+
+-->
+
+### Custom types
+
+<!-- UPDATE 10.0 - We'll hold this for when the file descriptor approach comes back.
+
+Custom types aren't trimmed by Blazor when an app is published, but we recommend [preserving types as dynamic dependencies](#preserve-the-type-as-a-dynamic-dependency) instead of creating custom types.
+
+-->
+
+The following modifications create a `StringKeyValuePair` type for use by the component.
+
+`StringKeyValuePair.cs`:
+
+```csharp
+[method: SetsRequiredMembers]
+public sealed class StringKeyValuePair(string key, string value)
+{
+    public required string Key { get; init; } = key;
+    public required string Value { get; init; } = value;
+}
+```
+
+The component is modified to use the `StringKeyValuePair` type:
+
+```diff
+- private List<KeyValuePair<string, string>> items = [];
++ private List<StringKeyValuePair> items = [];
+```
+
+```diff
+- items = JsonSerializer.Deserialize<List<KeyValuePair<string, string>>>(data, options)!;
++ items = JsonSerializer.Deserialize<List<StringKeyValuePair>>(data, options)!;
+```
+
+Because custom types are never trimmed by Blazor when an app is published, the component works as designed after the app is published.
+
 ## Additional resources
 
 * [Trim self-contained deployments and executables](/dotnet/core/deploying/trimming/trim-self-contained)
diff --git a/aspnetcore/blazor/javascript-interoperability/index.md b/aspnetcore/blazor/javascript-interoperability/index.md
@@ -201,7 +201,7 @@ Blazor uses <xref:System.Text.Json?displayProperty=fullName> for serialization w
 * Global default serialization isn't customizable to avoid breaking existing component libraries, impacts on performance and security, and reductions in reliability.
 * Serializing .NET member names results in lowercase JSON key names.
 * JSON is deserialized as <xref:System.Text.Json.JsonElement> C# instances, which permit mixed casing. Internal casting for assignment to C# model properties works as expected in spite of any case differences between JSON key names and C# property names.
-* Complex framework types, such as <xref:System.Collections.Generic.KeyValuePair>, might be [trimmed away by the IL Trimmer on publish](xref:blazor/host-and-deploy/configure-trimmer) and not present for JS interop. We recommend creating custom types for types that the IL Trimmer trims away.
+* Complex framework types, such as <xref:System.Collections.Generic.KeyValuePair>, might be [trimmed away by the IL Trimmer on publish](xref:blazor/host-and-deploy/configure-trimmer#failure-to-preserve-types-used-by-a-published-app) and not present for JS interop or JSON serialization/deserialization. We recommend creating custom types for types that the IL Trimmer trims away.
 * Blazor always relies on [reflection for JSON serialization](/dotnet/standard/serialization/system-text-json/reflection-vs-source-generation), including when using C# [source generation](/dotnet/csharp/roslyn-sdk/source-generators-overview). Setting `JsonSerializerIsReflectionEnabledByDefault` to `false` in the app's project file results in an error when serialization is attempted.
 
 <xref:System.Text.Json.Serialization.JsonConverter> API is available for custom serialization. Properties can be annotated with a [`[JsonConverter]` attribute](xref:System.Text.Json.Serialization.JsonConverterAttribute) to override default serialization for an existing data type.
diff --git a/aspnetcore/blazor/security/includes/hosted-blazor-webassembly-notice.md b/aspnetcore/blazor/security/includes/hosted-blazor-webassembly-notice.md
@@ -0,0 +1,2 @@
+> [!IMPORTANT]
+> The Hosted Blazor WebAssembly project template was removed from the framework with the release of .NET 8 (November, 2023). The guidance in this article is only supported for .NET 7 or earlier. Hosted Blazor WebAssembly apps that are upgraded each release continue to receive product support. Alternatively, refactor the app into either a standalone Blazor WebAssembly app or a Blazor Web App.
diff --git a/aspnetcore/blazor/security/webassembly/hosted-with-azure-active-directory-b2c.md b/aspnetcore/blazor/security/webassembly/hosted-with-azure-active-directory-b2c.md
@@ -10,6 +10,8 @@ uid: blazor/security/webassembly/hosted-with-azure-active-directory-b2c
 ---
 # Secure a hosted ASP.NET Core Blazor WebAssembly app with Azure Active Directory B2C
 
+[!INCLUDE[](~/blazor/security/includes/hosted-blazor-webassembly-notice.md)]
+
 This article explains how to create a [hosted Blazor WebAssembly solution](xref:blazor/hosting-models#blazor-webassembly) that uses [Azure Active Directory (AAD) B2C](/azure/active-directory-b2c/overview) for authentication.
 
 For additional security scenario coverage after reading this article, see <xref:blazor/security/webassembly/additional-scenarios>.
diff --git a/aspnetcore/blazor/security/webassembly/hosted-with-identity-server.md b/aspnetcore/blazor/security/webassembly/hosted-with-identity-server.md
@@ -10,6 +10,8 @@ uid: blazor/security/webassembly/hosted-with-identity-server
 ---
 # Secure a hosted ASP.NET Core Blazor WebAssembly app with Identity Server
 
+[!INCLUDE[](~/blazor/security/includes/hosted-blazor-webassembly-notice.md)]
+
 This article explains how to create a [hosted Blazor WebAssembly solution](xref:blazor/hosting-models#blazor-webassembly) that uses [Duende Identity Server](https://docs.duendesoftware.com) to authenticate users and API calls.
 
 :::moniker range=">= aspnetcore-6.0"
diff --git a/aspnetcore/blazor/security/webassembly/hosted-with-microsoft-entra-id.md b/aspnetcore/blazor/security/webassembly/hosted-with-microsoft-entra-id.md
@@ -10,6 +10,8 @@ uid: blazor/security/webassembly/hosted-with-microsoft-entra-id
 ---
 # Secure a hosted ASP.NET Core Blazor WebAssembly app with Microsoft Entra ID
 
+[!INCLUDE[](~/blazor/security/includes/hosted-blazor-webassembly-notice.md)]
+
 This article explains how to create a [hosted Blazor WebAssembly solution](xref:blazor/hosting-models#blazor-webassembly) that uses [Microsoft Entra ID (ME-ID)](https://azure.microsoft.com/services/active-directory/) for authentication. This article focuses on a single tenant app with a single tenant Azure app registration.
 
 This article doesn't cover a *multi-tenant ME-ID registration*. For more information, see [Making your application multi-tenant](/entra/identity-platform/howto-convert-app-to-be-multi-tenant).
diff --git a/aspnetcore/blazor/security/webassembly/microsoft-entra-id-groups-and-roles-net-5-to-7.md b/aspnetcore/blazor/security/webassembly/microsoft-entra-id-groups-and-roles-net-5-to-7.md
@@ -11,9 +11,11 @@ zone_pivot_groups: blazor-groups-and-roles
 ---
 # Microsoft Entra (ME-ID) groups, Administrator Roles, and App Roles (.NET 5 to .NET 7)
 
-> [!NOTE]
+> [!IMPORTANT]
 > This isn't the latest version of this article. For the current ASP.NET Core release, see the latest version of <xref:blazor/security/webassembly/meid-groups-roles>.
 
+[!INCLUDE[](~/blazor/security/includes/hosted-blazor-webassembly-notice.md)]
+
 This article explains how to configure Blazor WebAssembly to use Microsoft Entra ID groups and roles.
 
 Microsoft Entra (ME-ID) provides several authorization approaches that can be combined with ASP.NET Core Identity:
diff --git a/aspnetcore/blazor/tooling.md b/aspnetcore/blazor/tooling.md
@@ -65,7 +65,7 @@ Select **Next**.
 :::moniker range=">= aspnetcore-8.0"
 
   > [!NOTE]
-  > The hosted Blazor WebAssembly project template isn't available in ASP.NET Core 8.0 or later. To create a hosted Blazor WebAssembly app, a **Framework** option earlier than .NET 8.0 must be selected with the **ASP.NET Core Hosted** checkbox.
+  > The Hosted Blazor WebAssembly project template isn't available in ASP.NET Core 8.0 or later. To create a hosted Blazor WebAssembly app, a **Framework** option earlier than .NET 8.0 must be selected with the **ASP.NET Core Hosted** checkbox.
 
 :::moniker-end
 
@@ -329,7 +329,7 @@ Create a new project:
   ```
 
   > [!NOTE]
-  > The hosted Blazor WebAssembly project template isn't available in ASP.NET Core 8.0 or later. To create a hosted Blazor WebAssembly app using a .NET 8.0 or later SDK, pass the `-f|--framework` option with a 7.0 target framework (`net7.0`):
+  > The Hosted Blazor WebAssembly project template isn't available in ASP.NET Core 8.0 or later. To create a hosted Blazor WebAssembly app using a .NET 8.0 or later SDK, pass the `-f|--framework` option with a 7.0 target framework (`net7.0`):
   >
   > ```dotnet cli
   > dotnet new blazorwasm -o BlazorApp -ho -f net7.0
diff --git a/aspnetcore/fundamentals/servers/yarp/direct-forwarding.md b/aspnetcore/fundamentals/servers/yarp/direct-forwarding.md
@@ -134,29 +134,6 @@ internal class CustomTransformer : HttpTransformer
 }
 ```
 
-```C#
-private class CustomTransformer : HttpTransformer
-{
-    public override async ValueTask TransformRequestAsync(HttpContext httpContext,
-        HttpRequestMessage proxyRequest, string destinationPrefix, CancellationToken cancellationToken)
-    {
-        // Copy all request headers
-        await base.TransformRequestAsync(httpContext, proxyRequest, destinationPrefix, cancellationToken);
-
-        // Customize the query string:
-        var queryContext = new QueryTransformContext(httpContext.Request);
-        queryContext.Collection.Remove("param1");
-        queryContext.Collection["area"] = "xx2";
-
-        // Assign the custom uri. Be careful about extra slashes when concatenating here. RequestUtilities.MakeDestinationAddress is a safe default.
-        proxyRequest.RequestUri = RequestUtilities.MakeDestinationAddress("https://example.com", httpContext.Request.Path, queryContext.QueryString);
-
-        // Suppress the original request header, use the one from the destination Uri.
-        proxyRequest.Headers.Host = null;
-    }
-}
-```
-
 There are also [extension methods](xref:Microsoft.AspNetCore.Builder.DirectForwardingIEndpointRouteBuilderExtensions) available that simplify the mapping of IHttpForwarder to endpoints.
 
 ```C#
diff --git a/aspnetcore/release-notes/aspnetcore-10.0.md b/aspnetcore/release-notes/aspnetcore-10.0.md
@@ -47,4 +47,24 @@ This section describes miscellaneous new features in ASP.NET Core 10.0.
 
 [!INCLUDE[](~/release-notes/aspnetcore-10/includes/testAppsTopLevel.md)]
 
+### Detect if URL is local using `RedirectHttpResult.IsLocalUrl`
+
+Use the new [`RedirectHttpResult.IsLocalUrl(url)`](https://source.dot.net/#Microsoft.AspNetCore.Http.Results/RedirectHttpResult.cs,c0ece2e6266cb369) helper method to detect if a URL is local. A URL is considered local if the following are true:
+
+- It doesn't have the [host](https://developer.mozilla.org/docs/Web/API/URL/host) or [authority](https://developer.mozilla.org/docs/Web/URI/Authority) section.
+- It has an [absolute path](https://developer.mozilla.org/docs/Learn_web_development/Howto/Web_mechanics/What_is_a_URL#absolute_urls_vs._relative_urls).
+
+URLs using [virtual paths](/previous-versions/aspnet/ms178116(v=vs.100)) '~/' are also local.
+
+`IsLocalUrl` is useful for validating URLs before redirecting to them to prevent [open redirection attacks](https://brightsec.com/blog/open-redirect-vulnerabilities/).
+
+```csharp
+if (RedirectHttpResult.IsLocalUrl(url))
+{
+    return Results.LocalRedirect(url);
+}
+```
+
+Thank you [@martincostello](https://github.com/martincostello) for this contribution!
+
 ## Related content

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+> [!IMPORTANT]`
	`2`	`+> The Hosted Blazor WebAssembly project template was removed from the framework with the release of .NET 8 (November, 2023). The guidance in this article is only supported for .NET 7 or earlier. Hosted Blazor WebAssembly apps that are upgraded each release continue to receive product support. Alternatively, refactor the app into either a standalone Blazor WebAssembly app or a Blazor Web App.`