Artigo
11/18/2011

Encoding.GetPreamble Method

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

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

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

Syntax

'Declaration
Public Overridable Function GetPreamble As Byte()

public virtual byte[] GetPreamble()

Return Value

Type: array<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.

Remarks

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:
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.

Examples

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

using System;
using System.Text;

class Example
{
   public static void Demo(System.Windows.Controls.TextBlock outputBlock)
   {
      Encoding unicode = Encoding.Unicode;

      // Get the preamble for the Unicode encoder. 
      // In this case the preamble contains the byte order mark (BOM).
      byte[] preamble = unicode.GetPreamble();

      // Make sure a preamble was returned 
      // and is large enough to containa BOM.
      if (preamble.Length >= 2)
      {
         if (preamble[0] == 0xFE && preamble[1] == 0xFF)
         {
            outputBlock.Text += "The Unicode encoder is encoding in big-endian order." + "\n";
         }
         else if (preamble[0] == 0xFF && preamble[1] == 0xFE)
         {
            outputBlock.Text += "The Unicode encoder is encoding in little-endian order." + "\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.

Compartilhar via