Encoding.GetPreamble Method

When overridden in a derived class, returns a sequence of bytes that specifies the encoding used.

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

'Declaration
Public Overridable Function GetPreamble As Byte()

Return Value

Type: System.Byte()
A byte array containing a sequence of bytes that specifies the encoding used.
-or-
A byte array of length zero, if a preamble is not required.

Optionally, the Encoding object provides a preamble that 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 (in Unicode, 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 follows (in hexadecimal):

  • UTF-8: EF BB BF

  • UTF-16 big-endian byte order: FE FF

  • UTF-16 little-endian byte order: FF FE

Caution noteCaution:

To ensure that the encoded bytes are decoded properly, your application should prefix encoded bytes with a preamble. However, most encodings do not provide a preamble. To ensure that the encoded bytes are decoded properly, the application should use the UTF8Encoding or UnicodeEncoding Unicode encodings with a preamble.

The following code example determines the byte order of the encoding based on the preamble.


Imports System.Text

Class Example
   Public Shared Sub Demo(ByVal outputBlock As System.Windows.Controls.TextBlock)
      Dim [unicode] As Encoding = Encoding.Unicode

      ' Get the preamble for the Unicode encoder. 
      ' In this case the preamble contains the byte order mark (BOM).
      Dim preamble As Byte() = [unicode].GetPreamble()

      ' Make sure a preamble was returned 
      ' and is large enough to contain a BOM.
      If preamble.Length >= 2 Then
         If preamble(0) = &HFE And preamble(1) = &HFF Then
            outputBlock.Text &= "The Unicode encoder is encoding in big-endian order." & vbCrLf
         Else
            If preamble(0) = &HFF And preamble(1) = &HFE Then
               outputBlock.Text &= "The Unicode encoder is encoding in little-endian order." & vbCrLf
            End If
         End If
      End If
   End Sub
End Class


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

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

Community Additions

ADD
Show: