EncodingProvider.GetEncoding Method

Definition

Namespace:

System.Text

Assembly:

System.Runtime.dll

Returns an encoding.

Overloads

GetEncoding(Int32)	Returns the encoding associated with the specified code page identifier.
GetEncoding(String)	Returns the encoding with the specified name.
GetEncoding(Int32, EncoderFallback, DecoderFallback)	Returns the encoding associated with the specified code page identifier. Parameters specify an error handler for characters that cannot be encoded and byte sequences that cannot be decoded.
GetEncoding(String, EncoderFallback, DecoderFallback)	Returns the encoding associated with the specified name. Parameters specify an error handler for characters that cannot be encoded and byte sequences that cannot be decoded.

GetEncoding(Int32)

Source:

EncodingProvider.cs

Returns the encoding associated with the specified code page identifier.

public:
 abstract System::Text::Encoding ^ GetEncoding(int codepage);

public abstract System.Text.Encoding? GetEncoding (int codepage);

abstract member GetEncoding : int -> System.Text.Encoding

Public MustOverride Function GetEncoding (codepage As Integer) As Encoding

Parameters

codepage

Int32

The code page identifier of the requested encoding.

Returns

Encoding

The encoding that is associated with the specified code page, or null if this EncodingProvider cannot return a valid encoding that corresponds to codepage.

Remarks

Notes to callers

This method is called by the Encoding.GetEncoding(Int32) method. You should not call it directly from user code.

Notes to Implementers

You override the GetEncoding(Int32) method to return the encoding or encodings supported by your EncodingProvider subclass. When user code attempts to retrieve an encoding by calling the GetEncoding(Int32) method, the method passes the codepage identifier to every registered encoding provider until one returns a valid encoding. If none returns a valid encoding, the GetEncoding(Int32) method attempts to retrieve a cached encoding whose code page identifier is codepage. Because of this, if codepage is not the code page identifier of an encoding that you support, the method should return null; it should never throw an exception.

Notes to Callers

This method is called by the GetEncoding(Int32) method. You should not call it directly from user code.

See also

• GetEncoding(Int32)

GetEncoding(String)

Source:

EncodingProvider.cs

Returns the encoding with the specified name.

public:
 abstract System::Text::Encoding ^ GetEncoding(System::String ^ name);

public abstract System.Text.Encoding? GetEncoding (string name);

abstract member GetEncoding : string -> System.Text.Encoding

Public MustOverride Function GetEncoding (name As String) As Encoding

Parameters

name

String

The name of the requested encoding.

Returns

Encoding

The encoding that is associated with the specified name, or null if this EncodingProvider cannot return a valid encoding that corresponds to name.

Remarks

Notes to inheritors

You override the GetEncoding(String) method to return the encoding or encodings supported by your EncodingProvider subclass. When user code attempts to retrieve an encoding by calling the GetEncoding(String) method, the method passes the name argument to every registered encoding provider until one returns a valid encoding. If none returns a valid encoding, the GetEncoding(String) method attempts to retrieve a cached encoding whose name is name. Because of this, if name is not the name of an encoding that you support, the method should return null. The only case in which the method should throw an exception is if name is null.

Notes to callers

This method is called by the Encoding.GetEncoding(String) method. You should not call it directly from user code.

Notes to Implementers

You override the GetEncoding(String) method to return the encoding or encodings supported by your EncodingProvider subclass. When user code attempts to retrieve an encoding by calling the GetEncoding(String) method, the method passes the name argument to every registered encoding provider until one returns a valid encoding. If none returns a valid encoding, the GetEncoding(String) method attempts to retrieve a cached encoding whose name is name. Because of this, if name is not the name of an encoding that you support, the method should return null. The only case in which the method should throw an exception is if name is null.

Notes to Callers

This method is called by the GetEncoding(String) method. You should not call it directly from user code.

See also

• GetEncoding(String)

GetEncoding(Int32, EncoderFallback, DecoderFallback)

Source:

EncodingProvider.cs

Returns the encoding associated with the specified code page identifier. Parameters specify an error handler for characters that cannot be encoded and byte sequences that cannot be decoded.

public:
 virtual System::Text::Encoding ^ GetEncoding(int codepage, System::Text::EncoderFallback ^ encoderFallback, System::Text::DecoderFallback ^ decoderFallback);

public virtual System.Text.Encoding? GetEncoding (int codepage, System.Text.EncoderFallback encoderFallback, System.Text.DecoderFallback decoderFallback);

abstract member GetEncoding : int * System.Text.EncoderFallback * System.Text.DecoderFallback -> System.Text.Encoding
override this.GetEncoding : int * System.Text.EncoderFallback * System.Text.DecoderFallback -> System.Text.Encoding

Public Overridable Function GetEncoding (codepage As Integer, encoderFallback As EncoderFallback, decoderFallback As DecoderFallback) As Encoding

Parameters

codepage

Int32

The code page identifier of the requested encoding.

encoderFallback

EncoderFallback

An object that provides an error-handling procedure when a character cannot be encoded with this encoding.

decoderFallback

DecoderFallback

An object that provides an error-handling procedure when a byte sequence cannot be decoded with this encoding.

Returns

Encoding

The encoding that is associated with the specified code page, or null if this EncodingProvider cannot return a valid encoding that corresponds to codepage.

Remarks

The encoderFallback and decoderFallback parameters are objects that define the fallback strategy used in the event that an encoder cannot convert a character to a sequence of bytes or a decoder cannot convert a sequence of bytes to a character. The .NET Framework provides the following fallback mechanisms:

• Exception fallback. If the encoderFallback argument is an instance of EncoderExceptionFallback, or the decoderExceptionFallback argument is an instance of DecoderExceptionFallback, the encoding method throws an exception if characters cannot be encoded, and the decoding method throws an exception if a byte sequence cannot be decoded.

• Replacement fallback. If the encoderFallback argument is an instance of EncoderReplacementFallback, or the decoderExceptionFallback argument is an instance of DecoderReplacementFallback, the encoding and decoding methods substitute a replacement string for characters that cannot be encoded and byte sequences cannot be decoded. If you instantiated the replacement fallback object by calling the parameterless constructor, the replacement character is a "?". If you call the EncoderReplacementFallback.EncoderReplacementFallback(String) or DecoderReplacementFallback.DecoderReplacementFallback(String) constructor, you can specify the replacement string.

• Best-fit fallback. You can derive from the EncoderFallback or DecoderFallback class to implement a best-fit replacement mechanism.

Notes to Inheritors

Because calls to this method use your implementation of the GetEncoding(Int32) method, you do not have to override it. When user code attempts to retrieve an encoding by calling the GetEncoding(Int32, EncoderFallback, DecoderFallback) method, the method passes the codepage identifier to every registered encoding provider until one returns a valid encoding. If none returns a valid encoding, the GetEncoding(Int32) method attempts to retrieve a cached encoding whose code page identifier is codepage. Because of this, if you do choose to override the GetEncoding(Int32, EncoderFallback, DecoderFallback) method, your override should return null if codepage is not the code page identifier of an encoding that you support; it should never throw an exception.

Notes to Callers

This method is called by the GetEncoding(Int32, EncoderFallback, DecoderFallback) method. You should not call it directly from user code.

See also

• GetEncoding(Int32, EncoderFallback, DecoderFallback)

GetEncoding(String, EncoderFallback, DecoderFallback)

Source:

EncodingProvider.cs

Returns the encoding associated with the specified name. Parameters specify an error handler for characters that cannot be encoded and byte sequences that cannot be decoded.

public:
 virtual System::Text::Encoding ^ GetEncoding(System::String ^ name, System::Text::EncoderFallback ^ encoderFallback, System::Text::DecoderFallback ^ decoderFallback);

public virtual System.Text.Encoding? GetEncoding (string name, System.Text.EncoderFallback encoderFallback, System.Text.DecoderFallback decoderFallback);

abstract member GetEncoding : string * System.Text.EncoderFallback * System.Text.DecoderFallback -> System.Text.Encoding
override this.GetEncoding : string * System.Text.EncoderFallback * System.Text.DecoderFallback -> System.Text.Encoding

Public Overridable Function GetEncoding (name As String, encoderFallback As EncoderFallback, decoderFallback As DecoderFallback) As Encoding

Parameters

name

String

The name of the preferred encoding.

encoderFallback

EncoderFallback

An object that provides an error-handling procedure when a character cannot be encoded with this encoding.

decoderFallback

DecoderFallback

An object that provides an error-handling procedure when a byte sequence cannot be decoded with the current encoding.

Returns

Encoding

The encoding that is associated with the specified name, or null if this EncodingProvider cannot return a valid encoding that corresponds to name.

Remarks

The encoderFallback and decoderFallback parameters are objects that define the fallback strategy used in the event that an encoder cannot convert a character to a sequence of bytes or a decoder cannot convert a sequence of bytes to a character. The .NET Framework provides the following fallback mechanisms:

• Exception fallback. If the encoderFallback argument is an instance of EncoderExceptionFallback, or the decoderExceptionFallback argument is an instance of DecoderExceptionFallback, the encoding method throws an exception if characters cannot be encoded, and the decoding method throws an exception if a byte sequence cannot be decoded.

• Replacement fallback. If the encoderFallback argument is an instance of EncoderReplacementFallback, or the decoderExceptionFallback argument is an instance of DecoderReplacementFallback, the encoding and decoding methods substitute a replacement string for characters that cannot be encoded and byte sequences cannot be decoded. If you instantiated the replacement fallback object by calling the parameterless constructor, the replacement character is a "?". If you call the EncoderReplacementFallback.EncoderReplacementFallback(String) or DecoderReplacementFallback.DecoderReplacementFallback(String) constructor, you can specify the replacement string.

• Best-fit fallback. You can derive from the EncoderFallback or DecoderFallback class to implement a best-fit replacement mechanism.

Notes to Inheritors

Because calls to this method use your implementation of the GetEncoding(String) method, you do not have to override it. When user code attempts to retrieve an encoding by calling the GetEncoding(String, EncoderFallback, DecoderFallback) method, the method passes the codepage identifier to every registered encoding provider until one returns a valid encoding. If none returns a valid encoding, the GetEncoding(Int32) method attempts to retrieve a cached encoding whose code page identifier is codepage. Because of this, if you do choose to override the GetEncoding(Int32, EncoderFallback, DecoderFallback) method, your override should return null if codepage is not the code page identifier of an encoding that you support; it should never throw an exception.

Notes to Callers

This method is called by the GetEncoding(String, EncoderFallback, DecoderFallback) method. You should not call it directly from user code.

See also

• GetEncoding(String, EncoderFallback, DecoderFallback)