This documentation is archived and is not being maintained.

UTF8Encoding.GetPreamble Method

Returns a Unicode byte order mark encoded in UTF-8 format, if the constructor for this instance requested byte order mark support.

[Visual Basic]
Overrides Public Function GetPreamble() As Byte()
[C#]
public override byte[] GetPreamble();
[C++]
public: unsigned char GetPreamble()  __gc[];
[JScript]
public override function GetPreamble() : Byte[];

Return Value

A byte array containing the Unicode byte order mark (U+FEFF), encoded as hexadecimal 0xEF, 0xBB, 0xBF, if the constructor for this instance requested a UTF-8 identifier be emitted; otherwise, a byte array of length zero.

Remarks

The byte order mark, when concatenated before the beginning of an encoded sequence of bytes, enables classes like System.IO.StreamReader determine whether subsequent bytes are encoded in UTF-8 format.

Concatenate this return value to the beginning of a UTF-8 encoded sequence of bytes if the constructor for this instance requested support for a byte order mark.

Example

[Visual Basic, C#, C++] The following example demonstrates how to use the GetPreamble method to return the Unicode byte order mark encoded in UTF-8 format for an instance of a UTF8Encoding that requested byte order mark support when it was created. Notice that the default constructor for a UTF8Encoding does not provide a preamble.

[Visual Basic] 
Imports System
Imports System.Text

Class UTF8EncodingExample
    
    Public Shared Sub Main()
        ' The default constructor does not provide a preamble.
        Dim UTF8NoPreamble As New UTF8Encoding()
        Dim UTF8WithPreamble As New UTF8Encoding(True)
        
        Dim preamble() As Byte
        
        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)
    End Sub 'Main
    
    
    Public Shared Sub ShowArray(theArray As Array)
        Dim o As Object
        For Each o In  theArray
            Console.Write("[{0}]", o)
        Next o
        Console.WriteLine()
    End Sub 'ShowArray
End Class 'UTF8EncodingExample

[C#] 
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();
    }
}

[C++] 
#using <mscorlib.dll>
using namespace System;
using namespace System::Text;
using namespace System::Collections;

void ShowArray(Array * theArray)
{
   IEnumerator* myEnum = theArray->GetEnumerator();
   while (myEnum->MoveNext())
   {
      Object* o = __try_cast<Object*>(myEnum->Current);
      Console::Write(S"[{0}]", o);
   }
   Console::WriteLine();
}

int 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(S"UTF8NoPreamble");
   Console::WriteLine(S" preamble length: {0}", __box(preamble -> Length));
   Console::Write(S" preamble: ");
   ShowArray(preamble);

   preamble = UTF8WithPreamble -> GetPreamble();
   Console::WriteLine(S"UTF8WithPreamble");
   Console::WriteLine(S" preamble length: {0}", __box(preamble -> Length));
   Console::Write(S" preamble: ");
   ShowArray(preamble);
}

[JScript] No example is available for JScript. To view a Visual Basic, C#, or C++ example, click the Language Filter button Language Filter in the upper-left corner of the page.

Requirements

Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family, .NET Compact Framework, Common Language Infrastructure (CLI) Standard

See Also

UTF8Encoding Class | UTF8Encoding Members | System.Text Namespace

Show: