Clarify OutputCache intent and limitations for classic ASP.Net.#12886
Open
StephenMolloy wants to merge 1 commit into
Open
Clarify OutputCache intent and limitations for classic ASP.Net.#12886StephenMolloy wants to merge 1 commit into
StephenMolloy wants to merge 1 commit into
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This pull request updates the classic ASP.NET (System.Web) API reference XML to clarify the intent and limitations of output caching variation (VaryBy*), emphasizing that it’s a performance optimization mechanism and must not be treated as a security/isolation boundary.
Changes:
- Added prominent
[!IMPORTANT]warnings across output-caching-related types about not usingVaryByto isolate personalized/tenant-sensitive/authorization-dependent responses. - Refined remarks for
VaryByParamsandVaryByHeadersto better describe what request data participates in cache variation and how alternate representations are served. - Improved wording in
System.Web.Caching.OutputCacheremarks (e.g., “alternate representations”).
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| xml/System.Web/HttpCacheVaryByParams.xml | Clarifies VaryByParams behavior and adds an IMPORTANT warning about non-security usage. |
| xml/System.Web/HttpCacheVaryByHeaders.xml | Clarifies VaryByHeaders behavior and adds an IMPORTANT warning about non-security usage. |
| xml/System.Web/HttpCacheVaryByContentEncodings.xml | Adds an IMPORTANT warning about non-security usage of cache variation. |
| xml/System.Web/HttpCachePolicy.xml | Adds an IMPORTANT warning in SetVaryByCustom remarks about non-security usage of cache variation. |
| xml/System.Web.UI/PartialCachingAttribute.xml | Adds an IMPORTANT warning about non-security usage of cache variation. |
| xml/System.Web.UI/OutputCacheParameters.xml | Adds an IMPORTANT warning about non-security usage of cache variation. |
| xml/System.Web.Configuration/OutputCacheSection.xml | Adds an IMPORTANT warning about non-security usage of cache variation. |
| xml/System.Web.Configuration/OutputCacheProfile.xml | Adds an IMPORTANT warning about non-security usage of cache variation. |
| xml/System.Web.Caching/OutputCache.xml | Refines remarks wording and adds an IMPORTANT warning about non-security usage of cache variation. |
|
|
||
| ## Remarks | ||
| The <xref:System.Web.HttpCachePolicy.VaryByParams%2A> 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 <xref:System.Web.HttpCachePolicy.VaryByParams%2A> 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. |
|
|
||
| ## Remarks | ||
| The <xref:System.Web.HttpCachePolicy.VaryByHeaders%2A> 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 <xref:System.Web.HttpCachePolicy.VaryByHeaders%2A> 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. |
Comment on lines
+24
to
27
| > [!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 <xref:System.Web.HttpCachePolicy.VaryByContentEncodings%2A> 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. |
| > [!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. | ||
|
|
||
| <xref:System.Web.HttpCachePolicy.SetVaryByCustom%2A> is introduced in the .NET Framework version 3.5. For more information, see [Versions and Dependencies](/dotnet/framework/migration-guide/versions-and-dependencies). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request updates the XML documentation for several ASP.NET output caching-related types to clarify the intended use and limitations of the
VaryBysettings. The main focus is to add prominent warnings that output caching and its variation mechanisms are meant for performance optimization and not for isolating personalized or sensitive content. Additional clarifications are also made to some remarks for better accuracy.Documentation improvements and warnings
Security and usage warnings:
[!IMPORTANT]note to the remarks of all affected types, explaining that output caching andVaryBysettings are for performance optimization only, and should not be relied upon to isolate personalized, tenant-specific, authorization-dependent, or sensitive responses. Explicit isolation must be enforced independently of cache configuration. [1] [2] [3] [4] [5] [6] [7] [8] [9]Clarifications to remarks:
VaryByHeadersandVaryByParamswork, specifying that they store and serve the appropriate representation of a resource for a given request, and clarifying the types of request data used for variation. [1] [2]OutputCache.xmlremarks to use "alternate representations" instead of "different versions" for greater precision.These changes help prevent misuse of output caching for security or isolation, and make the documentation clearer for developers.