This documentation is archived and is not being maintained.

DecoderFallback Class

Provides a failure-handling mechanism, called a fallback, for an encoded input byte sequence that cannot be converted to an output character.

Namespace:  System.Text
Assembly:  mscorlib (in mscorlib.dll)

public abstract class DecoderFallback

The DecoderFallback type exposes the following members.

Protected methodDecoderFallbackInitializes a new instance of the DecoderFallback class.

Public propertyStatic memberExceptionFallbackGets an object that throws an exception when an input byte sequence cannot be decoded.
Public propertyMaxCharCountWhen overridden in a derived class, gets the maximum number of characters the current DecoderFallback object can return.
Public propertyStatic memberReplacementFallbackGets an object that outputs a substitute string in place of an input byte sequence that cannot be decoded.

Public methodCreateFallbackBufferWhen overridden in a derived class, initializes a new instance of the DecoderFallbackBuffer class.
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 methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)

An encoding maps a Unicode character to an encoded sequence of bytes. A particular encoding is represented by a type that is derived from the Encoding class. Specifically, a character is encoded to a byte sequence by calling the encoding type's Encoding.GetBytes(String) method, and the byte sequence is decoded to a character array or a string by calling the Encoding.GetChars(Byte[]) or Encoding.GetString(Byte[]) method.

A decoding operation can fail if the input byte sequence cannot be mapped by the encoding. For example, an ASCIIEncoding object cannot decode a byte sequence if that sequence represents a character that has a code point value that is outside the range U+0000 to U+007F.

When a decoding conversion cannot be performed, the .NET Framework provides a failure-handling mechanism called a fallback. Your application can use predefined .NET Framework decoder fallbacks, or it can create a custom decoder fallback derived from the DecoderFallback and DecoderFallbackBuffer classes.

DecoderFallback and DecoderFallbackBuffer are the base classes for all decoding fallback handlers in the .NET Framework. They support the following three kinds of fallback handling mechanisms:

  • Best-fit fallback, which maps valid Unicode characters that cannot be decoded to an approximate equivalent. For example, a best-fit fallback handler for the ASCIIEncoding class might map Æ (U+00C6) to AE (U+0041 + U+0045). A best-fit fallback handler might also be implemented to transliterate one alphabet (such as Cyrillic) to another (such as Latin or Roman). The .NET Framework does not provide any public best-fit fallback implementations.

  • Replacement fallback, which replaces each character that cannot be decoded with a predefined string. The .NET Framework provides a predefined replacement fallback handler. The DecoderReplacementFallback class replaces each byte sequence that cannot be decoded with a question mark character ("?", or U+003F) or a REPLACEMENT CHARACTER (U+FFFD). You can customize the replacement string by specifying a substitute in the call to the DecoderReplacementFallback.DecoderReplacementFallback(String) constructor. After the substitute string is emitted, the decoding operation continues converting the remainder of the input.

  • Exception fallback, which throws an exception when a byte sequence cannot be decoded. The .NET Framework provides a predefined exception fallback handler. The DecoderExceptionFallback class throws a DecoderFallbackException when an invalid byte sequence is encountered, and the decoding operation terminates.

If you choose to implement a custom solution, you must override the following abstract members of the DecoderFallback class:

  • The CreateFallbackBuffer method, which returns a class instance derived from DecoderFallbackBuffer. Depending on the type of fallback handler that you are developing, the DecoderFallbackBuffer implementation is responsible for performing the mapping or replacement, or for throwing the exception.

  • The MaxCharCount property, which returns the maximum number of characters that the fallback implementation can return. For an exception fallback handler, its value should be zero.

For more information about encoding, decoding, and fallback strategies, see Character Encoding in the .NET Framework.

.NET Framework

Supported in: 4, 3.5, 3.0, 2.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, 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.