From 5c0770695b0091917a9c856bf2102dd8e808f16e Mon Sep 17 00:00:00 2001 From: Steve Molloy Date: Fri, 17 Jul 2026 11:48:33 -0700 Subject: [PATCH 1/2] Clarify OutputCache intent and limitations for classic ASP.Net. --- xml/System.Web.Caching/OutputCache.xml | 7 +++++-- xml/System.Web.Configuration/OutputCacheProfile.xml | 4 ++++ xml/System.Web.Configuration/OutputCacheSection.xml | 4 ++++ xml/System.Web.UI/OutputCacheParameters.xml | 4 ++++ xml/System.Web.UI/PartialCachingAttribute.xml | 4 ++++ xml/System.Web/HttpCachePolicy.xml | 4 ++++ xml/System.Web/HttpCacheVaryByContentEncodings.xml | 4 ++++ xml/System.Web/HttpCacheVaryByHeaders.xml | 5 ++++- xml/System.Web/HttpCacheVaryByParams.xml | 5 ++++- 9 files changed, 37 insertions(+), 4 deletions(-) diff --git a/xml/System.Web.Caching/OutputCache.xml b/xml/System.Web.Caching/OutputCache.xml index bdbe332b6f1..e478bda5817 100644 --- a/xml/System.Web.Caching/OutputCache.xml +++ b/xml/System.Web.Caching/OutputCache.xml @@ -18,8 +18,11 @@ [!IMPORTANT] +> Output caching is a performance optimization feature. The `VaryBy` settings are designed to cache alternate representations of a resource based on request characteristics; they are not designed to isolate audiences or classes of content. Do not rely on cache variation to separate personalized, tenant-specific, authorization-dependent, or otherwise sensitive responses. Enforce any required isolation between request contexts independently of the cache configuration. The class enables you to extend output caching. For example, you can configure one or more custom output-cache providers that target other storage devices such as local or remote disks, databases, cloud storage, and distributed cache engines. diff --git a/xml/System.Web.Configuration/OutputCacheProfile.xml b/xml/System.Web.Configuration/OutputCacheProfile.xml index 74691026946..d1030068e92 100644 --- a/xml/System.Web.Configuration/OutputCacheProfile.xml +++ b/xml/System.Web.Configuration/OutputCacheProfile.xml @@ -20,6 +20,10 @@ [!IMPORTANT] +> Output caching is a performance optimization feature. The `VaryBy` settings are designed to cache alternate representations of a resource based on request characteristics; they are not designed to isolate audiences or classes of content. Do not rely on cache variation to separate personalized, tenant-specific, authorization-dependent, or otherwise sensitive responses. Enforce any required isolation between request contexts independently of the cache configuration. + The class provides a way to programmatically access and modify the `add` element of the `outputCacheProfiles` section in the `caching` section of a configuration file. The object centralizes frequently used configuration settings such as dependencies, cache location, and cache expiration time, eliminating the need to specify them on every page. diff --git a/xml/System.Web.Configuration/OutputCacheSection.xml b/xml/System.Web.Configuration/OutputCacheSection.xml index d9dee1b17a7..1fef6b37394 100644 --- a/xml/System.Web.Configuration/OutputCacheSection.xml +++ b/xml/System.Web.Configuration/OutputCacheSection.xml @@ -20,6 +20,10 @@ [!IMPORTANT] +> Output caching is a performance optimization feature. The `VaryBy` settings are designed to cache alternate representations of a resource based on request characteristics; they are not designed to isolate audiences or classes of content. Do not rely on cache variation to separate personalized, tenant-specific, authorization-dependent, or otherwise sensitive responses. Enforce any required isolation between request contexts independently of the cache configuration. + The class allows you to programmatically access and modify the `OutputCache` section. ]]> diff --git a/xml/System.Web.UI/OutputCacheParameters.xml b/xml/System.Web.UI/OutputCacheParameters.xml index 3ea06644242..4a03ed4f55b 100644 --- a/xml/System.Web.UI/OutputCacheParameters.xml +++ b/xml/System.Web.UI/OutputCacheParameters.xml @@ -20,6 +20,10 @@ [!IMPORTANT] +> Output caching is a performance optimization feature. The `VaryBy` settings are designed to cache alternate representations of a resource based on request characteristics; they are not designed to isolate audiences or classes of content. Do not rely on cache variation to separate personalized, tenant-specific, authorization-dependent, or otherwise sensitive responses. Enforce any required isolation between request contexts independently of the cache configuration. + The class is not used by ASP.NET page or control developers. It provides a data structure used to store cache settings parsed from an [@ OutputCache](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/hdxfb6cy(v=vs.100)) page directive by ASP.NET page and control parsers such as and . The object is used with the method to initialize the output cache for a page and its contents at run time. ]]> diff --git a/xml/System.Web.UI/PartialCachingAttribute.xml b/xml/System.Web.UI/PartialCachingAttribute.xml index 7a23ed52781..a7ac31e9ceb 100644 --- a/xml/System.Web.UI/PartialCachingAttribute.xml +++ b/xml/System.Web.UI/PartialCachingAttribute.xml @@ -27,6 +27,10 @@ [!IMPORTANT] +> Output caching is a performance optimization feature. The `VaryBy` settings are designed to cache alternate representations of a resource based on request characteristics; they are not designed to isolate audiences or classes of content. Do not rely on cache variation to separate personalized, tenant-specific, authorization-dependent, or otherwise sensitive responses. Enforce any required isolation between request contexts independently of the cache configuration. + The attribute class marks user controls (.ascx files) that support fragment caching, and encapsulates the cache settings that ASP.NET uses when caching the control. Page and controls developers use the attribute to enable output caching for a user control in a code-behind file. Using the is one of several ways you can enable output caching. The following list describes methods you can use to enable output caching. diff --git a/xml/System.Web/HttpCachePolicy.xml b/xml/System.Web/HttpCachePolicy.xml index 3716829d3a4..5100463f4d7 100644 --- a/xml/System.Web/HttpCachePolicy.xml +++ b/xml/System.Web/HttpCachePolicy.xml @@ -1345,6 +1345,10 @@ [!IMPORTANT] +> Output caching is a performance optimization feature. The `VaryBy` settings are designed to cache alternate representations of a resource based on request characteristics; they are not designed to isolate audiences or classes of content. Do not rely on cache variation to separate personalized, tenant-specific, authorization-dependent, or otherwise sensitive responses. Enforce any required isolation between request contexts independently of the cache configuration. + is introduced in the .NET Framework version 3.5. For more information, see [Versions and Dependencies](/dotnet/framework/migration-guide/versions-and-dependencies). diff --git a/xml/System.Web/HttpCacheVaryByContentEncodings.xml b/xml/System.Web/HttpCacheVaryByContentEncodings.xml index 84c0b0a654e..4e27926de7b 100644 --- a/xml/System.Web/HttpCacheVaryByContentEncodings.xml +++ b/xml/System.Web/HttpCacheVaryByContentEncodings.xml @@ -20,6 +20,10 @@ [!IMPORTANT] +> Output caching is a performance optimization feature. The `VaryBy` settings are designed to cache alternate representations of a resource based on request characteristics; they are not designed to isolate audiences or classes of content. Do not rely on cache variation to separate personalized, tenant-specific, authorization-dependent, or otherwise sensitive responses. Enforce any required isolation between request contexts independently of the cache configuration. + The property is used to specify whether dynamically compressed responses are cached. Caching dynamically compressed responses means that the cost of compression is incurred only one time, during the first request for the resource (or after an application restart) and when the cache item expires. The property of the class identifies which request header parameters ASP.NET uses to uniquely identify a variation of the response if there are multiple cached responses for a resource. This is useful when a response depends on a set of client inputs, such as headers, parameters, or content encodings. diff --git a/xml/System.Web/HttpCacheVaryByHeaders.xml b/xml/System.Web/HttpCacheVaryByHeaders.xml index b6de60eb64c..0cb638a1ad4 100644 --- a/xml/System.Web/HttpCacheVaryByHeaders.xml +++ b/xml/System.Web/HttpCacheVaryByHeaders.xml @@ -21,7 +21,10 @@ property identifies which request header parameters ASP.NET uses to uniquely identify a variation of the response when there are multiple cached responses for a resource. This is useful when a response depends on a set of client inputs, such as headers or parameters. + The property identifies which request headers ASP.NET uses to uniquely identify a variation of the response when there are multiple cached responses for a resource. This is useful when a response depends on a set of request headers. In this way, `VaryByHeaders` lets the output cache store and serve the appropriate representation of a resource for a given request. + +> [!IMPORTANT] +> Output caching is a performance optimization feature. The `VaryBy` settings are designed to cache alternate representations of a resource based on request characteristics; they are not designed to isolate audiences or classes of content. Do not rely on cache variation to separate personalized, tenant-specific, authorization-dependent, or otherwise sensitive responses. Enforce any required isolation between request contexts independently of the cache configuration. The is not directly related to HTTP cache-control headers, but helps ensure that a client or proxy varies by the specified headers. For more information about `VaryByHeaders`, see RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1, available on the [World Wide Web Consortium (W3C) Web site](https://go.microsoft.com/fwlink/?linkid=37125). See section 14, "Header Field Definitions", for complete details. diff --git a/xml/System.Web/HttpCacheVaryByParams.xml b/xml/System.Web/HttpCacheVaryByParams.xml index d6ad58aca81..6ca89c75a2c 100644 --- a/xml/System.Web/HttpCacheVaryByParams.xml +++ b/xml/System.Web/HttpCacheVaryByParams.xml @@ -21,7 +21,10 @@ property identifies which HTTP `Get` or `Post` parameters ASP.NET uses to uniquely identify a variation of the response when there are multiple cached responses for a resource. This is useful when a response depends on a set of client inputs, such as headers or parameters. + The property identifies which HTTP `GET` query string or `POST` form parameters ASP.NET uses to uniquely identify a variation of the response when there are multiple cached responses for a resource. This is useful when a response depends on a set of client inputs, such as query string values or form fields. In this way, `VaryByParams` lets the output cache store and serve the appropriate representation of a resource for a given request. + +> [!IMPORTANT] +> Output caching is a performance optimization feature. The `VaryBy` settings are designed to cache alternate representations of a resource based on request characteristics; they are not designed to isolate audiences or classes of content. Do not rely on cache variation to separate personalized, tenant-specific, authorization-dependent, or otherwise sensitive responses. Enforce any required isolation between request contexts independently of the cache configuration. The is not directly related to HTTP cache-control headers, but helps ensure that a client or proxy varies by the specified parameters. For more information about `VaryByParams`, see RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1, available on the [World Wide Web Consortium (W3C) Web](https://go.microsoft.com/fwlink/?linkid=37125) site. See section 14, "Header Field Definitions", for complete details. From fa51cfce2326f83bad28f7505a2507dd6d422ce5 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 20 Jul 2026 08:47:01 -0700 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- xml/System.Web/HttpCachePolicy.xml | 2 +- xml/System.Web/HttpCacheVaryByContentEncodings.xml | 2 +- xml/System.Web/HttpCacheVaryByHeaders.xml | 2 +- xml/System.Web/HttpCacheVaryByParams.xml | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/xml/System.Web/HttpCachePolicy.xml b/xml/System.Web/HttpCachePolicy.xml index 5100463f4d7..9191c201fb4 100644 --- a/xml/System.Web/HttpCachePolicy.xml +++ b/xml/System.Web/HttpCachePolicy.xml @@ -1349,7 +1349,7 @@ > [!IMPORTANT] > Output caching is a performance optimization feature. The `VaryBy` settings are designed to cache alternate representations of a resource based on request characteristics; they are not designed to isolate audiences or classes of content. Do not rely on cache variation to separate personalized, tenant-specific, authorization-dependent, or otherwise sensitive responses. Enforce any required isolation between request contexts independently of the cache configuration. - is introduced in the .NET Framework version 3.5. For more information, see [Versions and Dependencies](/dotnet/framework/migration-guide/versions-and-dependencies). + was introduced in .NET Framework version 3.5. For more information, see [Versions and Dependencies](/dotnet/framework/migration-guide/versions-and-dependencies). diff --git a/xml/System.Web/HttpCacheVaryByContentEncodings.xml b/xml/System.Web/HttpCacheVaryByContentEncodings.xml index 4e27926de7b..0e0f42f2d03 100644 --- a/xml/System.Web/HttpCacheVaryByContentEncodings.xml +++ b/xml/System.Web/HttpCacheVaryByContentEncodings.xml @@ -24,7 +24,7 @@ > [!IMPORTANT] > Output caching is a performance optimization feature. The `VaryBy` settings are designed to cache alternate representations of a resource based on request characteristics; they are not designed to isolate audiences or classes of content. Do not rely on cache variation to separate personalized, tenant-specific, authorization-dependent, or otherwise sensitive responses. Enforce any required isolation between request contexts independently of the cache configuration. - The property is used to specify whether dynamically compressed responses are cached. Caching dynamically compressed responses means that the cost of compression is incurred only one time, during the first request for the resource (or after an application restart) and when the cache item expires. +The property is used to specify whether dynamically compressed responses are cached. Caching dynamically compressed responses means that the cost of compression is incurred only one time, during the first request for the resource (or after an application restart) and when the cache item expires. The property of the class identifies which request header parameters ASP.NET uses to uniquely identify a variation of the response if there are multiple cached responses for a resource. This is useful when a response depends on a set of client inputs, such as headers, parameters, or content encodings. diff --git a/xml/System.Web/HttpCacheVaryByHeaders.xml b/xml/System.Web/HttpCacheVaryByHeaders.xml index 0cb638a1ad4..4014bcac062 100644 --- a/xml/System.Web/HttpCacheVaryByHeaders.xml +++ b/xml/System.Web/HttpCacheVaryByHeaders.xml @@ -21,7 +21,7 @@ property identifies which request headers ASP.NET uses to uniquely identify a variation of the response when there are multiple cached responses for a resource. This is useful when a response depends on a set of request headers. In this way, `VaryByHeaders` lets the output cache store and serve the appropriate representation of a resource for a given request. + The property identifies which request headers ASP.NET uses to uniquely identify a variation of the response when there are multiple cached responses for a resource. This is useful when a response depends on a set of request headers. In this way, `VaryByHeaders` lets the output cache store and serve the appropriate representation of a resource for a given request. > [!IMPORTANT] > Output caching is a performance optimization feature. The `VaryBy` settings are designed to cache alternate representations of a resource based on request characteristics; they are not designed to isolate audiences or classes of content. Do not rely on cache variation to separate personalized, tenant-specific, authorization-dependent, or otherwise sensitive responses. Enforce any required isolation between request contexts independently of the cache configuration. diff --git a/xml/System.Web/HttpCacheVaryByParams.xml b/xml/System.Web/HttpCacheVaryByParams.xml index 6ca89c75a2c..7a36e945d9b 100644 --- a/xml/System.Web/HttpCacheVaryByParams.xml +++ b/xml/System.Web/HttpCacheVaryByParams.xml @@ -21,7 +21,7 @@ property identifies which HTTP `GET` query string or `POST` form parameters ASP.NET uses to uniquely identify a variation of the response when there are multiple cached responses for a resource. This is useful when a response depends on a set of client inputs, such as query string values or form fields. In this way, `VaryByParams` lets the output cache store and serve the appropriate representation of a resource for a given request. + The property identifies which HTTP `GET` query string or `POST` form parameters ASP.NET uses to uniquely identify a variation of the response when there are multiple cached responses for a resource. This is useful when a response depends on a set of client inputs, such as query string values or form fields. In this way, `VaryByParams` lets the output cache store and serve the appropriate representation of a resource for a given request. > [!IMPORTANT] > Output caching is a performance optimization feature. The `VaryBy` settings are designed to cache alternate representations of a resource based on request characteristics; they are not designed to isolate audiences or classes of content. Do not rely on cache variation to separate personalized, tenant-specific, authorization-dependent, or otherwise sensitive responses. Enforce any required isolation between request contexts independently of the cache configuration.