Article
11/18/2011

Encoding.GetEncoding Method

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Returns the encoding associated with the specified name.

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

Syntax

'Declaration
Public Shared Function GetEncoding ( _
    name As String _
) As Encoding

public static Encoding GetEncoding(
    string name
)

Parameters

name
Type: System.String
The name of the preferred encoding.

Return Value

Type: System.Text.Encoding
The object associated with the specified name.

Exceptions

Exception	Condition
ArgumentException	name is not the name of a valid encoding.

Remarks

The following table lists valid values for the name parameter. Except for "utf-16LE", they correspond to the strings returned by each encoding's WebName property.

Name	Encoding
utf-8	UTF8Encoding
utf-16	UnicodeEncoding (little-endian)
utf-16BE	UnicodeEncoding (big-endian)
utf-16LE	UnicodeEncoding (little-endian)

The name parameter is not case-sensitive. For example, the method returns a UnicodeEncoding object if name is either "utf-16" or 'UTF-16".

GetEncoding returns a cached instance with default settings. To get an instance with different settings, call the appropriate constructors of derived classes. For example, the UnicodeEncoding class provides a constructor that allows enabling of error detection.

Platform Notes

Silverlight for Windows Phone

If you pass an invalid code page name to GetEncoding, the method throws PlatformNotSupportedException instead of ArgumentException.

Examples

The following example instantiates several encoding objects, including two that are returned by the GetEncoding method. It then checks them for equality.

Imports System.Text

Public Class Example

   Public Shared Sub Demo(ByVal outputBlock As System.Windows.Controls.TextBlock)
      ' Get a UTF-16 encoding.
      Dim e16_1 As Encoding = Encoding.GetEncoding("utf-16")

      ' Instantiate a second UTF-16 encoding.
      Dim e16_2 As Encoding = New UnicodeEncoding()

      ' Instantiate a Unicode little endian encoding.
      Dim le As Encoding = New UnicodeEncoding(False, True)

      ' Instantiate a Unicode big endian encoding.
      Dim be As Encoding = New UnicodeEncoding(True, True)

      ' Get a UTF-8 encoding by name.
      Dim e8 As Encoding = Encoding.GetEncoding("utf-8")

      ' Check equality of e16_1 and e16_2.
      outputBlock.Text &= String.Format("{0} equals {1}? {2}", _
                                        e16_1.WebName, e16_2.WebName, _ 
                                        e16_1.Equals(e16_2)) & vbCrLf

      ' Check equality of e16_1 and unicode little endian encoding.
      outputBlock.Text &= String.Format("{0} equals {1}? {2}", _
                                        e16_1.WebName, le.WebName, _
                                        e16_1.Equals(le)) & vbCrLf

      ' Check equality of e16_1 and unicode bug endian encoding.
      outputBlock.Text &= String.Format("{0} equals {1}? {2}", _
                                        e16_1.WebName, be.WebName, _ 
                                        e16_1.Equals(be)) & vbCrLf

      ' Check equality of e16_1 and e8.
      outputBlock.Text &= String.Format("{0} equals {1}? {2}", _
                                        e16_1.WebName, e8.WebName, _ 
                                        e16_1.Equals(e8)) & vbCrLf
   End Sub
End Class
' This example produces the following output.
'       utf-16 equals utf-16? True
'       utf-16 equals utf-16? True
'       utf-16 equals utf16BE? False
'       utf-16 equals utf8? False

using System;
using System.Text;

public class Example
{
   public static void Demo(System.Windows.Controls.TextBlock outputBlock)
   {
      // Get a UTF-16 encoding.
      Encoding e16_1 = Encoding.GetEncoding("utf-16");

      // Instantiate a second UTF-16 encoding.
      Encoding e16_2 = new UnicodeEncoding();

      // Instantiate a Unicode little endian encoding.
      Encoding le = new UnicodeEncoding(false, true);

      // Instantiate a Unicode big endian encoding.
      Encoding be = new UnicodeEncoding(true, true);

      // Get a UTF-8 encoding by name.
      Encoding e8 = Encoding.GetEncoding("utf-8");

      // Check equality of e16_1 and e16_2.
      outputBlock.Text += String.Format("{0} equals {1}? {2}\n", 
                                        e16_1.WebName, e16_2.WebName, 
                                        e16_1.Equals(e16_2));

      // Check equality of e16_1 and unicode little endian encoding.
      outputBlock.Text += String.Format("{0} equals {1}? {2}\n", 
                                        e16_1.WebName, le.WebName, 
                                        e16_1.Equals(le));

      // Check equality of e16_1 and unicode bug endian encoding.
      outputBlock.Text += String.Format("{0} equals {1}? {2}\n", 
                                        e16_1.WebName, be.WebName, 
                                        e16_1.Equals(be));

      // Check equality of e16_1 and e8.
      outputBlock.Text += String.Format("{0} equals {1}? {2}\n", 
                                        e16_1.WebName, e8.WebName, 
                                        e16_1.Equals(e8));
   }

}


/* 
This example produces the following output:
   utf-16 equals utf-16? True
   utf-16 equals utf-16? True
   utf-16 equals utf16BE? False
   utf-16 equals utf8? False
*/

Version Information

Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

XNA Framework

Supported in: Xbox 360, Windows Phone OS 7.0

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.