Encoding.GetPreamble Method

July 28, 2014

When overridden in a derived class, returns a sequence of bytes that specifies the encoding used.

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

public virtual byte[] GetPreamble()

Return Value

Type: System.Byte []
A byte array containing a sequence of bytes that specifies the encoding used.
-or-
A byte array of length zero, if a preamble is not required.

Optionally, the Encoding object provides a preamble that is an array of bytes that can be prefixed to the sequence of bytes resulting from the encoding process. If the preamble contains a byte order mark (in Unicode, code point U+FEFF), it helps the decoder determine the byte order and the transformation format or UTF.

The Unicode byte order mark (BOM) is serialized as follows (in hexadecimal):

  • UTF-8: EF BB BF

  • UTF-16 big-endian byte order: FE FF

  • UTF-16 little-endian byte order: FF FE

Caution noteCaution:

To ensure that the encoded bytes are decoded properly, your application should prefix encoded bytes with a preamble. However, most encodings do not provide a preamble. To ensure that the encoded bytes are decoded properly, the application should use the UTF8Encoding or UnicodeEncoding Unicode encodings with a preamble.

The following code example determines the byte order of the encoding based on the preamble.


using System;
using System.Text;

class Example
{
   public static void Demo(System.Windows.Controls.TextBlock outputBlock)
   {
      Encoding unicode = Encoding.Unicode;

      // Get the preamble for the Unicode encoder. 
      // In this case the preamble contains the byte order mark (BOM).
      byte[] preamble = unicode.GetPreamble();

      // Make sure a preamble was returned 
      // and is large enough to containa BOM.
      if (preamble.Length >= 2)
      {
         if (preamble[0] == 0xFE && preamble[1] == 0xFF)
         {
            outputBlock.Text += "The Unicode encoder is encoding in big-endian order." + "\n";
         }
         else if (preamble[0] == 0xFF && preamble[1] == 0xFE)
         {
            outputBlock.Text += "The Unicode encoder is encoding in little-endian order." + "\n";
         }
      }
   }
}


Windows Phone OS

Supported in: 8.1, 8.0, 7.1, 7.0

Windows Phone

Show:
© 2014 Microsoft