UTF8Encoding.GetPreamble 方法

public:
 override cli::array <System::Byte> ^ GetPreamble();

public override byte[] GetPreamble();

override this.GetPreamble : unit -> byte[]

Public Overrides Function GetPreamble () As Byte()

返回

一个包含 Unicode 字节顺序标记的字节数组（如果 UTF8Encoding 编码对象配置为提供一个这样的字节数组）。 否则，此方法返回一个零长度的字节数组。

示例

以下示例使用 GetPreamble 方法返回以 UTF-8 格式编码的 Unicode 字节顺序标记。 请注意， 的 UTF8Encoding 无参数构造函数不提供前言。

using System;
using System.Text;

class Example
{
    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);
        Console.WriteLine();
        
        preamble = UTF8WithPreamble.GetPreamble();
        Console.WriteLine("UTF8WithPreamble");
        Console.WriteLine(" preamble length: {0}", preamble.Length);
        Console.Write(" preamble: ");
        ShowArray(preamble);
    }

    public static void ShowArray(Byte[] bytes)
    {
        foreach (var b in bytes)
            Console.Write("{0:X2} ", b);

        Console.WriteLine();
    }
}
// The example displays the following output:
//    UTF8NoPreamble
//     preamble length: 0
//     preamble:
//
//    UTF8WithPreamble
//     preamble length: 3
//     preamble: EF BB BF

Imports System.Text

Module Example
    Public 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)
        Console.WriteLine()
        
        preamble = UTF8WithPreamble.GetPreamble()
        Console.WriteLine("UTF8WithPreamble")
        Console.WriteLine(" preamble length: {0}", preamble.Length)
        Console.Write(" preamble: ")
        ShowArray(preamble)
    End Sub

    Public Sub ShowArray(bytes As Byte())
        For Each b In  bytes
            Console.Write("{0:X2} ", b)
        Next
        Console.WriteLine()
    End Sub
End Module
' The example displays the following output:
'    UTF8NoPreamble
'     preamble length: 0
'     preamble:
'
'    UTF8WithPreamble
'     preamble length: 3
'     preamble: EF BB BF

以下示例实例化两UTF8Encoding个 对象，第一个是通过调用不提供 BOM 的无UTF8Encoding()参数构造函数，第二个是通过调用其encoderShouldEmitUTF8Identifier参数设置为 的构造函数来true实例UTF8Encoding(Boolean)化。 然后， GetPreamble 它会调用 方法，在编写 UF8 编码的字符串之前将 BOM 写入文件。 如示例中的控制台输出所示，保存来自第二个编码器的字节的文件比第一个编码器多三个字节。

using System;
using System.IO;
using System.Text;

public class Example
{
   public static void Main()
   {
      String s = "This is a string to write to a file using UTF-8 encoding.";

      // Write a file using the default constructor without a BOM.
      var enc = new UTF8Encoding();
      Byte[] bytes = enc.GetBytes(s);
      WriteToFile("NoPreamble.txt", enc, bytes);

      // Use BOM.
      enc = new UTF8Encoding(true);
      WriteToFile("Preamble.txt", enc, bytes);
   }

   private static void WriteToFile(String fn, Encoding enc, Byte[] bytes)
   {
      var fs = new FileStream(fn, FileMode.Create);
      Byte[] preamble = enc.GetPreamble();
      fs.Write(preamble, 0, preamble.Length);
      Console.WriteLine("Preamble has {0} bytes", preamble.Length);
      fs.Write(bytes, 0, bytes.Length);
      Console.WriteLine("Wrote {0} bytes to {1}.", fs.Length, fn);
      fs.Close();
      Console.WriteLine();
   }
}
// The example displays the following output:
//       Preamble has 0 bytes
//       Wrote 57 bytes to NoPreamble.txt.
//
//       Preamble has 3 bytes
//       Wrote 60 bytes to Preamble.txt.

Imports System.IO
Imports System.Text

Module Example
   Public Sub Main()
      Dim s As String = "This is a string to write to a file using UTF-8 encoding."
      
      ' Write a file using the default constructor without a BOM.
      Dim enc As New UTF8Encoding()
      Dim bytes() As Byte = enc.GetBytes(s)
      WriteToFile("NoPreamble.txt", enc, bytes)

      ' Use BOM.
      enc = New UTF8Encoding(True)
      WriteToFile("Preamble.txt", enc, bytes)
   End Sub

   Private Sub WriteToFile(fn As String, enc As Encoding, bytes As Byte())
      Dim fs As New FileStream(fn, FileMode.Create)
      Dim preamble() As Byte = enc.GetPreamble()
      fs.Write(preamble, 0, preamble.Length)
      Console.WriteLine("Preamble has {0} bytes", preamble.Length)
      fs.Write(bytes, 0, bytes.Length)
      Console.WriteLine("Wrote {0} bytes to {1}.", fs.Length, fn)
      fs.Close()
      Console.WriteLine()
   End Sub
End Module
' The example displays the following output:
'       Preamble has 0 bytes
'       Wrote 57 bytes to NoPreamble.txt.
'
'       Preamble has 3 bytes
'       Wrote 60 bytes to Preamble.txt.

还可以在控制台窗口中使用 fc 命令比较文件，也可以在包含十六进制视图模式的文本编辑器中检查文件。 请注意，在支持 UTF-8 的编辑器中打开文件时，不会显示 BOM。

注解

对象 UTF8Encoding 可以提供一个前言，它是一个字节数组，可以作为编码过程产生的字节序列的前缀。 在编码字节序列前面加上字节顺序标记 (码位 U+FEFF) 有助于解码器确定字节顺序和转换格式（即 UTF）。 BOM) (Unicode 字节顺序标记序列化为0xEF 0xBB 0xBF。 请注意，Unicode 标准既不需要也不建议对 UTF-8 编码流使用 BOM。

可以实例化UTF8Encoding对象，其GetPreamble方法按以下方式返回有效的 BOM：

• 通过 UTF8Encoding 检索 属性返回的对象 Encoding.UTF8 。

• 使用 参数调用 UTF8Encoding 构造函数 encoderShouldEmitUTF8Identifier 并将其值设置为 true。

所有其他UTF8Encoding对象配置为返回空数组而不是有效的 BOM。

BOM 为丢失了对其编码的引用的文件（如未标记或未正确标记的 Web 数据或当企业没有国际问题时存储的随机文本文件）提供几乎确定的编码标识。 如果数据一致且正确标记，通常可以避免用户问题。

对于提供编码类型的标准，BOM 有些多余。 但是，可以使用它来帮助服务器发送正确的编码标头。 或者，它可以用作回退，以防编码在其他情况下丢失。

使用 BOM 存在一些缺点。 例如，了解如何限制使用 BOM 的数据库字段可能很困难。 文件的串联可能也是一个问题，例如，当文件以这样一种方式进行合并时，不需要的字符会在数据中间结束。 但尽管有几个缺点，但强烈建议使用 BOM。

有关字节顺序和字节顺序标记的详细信息，请参阅unicode 主页上的 unicode 标准。