Merge pull request #35563 from dotnet/main

Author: guardrex

aspnetcore/blazor/call-web-api.md

@@ -5,7 +5,7 @@ description: Learn how to call a web API from Blazor apps.
 monikerRange: '>= aspnetcore-3.1'
 ms.author: wpickett
 ms.custom: mvc
-ms.date: 05/30/2025
+ms.date: 06/03/2025
 uid: blazor/call-web-api
 ---
 # Call a web API from ASP.NET Core Blazor
@@ -124,6 +124,10 @@ To configure a production distributed cache provider, see <xref:performance/cach
 
 For more information, see [Token cache serialization: Distributed caches](/entra/msal/dotnet/how-to/token-cache-serialization?tabs=msal#distributed-caches). However, the code examples shown don't apply to ASP.NET Core apps, which configure distributed caches via <xref:Microsoft.Extensions.DependencyInjection.MemoryCacheServiceCollectionExtensions.AddDistributedMemoryCache%2A>, not <xref:Microsoft.Identity.Web.TokenCacheExtensions.AddDistributedTokenCache%2A>.
 
+<!-- DOC AUTHOR NOTE: The next part on using a shared DP key ring is also
+                      covered in the *BWA+Entra* security article. Mirror 
+                      changes when updating this portion of content. -->
+
 Use a shared Data Protection key ring in production so that instances of the app across servers in a web farm can decrypt tokens when <xref:Microsoft.Identity.Web.TokenCacheProviders.Distributed.MsalDistributedTokenCacheAdapterOptions.Encrypt%2A?displayProperty=nameWithType> is set to `true`.
 
 > [!NOTE]
@@ -135,22 +139,73 @@ Use a shared Data Protection key ring in production so that instances of the app
 >
 > Later in the development and testing period, enable token encryption and adopt a shared Data Protection key ring.
 
-The following example shows how to use [Azure Blob Storage and Azure Key Vault](xref:security/data-protection/configuration/overview#protectkeyswithazurekeyvault) for the shared key ring. Add the following packages to the server project of the Blazor Web App:
+The following example shows how to use [Azure Blob Storage and Azure Key Vault (`PersistKeysToAzureBlobStorage`/`ProtectKeysWithAzureKeyVault`)](xref:security/data-protection/configuration/overview#protectkeyswithazurekeyvault) for the shared key ring. The service configurations are base case scenarios for demonstration purposes. Before deploying production apps, familiarize yourself with the Azure services and adopt best practices using their dedicated documentation sets, which are listed at the end of this section.
+
+Add the following packages to the server project of the Blazor Web App:
 
 * [`Azure.Extensions.AspNetCore.DataProtection.Blobs`](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.DataProtection.Blobs)
 * [`Azure.Extensions.AspNetCore.DataProtection.Keys`](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.DataProtection.Keys)
 
 [!INCLUDE[](~/includes/package-reference.md)]
 
-Configure Azure Blob Storage to maintain the encrypted keys and protect them with Azure Key Vault. In the following example, the `{BLOB URI WITH SAS TOKEN}` placeholder is the full URI where the key file should be stored with the SAS token as a query string parameter, and the `{KEY IDENTIFIER}` placeholder is the key vault key identifier used for key encryption:
+> [!NOTE]
+> Before proceeding with the following steps, confirm that the app is registered with Microsoft Entra.
+
+Configure Azure Blob Storage to maintain Data Protection keys and encrypt them at rest with Azure Key Vault:
+
+* Create an Azure storage account. The account name in the following example is `contoso`.
+
+* Create a container to hold the Data Protection keys. The container name in the following example is `data-protection`.  
+
+* Create the key file on your local machine. In the following example, the key file is named `keys.xml`. You can use a text editor to create the file.
+
+  `keys.xml`:
+
+  ```xml
+  <?xml version="1.0" encoding="utf-8"?>
+  <repository>
+  </repository>
+  ```
+
+* Upload the key file (`keys.xml`) to the container of the storage account. Use the context menu's **View/edit** command at the end of the key row in the portal to confirm that the blob contains the preceding content.
+
+* Use the context menu's **Generate SAS** command to obtain the blob's URI with a shared access signature (SAS). When you create the SAS, use the following permissions: `Read`, `Add`, `Create`, `Write`, `Delete`. The URI is used later where the `{BLOB URI WITH SAS}` placeholder appears.
+
+When establishing the key vault in the Entra or Azure portal:
+
+* Configure the key vault to use a **Vault access policy**. Confirm that public access on the **Networking** step is **enabled** (checked).
+
+* In the **Access policies** pane, create a new access policy with `Get`, `Unwrap Key`, and `Wrap Key` Key permissions. Select the registered application as the service principal.
+
+* When key encryption is active, keys in the key file include the comment, ":::no-loc text="This key is encrypted with Azure Key Vault.":::" After starting the app, select the **View/edit** command from the context menu at the end of the key row to confirm that a key is present with key vault security applied.
+
+The <xref:Microsoft.Extensions.Azure.AzureEventSourceLogForwarder> service in the following example forwards log messages from Azure SDK for logging and requires the [`Microsoft.Extensions.Azure` NuGet package](https://www.nuget.org/packages/Microsoft.Extensions.Azure).
+
+[!INCLUDE[](~/includes/package-reference.md)]
+
+At the top of the `Program` file, provide access to the API in the <xref:Microsoft.Extensions.Azure?displayProperty=fullName> namespace:
+
+```csharp
+using Microsoft.Extensions.Azure;
+```
+
+Use the following code in the `Program` file where services are registered:
 
 ```csharp
+builder.Services.TryAddSingleton<AzureEventSourceLogForwarder>();
+
 builder.Services.AddDataProtection()
-    .PersistKeysToAzureBlobStorage(new Uri("{BLOB URI WITH SAS TOKEN}"))
+    .PersistKeysToAzureBlobStorage(new Uri("{BLOB URI WITH SAS}"))
     .ProtectKeysWithAzureKeyVault(new Uri("{KEY IDENTIFIER}"), new DefaultAzureCredential());
 ```
 
-For more information on using a shared Data Protection key ring, see <xref:host-and-deploy/web-farm#data-protection> and <xref:security/data-protection/configuration/overview>.
+`{BLOB URI WITH SAS}`: The full URI where the key file should be stored with the SAS token as a query string parameter. The URI is generated by Azure Storage when you request a SAS for the uploaded key file. The container name in the following example is `data-protection`, and the storage account name is `contoso`. The key file is named `keys.xml`.
+
+Example: :::no-loc text="https://contoso.blob.core.windows.net/data-protection/keys.xml?sp={PERMISSIONS}&st={START DATETIME}&se={EXPIRATION DATETIME}&spr=https&sv={STORAGE VERSION DATE}&sr=c&sig={TOKEN}":::
+
+`{KEY IDENTIFIER}`: Azure Key Vault key identifier used for key encryption. The key vault name is `contoso` in the following example, and an access policy allows the application to access the key vault with `Get`, `Unwrap Key`, and `Wrap Key` permissions. The example key name is `data-protection`. The version of the key (`{KEY VERSION}` placeholder) is obtained from the key in the Entra or Azure portal after it's created.
+
+Example: :::no-loc text="https://contoso.vault.azure.net/keys/data-protection/{KEY VERSION}":::
 
 Inject <xref:Microsoft.Identity.Abstractions.IDownstreamApi> and call <xref:Microsoft.Identity.Abstractions.IDownstreamApi.CallApiForUserAsync%2A> when calling on behalf of a user:
 
@@ -180,6 +235,11 @@ For more information, see the following resources:
 * *Secure an ASP.NET Core Blazor Web App with Microsoft Entra ID*
   * [Non-BFF pattern (Interactive Auto)](xref:blazor/security/blazor-web-app-entra?pivots=non-bff-pattern)
   * [BFF pattern (Interactive Auto)](xref:blazor/security/blazor-web-app-entra?pivots=non-bff-pattern-server)
+* [Host ASP.NET Core in a web farm: Data Protection](xref:host-and-deploy/web-farm#data-protection)
+* <xref:security/data-protection/configuration/overview>
+* <xref:security/data-protection/implementation/key-storage-providers>
+* [Azure Key Vault documentation](/azure/key-vault/general/)
+* [Azure Storage documentation](/azure/storage/)
 
 ## Sample apps
 
@@ -304,6 +364,27 @@ The solution includes a demonstration of obtaining weather data securely via an
 
 :::moniker-end
 
+## Disposal of `HttpRequestMessage`, `HttpResponseMessage`, and `HttpClient`
+
+An <xref:System.Net.Http.HttpRequestMessage> without a body doesn't require explicit disposal with a [`using` declaration (C# 8 or later)](/dotnet/csharp/language-reference/proposals/csharp-8.0/using) or a `using` block (earlier than C# 8), but we recommend disposing with every use for the following reasons:
+
+* It provides a performance improvement by avoiding finalizers.
+* It hardens the code for the future in case a request body is ever added to a <xref:System.Net.Http.HttpRequestMessage> that didn't initially have one.
+* It potentially avoids functional issues if a delegating handler expects <xref:System.IDisposable.Dispose%2A>/<xref:System.IAsyncDisposable.DisposeAsync%2A> to be called.
+* It's simpler to apply a general rule everywhere than trying to remember the specific cases when it matters.
+
+Always dispose of <xref:System.Net.Http.HttpResponseMessage> instances.
+
+***Never*** dispose of <xref:System.Net.Http.HttpClient> instances created by calling <xref:System.Net.Http.IHttpClientFactory.CreateClient%2A> because they're managed by the framework.
+
+Example:
+
+```csharp
+using var request = new HttpRequestMessage(HttpMethod.Get, "/weather-forecast");
+var client = clientFactory.CreateClient("ExternalApi");
+using var response = await client.SendAsync(request);
+```
+
 ## Client-side scenarios for calling external web APIs
 
 Client-based components call external web APIs using <xref:System.Net.Http.HttpClient> instances, typically created with a preconfigured <xref:System.Net.Http.HttpClient> registered in the `Program` file:
@@ -351,12 +432,12 @@ else
 
     protected override async Task OnInitializedAsync()
     {
-        var request = new HttpRequestMessage(HttpMethod.Get,
+        using var request = new HttpRequestMessage(HttpMethod.Get,
             "https://api.github.com/repos/dotnet/AspNetCore.Docs/branches");
         request.Headers.Add("Accept", "application/vnd.github.v3+json");
         request.Headers.Add("User-Agent", "HttpClientFactory-Sample");
 
-        var response = await Client.SendAsync(request);
+        using var response = await Client.SendAsync(request);
 
         if (response.IsSuccessStatusCode)
         {
@@ -411,10 +492,10 @@ Even if you call <xref:Microsoft.AspNetCore.Components.WebAssembly.Http.WebAssem
 
           var urlEncodedRequestUri = WebUtility.UrlEncode("{REQUEST URI}");
 
-          var request = new HttpRequestMessage(HttpMethod.Get, 
+          using var request = new HttpRequestMessage(HttpMethod.Get, 
               $"https://corsproxy.io/?{urlEncodedRequestUri}");
 
-          var response = await client.SendAsync(request);
+          using var response = await client.SendAsync(request);
 
           ...
       }
@@ -468,14 +549,14 @@ else
 
     protected override async Task OnInitializedAsync()
     {
-        var request = new HttpRequestMessage(HttpMethod.Get,
+        using var request = new HttpRequestMessage(HttpMethod.Get,
             "https://api.github.com/repos/dotnet/AspNetCore.Docs/branches");
         request.Headers.Add("Accept", "application/vnd.github.v3+json");
         request.Headers.Add("User-Agent", "HttpClientFactory-Sample");
 
         var client = ClientFactory.CreateClient();
 
-        var response = await client.SendAsync(request);
+        using var response = await client.SendAsync(request);
 
         if (response.IsSuccessStatusCode)
         {
@@ -579,11 +660,11 @@ In the following file upload example:
 * `Http` is the <xref:System.Net.Http.HttpClient>.
 
 ```csharp
-var request = new HttpRequestMessage(HttpMethod.Post, "/Filesave");
+using var request = new HttpRequestMessage(HttpMethod.Post, "/Filesave");
 request.SetBrowserRequestStreamingEnabled(true);
 request.Content = content;
 
-var response = await Http.SendAsync(request);
+using var response = await Http.SendAsync(request);
 ```
 
 Streaming requests:
@@ -737,7 +818,7 @@ As of C# 11 (.NET 7), you can compose a JSON string as a [raw string literal](/d
 <xref:System.Net.Http.Json.HttpClientJsonExtensions.PatchAsJsonAsync%2A> returns an <xref:System.Net.Http.HttpResponseMessage>. To deserialize the JSON content from the response message, use the <xref:System.Net.Http.Json.HttpContentJsonExtensions.ReadFromJsonAsync%2A> extension method. The following example reads JSON todo item data as an array. An empty array is created if no item data is returned by the method, so `content` isn't null after the statement executes:
 
 ```csharp
-var response = await Http.PatchAsJsonAsync(...);
+using var response = await Http.PatchAsJsonAsync(...);
 var content = await response.Content.ReadFromJsonAsync<TodoItem[]>() ??
     Array.Empty<TodoItem>();
 ```
@@ -1120,7 +1201,7 @@ For a demonstration, see <xref:blazor/security/webassembly/standalone-with-ident
 When composing an <xref:System.Net.Http.HttpRequestMessage>, set the browser request credentials and header directly:
 
 ```csharp
-var request = new HttpRequestMessage() { ... };
+using var request = new HttpRequestMessage() { ... };
 
 request.SetBrowserRequestCredentials(BrowserRequestCredentials.Include);
 request.Headers.Add("X-Requested-With", [ "XMLHttpRequest" ]);
@@ -1156,7 +1237,7 @@ request.Headers.Add("X-Requested-With", [ "XMLHttpRequest" ]);
 
     private async Task PostRequest()
     {
-        var request = new HttpRequestMessage()
+        using var request = new HttpRequestMessage()
         {
             Method = new HttpMethod("POST"),
             RequestUri = new Uri("https://localhost:10000/todoitems"),
@@ -1178,7 +1259,7 @@ request.Headers.Add("X-Requested-With", [ "XMLHttpRequest" ]);
             request.Content.Headers.TryAddWithoutValidation(
                 "x-custom-header", "value");
 
-            var response = await Http.SendAsync(request);
+            using var response = await Http.SendAsync(request);
             var responseStatusCode = response.StatusCode;
 
             responseBody = await response.Content.ReadAsStringAsync();
@@ -1241,8 +1322,9 @@ request.SetBrowserResponseStreamingEnabled(true);
 By default, [`HttpCompletionOption.ResponseContentRead`](xref:System.Net.Http.HttpCompletionOption) is set, which results in the <xref:System.Net.Http.HttpClient> completing after reading the entire response, including the content. In order to be able to use the <xref:Microsoft.AspNetCore.Components.WebAssembly.Http.WebAssemblyHttpRequestMessageExtensions.SetBrowserResponseStreamingEnabled%2A> option on large files, set [`HttpCompletionOption.ResponseHeadersRead`](xref:System.Net.Http.HttpCompletionOption) to avoid caching the file's content in memory:
 
 ```diff
-- var response = await Http.SendAsync(request);
-+ var response = await Http.SendAsync(request, HttpCompletionOption.ResponseHeadersRead);
+- using var response = await Http.SendAsync(request);
++ using var response = await Http.SendAsync(request, 
++     HttpCompletionOption.ResponseHeadersRead);
 ```
 
 :::moniker-end
@@ -1345,9 +1427,9 @@ To add antiforgery support to an HTTP request, inject the `AntiforgeryStateProvi
 private async Task OnSubmit()
 {
     var antiforgery = Antiforgery.GetAntiforgeryToken();
-    var request = new HttpRequestMessage(HttpMethod.Post, "action");
+    using var request = new HttpRequestMessage(HttpMethod.Post, "action");
     request.Headers.Add("RequestVerificationToken", antiforgery.RequestToken);
-    var response = await client.SendAsync(request);
+    using var response = await client.SendAsync(request);
     ...
 }
 ```

aspnetcore/blazor/components/quickgrid.md

@@ -446,7 +446,7 @@ The <xref:Microsoft.AspNetCore.Components.QuickGrid.GridItemsProvider%601> conve
                 { "limit", req.Count },
             });
 
-            var response = await Http.GetFromJsonAsync<FoodRecallQueryResult>(
+            using var response = await Http.GetFromJsonAsync<FoodRecallQueryResult>(
                 url, req.CancellationToken);
 
             return GridItemsProviderResult.From(

aspnetcore/blazor/file-uploads.md

@@ -709,11 +709,11 @@ In a Blazor Web App, add the <xref:Microsoft.AspNetCore.Components.WebAssembly.H
 
         if (upload)
         {
-            var request = new HttpRequestMessage(HttpMethod.Post, "/Filesave");
+            using var request = new HttpRequestMessage(HttpMethod.Post, "/Filesave");
             request.SetBrowserRequestStreamingEnabled(true);
             request.Content = content;
 
-            var response = await Http.SendAsync(request);
+            using var response = await Http.SendAsync(request);
 
             var newUploadResults = await response.Content
                 .ReadFromJsonAsync<IList<UploadResult>>();

aspnetcore/blazor/forms/validation.md

@@ -744,7 +744,7 @@ In the following component, update the namespace of the **`Shared`** project (`@
 
         try
         {
-            var response = await Http.PostAsJsonAsync<Starship>(
+            using var response = await Http.PostAsJsonAsync<Starship>(
                 "StarshipValidation", (Starship)editContext.Model);
 
             var errors = await response.Content
@@ -888,7 +888,7 @@ The preceding example sets the base address with `builder.HostEnvironment.BaseAd
 
         try
         {
-            var response = await Http.PostAsJsonAsync<Starship>(
+            using var response = await Http.PostAsJsonAsync<Starship>(
                 "StarshipValidation", (Starship)editContext.Model);
 
             var errors = await response.Content

aspnetcore/blazor/hybrid/security/maui-blazor-web-identity.md

@@ -162,7 +162,7 @@ In `MauiBlazorWeb/Services/MauiAuthenticationStateProvider.cs`:
         // Call the Login endpoint and pass the email and password
         var httpClient = HttpClientHelper.GetHttpClient();
         var loginData = new { loginModel.Email, loginModel.Password };
-        var response = await httpClient.PostAsJsonAsync(HttpClientHelper.LoginUrl, 
+        using var response = await httpClient.PostAsJsonAsync(HttpClientHelper.LoginUrl, 
             loginData);
 
         LoginStatus =