Clarify OutputCache intent and limitations for classic ASP.Net.

Author: StephenMolloy

xml/System.Web.Caching/OutputCache.xml

@@ -18,8 +18,11 @@
     <remarks>
       <format type="text/markdown"><![CDATA[  
   
-## Remarks  
- Output caching stores the generated output of pages, controls, and HTTP responses in memory. Output caching enables you to cache different versions of content depending on the query string and on form-post parameters to a page, on browser type, or on the language of the user. You can configure ASP.NET to cache an output-cache entry for a specific period. You can also configure ASP.NET to evict a cache entry automatically based on an external event such as changes in the database that the cache depends on.  
+## Remarks
+ Output caching stores the generated output of pages, controls, and HTTP responses in memory. Output caching enables you to cache alternate representations of content depending on the query string and form-post parameters to a page, on browser type, or on the language of the user. You can configure ASP.NET to cache an output-cache entry for a specific period. You can also configure ASP.NET to evict a cache entry automatically based on an external event such as changes in the database that the cache depends on.
+
+> [!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.Caching.OutputCache> 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.  
   

xml/System.Web.Configuration/OutputCacheProfile.xml

@@ -20,6 +20,10 @@
       <format type="text/markdown"><![CDATA[
 
 ## Remarks
+
+> [!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.Configuration.OutputCacheProfile> 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 <xref:System.Web.Configuration.OutputCacheProfile> object centralizes frequently used configuration settings such as dependencies, cache location, and cache expiration time, eliminating the need to specify them on every page.

xml/System.Web.Configuration/OutputCacheSection.xml

@@ -20,6 +20,10 @@
       <format type="text/markdown"><![CDATA[
 
 ## Remarks
+
+> [!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.Configuration.OutputCacheSection> class allows you to programmatically access and modify the `OutputCache` section.
 
  ]]></format>

xml/System.Web.UI/OutputCacheParameters.xml

@@ -20,6 +20,10 @@
       <format type="text/markdown"><![CDATA[  
   
 ## Remarks  
+  
+> [!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.UI.OutputCacheParameters> 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 <xref:System.Web.UI.PageParser> and <xref:System.Web.UI.TemplateControlParser>. The <xref:System.Web.UI.OutputCacheParameters> object is used with the <xref:System.Web.UI.Page.InitOutputCache%2A?displayProperty=nameWithType> method to initialize the output cache for a page and its contents at run time.  
   
  ]]></format>

xml/System.Web.UI/PartialCachingAttribute.xml

@@ -27,6 +27,10 @@
       <format type="text/markdown"><![CDATA[  
   
 ## Remarks  
+  
+> [!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.UI.PartialCachingAttribute> 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 <xref:System.Web.UI.PartialCachingAttribute> attribute to enable output caching for a user control in a code-behind file.  
   
  Using the <xref:System.Web.UI.PartialCachingAttribute> is one of several ways you can enable output caching. The following list describes methods you can use to enable output caching.  

xml/System.Web/HttpCachePolicy.xml

@@ -1345,6 +1345,10 @@
           <format type="text/markdown"><![CDATA[  
   
 ## Remarks  
+  
+> [!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).  
   
    

xml/System.Web/HttpCacheVaryByContentEncodings.xml

@@ -20,6 +20,10 @@
       <format type="text/markdown"><![CDATA[  
   
 ## Remarks  
+  
+> [!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.  
   
  The <xref:System.Web.HttpCachePolicy.VaryByContentEncodings%2A> property of the <xref:System.Web.HttpCachePolicy> 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.  

xml/System.Web/HttpCacheVaryByHeaders.xml

@@ -21,7 +21,10 @@
       <format type="text/markdown"><![CDATA[  
   
 ## 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 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. 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 <xref:System.Web.HttpCacheVaryByHeaders> 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.  
   

xml/System.Web/HttpCacheVaryByParams.xml

@@ -21,7 +21,10 @@
       <format type="text/markdown"><![CDATA[  
   
 ## 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` 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. 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 <xref:System.Web.HttpCacheVaryByParams> 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.