This documentation is archived and is not being maintained.

HttpEncoder Class

Implements the core encoding and decoding logic used by ASP.NET.


Namespace:  System.Web.Util
Assembly:  System.Web (in System.Web.dll)

public class HttpEncoder

The HttpEncoder type exposes the following members.

Public methodHttpEncoderInitializes a new instance of the HttpEncoder class.

Public propertyStatic memberCurrentGets or set the HttpEncoder type that will be used in an application.
Public propertyStatic memberDefaultGets a reference to the default encoder for ASP.NET.

Public methodEquals(Object)Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodGetHashCodeServes as a hash function for a particular type. (Inherited from Object.)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Protected methodHeaderNameValueEncodeEncodes a header name and value into a string that can be used as an HTTP header.
Protected methodHtmlAttributeEncodeEncodes an incoming value into a string that can be inserted into an HTML attribute that is delimited by using double quotation marks.
Protected methodHtmlDecodeDecodes a value from an HTML-encoded string.
Protected methodHtmlEncodeEncodes a string into an HTML-encoded string.
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)
Protected methodUrlEncodeEncodes an array of characters that are not allowed in a URL into a hexadecimal character-entity equivalent.
Protected methodUrlPathEncodeEncodes a subsection of a URL.

The default ASP.NET implementation for encoding and decoding is the HttpEncoder class. The class contains the core encoding and decoding logic that is used by methods in classes such as HttpUtility, HttpServerUtility, and HttpResponseHeader.

You can inherit from the HttpEncoder class and override its behavior to customize the default encoder/decoder behavior of ASP.NET. You then set the EncoderType property of the HttpRuntimeSection class to configure your custom encoding/decoding class.

Because the HttpEncoder class contains the default base ASP.NET encoding functionality, a custom encoder/decoder class that derives from it can override the built-in ASP.NET encoder/decoder behavior or change only selected aspects of it.

You can configure the custom encoding type for in ASP.NET to replace or supplement the following encoding behavior:

  • HTML encoding

  • HTML attribute encoding

  • URL encoding

  • URL path encoding

  • HTTP header name and header value encoding

Notes to Inheritors

When you create a custom encoder class and override the base methods, the derived encoder might throw an exception from any of the overridden methods. However, in the following cases throwing such an exception could lead to unexpected behavior in ASP.NET:

  • If ASP.NET is rendering an error page that is caused by an unhandled exception that was thrown from a custom encoder, ASP.NET does not attempt to encode its error output by calling into the custom encoder. If you allow this, an unhandled exception occurs from the unhandled exception that is the handling error path. To prevent this behavior, the ASP.NET error page always uses the ASP.NET default encoder.

  • When ASP.NET is sending HTTP headers to IIS, ASP.NET does not expect unhandled exceptions to occur. Therefore, the standard ASP.NET error page will be rendered (if configuration settings allows this page to be displayed).

The following example shows how to create a custom encoder that routes HTML encoding calls into methods of the anti-XSS library’s Microsoft.Security.Application.AntiXSS type. The anti-XSS library is available for download from

[Visual Basic]

Imports System 
Imports System.Web 
Imports System.Web.Util 
Imports Microsoft.Security.Application 

Public Class AntiXssEncoder Inherits HttpEncoder 
    Public Sub New()
    End Sub 
    Protected Overloads Overrides Sub HtmlEncode(ByVal value As String, _
            ByVal output As System.IO.TextWriter)
    End Sub 

    Protected Overloads Overrides Sub HtmlAttributeEncode(ByVal _
            value As String, ByVal output As System.IO.TextWriter) 
    End Sub
End Class


using System;
using System.Web;
using System.Web.Util;
using Microsoft.Security.Application;

public class AntiXssEncoder : HttpEncoder
    public AntiXssEncoder() { }
    protected override void HtmlEncode(string value, 
        System.IO.TextWriter output)

    protected override void HtmlAttributeEncode(string value,
        System.IO.TextWriter output)

After you have added this code to an application, you can configure the application to use the custom HTTP encoder. The following example from a Web.config file shows how to configure ASP.NET to use the custom http encoder.

<httpRuntime  encoderType="AntiXssEncoder" />

Only one custom encoding type can be configured per application.

.NET Framework

Supported in: 4

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.