Merge pull request #35301 from dotnet/main

Merge to Live

Author: Rick-Anderson

aspnetcore/fundamentals/http-logging/index.md

@@ -8,7 +8,6 @@ ms.custom: mvc
 ms.date: 10/25/2023
 uid: fundamentals/http-logging/index
 ---
-
 # HTTP logging in ASP.NET Core
 
 [!INCLUDE[](~/includes/not-latest-version.md)]
@@ -46,8 +45,8 @@ The empty lambda in the preceding example of calling `AddHttpLogging` adds the m
 Add the following line to the `appsettings.Development.json` file at the `"LogLevel": {` level so the HTTP logs are displayed:
 
 ```json
- "Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware": "Information"
- ```
+"Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware": "Information"
+```
 
 With the default configuration, a request and response is logged as a pair of messages similar to the following example:
 
@@ -87,11 +86,11 @@ To configure global options for the HTTP logging middleware, call <xref:Microsof
 [!code-csharp[](~/fundamentals/http-logging/samples/8.x/Program.cs?name=snippet_Addservices)]
 
 > [!NOTE]
-> In the preceding sample and following samples, `UseHttpLogging` is called after `UseStaticFiles`, so HTTP logging is not enabled for static files. To enable static file HTTP logging, call `UseHttpLogging` before `UseStaticFiles`.
+> In the preceding sample and following samples, `UseHttpLogging` is called after `UseStaticFiles`, so HTTP logging isn't enabled for static files. To enable static file HTTP logging, call `UseHttpLogging` before `UseStaticFiles`.
 
 ### `LoggingFields`
 
-[`HttpLoggingOptions.LoggingFields`](xref:Microsoft.AspNetCore.HttpLogging.HttpLoggingOptions.LoggingFields) is an enum flag that configures specific parts of the request and response to log. ``HttpLoggingOptions.LoggingFields`` defaults to <xref:Microsoft.AspNetCore.HttpLogging.HttpLoggingFields.RequestPropertiesAndHeaders> | <xref:Microsoft.AspNetCore.HttpLogging.HttpLoggingFields.ResponsePropertiesAndHeaders>.
+[`HttpLoggingOptions.LoggingFields`](xref:Microsoft.AspNetCore.HttpLogging.HttpLoggingOptions.LoggingFields) is an enum flag that configures specific parts of the request and response to log. `LoggingFields` defaults to <xref:Microsoft.AspNetCore.HttpLogging.HttpLoggingFields.RequestPropertiesAndHeaders> | <xref:Microsoft.AspNetCore.HttpLogging.HttpLoggingFields.ResponsePropertiesAndHeaders>.
 
 ### `RequestHeaders` and `ResponseHeaders`
 
@@ -132,7 +131,7 @@ For endpoint-specific configuration in minimal API apps, a <xref:Microsoft.AspNe
 
 [!code-csharp[](~/fundamentals/http-logging/samples/8.x/Program.cs?name=snippet6)]
 
-For endpoint-specific configuration in apps that use controllers, the [`[HttpLogging]`](xref:Microsoft.AspNetCore.HttpLogging.HttpLoggingAttribute) attribute is available. The attribute can also be used in minimal API apps, as shown in the following example:
+For endpoint-specific configuration in apps that use controllers, the [`[HttpLogging]` attribute](xref:Microsoft.AspNetCore.HttpLogging.HttpLoggingAttribute) is available. The attribute can also be used in minimal API apps, as shown in the following example:
 
 [!code-csharp[](~/fundamentals/http-logging/samples/8.x/Program.cs?name=snippet5)]
 
@@ -145,13 +144,13 @@ For endpoint-specific configuration in apps that use controllers, the [`[HttpLog
 * Adjust how much of the request or response body is logged.
 * Add custom fields to the logs.
 
-Register an `IHttpLoggingInterceptor` implementation by calling [`AddHttpLoggingInterceptor<T>`](xref:Microsoft.Extensions.DependencyInjection.HttpLoggingServicesExtensions.AddHttpLoggingInterceptor%60%601(Microsoft.Extensions.DependencyInjection.IServiceCollection)) in `Program.cs`. If multiple `IHttpLoggingInterceptor` instances are registered, they're run in the order registered.
+Register an <xref:Microsoft.AspNetCore.HttpLogging.IHttpLoggingInterceptor> implementation by calling <xref:Microsoft.Extensions.DependencyInjection.HttpLoggingServicesExtensions.AddHttpLoggingInterceptor%2A> in `Program.cs`. If multiple <xref:Microsoft.AspNetCore.HttpLogging.IHttpLoggingInterceptor> instances are registered, they're run in the order registered.
 
-The following example shows how to register an `IHttpLoggingInterceptor` implementation:
+The following example shows how to register an <xref:Microsoft.AspNetCore.HttpLogging.IHttpLoggingInterceptor> implementation:
 
 [!code-csharp[](~/fundamentals/http-logging/samples/8.x/Program.cs?name=snippet4&highlight=7)]
 
-The following example is an `IHttpLoggingInterceptor` implementation that:
+The following example is an <xref:Microsoft.AspNetCore.HttpLogging.IHttpLoggingInterceptor> implementation that:
 
 * Inspects the request method and disables logging for POST requests.
 * For non-POST requests:
@@ -160,7 +159,7 @@ The following example is an `IHttpLoggingInterceptor` implementation that:
 
 [!code-csharp[](~/fundamentals/http-logging/samples/8.x/SampleHttpLoggingInterceptor.cs)]
 
-With this interceptor, a POST request doesn't generate any logs even if HTTP logging is configured to log `HttpLoggingFields.All`. A GET request generates logs similar to the following example:
+With this interceptor, a POST request doesn't generate any logs even if HTTP logging is configured to log [`HttpLoggingFields.All`](xref:Microsoft.AspNetCore.HttpLogging.HttpLoggingFields). A GET request generates logs similar to the following example:
 
 ```output
 info: Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware[1]
@@ -200,7 +199,7 @@ info: Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware[8]
 The following list shows the order of precedence for logging configuration:
 
 1. Global configuration from <xref:Microsoft.AspNetCore.HttpLogging.HttpLoggingOptions>, set by calling <xref:Microsoft.Extensions.DependencyInjection.HttpLoggingServicesExtensions.AddHttpLogging%2A>.
-1. Endpoint-specific configuration from the [`[HttpLogging]`](xref:Microsoft.AspNetCore.HttpLogging.HttpLoggingAttribute) attribute or the <xref:Microsoft.AspNetCore.Builder.HttpLoggingEndpointConventionBuilderExtensions.WithHttpLogging%2A> extension method overrides global configuration.
+1. Endpoint-specific configuration from the [`[HttpLogging]` attribute](xref:Microsoft.AspNetCore.HttpLogging.HttpLoggingAttribute) or the <xref:Microsoft.AspNetCore.Builder.HttpLoggingEndpointConventionBuilderExtensions.WithHttpLogging%2A> extension method overrides global configuration.
 1. [`IHttpLoggingInterceptor`](#ihttplogginginterceptor) is called with the results and can further modify the configuration per request.
 
 :::moniker-end
@@ -211,17 +210,18 @@ The following list shows the order of precedence for logging configuration:
 
 ## Redacting sensitive data
 
-Http logging with redaction can be enabled by calling `AddHttpLoggingRedaction`<!-- Microsoft.Extensions.DependencyInjection.HttpLoggingServiceCollectionExtensions.AddHttpLoggingRedaction> -->:
+Http logging with redaction can be enabled by calling <xref:Microsoft.Extensions.DependencyInjection.HttpLoggingServiceCollectionExtensions.AddHttpLoggingRedaction%2A>:
 
 [!code-csharp[](~/fundamentals/http-logging/samples/9.x/Program.cs?name=snippet7&highlight=9)]
 
 For more information about .NET's data redaction library, see [Data redaction in .NET](/dotnet/core/extensions/data-redaction).
 
 ## Logging redaction options
 
-To configure options for logging with redaction, call `AddHttpLoggingRedaction`<!-- Microsoft.Extensions.DependencyInjection.HttpLoggingServiceCollectionExtensions.AddHttpLoggingRedaction>--> in `Program.cs`, using the lambda to configure <!-- Microsoft.AspNetCore.Diagnostics.Logging.LoggingRedactionOptions>--> `LoggingRedactionOptions`:
+To configure options for logging with redaction, call <xref:Microsoft.Extensions.DependencyInjection.HttpLoggingServiceCollectionExtensions.AddHttpLoggingRedaction%2A> in `Program.cs` using the lambda to configure <xref:Microsoft.AspNetCore.Diagnostics.Logging.LoggingRedactionOptions>:
 
 [!code-csharp[](~/fundamentals/http-logging/samples/9.x/MyTaxonomyClassifications.cs)]
+
 [!code-csharp[](~/fundamentals/http-logging/samples/9.x/Program.cs?name=snippet_redactionOptions&highlight=6)]
 
 With the previous redaction configuration, the output is similar to the following:
@@ -242,66 +242,56 @@ info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
       Request finished HTTP/2 GET https://localhost:61361/ - 200 - text/plain;+charset=utf-8 105.5334ms
 ```
 
-***Note:*** Request path `/home` isn't logged because it is included in `ExcludePathStartsWith` property. `http.request.header.accept` and `http.response.header.content-type` were redacted by  <!-- Microsoft.Extensions.Compliance.Redaction.ErasingRedactor> --> `Redaction.ErasingRedactor`.
+> [!NOTE]
+> Request path `/home` isn't logged because it's included in the [`ExcludePathStartsWith` property](#excludepathstartswith). `http.request.header.accept` and `http.response.header.content-type` were redacted by <xref:Microsoft.Extensions.Compliance.Redaction.ErasingRedactor?displayProperty=nameWithType>.
 
-### RequestPathLoggingMode
+### `RequestPathLoggingMode`
 
-<!-- Microsoft.AspNetCore.Diagnostics.Logging.LoggingRedactionOptions.RequestPathLoggingMode>-->
-`RequestPathLoggingMode` determines how the request path is logged, whether `Formatted` or `Structured`.
+<xref:Microsoft.AspNetCore.Diagnostics.Logging.LoggingRedactionOptions.RequestPathLoggingMode%2A> determines how the request path is logged, whether `Formatted` or `Structured`, set by <xref:Microsoft.AspNetCore.Diagnostics.Logging.IncomingPathLoggingMode>:
 
-<!-- Microsoft.AspNetCore.Diagnostics.Logging.IncomingPathLoggingMode.Formatted> -->
-* `Formatted` logs the request path without parameters.
-<!-- Microsoft.AspNetCore.Diagnostics.Logging.IncomingPathLoggingMode.Structured> -->
-* `Structured` logs the request path with parameters included.
+* `Formatted`: Logs the request path without parameters.
+* `Structured`: Logs the request path with parameters included.
 
 [!code-csharp[](~/fundamentals/http-logging/samples/9.x/Program.cs?name=snippet_redactionOptions&highlight=9)]
 
-### RequestPathParameterRedactionMode
+### `RequestPathParameterRedactionMode`
 
-<!-- Microsoft.AspNetCore.Diagnostics.Logging.LoggingRedactionOptions.RequestPathParameterRedactionMode> -->
-`RequestPathParameterRedactionMode` specifies how route parameters in the request path should be redacted, whether `Strict`, `Loose`, or `None`.
+<xref:Microsoft.AspNetCore.Diagnostics.Logging.LoggingRedactionOptions.RequestPathParameterRedactionMode%2A>
+specifies how route parameters in the request path should be redacted, whether `Strict`, `Loose`, or `None`, set by <xref:Microsoft.Extensions.Http.Diagnostics.HttpRouteParameterRedactionMode>:
 
-<!-- Microsoft.AspNetCore.Diagnostics.Logging.HttpRouteParameterRedactionMode.Strict>-->
 * `Strict`: Request route parameters are considered sensitive, require explicit annotation with a data classification, and are redacted by default.
-<!-- Microsoft.AspNetCore.Diagnostics.Logging.HttpRouteParameterRedactionMode.Loose>-->
 * `Loose`: All parameters are considered as non-sensitive and included as-is by default.
-<!-- Microsoft.AspNetCore.Diagnostics.Logging.HttpRouteParameterRedactionMode.None>-->
 * `None`: Route parameters aren't redacted regardless of the presence of data classification annotations.
 
 [!code-csharp[](~/fundamentals/http-logging/samples/9.x/Program.cs?name=snippet_redactionOptions&highlight=8)]
 
-### RequestHeadersDataClasses
+### `RequestHeadersDataClasses`
 
-<!-- Microsoft.AspNetCore.Diagnostics.Logging.LoggingRedactionOptions.RequestHeadersDataClasses>-->
-`RequestHeadersDataClasses` maps request headers to their data classification, which determines how they are redacted:
+<xref:Microsoft.AspNetCore.Diagnostics.Logging.LoggingRedactionOptions.RequestHeadersDataClasses%2A> maps request headers to their data classification, which determines how they are redacted:
 
 [!code-csharp[](~/fundamentals/http-logging/samples/9.x/Program.cs?name=snippet_redactionOptions&highlight=10)]
 
-### ResponseHeadersDataClasses
+### `ResponseHeadersDataClasses`
 
-<!-- Microsoft.AspNetCore.Diagnostics.Logging.LoggingRedactionOptions.ResponseHeadersDataClasses>-->
-`ResponseHeadersDataClasses`, similar to <!-- Microsoft.AspNetCore.Diagnostics.Logging.LoggingRedactionOptions.RequestHeadersDataClasses>--> `RequestHeadersDataClasses`, but for response headers:
+<xref:Microsoft.AspNetCore.Diagnostics.Logging.LoggingRedactionOptions.ResponseHeadersDataClasses%2A>, similar to <xref:Microsoft.AspNetCore.Diagnostics.Logging.LoggingRedactionOptions.RequestHeadersDataClasses%2A>`, but for response headers:
 
 [!code-csharp[](~/fundamentals/http-logging/samples/9.x/Program.cs?name=snippet_redactionOptions&highlight=11)]
 
-### RouteParameterDataClasses
+### `RouteParameterDataClasses`
 
-<!-- Microsoft.AspNetCore.Diagnostics.Logging.LoggingRedactionOptions.RouteParameterDataClasses>-->
-`RouteParameterDataClasses` maps route parameters to their data classification:
+<xref:Microsoft.AspNetCore.Diagnostics.Logging.LoggingRedactionOptions.RouteParameterDataClasses%2A> maps route parameters to their data classification:
 
 [!code-csharp[](~/fundamentals/http-logging/samples/9.x/Program.cs?name=snippet_redactionOptions&highlight=12,13,14,15)]
 
-### ExcludePathStartsWith
+### `ExcludePathStartsWith`
 
-<!-- Microsoft.AspNetCore.Diagnostics.Logging.LoggingRedactionOptions.ExcludePathStartsWith>-->
-`ExcludePathStartsWith` specifies paths that should be excluded from logging entirely:
+<xref:Microsoft.AspNetCore.Diagnostics.Logging.LoggingRedactionOptions.ExcludePathStartsWith%2A> specifies paths that should be excluded from logging entirely:
 
 [!code-csharp[](~/fundamentals/http-logging/samples/9.x/Program.cs?name=snippet_redactionOptions&highlight=16,17)]
 
-### IncludeUnmatchedRoutes
+### `IncludeUnmatchedRoutes`
 
-<!-- Microsoft.AspNetCore.Diagnostics.Logging.LoggingRedactionOptions.IncludeUnmatchedRoutes>-->
-`IncludeUnmatchedRoutes` allows reporting unmatched routes. If set to `true`, logs whole path of routes not identified by [Routing](xref:fundamentals/routing) instead of logging `Unknown` value for path attribute:
+<xref:Microsoft.AspNetCore.Diagnostics.Logging.LoggingRedactionOptions.IncludeUnmatchedRoutes%2A> allows reporting unmatched routes. If set to `true`, logs whole path of routes not identified by [Routing](xref:fundamentals/routing) instead of logging `Unknown` value for path attribute:
 
 [!code-csharp[](~/fundamentals/http-logging/samples/9.x/Program.cs?name=snippet_redactionOptions&highlight=18)]
 

aspnetcore/fundamentals/middleware/request-response.md

@@ -5,7 +5,7 @@ description: Learn how to read the request body and write the response body in A
 monikerRange: '>= aspnetcore-3.0'
 ms.author: tdykstra
 ms.custom: mvc
-ms.date: 5/29/2019
+ms.date: 4/22/2025
 uid: fundamentals/middleware/request-response
 ---
 # Request and response operations in ASP.NET Core
@@ -25,7 +25,10 @@ There are two abstractions for the request and response bodies: <xref:System.IO.
 * `TextWriter`
 * `HttpResponse.WriteAsync`
 
-Streams aren't being removed from the framework. Streams continue to be used throughout .NET, and many stream types don't have pipe equivalents, such as `FileStreams` and `ResponseCompression`.
+Streams aren't being removed from the framework. Streams continue to be used throughout .NET:
+
+* Many stream types don't have pipe equivalents, such as `FileStreams` and `ResponseCompression`.
+* It's straightforward adding compression to a stream.
 
 ## Stream examples
 
@@ -70,7 +73,7 @@ These issues are fixable, but the code is becoming progressively more complicate
 
 ## Pipelines
 
-The following example shows how the same scenario can be handled using a [PipeReader](/dotnet/standard/io/pipelines#pipe):
+The following example shows how the preceding stream scenario can be handled using a [PipeReader](/dotnet/standard/io/pipelines#pipe):
 
 [!code-csharp[](request-response/samples/3.x/RequestResponseSample/Startup.cs?name=GetListOfStringFromPipe)]
 
@@ -80,6 +83,13 @@ This example fixes many issues that the streams implementations had:
 * Encoded strings are directly added to the list of returned strings.
 * Other than the `ToArray` call, and the memory used by the string, string creation is allocation free.
 
+When writing directly to `HttpResponse.BodyWriter`, call `PipeWriter.FlushAsync` manually to ensure the data is flushed to the underlying response response body. Here's why:
+
+* `HttpResponse.BodyWriter` is a `PipeWriter` that buffers data until a flush operation is triggered.
+* Calling `FlushAsync` writes the buffered data to the underlying response body.
+
+It's up to the developer to decide when to call `FlushAsync`, balancing factors such as buffer size, network write overhead, and whether the data should be sent in discrete chunks. For more information, see [System.IO.Pipelines in .NET](/dotnet/standard/io/pipelines).
+
 ## Adapters
 
 The `Body`, `BodyReader`, and `BodyWriter` properties are available for `HttpRequest` and `HttpResponse`. When you set `Body` to a different stream, a new set of adapters automatically adapt each type to the other. If you set `HttpRequest.Body` to a new stream, `HttpRequest.BodyReader` is automatically set to a new `PipeReader` that wraps `HttpRequest.Body`.