This documentation is archived and is not being maintained.

UnicodeEncoding.GetPreamble Method

Returns a Unicode byte order mark encoded in UTF-32 format, if the constructor for this instance requested that a byte order mark be provided.

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

public override byte[] GetPreamble ()
public byte[] GetPreamble ()
public override function GetPreamble () : byte[]

Return Value

A byte array containing the Unicode byte order mark, if the constructor for this instance requested that a byte order mark be provided. Otherwise, a byte array of length zero.

If the preamble is prefixed to an encoded stream, it helps the decoder to identify the encoding format used.

The encoder can use the big-endian byte order (most significant byte first) or the little-endian byte order (least significant byte first). For example, the Latin Capital Letter A (code point U+0041) is serialized as follows (in hexadecimal):

  • Big-endian byte order: 00 00 00 41

  • Little-endian byte order: 41 00 00 00

Optionally, the UnicodeEncoding provides a preamble, which is an array of bytes that you can prefix to the sequence of bytes resulting from the encoding process. If the preamble contains a byte order mark (code point U+FEFF), it helps the decoder determine the byte order and the transformation format or UTF. The Unicode byte order mark is serialized as follows (in hexadecimal):

  • Big-endian byte order: 00 00 FE FF

  • Little-endian byte order: FF FE 00 00

It is generally more efficient to store Unicode characters using the native byte order. For example, it is better to use the little-endian byte order on little-endian platforms, such as Intel machines.

For more information on byte order and the byte order mark, see The Unicode Standard at www.unicode.org.

Caution noteCaution

To ensure that the encoded bytes are decoded properly, prefix encoded bytes with a preamble.

The following code example demonstrates how to use the GetPreamble method to return the Unicode byte order mark in big-endian or little-endian format 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);
        }
    }
}

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

class UnicodeEncodingExample
{
    public static void main(String[] args)
    {
        ubyte byteOrderMark[];
        byteOrderMark = Encoding.get_Unicode().GetPreamble();
        Console.WriteLine("Default (little-endian) Unicode Preamble:");
        for(int iCtr = 0; iCtr < byteOrderMark.length; iCtr++) {
            ubyte b = byteOrderMark[iCtr];
            Console.Write("[{0}]", String.valueOf(b));
        }
        Console.WriteLine("\n");
        UnicodeEncoding bigEndianUnicode = new UnicodeEncoding(true, true);
        byteOrderMark = bigEndianUnicode.GetPreamble();
        Console.WriteLine("Big-endian Unicode Preamble:");
        for(int iCtr = 0; iCtr < byteOrderMark.length; iCtr++) {
            ubyte b = byteOrderMark[iCtr];
            Console.Write("[{0}]", String.valueOf(b));
        }
    } //main
} //UnicodeEncodingExample

Windows 98, Windows 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile for Pocket PC, Windows Mobile for Smartphone, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see System Requirements.

.NET Framework

Supported in: 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 2.0, 1.0
Show: