Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

UTF8Encoding.GetPreamble Method

Returns a Unicode byte order mark encoded in UTF-8 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.

Optionally, the UTF8Encoding 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 EF BB BF (in hexadecimal). The GetPreamble method returns an array of bytes containing the byte order mark.

For more information on Unicode encoding, 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 example demonstrates how to use the GetPreamble method to return the Unicode byte order mark encoded in UTF-8 format. Notice that the default constructor for UTF8Encoding does not provide a preamble.

using System;
using System.Text;

class UTF8EncodingExample {
    public static void Main() {
        // The default constructor does not provide a preamble.
        UTF8Encoding UTF8NoPreamble = new UTF8Encoding();
        UTF8Encoding UTF8WithPreamble = new UTF8Encoding(true);

        Byte[] preamble;

        preamble = UTF8NoPreamble.GetPreamble();
        Console.WriteLine("UTF8NoPreamble");
        Console.WriteLine(" preamble length: {0}", preamble.Length);
        Console.Write(" preamble: ");
        ShowArray(preamble);

        preamble = UTF8WithPreamble.GetPreamble();
        Console.WriteLine("UTF8WithPreamble");
        Console.WriteLine(" preamble length: {0}", preamble.Length);
        Console.Write(" preamble: ");
        ShowArray(preamble);
    }

    public static void ShowArray(Array theArray) {
        foreach (Object o in theArray) {
            Console.Write("[{0}]", o);
        }
        Console.WriteLine();
    }
}

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

class UTF8EncodingExample
{
    public static void main(String[] args)
    {
        // The default constructor does not provide a preamble.
        UTF8Encoding utf8NoPreamble = new UTF8Encoding();
        UTF8Encoding utf8WithPreamble = new UTF8Encoding(true);
        ubyte preamble[];

        preamble = utf8NoPreamble.GetPreamble();
        Console.WriteLine("UTF8NoPreamble");
        Console.WriteLine(" preamble length: {0}",
            String.valueOf(preamble.length));
        Console.Write(" preamble: ");
        ShowArray(preamble);
        preamble = utf8WithPreamble.GetPreamble();
        Console.WriteLine("UTF8WithPreamble");
        Console.WriteLine(" preamble length: {0}",
            String.valueOf(preamble.length));
        Console.Write(" preamble: ");
        ShowArray(preamble);
    } //main

    public static void ShowArray(Array theArray)
    {
        Object o = null;
        for (int iCtr = 0; iCtr < theArray.get_Count(); iCtr++) {
            o = theArray.get_Item(iCtr);
            Console.Write("[{0}]", o);
        }
        Console.WriteLine();
    } //ShowArray
} //UTF8EncodingExample

Windows 98, Windows 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 .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
Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.