HttpCacheVaryByContentEncodings.xml

<Type Name="HttpCacheVaryByContentEncodings" FullName="System.Web.HttpCacheVaryByContentEncodings">
  <TypeSignature Language="C#" Value="public sealed class HttpCacheVaryByContentEncodings" />
  <TypeSignature Language="ILAsm" Value=".class public auto ansi sealed beforefieldinit HttpCacheVaryByContentEncodings extends System.Object" />
  <TypeSignature Language="DocId" Value="T:System.Web.HttpCacheVaryByContentEncodings" />
  <TypeSignature Language="VB.NET" Value="Public NotInheritable Class HttpCacheVaryByContentEncodings" />
  <TypeSignature Language="F#" Value="type HttpCacheVaryByContentEncodings = class" />
  <TypeSignature Language="C++ CLI" Value="public ref class HttpCacheVaryByContentEncodings sealed" />
  <AssemblyInfo>
    <AssemblyName>System.Web</AssemblyName>
    <AssemblyVersion>2.0.0.0</AssemblyVersion>
    <AssemblyVersion>4.0.0.0</AssemblyVersion>
  </AssemblyInfo>
  <Base>
    <BaseTypeName>System.Object</BaseTypeName>
  </Base>
  <Interfaces />
  <Docs>
    <summary>Provides a type-safe way to set the <see cref="P:System.Web.HttpCachePolicy.VaryByContentEncodings" /> property of the <see cref="T:System.Web.HttpCachePolicy" /> class.</summary>
    <remarks>
      <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> 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.  
  
 The <xref:System.Web.HttpCacheVaryByContentEncodings> class is not directly related to HTTP cache-control headers. However, it helps make sure that a response to a client or a proxy varies by the specified content encoding. Setting the cache to vary by content encoding enables ASP.NET to vary the response by the `Accept-Encoding` header. When a request is processed, the `Accept-Encoding` header is checked and the first acceptable encoding is identified and used to take one of the following actions:  
  
-   If a matching encoding is also found in the <xref:System.Web.HttpCachePolicy.VaryByContentEncodings%2A> list and a cached response exists, the cached response is sent.  
  
-   If a matching encoding is also found in the <xref:System.Web.HttpCachePolicy.VaryByContentEncodings%2A> list but a cached response does not exist, a response is generated and inserted into the cache.  
  
-   If a matching encoding is not found in the <xref:System.Web.HttpCachePolicy.VaryByContentEncodings%2A> list, the cache is searched for a non-encoded response, also referred to as the identity response. If the identity response is found, it is sent. Otherwise a new non-encoded response is generated and stored in the cache.  
  
 For more information about the <xref:System.Web.HttpCachePolicy.VaryByContentEncodings%2A> property, 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.  
  
 You can set the <xref:System.Web.HttpCachePolicy.VaryByContentEncodings%2A> property by using the `@ OutputCache` directive or by adding a profile to the `outputCacheProfile` element in the Web.config file.
  
## Examples  
 The following example shows how to enable a dynamically compressed response that can be served from the output cache. The encoding that is acceptable is "gzip" and is set by using the `VaryByContentEncodings` attribute of the `@ OutputCache` directive. If the Web server that hosts the page does not have dynamic compression enabled, the output cache will not have a cached response for the specified content encoding.  
  
 :::code language="aspx-csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Web.HttpCachePolicy.VaryByContentEncodings/CS/default.aspx" id="Snippet1":::
 :::code language="aspx-vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Web.HttpCachePolicy.VaryByContentEncodings/VB/default.aspx" id="Snippet1":::  
  
 ]]></format>
    </remarks>
    <altmember cref="P:System.Web.HttpCachePolicy.VaryByContentEncodings" />
  </Docs>
  <Members>
    <Member MemberName=".ctor">
      <MemberSignature Language="C#" Value="public HttpCacheVaryByContentEncodings ();" FrameworkAlternate="netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1" />
      <MemberSignature Language="ILAsm" Value=".method public hidebysig specialname rtspecialname instance void .ctor() cil managed" FrameworkAlternate="netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1" />
      <MemberSignature Language="DocId" Value="M:System.Web.HttpCacheVaryByContentEncodings.#ctor" FrameworkAlternate="netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1" />
      <MemberSignature Language="VB.NET" Value="Public Sub New ()" FrameworkAlternate="netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1" />
      <MemberSignature Language="C++ CLI" Value="public:&#xA; HttpCacheVaryByContentEncodings();" FrameworkAlternate="netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1" />
      <MemberType>Constructor</MemberType>
      <AssemblyInfo>
        <AssemblyName>System.Web</AssemblyName>
        <AssemblyVersion>4.0.0.0</AssemblyVersion>
      </AssemblyInfo>
      <Parameters />
      <Docs>
        <summary>Initializes a new instance of the <see cref="T:System.Web.HttpCacheVaryByContentEncodings" /> class.</summary>
        <remarks>To be added.</remarks>
      </Docs>
    </Member>
    <Member MemberName="GetContentEncodings">
      <MemberSignature Language="C#" Value="public string[] GetContentEncodings ();" FrameworkAlternate="netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1" />
      <MemberSignature Language="ILAsm" Value=".method public hidebysig instance string[] GetContentEncodings() cil managed" FrameworkAlternate="netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1" />
      <MemberSignature Language="DocId" Value="M:System.Web.HttpCacheVaryByContentEncodings.GetContentEncodings" FrameworkAlternate="netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1" />
      <MemberSignature Language="VB.NET" Value="Public Function GetContentEncodings () As String()" FrameworkAlternate="netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1" />
      <MemberSignature Language="C++ CLI" Value="public:&#xA; cli::array &lt;System::String ^&gt; ^ GetContentEncodings();" FrameworkAlternate="netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1" />
      <MemberSignature Language="F#" Value="member this.GetContentEncodings : unit -&gt; string[]" Usage="httpCacheVaryByContentEncodings.GetContentEncodings " FrameworkAlternate="netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1" />
      <MemberType>Method</MemberType>
      <AssemblyInfo>
        <AssemblyName>System.Web</AssemblyName>
        <AssemblyVersion>4.0.0.0</AssemblyVersion>
      </AssemblyInfo>
      <ReturnValue>
        <ReturnType FrameworkAlternate="netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1">System.String[]</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>Gets an array of values which specify the content encodings to be used for varying the cache.</summary>
        <returns>An array of values which contain the content encodings for varying the cache.</returns>
        <remarks>To be added.</remarks>
      </Docs>
    </Member>
    <Member MemberName="Item">
      <MemberSignature Language="C#" Value="public bool this[string contentEncoding] { get; set; }" />
      <MemberSignature Language="ILAsm" Value=".property instance bool Item(string)" />
      <MemberSignature Language="DocId" Value="P:System.Web.HttpCacheVaryByContentEncodings.Item(System.String)" />
      <MemberSignature Language="VB.NET" Value="Default Public Property Item(contentEncoding As String) As Boolean" />
      <MemberSignature Language="F#" Value="member this.Item(string) : bool with get, set" Usage="System.Web.HttpCacheVaryByContentEncodings.Item" />
      <MemberSignature Language="C++ CLI" Value="public:&#xA; property bool default[System::String ^] { bool get(System::String ^ contentEncoding); void set(System::String ^ contentEncoding, bool value); };" />
      <MemberType>Property</MemberType>
      <AssemblyInfo>
        <AssemblyName>System.Web</AssemblyName>
        <AssemblyVersion>2.0.0.0</AssemblyVersion>
        <AssemblyVersion>4.0.0.0</AssemblyVersion>
      </AssemblyInfo>
      <ReturnValue>
        <ReturnType>System.Boolean</ReturnType>
      </ReturnValue>
      <Parameters>
        <Parameter Name="contentEncoding" Type="System.String" />
      </Parameters>
      <Docs>
        <param name="contentEncoding">The name of the content encoding.</param>
        <summary>Gets or sets a value that indicates whether the cache varies according to the specified content encoding.</summary>
        <value>
          <see langword="true" /> if the cache should vary by the specified content encoding; otherwise, <see langword="false" />.</value>
        <remarks>To be added.</remarks>
        <exception cref="T:System.ArgumentNullException">The content encoding is <see langword="null" />.</exception>
      </Docs>
    </Member>
    <Member MemberName="SetContentEncodings">
      <MemberSignature Language="C#" Value="public void SetContentEncodings (string[] contentEncodings);" />
      <MemberSignature Language="ILAsm" Value=".method public hidebysig instance void SetContentEncodings(string[] contentEncodings) cil managed" />
      <MemberSignature Language="DocId" Value="M:System.Web.HttpCacheVaryByContentEncodings.SetContentEncodings(System.String[])" />
      <MemberSignature Language="VB.NET" Value="Public Sub SetContentEncodings (contentEncodings As String())" />
      <MemberSignature Language="F#" Value="member this.SetContentEncodings : string[] -&gt; unit" Usage="httpCacheVaryByContentEncodings.SetContentEncodings contentEncodings" />
      <MemberSignature Language="C++ CLI" Value="public:&#xA; void SetContentEncodings(cli::array &lt;System::String ^&gt; ^ contentEncodings);" />
      <MemberType>Method</MemberType>
      <AssemblyInfo>
        <AssemblyName>System.Web</AssemblyName>
        <AssemblyVersion>4.0.0.0</AssemblyVersion>
      </AssemblyInfo>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters>
        <Parameter Name="contentEncodings" Type="System.String[]" Index="0" FrameworkAlternate="netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1" />
      </Parameters>
      <Docs>
        <param name="contentEncodings">An array of values which contain the content encodings for varying the cache.</param>
        <summary>Sets an array of values which specify the content encodings to be used for varying the cache.</summary>
        <remarks>To be added.</remarks>
      </Docs>
    </Member>
  </Members>
</Type>