Article
11/17/2011

UTF8Encoding.GetPreamble Method

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Returns a Unicode byte order mark encoded in UTF-8 format.

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

Syntax

'Declaration
Public Overrides Function GetPreamble As Byte()

public override byte[] GetPreamble()

Return Value

Type: array<System.Byte[]
A byte array containing the Unicode byte order mark, if the constructor for this instance requests a byte order mark. Otherwise, this method returns a zero-length byte array.

Remarks

Optionally, the UTF8Encoding object provides a preamble, which 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 (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 EF BB BF (in hexadecimal).

Your applications are recommended to use the BOM, as it provides nearly certain identification of an encoding for files that otherwise have lost reference to the UTF8Encoding 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.

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:
To ensure that the encoded bytes are decoded properly, your application should prefix encoded bytes with a preamble.

Examples

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.

Imports System.Text

Class Example

   Public Shared Sub Demo(ByVal outputBlock As System.Windows.Controls.TextBlock)
      ' 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()
      outputBlock.Text &= "UTF8NoPreamble" & vbCrLf
      outputBlock.Text += String.Format(" preamble length: {0}", preamble.Length) & vbCrLf
      outputBlock.Text &= " preamble: "
      ShowArray(outputBlock, preamble)

      preamble = UTF8WithPreamble.GetPreamble()
      outputBlock.Text &= "UTF8WithPreamble" & vbCrLf
      outputBlock.Text += String.Format(" preamble length: {0}", preamble.Length) & vbCrLf
      outputBlock.Text &= " preamble: "
      ShowArray(outputBlock, preamble)
   End Sub 'Main


   Public Shared Sub ShowArray(ByVal outputBlock As System.Windows.Controls.TextBlock, ByVal theArray As Array)
      Dim o As Object
      For Each o In theArray
         outputBlock.Text += String.Format("[{0}]", o)
      Next o
      outputBlock.Text &= vbCrLf
   End Sub 'ShowArray
End Class 'UTF8EncodingExample

using System;
using System.Text;

class Example
{
   public static void Demo(System.Windows.Controls.TextBlock outputBlock)
   {
      // The default constructor does not provide a preamble.
      UTF8Encoding UTF8NoPreamble = new UTF8Encoding();
      UTF8Encoding UTF8WithPreamble = new UTF8Encoding(true);

      Byte[] preamble;

      preamble = UTF8NoPreamble.GetPreamble();
      outputBlock.Text += "UTF8NoPreamble" + "\n";
      outputBlock.Text += String.Format(" preamble length: {0}", preamble.Length) + "\n";
      outputBlock.Text += " preamble: ";
      ShowArray(outputBlock, preamble);

      preamble = UTF8WithPreamble.GetPreamble();
      outputBlock.Text += "UTF8WithPreamble" + "\n";
      outputBlock.Text += String.Format(" preamble length: {0}", preamble.Length) + "\n";
      outputBlock.Text += " preamble: ";
      ShowArray(outputBlock, preamble);
   }

   public static void ShowArray(System.Windows.Controls.TextBlock outputBlock, Array theArray)
   {
      foreach (Object o in theArray)
      {
         outputBlock.Text += String.Format("[{0}]", o);
      }
      outputBlock.Text += "\n";
   }
}

Version Information

Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

XNA Framework

Supported in: Xbox 360, Windows Phone OS 7.0

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.