[Pre3] Response streaming default and opt-out (#34894)

Author: guardrex

aspnetcore/blazor/call-web-api.md

@@ -972,7 +972,54 @@ requestMessage.Headers.Add("X-Requested-With", [ "XMLHttpRequest" ]);
 
 Blazor's client-side implementation of <xref:System.Net.Http.HttpClient> uses [Fetch API](https://developer.mozilla.org/docs/Web/API/fetch) and configures the underlying [request-specific Fetch API options](https://developer.mozilla.org/docs/Web/API/fetch#Parameters) via <xref:System.Net.Http.HttpRequestMessage> extension methods and <xref:Microsoft.AspNetCore.Components.WebAssembly.Http.WebAssemblyHttpRequestMessageExtensions>. Set additional options using the generic <xref:Microsoft.AspNetCore.Components.WebAssembly.Http.WebAssemblyHttpRequestMessageExtensions.SetBrowserRequestOption%2A> extension method. Blazor and the underlying Fetch API don't directly add or modify request headers. For more information on how user agents, such as browsers, interact with headers, consult external user agent documentation sets and other web resources.
 
-The HTTP response is typically buffered to enable support for synchronous reads on the response content. To enable support for response streaming, use the <xref:Microsoft.AspNetCore.Components.WebAssembly.Http.WebAssemblyHttpRequestMessageExtensions.SetBrowserResponseStreamingEnabled%2A> extension method on the request.
+:::moniker range=">= aspnetcore-10.0"
+
+Response streaming is enabled by default.
+
+Calling <xref:System.Net.Http.HttpContent.ReadAsStreamAsync%2A?displayProperty=nameWithType> for an <xref:System.Net.Http.HttpResponseMessage.Content%2A?displayProperty=nameWithType> (`response.Content.ReadAsStreamAsync()`) returns a [`BrowserHttpReadStream` (reference source)](https://github.com/dotnet/runtime/blob/main/src/libraries/System.Net.Http/src/System/Net/Http/BrowserHttpHandler/BrowserHttpHandler.cs), not a <xref:System.IO.MemoryStream>. `BrowserHttpReadStream` doesn't support synchronous operations, such as `Stream.Read(Span<Byte>)`. If your code uses synchronous operations, you can opt-out of response streaming or copy the <xref:System.IO.Stream> into a <xref:System.IO.MemoryStream> yourself.
+
+[!INCLUDE[](~/includes/aspnetcore-repo-ref-source-links.md)]
+
+<!-- UPDATE 10.0 - Tracking on https://github.com/dotnet/runtime/issues/97449
+
+To opt-out of response streaming globally, use either of the following approaches:
+
+* Add the `<WasmEnableStreamingResponse>` property to the project file with a value of `false`:
+  
+  ```xml
+  <WasmEnableStreamingResponse>false</WasmEnableStreamingResponse>
+  ```
+
+* Set the `DOTNET_WASM_ENABLE_STREAMING_RESPONSE` environment variable to `false` or `0`.
+
+-->
+
+To opt-out of response streaming globally, set the `DOTNET_WASM_ENABLE_STREAMING_RESPONSE` environment variable to `false` or `0`.
+
+To opt-out of response streaming for an individual request, set <xref:Microsoft.AspNetCore.Components.WebAssembly.Http.WebAssemblyHttpRequestMessageExtensions.SetBrowserResponseStreamingEnabled%2A> to `false` on the <xref:System.Net.Http.HttpRequestMessage> (`requestMessage` in the following example):
+
+```csharp
+requestMessage.SetBrowserResponseStreamingEnabled(false);
+```
+
+:::moniker-end
+
+:::moniker range="< aspnetcore-10.0"
+
+The HTTP response is typically buffered to enable support for synchronous reads on the response content. To enable support for response streaming, set <xref:Microsoft.AspNetCore.Components.WebAssembly.Http.WebAssemblyHttpRequestMessageExtensions.SetBrowserResponseStreamingEnabled%2A>  to `true` on the <xref:System.Net.Http.HttpRequestMessage>:
+
+```csharp
+requestMessage.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(requestMessage);
++ var response = await Http.SendAsync(requestMessage, HttpCompletionOption.ResponseHeadersRead);
+```
+
+:::moniker-end
 
 To include credentials in a cross-origin request, use the <xref:Microsoft.AspNetCore.Components.WebAssembly.Http.WebAssemblyHttpRequestMessageExtensions.SetBrowserRequestCredentials%2A> extension method:
 

aspnetcore/release-notes/aspnetcore-10/includes/blazor.md

@@ -89,3 +89,37 @@ The following example uses the `CloseColumnOptionsAsync` method to close the col
         movies.Where(m => m.Title!.Contains(titleFilter));
 }
 ```
+
+<!-- PREVIEW 3 ..... NOTE CONTENT CHANGE FOR `<WasmEnableStreamingResponse>` BELOW!!!!!
+
+### Response streaming is opt-in and how to opt-out
+
+In prior Blazor releases, response streaming for <xref:System.Net.Http.HttpClient> requests was opt-in. Now, response streaming is enabled by default.
+
+This is a breaking change because calling <xref:System.Net.Http.HttpContent.ReadAsStreamAsync%2A?displayProperty=nameWithType> for an <xref:System.Net.Http.HttpResponseMessage.Content%2A?displayProperty=nameWithType> (`response.Content.ReadAsStreamAsync()`) returns a `BrowserHttpReadStream` and no longer a <xref:System.IO.MemoryStream>. `BrowserHttpReadStream` doesn't support synchronous operations, such as `Stream.Read(Span<Byte>)`. If your code uses synchronous operations, you can opt-out of response streaming or copy the <xref:System.IO.Stream> into a <xref:System.IO.MemoryStream> yourself.
+
+DON'T USE (comment out) ..............
+
+To opt-out of response streaming globally, use either of the following approaches:
+
+* Add the `<WasmEnableStreamingResponse>` property to the project file with a value of `false`:
+  
+  ```xml
+  <WasmEnableStreamingResponse>false</WasmEnableStreamingResponse>
+  ```
+
+* Set the `DOTNET_WASM_ENABLE_STREAMING_RESPONSE` environment variable to `false` or `0`.
+
+..................... UNTIL https://github.com/dotnet/runtime/issues/97449 IS RESOLVED AND RELEASED.
+
+To opt-out of response streaming globally, set the `DOTNET_WASM_ENABLE_STREAMING_RESPONSE` environment variable to `false` or `0`.
+
+To opt-out of response streaming for an individual request, set <xref:Microsoft.AspNetCore.Components.WebAssembly.Http.WebAssemblyHttpRequestMessageExtensions.SetBrowserResponseStreamingEnabled%2A> to `false` on the <xref:System.Net.Http.HttpRequestMessage> (`requestMessage` in the following example):
+
+```csharp
+requestMessage.SetBrowserResponseStreamingEnabled(false);
+```
+
+For more information, see [`HttpClient` and `HttpRequestMessage` with Fetch API request options (*Call web API* article)](xref:blazor/call-web-api?view=aspnetcore-10.0#httpclient-and-httprequestmessage-with-fetch-api-request-options).
+
+-->