UnicodeEncoding.GetPreamble Method

Returns a Unicode byte order mark encoded in UTF-16 format, if the constructor for this instance requests a byte order mark.

Namespace:  System.Text
Assemblies:   System.Text.Encoding.Extensions (in System.Text.Encoding.Extensions.dll)
  mscorlib (in mscorlib.dll)

public override byte[] GetPreamble()

Return Value

Type: System.Byte[]
A byte array containing the Unicode byte order mark, if the UnicodeEncoding object is configured to supply one. Otherwise, this method returns a zero-length byte array.

The UnicodeEncoding object can provide a preamble, which is a byte array that can be prefixed to the sequence of bytes resulting from the encoding process. Prefacing a sequence of encoded bytes with a byte order mark (code point U+FEFF) 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):

  • Big endian byte order: 00 00 FE FF

  • Little endian byte order: FF FE 00 00

You can instantiate a UnicodeEncoding object whose GetPreamble method returns a valid BOM in the following ways:

We recommended that you use the BOM, since it provides nearly certain identification of an encoding for files that otherwise have lost a reference to their encoding, such as untagged or improperly tagged web data or random text files stored when a business did not have international concerns. Often user problems might be avoided if data is consistently and properly tagged.

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.

Caution noteCaution

To ensure that the encoded bytes are decoded properly, you should prefix the beginning of a stream of encoded bytes with a preamble.

The following example demonstrates how to use the GetPreamble method to retrieve the Unicode byte order mark in big endian or little endian byte order for an instance of a UnicodeEncoding.

using System;
using System.Text;

class UnicodeEncodingExample {
    public static void Main() {
        Byte[] byteOrderMark;

        byteOrderMark = Encoding.Unicode.GetPreamble();
        Console.WriteLine("Default (little-endian) Unicode Preamble:");
        foreach (Byte b in byteOrderMark) {
            Console.Write("[{0}]", b);
        }
        Console.WriteLine("\n");

        UnicodeEncoding bigEndianUnicode = new UnicodeEncoding(true, true);
        byteOrderMark = bigEndianUnicode.GetPreamble();
        Console.WriteLine("Big-endian Unicode Preamble:");
        foreach (Byte b in byteOrderMark) {
            Console.Write("[{0}]", b);
        }
    }
}

The following example instantiates two UnicodeEncoding objects, the first of which does not provide a BOM, and the second of which does. It then calls the GetPreamble method to write the BOM to a file before writing a Unicode-encoded string. As the console output from the example shows, the file that saves the bytes from the second encoder has three more bytes than the first.

You can also compare the files by using the fc command in a console window, or you can inspect the files in a text editor that includes a Hex View mode. Note that when the file is opened in an editor that supports UTF-16 encoding, the BOM is not displayed.

.NET Framework

Supported in: 4.6, 4.5, 4, 3.5, 3.0, 2.0, 1.1

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

XNA Framework

Supported in: 3.0, 2.0, 1.0

Portable Class Library

Supported in: Portable Class Library

Supported in: Windows Phone 8.1

Supported in: Windows Phone Silverlight 8.1

Supported in: Windows Phone Silverlight 8
Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2015 Microsoft