Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

Encoding.GetPreamble Method

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 ()
public byte[] GetPreamble ()
public function GetPreamble () : byte[]
Not applicable.

Return Value

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

  • UTF-32 big endian byte order: 00 00 FE FF

  • UTF-32 little endian byte order: FF FE 00 00

Your applications are recommended to use the BOM, because it provides nearly certain identification of an encoding for files that otherwise have lost reference to the Encoding object, for example, untagged or improperly tagged web data or random text files stored when a business did not have international concerns or other data. Often user problems might be avoided if data is consistently and properly tagged, preferably in UTF-8 or UTF-16.

For standards that provide an encoding type, a BOM is somewhat redundant. However, it can be used to help a server send the correct encoding header. Alternatively, it can be used as a fallback in case the encoding is otherwise lost.

There are some disadvantages to using a BOM. For example, knowing how to limit the database fields that use a BOM can be difficult. Concatenation of files can be a problem also, for example, when files are merged in such a way that an unnecessary character can end up in the middle of data. In spite of the few disadvantages, however, the use of a BOM is highly recommended.

For more information on byte order and the byte order mark, see The Unicode Standard at the Unicode home page.

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 a Unicode encoding, that is, UTF8Encoding, UnicodeEncoding, or UTF32Encoding, with a preamble.

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

using System;
using System.Text;

namespace GetPreambleExample
{
   class GetPreambleExampleClass
   {
      static void Main()
      {
         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)
            {
               Console.WriteLine("The Unicode encoder is encoding in big-endian order.");
            }
            else if(preamble[0] == 0xFF && preamble[1] == 0xFE)
            {
               Console.WriteLine("The Unicode encoder is encoding in little-endian order.");
            }
         }
      }
   }
}

package GetPreambleExample; 

import System.*;
import System.Text.*;

class GetPreambleExampleClass
{
    public static void main(String[] args)
    {
        Encoding unicode = Encoding.get_Unicode();

        // Get the preamble for the Unicode encoder. 
        // In this case the preamble contains the byte order mark (BOM).
        ubyte 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) {
                Console.WriteLine("The Unicode encoder is "
                + "encoding in big-endian order.");
            }
            else {
                if(preamble[0] == 0xFF && preamble[1] == 0xFE) {
                    Console.WriteLine("The Unicode encoder is" 
                    + " encoding in little-endian order.");
                }
            }
        }
    } //main
} //GetPreambleExampleClass 

Windows 98, Windows Server 2000 SP4, Windows Millennium Edition, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The Microsoft .NET Framework 3.0 is supported on Windows Vista, Microsoft Windows XP SP2, and Windows Server 2003 SP1.

.NET Framework

Supported in: 3.0, 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 2.0, 1.0

XNA Framework

Supported in: 1.0

Community Additions

Show:
© 2014 Microsoft